Root tsconfig core path report

Date: 2026-03-06

Scope

Safe review and narrowing of root-level @kvary/core TypeScript path mappings.

Primary target:

• tsconfig.json

Root config chain

Observed state:

• root tsconfig.json did not extend any base config
• no package or service tsconfig*.json files were found to extend root tsconfig.json

Implication:

• root @kvary/core/* path mappings were not serving as a shared inherited base
• their effect was limited to tooling/commands that resolve TypeScript from repo root and happen to consult the root tsconfig

Previous root mappings

Before this change, root tsconfig.json contained:

• @kvary/core/governance -> packages/core/governance/index.ts
• @kvary/core/* -> packages/core/*

These were raw source mappings into packages/core.

Consumer classification

| Consumer/context | Example | Classification | Notes | | --- | --- | --- | --- | | web app | apps/web/src/app/.../kes/page.tsx | SAFE_PACKAGE_RESOLUTION | already stabilized separately in web config | | service code with local tsconfig | services/api/src/tenders/engine.ts | SAFE_PACKAGE_RESOLUTION | service uses its own tsconfig, not root | | root-run tsx script | scripts/golden.ts | SAFE_PACKAGE_RESOLUTION | works through package-name resolution | | root-run JS script | scripts/golden.js | TOOLING_ONLY | Node require() uses package exports | | root-run TS test | tests/governance/governance.replay-determinism.test.ts | SAFE_PACKAGE_RESOLUTION | imports resolve without root paths | | source-inspection tooling | scripts/verify-governance-consistency.ts | TOOLING_ONLY | uses raw filesystem path to packages/core/governance/types.ts, not @kvary/core/* | | shell compile script | scripts/run-ledger-v2-golden.sh | TOOLING_ONLY | compiles raw packages/core/*.ts files by path | | app cache artifact | apps/web/tsconfig.tsbuildinfo | MANUAL_VERIFY_FIRST | cache artifact, not a source consumer |

Change applied

Smallest safe change:

• removed only the root paths mappings for @kvary/core/governance and @kvary/core/*
• kept baseUrl: "." unchanged

This preserves overall root tsconfig shape while eliminating explicit raw-source aliasing for @kvary/core.

Validation

Root-run script

Executed:

npm exec -- tsx scripts/golden.ts

Result:

• succeeded after root mapping removal

Representative TypeScript resolution from root

Executed:

npm exec -- tsc --noEmit --traceResolution scripts/golden.ts
npm exec -- tsc --noEmit --traceResolution tests/governance/governance.replay-determinism.test.ts

Observed:

• @kvary/core/* still resolves successfully
• resolution goes through node_modules/@kvary/core/package.json
• TypeScript then resolves to workspace-backed files such as:
  • packages/core/canonical/canonicalSerialize.ts
  • packages/core/governance/appendGovernanceRecord.ts
  • packages/core/governance/types.ts

Important nuance:

• after removing root paths, root-level TypeScript tooling no longer depends on explicit tsconfig aliasing
• however, it may still resolve to package source .ts through the workspace symlink in node_modules
• that remaining source coupling is a workspace/package-resolution behavior issue, not a root tsconfig paths issue

Service validation

Executed:

npm --prefix services/api exec -- tsc -p tsconfig.json --noEmit

Observed:

• no @kvary/core module resolution regressions were introduced
• service-level compile context continues to rely on package resolution, not root tsconfig paths

Known unrelated failures

Some root-level tsc invocations still surface unrelated app alias errors under apps/web because those commands are not scoped to a single project config. These are not caused by removing root @kvary/core path mappings.

What changed

• tsconfig.json: removed raw @kvary/core paths

What remains dependent

Remaining source-coupled tooling is still present, but not because of root tsconfig paths:

1. verify-governance-consistency.ts
2. verify-governance-consistency.js
3. run-ledger-v2-golden.sh

These use raw filesystem paths into packages/core, and should be handled as separate tooling migrations.

Recommended next cleanup candidates

1. tooling migration for raw packages/core/*.ts filesystem consumers
2. review whether @kvary/core should eventually expose stronger declaration-first resolution for root TypeScript tooling
3. only after those steps, revisit the remaining packages/core/*.js manual-verify cleanup set