forge-workflow 0.1.0-beta.5 → 0.1.0-beta.7

package/lib/workflow/plan-authority.js

@@ -0,0 +1,225 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash, randomUUID } = require('node:crypto');
+
+const SCHEMA = 'forge.plan.v1';
+const ARTIFACT_FILES = Object.freeze(['plan.md', 'tasks.md']);
+
+function sha256(content) {
+  return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+
+function readUtf8(absolutePath) {
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(fs.readFileSync(absolutePath));
+  } catch (error) {
+    throw new Error(`Plan artifact must be valid UTF-8: ${absolutePath} (${error.message})`);
+  }
+}
+
+function normalizeRelativePath(projectRoot, candidate) {
+  const absolute = path.resolve(projectRoot, candidate);
+  const relative = path.relative(projectRoot, absolute);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error('Plan artifact paths must stay inside the project root');
+  }
+  return relative.split(path.sep).join('/');
+}
+
+function artifactPath(projectRoot, relativePath) {
+  return path.join(projectRoot, ...relativePath.split('/'));
+}
+
+function isContained(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+// Resolve every existing component below the project root. Refuse links/reparse
+// points even when their target happens to remain inside the repo: allowing them
+// would make a later target swap bypass the containment decision.
+function assertSafeArtifactPath(projectRoot, absolutePath) {
+  const rootAbsolute = path.resolve(projectRoot);
+  const candidateAbsolute = path.resolve(absolutePath);
+  if (!isContained(rootAbsolute, candidateAbsolute)) {
+    throw new Error('Plan artifact path escapes the project root');
+  }
+  const rootReal = fs.realpathSync.native(rootAbsolute);
+  const segments = path.relative(rootAbsolute, candidateAbsolute).split(path.sep).filter(Boolean);
+  let current = rootAbsolute;
+  for (const segment of segments) {
+    current = path.join(current, segment);
+    if (!fs.existsSync(current)) break;
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink()) {
+      throw new Error('Plan artifact path contains a symbolic link or reparse point');
+    }
+    const currentReal = fs.realpathSync.native(current);
+    if (!isContained(rootReal, currentReal)) {
+      throw new Error('Plan artifact path resolves outside the project root');
+    }
+  }
+}
+
+function snapshotDigest(artifacts) {
+  const canonical = JSON.stringify(artifacts.map(({ path: artifact, sha256: digest }) => ({ path: artifact, sha256: digest })));
+  return sha256(canonical);
+}
+
+function createSnapshot({ projectRoot, workFolder }) {
+  const folder = normalizeRelativePath(projectRoot, workFolder);
+  const artifacts = ARTIFACT_FILES.map((filename) => {
+    const relativePath = `${folder}/${filename}`;
+    const absolutePath = artifactPath(projectRoot, relativePath);
+    assertSafeArtifactPath(projectRoot, absolutePath);
+    if (!fs.existsSync(absolutePath)) return null;
+    if (!fs.lstatSync(absolutePath).isFile()) {
+      throw new Error(`Plan artifact must be a regular file: ${relativePath}`);
+    }
+    const content = readUtf8(absolutePath);
+    return { path: relativePath, content, sha256: sha256(content) };
+  });
+  if (artifacts.some((entry) => entry === null)) return null;
+  return { schema: SCHEMA, digest: snapshotDigest(artifacts), artifacts };
+}
+
+function findPlanWorkFolder(projectRoot, featureSlug) {
+  if (!projectRoot || !featureSlug) return null;
+  const workRoot = path.join(projectRoot, 'docs', 'work');
+  if (!fs.existsSync(workRoot)) return null;
+  const suffix = `-${featureSlug}`;
+  const matches = fs.readdirSync(workRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && (entry.name === featureSlug || entry.name.endsWith(suffix)))
+    .map((entry) => `docs/work/${entry.name}`)
+    .filter((folder) => ARTIFACT_FILES.every((filename) => fs.existsSync(artifactPath(projectRoot, `${folder}/${filename}`))))
+    .sort();
+  return matches.length === 1 ? matches[0] : null;
+}
+
+function validateSnapshot(snapshot) {
+  if (!snapshot || snapshot.schema !== SCHEMA || !Array.isArray(snapshot.artifacts)) {
+    throw new Error('Kernel plan snapshot is invalid');
+  }
+  if (snapshot.artifacts.length !== ARTIFACT_FILES.length) {
+    throw new Error('Kernel plan snapshot is invalid');
+  }
+  const expectedNames = new Set(ARTIFACT_FILES);
+  const observedNames = new Set();
+  for (const artifact of snapshot.artifacts) {
+    if (!artifact || typeof artifact.path !== 'string' || typeof artifact.content !== 'string'
+      || sha256(artifact.content) !== artifact.sha256) {
+      throw new Error('Kernel plan snapshot is invalid');
+    }
+    const filename = path.posix.basename(artifact.path);
+    if (!expectedNames.has(filename) || observedNames.has(filename)) {
+      throw new Error('Kernel plan snapshot is invalid');
+    }
+    observedNames.add(filename);
+  }
+  if (snapshot.digest !== snapshotDigest(snapshot.artifacts)) {
+    throw new Error('Kernel plan snapshot is invalid');
+  }
+  return snapshot;
+}
+
+function readPlanSnapshot(driver, issueId) {
+  if (!driver || typeof driver.loadPlanSnapshot !== 'function') return null;
+  const snapshot = driver.loadPlanSnapshot({ issue_id: issueId }, {});
+  return snapshot ? validateSnapshot(snapshot) : null;
+}
+
+function inspectArtifacts(projectRoot, snapshot) {
+  const missing = [];
+  const drifted = [];
+  for (const artifact of snapshot.artifacts) {
+    const relative = normalizeRelativePath(projectRoot, artifact.path);
+    const absolute = artifactPath(projectRoot, relative);
+    assertSafeArtifactPath(projectRoot, absolute);
+    if (!fs.existsSync(absolute)) {
+      missing.push({ ...artifact, absolute });
+      continue;
+    }
+    const content = readUtf8(absolute);
+    if (sha256(content) !== artifact.sha256) drifted.push(artifact.path);
+  }
+  return { missing, drifted };
+}
+
+function materializeMissing(projectRoot, missing) {
+  const staged = [];
+  const created = [];
+  try {
+    for (const artifact of missing) {
+      assertSafeArtifactPath(projectRoot, artifact.absolute);
+      fs.mkdirSync(path.dirname(artifact.absolute), { recursive: true });
+      assertSafeArtifactPath(projectRoot, artifact.absolute);
+      const temporary = `${artifact.absolute}.forge-${randomUUID()}.tmp`;
+      fs.writeFileSync(temporary, artifact.content, { encoding: 'utf8', flag: 'wx' });
+      staged.push({ temporary, destination: artifact.absolute });
+    }
+    for (const entry of staged) {
+      // link is create-only (fails EEXIST), unlike rename which may overwrite a
+      // file another process materialized after our drift check.
+      fs.linkSync(entry.temporary, entry.destination);
+      fs.rmSync(entry.temporary, { force: true });
+      created.push(entry.destination);
+    }
+  } catch (error) {
+    for (const entry of staged) {
+      if (fs.existsSync(entry.temporary)) fs.rmSync(entry.temporary, { force: true });
+    }
+    for (const destination of created) {
+      if (fs.existsSync(destination)) fs.rmSync(destination, { force: true });
+    }
+    throw error;
+  }
+}
+
+function guidance(message, repairCommand) {
+  return `${message} ${repairCommand}`;
+}
+
+function reconcilePlanAuthority({
+  driver,
+  issueId,
+  projectRoot,
+  workFolder,
+  mode = 'dev',
+  repairCommand = `forge plan "<feature>" --issue ${issueId}`,
+} = {}) {
+  if (!driver || !issueId || !projectRoot) {
+    throw new Error('Plan authority requires a Kernel driver, issue id, and project root');
+  }
+  const existing = readPlanSnapshot(driver, issueId);
+  if (!existing) {
+    const snapshot = workFolder ? createSnapshot({ projectRoot, workFolder }) : null;
+    if (!snapshot) {
+      throw new Error(guidance('Plan authority is missing. Create plan.md and tasks.md, then run:', repairCommand));
+    }
+    if (typeof driver.recordPlanSnapshotTransition !== 'function') {
+      throw new Error('Kernel driver cannot persist plan authority');
+    }
+    driver.recordPlanSnapshotTransition({ issue_id: issueId, snapshot }, {});
+    return { status: 'captured', snapshot };
+  }
+
+  const { missing, drifted } = inspectArtifacts(projectRoot, existing);
+  if (drifted.length > 0) {
+    throw new Error(guidance('Plan artifacts drifted from Kernel authority. Reconcile the files, then run:', repairCommand));
+  }
+  if (missing.length > 0) {
+    materializeMissing(projectRoot, missing);
+    return { status: 'materialized', snapshot: existing };
+  }
+  return { status: mode === 'plan' ? 'reconciled' : 'verified', snapshot: existing };
+}
+
+module.exports = {
+  SCHEMA,
+  createSnapshot,
+  findPlanWorkFolder,
+  readPlanSnapshot,
+  reconcilePlanAuthority,
+};

