Skip to content

Six docs pages still describe order-api before it had authentication #75

Description

@btravers

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P1Should land before 1.0 — real DX cost, or a decision blocking other workbugSomething isn't workingdocumentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions