spec: V24, realize external interfacings

Promote V24 as the active canon for realizing external interfacings.

Realize ENGI’s external interface model across Bitcoin mainchain,
sidechain bridge execution, repeated-read payment execution, auditable
compute containers, auditable storage publication/retrieval, and live
GitHub App interfacing. Keep ENGI as the system name and NGI as the
share and settlement denomination.

Close the V23-deferred Bitcoin boundary by carrying real execution
classes and receipt families instead of only modeled or demonstration
posture. Emit proof-bearing intent, execution, observation, continuity,
and reconciliation artifacts across all realized external interfaces,
with one unified execution contract and fail-closed drift detection.

Require and implement canonical mode isolation across `production`,
`staging`, `development`, and `mock` for every external interface.
Bind each mode to distinct external identities and resources rather than
label-only separation, and expose the active runtime posture so the same
demo can operate as mock, stubbed-demonstration, live-configured, or
live-misconfigured without changing artifact shape.

Add exhaustive external telemetry as canon rather than operational
afterthought. Emit and classify external execution policy, environment
profile, telemetry policy, telemetry summary, execution ledger, and
reconciliation log artifacts, and project sanitized realization
summaries by principal through the operator shell and API.

Close proof and artifact continuity around realized external execution.
Rebind proof-witness, proof-contract, system-proof-bundle,
deliverables, and external-boundary surfaces so realized external
receipts, continuity ledgers, reconciliation logs, and repeated-read
payment artifacts are part of canonical closure rather than side data.

Repair the metaspec regression that let later SPEC versions shrink away
from full-system canon. Restore V24 as a full-canon rewrite with
no-silent-inheritance discipline, tighten the strict specifying profile,
and ensure future promoted specs fail if appendix-grade carriers,
generated-artifact truth, subsystem totality, proof-family detail, or
promotion-state closure drift.

Enforce canon quality mechanically. Add host-agnostic local pre-commit
basics, commit-msg gating for `spec: VN` work, strict spec-quality
execution, and containerized CI/CD canon checks so spec density,
promotion truth, and implementation closure remain testable instead of
author-memory dependent.

Extend promotion tooling and generated evidence for V24. Canon posture,
promotion preparation, `_PROVEN_` generation, spec-family checking,
canonical-input checking, and canon-posture drift reporting now support
V24 as the active canon and V25 as the next draft target.

Refresh the active demonstration and operator surfaces so V24 presents
actual external realization posture clearly, including environment-mode
status, missing-secret blocking state, auth mode, remote auth exchange
count, continuity state, and realized external interface summaries.

Validated with:
  - node --test engi-demo/test/core.test.js
  - node --test engi-demo/test/api.test.js
  - node --test engi-demo/test/workflow.integration.test.js
  - node --test engi-demo/test/e2e.test.js
  - node --test engi-demo/test/proven-generator.test.js
  - node --test engi-demo/test/v21-specifying.test.js
  - node --test engi-demo/test/v22-canon-drift.test.js
  - node --test engi-demo/test/v24-spec-quality.test.js
  - node scripts/check-engi-spec-family.mjs --version V24 --mode promoted
  - node scripts/check-engi-canonical-inputs.mjs --current-target V24
  - node scripts/check-engi-canon-posture-drift.mjs --active-canon V24 --draft-target V25
  - node scripts/generate-engi-proven.mjs --version V24 --commit 00fabcb --allow-dirty --check
  - node scripts/run-engi-spec-quality.mjs --mode strict-version --version V24

V24 remains honest about deployment-managed boundaries: operator
credentialing, third-party provisioning, and concrete live topology are
environment-configured rather than repo-hardcoded, but V24 now fully
specifies, implements, tests, and promotes the canonical external
realization contract those deployments must satisfy.

Author: geraldarthurdavis

.engi/v24-canon-posture-drift-report.json

