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

package/packages/flow/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/packages/flow/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 };

package/packages/memory/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/packages/memory/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/packages/memory/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/packages/memory/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/packages/memory/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/packages/memory/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/packages/memory/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/packages/memory/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"}}