magenta-canon 0.1.1 → 0.1.2

package/docs/NPM_PACKAGING.md

@@ -67,7 +67,7 @@ verifier behavior.
 ## What ships in the tarball
 
 Controlled by the `files` allowlist in `package.json`. Current contents
-(`magenta-canon-0.1.1.tgz` — 75 files, ~210 KB packed, ~849 KB unpacked):
+(`magenta-canon-0.1.2.tgz` — 77 files, ~215 KB packed, ~870 KB unpacked):
 
 | Path | Why |
 |---|---|
@@ -78,6 +78,7 @@ Controlled by the `files` allowlist in `package.json`. Current contents
 | `examples/` | the demo gateway config + the minimal downstream MCP server |
 | `tsconfig.json` | required so `tsx` resolves the `@shared/*` path alias at runtime |
 | `docs/MAGENTA_VERIFICATION_SPEC.md`, `MCP_GATEWAY.md`, `SECURITY_MODEL.md`, `NPM_PACKAGING.md` | the spec + the docs a CLI user needs |
+| `public/canon/schemas/constitutional-spine.schema.json`, `public/canon/spine/constitutional-spine.v1.json` | the **only** two `public/` files shipped — runtime assets the control plane resolves at `process.cwd()/public/canon/...` to serve `/api/canon/spine`. Omitting them left the package internally inconsistent (referenced but not shipped) and surfaced an `ENOENT` in the control-plane log on a packaged install (0.1.1). The rest of `public/` (website, banner, sitemap) stays excluded. |
 | `README.md`, `LICENSE` | always |
 
 Runtime dependency added for packaging: **`tsx`** (moved from devDependencies to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magenta-canon",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "license": "Apache-2.0",
   "description": "A verifiable MCP accountability gateway for AI-agent tool calls: allows authorized calls, blocks unauthorized calls, records both, and produces cryptographic evidence anyone can verify.",
@@ -41,6 +41,8 @@
     "docs/MCP_GATEWAY.md",
     "docs/SECURITY_MODEL.md",
     "docs/NPM_PACKAGING.md",
+    "public/canon/schemas/constitutional-spine.schema.json",
+    "public/canon/spine/constitutional-spine.v1.json",
     "README.md",
     "LICENSE",
     "!**/*.test.ts",

package/public/canon/schemas/constitutional-spine.schema.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://themagentacanon.com/canon/schemas/constitutional-spine.schema.json",
+  "title": "Constitutional Spine Declaration Artifact (v1)",
+  "description": "Schema for the read-only declarative Constitutional Spine artifact. Validates the enumeration of candidate constitutional invariants with their five-field metadata (purpose, protected surface, drift risk, enforcement posture, severity) plus implementation status. Conformance to this schema does not confer enforcement; the artifact describes, it does not enact.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "artifact_version",
+    "artifact_id",
+    "generated_at_source",
+    "authority_status",
+    "adoption_status",
+    "enforceability_notice",
+    "status",
+    "enforcement_posture_global",
+    "source_design",
+    "non_goals",
+    "invariants"
+  ],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schema_version": { "type": "string", "const": "constitutional-spine/v1" },
+    "artifact_version": { "type": "string", "const": "v1" },
+    "artifact_id": { "type": "string", "minLength": 1 },
+    "version": { "type": "string", "description": "Artifact version identifier alias (e.g. v1)." },
+    "generated_at_source": { "type": "string", "minLength": 1 },
+    "source_design": { "type": "string", "minLength": 1 },
+    "source_section": { "type": "string" },
+    "description": { "type": "string" },
+    "authority_status": { "type": "string", "const": "non_authoritative" },
+    "adoption_status": { "type": "string", "const": "candidate_only" },
+    "status": { "type": "string", "enum": ["declared", "promoted"] },
+    "enforcement_posture_global": { "type": "string", "enum": ["non-enforcing", "enforcing"] },
+    "enforceability_notice": { "type": "string", "minLength": 1 },
+    "promotion_policy": { "type": "string" },
+    "severity_legend": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["advisory", "freeze"],
+      "properties": {
+        "advisory": { "type": "string" },
+        "freeze": { "type": "string" }
+      }
+    },
+    "implementation_status_legend": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["unimplemented", "partially-implemented", "implemented", "enforced"],
+      "properties": {
+        "unimplemented": { "type": "string" },
+        "partially-implemented": { "type": "string" },
+        "implemented": { "type": "string" },
+        "enforced": { "type": "string" }
+      }
+    },
+    "non_goals": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "invariants": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 50,
+      "items": { "$ref": "#/$defs/invariant" }
+    }
+  },
+  "$defs": {
+    "invariant": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "name",
+        "purpose",
+        "protected_surface",
+        "drift_risk",
+        "enforcement_posture",
+        "severity",
+        "implementation_status",
+        "implementationStatus",
+        "authority_status",
+        "adoption_status",
+        "caveat"
+      ],
+      "properties": {
+        "id": { "type": "string", "pattern": "^I-[0-9]+$" },
+        "name": { "type": "string", "minLength": 1 },
+        "purpose": { "type": "string", "minLength": 1 },
+        "protected_surface": { "type": "string", "minLength": 1 },
+        "drift_risk": { "type": "string", "minLength": 1 },
+        "enforcement_posture": { "type": "string", "minLength": 1 },
+        "severity": { "type": "string", "enum": ["advisory", "freeze"] },
+        "implementation_status": {
+          "type": "string",
+          "enum": ["unimplemented", "partially_implemented", "implemented", "enforced"],
+          "description": "Snake_case rendering of implementation status (HEAD-compatible)."
+        },
+        "implementationStatus": {
+          "type": "string",
+          "enum": ["unimplemented", "partially-implemented", "implemented", "enforced"],
+          "description": "camelCase rendering of implementation status (task-spec literal). Mirrors implementation_status."
+        },
+        "authority_status": { "type": "string", "const": "non_authoritative" },
+        "adoption_status": { "type": "string", "const": "candidate_only" },
+        "caveat": { "type": "string", "minLength": 1 },
+        "implementation_notes": { "type": "string" }
+      }
+    }
+  }
+}