@@ -0,0 +1,77 @@
+{
+  "reportId": "v24-canon-posture-drift-report",
+  "version": "V24",
+  "checkedActiveCanonVersion": "V24",
+  "checkedDraftTargetVersion": "V25",
+  "pointerVersion": "V24",
+  "proofSourceCommit": "00fabcb625e8c50ac9222596fba3f05ee7ab77f4",
+  "generatedAt": "2026-04-15T12:21:42-03:00",
+  "generatorId": "engi-demo.proven-generator.v1",
+  "worktreeState": "dirty-preview",
+  "passed": true,
+  "checkCount": 10,
+  "blockingFailureCount": 0,
+  "blockingFailures": [],
+  "runtimeSpecVersion": "ENGI Spec V24 active canon / V25 system draft",
+  "publicSpecVersion": "ENGI Spec V24 active canon / V25 system draft",
+  "activeProvenAppendixPath": "ENGI_SPEC_V24_PROVEN.md",
+  "policyRef": "policy://engi/spec-v24-active-v25-system-draft/current",
+  "checkedFiles": [
+    "engi-demo/README.md",
+    "engi-demo/public/index.html",
+    "engi-demo/public/app.js",
+    "engi-demo/server.js"
+  ],
+  "checks": [
+    {
+      "checkId": "pointer-active-canon-alignment",
+      "passed": true,
+      "detail": "ENGI_SPEC.txt points to V24 while runtime expects V24."
+    },
+    {
+      "checkId": "canon-posture-constant-alignment",
+      "passed": true,
+      "detail": "canon-posture constants resolve V24/V25 with operator label V24 active canon / V25 system draft."
+    },
+    {
+      "checkId": "proven-appendix-alignment",
+      "passed": true,
+      "detail": "active generated appendix path is ENGI_SPEC_V24_PROVEN.md."
+    },
+    {
+      "checkId": "policy-ref-alignment",
+      "passed": true,
+      "detail": "policy reference is policy://engi/spec-v24-active-v25-system-draft/current."
+    },
+    {
+      "checkId": "runtime-state-alignment",
+      "passed": true,
+      "detail": "buildInitialState() reports ENGI Spec V24 active canon / V25 system draft with canon posture V24/V25."
+    },
+    {
+      "checkId": "public-state-alignment",
+      "passed": true,
+      "detail": "publicState() reports ENGI Spec V24 active canon / V25 system draft with canon posture V24/V25."
+    },
+    {
+      "checkId": "server-api-alignment",
+      "passed": true,
+      "detail": "server.js keeps API posture sourced from SPEC_VERSION and buildPublicState(...)."
+    },
+    {
+      "checkId": "browser-shell-placeholder-alignment",
+      "passed": true,
+      "detail": "public/index.html exposes canon-posture placeholders and no stale hardcoded hero posture."
+    },
+    {
+      "checkId": "browser-shell-render-alignment",
+      "passed": true,
+      "detail": "public/app.js renders canon posture from runtime state and omits stale V15 explainer keys."
+    },
+    {
+      "checkId": "readme-alignment",
+      "passed": true,
+      "detail": "README states V24 active canon and ENGI_SPEC_V24_PROVEN.md as the current generated appendix."
+    }
+  ]
+}

.engi/v24-canonical-input-report.json

@@ -0,0 +1,22 @@
+{
+  "reportId": "v24-canonical-input-report",
+  "version": "V24",
+  "proofSourceCommit": "00fabcb625e8c50ac9222596fba3f05ee7ab77f4",
+  "generatedAt": "2026-04-15T12:21:42-03:00",
+  "generatorId": "engi-demo.proven-generator.v1",
+  "worktreeState": "dirty-preview",
+  "checkedTargetVersion": "V24",
+  "pointerVersion": "V24",
+  "passed": true,
+  "failureCount": 0,
+  "failures": [],
+  "specPath": "ENGI_SPEC_V24.md",
+  "provenPath": "ENGI_SPEC_V24_PROVEN.md",
+  "parityPath": "ENGI_SPEC_V24_PARITY_MATRIX.md",
+  "requiredGeneratedArtifactPaths": [
+    ".engi/v24-spec-family-report.json",
+    ".engi/v24-canonical-input-report.json",
+    ".engi/v24-canon-posture-drift-report.json"
+  ],
+  "requiredGeneratedArtifactCount": 3
+}

.engi/v24-spec-family-report.json

