docs(di): a need is an obligation, not a lookup

[btravers]

Closes #50.

The decision

Keep the model. The issue's framing — "needs bubble up until some ancestor
discharges it" — is what made it look like a hole, and the measurement says the
opposite.

A module's Needs is
Exclude<its providers' deps | its imports' unmet needs, Available>, and
Available is what the module provides plus what its imports export —
nothing else. So the satisfaction rule is already NestJS's. Measured: a sibling
that imports observability() and re-exports nothing does not discharge a
slice's Logger.

error TS2345: Argument of type 'Module<AmqpRuntime, ConfigInvalid, Env | Logger>'
  is not assignable to parameter of type 'Module<AmqpRuntime, ConfigInvalid, Env | Scope>'.

The one real divergence is what happens to a need nothing local satisfies:
NestJS makes it an error where it is written, di makes it a typed obligation
carried in the third channel until an ancestor discharges it, gated at
Module.build / Module.scoped / start. AuditSlice declaring [Logger]
and importing nothing is that channel working — nothing can run it until a root
supplies one, which needs-gate.test-d.ts's LoggerlessAmqp already pins.

The two open questions the issue attached

• @Global: not needed, and that follows from the above. NestJS needs one
  because the error is local, so a cross-cutting provider must be visible
  everywhere. Here the obligation travels to the composition root, which is the
  one place observability() is imported anyway.
• Reconsider overrideProvider for testing — it costs four hand-maintained parallel roots today #63 is unblocked, not forced. Substitution stays recomposition, so
  tappedAmqp's seam stays open. Import-visibility was the arm that needed
  overrideProvider to remain testable — the issue measured both halves of why
  ([di] two providers registered for port "LoggerConfig", then the closed
  recording seam).

What is in the diff

• module.test-d.ts — "only an import's own exports discharge a need", both
  arms: the opaque holder that leaves the need standing, and
  exports: [ConfigModule], the one difference that discharges it. The property
  the decision rests on had nothing pinning it.
• packages/di/CLAUDE.md — the decision, for a contributor, with the
  recomposability argument the issue asked for.
• docs/explanation/modules-and-privacy.md — the reader's version of the same
  question, which is "where is @Global". The page already described the
  mechanism correctly; what it did not have was the NestJS comparison.

No behaviour change, no changeset: *.test-d.ts is excluded from the build.

Gate

All six green from the root: format --check, lint, typecheck (31/31),
knip, test (30/30), build.

[Copilot]

Pull request overview

This PR documents and pins the decision from #50 that di treats unmet needs as typed obligations carried to the composition root (rather than local module errors), while still keeping visibility constrained to a module’s own provides plus its imports’ exports.

Changes:

• Adds a new .test-d.ts case asserting that only an import’s exports discharge downstream needs (opaque vs passthrough holder).
• Updates packages/di/CLAUDE.md with the clarified visibility model and the rationale (incl. NestJS comparison and why @Global isn’t needed).
• Updates the docs explanation page to reflect the same decision in reader-facing terms.

Reviewed changes

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

File	Description
packages/di/src/module.test-d.ts	Adds a type-level regression test pinning the “imports’ exports only” need-discharge rule.
packages/di/CLAUDE.md	Records the #50 decision and clarifies the model as “obligation, not lookup,” with consequences and rationale.
docs/explanation/modules-and-privacy.md	Adds a NestJS comparison section explaining why unmet needs travel to the root and why there’s no @Global.

Suppressed comments (1)

docs/explanation/modules-and-privacy.md:68

• Same grammatical issue here: "a need nothing local satisfies" reads as missing "that".

`di` has the first half and not the second. What a module can see is still its
own provides plus its imports' exports — a sibling that imports
`observability()` and re-exports nothing does **not** satisfy your `Logger` — but
a need nothing local satisfies is not an error. It stays in the module's `Needs`
channel and travels to whoever composes the module, and the

---

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

[btravers]

Correction — the central claim in this PR is wrong, and the issue is right.

I measured the sibling case (a module that imports observability() and
re-exports nothing does not discharge another module's Logger) and generalised
it to "di already has NestJS's visibility rule". It does not. The ancestor
case is the one #50 is about, and it behaves exactly as the issue says.

Type level — the root's own provides discharges an imported slice's need,
with the slice importing nothing:

const Slice = Module("Slice")({ provides: [RepositoryProvider], exports: [OrderRepository] });
const Root = Module("Root")({ imports: [Slice], provides: [DatabaseProvider], exports: [OrderRepository] });
const rootNeedsNothing: Equal<Channels<typeof Root>[2], never> = true;  // compiles

Runtime — the slice's provider receives the root's instance:

✓ a slice's provider receives the ROOT's service, importing nothing

So a slice genuinely does see providers from the root. Draft until #50 is
re-decided; the module.test-d.ts pin is still correct and still worth keeping
whichever way it goes, since the sibling rule is real.

[btravers]

Superseded by the corrected decision — see the PR that replaces it. The premise in this PR is wrong: the ancestor case is what #50 is about, and a root does supply an imported module's need without that module mentioning it.