refactor(core)!: a runtime resolves ports, it does not need them

[btravers]

Two different needs in one framework was one too many.

di's Module has a needs — what a composition root supplies it — and the
kernel's Runtime had one too, meaning something else entirely: the ports the
runtime reads back out of the built application context. They never appear in
the same object, which is exactly what made the collision easy to misread
rather than harmless.

const runtime: Runtime<typeof Clock> = {
  name: "ticker",
  resolves: [Clock],
  start: (host) => OkAsync(serving),
};

The type parameter follows the field — Runtime<Resolves, Info>,
RuntimeHost<Resolves>, RunUnit<Resolves>, RuntimeResolvesOf — and so does
start's gate sentence:

"UNSATISFIED RUNTIME PORTS — the runtime resolves a port the module does not export"

Blast radius

Small, because every shipped runtime declares resolves: []. An
application that composes http() / temporal() / amqp() and never writes a
runtime by hand is unaffected; a hand-rolled one renames a field.

RuntimeResolvesOf was never exported from packages/core/src/index.ts, so
the public surface change is the Runtime field and the gate sentence, nothing
else.

While renaming

The field's own comment now says the thing that was true and unwritten: the
array is never read at run time. It exists so Resolves is inferable from
the value, and start's gate checks it against the module's exports.

Gate

All six green from the root: format --check, lint, typecheck (31/31),
knip, test (30/30), build (10/10). Changeset included — minor, all nine.

[Copilot]

Pull request overview

Refactors @btravstack/core’s Runtime contract to rename needs → resolves, clarifying that a runtime reads ports from the built application context (distinct from di Module.needs) and aligning the type parameter names and gate messaging accordingly.

Changes:

• Rename Runtime<Needs, Info> → Runtime<Resolves, Info> (and RuntimeHost, RunUnit, and helper types) and update start’s gate sentence to UNSATISFIED RUNTIME PORTS.
• Update shipped starters and test utilities to declare resolves: [] (and update type tests/specs accordingly).
• Update documentation (package CLAUDE.md, READMEs, and docs site pages) plus add a changeset for the minor bump.

Reviewed changes

Copilot reviewed 36 out of 36 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/testing/src/test-runtime.ts	Update test runtime object to resolves: [].
packages/temporal/src/temporal-runtime.ts	Update Temporal runtime object to resolves: [].
packages/temporal/CLAUDE.md	Docs wording update to match resolves/gate rename.
packages/observability/src/test-fixtures.ts	Update hand-rolled runtime example to resolves: [Logger].
packages/http/src/http-runtime.ts	Update HTTP runtime object to resolves: [].
packages/http/CLAUDE.md	Docs wording update to match resolves/gate rename.
packages/core/src/start.ts	Rename gate/type plumbing from RuntimeNeedsOf → RuntimeResolvesOf and update gate sentence.
packages/core/src/start.test-d.ts	Update type-level gate tests to use resolves and new sentence.
packages/core/src/start.spec.ts	Update spec runtime object to resolves: [].
packages/core/src/runtime.ts	Rename Runtime field/type parameter and helper type to resolves/RuntimeResolvesOf.
packages/core/src/docs-examples.test-d.ts	Update compiled doc examples to resolves.
packages/core/README.md	Update README example runtime to resolves.
packages/core/CLAUDE.md	Update core package docs to use resolves terminology.
packages/amqp/src/amqp-runtime.ts	Update AMQP runtime object to resolves: [].
packages/amqp/CLAUDE.md	Docs wording update to match resolves/gate rename.
docs/typedoc.core.json	Update intentionallyNotExported for renamed helper type.
docs/reference/testing.md	Update testing reference docs to resolves.
docs/reference/http.md	Update HTTP reference wording to “resolves nothing”.
docs/reference/glossary.md	Update glossary entries for gate/runtime shape.
docs/reference/di/entry-points.md	Update entry-points doc to renamed gate arm.
docs/reference/core/start.md	Update StartGate docs and arm table to RuntimeResolvesOf/UNSATISFIED RUNTIME PORTS.
docs/reference/core/runtime.md	Update runtime reference page to resolves.
docs/reference/core/exit-codes.md	Update exit-codes page to renamed gate arm.
docs/reference/amqp.md	Update AMQP reference wording to “resolves nothing”.
docs/index.md	Update landing-page feature text to match rename.
docs/how-to/write-a-runtime.md	Update how-to guide’s runtime definitions/examples to resolves.
docs/how-to/open-a-per-request-scope.md	Update per-request scope page to renamed gate arm/field.
docs/explanation/why-start.md	Update explanation wording (“ports … not exported”).
docs/explanation/the-kernel-maps-nothing.md	Update explanation link text to resolves.
docs/explanation/starters.md	Update starters explanation to resolves terminology.
docs/explanation/one-process-one-runtime.md	Update explanation link text to match rename.
docs/explanation/design-decisions.md	Update gate wording to renamed arm.
docs/explanation/compile-time-wiring.md	Update compile-time wiring explanation tables/rows to UNSATISFIED RUNTIME PORTS.
docs/examples/order-api.md	Update example doc wording to renamed arm/field.
CLAUDE.md	Update repo-wide guidance text to resolves terminology.
.changeset/runtime-resolves.md	Add minor changeset documenting the rename and gate sentence update.

Suppressed comments (2)

packages/core/src/start.test-d.ts:64

• @ts-expect-error directive still references the old gate arm and field name (UNSATISFIED RUNTIME NEEDS / "needs"). After the rename, this comment should match the new diagnostic wording (UNSATISFIED RUNTIME PORTS / "resolves") so future readers don't chase the wrong concept.

expectTypeOf<
  StartGate<Greeting | NeedsClock>
>().toEqualTypeOf<"UNSATISFIED RUNTIME PORTS — the runtime resolves a port the module does not export">();

packages/core/src/start.test-d.ts:64

• These nearby comments still say "needs-free runtime" / "runtime's needs" even though the type parameter and field were renamed to Resolves/resolves. Updating the wording will keep the type-test file consistent with the new API and gate terminology.

expectTypeOf<
  StartGate<Greeting | NeedsClock>
>().toEqualTypeOf<"UNSATISFIED RUNTIME PORTS — the runtime resolves a port the module does not export">();

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.