package/node_modules/@forge/contracts/compatibility-matrix.v1.json

@@ -0,0 +1 @@
+{"matrix_version":1,"readers":{"0.1.0-beta.6":{"accepted":{"forge.memory.work-packet.v1":[1],"forge.memory.context-packet.v1":[1],"forge.memory.claim-request.v1":[1],"forge.memory.lease-receipt.v1":[1],"forge.memory.capability-manifest.v1":[1],"forge.memory.run-receipt.v1":[1],"forge.memory.feedback-report.v1":[1],"forge.memory.structured-error.v1":[1],"forge.memory.monitor-event.v1":[1],"forge.memory.delivery-receipt.v1":[1],"forge.memory.monitor-receipt.v1":[1]},"validation_surfaces":{"structural":"no_authority_or_freshness_claim","consequential":"requires_independent_live_expected"},"schema_annotations":{"generic_json_schema_enforces_x_forge":false,"conformance_helper":"validateContractStructure","requirement":"x-forge bounds and privacy annotations require the Forge runtime validator"},"run_receipt_non_authoritative_statuses":["NOT_EXECUTED"],"unknown_advisory":"preserve","unknown_consequential":"reject","unknown_schema_version":"reject"}}}

package/node_modules/@forge/contracts/contract-baseline.v1.json

