feat(core): add StartOptions.unit, the per-unit scope no handler manages

[btravers]

examples/order-api carried the per-request plumbing by hand: apiHandler opened
a Module.forkScope around every request and threaded RequestModule through.
That was the repo's own deferred item — "Per-unit ports: the unit module wired
into run's fork; the Module.forkScope call lands when the first runtime needs
a per-request transaction" — and order-api was that first consumer. This closes
the deferral at the kernel, where start.ts's annotation said the fork would land.

// the handler, before                              // after
Module.forkScope(ctx, RequestModule, (scope) =>     fromSafePromise(
  fromSafePromise(handler.handle(req, res, {          handler.handle(req, res, {
    prefix, context: { scope },                         prefix, context: { scope: ctx },
  })),                                                }),
);                                                  );

// the composition root
runMain(OrderApiModule, { runtime, unit: RequestModule, probes });

The design

• StartOptions.unit — a module the kernel forks around every unit: built as
  the unit opens (reading anything the application context carries), torn down as
  it closes. Unit work receives the forked Context; without the option, the
  application context exactly as before.
• The fork sits INSIDE registry.run, and both halves of that placement are
  load-bearing (unit-module.spec.ts guards them): teardown runs while the
  unit's ambient record is still open — a span's onStop logs under the
  request's own trace id — and the unit is not counted closed until the scope is,
  so a drain waits for unit teardown too.
• The gate covers both directions. RuntimeNeedsGate grows two defaulted
  parameters: runtime needs may draw on the unit module's exports (unit work is
  what receives them), and the unit module's own needs must be met by the
  application module's exports or Scope. Runtime needs check first — branch
  order matters, since inference through the documented escape hatch resolves
  against the first branch's error literal. start.test-d.ts pins both branches
  plus the clean runtime-need-from-unit-export call; order-api's
  needs-gate.test-d.ts pins the same against a real module.
• Unit E is pinned to never. A construction failure at unit scope has no
  modeled channel to land in, so it rides the unit's defect path — which every
  runtime already answers (an HTTP 500, a dead-letter).
• One caveat, documented: RuntimeHost.ctx remains the application context.
  A unit-provided port exists only while a unit is open; resolving one at runtime
  startup is a defect.
• No runtime package changes. The kernel controls the ctx handed to unit
  work, so http, temporal and amqp all get this at once — RunUnit was typed for
  it from the start.

Also in here

The kernel gains its first src/test-fixtures.ts (new specs follow all five test
conventions; excluded from coverage the way the examples' fixtures are), and the
"Per-unit ports" entry leaves Deferred, deliberately. Root CLAUDE.md,
packages/core/CLAUDE.md, both core READMEs and docs-examples.test-d.ts move
in the same commit; changeset included.

Gate

format ✓ lint ✓ typecheck ✓ (22 tasks) knip ✓ build ✓ test 21/22 —
core is 102/103 with the known local port-9000 clash; unit-module.spec.ts 2/2,
order-api 18/18 (its two per-request span-teardown log assertions now pass
through the kernel's fork).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR extends @btravstack/core’s kernel startup API to support a per-unit DI scope (StartOptions.unit) that is forked and torn down by the kernel for every unit of work, removing the need for handlers/runtimes to manage Module.forkScope themselves (e.g., HTTP request scope).

Changes:

• Added StartOptions.unit and extended the runtime needs gate to account for unit exports and unit-module needs.
• Updated kernel internals so the fork happens inside registry.run, ensuring teardown occurs while the unit’s ambient record is still open and that drains wait for teardown.
• Updated docs/examples/type-tests and introduced a core test fixture + spec to pin the new behavior.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
README.md	Updates high-level docs to describe per-unit ports via StartOptions.unit.
CLAUDE.md	Documents the new StartOptions.unit surface and updates core narrative.
packages/core/vitest.config.ts	Excludes src/test-fixtures.ts from coverage collection.
packages/core/src/with-app.ts	Extends withApp generics/signature to support unit and the expanded gate.
packages/core/src/unit-module.spec.ts	Adds spec coverage for per-unit forking and teardown timing relative to ambient unit record.
packages/core/src/test-fixtures.ts	Introduces core Vitest fixtures used by new specs to exercise unit-module behavior.
packages/core/src/start.ts	Implements StartOptions.unit, expands RuntimeNeedsGate, and forks scope per unit inside registry.run.
packages/core/src/start.test-d.ts	Adds type-level pins for the new two-direction gate behavior.
packages/core/src/run-main.ts	Extends runMain signature/gate to pass through unit generics/options.
packages/core/src/docs-examples.test-d.ts	Adds compiled docs example for StartOptions.unit usage.
packages/core/README.md	Documents the per-unit scope feature in the package README.
packages/core/CLAUDE.md	Updates internal core invariants/design notes to reflect the unit-module fork placement.
examples/order-api/src/test-fixtures.ts	Passes RequestModule via unit instead of managing per-request scope in handler.
examples/order-api/src/request-scope.ts	Updates request-scope documentation to reflect kernel-managed unit scoping.
examples/order-api/src/needs-gate.test-d.ts	Adds pins for unit-module gate behavior in a real example module.
examples/order-api/src/main.ts	Supplies unit: RequestModule to runMain for per-request scope.
examples/order-api/src/handler.ts	Removes Module.forkScope from handler and routes using the already-forked context.
.changeset/unit-module.md	Adds a changeset documenting the new minor feature.

---

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

[Copilot]

Pull request overview

Copilot reviewed 25 out of 26 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

Suppressed comments (1)

packages/core/src/test-fixtures.ts:79

• Fixture teardown awaits app.exited but discards the Result. If shutdown fails (Err/Defect), the fixture will still complete and the test can pass while the application exited uncleanly. Capture and assert/throw on the exit Result so teardown failures fail the test.

    app.stop();
    await app.exited;