package/public/canon/spine/constitutional-spine.v1.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "https://themagentacanon.com/canon/schemas/constitutional-spine.schema.json",
+  "schema_version": "constitutional-spine/v1",
+  "artifact_version": "v1",
+  "version": "v1",
+  "artifact_id": "constitutional-spine.v1",
+  "generated_at_source": "reports/magenta-canon-north-star-constitutional-field-design.md#section-6",
+  "source_design": "reports/magenta-canon-north-star-constitutional-field-design.md",
+  "source_section": "§6 (invariants), §12 (next-phase scope)",
+  "description": "Read-only declarative enumeration of candidate constitutional invariants for Magenta Canon. This artifact describes; it does not enforce. Promotion of any invariant to load-bearing status requires a separate, explicit governance event with evidence bundle.",
+  "authority_status": "non_authoritative",
+  "adoption_status": "candidate_only",
+  "status": "declared",
+  "enforcement_posture_global": "non-enforcing",
+  "enforceability_notice": "This artifact is a declaration only. It is not enforceable. No invariant listed here may be cited as binding on any actor, layer, or decision until a future, explicit governance event promotes it through the normal Magenta Canon authority process. Reading this artifact creates no authority and confers no permission.",
+  "promotion_policy": "Promotion of any invariant from declared to enforced requires a separate governance event, an evidence bundle, and a signed authority binding proof. This artifact's existence does not constitute promotion.",
+  "severity_legend": {
+    "advisory": "Surface only; no execution behavior change.",
+    "freeze": "When promoted, would halt mutating operations within the protected surface."
+  },
+  "implementation_status_legend": {
+    "unimplemented": "No code surface yet enforces or even structurally represents this invariant.",
+    "partially-implemented": "Some code paths approximate the invariant; coverage is incomplete or relies on call-site discipline rather than structural enforcement.",
+    "implemented": "Code surface exists and consistently honors the invariant in normal operation, but the invariant has not been promoted to a freeze condition.",
+    "enforced": "Invariant is promoted to a freeze condition: violations halt mutating operations within the protected surface."
+  },
+  "non_goals": [
+    "This artifact does not enforce any invariant.",
+    "This artifact does not modify Gravity Kernel.",
+    "This artifact does not change CEAL.",
+    "This artifact does not create authority.",
+    "This artifact does not write to any ledger.",
+    "This artifact does not influence eligibility decisions.",
+    "No write endpoints for the spine.",
+    "No visualization surface.",
+    "No new drift-detection signals.",
+    "No claim that the artifact is enforceable until a subsequent governance event explicitly promotes it."
+  ],
+  "invariants": [
+    {
+      "id": "I-1",
+      "name": "Evidence Outranks Assertion",
+      "purpose": "No claim may influence a judgment more strongly than its evidence supports.",
+      "protected_surface": "Eligibility computation, behavioral vectors, proposal intake, AI-generated content surfaces.",
+      "drift_risk": "Confidence inflation; assertions promoted to facts via repetition.",
+      "enforcement_posture": "Each input to a judgment carries an evidence-grade tag; ungraded inputs are rejected from ETDP bundles.",
+      "severity": "freeze",
+      "implementation_status": "unimplemented",
+      "implementationStatus": "unimplemented",
+      "authority_status": "non_authoritative",
+      "adoption_status": "candidate_only",
+      "caveat": "Evidence-grade tagging is not uniformly applied across all proposal intake surfaces today; this invariant is aspirational pending a governance event.",
+      "implementation_notes": "No evidence-grade tagging schema exists on inputs to eligibility or ETDP bundles today."
+    },
+    {
+      "id": "I-2",
+      "name": "Provenance Must Remain Preservable",
+      "purpose": "Every state-affecting datum must be traceable to its origin receipt.",
+      "protected_surface": "Receipt ledger, witnessed mutations, evidence bundles, public verifier surfaces.",
+      "drift_risk": "Optimizations that strip provenance for performance.",
+      "enforcement_posture": "Witnessed-mutation receipts mandatory; unsigned mutations rejected when trust is configured.",
+      "severity": "freeze",
+      "implementation_status": "implemented",
+      "implementationStatus": "implemented",
+      "authority_status": "non_authoritative",
+      "adoption_status": "candidate_only",
+      "caveat": "Implemented via witnessedMutation/witnessedTrustMutation in server/routes.ts; not promoted to enforced status because this declaration artifact does not itself enforce.",
+      "implementation_notes": "witnessedMutation / witnessedTrustMutation in server/routes.ts wrap mutations in snapshot→mutate→receipt→rollback; no mutation persists without a signed receipt when trust is configured."
+    },
+    {
+      "id": "I-3",
+      "name": "Uncertainty Must Remain Representable",
+      "purpose": "The system must never collapse a probabilistic claim into a binary one without an explicit governance event.",
+      "protected_surface": "All eligibility surfaces, AI-answer endpoints, dashboards.",
+      "drift_risk": "Operational simplification (humans/agents prefer binary answers; the system is tempted to oblige).",
+      "enforcement_posture": "Probabilistic outputs carry confidence bands through derivation chains; collapse requires a logged promotion event.",
+      "severity": "advisory",
+      "implementation_status": "unimplemented",
+      "implementationStatus": "unimplemented",
+      "authority_status": "non_authoritative",
+      "adoption_status": "candidate_only",
+      "caveat": "No confidence-band propagation exists today across AI-answer or eligibility surfaces; severity per §6 is advisory at low strain (and would escalate to freeze only on silent collapse).",
+      "implementation_notes": "No confidence-band propagation exists across endpoints; eligibility is intentionally binary by design (see governance.invariants in system.identity.json)."
+    },
+    {
+      "id": "I-4",
+      "name": "Confidence Must Match Verification",
+      "purpose": "Stated confidence may not exceed the strength of underlying verification.",
+      "protected_surface": "AI-answer surfaces, drift-detection outputs, behavioral vector reports.",
+      "drift_risk": "Verbal confidence inflation; cosmetic certainty.",
+      "enforcement_posture": "Confidence-to-verification ratio computed; mismatched outputs annotated with explicit caveat or refused.",
+      "severity": "advisory",
+      "implementation_status": "unimplemented",
+      "implementationStatus": "unimplemented",
+      "authority_status": "non_authoritative",
+      "adoption_status": "candidate_only",
+      "caveat": "No confidence-to-verification ratio is computed today.",
+      "implementation_notes": "No confidence-to-verification ratio is computed on AI-answer or drift outputs."
+    },
+    {
+      "id": "I-5",
+      "name": "Advisory Systems May Not Self-Promote",
+      "purpose": "Memory and evaluation layers (Brain Hub, VERN, precedent memory) may inform; they may not authorize.",
+      "protected_surface": "All authorization surfaces (capability grants, baseline commits, policy publishes).",
+      "drift_risk": "Pattern-of-use creeping from \"informs\" into \"approves\" via UI defaults or implicit acceptance.",
+      "enforcement_posture": "Authorization events require an explicit authority binding proof; advisory inputs are visible but never sufficient.",
+      "severity": "freeze",
+      "implementation_status": "partially_implemented",
+      "implementationStatus": "partially-implemented",
+      "authority_status": "non_authoritative",
+      "adoption_status": "candidate_only",
+      "caveat": "Authority binding proofs are required on capability mutations; precedent and behavioral surfaces are structurally advisory in code, but no surface audit verifies absence of decision-shaped advisory output.",
+      "implementation_notes": "Authorization endpoints require sovereign envelopes (server/sovereign-auth.ts); advisory layers (precedent-memory, behavioral-vector) cannot directly authorize. No formal self-promotion detector audits surface styling."
+    },
+    {
+      "id": "I-6",
+      "name": "CEAL Cannot Be Bypassed",
+      "purpose": "Bounded execution authority is the only path to side-effecting operations; no parallel path may exist.",
+      "protected_surface": "All execution surfaces.",
+      "drift_risk": "\"Quick path\" optimizations that skip CEAL for trusted callers.",
+      "enforcement_posture": "Gravity Kernel rejects mutations lacking a CEAL grant in their evidence bundle.",
+      "severity": "freeze",
+      "implementation_status": "partially_implemented",
+      "implementationStatus": "partially-implemented",
+      "authority_status": "non_authoritative",
+      "adoption_status": "candidate_only",
+      "caveat": "CEAL and Gravity Kernel are external to this repository. Magenta Canon does not currently verify CEAL grants on incoming mutations; proposal containment provides the closest internal analogue.",
+      "implementation_notes": "Proposal containment (server/proposal-containment.ts) requires proposal → simulation → eligibility → binding before execution. Gravity Kernel as described in the design is not implemented inside this repository, so CEAL-grant enforcement is not yet structurally complete."
+    },
+    {
+      "id": "I-7",
+      "name": "Governance Outranks Optimization",
+      "purpose": "When a governance constraint and an optimization metric conflict, governance wins.",
+      "protected_surface": "Eligibility computation, freeze conditions, change-management surfaces.",
+      "drift_risk": "Subtle refactors that re-order checks so optimization runs first and short-circuits governance.",
+      "enforcement_posture": "Governance checks are structurally first in eligibility evaluation; ordering is itself governance-protected.",
+      "severity": "freeze",
+      "implementation_status": "partially_implemented",
+      "implementationStatus": "partially-implemented",
+      "authority_status": "non_authoritative",
+      "adoption_status": "candidate_only",
+      "caveat": "Eligibility evaluation in proposal-containment runs governance checks before precedent influence today, but the ordering is not protected by a build-time invariant test.",
+      "implementation_notes": "Governance-first ordering is honored by call-site discipline in server/routes.ts (e.g., sovereign auth and capability checks precede any optimization), but ordering is not itself a governance-protected, structurally enforced invariant."
+    },
+    {
+      "id": "I-8",
+      "name": "Memory Cannot Silently Mutate Authority",
+      "purpose": "No precedent or behavioral vector may modify an authority grant without an explicit governance event.",
+      "protected_surface": "Authority topology, capability grants, delegation edges.",
+      "drift_risk": "\"Auto-renewal\" or \"auto-extension\" features added to make operations smoother.",
+      "enforcement_posture": "All authority mutations require explicit, signed governance envelopes; no read-derived mutation.",
+      "severity": "freeze",
+      "implementation_status": "implemented",
+      "implementationStatus": "implemented",
+      "authority_status": "non_authoritative",
+      "adoption_status": "candidate_only",
+      "caveat": "Authority mutations in authority-containment.ts and authority-topology.ts require explicit grant calls; no precedent or behavioral pathway can mutate authority records. Not promoted to enforced because this artifact does not enforce.",
+      "implementation_notes": "Capability grants and supersessions require sovereign envelopes; capability supersession cascades irreversibly. Precedent memory and behavioral vectors are read-only with respect to authority topology."
+    },
+    {
+      "id": "I-9",
+      "name": "Witness Lineage Cannot Be Severed",
+      "purpose": "The receipt chain must remain continuous; gaps are themselves invariant violations.",
+      "protected_surface": "Execution receipt ledger, ETDP proofs, evidence bundles.",
+      "drift_risk": "Pruning, deduplication, or \"compaction\" optimizations that lose chain links.",
+      "enforcement_posture": "Hash-chain continuity verified on every ETDP issuance; breaks halt issuance.",
+      "severity": "freeze",
+      "implementation_status": "implemented",
+      "implementationStatus": "implemented",
+      "authority_status": "non_authoritative",
+      "adoption_status": "candidate_only",
+      "caveat": "Hash-chain continuity is verified in execution-receipts.ts and economic-trust.ts (verifyProofChain). Note: receipt ledger is currently in-memory and ephemeral across restarts, which is a separate durability concern from chain continuity.",
+      "implementation_notes": "server/execution-receipts.ts maintains a hash-chained, append-only receipt ledger; ETDP proof issuance (server/economic-trust.ts) verifies replayability."
+    },
+    {
+      "id": "I-10",
+      "name": "No Layer May Escalate Autonomy Without Explicit Governance Approval",
+      "purpose": "Self-modification of authority, scope, or eligibility criteria requires a human-governed event.",
+      "protected_surface": "All layers — agents, services, the spine itself.",
+      "drift_risk": "Convenience features that let a layer \"tune itself\"; agent self-improvement loops.",
+      "enforcement_posture": "Self-modifying changes are detected at proposal intake; flagged at highest severity (D5) if attempted without governance event.",
+      "severity": "freeze",
+      "implementation_status": "partially_implemented",
+      "implementationStatus": "partially-implemented",
+      "authority_status": "non_authoritative",
+      "adoption_status": "candidate_only",
+      "caveat": "Authority topology forbids actors from granting themselves authority through normal capability paths, but no proposal-intake detector explicitly flags self-modification attempts as a distinct drift archetype.",
+      "implementation_notes": "Agent proposals enter as non-authoritative ExecutionProposals via /api/mdk/agent/propose and cannot trigger execution. Detection of self-scope-widening proposals (D5 archetype) is not yet a formal proposal-intake check."
+    }
+  ]
+}

