spec: V15, typed contracts refactor and metaspecing

(Rolled with v15 wips) V15 work-in-progress progression and the final staged closure into one
  canonical ENGI V15 refactor / metaspec pass.

  This establishes V15 as the active canon and rewrites the root/demo metaspec
  around that canon instead of a transition-state mix of earlier spec generations.
  The root V15 spec set, information audit, notes, system parity matrix, demo
  spec, implementation matrix, README, host capability docs, and seeded state now
  describe the same source-of-truth architecture and completion posture.

  It also ratifies the V15 naming and domain-model cleanup that separates system
  implementation from demo usage. Realization-profile replaces lingering
  demonstration-profile residue, settlement/source-to-shares discriminants are
  made explicit, Profile A / Profile B semantics are aligned across docs and
  source, and the demo shell now speaks the same repo-supply -> depositing ->
  needing -> fit -> evaluation -> branch artifacts -> settlement -> policy
  language as the spec.

  The source tree is reorganized around canonical module boundaries rather than a
  single `src/engi-demo.js` reservoir. This rolls in the V15 seam closures for:
  - canonical enums/types and realization/settlement discriminants
  - surfaces, prompting, projections, proof/materialization, and run artifacts
  - need measurement / inference
  - evaluation / materialization orchestration
  - settlement / exact-accounting emission
  - demo-shell/public-state shaping

  With those seams landed, `src/engi-demo.js` is reduced to orchestration and
  cross-cutting composition, while the extracted canonical families own their core
  system definitions and artifact/proof shaping. The browser shell and seeded
  demo state are correspondingly aligned to the same canonical surfaces and
  profile distinctions.

  This also folds in the final native-JS type-hardening closure for the V15
  refactoring sub-focus. The repo keeps its source natively JavaScript, but now
  treats strict checked-JS as the hard compiler truth. That includes:
  - the TS-native canonical contract layer in `src/canonical/type-contracts.ts`
  - strict `tsconfig`/`npm run typecheck` governance
  - checked-JS coverage across canonical subsystem families
  - checked-JS coverage across `src/engi-demo.js`, `public/app.js`, `server.js`,
    and the retained helper modules in `src/`
  - checked-JS coverage across `test/core.test.js`, `test/api.test.js`, and
    `test/e2e.test.js`

  The final staged hardening adds explicit JSDoc contracts, safer DOM and server
  helpers, stronger prompt/proof/materialization/run-artifact contracts, tighter
  need-measurement and surface typing, clearer internal-vs-public state handling,
  and typed native-JS test harnesses for API/core/browser parity. The
  implementation matrix is updated to reflect that V15 now closes under a strict
  checked-JS posture, with future `.ts` conversion remaining optional follow-on
  work rather than a blocker to the current canon.

  In effect, this commit turns V15 from a large refactor plan into the actual
  canonical implementation/metaspec state: spec, source organization, naming,
  proof/settlement surfaces, demo boundary, and compiler-enforced type-hardening
  all now describe the same system.

  Verification for the rolled canon is green:
  - `npm run typecheck`
  - `npm test` (71/71, including browser e2e)

Author: geraldarthurdavis

engi-demo/SPEC_V15_IMPLEMENTATION_MATRIX.md

@@ -137,7 +137,7 @@ V15 should treat canonical source hardening as a staged process:
 | Area | Current expectation | V15 closure target | Gap judgment |
 |---|---|---|---|
 | JavaScript structural cleanup before TS hardening | landing pass complete: canonical builder families and demo-shell/public-state shaping now live outside `src/engi-demo.js` | cleaner pre-TypeScript system boundaries | closed for current V15 JS pass |
