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

package/node_modules/@forge/contracts/src/definitions.js

@@ -0,0 +1,176 @@
+"use strict";
+
+function deepFreeze(value, seen = new WeakSet()) {
+  if (!value || typeof value !== "object" || seen.has(value)) return value;
+  seen.add(value);
+  for (const descriptor of Object.values(Object.getOwnPropertyDescriptors(value))) {
+    if (Object.hasOwn(descriptor, "value")) deepFreeze(descriptor.value, seen);
+  }
+  return Object.freeze(value);
+}
+
+const CONTRACTS = deepFreeze({
+  "forge.memory.work-packet.v1": {
+    name: "WorkPacket",
+    identity: ["issue_id", "expected_issue_revision", "packet_id", "packet_revision", "repository_id", "target_head"],
+    required: ["issue_id", "expected_issue_revision", "packet_id", "packet_revision", "repository_id", "target_head", "objective", "authority", "allowed_mutations", "workflow_config_revision", "capability_manifest_digest"],
+    optional: ["acceptance_criteria", "prohibited_actions", "dependencies", "constraints", "risk", "platform", "context_references", "expected_outputs", "target", "receipt_requirements", "idempotency_key", "token_budget", "budget_metric", "risk_manifest_digest"],
+  },
+  "forge.memory.context-packet.v1": {
+    name: "ContextPacket",
+    identity: ["work_packet_hash", "context_selection_revision", "privacy_scope_hash"],
+    required: ["work_packet_hash", "context_selection_revision", "privacy_scope_hash", "retention_class", "disclosure_class"],
+    optional: ["references", "summaries", "redaction_policy_revision"],
+  },
+  "forge.memory.claim-request.v1": {
+    name: "ClaimRequest",
+    identity: ["issue_id", "expected_issue_revision", "actor_id", "request_id"],
+    required: ["issue_id", "expected_issue_revision", "actor_id", "request_id", "requested_scope", "idempotency_key"],
+    optional: [],
+  },
+  "forge.memory.lease-receipt.v1": {
+    name: "LeaseReceipt",
+    identity: ["claim_request_id", "lease_id", "lease_epoch"],
+    required: ["claim_request_id", "lease_id", "lease_epoch", "issue_revision", "actor_id", "scope", "expires_at", "durable", "authority_signature"],
+    optional: [],
+  },
+  "forge.memory.capability-manifest.v1": {
+    name: "CapabilityManifest",
+    identity: ["provider_id", "manifest_revision", "config_revision"],
+    required: ["provider_id", "manifest_revision", "config_revision", "executable_identity", "provider_version", "probe_revision", "result_hash", "capabilities", "evaluator_status", "probed_at", "expires_at"],
+    optional: [],
+  },
+  "forge.memory.run-receipt.v1": {
+    name: "RunReceipt",
+    identity: ["packet_hash", "run_id", "attempt_id", "exact_head"],
+    required: ["packet_hash", "run_id", "attempt_id", "exact_head", "packet_revision", "manifest_digest", "workflow_config_revision", "status", "executor", "started_at", "ended_at", "evidence_refs", "validation", "cleanup"],
+    optional: ["lease_epoch", "tokens", "retries", "corrections", "mutations_attempted", "mutations_authorized", "structured_error", "active_time_ms", "passive_time_ms"],
+  },
+  "forge.memory.feedback-report.v1": {
+    name: "FeedbackReport",
+    identity: ["report_id", "product_version", "content_fingerprint"],
+    required: ["report_id", "product_version", "contract_version", "stable_error_code", "affected_capability", "redacted_reproduction_steps", "expected_classification", "actual_classification", "occurrence_count", "content_fingerprint", "consent_event_id", "redaction_policy_revision"],
+    optional: ["proposed_fix", "return_channel"],
+  },
+  "forge.memory.structured-error.v1": {
+    name: "StructuredError",
+    identity: ["parent_object_hash", "error_occurrence_id"],
+    required: ["parent_object_hash", "error_occurrence_id", "code", "terminal_classification", "safe_details"],
+    optional: ["retryable", "evidence_refs"],
+  },
+  "forge.memory.monitor-event.v1": {
+    name: "MonitorEvent",
+    identity: ["monitor_id", "event_id", "sequence"],
+    required: ["monitor_id", "event_id", "sequence", "subject_revision", "type", "actionability", "observed_at"],
+    optional: ["bounded_payload", "artifact_digest"],
+  },
+  "forge.memory.delivery-receipt.v1": {
+    name: "DeliveryReceipt",
+    identity: ["event_id", "target", "attempt"],
+    required: ["event_id", "target", "transport_tier", "attempt", "delivered_at", "acknowledged", "outcome"],
+    optional: [],
+  },
+  "forge.memory.monitor-receipt.v1": {
+    name: "MonitorReceipt",
+    identity: ["monitor_id", "owner_run_id", "last_sequence"],
+    required: ["monitor_id", "owner_run_id", "terminal_state", "terminal_reason", "last_sequence", "evidence_digest", "cancellation_acknowledged", "process_cleanup", "lease_cleanup"],
+    optional: ["undelivered_cursor"],
+  },
+});
+
+const STRING = Object.freeze({ type: "string", minLength: 1 });
+const INTEGER = Object.freeze({ type: "integer", minimum: 0 });
+const POSITIVE_INTEGER = Object.freeze({ type: "integer", minimum: 1 });
+const BOOLEAN = Object.freeze({ type: "boolean" });
+const OBJECT = Object.freeze({ type: "object" });
+const STRING_ARRAY = Object.freeze({ type: "array", items: { type: "string" } });
+const OBJECT_ARRAY = Object.freeze({ type: "array", items: { type: "object" } });
+const HASH = Object.freeze({ type: "string", pattern: "^[0-9a-f]{64}$" });
+const HEAD = Object.freeze({ type: "string", pattern: "^[0-9a-f]{40}(?:[0-9a-f]{24})?$" });
+const TIMESTAMP = Object.freeze({ type: "string", format: "date-time" });
+const EXTENSION_ID_PATTERN = "^[A-Za-z0-9][A-Za-z0-9_-]*(?:[./][A-Za-z0-9][A-Za-z0-9_-]*)+$";
+const EXTENSION_ID_MAX_LENGTH = 255;
+const SECRET_PATTERN = "(?:gh[pousr]_[A-Za-z0-9]{20,}|sk_(?:live|test)_[A-Za-z0-9]{16,}|sk-[A-Za-z0-9]{16,}|AKIA[0-9A-Z]{16}|(?:api[_-]?key|token|secret|password)\\s*[:=]\\s*\\S{8,})";
+const ABSOLUTE_USER_PATH_PATTERN = "(?:[A-Za-z]:\\\\Users\\\\[^\\\\\\s]+|/(?:Users|home)/[^/\\s]+/)";
+const SAFE_REDACTED_STRING = Object.freeze({ type: "string", minLength: 1, maxLength: 4096, not: { pattern: `${SECRET_PATTERN}|${ABSOLUTE_USER_PATH_PATTERN}` } });
+const SAFE_REDACTED_STEPS = Object.freeze({ type: "array", maxItems: 64, items: SAFE_REDACTED_STRING });
+const BOUNDED_OBJECT = Object.freeze({
+  type: "object",
+  maxProperties: 64,
+  "x-forge-max-depth": 8,
+  "x-forge-max-items": 128,
+  "x-forge-max-serialized-bytes": 16384,
+  "x-forge-secret-pattern": SECRET_PATTERN,
+  "x-forge-absolute-user-path-pattern": ABSOLUTE_USER_PATH_PATTERN,
+});
+const BOUNDED_OBJECT_ARRAY = Object.freeze({ type: "array", maxItems: 128, items: BOUNDED_OBJECT });
+
+const PAYLOAD_FIELDS = deepFreeze({
+  "forge.memory.work-packet.v1": {
+    issue_id: STRING, expected_issue_revision: INTEGER, packet_id: STRING, packet_revision: POSITIVE_INTEGER,
+    repository_id: STRING, target_head: HEAD, objective: STRING,
+    authority: { type: "object", required: ["kind", "issue_revision"], properties: { kind: STRING, issue_revision: INTEGER } },
+    allowed_mutations: STRING_ARRAY, workflow_config_revision: STRING, capability_manifest_digest: HASH,
+    acceptance_criteria: STRING_ARRAY, prohibited_actions: STRING_ARRAY, dependencies: STRING_ARRAY,
+    constraints: OBJECT, risk: OBJECT, platform: OBJECT, context_references: OBJECT_ARRAY,
+    expected_outputs: STRING_ARRAY, target: OBJECT, receipt_requirements: OBJECT, idempotency_key: STRING,
+    token_budget: POSITIVE_INTEGER, budget_metric: { type: "string", enum: ["provider_reported_total_tokens"] }, risk_manifest_digest: HASH,
+  },
+  "forge.memory.context-packet.v1": {
+    work_packet_hash: HASH, context_selection_revision: POSITIVE_INTEGER, privacy_scope_hash: HASH,
+    retention_class: { type: "string", enum: ["public_metadata", "local_sensitive", "remote_redacted", "restricted"] },
+    disclosure_class: { type: "string", enum: ["public_metadata", "local_sensitive", "remote_redacted", "restricted"] },
+    references: BOUNDED_OBJECT_ARRAY, summaries: BOUNDED_OBJECT_ARRAY, redaction_policy_revision: STRING,
+  },
+  "forge.memory.claim-request.v1": {
+    issue_id: STRING, expected_issue_revision: INTEGER, actor_id: STRING, request_id: STRING,
+    requested_scope: OBJECT, idempotency_key: STRING,
+  },
+  "forge.memory.lease-receipt.v1": {
+    claim_request_id: STRING, lease_id: STRING, lease_epoch: POSITIVE_INTEGER, issue_revision: INTEGER,
+    actor_id: STRING, scope: OBJECT, expires_at: TIMESTAMP, durable: BOOLEAN, authority_signature: STRING,
+  },
+  "forge.memory.capability-manifest.v1": {
+    provider_id: STRING, manifest_revision: POSITIVE_INTEGER, config_revision: STRING,
+    executable_identity: OBJECT, provider_version: STRING, probe_revision: STRING, result_hash: HASH,
+    capabilities: { type: "array", items: { type: "object", required: ["capability_id", "available"], properties: { capability_id: STRING, available: BOOLEAN } } },
+    evaluator_status: { type: "string", enum: ["approved", "unavailable", "quarantined"] }, probed_at: TIMESTAMP, expires_at: TIMESTAMP,
+  },
+  "forge.memory.run-receipt.v1": {
+    packet_hash: HASH, run_id: STRING, attempt_id: STRING, exact_head: HEAD, packet_revision: POSITIVE_INTEGER,
+    manifest_digest: HASH, workflow_config_revision: STRING, status: { type: "string", enum: ["PASS", "FAIL", "INCOMPLETE", "NOT_EXECUTED"] },
+    executor: OBJECT, started_at: TIMESTAMP, ended_at: TIMESTAMP, evidence_refs: OBJECT_ARRAY, validation: BOUNDED_OBJECT, cleanup: BOUNDED_OBJECT,
+    lease_epoch: POSITIVE_INTEGER, tokens: OBJECT, retries: INTEGER, corrections: INTEGER,
+    mutations_attempted: STRING_ARRAY, mutations_authorized: STRING_ARRAY, structured_error: BOUNDED_OBJECT,
+    active_time_ms: INTEGER, passive_time_ms: INTEGER,
+  },
+  "forge.memory.feedback-report.v1": {
+    report_id: STRING, product_version: STRING, contract_version: POSITIVE_INTEGER, stable_error_code: STRING,
+    affected_capability: STRING, redacted_reproduction_steps: SAFE_REDACTED_STEPS, expected_classification: STRING,
+    actual_classification: STRING, occurrence_count: POSITIVE_INTEGER, content_fingerprint: HASH,
+    consent_event_id: STRING, redaction_policy_revision: STRING, proposed_fix: SAFE_REDACTED_STRING, return_channel: BOUNDED_OBJECT,
+  },
+  "forge.memory.structured-error.v1": {
+    parent_object_hash: HASH, error_occurrence_id: STRING, code: STRING,
+    terminal_classification: { type: "string", enum: ["FAIL", "INCOMPLETE"] }, safe_details: BOUNDED_OBJECT,
+    retryable: BOOLEAN, evidence_refs: OBJECT_ARRAY,
+  },
+  "forge.memory.monitor-event.v1": {
+    monitor_id: STRING, event_id: STRING, sequence: INTEGER, subject_revision: STRING, type: STRING,
+    actionability: { type: "string", enum: ["advisory", "action_required", "terminal"] }, observed_at: TIMESTAMP,
+    bounded_payload: BOUNDED_OBJECT, artifact_digest: HASH,
+  },
+  "forge.memory.delivery-receipt.v1": {
+    event_id: STRING, target: STRING, transport_tier: { type: "string", enum: ["T0", "T1", "T2", "T3", "T4"] },
+    attempt: POSITIVE_INTEGER, delivered_at: TIMESTAMP, acknowledged: BOOLEAN,
+    outcome: { type: "string", enum: ["delivered", "pending", "failed", "acknowledged"] },
+  },
+  "forge.memory.monitor-receipt.v1": {
+    monitor_id: STRING, owner_run_id: STRING,
+    terminal_state: { type: "string", enum: ["PASS", "FAIL", "INCOMPLETE", "CANCELLED"] }, terminal_reason: STRING,
+    last_sequence: INTEGER, evidence_digest: HASH, cancellation_acknowledged: BOOLEAN,
+    process_cleanup: BOUNDED_OBJECT, lease_cleanup: BOUNDED_OBJECT, undelivered_cursor: INTEGER,
+  },
+});
+
+module.exports = { CONTRACTS, EXTENSION_ID_MAX_LENGTH, EXTENSION_ID_PATTERN, PAYLOAD_FIELDS };

