Core subpath consumer validation report

Date: 2026-03-06

Scope

Safe validation and normalization pass for @kvary/core/* consumers.

This step does not delete any packages/core/*.js files.

Inventory

| Cluster | Consumer file | Import path | Imported symbols | Runtime context | Risk level | Classification | | --- | --- | --- | --- | --- | --- | --- | | governance | apps/web/src/app/[locale]/(portal)/kes/HashVerificationPanel.tsx | @kvary/core/governance | IntegrityStatus, KESState | web | medium | NEEDS_EXPORT_ADJUSTMENT | | governance | apps/web/src/app/[locale]/(portal)/kes/SigningSlotPanel.tsx | @kvary/core/governance | KESState | web | medium | NEEDS_EXPORT_ADJUSTMENT | | governance | apps/web/src/app/[locale]/(portal)/kes/page.tsx | @kvary/core/governance | governance helpers/types | web | medium | NEEDS_EXPORT_ADJUSTMENT | | governance | apps/web/src/app/[locale]/[country]/(portal)/kes/HashVerificationPanel.tsx | @kvary/core/governance | IntegrityStatus, KESState | web | medium | NEEDS_EXPORT_ADJUSTMENT | | governance | apps/web/src/app/[locale]/[country]/(portal)/kes/SigningSlotPanel.tsx | @kvary/core/governance | KESState | web | medium | NEEDS_EXPORT_ADJUSTMENT | | governance | apps/web/src/app/[locale]/[country]/(portal)/kes/page.tsx | @kvary/core/governance | governance helpers/types | web | medium | NEEDS_EXPORT_ADJUSTMENT | | governance | services/api/src/tenders/engine.ts | @kvary/core/governance/appendGovernanceRecord, @kvary/core/governance/types | appendGovernanceRecord, GovernanceRecordV1 | service | low | NEEDS_EXPORT_ADJUSTMENT | | governance | services/api/src/auctions/engine.ts | @kvary/core/governance/appendGovernanceRecord, @kvary/core/governance/types | appendGovernanceRecord, GovernanceRecordV1 | service | low | NEEDS_EXPORT_ADJUSTMENT | | governance | services/api/src/governance/buildSubjectSnapshot.ts | @kvary/core/governance/types | GovernanceRecordV1 | service | low | NEEDS_EXPORT_ADJUSTMENT | | governance | services/api/src/state/inMemoryLedger.ts | @kvary/core/governance/types | GovernanceRecordV1 | service | low | NEEDS_EXPORT_ADJUSTMENT | | governance | services/api/src/auctions/ledger.ts | @kvary/core/governance/types | GovernanceRecordV1 | service | low | NEEDS_EXPORT_ADJUSTMENT | | governance | services/api/src/auctions/rebuildSnapshot.ts | @kvary/core/governance/types | GovernanceRecordV1 | service | low | NEEDS_EXPORT_ADJUSTMENT | | governance | services/api/src/auctions/snapshot.ts | @kvary/core/governance/types | GovernanceRecordV1 | service | low | NEEDS_EXPORT_ADJUSTMENT | | governance | services/api/src/tenders/ledger.ts | @kvary/core/governance/types | GovernanceRecordV1 | service | low | NEEDS_EXPORT_ADJUSTMENT | | governance | services/api/src/tenders/snapshot.ts | @kvary/core/governance/types | GovernanceRecordV1 | service | low | NEEDS_EXPORT_ADJUSTMENT | | governance | tests/governance/governance.replay-determinism.test.ts | raw ../../packages/core/... | appendGovernanceRecord, verifyFullGovernanceIntegrity, types | test | low | SAFE_TO_NORMALIZE | | governance | tests/governance/governance.replay-determinism.test.js | raw ../../packages/core/... | appendGovernanceRecord, verifyFullGovernanceIntegrity | test | medium | SAFE_TO_NORMALIZE | | ledger | services/api/src/tenders/engine.ts | @kvary/core/ledger/appendLedgerEntry, @kvary/core/ledger/types | appendLedgerEntry, LedgerEntry | service | low | NEEDS_EXPORT_ADJUSTMENT | | ledger | services/api/src/tenders/snapshot.ts | @kvary/core/ledger/types | LedgerEntry | service | low | NEEDS_EXPORT_ADJUSTMENT | | ledger | services/api/src/auctions/engine.ts | @kvary/core/ledger/types | LedgerEntry | service | low | NEEDS_EXPORT_ADJUSTMENT | | ledger | services/api/src/auctions/snapshot.ts | @kvary/core/ledger/types | LedgerEntry | service | low | NEEDS_EXPORT_ADJUSTMENT | | ledger | services/api/src/auctions/rebuildSnapshot.ts | @kvary/core/ledger/types | LedgerEntry | service | low | NEEDS_EXPORT_ADJUSTMENT | | ledger | services/api/src/governance/buildSubjectSnapshot.ts | @kvary/core/ledger/types | LedgerEntry | service | low | NEEDS_EXPORT_ADJUSTMENT | | ledger | services/api/src/state/inMemoryLedger.ts | @kvary/core/ledger/types | LedgerEntry | service | low | NEEDS_EXPORT_ADJUSTMENT | | ledger | tests/governance/governance.replay-determinism.test.ts | raw ../../packages/core/ledger/types | LedgerEntry | test | low | SAFE_TO_NORMALIZE | | ledger | scripts/run-ledger-v2-golden.sh | raw packages/core/*.ts paths | direct file compile targets | script | high | MANUAL_VERIFY_FIRST | | kes | apps/web/src/app/[locale]/(portal)/kes/page.tsx | @kvary/core/governance | KES governance data | web | medium | NEEDS_EXPORT_ADJUSTMENT | | kes | apps/web/src/app/[locale]/[country]/(portal)/kes/page.tsx | @kvary/core/governance | KES governance data | web | medium | NEEDS_EXPORT_ADJUSTMENT | | kes | services/api/src/routes/kes.ts | @kvary/core/kes/appendKesProposeVersion, @kvary/core/kes/appendKesRatifyVersion, @kvary/core/kes/types | KES appenders/types | service | low | NEEDS_EXPORT_ADJUSTMENT | | kes | services/api/src/adapters/kesInput.ts | @kvary/core/kes/types | KesProposeVersionInput | service | low | NEEDS_EXPORT_ADJUSTMENT | | canonical-hashing | services/api/src/tenders/engine.ts | @kvary/core/canonical/canonicalSerialize, @kvary/core/hashing/stableHash, @kvary/core/immutability/toSafeJson | canonical/hash/immutability helpers | service | low | NEEDS_EXPORT_ADJUSTMENT | | canonical-hashing | scripts/golden.ts | raw ../packages/core/... | canonicalSerialize, stableHash | script | low | SAFE_TO_NORMALIZE | | canonical-hashing | scripts/golden.js | raw ../packages/core/... | canonicalSerialize, stableHash | script | low | SAFE_TO_NORMALIZE | | config-alias | apps/web/tsconfig.json | raw ../../packages/core/* | TS path alias | web build config | high | MANUAL_VERIFY_FIRST | | config-alias | apps/web/next.config.js | alias/transpile for @kvary/core workspace root | webpack/Next alias | web build config | high | MANUAL_VERIFY_FIRST | | file-inspection | scripts/verify-governance-consistency.ts | raw packages/core/governance/types.ts | filesystem path to source file | script | high | MANUAL_VERIFY_FIRST | | file-inspection | scripts/verify-governance-consistency.js | raw packages/core/governance/types.ts | filesystem path to source file | script | high | MANUAL_VERIFY_FIRST |

What changed

1. Minimal package exports added

Added explicit exports entries in packages/core/package.json for the subpaths already used by live code:

• .
• ./governance
• ./governance/appendGovernanceRecord
• ./governance/types
• ./governance/verifyFullGovernanceIntegrity
• ./ledger/appendLedgerEntry
• ./ledger/types
• ./canonical/canonicalSerialize
• ./hashing/stableHash
• ./immutability/toSafeJson
• ./kes/appendKesProposeVersion
• ./kes/appendKesRatifyVersion
• ./kes/types

Reason:

• plain Node resolution for @kvary/core/governance and @kvary/core/governance/types was failing before this step
• current consumers were relying on workspace aliasing or internal layout rather than an explicit package surface

2. Safe raw-path normalization applied

Normalized these files away from raw packages/core/... imports:

• scripts/golden.ts
• scripts/golden.js
• tests/governance/governance.replay-determinism.test.ts
• tests/governance/governance.replay-determinism.test.js

New import style:

• @kvary/core/canonical/canonicalSerialize
• @kvary/core/hashing/stableHash
• @kvary/core/governance/appendGovernanceRecord
• @kvary/core/governance/verifyFullGovernanceIntegrity
• @kvary/core/governance/types
• @kvary/core/ledger/types

Validation

Build/package validation

Executed:

npm --prefix packages/core run build
npm exec -- node -e "import('@kvary/core/governance')..."
npm exec -- node -e "require('@kvary/core/governance/appendGovernanceRecord')..."

Results:

• packages/core build succeeded
• ESM import of @kvary/core/governance succeeded
• require() resolution succeeded for all newly exported subpaths:
  • @kvary/core/governance/appendGovernanceRecord
  • @kvary/core/governance/verifyFullGovernanceIntegrity
  • @kvary/core/governance/types
  • @kvary/core/ledger/types
  • @kvary/core/canonical/canonicalSerialize
  • @kvary/core/hashing/stableHash
  • @kvary/core/immutability/toSafeJson
  • @kvary/core/kes/appendKesProposeVersion
  • @kvary/core/kes/appendKesRatifyVersion
  • @kvary/core/kes/types

Normalized consumer validation

Executed:

npm exec -- tsx scripts/golden.ts
npm exec -- node scripts/golden.js
npm exec -- tsx --test tests/governance/governance.replay-determinism.test.ts
npm exec -- node --test tests/governance/governance.replay-determinism.test.js

Results:

• scripts/golden.ts passed
• scripts/golden.js passed
• tests/governance/governance.replay-determinism.test.ts resolved imports correctly, but the test itself failed with an application-level assertion: Ledger chain invalid: payloadHash mismatch
• tests/governance/governance.replay-determinism.test.js resolved package imports, but the test still fails due existing CommonJS node:test wrapper behavior: TypeError: (0 , node_test_1.default) is not a function

These two test failures are not package-resolution regressions introduced by this change.

Deferred clusters

Left unchanged on purpose:

1. apps/web/tsconfig.json

   • still maps @kvary/core/* to raw workspace source paths
   • high-risk build/runtime behavior change if touched

2. apps/web/next.config.js

   • still aliases @kvary/core to workspace root
   • high-risk Next bundling/runtime boundary

3. scripts/verify-governance-consistency.ts

4. scripts/verify-governance-consistency.js

   • these read the source file packages/core/governance/types.ts directly
   • they are source-inspection tools, not package consumers in the normal sense

5. scripts/run-ledger-v2-golden.sh

   • intentionally compiles specific packages/core/*.ts source files by filesystem path
   • should be handled as a separate tooling migration, not mixed with package-consumer stabilization

Recommended next cleanup candidates

After this step, the next low-risk candidate set is:

1. service-side @kvary/core/* consumers already on stable package subpaths

   • mostly covered now by explicit exports
   • can be revalidated once app/web aliasing is addressed

2. tooling cluster migration

   • scripts/verify-governance-consistency.*
   • scripts/run-ledger-v2-golden.sh

3. web alias/config migration

   • apps/web/tsconfig.json
   • apps/web/next.config.js

Only after those clusters are validated should another strict-delete pass for packages/core/*.js be considered.