-| TypeScript compiler regime | active widening pass landed: `typescript` + `@types/node` installed, `tsconfig.json` added, `npm run typecheck` active, `src/canonical/type-contracts.ts` provides the first TS-native contract layer, and checked-JS now covers `src/realization-profile.js`, `src/settlement-structs.js`, `src/canonical/prompting.js`, `src/canonical/projections.js`, `src/canonical/proof-materialization.js`, `src/canonical/need-measurement.js`, `src/canonical/evaluation-materialization.js`, `src/canonical/settlement.js`, `src/demo-shell-state.js`, and `server.js` | expand the checked surface until the TS compiler governs the full canonical source graph | active |
+| TypeScript compiler regime | strict checked-JS hard-gate landed: `typescript` + `@types/node` installed, `tsconfig.json` now runs with `checkJs: true`, `npm run typecheck` passes across the active V15 source graph and native-JS test graph, `src/canonical/type-contracts.ts` provides the TS-native contract layer, and checked-JS now covers the canonical subsystem families, `src/engi-demo.js`, `public/app.js`, `src/demo-shell-state.js`, `server.js`, and `test/core.test.js` / `test/api.test.js` / `test/e2e.test.js` | preserve maximal type strength while staying native JS unless a later repo decision explicitly calls for `.ts` conversion | landed for active source and tests |
 | Strong enum/discriminant design | partial | rich closed-case typing where appropriate | medium |
 | Domain type composition | partial | stronger composed system structs with explicit role separation | medium |
 | Typed identifiers / roots / refs | mixed | role-specific typing to reduce invalid mixing | medium |
@@ -159,21 +159,23 @@ The remaining work before and during TypeScript is no longer another structural
 It is preserving the landed module boundaries while expressing them with stronger typed contracts, branded ids/roots/refs, discriminated unions, and runtime-decoded boundary inputs.
 The residual logic still living in `src/engi-demo.js` is primarily orchestration-local cross-cutting composition such as run assembly, identity/authz wiring, policy-release shaping, and proof-bundle coordination, rather than another monolithic subsystem reservoir that must be extracted before TypeScript.
 
-## Final V15 TypeScript implementation matrix
+## Final V15 type-hardening matrix
 
-The goal of the TypeScript phase is not a cosmetic extension rename.
-It is a maximal-strength typed implementation of the canonical ENGI system where the type system itself expresses more of:
+For this repo branch, V15 closes in native JavaScript under a strict checked-JS regime rather than forcing a cosmetic `.ts` rename across the tree.
+The goal of the type-hardening phase is therefore a maximal-strength typed implementation of the canonical ENGI system where the type system itself expresses more of:
 - closed-case subsystem truth,
 - role-specific ids/roots/refs,
 - canonical artifact family boundaries,
 - proof/measurement/settlement invariants,
 - and system-layer versus demo-layer separation.
 
+Native `.ts` conversion remains optional later work, not a blocker for V15 implementation doneness in the current repo posture.
+
 ### TypeScript hardening phases
 
 | Phase | Scope | Type-strength objective | Concrete implementation target | Closure signal |
 |---|---|---|---|---|