package/node_modules/@forge/contracts/src/identity.js

@@ -0,0 +1,42 @@
+"use strict";
+
+const { canonicalize, computeContentHash } = require("./canonical.js");
+const { CONTRACTS } = require("./definitions.js");
+
+function semanticIdentity(value) {
+  const definition = CONTRACTS[value?.schema_id];
+  if (!definition) throw new TypeError(`Unsupported schema_id: ${value?.schema_id}`);
+  const identity = {};
+  for (const field of definition.identity) {
+    if (!Object.hasOwn(value.payload ?? {}, field)) {
+      throw new TypeError(`Semantic identity requires payload.${field}`);
+    }
+    identity[field] = value.payload[field];
+  }
+  return `${value.schema_id}:${canonicalize(identity)}`;
+}
+
+function classifySemanticAttempt(accepted, candidate) {
+  const acceptedIdentity = semanticIdentity(accepted);
+  const candidateIdentity = semanticIdentity(candidate);
+  if (acceptedIdentity !== candidateIdentity) {
+    return { status: "new-identity", identity: candidateIdentity };
+  }
+  const acceptedHash = computeContentHash(accepted);
+  const candidateHash = computeContentHash(candidate);
+  if (acceptedHash === candidateHash) {
+    return {
+      status: "retry-identical",
+      identity: candidateIdentity,
+      content_hash: candidateHash,
+    };
+  }
+  return {
+    status: "identity-conflict",
+    identity: candidateIdentity,
+    accepted_hash: acceptedHash,
+    candidate_hash: candidateHash,
+  };
+}
+
+module.exports = { classifySemanticAttempt, semanticIdentity };