package/scripts/demo.mjs

@@ -35,6 +35,7 @@ import {
 import { createServer } from "node:net";
 import os from "node:os";
 import path from "node:path";
+import { killChildTree } from "./proc-cleanup.mjs";
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const INTERNAL_KEY = "demo-operator-key";
@@ -117,22 +118,26 @@ const capture = (cmd, args, opts = {}) =>
   });
 
 // Run the MCP driver. The driver spawns the gateway (which spawns the downstream)
-// as children, and its kill doesn't always propagate through npx — so we run the
-// whole thing in its own process group, capture only stdout (stderr is discarded
-// so a lingering grandchild can't block us), resolve on `exit`, and then reap the
-// entire group. A watchdog guarantees the demo can never hang here.
+// as children, and its kill doesn't always propagate through npx — so on POSIX we
+// run the whole thing in its own process group and reap the entire group, while
+// on Windows (no process groups, negative PIDs are invalid) we terminate the
+// child directly. See scripts/proc-cleanup.mjs. We capture only stdout (stderr is
+// discarded so a lingering grandchild can't block us), resolve on `exit`, then
+// clean up. A watchdog guarantees the demo can never hang here.
+const isWindows = process.platform === "win32";
 const runDriver = (configPath, env) =>
   new Promise((resolve) => {
     const ch = spawn("node", ["scripts/mcp-demo-drive.mjs", configPath], {
-      cwd: ROOT, detached: true, stdio: ["ignore", "pipe", "ignore"], env,
+      // `detached` only buys us a process group on POSIX; skip it on Windows.
+      cwd: ROOT, detached: !isWindows, stdio: ["ignore", "pipe", "ignore"], env,
     });
     let out = "";
     ch.stdout.on("data", (d) => (out += d));
-    const killGroup = () => { try { process.kill(-ch.pid, "SIGKILL"); } catch {} };
-    const watchdog = setTimeout(() => { killGroup(); resolve({ code: 124, out }); }, 30_000);
+    const cleanup = () => killChildTree(ch);
+    const watchdog = setTimeout(() => { cleanup(); resolve({ code: 124, out }); }, 30_000);
     ch.on("exit", (code) => {
       clearTimeout(watchdog);
-      setTimeout(() => { killGroup(); resolve({ code: code ?? 0, out }); }, 150);
+      setTimeout(() => { cleanup(); resolve({ code: code ?? 0, out }); }, 150);
     });
   });
 