-| TS-0 Compiler regime | repository-wide TypeScript enablement | strict compiler truth with no weak-default posture | landed and widened: `tsconfig.json` carries strict NodeNext settings, `npm run typecheck` is active, `src/canonical/type-contracts.ts` provides the first TS-native canonical contract layer, and checked JS now includes all landed canonical subsystem families plus `src/demo-shell-state.js` and `server.js`; next step is extending the same regime to `src/engi-demo.js` and the browser shell source | TypeScript exists as a hard gate rather than an optional sidecar |
+| TS-0 Compiler regime | repository-wide TypeScript enablement for active implementation and parity tests | strict compiler truth with no weak-default posture | landed: `tsconfig.json` carries strict NodeNext settings with `checkJs: true`, `npm run typecheck` passes across `server.js`, `public/app.js`, `src/engi-demo.js`, all landed canonical subsystem families, `src/demo-shell-state.js`, the smaller retained implementation helpers in `src/`, and `test/core.test.js` / `test/api.test.js` / `test/e2e.test.js`; `src/canonical/type-contracts.ts` is the first TS-native canonical contract layer | TypeScript exists as a hard gate for active source and tests rather than an optional sidecar |
 | TS-1 Boundary freeze before conversion | the landed canonical JS module graph | ensure TS migration lands on stable subsystem boundaries instead of retyping a moving monolith | preserve the landed canonical families such as `src/canonical/need-measurement.ts`, `src/canonical/evaluation-materialization.ts`, `src/canonical/settlement.ts`, `src/canonical/projections.ts`, and `src/canonical/proof-materialization.ts`; only split further if typing pressure exposes a concrete design gain | `src/engi-demo.js` remains primarily orchestration/composition rather than regressing into mixed subsystem definition |
 | TS-2 Canonical primitive and identity families | ids, refs, roots, hashes, addresses, branch names, parser/evaluator ids, artifact paths | prevent invalid cross-role mixing at compile time | introduce branded/string-distinct types for ids and roots; examples: `NeedId`, `AssetId`, `InventoryEntryId`, `UnitHash`, `ContentRoot`, `BranchName`, `PolicyRef`, `ParserContractId`, `PromptOrEvaluatorId`, `LedgerAccountId`, `SignerAddress` | role-confusion bugs become type errors instead of stringly runtime accidents |
 | TS-3 Closed-case subsystem truth | enums, literal registries, discriminants, state cases | express system cases as exhaustive compile-time domains | convert current enum/JSDoc families to exported literal-union or enum-backed types with exhaustive switch handling; use `satisfies`/const-literal preservation for registries and stage catalogs | closed-case drift is prevented by exhaustiveness checking |
@@ -182,8 +184,8 @@ It is a maximal-strength typed implementation of the canonical ENGI system where
 | TS-6 Need measurement and inference typing | prompt contracts, parser contracts, inference proofs, recall channels, measurement traces | encode inference ownership and parse closure in types | active checked-JS pass landed: `src/canonical/need-measurement.js` now sits behind `// @ts-check` with typed scenario/parser/repo-analysis contracts and strict prompt-surface lookup closure; next step is converting the module and its dependencies from checked JS to native `.ts` without weakening those boundaries | the need-measurement boundary is fully typed and independently testable |
 | TS-7 Evaluation and materialization typing | ranking, verification, use tiers, asset-pack selection, branch artifact assembly | encode selection and materialization policy in discriminated result types | active checked-JS pass landed: `src/canonical/evaluation-materialization.js` now sits behind `// @ts-check`, with typed recall/ranking/verification/materialization boundaries and strict branch-artifact contract checking; next step is native `.ts` conversion and further discriminated typing for evaluator families and use-tier outcomes | the evaluation/materialization boundary is fully typed and independently testable |
 | TS-8 Proof and settlement maximal typing | source-to-shares, settlement participation, journal diff, accounting precision, proof bundle closure | turn accounting/proof invariants into explicit type-level structure | active checked-JS pass landed: `src/canonical/proof-materialization.js` and `src/canonical/settlement.js` now sit behind `// @ts-check`, with strict proof/materialization witness contracts and settlement/accounting interfaces tightened enough to keep `npm run typecheck` green; next step is native `.ts` conversion and stronger branded/value-family typing for basis points, shares, and ledger structures | settlement/proof structures are compile-time distinct instead of loosely numeric objects |