package/node_modules/@forge/contracts/src/schema.js

@@ -0,0 +1,72 @@
+"use strict";
+
+const {
+  CONTRACTS,
+  EXTENSION_ID_MAX_LENGTH,
+  EXTENSION_ID_PATTERN,
+  PAYLOAD_FIELDS,
+} = require("./definitions.js");
+
+function generateJsonSchema(schemaId) {
+  const definition = Object.hasOwn(CONTRACTS, schemaId) ? CONTRACTS[schemaId] : undefined;
+  if (!definition) throw new TypeError(`Unsupported schema_id: ${schemaId}`);
+  const payloadProperties = {};
+  for (const field of [...definition.required, ...definition.optional]) payloadProperties[field] = structuredClone(PAYLOAD_FIELDS[schemaId][field]);
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: schemaId,
+    title: definition.name,
+    type: "object",
+    required: ["schema_id", "schema_version", "object_id", "created_at", "producer", "capabilities_used", "provenance", "content_hash", "payload", "extensions"],
+    properties: {
+      schema_id: { const: schemaId },
+      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: definition.required, properties: payloadProperties, additionalProperties: false },
+      extensions: {
+        type: "object",
+        propertyNames: { pattern: EXTENSION_ID_PATTERN, maxLength: EXTENSION_ID_MAX_LENGTH },
+        additionalProperties: {
+          type: "object",
+          required: ["impact", "schema_version", "value"],
+          properties: {
+            impact: { const: "advisory" },
+            schema_version: { type: "integer", minimum: 1 },
+            value: {},
+          },
+          additionalProperties: false,
+        },
+      },
+    },
+    additionalProperties: false,
+  };
+}
+
+function supportedSchemaVersions(schemaId) {
+  return Object.hasOwn(CONTRACTS, schemaId) ? [1] : [];
+}
+
+module.exports = { generateJsonSchema, supportedSchemaVersions };

