Core tooling path cleanup report

Date: 2026-03-06

Scope

Tooling-only stabilization for:

• verify-governance-consistency.ts
• verify-governance-consistency.js
• run-ledger-v2-golden.sh

Previous raw filesystem dependencies

Governance consistency scripts

Both scripts previously read:

• packages/core/governance/types.ts

Dependency type:

• direct filesystem read of a raw TypeScript source file

Classification:

• SAFE_TO_REDIRECT_TO_DIST_SUBPATH

Reason:

• the scripts do not need TypeScript compiler APIs or source traversal
• they only parse the emitted GovernanceRecordType union text
• packages/core/dist/governance/types.d.ts is a stable package build artifact for this purpose

Ledger golden shell script

The shell script previously compiled raw source files:

• packages/core/canonical/canonicalSerialize.ts
• packages/core/hashing/hashV2.ts
• packages/core/ledger/hashV2Ledger.ts

Dependency type:

• direct TypeScript compilation from raw source file paths into tests/selfcheck-out

Classification:

• SAFE_TO_REDIRECT_TO_DIST_SUBPATH

Reason:

• the golden test only needs runnable JS with the same relative module graph
• packages/core/dist already contains the needed JS artifacts
• copying the dist JS trio preserves the test harness shape without compiling raw source

New strategy

Governance consistency scripts

New path strategy:

1. resolve @kvary/core/package.json
2. derive package root from the resolved package path
3. read dist/governance/types.d.ts

This keeps the scripts package-boundary aware and removes direct dependency on repo source layout.

Ledger golden script

New path strategy:

1. ensure tests/selfcheck-out/{canonical,hashing,ledger} exists
2. copy these dist JS files:
   • packages/core/dist/canonical/canonicalSerialize.js
   • packages/core/dist/hashing/hashV2.js
   • packages/core/dist/ledger/hashV2Ledger.js
3. run the existing golden vector test unchanged

This keeps the test harness behavior intact while removing raw .ts compilation.

What changed

Changed files:

• verify-governance-consistency.ts
• verify-governance-consistency.js
• run-ledger-v2-golden.sh

Additional note on JS parity

The compiled JS governance-consistency script had an existing iterator-spread bug around matchAll().

That bug was fixed while migrating the path source:

• replaced fragile spread-helper usage with Array.from(...)

This does not alter script intent; it restores parity with the TypeScript variant.

Validation

Executed:

npm --prefix packages/core run build
npm exec -- tsx scripts/verify-governance-consistency.ts
npm exec -- node scripts/verify-governance-consistency.js
bash scripts/run-ledger-v2-golden.sh

Results:

• packages/core build succeeded
• TypeScript governance consistency script passed
• JavaScript governance consistency script passed
• ledger golden shell script passed

Observed warning:

• bash scripts/run-ledger-v2-golden.sh emits a Node warning about typeless package JSON when running copied ESM files from tests/selfcheck-out
• this is non-fatal
• the golden vector still passed

Deferred / not changed

Nothing else in this tooling cluster was changed.

No services, apps, or runtime entrypoints were touched.

Impact on future packages/core cleanup

This change narrows the remaining manual-verify surface.

What it unlocks:

• these three tooling files are no longer blockers for deleting packages/core/*.ts or packages/core/*.js source duplicates based on raw filesystem coupling

What still remains before a narrower safe-delete pass:

• any other manual-verify packages/core consumers outside this tooling cluster
• workspace resolution cases where TypeScript still lands on package source through node_modules/@kvary/core symlink behavior

Conclusion

This tooling cluster is now stabilized away from direct raw packages/core/*.ts filesystem reads.

That is a real cleanup unlock for the next packages/core manual-verify reduction pass.