package/scripts/proc-cleanup.mjs

@@ -0,0 +1,31 @@
+/**
+ * Cross-platform best-effort termination of a detached child process and its
+ * process group. Used by the demo driver (scripts/demo.mjs) to reap the MCP
+ * driver together with the gateway + downstream it spawns.
+ *
+ * POSIX: the child is spawned `detached`, so it leads its own process group and
+ * we can tear the whole group down with `process.kill(-pid)` (a NEGATIVE pid).
+ *
+ * Windows: there are no POSIX process groups and a negative pid is invalid —
+ * `process.kill(-pid)` throws `EINVAL`/`ESRCH`, which is exactly what broke
+ * `npx magenta-canon demo` at step 3/7 on Windows. So on win32 we never use a
+ * negative pid; we terminate the child directly via `child.kill()`.
+ *
+ * Pure and injectable (`platform`, `kill`) so it can be unit-tested without
+ * actually spawning processes. No verifier/witness/evidence/gateway semantics.
+ */
+export function killChildTree(
+  child,
+  { platform = process.platform, kill = process.kill, signal = "SIGKILL" } = {},
+) {
+  const pid = child && child.pid;
+  if (pid == null) return;
+  if (platform === "win32") {
+    // No negative-PID group kill on Windows. Terminate the child directly;
+    // Node maps child.kill() to TerminateProcess for the child.
+    try { child.kill(signal); } catch { /* already gone */ }
+    return;
+  }
+  // POSIX: kill the entire detached process group (negative pid).
+  try { kill(-pid, signal); } catch { /* group already gone */ }
+}