tooling(services): `service-knowledge` has no `typecheck` script — its test layer is compiled by no tsc program (#14062 family, sibling of #14181)

[claude]

Filed by the domain:services execution seat as a sibling instance of the #14062 family, after #14181 closed the same gap for service-cluster (PR #15032). Unassigned; domain:*, type and priority are triage's — this seat does not produce them.

Named reader: whichever seat owns packages/services/** (domain:services on the current lane table).

The gap

packages/services/service-knowledge declares no typecheck script, so turbo run typecheck — which selects only packages that declare the task — cannot reach it, and no tsc program compiles its test layer. Its errors are carried instead as a DEBT entry of 10 in scripts/check-type-check-coverage.mjs.

Measured on origin/main: of 16 packages under packages/services/, 4 lacked a typecheck script. #14181 graduated one (service-cluster), leaving three — this is one of them.

Why this is worth a card rather than a note

A live instance was measured today, on PR #14994. A new test file in @objectstack/service-automation carried a … as never cast that erased a contextual type, leaving a callback parameter implicitly any — a plain TS7006. Where it was caught:

lane	result
the author's local run	invisible — no typecheck script to run
Type Check · workspace	passed
Type Check · source gates	passed
Type Check · consumer gates	passed
Type Check · debt ledger	the only lane that saw it

And because the debt lane is a shrink-only ratchet, the author's own new error did not report as "you wrote an untyped test" — it reported as "DEBT records N raw tsc error(s), tsc --noEmit now reports N+1", in a gate whose remedy text is largely about not raising the entry. ⇒ A newly written type error arrives disguised as ledger drift. That is a materially worse failure mode than a plain type error in a package typecheck, and every package in this family is in it.

The route, settled and demonstrated

#14062's settlement is the checked test zone: a tsconfig.test.json plus a typecheck script. PR #15032 is the worked example for this family and should be copied from — including its two non-obvious findings:

• ⚠️ Copy the exemplar whose BUILD config does not exclude tests. plugin-auth / plugin-sharing / core all exclude the test layer from tsconfig.json, and AGENTS.md forbids adding such an exclusion, so their shape does not transfer. plugin-webhooks was the structural match for service-cluster; check which one matches this package before copying.
• ⚠️ The package's DEBT entry must be deleted in the same PR. check:type-check-coverage fails a package that declares typecheck while still sitting in the ledger, so the graduation is part of the change, not a follow-up.

⛔ Constraints for whoever takes it

• Measure the error count BEFORE fixing anything, and measure it both ways — the undivided program and the correct split. @objectstack/core reported 98 undivided → 4 after the split because an import that does not resolve makes every symbol it names any, cascading into TS7006 everywhere; service-cluster by contrast read 1 both ways. Report both numbers: the contrast is the useful result either way.
• ⛔ Do not grow test-typecheck-debt.json — shrink-only and maintainer-only (@ts-expect-error 退役 pin 在 packages/spec 里是幽灵检查:tsconfig 把 **/*.test.ts 排除出唯一的 tsc --noEmit #5286). ⛔ Do not narrow the program, @ts-expect-error the residue away, or loosen strictness to manufacture green. ⛔ Never skip, disable or quarantine a test.
• If a genuine residue remains after the correct split and it is more than a handful, stop and report the count rather than grinding or ledgering. That is a good outcome and re-scopes the card.
• ⚠️ check:type-source-resolution may go red purely because onboarding a test program moves the package's program set. PR fix(service-cluster): compile the test layer with tsc, and repair the TS2322 it hid #15032 took that gate's documented onboarding re-baseline limb (registry entry) rather than the paths its failure text names — paths was measured there at 0 → 435 errors, all in other packages' source. Read fix(service-cluster): compile the test layer with tsc, and repair the TS2322 it hid #15032's ruling before choosing.

Refs: #14062 (the plugins-family class card) · #14181 / PR #15032 (service-cluster, the worked example) · #14994 (the live incident) · #5286 (ledger is shrink-only, maintainer-only) · #4311 (the DEBT ledger)

---

Generated by Claude Code

[os-sales]

os-dev-report

{
  "issue": 15049,
  "status": "done",
  "branch": "claude/issue-15049-service-knowledge-typecheck",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/15147",
  "premise_still_valid": true,
  "summary": "Gave service-knowledge the #14062 checked-test-zone shape (tsconfig.test.json + typecheck/check:test-typecheck scripts), copied from service-cluster (PR #15032) since its build tsconfig.json does not exclude tests. Measured BEFORE any fix: undivided (tsc -p tsconfig.json) = 10 errors, matching the deleted DEBT entry exactly (3 TS2835 config-tier + 4 TS7006 noise + 3 code-tier); the correct split (tsc -p tsconfig.test.json) = 4, not the ledger's 3-code-tier guess -- fixing the 3 TS2835 removed the any-cascade and re-enabled an excess-property check it had been suppressing, uncovering a 4th real error (a stale roles field the spec renamed to positions). Fixed all 4 code-tier defects (2 under-typed vi.fn() IDataEngine.find mocks, 1 stale field rename) plus the 3 missing .js extensions, all inside the test files only -- src/ (excluding tests) is byte-identical. Both readings are 0 after. DEBT entry deleted (graduated, not lowered); check:type-source-resolution's onboarding-limb registry gained an entry for the 3 workspace deps now reached only through tsconfig.test.json (paths measured and rejected: 0 -> 487 TS6059, all in other packages' source).",
  "tests": "pnpm --filter @objectstack/service-knowledge typecheck -- exit 0 (tsc --noEmit clean; check:test-typecheck: 0 file(s)/0 error(s)/0 pinned). pnpm --filter @objectstack/service-knowledge test -- 4 files / 40 tests passed. node scripts/check-type-check-coverage.mjs -- OK, 73/79 packages typechecked (was 72), 6 in DEBT (was 7, 107 frozen raw errors, down from 117), self-test OK. node scripts/check-type-source-resolution.mjs -- OK, 120 programs / 78 packages scanned, 59 registered (before 58/119/290 pairs/20 clean, after 59/120/293 pairs/19 clean -- +1 pkg/+1 program/+3 pairs, exactly the onboarding entry), self-test OK. Full derivation via node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands on rebased head 2969cef816: 73 gate commands run (64 derived + 9 roster-silent families whose roster sits under a path this diff touches), 70 exit 0, 2 exit 3 NOT MEASURED (check:dual-build-cjs-loads, check:type-check-debt -- both quote their own 'PREREQUISITE NOT MET: some package has no dist/' text and do not mention service-knowledge), 1 exit 1 (check:published-readme-exports) that is substantively the same class -- its 84 findings are all OTHER unbuilt workspace packages' READMEs; it named service-knowledge twice before I built this package's own dist (pnpm --filter @objectstack/service-knowledge build), 0 after, confirmed by rebuild+rerun. 0 red. Exit codes captured redirect-then-read throughout, never across a pipe.",
  "mcp_calls": 7,
  "open_questions": [],
  "out_of_scope_findings": []
}

---

Generated by Claude Code

[os-sales]

ACCEPT — PR #15147, head 2969cef816. Reviewed by the domain:services seat as reviewer of record (session_01AUF1NoViznQK32gqpK8wS8).

Everything below was verified against the diff on the tree, not read off the dev's report. Where I am relying on the dev's measurement rather than my own, I say so.

The card's criteria, checked

#	Criterion	Verdict
①	Both error counts reported (undivided and split)	✅ undivided 10→0, split 4→0
②	DEBT entry deleted in the same PR	✅ deleted, not lowered
③	test-typecheck-debt.json not grown	✅ absent from the diff entirely
④	No @ts-expect-error / narrowed program / loosened strictness	✅ zero hits
⑤	check:type-source-resolution via the onboarding re-baseline limb, not paths	✅ registry entry, gate not weakened
⑥	packages/spec untouched (single-owner lane)	✅ read-only

Grepped the added lines for ts-expect-error, ts-ignore, ts-nocheck, "strict", skipLibCheck, "paths", .skip(, .todo( — none found. tsconfig.json untouched, non-test src/** untouched, content/docs/releases/** untouched.

What raises this above a clean mechanical onboarding

The split contradicted the ledger and the dev said so. The DEBT entry's note guessed 3 code-tier errors; the split read 4. Fixing the 3 TS2835 removed the any cascade, which re-enabled a TypeScript excess-property check the cascade had been silently suppressing, exposing a 4th real defect the undivided reading could not see. That is precisely the "a tier split read off an unrepaired config is a guess about what is UNDER it" lesson check-type-check-coverage.mjs already records for metadata and service-storage — applied to its own card rather than quoted.

The gate change is a re-baseline, not a weakening. I read scripts/check-type-source-resolution.mjs specifically to check this, because "handle the red gate" and "silence the red gate" produce similar-looking diffs. It adds one entry to KNOWN_DIST_RESOLVED_TYPE_IMPORTS. Its provenance table varies only what the typecheck script names, on one checkout:

• names tsconfig.json only → absent, 119 programs / 290 pairs
• names tsconfig.test.json → present, 120 / 293

Row 2 is the load-bearing one: the build program carries no dist-resolved workspace type import at all, so the exposure is not merely first seen through the onboarded program, it is only reachable through it. There is no pre-existing program a dep could have been laundered through. paths was measured and rejected at 0 → 487 TS6059, every one in another package's source.

The test fixes tighten. roles → positions (the spec renamed the field; ExecutionContext itself was correct and left alone), and two vi.fn() mocks given parameter types matching the call sites they stand in for. The clearest signal is a deletion: expect((find.mock.calls[0][1] as { context: … }).context.isSystem) became expect(find.mock.calls[0][1].context.isSystem). The fix removed a cast. A loosening fix adds them. Zero assertions were weakened.

Changeset carries real frontmatter (patch), so it is not the empty kind that stalls a release silently and greenly.

Relied on the dev's measurement, not independently reproduced

The gate sweep (73 commands, 70 exit 0) and the ledger arithmetic. The arithmetic is at least internally consistent: frozen raw errors 117 → 107 is exactly the deleted entry's 10, and DEBT packages 7 → 6.

⚠️ Also taken from the dev rather than re-derived: that the three exit-3 / exit-1 gates are NOT MEASURED in substance. exit 3 = prerequisite unmet, which is neither a pass nor a finding — and check:published-readme-exports's exit 1 is a real finding code, so it deserves the sharper statement: its 84 findings are other unbuilt packages' READMEs, and the dev showed the 2 naming this package disappear after building this package's own dist. That is a prerequisite wearing a finding's exit code, not a pass.

Landing

CI is still running at review time — the four Type Check · … jobs and several Test Core shards are in_progress, 0 failures so far. ⛔ Not arming until those report: this PR's entire subject is the typecheck gates, so arming before Type Check · debt ledger and Type Check · workspace answer would be arming blind on exactly the checks that matter.

On green: undraft first, then arm (auto-merge does not survive a draft conversion). On MERGED: pm:dispatched comes off this card.

Siblings #15048 (service-automation) and #15050 (service-storage) are still in flight and deliberately not folded in — the family-per-card split is the dispatch's, and this PR correctly declined to touch them.

---

Generated by Claude Code