export withOrchestration

[turadg]

refs: #9757
refs: #9765

Description

I noticed that withOrchestration isn't exported from the package. This exports it. It also exports the OrchestrationTools that the docs for that type require. I tried to not export provideOrchestration because it's more of an implementation detail, but JSDoc type expressions make it hard to export OrchestrationTools without also exporting provideOrchestration. I also considered getting rid of it but tests need to be able to set up OrchestrationTools without spinning up a contract. So I marked provideOrchestration as @internal so it doesn't show up in docs.

This also proposes a solution to,

• ReturnType<...> idiom obscures reference docs for public APIs #9765
  using the @interface tag to get the dynamic aspects to expand.

Before

CosmosInterchainService: ReturnType<[MakeCosmosInterchainService

After

interface CosmosInterchainService {
    [PASS_STYLE]: "remotable";
    [toStringTag]: string;
    __getInterfaceGuard__?: (() => undefined | InterfaceGuard<{
        makeAccount: any;
        provideICQConnection: any;
    }>);
    makeAccount(chainId, hostConnectionId, controllerConnectionId): Vow<IcaAccount>;
    provideICQConnection(controllerConnectionId): Guarded<{
        getLocalAddress(): `/ibc-port/${string}`;
        getRemoteAddress(): `/${string}ibc-port/${string}/ordered/${string}` | `/${string}ibc-port/${string}/unordered/${string}`;
        query(msgs): Promise<JsonSafe<ResponseQuery>[]>;
    }> | Vow<Guarded<{
        getLocalAddress(): `/ibc-port/${string}`;
        getRemoteAddress(): `/${string}ibc-port/${string}/ordered/${string}` | `/${string}ibc-port/${string}/unordered/${string}`;
        query(msgs): Promise<JsonSafe<ResponseQuery>[]>;
    }>>;
}

If that is agreeable I can convert the others in this PR or follow up.

Security Considerations

Scaling Considerations

Documentation Considerations

Testing Considerations

• provideOrchestration not in Markdown docs build for docs site
• withOrchestration signature is clear and concise

Upgrade Considerations

[dckc]

I'd like to review this by looking at a cloudflare preview. Any idea why it's not here?

It was there on at least one recent PR: #9798 (comment)

[0xpatrickdev]

I'd like to review this by looking at a cloudflare preview. Any idea why it's not here?

It was there on at least one recent PR: #9798 (comment)

Good idea. Clicking into Cloudflare Pages job I see:

Preview URL:	https://d7d9f03e.agoric-sdk.pages.dev
Branch Preview URL:	https://ta-export-withorchestration.agoric-sdk.pages.dev

[0xpatrickdev]

/** @interface */

Nice finding!

Tangential to these changes, but interfaces/_agoric_orchestration.Orchestrator is virtually unreadable with the KnownChains generic

[dckc]

... Orchestrator is virtually unreadable with the KnownChains generic

I noted that as a task in...

• Incomplete jsdocs for Orchestration API types, variables, methods and parameters #9757

[dckc]

bleah. the preview suffers from...

• typedoc function pages are not loading on agoric-sdk.pages.dev #9729

[dckc]

this all looks like forward progress
in particular, https://ta-export-withorchestration.agoric-sdk.pages.dev/interfaces/_agoric_orchestration.CosmosInterchainService looks better.

some parts might not be working as well as expected, though

[dckc]

this getPower thing still isn't gone? darn.

[dckc]

doesn't seem to have the desired effect. I still see it:

https://ta-export-withorchestration.agoric-sdk.pages.dev/modules/_agoric_orchestration

[turadg]

Good catch. It needs the excludeInternal option, but even with that it's appearing.

I'll wait for #9727 and try again. I don't want to create merge conflicts for that one and maybe it fixes the bug.

[turadg]

I tried merging and that didn't fix it. Now I suspect a bug in typedoc

[dckc]

yeah, I've tried without luck to get @internal to do anything

[turadg]

Delivered better in #10050