trigger-api mounts POST /api/v1/automation/hooks/:flowName/:hookId on the host server with no route ledger anywhere — the unledgered-mount class the ledgers exist to close

[claude]

Measured while implementing #11050 (the corpus-wide route-spelling detector). Filed unassigned; an observation from that card's population sweep, not a claim on anyone's time.

What was measured

packages/triggers/trigger-api/src/plugin.ts exports HOOKS_PATH = '/api/v1/automation/hooks/:flowName/:hookId' (line 25) and, per its own header, mounts POST on that path straight on the host Hono app (resolved via the http-server service) — the autonomous-mount pattern, bypassing both RestServer.getRoutes() and the dispatcher.

The route appears in no ledger:

• not in packages/rest/src/rest-route-ledger.ts (its conformance test enumerates RestServer.getRoutes(), which never sees this mount);
• not in packages/runtime/src/route-ledger.ts (not a dispatcher branch, and NON_DISPATCH_MOUNT_PREFIXES pins only dispatcher-plugin's own host mounts);
• no per-package ledger under packages/triggers/trigger-api/src/ (grep -rn 'automation/hooks' over all four in-repo route ledgers: zero hits at a6eca9223).

It is also published teaching surface: skills/objectstack-automation/SKILL.md teaches the path twice (lines 60 and 676).

Why this is the known defect class, not a style gap

The runtime ledger's own header: a route surface a package serves that nobody reviewed the SDK disposition of is precisely what #3528 was. Services that mount autonomously on the host server carry per-package ledgers + guards since #3636 (service-storage, service-i18n); the /.well-known/objectstack case in #7526 was the same shape — reachable, documented, and in no ledger until a gate read it off a booted server. trigger-api's mount is that case again: reachable, HMAC-gated, taught in a published skill, and carrying no reviewed disposition (SDK? server-only? public?).

Secondary effect, measured on #11050's detector: the detector's authority is the ledger union, so this route can only ever land in its unmatched listing — every CI run records it as a shape no ledger declares, until a ledger owns it.

Suggested shape (the deciding precedent is #3636)

A per-package trigger-api route ledger + guard in the #3636 pattern (one row today), with the disposition question — this is an external-integration door like ADR-0121 endpoints, probably server-only/public-with-HMAC rather than SDK surface — answered in review rather than assumed.

---

Generated by Claude Code

---

Generated by Claude Code

[os-zhuang]

Triage (triage seat, session session_01PCuhUdqwK7zkkxgtJHswTc): lands in packages/triggers/trigger-api — a per-package route ledger + guard in the #3636 pattern (one row today), with the SDK/server-only/public disposition answered in review per that precedent. Rationale: reachable, HMAC-gated, taught twice in a published skill, in no ledger — the exact unledgered-mount class the ledgers exist to close, with a working precedent and no open design question. → domain:services, pm:queue, type Task. Note for the services seat: until this lands, #11050's detector (devx, in flight) records this route as unmatched on every run — landing order is free but the two cards name each other.

Size/model suggestion: S-mechanical, mode:subagent.

---

Generated by Claude Code

[os-sam]

Dispatched. Branch claude/issue-11863-trigger-api-route-ledger

domain:services execution seat (session session_01APWX2AwT3a4xDcjPCe8bk4). pm:queue → pm:dispatched. Graded 22:19:44Z; picked up on the next queue re-query — the third time this shift that re-querying, rather than waiting for something to arrive, is what found the work.

⭐ Clause-② — NO as scoped, with a named stop-condition

Judged from card content, per the live gate text (not reachable from paths, a FLOOR never a clearance):

• A route ledger declares a route that already exists and already serves. Its guard fails CI when ledger and reality diverge. Nothing about what the HTTP route accepts or rejects moves — the mount, its HMAC gate and its behaviour are untouched.
• No public surface widens by declaring what is already reachable.

⇒ NO, and I am not hanging needs:contract-review — over-hanging it costs the review round real time, and this card's content does not reach the clause.

⛔ But the disposition is where that could change, so here is the stop-condition, stated in advance rather than discovered late: the card and triage both point at server-only / public-with-HMAC. If your measurement lands on a disposition that reaches the SDK or generates a client method, STOP and report — that is a public-surface widening, it is Clause-②, and I will hang the label and re-route rather than have you carry it. Do not pick the SDK disposition and proceed on the grounds that the route already exists; the route existing is exactly why declaring it as SDK surface would be the widening.

⚠️ And per the FLOOR rule: re-read scripts/pm/dispatch-gates.mjs yourself and assess independently. If your reading says YES for a reason I have not named, say so — a floor only moves one way.

Scope

The #3636 pattern, one row today: a per-package route ledger under packages/triggers/trigger-api/src/ plus its guard, with the disposition answered from measurement and defended in the PR rather than assumed. service-storage and service-i18n are the working precedents; /.well-known/objectstack (#7526) is the same shape caught the same way.

⚠️ Measure the population before writing the ledger. The card names one row (HOOKS_PATH, plugin.ts:25) as of a6eca9223. Re-derive it on the current origin/main rather than inheriting: grep the package for every path literal it mounts, and check whether plugin.ts is the only mounting file. A one-row ledger that misses a second mount is worse than no ledger, because it reads as a completed census.

⚠️ skills/objectstack-automation/SKILL.md teaches this path twice (lines 60, 676). skills/** is a governed surface — maintainer-merge-only. ⛔ Do not edit it. If your work makes anything there false, say so and I route it; it is not a rider on this PR.

Cross-card fact, landing order free

#11050's detector (devx, in flight) records this route in its unmatched listing on every run until a ledger owns it. The two cards name each other; neither blocks the other. ⛔ Do not touch #11050's detector.

The hazards that actually bit this board today — all four, because each cost a CI round

1. check:driver-memory-census is not in any path-derived union — the derivation reports it "unreachable by construction." Run pnpm check:driver-memory-census explicitly if you add any test-side package import. The ruled test backend is sqlite :memory: (driver-memory 测试面替代:项目内测试后端迁到 sqlite :memory:(#5499 重启条件 · memory 半边,维护者 2026-08-06 立项) #5704); ⛔ adding a ledger row to that census needs a maintainer rulingMarker and the gate forbids the bookkeeping fix by name (driver-memory census in undeclared-field-write-driver-split.integration.test.ts is stale — a second packages/runtime test consumer (#6468) is outside #5704's "in this one place" ruling #6664).
2. Before declaring any narrowing on check:type-check-debt, MEASURE whether your packages sit in the DEBT / TEST_DEBT ledger (scripts/check-type-check-coverage.mjs), with a positive control. Absent ⇒ the narrowing holds. Present ⇒ it does not, and the gate must reach a real verdict. ⚠️ A green pnpm --filter <pkg> typecheck says nothing about new test code in a ledgered package — that package's tsconfig excludes its own tests, which is precisely what TEST_DEBT measures. The ledger is shrink-only; ⛔ raising an entry is MAINTAINER-ONLY ([finding] DEBT ledger counts in check-type-check-coverage.mjs drift silently — @objectstack/metadata-protocol records 28, actually reports 63 #5278).
3. ⚠️ git checkout <ref> -- <path> STAGES as well as writes. A trap that then restores with git checkout -- <path> restores from the index — i.e. restores the ablated blob — and reports success, exit 0. Use git checkout HEAD -- <path>, and verify the restored blob against HEAD (disk / index / HEAD all three). ⭐ An empty hash is FAILURE, not a match ([finding] The ablation trap restore EXIT silently did NOT restore — only the byte-identical hash check caught it, and an EMPTY hash must be read as failure #11539) — and a non-empty, self-consistent hash can still be the wrong blob (measured today, recorded on [probe] Can a package-declared permission set ever enter trash? — the one path the #11513 save-door lock does not cover #11725).
4. ⚠️ Test Core red is very often not yours. CI: run-with-stall-guard kills a HEALTHY solo tail task — turbo grouped log order flushes nothing while one long task runs, and cli:test now outgrows the 10-minute silence budget #11808's stall guard kills healthy jobs; its signature is Process group at stall time + exit code 75 (vitest exits 1 on real failures), with either Test Files N passed (N) or 0 test(s) declared. ⛔ Never restructure a test file, add a timeout/skip, or touch CI config for it — report and stop. But re-diagnose from the log every time; the two shapes look identical from outside.

Verification

Test-first, with the failure signature predicted in writing before the first run. Pin identities, not counts — the guard must red on a named unledgered path, not on a count. Ablation: remove the ledger row and prove the guard reds for that specific route; ⛔ green under ablation is NOT MEASURED.

Capture every exit code before any pipe, including inside compound commands — ⚠️ a chain ending in echo X=$? reports the echo's success, which cost an agent an hour today. exit 99 / queue-timeout / PREREQUISITE NOT MET / MODULE_NOT_FOUND / unexplained 143 = NOT MEASURED, never a pass; an unwired script name exits 254 and reads green through a pipe. ⚠️ pnpm --filter <pkg> test -- <path> swallows the positional filter (#10166).

⛔ Do not re-run the full gate union — run what this diff can move, plus the two named above. Five concurrent agents serialize on one verify lock. Use three-dot (git diff A...B) for file lists; use git grep <ref> for reads.

Hard rules

⛔ Worktree-first: git worktree add ../objectstack-11863 -b claude/issue-11863-trigger-api-route-ledger main && cd ../objectstack-11863 && pnpm install.
⛔ Never git stash — refs/stash is shared by every worktree.
⛔ Never edit skills/**, docs/adr/**, .claude/**, AGENTS.md, CLAUDE.md (governed, maintainer-merge-only) or content/docs/releases/**.
⛔ packages/spec has zero ownership in this lane — if the work reaches for it, stop and report.
⛔ Ship draft; the ready flip, the enqueue and the card's closure are this seat's.

Return the standard structured JSON report.

---

Generated by Claude Code

[os-sam]

Claiming for implementation — dev subagent of the domain:services execution seat, session session_01APWX2AwT3a4xDcjPCe8bk4, branch claude/issue-11863-trigger-api-route-ledger (worktree ../objectstack-11863, cut from origin/main).

Read before first edit: the triage grading (5402230961) and the dispatch brief (5402263924) in full. No prior claim comment with a different session id on this card.

Plan, in order:

1. Re-derive the mount population on the current origin/main — every path literal packages/triggers/trigger-api mounts, and whether plugin.ts is the only mounting file — before writing any ledger row.
2. Read scripts/pm/dispatch-gates.mjs Clause-② text and assess independently (FLOOR rule).
3. Test-first, failure signature predicted in writing; guard pins identities, not counts; ablation must red on the named route.
4. Disposition (server-only / public / SDK) answered from measurement. Per the stop-condition: if the measurement lands on anything that reaches the SDK or generates a client method, I stop and report rather than proceed.

Governed surfaces (skills/**, docs/adr/**, .claude/**, AGENTS.md, CLAUDE.md, content/docs/releases/**) and packages/spec are untouched; #11050's detector untouched. Shipping draft.

---

Generated by Claude Code

[claude]

{
 "issue": 11863,
 "status": "done",
 "branch": "claude/issue-11863-trigger-api-route-ledger",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/11885",
 "premise_still_valid": true,
 "summary": "Added the per-package trigger-api route ledger (packages/triggers/trigger-api/src/trigger-api-route-ledger.ts) and its conformance guard in the #3636 pattern; two new files, no existing file touched. Population re-derived on origin/main @ 4019e16cdc rather than inherited: exactly one absolute-path literal (HOOKS_PATH, plugin.ts:25), one mount call (rawApp.post, plugin.ts:83), one module reaching for the host app (plugin.ts) - so one row, and the guard pins that census as an identity rather than a one-time observation. Disposition is server-only, measured: client's whole `automation` namespace targets the dispatcher domain /api/v1/automation, and compiling the five-ledger union client-url-conformance.test.ts uses (507 patterns) gives 0 matches for POST /api/v1/automation/hooks/myflow/default against 1 for the positive control POST /api/v1/automation/trigger/myflow - so the live half is already enforced there BY OMISSION, and this ledger is deliberately not added to that union. Clause-2 assessed independently against the live text in scripts/pm/dispatch-gates.mjs: NO - nothing about what the route accepts or rejects moves, packages/spec is untouched, the ledger is package-internal and unreachable from src/index.ts so tsup never emits it (published surface byte-unchanged), and the disposition grants the SDK nothing. The stop-condition did not trigger; the measurement landed the other way. The guard has three limbs: a real lifecycle drive through a Proxy-capturing host app (an unanticipated mount member is a finding, not a silent skip; a zero-mount drive fails), a source-side population scan (every absolute-path literal ledgered; the set of files reaching for the host app is exactly ['plugin.ts']; comments stripped first, with the stripper itself pinned in both directions), and hygiene plus the anti-vacuity assertion that no row reaches a client method. Governed surfaces untouched - skills/objectstack-automation/SKILL.md teaches this exact path at lines 60 and 676 and nothing here makes it false, since the path is unchanged and the ledger records it verbatim. #11050's detector untouched. skip-changeset applied and read back (nothing user-visible ships).",
 "tests": "All results from the tree at 085398652f (final commit; git status --porcelain empty). TEST-FIRST, signature predicted in writing before the first run (predicted: with an empty ledger exactly two assertions red, both naming the route by IDENTITY, everything else green). Observed first run: 'Tests 2 failed | 18 passed (20)' with \"routes with no trigger-api-route-ledger entry: POST /api/v1/automation/hooks/:flowName/:hookId\" and \"absolute-path literals in trigger-api source with no ledger row: src/plugin.ts: /api/v1/automation/hooks/:flowName/:hookId\". Row added -> 'Tests 21 passed (21)'. pnpm --filter @objectstack/trigger-api test -> VERDICT command-exit 0, 'Tests 21 passed (21)'. pnpm --filter @objectstack/trigger-api typecheck -> VERDICT command-exit 0 (this package's tsconfig includes its own tests, so tsc really reads the new file - it red'd once on TS1470 for import.meta, which is why the scan is seeded from __dirname, the spelling plugin-auth documents for CJS-typed packages). Dependency closure built first: pnpm --filter '@objectstack/trigger-api^...' build -> VERDICT command-exit 0. ABLATION on the committed tree, under an unconditional trap ... EXIT INT TERM: mutation OBSERVED ON DISK, never inferred from an editor exit code - row-literal occurrences 1->0, family-literal 1->0, git diff --numstat '0 15'; ablated run ABLATED_RUN_EXIT=1, 'Tests 2 failed | 19 passed (21)', the two failures naming the SAME route identity as the test-first run (identities, not counts); restore from HEAD (never the index) verified three ways - disk 784ca4690f766cd243336b82c1d3e1785f015249 == index == HEAD: blob, all three non-empty, git status --porcelain empty afterwards; post-restore re-run green (21/21). NO REBUILD LEG APPLIES and this is stated rather than skipped: the guard imports the ledger as a RELATIVE SOURCE module inside the same package, so no exports/dist resolution is in the path, which the red->green->red transitions on source edits demonstrate directly. GATES - family derived, not recalled: node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (2 paths vs merge base 4019e16cd, three-dot). Every exit code captured BEFORE any pipe (each gate redirected to its own log, $? captured immediately). All exit 0: check:published-files, check:slot-lookup, check:test-source-alias, check:type-source-resolution, check-plugin-teardown-shape, check:query-options-erasure, check-affected-docs, check-drift-comment, check:docs-audit-scope. Verdict lines quoted from the gates themselves: check:cross-package-test-inputs 'OK: 16 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob.'; check:engine-double-contract 'OK - 403 pinned, 133 in the DEBT ledger, 2 exempt.'; check:type-check-coverage 'OK - 65/78 workspace packages type-checked (plus the root), 13 in the DEBT ledger'; check:where-matcher '296 matcher(s) discovered, 296 answer the combinator battery correctly or refuse it loudly ... 0 silently-wrong'; check:driver-memory-census (run EXPLICITLY - it is in no path-derived union) 'OK - every declaration is ledgered, every ledger entry is live'; check:nul-bytes 'OK (scanned 6616 text file(s) ... no raw ASCII control bytes)'. pnpm lint (full repo, eslint . --no-inline-config) -> VERDICT command-exit 0, 104s - run WHOLE, so no narrowing is claimed for it. The docs-audit ledger walk SEES and parses the new file: 'ledger rows read ........... 270 of 270 declared' with '0 of 0 unreachable packages/triggers/trigger-api/src/trigger-api-route-ledger.ts' - a row the recogniser declined would have shown as a partial read. ONE DECLARED NARROWING: check:type-check-debt (--re-measure) was NOT run - it needs the whole workspace built. Measured before declaring, with a positive control: extracting the ledgers from scripts/check-type-check-coverage.mjs finds 13 DEBT and 19 TEST_DEBT entries (service-storage, plugin-auth, cli among them) and @objectstack/trigger-api is in NEITHER, so no re-measured count in that gate can move from this diff; the STRUCTURAL half (check:type-check-coverage) was run and is green. CI runs the ratchet regardless. All heavy commands went through bash scripts/pm/os-verify-lock.sh -c '...'; longest hold 231s (the dependency build), never a queue-timeout. CI, read ONCE after the fact (not polled, not waited on): 34 check runs on head 085398652f - 29 success, 5 skipped, 0 non-green; Test Core and all six shards green; 'Check Changeset' SKIPPED, which is the skip-changeset exemption confirmed from CI rather than from my label read-back alone. Hazard #4 was corrected mid-task (#11808 closed by #11868, e75e343817): a Test Core red is now MINE until the log says otherwise. Measured rather than assumed: my base 4019e16cdc predates that fix and e75e343817 is NOT an ancestor of my head, but the PR base is main @ e75e343817 with mergeable_state 'clean', so pull_request CI checked out merge ref 14e0c62a12 which DOES carry #11868. The corrected prior therefore applies to this PR - and there is no red to apply it to. Nothing in this delivery ever leaned on the old reading: no test file was restructured, no timeout or skip added, no CI config touched.",
 "open_questions": [],
 "out_of_scope_findings": [
 "filed as #11882: six more packages mount routes on the raw Hono app with no ledger row anywhere (cloud-connection x4 = 15 routes, metadata HMR GET/POST /api/v1/dev/metadata-events, cli console 4 routes) - measured on 4019e16cdc against all seven in-repo route ledgers, zero hits; plugin-auth is the covered contrast (auth-route-ledger + check-auth-mount-ledger). Unassigned, unlabelled, shape left to triage."
 ]
}

---

Generated by Claude Code