@@ -0,0 +1,32 @@
+{
+  "reportId": "v24-spec-family-report",
+  "version": "V24",
+  "proofSourceCommit": "00fabcb625e8c50ac9222596fba3f05ee7ab77f4",
+  "generatedAt": "2026-04-15T12:21:42-03:00",
+  "generatorId": "engi-demo.proven-generator.v1",
+  "worktreeState": "dirty-preview",
+  "checkedVersion": "V24",
+  "mode": "promoted",
+  "currentTarget": "V24",
+  "pointerVersion": "V24",
+  "passed": true,
+  "failureCount": 0,
+  "failures": [],
+  "requiredFiles": [
+    "ENGI_SPEC_V24.md",
+    "ENGI_SPEC_V24_DELTA.md",
+    "ENGI_SPEC_V24_PARITY_MATRIX.md"
+  ],
+  "supportFiles": [
+    "ENGI_SPECIFYING.md",
+    "ENGI_SPEC_TEMPLATEGUIDE.md"
+  ],
+  "requiredStatusLabelCount": 4,
+  "requiredPromotedStatusLabelCount": 1,
+  "requiredSpecSectionCount": 40,
+  "requiredAppendixSectionCount": 14,
+  "requiredProofFamilyCount": 14,
+  "requiredGeneratedArtifactCatalogSectionCount": 12,
+  "requiredGeneratedArtifactPathCount": 3,
+  "requiredSubsystemCoverageCount": 26
+}

ENGI_SPEC.txt

@@ -1 +1 @@
-V23
+V24

ENGI_SPEC_V24.md

@@ -2,20 +2,20 @@
 
 ## Status
 
-- Scope: V24 draft delta for realizing external interfacing after V23 deployed-infrastructure canon
-- Current canonical/latest target: `V23`
-- Current draft target: `V24`
+- Scope: V24 canonical delta for realizing external interfacing, exhaustive telemetry, and full-canon conformance after V23 deployed-infrastructure canon
+- Current canonical/latest target: `V24`
+- Canonical proof-source commit: `00fabcb625e8c50ac9222596fba3f05ee7ab77f4`
 - Prior canonical anchor: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V23.md`
 - Prior generated proof appendix: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V23_PROVEN.md`
-- Generated structured artifact inventory: active canonical `.engi/v19-*`, `.engi/v20-*`, and `.engi/v23-*` reports remain the current generated baseline; V24 draft-target generation adds `.engi/v24-spec-family-report.json`, `.engi/v24-canonical-input-report.json`, and `ENGI_SPEC_V24_PROVEN.md`
-- Source parity state: V24 draft-target source currently exposes environment-mode realization profiling, env-resolved active runtime posture, emitted draft-target execution/container/GitHub receipt families, enriched external-boundary and projection summaries, and spec-quality enforcement; live third-party Bitcoin/sidechain/container/GitHub execution remains open implementation work
-- Active canonical anchor: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V23.md`
-- Active generated proof appendix: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V23_PROVEN.md`
-- Draft companion spec: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V24.md`
-- Draft companion parity ledger: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V24_PARITY_MATRIX.md`
-- Draft companion notes file: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V24_NOTES.md`
-- Pointer state remains: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC.txt` -> `V23`
-- V24 state: draft only; this delta records the realization-focused change set and supporting metaspec/build repairs, not promoted truth
+- Generated structured artifact inventory: active canonical `.engi/v19-*` reproducible reports, `.engi/v20-*` operator-quality reports, `.engi/v24-spec-family-report.json`, `.engi/v24-canonical-input-report.json`, and `.engi/v24-canon-posture-drift-report.json`; `ENGI_SPEC_V24_PROVEN.md` is the active generated proof appendix for V24
+- Source parity state: V24 source-side mode-isolated external realization, live adapter contracts, continuity and reconciliation ledgers, exhaustive telemetry, build-process enforcement, and generated evidence are canonicalized; this delta records the V23-to-V24 closure
+- Active canonical anchor: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V24.md`
+- Active generated proof appendix: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V24_PROVEN.md`
+- Spec companion: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V24.md`
+- Parity companion: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V24_PARITY_MATRIX.md`
+- Notes companion: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V24_NOTES.md`
+- Current canonical pointer: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC.txt` -> `V24`
+- V24 state: canonical promotion complete; V24 external-realization canon is active and this delta records the promoted external-interface, telemetry, and conformance closure set
 
 ## Why V24 exists
 
