Stateful handler verification matrix and gaps in fixtures suggest; composition-fit discovery fixes (#1136, #1137)

[jimhoyd]

Problem and change

#1136: make stateful custom-handler verification gaps actionable

• What fixtures can express today. No fixture syntax was added, and schemas/requests.schema.json is unchanged.

  Invariant	Expressible as a fixture?
  Capacity exhaustion	Yes
  Persistence across restart	Yes
  Parent/derived credential revocation	Yes
  Concurrent mutation / idempotency	Partly: sequential replay only
  Permission change while an operation waits	No
  Delayed cleanup failure	No
  Owned-process termination	No

• Reference scenarios. examples/stateful-verification/ is a synthetic "channel" handler:

  • 39 fixture cases; it audits ready.
  • tests/in-flight.test.mjs is a plain node:test for the scenarios fixtures can't express.
  • Six switchable defects; test/stateful-verification.test.ts asserts exactly which checks each one fails.
  • Four of the six fail no fixture at all.

• Guidance. docs/READINESS.md has a new "Stateful handler verification" section: the matrix, "untested is not passed", and the boundary between fixtures and ordinary tests. AI-AUTHORING and TOOLING point to it.

• Tooling. urlcode fixtures suggest, MCP suggest_fixtures and the SDK add verificationGaps when a route qualifies:

  • A route qualifies from YAML alone: it has function or middleware, no extension, and a write method or stream: true.
  • status is always untested. It never claims coverage, reads no handler source and runs no project code; a test asserts this.
  • The key is absent otherwise, so existing output is unchanged.

#1137: composition discovery against a real application

The assessment result is on the issue. These changes are each tied to an observed discovery miss:

• plan-feature. The mcp authoring surfaces gain planner goal words, so plan-feature now names mcp for a remote-MCP goal; before, it returned nothing. The durable-collection note states the store's scope.
• auth and mcp docs. The surfaces and READMEs now state where each contract stops:
  • the session cookie is the only credential;
  • there is an owner-database option;
  • a schema-adding plugin can't use the bundled database file (with a clearer refusal message);
  • a protected mcp mount refuses headless callers;
  • handlers get no caller identity.
• docs search. It now matches catalog add-ons on their authoring contract, so oauth, bearer token and postgres name the add-on.
• TOOLING. It now states that review reads only a route's entry module.
• Executable composition. test/account-composition.test.ts has four tests with negative authorization cases, plus one test each in feature-plan and review.

Gaps reproduced and filed, not fixed here: #1139, #1140, #1141.

Verification

• npm run verify exits 0 on this exact tree.

  • Core: 1439 pass.
  • Workspaces: auth 33, mcp 47, store 239.
  • Add-ons and proofs: addons 9, proof 12, authjs 13, native 7, ecosystem 13.
  • 0 failures anywhere.

• npm run test:package exits 0: "46 packaged example commands ran from consumer copies; Packed installation and starter/cookbook checks passed".

• Core package budget, from the merged measurement:

  	Old budget	New budget	Measured
  Packed	1098 KiB	1111 KiB	1133642 bytes
  Unpacked	4300 KiB	4348 KiB	4444006 bytes
  Entries	570	576	571

Limitations

• [Request]: Make stateful custom-handler verification gaps actionable in existing authoring tools #1136:
  • The example's ordinary test relies on a 200 ms pause and on process signals. It has run on macOS only, so this PR's CI is its first run on Linux and Windows.
  • Real-app evidence was gathered privately, as in-process ordinary tests, not HTTP fixtures. Byte exhaustion and the Postgres and S3 paths were not exercised.
  • Usefulness is not measured.
• [Request]: Evaluate current composition discovery against peer-bin application plumbing #1137:
  • No application simplification is proposed.
  • Unverified: Postgres as the auth database, captcha and rate-limit parity, and password-hash migration.
• Review: no independent security review.

Closes #1136
Closes #1137

🤖 Generated with Claude Code