@@ -0,0 +1,134 @@
+{
+  "baseline_version": 1,
+  "generator_version": "contracts-schema-gen/7",
+  "artifacts": [
+    {
+      "path": "compatibility-matrix.v1.json",
+      "sha256": "4ca93d10ae9bff80dd3785bb5ebfc77610cf19e928b9b9ae3f6a1ad9c2fea18e"
+    },
+    {
+      "path": "fixtures/v1/canonical-hash.json",
+      "sha256": "469c5b83ebe5e02601cd41b83f35f013f8fb4b118b8e213dc1790bb61301dc3c"
+    },
+    {
+      "path": "fixtures/v1/contract-inputs.v1.json",
+      "sha256": "40f28821f77ea153259a43e0ca8a5d6611f3e5e0ec4e4e47114d4cddeadac3fc"
+    },
+    {
+      "path": "fixtures/v1/feedback-secret-reject.json",
+      "sha256": "d2a8762a169617a6c98f5654e1d5265732485037e55af107018d139895b47869"
+    },
+    {
+      "path": "fixtures/v1/identity-conflict.json",
+      "sha256": "c703733d89f8adb079fb0e0ffe01ad35238d9a5f3ae725af54bca8b518fd6039"
+    },
+    {
+      "path": "fixtures/v1/malformed-envelope-inputs.v1.json",
+      "sha256": "17354a1178523332645f27d506eeabaa39eb6ea6bfa448807f7d0b8d4a1226f2"
+    },
+    {
+      "path": "fixtures/v1/malformed-missing-required.json",
+      "sha256": "e4031505309e8b172d274ef7c4ef617e71217742ff2b7285f37859db0eea42b9"
+    },
+    {
+      "path": "fixtures/v1/monitor-bounds-reject.json",
+      "sha256": "36594e37f3707572ec73c60134f24f5fb3ae17a41d804c409fc03a83e9716c26"
+    },
+    {
+      "path": "fixtures/v1/monitor-receipt-privacy-reject.json",
+      "sha256": "e2c53bc43d727d3583f9f2da6538c127a08997fe279f9e74d585c5b95983b4bf"
+    },
+    {
+      "path": "fixtures/v1/not-executed-receipt.json",
+      "sha256": "4582002c36cca422ac1ad9a5858558234d5ed162dbe72b36665fe09ab098099f"
+    },
+    {
+      "path": "fixtures/v1/privacy-redaction.json",
+      "sha256": "be4bae1d68db334875b3d198525dcd46f3efb46dbeea62de03399a915b716e20"
+    },
+    {
+      "path": "fixtures/v1/retry-identical.json",
+      "sha256": "41c944e15725d45a19bd97015c4bf7fb6ca1a4740426225426bc38799046bd8a"
+    },
+    {
+      "path": "fixtures/v1/stale-authority-reject.json",
+      "sha256": "700173546cff08486df201316472921d8304ea892c29770b5f199e63c92601b3"
+    },
+    {
+      "path": "fixtures/v1/structured-error-privacy-reject.json",
+      "sha256": "008186d22ed5048e4926c7b56c08a71802392886425944d0e1a22b10c7433d58"
+    },
+    {
+      "path": "fixtures/v1/structured-error-stripe-live-reject.json",
+      "sha256": "6e7e0d865ccab874fed66cefd15943bbaf51e4be37bfc99cd38f2e8cd6cafce6"
+    },
+    {
+      "path": "fixtures/v1/structured-error-stripe-test-reject.json",
+      "sha256": "ab9d748875e4688299a8678a551a2d3f13eb85c6f852ccbaaf102b870b3da82c"
+    },
+    {
+      "path": "fixtures/v1/unknown-advisory-roundtrip.json",
+      "sha256": "674e1dd9585d86ed7c8851a3d7e2b0ce81427a3dbc59c149409ee87375f9e879"
+    },
+    {
+      "path": "fixtures/v1/unknown-consequential-reject.json",
+      "sha256": "4228ce85d8f92d6eea61802fd34a410eab778314c70c8315cd1d9c9ba8ef2813"
+    },
+    {
+      "path": "fixtures/v1/valid-full.json",
+      "sha256": "2ba47dfcd5bc6dc4fae83160b05eeca480b51b065d251a0f531ca2c3effb0397"
+    },
+    {
+      "path": "fixtures/v1/valid-minimal.json",
+      "sha256": "e7d4e7d5cb11b4de809140d572c6f40a5ed4fc813f0044983930a6fbaab99444"
+    },
+    {
+      "path": "fixtures/v1/wrong-capability-digest.json",
+      "sha256": "8599acc3eebfba3883ec05e496cfc66e08e79877c8193c24db75540b4549062a"
+    },
+    {
+      "path": "schemas/v1/capability-manifest.schema.json",
+      "sha256": "8435c1ec9ebfd0f9b9b6d06f490dcfdac4696f002a83692899e1e172f17cd6dd"
+    },
+    {
+      "path": "schemas/v1/claim-request.schema.json",
+      "sha256": "eb9a6aa46c51550fa5505caeeff6e7773fce128e940fdb85a851cfd13cbf1375"
+    },
+    {
+      "path": "schemas/v1/context-packet.schema.json",
+      "sha256": "36f422011e03fafe07de5fb16a1e9c745015b4257f640e77f1ae1f4ba70971eb"
+    },
+    {
+      "path": "schemas/v1/delivery-receipt.schema.json",
+      "sha256": "1e505c9a790d2e5a3ccf1cd227b7a708924f9d92a61c2220964f7cb05a9d8f4c"
+    },
+    {
+      "path": "schemas/v1/feedback-report.schema.json",
+      "sha256": "6f9f272b831d30574ecf56601307a361544f022c7690fd8077aeae8ca5913e37"
+    },
+    {
+      "path": "schemas/v1/lease-receipt.schema.json",
+      "sha256": "e7b3c1f6857e4ebad930518236011b8346054b1fa7d38607def4a42c1ba9a739"
+    },
+    {
+      "path": "schemas/v1/monitor-event.schema.json",
+      "sha256": "df270f5b7e280c10293f2c964727d13baa0488c9e1cc87037ba1307bc76958dc"
+    },
+    {
+      "path": "schemas/v1/monitor-receipt.schema.json",
+      "sha256": "555dba3db355498a1813bfcf045fe2c3f10057789539918e3303c11191048b33"
+    },
+    {
+      "path": "schemas/v1/run-receipt.schema.json",
+      "sha256": "de55aca54248a208560fffade7bcfdc555e83daf330f37fe482bb8068495ece6"
+    },
+    {
+      "path": "schemas/v1/structured-error.schema.json",
+      "sha256": "ea8b6d40528634743efa91a550d27d8191adc8ce95e630356dadce98ba864d64"
+    },
+    {
+      "path": "schemas/v1/work-packet.schema.json",
+      "sha256": "82f149e5ceedf004a5c129f264d0cb94e6704a7eadae8f02dbd40a62b75a556c"
+    }
+  ]
+}