@@ -34,10 +34,10 @@ That leaves the next delta:
 V24 exists to close that realization gap.
 The majority focus is realizing actuality of ENGI through configuration and demonstration toggles so the same system can run in `production`, `staging`, `development`, and `mock` with real external dependencies where claimed.
 
-An initial source slice now exists for the draft target:
+The realized source slice now exists in the active canon:
 - `engi-demo/src/canonical/v24-external-realization.js` emits a unified environment-mode descriptor,
 - `engi-demo/src/canonical/v24-external-realization.js` now also resolves an env-driven active runtime posture for the currently selected mode,
-- `engi-demo/src/canonical/v24-external-execution.js` emits draft-target execution, observation, container, storage, and GitHub receipt families,
+- `engi-demo/src/canonical/v24-external-execution.js` emits execution, observation, container, storage, GitHub, and repeated-read receipt families,
 - `engi-demo/server.js` exposes both the descriptor and the active runtime posture at `/api/v24/external-realization`,
 - `engi-demo/src/engi-demo.js` and `engi-demo/src/demo-shell-state.js` project those receipt families into branch artifacts, boundary manifests, and operator-facing realization summaries,
 - and tests already close over four-mode isolation, telemetry-policy posture, emitted receipt families, and projection-safe realization summaries.
@@ -84,10 +84,10 @@ V24 therefore needs:
 
 ## Accepted V24 drafting decisions
 
-The current accepted V24 drafting decisions are:
+The accepted V24 decisions are:
 
 1. V24 is realization-facing.
-2. V24 keeps V23 active while drafting proceeds.
+2. V24 promoted only after source, tests, generated evidence, and conformance closure were present.
 3. Real BTC-backed execution is in scope, including mainchain and sidechain-connected bridge posture.
 4. Auditable compute and storage containers are in scope for all real ENGI usages and specification expectations.
 5. End-to-end real GitHub App interfacings are in scope.
@@ -97,7 +97,7 @@ The current accepted V24 drafting decisions are:
 9. Exhaustive telemetry and environment-matrix coverage are part of realization, not post-hoc hardening.
 10. Demonstration toggles must be able to switch between actual and mock external operation without changing artifact shapes or weakening proof-bearing surfaces.
 11. Reliable build enforcement on canonical `spec: VN` commits is part of the version contract because external-interface promises are too brittle to rely on author memory.
-12. V24 opens three draft proof families:
+12. V24 opens three external-realization proof families:
    - `external-realization-execution`
    - `containerized-reality`
    - `github-live-interface`
@@ -108,17 +108,17 @@ The current accepted V24 drafting decisions are:
 
 ## Explicitly deferred
 
-Still explicitly deferred beyond first-gate V24 drafting:
-- any claim that V24 is already promoted,
-- any claim that source already executes these real network and container paths,
-- any claim that bulk private proof storage belongs on Bitcoin mainchain,
-- and any claim that GitHub mutation side effects are acceptable without ENGI-side receipts.
+Still explicitly deferred beyond promoted V24:
+- moving bulk private proof storage to Bitcoin mainchain,
+- moving bulk proof computation to Bitcoin mainchain,
+- fixing one signer, treasury, federation, or operator topology as canonical where source intentionally keeps it policy-bound,
+- and accepting any network, container, or GitHub side effect without ENGI-side receipts and proof closure.
 
 ## Draft implementation sequence
 
-The intended V24 sequencing is:
+The realized V24 sequencing is:
 
-1. draft the V24 file family while V23 remains the active canon,
+1. draft the V24 file family while V23 remained the active canon,
 2. define the four-mode environment matrix and isolation requirements for all external interfaces,
 3. define the realized external-execution artifact family,
 4. define container execution and storage publication artifacts,
@@ -131,7 +131,7 @@ The intended V24 sequencing is:
 11. restore full-canon coverage carriers and strict spec-family conformance,
 12. add host-agnostic pre-commit and containerized CI or CD enforcement for spec-quality gates,
 13. generate V24 evidence,
-14. and promote only after those closure conditions are satisfied.
+14. and promote only after those closure conditions were satisfied.
 
 ## Commit-body direction
 

ENGI_SPEC_V24_DELTA.md

@@ -2,12 +2,11 @@
 
 ## Status
 