-| TS-9 Demo-shell and server typing | `server.js`, demo-shell/public-state shaping, browser app source | preserve demo UX while moving source-of-truth into typed modules | active checked-JS pass landed for `server.js` and `src/demo-shell-state.js`; next step is native `.ts` conversion for those files, then moving browser source-of-truth from hand-authored `public/app.js` to typed source compiled into `public/app.js` | system source becomes typed end-to-end instead of stopping at backend modules |
-| TS-10 Test and fixture typing | node tests, e2e harness, seeded fixtures | make parity proof participate in the type regime | convert core/API/e2e tests to TypeScript-aware execution or precompiled output; type seeded fixture/state builders and assertion helpers | tests catch both runtime and static-shape regressions |
+| TS-9 Demo-shell and server typing | `server.js`, demo-shell/public-state shaping, browser app source | preserve demo UX while moving source-of-truth into typed modules | landed in checked JS for the current repo posture: `server.js`, `src/demo-shell-state.js`, `src/engi-demo.js`, and `public/app.js` are all inside the active compiler gate and `npm run typecheck` stays green | active source is typed end-to-end instead of stopping at backend modules |
+| TS-10 Test and fixture typing | node tests, e2e harness, seeded fixtures | make parity proof participate in the type regime | landed in checked JS while staying native `.js`: `test/core.test.js`, `test/api.test.js`, and `test/e2e.test.js` now participate in the same strict compiler gate as the source graph and still pass under `npm test` | tests catch both runtime and static-shape regressions inside the active repo gate |
 | TS-11 Strictness ratchet and debt burn-down | final post-conversion hardening | eliminate weak escape hatches | forbid broad `any`; require documented/narrowed `unknown`; track and burn down temporary `@ts-expect-error` or compatibility shims; prefer exact return types for canonical builders | the final TS state is strong by default, not nominally converted |
 
 ### Type-strength design requirements for the TS phase
@@ -198,24 +200,24 @@ It is a maximal-strength typed implementation of the canonical ENGI system where
 | System-vs-demo separation | system-owned canonical types live in canonical modules; demo-shell projection/view types stay in demo-owned modules | preserves the V15 architecture at the type layer |
 | Runtime/schema parity | runtime validators and static types are kept aligned for persisted JSON and API boundaries | prevents static/runtime shape drift |
 
-### Recommended TypeScript migration order
+### Recommended type-hardening order
 
 1. Add compiler/build infrastructure and strict settings.
 2. Preserve the landed JS canonical boundaries as the TS migration surface; only split further when the type design clearly benefits.
-3. Convert canonical leaf modules first: enums/types, realization-profile, settlement-structs, prompting, projections, proof-materialization, surfaces, run-artifacts. The checked-JS hardening pass is already active across the first six of those.
+3. Convert canonical leaf modules first: enums/types, realization-profile, settlement-structs, prompting, projections, proof-materialization, surfaces, run-artifacts. The checked-JS hardening pass is now active across all of those except the enum/type declaration files themselves.
 4. Convert the landed canonical subsystem families next: need-measurement, evaluation-materialization, settlement. The checked-JS hardening pass is now active for all three.
 5. Convert demo-shell/public-state shaping and server boundary code. The checked-JS hardening pass is now active for `src/demo-shell-state.js` and `server.js`.
-6. Convert `src/engi-demo.js` last after its responsibilities stay narrowed to orchestration/composition. At this point it is the main remaining backend/source reservoir still outside the checked-JS widening pass, alongside the browser shell source.
-7. Convert tests and fixture helpers, then ratchet strictness and remove temporary compatibility shims.
+6. Keep `src/engi-demo.js`, `public/app.js`, and the parity test graph inside the strict checked-JS gate as the orchestration/browser boundary and proof harness remain stable.
+7. Ratchet strictness and burn down temporary compatibility annotations only where they no longer serve the native-JS checked path.
 
-### TypeScript completion condition for the V15 refactor sub-focus
+### Type-hardening completion condition for the V15 refactor sub-focus
 
-The TypeScript phase is complete for V15 when:
+The V15 type-hardening phase is complete when:
 1. the landed canonical subsystem boundaries are preserved through conversion,
-2. canonical modules and orchestration are converted to TypeScript,
+2. canonical modules and orchestration are strongly typed in the active repo posture,
 3. demo-shell and server source-of-truth are typed,
 4. ids/roots/refs/hashes are role-distinct where misuse risk exists,
 5. major artifact families and settlement/proof structures are discriminated and explicitly typed,
 6. persisted-state and API boundaries are decoded rather than trusted implicitly,
-7. tests run against the typed source or typed build output,
+7. tests participate in the strict compiler gate and run against the typed source,
 8. and the resulting codebase is strong-by-default rather than merely extension-renamed.