proof-harness 0.1.0-next.1

package/dist/node.js

@@ -0,0 +1,553 @@
+// src/shared/portable-vocabulary.mjs
+var ACTION_CHANGE_KINDS = (
+  /** @type {const} */
+  [
+    "added",
+    "removed",
+    "middleware_changed",
+    "invariants_changed",
+    "service_role_mutations_changed",
+    "metadata_changed"
+  ]
+);
+var TABLE_CHANGE_KINDS = (
+  /** @type {const} */
+  [
+    "added",
+    "removed",
+    "columns_added",
+    "columns_removed",
+    "rls_classification_changed",
+    "policies_changed"
+  ]
+);
+var TENANT_ISOLATION_TABLE_HELPERS = (
+  /** @type {const} */
+  [
+    "assert.tenantIsolation"
+  ]
+);
+var TENANT_ISOLATION_ACTION_HELPERS = (
+  /** @type {const} */
+  [
+    "assert.tenantIsolation",
+    "assert.authorization"
+  ]
+);
+
+// src/shared/mission-types.ts
+var MISSION_MANIFEST_SCHEMA_VERSION = 1;
+function requiredEvidenceOrigin(kind, evidence) {
+  if (kind === "tenant_isolation") return "helper";
+  return evidence ?? "any";
+}
+
+// src/shared/vocabulary.ts
+var PROOF_VERBS = [
+  "create",
+  "read",
+  "update",
+  "delete",
+  "invoke",
+  "transfer"
+];
+var PROOF_KINDS = [
+  "happy_path",
+  "tenant_isolation",
+  "authorization",
+  "validation",
+  "error_handling",
+  "idempotency"
+];
+var RLS_CLASSIFICATIONS = [
+  "workspace_scoped",
+  "user_scoped",
+  "admin_only",
+  "public_read",
+  "service_only",
+  "unclassified"
+];
+var POLICY_COMMANDS = [
+  "SELECT",
+  "INSERT",
+  "UPDATE",
+  "DELETE",
+  "ALL"
+];
+function isProofVerb(value) {
+  return typeof value === "string" && PROOF_VERBS.includes(value);
+}
+function isProofKind(value) {
+  return typeof value === "string" && PROOF_KINDS.includes(value);
+}
+function isRlsClassification(value) {
+  return typeof value === "string" && RLS_CLASSIFICATIONS.includes(value);
+}
+function isPolicyCommand(value) {
+  return typeof value === "string" && POLICY_COMMANDS.includes(value);
+}
+
+// src/shared/trace-types.ts
+var ASSERTION_ROLE_ALIASES = {
+  negative: "primary",
+  positive_control: "control"
+};
+function normalizeAssertionRole(role) {
+  if (role === void 0 || role === null) return "primary";
+  if (role === "primary" || role === "control") return role;
+  if (typeof role === "string" && role in ASSERTION_ROLE_ALIASES) {
+    return ASSERTION_ROLE_ALIASES[role];
+  }
+  return null;
+}
+
+// src/node/validate-mission.ts
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function expectedChangesShapeIssues(block) {
+  const issues = [];
+  if (block === void 0) return issues;
+  if (!block || typeof block !== "object" || Array.isArray(block)) {
+    issues.push({
+      category: "manifest_shape",
+      message: "expectedChanges must be an object when present"
+    });
+    return issues;
+  }
+  const changes = block;
+  for (const key of ["modules", "dependencies"]) {
+    const list = changes[key];
+    if (list === void 0) continue;
+    if (!Array.isArray(list) || !list.every(isNonEmptyString)) {
+      issues.push({
+        category: "manifest_shape",
+        message: `expectedChanges.${key} must be an array of non-empty strings when present`
+      });
+    }
+  }
+  const validateEntryList = (key, nameField, kinds) => {
+    const list = changes[key];
+    if (list === void 0) return;
+    if (!Array.isArray(list)) {
+      issues.push({
+        category: "manifest_shape",
+        message: `expectedChanges.${key} must be an array when present`
+      });
+      return;
+    }
+    for (const entry of list) {
+      if (isNonEmptyString(entry)) continue;
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        issues.push({
+          category: "manifest_shape",
+          message: `expectedChanges.${key} entries must be non-empty strings or { ${nameField}, changes? } objects`
+        });
+        continue;
+      }
+      const record = entry;
+      if (!isNonEmptyString(record[nameField])) {
+        issues.push({
+          category: "manifest_shape",
+          message: `expectedChanges.${key}[].${nameField} is required (non-empty string)`
+        });
+      }
+      if (record.changes !== void 0) {
+        if (!Array.isArray(record.changes) || record.changes.length === 0 || !record.changes.every((c) => kinds.includes(c))) {
+          issues.push({
+            category: "manifest_shape",
+            message: `expectedChanges.${key}[].changes must be a non-empty array drawn from: ${kinds.join(", ")}`
+          });
+        }
+      }
+    }
+  };
+  validateEntryList("actions", "ref", ACTION_CHANGE_KINDS);
+  validateEntryList("tables", "name", TABLE_CHANGE_KINDS);
+  if (changes.lockfile !== void 0 && typeof changes.lockfile !== "boolean") {
+    issues.push({
+      category: "manifest_shape",
+      message: "expectedChanges.lockfile must be a boolean when present"
+    });
+  }
+  return issues;
+}
+function shapeIssues(manifest) {
+  const issues = [];
+  if (!manifest || typeof manifest !== "object") {
+    issues.push({
+      category: "manifest_shape",
+      message: "manifest is not a JSON object"
+    });
+    return issues;
+  }
+  const m = manifest;
+  if (m.schemaVersion !== MISSION_MANIFEST_SCHEMA_VERSION) {
+    issues.push({
+      category: "manifest_shape",
+      message: `expected schemaVersion=${MISSION_MANIFEST_SCHEMA_VERSION}, found ${String(m.schemaVersion)}`
+    });
+  }
+  if (typeof m.missionId !== "string" || m.missionId.length === 0) {
+    issues.push({
+      category: "manifest_shape",
+      message: "missionId is required (non-empty string)"
+    });
+  }
+  if (typeof m.missionTitle !== "string" || m.missionTitle.length === 0) {
+    issues.push({
+      category: "manifest_shape",
+      message: "missionTitle is required (non-empty string)"
+    });
+  }
+  if (typeof m.createdAt !== "string" || m.createdAt.length === 0) {
+    issues.push({
+      category: "manifest_shape",
+      message: "createdAt is required (ISO-8601 string)"
+    });
+  }
+  issues.push(...expectedChangesShapeIssues(m.expectedChanges));
+  const req = m.requirements;
+  if (!req || typeof req !== "object") {
+    issues.push({
+      category: "manifest_shape",
+      message: "requirements block is required"
+    });
+    return issues;
+  }
+  if (!Array.isArray(req.capabilities_must_exist)) {
+    issues.push({
+      category: "manifest_shape",
+      message: "requirements.capabilities_must_exist must be an array"
+    });
+  }
+  if (!Array.isArray(req.schema_must_contain)) {
+    issues.push({
+      category: "manifest_shape",
+      message: "requirements.schema_must_contain must be an array"
+    });
+  }
+  if (!Array.isArray(req.trace_must_prove)) {
+    issues.push({
+      category: "manifest_shape",
+      message: "requirements.trace_must_prove must be an array"
+    });
+  }
+  if (req.policies_must_not_allow !== void 0 && !Array.isArray(req.policies_must_not_allow)) {
+    issues.push({
+      category: "manifest_shape",
+      message: "requirements.policies_must_not_allow must be an array when present"
+    });
+  }
+  for (const cap of req.capabilities_must_exist ?? []) {
+    if (!isProofVerb(cap.verb)) {
+      issues.push({
+        category: "manifest_shape",
+        message: `capabilities_must_exist[].verb "${String(cap.verb)}" is not in PROOF_VERBS`
+      });
+    }
+  }
+  for (const s of req.schema_must_contain ?? []) {
+    if (!isRlsClassification(
+      s.rls_classification
+    )) {
+      issues.push({
+        category: "manifest_shape",
+        message: `schema_must_contain[].rls_classification "${String(s.rls_classification)}" is not in RLS_CLASSIFICATIONS`
+      });
+    }
+  }
+  for (const t of req.trace_must_prove ?? []) {
+    if (!isProofKind(t.kind)) {
+      issues.push({
+        category: "manifest_shape",
+        message: `trace_must_prove[].kind "${String(t.kind)}" is not in PROOF_KINDS`
+      });
+    }
+    const evidence = t.evidence;
+    if (evidence !== void 0 && evidence !== "helper" && evidence !== "any") {
+      issues.push({
+        category: "manifest_shape",
+        message: `trace_must_prove[].evidence "${String(evidence)}" is not a valid evidence origin; expected "helper" or "any"`
+      });
+    }
+    if (evidence === "any" && t.kind === "tenant_isolation") {
+      issues.push({
+        category: "manifest_shape",
+        message: 'trace_must_prove[].evidence "any" is not allowed for kind "tenant_isolation"; isolation evidence must come from an SDK helper (assert.tenantIsolation, or assert.authorization for action targets)'
+      });
+    }
+  }
+  for (const p of Array.isArray(req.policies_must_not_allow) ? req.policies_must_not_allow : []) {
+    const prohibition = p;
+    if (typeof prohibition.role !== "string" || prohibition.role.length === 0) {
+      issues.push({
+        category: "manifest_shape",
+        message: "policies_must_not_allow[].role is required (non-empty database role name)"
+      });
+    }
+    if (prohibition.commands !== void 0) {
+      if (!Array.isArray(prohibition.commands)) {
+        issues.push({
+          category: "manifest_shape",
+          message: "policies_must_not_allow[].commands must be an array when present"
+        });
+      } else {
+        for (const command of prohibition.commands) {
+          if (!isPolicyCommand(command)) {
+            issues.push({
+              category: "manifest_shape",
+              message: `policies_must_not_allow[].commands entry "${String(command)}" is not in POLICY_COMMANDS`
+            });
+          }
+        }
+      }
+    }
+  }
+  return issues;
+}
+function checkCapabilities(manifest, capabilities) {
+  const issues = [];
+  for (const req of manifest.requirements.capabilities_must_exist) {
+    const match = capabilities.capabilities.find(
+      (c) => c.name === req.name && c.module === req.module
+    );
+    if (!match) {
+      issues.push({
+        category: "capability_missing",
+        message: `expected capability ${req.module}:${req.name} (verb=${req.verb}, object=${req.object}); not found in capabilities.json`,
+        context: { requirement: req }
+      });
+      continue;
+    }
+    if (match.verb !== req.verb) {
+      issues.push({
+        category: "capability_mismatch",
+        message: `capability ${req.module}:${req.name} has verb="${match.verb ?? "<missing>"}" but manifest requires "${req.verb}"; add or update withProof({ verb }) on the action`,
+        context: { requirement: req, found: match }
+      });
+    }
+    if (req.object && match.object !== req.object) {
+      issues.push({
+        category: "capability_mismatch",
+        message: `capability ${req.module}:${req.name} has object="${match.object ?? "<missing>"}" but manifest requires "${req.object}"; add or update withProof({ object }) on the action`,
+        context: { requirement: req, found: match }
+      });
+    }
+    if (req.invariants && req.invariants.length > 0) {
+      const missing = req.invariants.filter(
+        (inv) => !match.invariants.includes(inv)
+      );
+      if (missing.length > 0) {
+        issues.push({
+          category: "capability_mismatch",
+          message: `capability ${req.module}:${req.name} is missing invariants: ${missing.join(", ")}; add them to withProof({ invariants })`,
+          context: { requirement: req, found: match, missing }
+        });
+      }
+    }
+  }
+  return issues;
+}
+function checkSchema(manifest, schema) {
+  const issues = [];
+  for (const req of manifest.requirements.schema_must_contain) {
+    const table = schema.tables.find((t) => t.name === req.table);
+    if (!table) {
+      issues.push({
+        category: "schema_missing",
+        message: `expected table "${req.table}" not found in schema.json; add a CREATE TABLE migration`,
+        context: { requirement: req }
+      });
+      continue;
+    }
+    const missingCols = req.required_columns.filter(
+      (c) => !table.columns.includes(c)
+    );
+    if (missingCols.length > 0) {
+      issues.push({
+        category: "schema_column_missing",
+        message: `table "${req.table}" is missing columns: ${missingCols.join(", ")}; found columns: ${table.columns.join(", ")}`,
+        context: {
+          requirement: req,
+          missing: missingCols,
+          found: table.columns
+        }
+      });
+    }
+    if (table.rls_classification !== req.rls_classification) {
+      issues.push({
+        category: "schema_rls_mismatch",
+        message: `table "${req.table}" has rls_classification="${table.rls_classification}" but manifest requires "${req.rls_classification}"; review RLS policies on the table`,
+        context: { requirement: req, found: table.rls_classification }
+      });
+    }
+  }
+  return issues;
+}
+function policyGrantsRole(policy, role) {
+  if (policy.roles.length === 0) return true;
+  return policy.roles.some(
+    (r) => r === role || r === "public" || r === "PUBLIC"
+  );
+}
+function policyMatchesCommands(policy, commands) {
+  if (!commands || commands.length === 0) return true;
+  if (policy.command === "ALL") return true;
+  return commands.includes(policy.command);
+}
+function checkPolicies(manifest, schema) {
+  const issues = [];
+  for (const req of manifest.requirements.policies_must_not_allow ?? []) {
+    const table = schema.tables.find((t) => t.name === req.table);
+    if (!table) {
+      issues.push({
+        category: "schema_missing",
+        message: `expected table "${req.table}" not found in schema.json; add a CREATE TABLE migration`,
+        context: { requirement: req }
+      });
+      continue;
+    }
+    const offending = table.policies.filter(
+      (p) => policyGrantsRole(p, req.role) && policyMatchesCommands(p, req.commands)
+    );
+    if (offending.length > 0) {
+      const scope = req.commands?.length ? req.commands.join(", ") : "any command";
+      issues.push({
+        category: "schema_policy_permits",
+        message: `table "${req.table}" must not allow role "${req.role}" (${scope}), but ${offending.length} policy/policies do: ` + offending.map(
+          (p) => `"${p.name}" FOR ${p.command} TO ${p.roles.length > 0 ? p.roles.join("/") : "PUBLIC (no TO clause)"}`
+        ).join(", ") + `; requirement: "${req.description}"`,
+        context: { requirement: req, offending }
+      });
+    }
+  }
+  return issues;
+}
+function collectAssertions(bundle) {
+  const out = [];
+  for (const trace of bundle) {
+    for (const step of trace.steps ?? []) {
+      for (const a of step.assertions ?? []) {
+        out.push({
+          ...a,
+          proofId: trace.proofId,
+          ...trace.specFile ? { specFile: trace.specFile } : {}
+        });
+      }
+    }
+  }
+  return out;
+}
+function allowedHelpersFor(kind, target, tableNames) {
+  if (kind !== "tenant_isolation") return null;
+  const head = String(target).split(".")[0];
+  return tableNames.has(head) ? TENANT_ISOLATION_TABLE_HELPERS : TENANT_ISOLATION_ACTION_HELPERS;
+}
+function checkTraces(manifest, bundle, schema) {
+  const issues = [];
+  const evidence = [];
+  const assertions = collectAssertions(bundle);
+  const tableNames = new Set((schema.tables ?? []).map((t) => t.name));
+  for (const req of manifest.requirements.trace_must_prove) {
+    const requiredRole = normalizeAssertionRole(req.role);
+    if (requiredRole === null) {
+      issues.push({
+        category: "manifest_shape",
+        message: `trace_must_prove[].role "${String(req.role)}" is not a valid assertion role; expected "primary" or "control"`,
+        context: { requirement: req }
+      });
+      continue;
+    }
+    const candidates = assertions.filter(
+      (a) => a.kind === req.kind && a.target === req.target && (req.proofId === void 0 || a.proofId === req.proofId)
+    );
+    const requiredOrigin = requiredEvidenceOrigin(req.kind, req.evidence);
+    const allowedHelpers = allowedHelpersFor(req.kind, req.target, tableNames);
+    const originSatisfied = (a) => requiredOrigin === "any" || typeof a.emittedBy === "string" && (allowedHelpers === null || allowedHelpers.includes(a.emittedBy));
+    const match = candidates.find(
+      (a) => a.passed === true && normalizeAssertionRole(a.role) === requiredRole && originSatisfied(a)
+    );
+    if (match) {
+      evidence.push({
+        kind: req.kind,
+        target: req.target,
+        role: requiredRole,
+        satisfied: true,
+        proofId: match.proofId,
+        ...match.specFile ? { specFile: match.specFile } : {},
+        ...match.detail ? { detail: match.detail } : {},
+        ...match.emittedBy ? { emittedBy: match.emittedBy } : {}
+      });
+      continue;
+    }
+    evidence.push({
+      kind: req.kind,
+      target: req.target,
+      role: requiredRole,
+      satisfied: false
+    });
+    const failed = candidates.filter((a) => a.passed === false);
+    const wrongRole = candidates.filter(
+      (a) => a.passed === true && normalizeAssertionRole(a.role) !== requiredRole
+    );
+    const unverified = candidates.filter(
+      (a) => a.passed === true && normalizeAssertionRole(a.role) === requiredRole && !originSatisfied(a)
+    );
+    if (unverified.length > 0) {
+      const found = unverified[0].emittedBy ? `was emitted by ${unverified[0].emittedBy}, which cannot vouch for this claim` : "was recorded directly by spec code (no emittedBy)";
+      const wanted = allowedHelpers ? allowedHelpers.join(" or ") : "an SDK assert.* helper";
+      issues.push({
+        category: "trace_unverified",
+        message: `a passing role="${requiredRole}" assertion with kind="${req.kind}" and target="${req.target}" exists but ${found}, and this requirement demands evidence="helper"${req.evidence === void 0 ? ` (mandatory for ${req.kind})` : ""}. Emit the claim through ${wanted}${allowedHelpers === null ? `, or set evidence: "any" on the requirement if a bespoke probe is intended` : ""}; description: "${req.description}"`,
+        context: { requirement: req, unverifiedCount: unverified.length }
+      });
+      continue;
+    }
+    let reason;
+    if (failed.length > 0) {
+      reason = `found ${failed.length} matching assertion(s) but they FAILED: ` + failed.map((a) => `[${a.proofId}] ${a.detail ?? "(no detail)"}`).join(" | ");
+    } else if (wrongRole.length > 0) {
+      reason = `found ${wrongRole.length} passing assertion(s) with role="${normalizeAssertionRole(wrongRole[0].role)}" but this requirement needs role="${requiredRole}". A "control" assertion passes by design and only shows the probe could have failed \u2014 it cannot stand in for the claim itself. Add the missing ${requiredRole} probe`;
+    } else if (req.proofId !== void 0) {
+      reason = `no assertion with this kind+target was emitted by proof "${req.proofId}" (other proofs may have emitted one; this requirement is pinned)`;
+    } else {
+      reason = "no assertion with this kind+target was emitted by any proof";
+    }
+    issues.push({
+      category: "trace_missing",
+      message: `no passing role="${requiredRole}" assertion found with kind="${req.kind}" and target="${req.target}"; ${reason}; description: "${req.description}"`,
+      context: { requirement: req, candidateCount: candidates.length }
+    });
+  }
+  return { issues, evidence };
+}
+function validateMission(input) {
+  const shape = shapeIssues(input.manifest);
+  if (shape.length > 0) {
+    return {
+      missionId: input.manifest?.missionId ?? "<invalid>",
+      ok: false,
+      issues: shape
+    };
+  }
+  const manifest = input.manifest;
+  const traceResult = checkTraces(manifest, input.traces, input.schema);
+  const issues = [
+    ...checkCapabilities(manifest, input.capabilities),
+    ...checkSchema(manifest, input.schema),
+    ...checkPolicies(manifest, input.schema),
+    ...traceResult.issues
+  ];
+  return {
+    missionId: manifest.missionId,
+    ok: issues.length === 0,
+    issues,
+    evidence: traceResult.evidence
+  };
+}
+export {
+  collectAssertions,
+  validateMission
+};
+//# sourceMappingURL=node.js.map