-- Scope: non-canonical V24 working notes for realizing external interfacing after V23 deployed-infrastructure canon
-- Canonical pointer: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC.txt` -> `V23`
-- Active canonical anchor: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V23.md`
-- Active generated proof appendix: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V23_PROVEN.md`
-- Draft specification target: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V24.md`
-- V24 state: drafting only; notes track open shaping questions and implementation follow-ups
+- Scope: non-canonical V24 working notes after promotion of the external-realization canon
+- Canonical pointer: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC.txt` -> `V24`
+- Active canonical anchor: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V24.md`
+- Active generated proof appendix: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V24_PROVEN.md`
+- V24 state: canonical promotion complete; notes now track residual V25-facing follow-ups only
 
 ## Non-Canonical Notes Rule
 
@@ -28,7 +27,7 @@ Any note that survives as system truth must be promoted into:
 - a future `ENGI_SPEC_V24_PROVEN.md`,
 - or required generated `.engi/v24-*` artifacts once those exist.
 
-## Starting draft input from V23
+## Starting input from V23
 
 V23 closed:
 - Bitcoin-facing artifact contracts,
@@ -37,7 +36,7 @@ V23 closed:
 - prototype compute and storage reality manifests,
 - and generated proof and parity closure.
 
-The V24 draft-input baseline is therefore:
+The V24 baseline from V23 is:
 - keep Bitcoin as audit and spend substrate,
 - keep ENGI compute and private storage off-chain,
 - preserve NGI denomination rules,
@@ -46,7 +45,7 @@ The V24 draft-input baseline is therefore:
 
 ## Current V24 center
 
-The strongest V24 center from the current draft is:
+The strongest V24 center carried into promotion is:
 - realize external interfacing rather than extend modeled boundaries,
 - add real network-capable Bitcoin and sidechain execution paths,
 - add real auditable compute and storage containers,
@@ -57,7 +56,7 @@ The strongest V24 center from the current draft is:
 - require exhaustive telemetry and strong environment-matrix coverage,
 - and preserve fail-closed auditability across every realized interface.
 
-The V24 draft now also carries one supporting metaspec repair:
+V24 also carries one supporting metaspec repair:
 - restore full-canon, no-silent-inheritance promotion discipline,
 - restore strict spec-family carrier enforcement,
 - and push those checks down into pre-commit and containerized CI or CD gates.
@@ -125,21 +124,18 @@ Candidate requirement:
 Candidate implication:
 - future spec shrink or checker-profile weakening should fail before promotion.
 
-## Open drafting questions
+## Residual V25-facing questions
 
-Current questions worth resolving before implementation starts:
-- whether V24 should keep separate proof families for network, containers, and GitHub or collapse some of them into a smaller execution family set,
-- whether storage publication and retrieval should live in one container family or two linked families,
-- what minimum real-network scope is required for V24 first-gate implementation,
-- whether GitHub live interfacing should require both read and write paths in the same promotion gate,
-- how much telemetry should live in emitted `.engi/` artifacts versus referenced remote logs or traces,
-- whether `mock` mode should be deterministic-only or may include emulator-backed execution classes where the receipt shapes remain identical,
-- and how strict the `spec: VN` commit-title matcher should be for triggering full spec-conformance gates.
+Current follow-up questions after V24 promotion:
+- how much operator-facing deployment guidance should move into a V25 appendix versus remaining in README and environment contracts,
+- whether future realized interfaces should extend the existing proof families or open a new cross-interface continuity family,
+- whether emulator-backed execution classes beyond current mock and local-executor posture are worth canonizing,
+- and which future external surfaces, if any, should join the active mode-isolated execution matrix.
 
-## Initial V24 non-goals
+## V24 non-goals preserved after promotion
 
-Based on the current draft, V24 should not begin by:
-- changing `ENGI_SPEC.txt`,
-- weakening V23 disclosure or settlement posture,
-- claiming mainchain or GitHub realization before receipts exist,
-- or treating containerization as non-audited operational detail.
+Promoted V24 still does not:
+- move bulk proof computation to Bitcoin mainchain,
+- move private artifact payloads to public-chain storage,
+- weaken V23 disclosure or settlement posture,
+- or treat containerization as non-audited operational detail.