`plugin-auth/examples/basic-usage.ts` imports `@objectstack/plugin-hono-server`, which the package declares in no dependency block

[os-zhuang]

Surfaced by the #10756 census (the source-coverage blind spot), not repaired there: the
repair is a manifest change (or an example rewrite), which is a different surface from
that card's gate work.

The measurement

packages/plugins/plugin-auth/examples/basic-usage.ts line 12:

import { HonoServerPlugin } from '@objectstack/plugin-hono-server';

Compiled against the package's own config with the dependency closure built, on main @
5886ee6d22:

packages/plugins/plugin-auth/examples/basic-usage.ts(12,34): error TS2307: Cannot find
module '@objectstack/plugin-hono-server' or its corresponding type declarations.

packages/plugins/plugin-auth/package.json declares @objectstack/plugin-hono-server in
none of dependencies, devDependencies or peerDependencies. (It does declare
hono itself, which is a different package.) So the import cannot resolve, and the
example as written cannot run or compile for anybody who copies it.

Why nothing caught it

packages/plugins/plugin-auth/tsconfig.json selects include: ["src/**/*"], so
examples/ is in no tsc program the package's typecheck script runs — the exact
blind spot #10756 measures. Nothing else reads the directory either: it is not a test,
tsup builds only src, and no file imports it. It is the census's single instance of
source that is in no tsc program at all rather than merely outside its package's own.

The two repairs, both defensible

1. Add the dependency (devDependencies, workspace:*) so the example compiles.
   Right if the example is meant to be a working reference for the hono pairing.
2. Rewrite or delete the example. Right if it is stale — it is the only file in the
   directory and nothing references it.

Not choosing here. Whichever is taken, packages/plugins/plugin-auth/examples is an
entry in UNCHECKED_SOURCE_DEBT (scripts/check-type-check-coverage.mjs), and putting
the directory in a tsc program means deleting that entry — which RECONCILED forces.

Dedupe

search_issues for the import, the example path, and the missing-dependency shape
returns nothing.

[huangyiirene]

Triage: lands in packages/plugins/plugin-auth (the example file and/or its package.json manifest, plus the paired UNCHECKED_SOURCE_DEBT entry deletion once the directory joins a tsc program) ⇒ domain:services, pm:queue, type Task. Rationale: the choice between repair 1 (declare the dep as devDependencies: workspace:*) and repair 2 (delete/rewrite the sole stale example) is lane discretion — neither expands the accepted set or the public surface, so no maintainer decision is needed. Note for the services seat: whichever repair, coordinate the UNCHECKED_SOURCE_DEBT/RECONCILED ledger edit with the in-flight #10756 gate work (same instrument, fold-or-serial to answer at claim time). — triage seat, session session_016N5bHZr1DG4g9RK7v36YtV

---

Generated by Claude Code

[os-warren]

Claim: dispatched.

• session: user-29 [974948]
• branch: claude/issue-10869-plugin-auth-example-dependency
• worktree: ../objectstack-10869
• Clause-②: no — a manifest entry or an example rewrite changes no contract and widens no public surface.
• serial constraint: packages/plugins/plugin-auth/examples/ + package.json. ⚠️ PR fix(plugin-auth): verify-domain answers DOMAIN_VERIFICATION_DISABLED for the disabled condition #11004 (card plugin-auth: verify-domain answers a FAILURE code when domain verification is DISABLED, while its sibling route answers DOMAIN_VERIFICATION_DISABLED #10859) is open on src/register-sso-provider.ts in the same package and touches no manifest and no lockfile — verified against its file list. No conflict expected; do not touch its files.

Why this is dispatchable when the card says "Not choosing here"

The filer declined out of scope discipline, not because the choice needs a ruling. "Is this example a working reference or is it stale?" is answerable by measurement — whether the hono pairing is a documented supported pattern, whether anything references the file, whether the API it demonstrates still exists. Measure it and choose. If the measurements genuinely do not separate the two, report needs_decision rather than picking to make the card closeable.

