The Cordis API catalog

The Cordis API catalog is the generated reference of the services, events and types that a build exposes, together with the inherited API that comes with the runtime itself. This page shows what it contains, which entries it keeps, how its regions are generated, and how it is served and checked.

The build pipeline that produces package artifacts is on Plugin artifacts and the catalog, and the calls that cross between a plugin's halves are on Remote methods and streams.

What the catalog contains

• Services. Each service is listed under its context key with its type and a summary, and its full contract adds the public methods and how a plugin should depend on the service: an optional lookup that checks for absence, or a declared hard dependency.
• Events. Each event is listed with its dispatch mode and its listener contract: the parameters a listener receives and how the event is dispatched.
• Types. The types that signatures reference are listed with a link to the documentation page that owns each one, so a signature renders with its cross-links.
• The inherited context API. Beside what packages declare, the catalog carries the inherited part of the API: the services, events and context that come with the runtime itself, kept apart from package contributions on their own page.

Generate the catalog and its regions

• From the sources. The catalog is a build-time result, projected from the project's sources. Nothing generates it while Oda runs.
• One command. pnpm run gen-cordis-api rewrites the generated file and every generated region from the sources. Run it after you change a service or an event, and commit the result.
• Marked regions. In a documentation page, the generated text sits between a BEGIN GENERATED and an END GENERATED comment marker of the cordis-surface region; in the generated file, a banner marks the content as generated.
• Headings. A generated region carries the heading ## Cordis API, and the inherited API has a page of its own, titled # Inherited Cordis API.

Which entries the catalog keeps

• A class wins over an interface. When a class and an interface both declare the same service key, the catalog keeps the class and skips the interface.
• Deprecated entries are skipped. A service or event marked deprecated stays out of the catalog, so the catalog describes the current surface.
• Optional keys are not services. A context key declared as optional, or as possibly undefined, stays out; only required context keys become services.
• Long declarations are truncated. A runtime declaration in the generated output is cut after 1,500 characters, and the cut text says the full shape is in the source.

The checks that fail closed

• JSDoc completeness. An event needs its dispatch mode, every parameter needs a name, and a method that returns a value needs its return documented. A missing tag fails the check, and the finding names its source file and line: is missing an @mode tag. Add '@mode emit|bail|waterfall|parallel|serial' to its JSDoc, is missing @param ., or is missing @returns (return type: ). The check fails with the total count of findings.
• Type links. A signature may reference only types the catalog can link: a type with a documentation page that owns it, a built-in, or an explicit exemption. A reference with no home fails the check and names the type.
• Freshness. pnpm run verify-cordis-api compares each committed generated result with its sources. When one no longer matches, the check fails and says to regenerate and commit.

How the catalog is served

• The inspection tools answer from this catalog, so their answers describe what the build actually exposes. A directory answer lists each service and event with a summary and its signature; an exact answer adds the full contract. See Inspect and manage extensions.
• The served catalog and the rendered regions come from the same pass over the sources, so the two cannot drift apart.

Questions, answered

What is in the Cordis API catalog?

Services, events and the types behind their signatures, plus the inherited context API that comes with the runtime itself. A service is listed with its methods and how to depend on it, and an event with its dispatch mode and listener contract.

Why does the catalog show a class when an interface declares the same key?

When a class and an interface both declare the same service key, the catalog keeps the class and skips the interface.

Why is a deprecated service missing from the catalog?

The catalog skips entries marked deprecated, so it describes the current surface only.

Why is my optional context key not a service?

Only required context keys become services. A key declared as optional, or as possibly undefined, stays out of the catalog.

Why is part of a declaration cut off in the catalog?

Declarations in the generated output are truncated after 1,500 characters. The cut text says the full shape is in the source.

Where does the generated catalog appear?

In the generated file, and in documentation pages: a generated region is titled ## Cordis API, and the inherited API has a page of its own, titled # Inherited Cordis API.

What is the Inherited Cordis API page?

It holds the part of the API that comes with the runtime itself, apart from what packages contribute.

How can I read the catalog while I build an extension?

Use the inspection tools: their answers come from the built catalog, so they describe what the build actually exposes. Inspect and manage extensions covers the calls.

I changed a service. What do I run?

Run pnpm run gen-cordis-api to regenerate the file and the regions, then commit the result. The freshness check pnpm run verify-cordis-api fails on anything that was not regenerated and committed.