package/node_modules/@forge/contracts/fixtures/v1/canonical-hash.json

@@ -0,0 +1 @@
+{"fixture_id":"canonical-hash","input_ref":{"file":"contract-inputs.v1.json","schema_id":"forge.memory.work-packet.v1"},"operation":"canonical-hash","expected":{"stable_under_key_reordering":true,"content_hash_excluded":true}}

package/node_modules/@forge/contracts/fixtures/v1/contract-inputs.v1.json

@@ -0,0 +1,71 @@
+{
+  "corpus_version": 1,
+  "inputs": [
+    {
+      "schema_id": "forge.memory.work-packet.v1", "schema_version": 1, "object_id": "00000000-0000-4000-8000-000000000001", "created_at": "2026-08-09T12:00:00.000Z",
+      "producer": { "product_id": "forge-memory", "product_version": "0.1.0-beta.6", "instance_id": "fixture" }, "capabilities_used": [],
+      "provenance": { "source_kind": "fixture", "actor_class": "system", "actor_id": "fixture" }, "content_hash": "b5b6527735acceed41f41cb4b7ae778ad8e3d3fd517832c4936e8c632881c10c",
+      "payload": { "issue_id": "issue-1", "expected_issue_revision": 1, "packet_id": "packet-1", "packet_revision": 1, "repository_id": "github.com/example/forge", "target_head": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "objective": "fixture objective", "authority": { "kind": "kernel", "issue_revision": 1 }, "allowed_mutations": ["files"], "workflow_config_revision": "config-1", "capability_manifest_digest": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc" }, "extensions": {}
+    },
+    {
+      "schema_id": "forge.memory.context-packet.v1", "schema_version": 1, "object_id": "00000000-0000-4000-8000-000000000002", "created_at": "2026-08-09T12:00:00.000Z",
+      "producer": { "product_id": "forge-memory", "product_version": "0.1.0-beta.6", "instance_id": "fixture" }, "capabilities_used": [],
+      "provenance": { "source_kind": "fixture", "actor_class": "system", "actor_id": "fixture" }, "content_hash": "278663383d458667b71eb25f6bed8c5828445e070b5af2369a46bc2953b34999",
+      "payload": { "work_packet_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "context_selection_revision": 1, "privacy_scope_hash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "retention_class": "local_sensitive", "disclosure_class": "remote_redacted", "redaction_policy_revision": "redaction-1", "summaries": [{ "kind": "issue", "text": "redacted fixture" }] }, "extensions": {}
+    },
+    {
+      "schema_id": "forge.memory.claim-request.v1", "schema_version": 1, "object_id": "00000000-0000-4000-8000-000000000003", "created_at": "2026-08-09T12:00:00.000Z",
+      "producer": { "product_id": "forge-memory", "product_version": "0.1.0-beta.6", "instance_id": "fixture" }, "capabilities_used": [],
+      "provenance": { "source_kind": "fixture", "actor_class": "agent", "actor_id": "agent-1" }, "content_hash": "aa1972081945dbfff1b9a800ce139968f6bc8581f19d5f243906181565a665aa",
+      "payload": { "issue_id": "issue-1", "expected_issue_revision": 1, "actor_id": "agent-1", "request_id": "request-1", "requested_scope": { "mutations": ["files"] }, "idempotency_key": "claim-1" }, "extensions": {}
+    },
+    {
+      "schema_id": "forge.memory.lease-receipt.v1", "schema_version": 1, "object_id": "00000000-0000-4000-8000-000000000004", "created_at": "2026-08-09T12:00:00.000Z",
+      "producer": { "product_id": "forge-memory", "product_version": "0.1.0-beta.6", "instance_id": "fixture" }, "capabilities_used": [],
+      "provenance": { "source_kind": "kernel", "actor_class": "authority", "actor_id": "kernel" }, "content_hash": "f3fdc336f2da33d69ed4e1e360e455d9903123add962464062d29f373cabe3d0",
+      "payload": { "claim_request_id": "request-1", "lease_id": "lease-1", "lease_epoch": 1, "issue_revision": 1, "actor_id": "agent-1", "scope": { "mutations": ["files"] }, "expires_at": "2026-08-09T13:00:00.000Z", "durable": true, "authority_signature": "fixture-signature" }, "extensions": {}
+    },
+    {
+      "schema_id": "forge.memory.capability-manifest.v1", "schema_version": 1, "object_id": "00000000-0000-4000-8000-000000000005", "created_at": "2026-08-09T12:00:00.000Z",
+      "producer": { "product_id": "forge-flow", "product_version": "0.1.0-beta.6", "instance_id": "fixture" }, "capabilities_used": [],
+      "provenance": { "source_kind": "probe", "actor_class": "system", "actor_id": "probe" }, "content_hash": "296ff678e04103e339231fef672db2220f5bd23981fefdc96dcfcd6f338f355e",
+      "payload": { "provider_id": "codex", "manifest_revision": 1, "config_revision": "config-1", "executable_identity": { "path_hash": "fixture" }, "provider_version": "1.0.0", "probe_revision": "probe-1", "result_hash": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd", "capabilities": [{ "capability_id": "flow.execute", "available": true }], "evaluator_status": "approved", "probed_at": "2026-08-09T12:00:00.000Z", "expires_at": "2026-08-09T13:00:00.000Z" }, "extensions": {}
+    },
+    {
+      "schema_id": "forge.memory.run-receipt.v1", "schema_version": 1, "object_id": "00000000-0000-4000-8000-000000000006", "created_at": "2026-08-09T12:30:00.000Z",
+      "producer": { "product_id": "forge-flow", "product_version": "0.1.0-beta.6", "instance_id": "run-1" }, "capabilities_used": [],
+      "provenance": { "source_kind": "execution", "actor_class": "agent", "actor_id": "agent-1" }, "content_hash": "4f919795d2c62ad6520b54fc526c215621ef046a59326f673aa6e41a1f6fc751",
+      "payload": { "packet_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "run_id": "run-1", "attempt_id": "attempt-1", "exact_head": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "packet_revision": 1, "manifest_digest": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", "workflow_config_revision": "config-1", "status": "PASS", "executor": { "product": "forge-flow" }, "started_at": "2026-08-09T12:00:00.000Z", "ended_at": "2026-08-09T12:30:00.000Z", "evidence_refs": [], "validation": { "status": "PASS" }, "cleanup": { "status": "PASS" } }, "extensions": {}
+    },
+    {
+      "schema_id": "forge.memory.feedback-report.v1", "schema_version": 1, "object_id": "00000000-0000-4000-8000-000000000007", "created_at": "2026-08-09T12:00:00.000Z",
+      "producer": { "product_id": "forge-memory", "product_version": "0.1.0-beta.6", "instance_id": "fixture" }, "capabilities_used": [],
+      "provenance": { "source_kind": "feedback", "actor_class": "anonymous-user", "actor_id": "report-1" }, "content_hash": "3adb5b3f1b726b7b67032bf607ab89e54aee3f9eeefa6d4cdbd29340bee555c1",
+      "payload": { "report_id": "report-1", "product_version": "0.1.0-beta.6", "contract_version": 1, "stable_error_code": "FORGE_FIXTURE", "affected_capability": "flow.execute", "redacted_reproduction_steps": ["run fixture"], "expected_classification": "PASS", "actual_classification": "FAIL", "occurrence_count": 1, "content_fingerprint": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "consent_event_id": "consent-1", "redaction_policy_revision": "redaction-1" }, "extensions": {}
+    },
+    {
+      "schema_id": "forge.memory.structured-error.v1", "schema_version": 1, "object_id": "00000000-0000-4000-8000-000000000008", "created_at": "2026-08-09T12:00:00.000Z",
+      "producer": { "product_id": "forge-memory", "product_version": "0.1.0-beta.6", "instance_id": "fixture" }, "capabilities_used": [],
+      "provenance": { "source_kind": "execution", "actor_class": "system", "actor_id": "forge" }, "content_hash": "50d181d71714a308539f5612fee7dfa854a4abe9591981842303de24db64982d",
+      "payload": { "parent_object_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "error_occurrence_id": "error-1", "code": "FORGE_FIXTURE", "terminal_classification": "FAIL", "safe_details": { "summary": "fixture failure" } }, "extensions": {}
+    },
+    {
+      "schema_id": "forge.memory.monitor-event.v1", "schema_version": 1, "object_id": "00000000-0000-4000-8000-000000000009", "created_at": "2026-08-09T12:00:00.000Z",
+      "producer": { "product_id": "forge-flow", "product_version": "0.1.0-beta.6", "instance_id": "monitor-1" }, "capabilities_used": [],
+      "provenance": { "source_kind": "monitor", "actor_class": "system", "actor_id": "monitor" }, "content_hash": "01b1e7086a5ba2ddf521ad8e8901db925d9f9e8fe2db75c43ca5eea941d68559",
+      "payload": { "monitor_id": "monitor-1", "event_id": "event-1", "sequence": 0, "subject_revision": "head-1", "type": "check.completed", "actionability": "advisory", "observed_at": "2026-08-09T12:00:00.000Z", "bounded_payload": { "status": "PASS" } }, "extensions": {}
+    },
+    {
+      "schema_id": "forge.memory.delivery-receipt.v1", "schema_version": 1, "object_id": "00000000-0000-4000-8000-000000000010", "created_at": "2026-08-09T12:00:00.000Z",
+      "producer": { "product_id": "forge-flow", "product_version": "0.1.0-beta.6", "instance_id": "delivery-1" }, "capabilities_used": [],
+      "provenance": { "source_kind": "delivery", "actor_class": "system", "actor_id": "adapter" }, "content_hash": "0bfe86d8a48be6ac271c92c1e767ec53ce0f7bfc2e228a47832522eefa44b40a",
+      "payload": { "event_id": "event-1", "target": "agent-1", "transport_tier": "T1", "attempt": 1, "delivered_at": "2026-08-09T12:00:00.000Z", "acknowledged": true, "outcome": "acknowledged" }, "extensions": {}
+    },
+    {
+      "schema_id": "forge.memory.monitor-receipt.v1", "schema_version": 1, "object_id": "00000000-0000-4000-8000-000000000011", "created_at": "2026-08-09T12:00:00.000Z",
+      "producer": { "product_id": "forge-flow", "product_version": "0.1.0-beta.6", "instance_id": "monitor-1" }, "capabilities_used": [],
+      "provenance": { "source_kind": "monitor", "actor_class": "system", "actor_id": "monitor" }, "content_hash": "01da8754bae5d5a17501a7e20bfc93959e274227add6a31e451424b2c1ac7251",
+      "payload": { "monitor_id": "monitor-1", "owner_run_id": "run-1", "terminal_state": "PASS", "terminal_reason": "predicate satisfied", "last_sequence": 0, "evidence_digest": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", "cancellation_acknowledged": true, "process_cleanup": { "status": "PASS" }, "lease_cleanup": { "status": "PASS" } }, "extensions": {}
+    }
+  ]
+}

package/node_modules/@forge/contracts/fixtures/v1/feedback-secret-reject.json

@@ -0,0 +1 @@
+{"fixture_id":"feedback-secret-reject","input_ref":{"file":"contract-inputs.v1.json","schema_id":"forge.memory.feedback-report.v1"},"mutation":{"operation":"replace","path":"payload.redacted_reproduction_steps","value":["token=ghp_123456789012345678901234567890"],"rehash":true},"operation":"validate-structure","expected":{"ok":false,"code":"PRIVACY_SECRET_PATTERN"}}

package/node_modules/@forge/contracts/fixtures/v1/identity-conflict.json

@@ -0,0 +1 @@
+{"fixture_id":"identity-conflict","accepted_ref":{"file":"contract-inputs.v1.json","schema_id":"forge.memory.work-packet.v1"},"candidate_ref":{"file":"contract-inputs.v1.json","schema_id":"forge.memory.work-packet.v1"},"candidate_mutation":{"operation":"replace","path":"payload.objective","value":"conflicting objective","rehash":true},"operation":"classify-semantic-attempt","expected":{"status":"identity-conflict"}}

package/node_modules/@forge/contracts/fixtures/v1/malformed-envelope-inputs.v1.json

@@ -0,0 +1,16 @@
+{
+  "corpus_version": 1,
+  "base_input": { "ref": "contract-inputs.v1.json", "schema_id": "forge.memory.work-packet.v1" },
+  "cases": [
+    { "missing_field": "schema_id", "operation": "remove", "expected_code": "MISSING_REQUIRED" },
+    { "missing_field": "schema_version", "operation": "remove", "expected_code": "MISSING_REQUIRED" },
+    { "missing_field": "object_id", "operation": "remove", "expected_code": "MISSING_REQUIRED" },
+    { "missing_field": "created_at", "operation": "remove", "expected_code": "MISSING_REQUIRED" },
+    { "missing_field": "producer", "operation": "remove", "expected_code": "MISSING_REQUIRED" },
+    { "missing_field": "capabilities_used", "operation": "remove", "expected_code": "MISSING_REQUIRED" },
+    { "missing_field": "provenance", "operation": "remove", "expected_code": "MISSING_REQUIRED" },
+    { "missing_field": "content_hash", "operation": "remove", "expected_code": "MISSING_REQUIRED" },
+    { "missing_field": "payload", "operation": "remove", "expected_code": "MISSING_REQUIRED" },
+    { "missing_field": "extensions", "operation": "remove", "expected_code": "MISSING_REQUIRED" }
+  ]
+}

package/node_modules/@forge/contracts/fixtures/v1/malformed-missing-required.json

@@ -0,0 +1 @@
+{"fixture_id":"malformed-missing-required","input_ref":{"file":"malformed-envelope-inputs.v1.json"},"operation":"materialize-cases","expected":{"case_count":10,"code":"MISSING_REQUIRED"}}

package/node_modules/@forge/contracts/fixtures/v1/monitor-bounds-reject.json

@@ -0,0 +1 @@
+{"fixture_id":"monitor-bounds-reject","input_ref":{"file":"contract-inputs.v1.json","schema_id":"forge.memory.monitor-event.v1"},"mutation":{"operation":"replace","path":"payload.bounded_payload","value":{"shape":"nine-level nested object; materializer repeats key child nine times"},"rehash":true},"operation":"validate-structure","expected":{"ok":false,"code":"BOUNDED_VALUE_TOO_DEEP"}}

package/node_modules/@forge/contracts/fixtures/v1/monitor-receipt-privacy-reject.json

@@ -0,0 +1 @@
+{"fixture_id":"monitor-receipt-privacy-reject","input_ref":{"file":"contract-inputs.v1.json","schema_id":"forge.memory.monitor-receipt.v1"},"mutation":{"operation":"replace","path":"payload.process_cleanup","value":{"detail":"password=supersecretvalue"},"rehash":true},"operation":"validate-structure","expected":{"ok":false,"code":"PRIVACY_SECRET_PATTERN"}}

package/node_modules/@forge/contracts/fixtures/v1/not-executed-receipt.json

@@ -0,0 +1 @@
+{"fixture_id":"not-executed-receipt","input_ref":{"file":"contract-inputs.v1.json","schema_id":"forge.memory.run-receipt.v1"},"mutation":{"operation":"replace","path":"payload.status","value":"NOT_EXECUTED","rehash":true},"operation":"validate-structure-then-authority","expected":{"structural_ok":true,"authority_ok":false,"authority_code":"NOT_EXECUTED_NO_TRANSITION"}}

package/node_modules/@forge/contracts/fixtures/v1/privacy-redaction.json

@@ -0,0 +1 @@
+{"fixture_id":"privacy-redaction","input_ref":{"file":"contract-inputs.v1.json","schema_id":"forge.memory.context-packet.v1"},"live_expected":{"workPacketHash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","privacyScopeHash":"dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd","redactionPolicyRevision":"redaction-1","allowedDisclosureClasses":["remote_redacted"]},"operation":"validate-expected","expected":{"code":"STALE_PRIVACY_SCOPE","raw_content_embedded":false}}

package/node_modules/@forge/contracts/fixtures/v1/retry-identical.json

@@ -0,0 +1 @@
+{"fixture_id":"retry-identical","accepted_ref":{"file":"contract-inputs.v1.json","schema_id":"forge.memory.work-packet.v1"},"candidate_ref":{"file":"contract-inputs.v1.json","schema_id":"forge.memory.work-packet.v1"},"operation":"classify-semantic-attempt","expected":{"status":"retry-identical"}}

package/node_modules/@forge/contracts/fixtures/v1/stale-authority-reject.json

@@ -0,0 +1 @@
+{"fixture_id":"stale-authority-reject","input_ref":{"file":"contract-inputs.v1.json","schema_id":"forge.memory.work-packet.v1"},"live_expected":{"issueRevision":2,"workflowConfigRevision":"config-1","capabilityManifestDigest":"cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc","exactHead":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"operation":"validate-expected","expected":{"code":"STALE_ISSUE_REVISION"}}

package/node_modules/@forge/contracts/fixtures/v1/structured-error-privacy-reject.json

@@ -0,0 +1 @@
+{"fixture_id":"structured-error-privacy-reject","input_ref":{"file":"contract-inputs.v1.json","schema_id":"forge.memory.structured-error.v1"},"mutation":{"operation":"replace","path":"payload.safe_details","value":{"detail":"token=ghp_123456789012345678901234567890"},"rehash":true},"operation":"validate-structure","expected":{"ok":false,"code":"PRIVACY_SECRET_PATTERN"}}

package/node_modules/@forge/contracts/fixtures/v1/structured-error-stripe-live-reject.json

@@ -0,0 +1 @@
+{"fixture_id":"structured-error-stripe-live-reject","input_ref":{"file":"contract-inputs.v1.json","schema_id":"forge.memory.structured-error.v1"},"mutation":{"operation":"replace","path":"payload.safe_details","value":{"detail":"sk_live_1234567890ABCDEF"},"rehash":true},"operation":"validate-structure","expected":{"ok":false,"code":"PRIVACY_SECRET_PATTERN"}}

package/node_modules/@forge/contracts/fixtures/v1/structured-error-stripe-test-reject.json

@@ -0,0 +1 @@
+{"fixture_id":"structured-error-stripe-test-reject","input_ref":{"file":"contract-inputs.v1.json","schema_id":"forge.memory.structured-error.v1"},"mutation":{"operation":"replace","path":"payload.safe_details","value":{"detail":"sk_test_ABCDEF1234567890"},"rehash":true},"operation":"validate-structure","expected":{"ok":false,"code":"PRIVACY_SECRET_PATTERN"}}

package/node_modules/@forge/contracts/fixtures/v1/unknown-advisory-roundtrip.json

@@ -0,0 +1 @@
+{"fixture_id":"unknown-advisory-roundtrip","input_ref":{"file":"contract-inputs.v1.json","schema_id":"forge.memory.work-packet.v1"},"mutation":{"operation":"add","path":"extensions.vendor.example/advisory","value":{"impact":"advisory","schema_version":1,"value":{"note":"preserve"}},"rehash":true},"operation":"roundtrip-extension","expected":{"preserved":true}}

package/node_modules/@forge/contracts/fixtures/v1/unknown-consequential-reject.json

@@ -0,0 +1 @@
+{"fixture_id":"unknown-consequential-reject","input_ref":{"file":"contract-inputs.v1.json","schema_id":"forge.memory.work-packet.v1"},"mutation":{"operation":"add","path":"extensions.vendor.example/authority","value":{"impact":"consequential","schema_version":1,"value":{"permit":true}},"rehash":true},"operation":"validate-extension","expected":{"code":"UNKNOWN_CONSEQUENTIAL_EXTENSION"}}

package/node_modules/@forge/contracts/fixtures/v1/valid-full.json

@@ -0,0 +1 @@
+{"fixture_id":"valid-full","input_ref":{"file":"contract-inputs.v1.json","schema_id":"forge.memory.work-packet.v1"},"mutations":[{"operation":"add","path":"payload.acceptance_criteria","value":["all gates pass"]},{"operation":"add","path":"payload.prohibited_actions","value":["merge"]}],"operation":"rehash-and-validate-structure","authority_claim":false,"expected":{"ok":true}}

package/node_modules/@forge/contracts/fixtures/v1/valid-minimal.json

@@ -0,0 +1 @@
+{"fixture_id":"valid-minimal","input_ref":{"file":"contract-inputs.v1.json","schema_id":"forge.memory.work-packet.v1"},"operation":"validate-structure","authority_claim":false,"expected":{"ok":true}}

package/node_modules/@forge/contracts/fixtures/v1/wrong-capability-digest.json

@@ -0,0 +1 @@
+{"fixture_id":"wrong-capability-digest","input_ref":{"file":"contract-inputs.v1.json","schema_id":"forge.memory.work-packet.v1"},"live_expected":{"issueRevision":1,"workflowConfigRevision":"config-1","capabilityManifestDigest":"dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd","exactHead":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"operation":"validate-expected","expected":{"code":"WRONG_CAPABILITY_DIGEST"}}

package/node_modules/@forge/contracts/index.js

@@ -0,0 +1,32 @@
+"use strict";
+
+const { canonicalize, computeContentHash } = require("./src/canonical.js");
+const { verifyContractBaseline } = require("./src/baseline.js");
+const { CONTRACTS } = require("./src/definitions.js");
+const { classifySemanticAttempt, semanticIdentity } = require("./src/identity.js");
+const { generateJsonSchema, supportedSchemaVersions } = require("./src/schema.js");
+const {
+  ContractValidationError,
+  ENVELOPE_FIELDS,
+  parseContract,
+  validateContract,
+  validateContractStructure,
+  validateEnvelope,
+} = require("./src/validate.js");
+
+module.exports = {
+  ENVELOPE_FIELDS,
+  CONTRACTS,
+  ContractValidationError,
+  canonicalize,
+  classifySemanticAttempt,
+  computeContentHash,
+  generateJsonSchema,
+  parseContract,
+  semanticIdentity,
+  supportedSchemaVersions,
+  validateContract,
+  validateContractStructure,
+  validateEnvelope,
+  verifyContractBaseline,
+};

package/node_modules/@forge/contracts/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@forge/contracts",
+  "version": "0.1.0-beta.6",
+  "description": "Behavior-neutral packet and receipt contracts for Forge products",
+  "main": "index.js",
+  "type": "commonjs",
+  "files": [
+    "index.js",
+    "src/",
+    "schemas/",
+    "fixtures/",
+    "contract-baseline.v1.json",
+    "compatibility-matrix.v1.json"
+  ],
+  "scripts": {
+    "test": "bun test test",
+    "lint": "eslint . --max-warnings 0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/harshanandak/forge.git",
+    "directory": "packages/contracts"
+  },
+  "homepage": "https://github.com/harshanandak/forge#readme",
+  "bugs": {
+    "url": "https://github.com/harshanandak/forge/issues"
+  },
+  "engines": {
+    "node": ">=22.16.0"
+  }
+}

package/node_modules/@forge/contracts/schemas/v1/capability-manifest.schema.json

@@ -0,0 +1 @@
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"forge.memory.capability-manifest.v1","title":"CapabilityManifest","type":"object","required":["schema_id","schema_version","object_id","created_at","producer","capabilities_used","provenance","content_hash","payload","extensions"],"properties":{"schema_id":{"const":"forge.memory.capability-manifest.v1"},"schema_version":{"const":1},"object_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"producer":{"type":"object","required":["product_id","product_version","instance_id"],"properties":{"product_id":{"type":"string","minLength":1},"product_version":{"type":"string","minLength":1},"instance_id":{"type":"string","minLength":1}},"additionalProperties":false},"capabilities_used":{"type":"array","items":{"type":"object","required":["capability_id","manifest_digest"],"properties":{"capability_id":{"type":"string","minLength":1},"manifest_digest":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"additionalProperties":false}},"provenance":{"type":"object","required":["source_kind","actor_class","actor_id"],"properties":{"source_kind":{"type":"string","minLength":1},"actor_class":{"type":"string","minLength":1},"actor_id":{"type":"string","minLength":1}},"additionalProperties":false},"content_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"payload":{"type":"object","required":["provider_id","manifest_revision","config_revision","executable_identity","provider_version","probe_revision","result_hash","capabilities","evaluator_status","probed_at","expires_at"],"properties":{"provider_id":{"type":"string","minLength":1},"manifest_revision":{"type":"integer","minimum":1},"config_revision":{"type":"string","minLength":1},"executable_identity":{"type":"object"},"provider_version":{"type":"string","minLength":1},"probe_revision":{"type":"string","minLength":1},"result_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"capabilities":{"type":"array","items":{"type":"object","required":["capability_id","available"],"properties":{"capability_id":{"type":"string","minLength":1},"available":{"type":"boolean"}}}},"evaluator_status":{"type":"string","enum":["approved","unavailable","quarantined"]},"probed_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"}},"additionalProperties":false},"extensions":{"type":"object","propertyNames":{"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]*(?:[./][A-Za-z0-9][A-Za-z0-9_-]*)+$","maxLength":255},"additionalProperties":{"type":"object","required":["impact","schema_version","value"],"properties":{"impact":{"const":"advisory"},"schema_version":{"type":"integer","minimum":1},"value":{}},"additionalProperties":false}}},"additionalProperties":false}

package/node_modules/@forge/contracts/schemas/v1/claim-request.schema.json

@@ -0,0 +1 @@
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"forge.memory.claim-request.v1","title":"ClaimRequest","type":"object","required":["schema_id","schema_version","object_id","created_at","producer","capabilities_used","provenance","content_hash","payload","extensions"],"properties":{"schema_id":{"const":"forge.memory.claim-request.v1"},"schema_version":{"const":1},"object_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"producer":{"type":"object","required":["product_id","product_version","instance_id"],"properties":{"product_id":{"type":"string","minLength":1},"product_version":{"type":"string","minLength":1},"instance_id":{"type":"string","minLength":1}},"additionalProperties":false},"capabilities_used":{"type":"array","items":{"type":"object","required":["capability_id","manifest_digest"],"properties":{"capability_id":{"type":"string","minLength":1},"manifest_digest":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"additionalProperties":false}},"provenance":{"type":"object","required":["source_kind","actor_class","actor_id"],"properties":{"source_kind":{"type":"string","minLength":1},"actor_class":{"type":"string","minLength":1},"actor_id":{"type":"string","minLength":1}},"additionalProperties":false},"content_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"payload":{"type":"object","required":["issue_id","expected_issue_revision","actor_id","request_id","requested_scope","idempotency_key"],"properties":{"issue_id":{"type":"string","minLength":1},"expected_issue_revision":{"type":"integer","minimum":0},"actor_id":{"type":"string","minLength":1},"request_id":{"type":"string","minLength":1},"requested_scope":{"type":"object"},"idempotency_key":{"type":"string","minLength":1}},"additionalProperties":false},"extensions":{"type":"object","propertyNames":{"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]*(?:[./][A-Za-z0-9][A-Za-z0-9_-]*)+$","maxLength":255},"additionalProperties":{"type":"object","required":["impact","schema_version","value"],"properties":{"impact":{"const":"advisory"},"schema_version":{"type":"integer","minimum":1},"value":{}},"additionalProperties":false}}},"additionalProperties":false}