⚠️ The trap: repair 1 as written is unverifiable

The card presents "add the dependency" and "rewrite or delete" as the two repairs. Adding the dependency does not put examples/ into any tsc program. packages/plugins/plugin-auth/tsconfig.json selects include: ["src/**/*"], and that is unchanged by a manifest edit — so after repair 1 the example still compiles in no program, pnpm typecheck still ignores it, and nothing verifies that the fix worked.

That matters twice over:

• you would be shipping a repair whose only evidence is that you typed the right package name;
• and the defect could silently return, because the blind spot that hid it ([finding] A package can pass check:type-check-coverage with a whole source directory outside tsc — packages/objectql/scripts/** is invisible to its own typecheck #10756's census: this is the census's single instance of source in no tsc program at all) is untouched.

So if you take repair 1, you must also produce a real compile of that file — either by widening the program, or by an explicit tsc invocation over it that you run and report. Reproduce the card's original error first (TS2307), then show the same invocation clean. A fix with no reproduction of the failure it fixes is not measured.

⚠️ The ratchet interaction — and a correction to how the card states it

The card says: "putting the directory in a tsc program means deleting that entry — which RECONCILED forces." That is right, but it applies only if you widen the program, not to a bare manifest edit. Be precise about which case you are in:

• manifest edit only → packages/plugins/plugin-auth/examples stays in UNCHECKED_SOURCE_DEBT (scripts/check-type-check-coverage.mjs); do not delete the entry, because the directory is still unchecked and a stale entry is its own failure.
• widen the program → the entry must be deleted in the same PR, and check:type-check-coverage will tell you so. Run it and quote its verdict line either way.
• delete the example → say explicitly what happens to the entry, and check whether the directory ceases to exist (an entry naming a directory that is gone is also stale).

⛔ Do not delete a debt-ledger entry to make a gate quiet. Every ratchet in this repo is shrink-only because the plugin was repaired, never because the entry was inconvenient.

Standing proof standard

Reproduce the TS2307 on the current tree before editing — the card measured it at 5886ee6d22 and the tree has moved; if it no longer reproduces, say so and stop. Ablation with the signature predicted first, restore proved byte-identical by git hash-object. Zero-hit counter-check with a positive control on the same corpus. Gate union derived on the final commit, clean tree, dispatch-gates.mjs with no path arguments, exit codes captured before any pipe. Class #10309 is live — run what you judge relevant explicitly and say whether the derivation named it. Changeset required. Draft PR only.

⚠️ A pnpm --filter that matches no script exits 0 having run nothing — echo the script name so a zero-match cannot read as a pass. An unwired script name exits 254 and reads GREEN through a pipe. Never git stash (shared stack). Never report a grep hit count as a fact count.

⛔ Do not touch content/docs/releases/** or packages/spec.

Refs

#10756 (the census that surfaced it, and the blind spot itself) · scripts/check-type-check-coverage.mjs (UNCHECKED_SOURCE_DEBT, RECONCILED) · #10615 (a standing plugin-auth TEST_DEBT surplus — not yours, do not run --lower)

---

Generated by Claude Code

[os-warren]

os-dev-report

{
 "issue": 10869,
 "status": "done",
 "branch": "claude/issue-10869-plugin-auth-example-dependency",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/11008",
 "premise_still_valid": true,
 "summary": "Chose repair 1 (declare the dependency) AND widened the program, because repair 1 alone is unverifiable. What chose it over 'delete the example': the file is PUBLISHED, not orphaned — content/docs/permissions/authentication.mdx:1284 links it as 'Basic Auth Example' under 'Complete working examples are available in the repository'; the hono pairing is a documented supported pattern stated in plugin-auth's own class docblock ('Server mode (HonoServerPlugin active): Registers HTTP routes at basePath'); and the API it demonstrates still exists as written, which the clean strict compile measures (ObjectKernel.use/bootstrap/getService/shutdown, HonoServerPlugin({port}), every AuthPluginOptions key it passes). Nothing read as stale, so it is a working reference and the repair is to make it work. Added @objectstack/plugin-hono-server as devDependencies workspace:* (src imports it nowhere — zero-hit counter-check below — and `files` ships only dist, so nothing new reaches a tarball; no cycle), plus packages/plugins/plugin-auth/tsconfig.examples.json, a non-emitting sibling named in the typecheck script on the packages/spec (#5475) and packages/objectql (#10756) precedent that check-type-check-coverage.mjs names as the remedy in its own header. Because the directory is now read, its UNCHECKED_SOURCE_DEBT entry was deleted and the ledger header records the graduation. Changeset added. Draft PR only; not marked ready, not queued, no auto-merge.",
 "tests": "All evidence at final commit a144502c, clean tree, merge base 163a16241. ⚠️ Every exit code captured BEFORE any pipe (cmd > file 2>&1; EXIT=$?), never after a tail; gate results quoted from the gate's OWN verdict line, never from a bare $?. REPRODUCTION (the card measured at 5886ee6d22; re-measured here): `cd packages/plugins/plugin-auth && pnpm exec tsc --noEmit -p tsconfig.examples.json` -> TSC_EXIT=2, `examples/basic-usage.ts(12,34): error TS2307: Cannot find module '@objectstack/plugin-hono-server' or its corresponding type declarations.` — same file, line and column as the card. IDENTICAL invocation after the fix -> TSC_EXIT=0, 0 bytes of output. ⚠️ INSTRUMENT, not a finding: the first run ALSO reported basic-usage.ts(13,28) TS2307 for @objectstack/plugin-auth itself — the unbuilt-closure artifact (the example self-references its own package, resolving through dist/index.d.ts, which was not built). Built it, second error gone, exactly the one card error left. Not explained away: `turbo run build --filter='./packages/*' --filter='./examples/*^...' --dry=json` lists @objectstack/plugin-auth#build, so lint.yml's typecheck-workspace builds it before typecheck and the self-reference resolves in CI. ABLATION — PREDICTION WRITTEN BEFORE MUTATING: remove the devDependency line + pnpm install => turns RED, exit 2, exactly one error, exactly `examples/basic-usage.ts(12,34): error TS2307: Cannot find module '@objectstack/plugin-hono-server' …`; direction predicted as a straight red (not a count change, not a reversal) because the widened program compiles the file unconditionally and only the resolution is removed. OBSERVED: exit 2, exactly that one error, exactly that line — prediction and observation match on all three. REBUILD STATEMENT: the ablated artifact is the pnpm workspace symlink, not a dist/ file, so the rebuild requirement takes its manifest-layer form — BOTH legs ran `pnpm install` and BOTH proved the artifact's state before reading tsc (mutation leg: 'LINK ABSENT'; restore leg: 'LINK PRESENT'); a manifest edit without install leaves the symlink and the mutated leg would have stayed falsely GREEN. RESTORE BYTE-IDENTICAL: package.json c2f5f3bdd79a2b2c4abb086b38717def53d811e4 -> c2f5f3bdd79a2b2c4abb086b38717def53d811e4; pnpm-lock.yaml 8491e01df7bc5f9468ddaad40f1adac461090c37 -> 8491e01df7bc5f9468ddaad40f1adac461090c37; restored leg re-runs TSC_EXIT=0. ZERO-HIT COUNTER-CHECK (claim: src imports plugin-hono-server nowhere, so devDependencies is the right block), positive control run FIRST: control `grep -rn \"from '@objectstack/core'\" src/` -> 3 hits (instrument reaches the corpus); claim `grep -rn \"from '@objectstack/plugin-hono-server'\" src/` -> exit 1, ZERO hits; second control, same pattern on examples/ -> basic-usage.ts:12 (the pattern itself works). ⚠️ A FIRST ATTEMPT AT THIS WAS NOT MEASURED and is discarded: its regex used `[^\\n]*`, whose bracket expression excludes the literal `n`, and its own positive control came back EMPTY — the control is what caught it. Also: 3 `plugin-hono-server` strings do exist in src/, all three inspected line by line and all three comment prose, no import (never reported as a count). LEDGER, both directions: BEFORE the ledger edit `pnpm check:type-check-coverage` GATE_EXIT=1 with its own line 'UNCHECKED_SOURCE_DEBT entry for \"packages/plugins/plugin-auth/examples\" is no longer unread source (a tsc program reads it now, or the directory is gone) -- delete it from scripts/check-type-check-coverage.mjs. That is the ratchet: this list only shrinks.' AFTER: GATE_EXIT=0, 'check-type-check-coverage: OK — 65/78 workspace packages type-checked (plus the root), 13 in the DEBT ledger …' and 'source layer: 9 directory(ies) … in 9 ledgered entr(y/ies)' (10 -> 9). GATE UNION derived on the final commit, clean tree, `node scripts/pm/dispatch-gates.mjs` with NO path arguments: DERIVE_EXIT=0, 5 paths vs merge base 163a16241, 20 families named. All 20 run, all EXIT=0: check:changeset-gate-self-tests, check:cross-package-test-inputs, check:entry-guard, check:objectui-changeset, check:override-consistency, check:parse-guard, check:slot-lookup, check:test-source-alias, check:type-check-coverage, check:type-check-debt, check:type-source-resolution, check-adr-0087-registration, check-changeset-fixed, check-changeset-no-major, check-ci-filter-parity, check-empty-changeset, check-osv-exemptions, check-plugin-teardown-shape, check-affected-docs. CLASS #10309 — the derivation IS short here and I say so: it did NOT name check:published-files or check:nul-bytes, both of which I judged relevant (a package.json and a new tsconfig were edited) and ran explicitly; both EXIT=0, 'check-nul-bytes: OK (scanned 6357 text file(s) … no raw ASCII control bytes)'. ⚠️ REFUSAL, NOT A MEASUREMENT: check:type-check-debt first exited 1 with '--re-measure cannot run: 30 workspace dependenc(ies) of the ledgered packages have no built type entry point on disk' — nothing was checked, so it was NOT recorded as a pass or a fail. Built the closure exactly as lint.yml does (`turbo run build --filter='./packages/*' --filter='./packages/*/*'`, 'Tasks: 70 successful, 70 total') and re-ran to its own green verdict: 'check-type-check-coverage --re-measure: OK — 33 ledger entr(ies) re-measured in 381.0s, 1908 raw tsc error(s) total, none above its recorded number.' Also green: 'check-type-source-resolution OK — 77 packages with a tsconfig.json scanned; 51 registered as still resolving a workspace dep's types through dist/.' PACKAGE SUITE, script name echoed so a zero-match cannot read as a pass — declared script: `vitest run`; `pnpm --filter @objectstack/plugin-auth run test` -> TEST_EXIT=0, 'Test Files 67 passed (67)', 'Tests 1400 passed (1400)'. Package typecheck, script echoed as `tsc --noEmit && tsc --noEmit -p tsconfig.examples.json` -> TYPECHECK_EXIT=0. All heavy build/test ran through scripts/pm/os-verify-lock.sh (VERDICT lines: 308s, 15s, 476s, 80s). NO NARROWINGS DECLARED — nothing was skipped or scoped down. NOT RUN, deliberately: `check:type-check-debt --lower`. The gate reports '@objectstack/plugin-auth: TEST_DEBT records 109, tsc now reports 97 (-12) -- the entry can be lowered'; that is the standing surplus in #10615, it pre-dates this branch, and this PR touches no test and no src file, so that ledger is not this card's to move.",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code