Introduced by #73 and found while sweeping the docs for #74.
The problem
examples/order-api gained authentication in #73: contract.orders is
authenticated(...), the slices import HttpController from the application's
own src/auth.ts rather than from @btravstack/http, there is a new
src/authenticator.ts, and the orders controller serves
context.principal.tenantId instead of input.tenantId.
Six documentation pages still describe the deployment as it was before that:
| Page |
shows |
docs/examples/order-api.md |
the whole example, as a four-file slice layout with no auth.ts, no authenticator, and .execute(input.id, input.quantity) |
docs/how-to/split-a-router-into-controllers.md |
both controller samples on the pre-auth call, contracts with no marker |
docs/how-to/serve-orpc-over-http.md |
the same |
docs/index.md |
the home page's controller sample |
docs/reference/http.md |
a controller sample on the pre-auth call, though the page does document the authenticator elsewhere |
docs/explanation/the-kernel-maps-nothing.md |
a controller sample on the pre-auth call |
docs/how-to/protect-a-procedure.md, docs/how-to/test-an-application.md and
docs/reference/contract.md are correct — they were written or fixed as part of
#73.
Why it is not a sweep
docs/examples/order-api.md is the sharp case. It documents the example
file by file, so it is not a stale line but a missing file: the page has no
src/auth.ts, never names httpAuth<Identity>(), and its slice table lists
four paths where the example now has five. Its controller samples cannot simply
gain context.principal either — the surrounding prose explains the tenant as
an input field, which is the design #73 deliberately moved.
The other five are smaller, but each needs the contract sample, the controller
sample and the prose between them to move together, or the page contradicts
itself mid-scroll.
Not fixed in #74
That PR is about input validation, and it already touches these files. Mixing
in an identity rewrite would make its diff about two unrelated things, and the
order-api.md half is a section rewrite rather than an edit. #74 changed the
schemas on these pages and deliberately left the markers and controller calls
alone.
Acceptance
- The six pages describe the example as it ships: the marker on
contract.orders,
HttpController imported from the application's src/auth.ts, the
authenticator wired at the root, and the tenant read off the principal.
docs/examples/order-api.md's file listing includes src/auth.ts and
src/authenticator.ts.
- Every changed sample is compiled in a scratch file inside the workspace whose
dependencies it needs, per the repo's rule, and deleted afterwards.
- A grep for
execute(input. across docs/ returns nothing outside docs/api/.
Worth fixing while there
Nothing gates these samples. packages/core has docs-examples.test-d.ts for
exactly this reason and the four starters do not — already recorded under
"Deferred, deliberately" in the root CLAUDE.md, whose own trigger is "add it
the next time one of those samples is found to have drifted". This is the second
such finding in two days.
Introduced by #73 and found while sweeping the docs for #74.
The problem
examples/order-apigained authentication in #73:contract.ordersisauthenticated(...), the slices importHttpControllerfrom the application'sown
src/auth.tsrather than from@btravstack/http, there is a newsrc/authenticator.ts, and the orders controller servescontext.principal.tenantIdinstead ofinput.tenantId.Six documentation pages still describe the deployment as it was before that:
docs/examples/order-api.mdauth.ts, no authenticator, and.execute(input.id, input.quantity)docs/how-to/split-a-router-into-controllers.mddocs/how-to/serve-orpc-over-http.mddocs/index.mddocs/reference/http.mddocs/explanation/the-kernel-maps-nothing.mddocs/how-to/protect-a-procedure.md,docs/how-to/test-an-application.mdanddocs/reference/contract.mdare correct — they were written or fixed as part of#73.
Why it is not a sweep
docs/examples/order-api.mdis the sharp case. It documents the examplefile by file, so it is not a stale line but a missing file: the page has no
src/auth.ts, never nameshttpAuth<Identity>(), and its slice table listsfour paths where the example now has five. Its controller samples cannot simply
gain
context.principaleither — the surrounding prose explains the tenant asan input field, which is the design #73 deliberately moved.
The other five are smaller, but each needs the contract sample, the controller
sample and the prose between them to move together, or the page contradicts
itself mid-scroll.
Not fixed in #74
That PR is about input validation, and it already touches these files. Mixing
in an identity rewrite would make its diff about two unrelated things, and the
order-api.mdhalf is a section rewrite rather than an edit. #74 changed theschemas on these pages and deliberately left the markers and controller calls
alone.
Acceptance
contract.orders,HttpControllerimported from the application'ssrc/auth.ts, theauthenticator wired at the root, and the tenant read off the principal.
docs/examples/order-api.md's file listing includessrc/auth.tsandsrc/authenticator.ts.dependencies it needs, per the repo's rule, and deleted afterwards.
execute(input.acrossdocs/returns nothing outsidedocs/api/.Worth fixing while there
Nothing gates these samples.
packages/corehasdocs-examples.test-d.tsforexactly this reason and the four starters do not — already recorded under
"Deferred, deliberately" in the root
CLAUDE.md, whose own trigger is "add itthe next time one of those samples is found to have drifted". This is the second
such finding in two days.