package/node_modules/@forge/contracts/src/validate.js

@@ -0,0 +1,305 @@
+"use strict";
+
+const { canonicalize, computeContentHash, preflightCanonicalValue } = require("./canonical.js");
+const {
+  CONTRACTS,
+  EXTENSION_ID_MAX_LENGTH,
+  EXTENSION_ID_PATTERN,
+  PAYLOAD_FIELDS,
+} = require("./definitions.js");
+
+const ENVELOPE_FIELDS = Object.freeze([
+  "schema_id", "schema_version", "object_id", "created_at", "producer",
+  "capabilities_used", "provenance", "content_hash", "payload", "extensions",
+]);
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const SHA256 = /^[0-9a-f]{64}$/;
+const RFC3339_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+const LIVE_EVIDENCE_FIELDS = Object.freeze({
+  "forge.memory.work-packet.v1": ["issueRevision", "workflowConfigRevision", "capabilityManifestDigest", "exactHead"],
+  "forge.memory.context-packet.v1": ["workPacketHash", "privacyScopeHash", "redactionPolicyRevision", "allowedDisclosureClasses"],
+  "forge.memory.claim-request.v1": ["issueRevision", "actorId"],
+  "forge.memory.lease-receipt.v1": ["issueRevision", "actorId", "leaseEpoch", "observedAt"],
+  "forge.memory.capability-manifest.v1": ["providerId", "configRevision", "observedAt"],
+  "forge.memory.run-receipt.v1": ["packetHash", "workflowConfigRevision", "capabilityManifestDigest", "exactHead"],
+  "forge.memory.feedback-report.v1": ["consentEventId", "redactionPolicyRevision"],
+  "forge.memory.structured-error.v1": ["parentObjectHash"],
+  "forge.memory.monitor-event.v1": ["monitorId", "subjectRevision"],
+  "forge.memory.delivery-receipt.v1": ["eventId", "target"],
+  "forge.memory.monitor-receipt.v1": ["monitorId", "ownerRunId"],
+});
+const EXTENSION_ID = new RegExp(EXTENSION_ID_PATTERN);
+const SECRET_PATTERN = /(?:gh[pousr]_[A-Za-z0-9]{20,}|sk_(?:live|test)_[A-Za-z0-9]{16,}|sk-[A-Za-z0-9]{16,}|AKIA[0-9A-Z]{16}|(?:api[_-]?key|token|secret|password)\s*[:=]\s*\S{8,})/i;
+const ABSOLUTE_USER_PATH = /(?:[A-Za-z]:\\Users\\[^\\\s]+|\/(?:Users|home)\/[^/\s]+\/)/i;
+const BOUNDED_LIMITS = Object.freeze({ maxDepth: 8, maxItems: 128, maxProperties: 64, maxBytes: 16_384 });
+
+function error(errors, path, code) {
+  errors.push({ path, code });
+}
+
+function validateEnvelope(value, options = {}) {
+  const errors = [];
+  try {
+    preflightCanonicalValue(value);
+  } catch {
+    return { ok: false, errors: [{ path: "$", code: "NON_CANONICAL_VALUE" }] };
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return { ok: false, errors: [{ path: "$", code: "INVALID_ENVELOPE" }] };
+  }
+  for (const field of ENVELOPE_FIELDS) {
+    if (!Object.hasOwn(value, field)) error(errors, `$.${field}`, "MISSING_REQUIRED");
+  }
+  if (errors.length > 0) return { ok: false, errors };
+  if (!Object.hasOwn(CONTRACTS, value.schema_id)) error(errors, "$.schema_id", "UNSUPPORTED_SCHEMA");
+  if (value.schema_version !== 1) error(errors, "$.schema_version", "UNSUPPORTED_VERSION");
+  if (typeof value.schema_id !== "string" || value.schema_id.length === 0) error(errors, "$.schema_id", "INVALID_TYPE");
+  if (!UUID.test(value.object_id)) error(errors, "$.object_id", "INVALID_UUID");
+  if (typeof value.created_at !== "string" || !RFC3339_UTC.test(value.created_at) || Number.isNaN(Date.parse(value.created_at))) error(errors, "$.created_at", "INVALID_TIMESTAMP");
+  if (!value.producer || typeof value.producer !== "object" || Array.isArray(value.producer)) error(errors, "$.producer", "INVALID_TYPE");
+  else for (const field of ["product_id", "product_version", "instance_id"]) if (typeof value.producer[field] !== "string" || value.producer[field].length === 0) error(errors, `$.producer.${field}`, "MISSING_REQUIRED");
+  if (!Array.isArray(value.capabilities_used)) error(errors, "$.capabilities_used", "INVALID_TYPE");
+  else {
+    const keys = value.capabilities_used.map((item) => `${item?.capability_id ?? ""}:${item?.manifest_digest ?? ""}`);
+    if (value.capabilities_used.some((item) => !item || typeof item !== "object" || Array.isArray(item) || typeof item.capability_id !== "string" || item.capability_id.length === 0 || !SHA256.test(item.manifest_digest))) {
+      error(errors, "$.capabilities_used", "INVALID_CAPABILITY_BINDING");
+    }
+    if (keys.join("\0") !== [...keys].sort().join("\0")) error(errors, "$.capabilities_used", "NOT_SORTED");
+  }
+  if (!value.provenance || typeof value.provenance !== "object" || Array.isArray(value.provenance)) error(errors, "$.provenance", "INVALID_TYPE");
+  else for (const field of ["source_kind", "actor_class", "actor_id"]) if (typeof value.provenance[field] !== "string" || value.provenance[field].length === 0) error(errors, `$.provenance.${field}`, "MISSING_REQUIRED");
+  if (!SHA256.test(value.content_hash)) error(errors, "$.content_hash", "INVALID_CONTENT_HASH");
+  if (!value.payload || typeof value.payload !== "object" || Array.isArray(value.payload)) error(errors, "$.payload", "INVALID_TYPE");
+  if (!value.extensions || typeof value.extensions !== "object" || Array.isArray(value.extensions)) error(errors, "$.extensions", "INVALID_TYPE");
+  if (options.verifyHash !== false && SHA256.test(value.content_hash)) {
+    try {
+      if (computeContentHash(value) !== value.content_hash) error(errors, "$.content_hash", "CONTENT_HASH_MISMATCH");
+    } catch {
+      error(errors, "$", "NON_CANONICAL_VALUE");
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+function validateExtensions(extensions, errors) {
+  if (!extensions || typeof extensions !== "object" || Array.isArray(extensions)) return;
+  for (const [extensionId, extension] of Object.entries(extensions)) {
+    const path = `$.extensions[${JSON.stringify(extensionId)}]`;
+    if (extensionId.length > EXTENSION_ID_MAX_LENGTH || !EXTENSION_ID.test(extensionId)) error(errors, path, "INVALID_EXTENSION_ID");
+    if (!extension || typeof extension !== "object" || Array.isArray(extension)) {
+      error(errors, path, "INVALID_EXTENSION");
+      continue;
+    }
+    if (extension.impact === "consequential") error(errors, path, "UNKNOWN_CONSEQUENTIAL_EXTENSION");
+    const allowed = new Set(["impact", "schema_version", "value"]);
+    const hasExtra = Object.keys(extension).some((field) => !allowed.has(field));
+    if (extension.impact !== "advisory" || !Number.isInteger(extension.schema_version) || extension.schema_version < 1 || !Object.hasOwn(extension, "value") || hasExtra) error(errors, path, "INVALID_EXTENSION");
+  }
+}
+
+function compare(errors, actual, expected, path, code) {
+  if (expected !== undefined && actual !== expected) error(errors, path, code);
+}
+
+function isType(value, type) {
+  if (type === "integer") return Number.isInteger(value);
+  if (type === "array") return Array.isArray(value);
+  if (type === "object") return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+  return typeof value === type;
+}
+
+function validateShape(value, shape, path, errors) {
+  if (!isType(value, shape.type)) {
+    error(errors, path, "INVALID_TYPE");
+    return;
+  }
+  if (shape.enum && !shape.enum.includes(value)) error(errors, path, "INVALID_ENUM");
+  if (shape.minLength !== undefined && value.length < shape.minLength) error(errors, path, "INVALID_LENGTH");
+  if (shape.maxLength !== undefined && value.length > shape.maxLength) error(errors, path, "BOUNDED_VALUE_TOO_LARGE");
+  if (shape.minimum !== undefined && value < shape.minimum) error(errors, path, "OUT_OF_RANGE");
+  if (shape.pattern && !new RegExp(shape.pattern).test(value)) error(errors, path, "INVALID_FORMAT");
+  if (shape.not?.pattern && new RegExp(shape.not.pattern, "i").test(value)) error(errors, path, "PRIVACY_PATTERN_REJECTED");
+  if (shape.format === "date-time" && (!RFC3339_UTC.test(value) || Number.isNaN(Date.parse(value)))) error(errors, path, "INVALID_TIMESTAMP");
+  if (shape.type === "array" && shape.maxItems !== undefined && value.length > shape.maxItems) error(errors, path, "BOUNDED_VALUE_TOO_MANY_ITEMS");
+  if (shape.type === "array" && shape.items) value.forEach((item, index) => validateShape(item, shape.items, `${path}[${index}]`, errors));
+  if (shape.type === "object") {
+    if (shape.maxProperties !== undefined && Object.keys(value).length > shape.maxProperties) error(errors, path, "BOUNDED_VALUE_TOO_MANY_PROPERTIES");
+    for (const field of shape.required ?? []) {
+      if (!Object.hasOwn(value, field)) error(errors, `${path}.${field}`, "MISSING_REQUIRED");
+    }
+    for (const [field, fieldShape] of Object.entries(shape.properties ?? {})) {
+      if (Object.hasOwn(value, field)) validateShape(value[field], fieldShape, `${path}.${field}`, errors);
+    }
+    if (shape.additionalProperties === false) {
+      const allowed = new Set(Object.keys(shape.properties ?? {}));
+      for (const field of Object.keys(value)) if (!allowed.has(field)) error(errors, `${path}.${field}`, "UNKNOWN_FIELD");
+    }
+  }
+}
+
+function inspectPrivacyString(value, path, errors) {
+  if (SECRET_PATTERN.test(value)) error(errors, path, "PRIVACY_SECRET_PATTERN");
+  if (ABSOLUTE_USER_PATH.test(value)) error(errors, path, "PRIVACY_ABSOLUTE_PATH");
+}
+
+function inspectBoundedValue(value, path, errors, depth = 0) {
+  if (depth > BOUNDED_LIMITS.maxDepth) {
+    error(errors, path, "BOUNDED_VALUE_TOO_DEEP");
+    return;
+  }
+  if (typeof value === "string") {
+    inspectPrivacyString(value, path, errors);
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (value.length > BOUNDED_LIMITS.maxItems) error(errors, path, "BOUNDED_VALUE_TOO_MANY_ITEMS");
+    value.forEach((item, index) => inspectBoundedValue(item, `${path}[${index}]`, errors, depth + 1));
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  const entries = Object.entries(value);
+  if (entries.length > BOUNDED_LIMITS.maxProperties) error(errors, path, "BOUNDED_VALUE_TOO_MANY_PROPERTIES");
+  entries.forEach(([field, item]) => inspectBoundedValue(item, `${path}.${field}`, errors, depth + 1));
+}
+
+function validateBoundedPrivacy(value, errors) {
+  const targets = [];
+  if (value?.schema_id === "forge.memory.feedback-report.v1") {
+    targets.push([value.payload?.redacted_reproduction_steps, "$.payload.redacted_reproduction_steps"]);
+    if (value.payload?.proposed_fix !== undefined) targets.push([value.payload.proposed_fix, "$.payload.proposed_fix"]);
+    if (value.payload?.return_channel !== undefined) targets.push([value.payload.return_channel, "$.payload.return_channel"]);
+  } else if (value?.schema_id === "forge.memory.context-packet.v1") {
+    if (value.payload?.references !== undefined) targets.push([value.payload.references, "$.payload.references"]);
+    if (value.payload?.summaries !== undefined) targets.push([value.payload.summaries, "$.payload.summaries"]);
+  } else if (value?.schema_id === "forge.memory.monitor-event.v1" && value.payload?.bounded_payload !== undefined) {
+    targets.push([value.payload.bounded_payload, "$.payload.bounded_payload"]);
+  } else if (value?.schema_id === "forge.memory.monitor-receipt.v1") {
+    targets.push([value.payload?.process_cleanup, "$.payload.process_cleanup"], [value.payload?.lease_cleanup, "$.payload.lease_cleanup"]);
+  } else if (value?.schema_id === "forge.memory.structured-error.v1") {
+    targets.push([value.payload?.safe_details, "$.payload.safe_details"]);
+  } else if (value?.schema_id === "forge.memory.run-receipt.v1") {
+    targets.push(
+      [value.payload?.validation, "$.payload.validation"],
+      [value.payload?.cleanup, "$.payload.cleanup"],
+    );
+    if (value.payload?.structured_error !== undefined) targets.push([value.payload.structured_error, "$.payload.structured_error"]);
+  }
+  for (const [target, path] of targets) {
+    if (target === undefined) continue;
+    inspectBoundedValue(target, path, errors);
+    try {
+      canonicalize(target, { maxDepth: 64, maxNodes: 100_000, maxBytes: BOUNDED_LIMITS.maxBytes });
+    } catch (failure) {
+      if (failure.code === "CANONICAL_BYTE_LIMIT") error(errors, path, "BOUNDED_VALUE_TOO_LARGE");
+    }
+  }
+}
+
+function isStale(expiresAt, observedAt) {
+  const expires = Date.parse(expiresAt);
+  const observed = Date.parse(observedAt);
+  return Number.isNaN(expires) || Number.isNaN(observed) || expires <= observed;
+}
+
+function validateConsequentialEvidence(value, expected, errors) {
+  if (!value?.payload) return;
+  if (value.schema_id === "forge.memory.run-receipt.v1" && value.payload.status === "NOT_EXECUTED") {
+    error(errors, "$.payload.status", "NOT_EXECUTED_NO_TRANSITION");
+  }
+  const requiredEvidence = LIVE_EVIDENCE_FIELDS[value.schema_id] ?? [];
+  for (const field of requiredEvidence) {
+    if (!expected || !Object.hasOwn(expected, field)) error(errors, `$.live_expected.${field}`, "MISSING_LIVE_EVIDENCE");
+  }
+  if (!expected) return;
+  const payload = value.payload;
+  if (value.schema_id === "forge.memory.work-packet.v1") {
+    compare(errors, payload.expected_issue_revision, expected.issueRevision, "$.payload.expected_issue_revision", "STALE_ISSUE_REVISION");
+    compare(errors, payload.workflow_config_revision, expected.workflowConfigRevision, "$.payload.workflow_config_revision", "STALE_WORKFLOW_CONFIG");
+    compare(errors, payload.capability_manifest_digest, expected.capabilityManifestDigest, "$.payload.capability_manifest_digest", "WRONG_CAPABILITY_DIGEST");
+    compare(errors, payload.target_head, expected.exactHead, "$.payload.target_head", "STALE_EXACT_HEAD");
+  } else if (value.schema_id === "forge.memory.context-packet.v1") {
+    compare(errors, payload.work_packet_hash, expected.workPacketHash, "$.payload.work_packet_hash", "STALE_WORK_PACKET");
+    compare(errors, payload.privacy_scope_hash, expected.privacyScopeHash, "$.payload.privacy_scope_hash", "STALE_PRIVACY_SCOPE");
+    compare(errors, payload.redaction_policy_revision, expected.redactionPolicyRevision, "$.payload.redaction_policy_revision", "STALE_REDACTION_POLICY");
+    if (expected.allowedDisclosureClasses && !expected.allowedDisclosureClasses.includes(payload.disclosure_class)) {
+      error(errors, "$.payload.disclosure_class", "DISCLOSURE_NOT_ALLOWED");
+    }
+  } else if (value.schema_id === "forge.memory.run-receipt.v1") {
+    compare(errors, payload.packet_hash, expected.packetHash, "$.payload.packet_hash", "STALE_WORK_PACKET");
+    compare(errors, payload.workflow_config_revision, expected.workflowConfigRevision, "$.payload.workflow_config_revision", "STALE_WORKFLOW_CONFIG");
+    compare(errors, payload.manifest_digest, expected.capabilityManifestDigest, "$.payload.manifest_digest", "WRONG_CAPABILITY_DIGEST");
+    compare(errors, payload.exact_head, expected.exactHead, "$.payload.exact_head", "STALE_EXACT_HEAD");
+    compare(errors, payload.lease_epoch, expected.leaseEpoch, "$.payload.lease_epoch", "STALE_LEASE_EPOCH");
+  } else if (value.schema_id === "forge.memory.claim-request.v1") {
+    compare(errors, payload.expected_issue_revision, expected.issueRevision, "$.payload.expected_issue_revision", "STALE_ISSUE_REVISION");
+    compare(errors, payload.actor_id, expected.actorId, "$.payload.actor_id", "STALE_ACTOR");
+  } else if (value.schema_id === "forge.memory.lease-receipt.v1") {
+    compare(errors, payload.issue_revision, expected.issueRevision, "$.payload.issue_revision", "STALE_ISSUE_REVISION");
+    compare(errors, payload.actor_id, expected.actorId, "$.payload.actor_id", "STALE_ACTOR");
+    compare(errors, payload.lease_epoch, expected.leaseEpoch, "$.payload.lease_epoch", "STALE_LEASE_EPOCH");
+    if (isStale(payload.expires_at, expected.observedAt)) error(errors, "$.payload.expires_at", "STALE_LEASE");
+  } else if (value.schema_id === "forge.memory.capability-manifest.v1") {
+    compare(errors, payload.provider_id, expected.providerId, "$.payload.provider_id", "STALE_PROVIDER");
+    compare(errors, payload.config_revision, expected.configRevision, "$.payload.config_revision", "STALE_CAPABILITY_CONFIG");
+    if (isStale(payload.expires_at, expected.observedAt)) error(errors, "$.payload.expires_at", "STALE_CAPABILITY_MANIFEST");
+  } else if (value.schema_id === "forge.memory.feedback-report.v1") {
+    compare(errors, payload.consent_event_id, expected.consentEventId, "$.payload.consent_event_id", "STALE_CONSENT");
+    compare(errors, payload.redaction_policy_revision, expected.redactionPolicyRevision, "$.payload.redaction_policy_revision", "STALE_REDACTION_POLICY");
+  } else if (value.schema_id === "forge.memory.structured-error.v1") {
+    compare(errors, payload.parent_object_hash, expected.parentObjectHash, "$.payload.parent_object_hash", "STALE_PARENT_OBJECT");
+  } else if (value.schema_id === "forge.memory.monitor-event.v1") {
+    compare(errors, payload.monitor_id, expected.monitorId, "$.payload.monitor_id", "STALE_MONITOR");
+    compare(errors, payload.subject_revision, expected.subjectRevision, "$.payload.subject_revision", "STALE_SUBJECT");
+  } else if (value.schema_id === "forge.memory.delivery-receipt.v1") {
+    compare(errors, payload.event_id, expected.eventId, "$.payload.event_id", "STALE_EVENT");
+    compare(errors, payload.target, expected.target, "$.payload.target", "STALE_DELIVERY_TARGET");
+  } else if (value.schema_id === "forge.memory.monitor-receipt.v1") {
+    compare(errors, payload.monitor_id, expected.monitorId, "$.payload.monitor_id", "STALE_MONITOR");
+    compare(errors, payload.owner_run_id, expected.ownerRunId, "$.payload.owner_run_id", "STALE_OWNER_RUN");
+  }
+}
+
+function validateContractStructure(value, options = {}) {
+  const envelope = validateEnvelope(value, options);
+  if (envelope.errors.some((item) => item.code === "NON_CANONICAL_VALUE")) return envelope;
+  const errors = [...envelope.errors];
+  const definition = Object.hasOwn(CONTRACTS, value?.schema_id) ? CONTRACTS[value.schema_id] : undefined;
+  if (definition && value?.payload && typeof value.payload === "object" && !Array.isArray(value.payload)) {
+    for (const field of definition.required) {
+      if (!Object.hasOwn(value.payload, field)) error(errors, `$.payload.${field}`, "MISSING_REQUIRED");
+    }
+    const allowed = new Set([...definition.required, ...definition.optional]);
+    for (const field of Object.keys(value.payload)) {
+      if (!allowed.has(field)) error(errors, `$.payload.${field}`, "UNKNOWN_PAYLOAD_FIELD");
+      else validateShape(value.payload[field], PAYLOAD_FIELDS[value.schema_id][field], `$.payload.${field}`, errors);
+    }
+  }
+  validateExtensions(value?.extensions, errors);
+  if (!errors.some((item) => item.code === "NON_CANONICAL_VALUE")) validateBoundedPrivacy(value, errors);
+  return { ok: errors.length === 0, errors };
+}
+
+function validateContract(value, options = {}) {
+  const structural = validateContractStructure(value, options);
+  if (structural.errors.some((item) => item.code === "NON_CANONICAL_VALUE")) return structural;
+  const errors = [...structural.errors];
+  validateConsequentialEvidence(value, options.expected, errors);
+  return { ok: errors.length === 0, errors };
+}
+
+class ContractValidationError extends Error {
+  constructor(errors) {
+    super("Contract validation failed");
+    this.name = "ContractValidationError";
+    this.errors = errors;
+  }
+}
+
+function parseContract(json, options = {}) {
+  const value = JSON.parse(json);
+  const result = validateContract(value, options);
+  if (!result.ok) throw new ContractValidationError(result.errors);
+  return value;
+}
+
+module.exports = { ContractValidationError, ENVELOPE_FIELDS, parseContract, validateContract, validateContractStructure, validateEnvelope };