proof-harness 0.1.0-next.1

package/dist/shared.js

@@ -0,0 +1,121 @@
+// 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 MODULE_KINDS = [
+  /** The template ships it. Always present. */
+  "core",
+  /** Installable and already proven. Configured by answering its decisions. */
+  "extension",
+  /** Domain-specific code built for one product, under `__business-logic/`. */
+  "business",
+  /** Does not exist yet. An agent must build it against checks authored first. */
+  "generated"
+];
+var APPLIED_BY = [
+  /** Set a value in a named constant. */
+  "config",
+  /** Rewrite prose — legal text, marketing copy. */
+  "content",
+  /** Add or remove files, components, routes, migrations. */
+  "code"
+];
+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 isModuleKind(value) {
+  return typeof value === "string" && MODULE_KINDS.includes(value);
+}
+function isAppliedBy(value) {
+  return typeof value === "string" && APPLIED_BY.includes(value);
+}
+
+// src/shared/portable-vocabulary.mjs
+var TENANT_ISOLATION_TABLE_HELPERS = (
+  /** @type {const} */
+  [
+    "assert.tenantIsolation"
+  ]
+);
+var TENANT_ISOLATION_ACTION_HELPERS = (
+  /** @type {const} */
+  [
+    "assert.tenantIsolation",
+    "assert.authorization"
+  ]
+);
+
+// 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;
+}
+function normalizeAssertionStatus(status, passed) {
+  if (status === "passed" || status === "failed" || status === "incomplete" || status === "skipped") {
+    return status;
+  }
+  return passed ? "passed" : "failed";
+}
+var TRACE_ARTIFACT_SCHEMA_VERSION = 2;
+
+// src/shared/mission-types.ts
+var MISSION_MANIFEST_SCHEMA_VERSION = 1;
+
+// src/shared/module-types.ts
+var MODULE_DESCRIPTOR_SCHEMA_VERSION = 1;
+export {
+  APPLIED_BY,
+  ASSERTION_ROLE_ALIASES,
+  MISSION_MANIFEST_SCHEMA_VERSION,
+  MODULE_DESCRIPTOR_SCHEMA_VERSION,
+  MODULE_KINDS,
+  PROOF_KINDS,
+  PROOF_VERBS,
+  RLS_CLASSIFICATIONS,
+  TENANT_ISOLATION_ACTION_HELPERS,
+  TENANT_ISOLATION_TABLE_HELPERS,
+  TRACE_ARTIFACT_SCHEMA_VERSION,
+  isAppliedBy,
+  isModuleKind,
+  isProofKind,
+  isProofVerb,
+  isRlsClassification,
+  normalizeAssertionRole,
+  normalizeAssertionStatus
+};
+//# sourceMappingURL=shared.js.map

package/dist/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/shared/vocabulary.ts","../src/shared/portable-vocabulary.mjs","../src/shared/trace-types.ts","../src/shared/mission-types.ts","../src/shared/module-types.ts"],"sourcesContent":["// Import External Packages\n// Import Local Imports\n// Import Core Dependencies\n// Import Shared Dependencies\n// Import Extension Dependencies\n\n// ---------------------------------------------------------------------------\n// Closed Vocabularies\n//\n// These are the ONLY allowed values for verb, kind, and rls_classification\n// across the Proof system. Keeping them closed lets the scanner, manifest\n// validator, and trace consumers all speak the same language.\n// ---------------------------------------------------------------------------\n\n/**\n * Verb — the action a capability performs.\n * Used as metadata in `withProof({ verb: ... })`.\n */\nexport const PROOF_VERBS = [\n  \"create\",\n  \"read\",\n  \"update\",\n  \"delete\",\n  \"invoke\",\n  \"transfer\",\n] as const;\n\nexport type ProofVerb = (typeof PROOF_VERBS)[number];\n\n/**\n * Kind — the category of a trace step / assertion.\n * Used in `trace_must_prove` manifest entries and emitted by `assert.*`\n * helpers and `trace.step({ kind })` calls.\n */\nexport const PROOF_KINDS = [\n  \"happy_path\",\n  \"tenant_isolation\",\n  \"authorization\",\n  \"validation\",\n  \"error_handling\",\n  \"idempotency\",\n] as const;\n\nexport type ProofKind = (typeof PROOF_KINDS)[number];\n\n/**\n * RLS classification — how a table is scoped under Row Level Security.\n * Emitted by the migration parser (v1). Defined here so v0.5 helpers and\n * future tooling share the same vocabulary.\n */\nexport const RLS_CLASSIFICATIONS = [\n  \"workspace_scoped\",\n  \"user_scoped\",\n  \"admin_only\",\n  \"public_read\",\n  \"service_only\",\n  \"unclassified\",\n] as const;\n\nexport type RlsClassification = (typeof RLS_CLASSIFICATIONS)[number];\n\n/**\n * The commands a Postgres RLS policy can cover, as the migration parser reports\n * them.\n *\n * `rls_classification` gives a table one label, which is a useful summary and a\n * poor description: real policies are per-command, so a table can be readable\n * only by admins while being writable only by the service role. `ALL` is Postgres'\n * own wildcard and matches every command, which is why a prohibition on any single\n * command has to consider it.\n */\nexport const POLICY_COMMANDS = [\n  \"SELECT\",\n  \"INSERT\",\n  \"UPDATE\",\n  \"DELETE\",\n  \"ALL\",\n] as const;\n\nexport type PolicyCommand = (typeof POLICY_COMMANDS)[number];\n\n/**\n * Module kind — which of four very different things a module is.\n *\n * The field a planner reads first, because it decides cost and risk at once.\n * A module moving from `generated` to `extension` is work that will never be\n * paid for twice, and it should be visible in a diff.\n */\nexport const MODULE_KINDS = [\n  /** The template ships it. Always present. */\n  \"core\",\n  /** Installable and already proven. Configured by answering its decisions. */\n  \"extension\",\n  /** Domain-specific code built for one product, under `__business-logic/`. */\n  \"business\",\n  /** Does not exist yet. An agent must build it against checks authored first. */\n  \"generated\",\n] as const;\n\nexport type ModuleKind = (typeof MODULE_KINDS)[number];\n\n/**\n * How a buyer's answer reaches the code.\n *\n * The only technical field a planner needs, because it is what separates a\n * cheap dispatch from an expensive one. Most of this template is `code`: the\n * survey behind this vocabulary found exactly one real feature flag and about\n * twenty-five decisions that mean deleting routes and components.\n */\nexport const APPLIED_BY = [\n  /** Set a value in a named constant. */\n  \"config\",\n  /** Rewrite prose — legal text, marketing copy. */\n  \"content\",\n  /** Add or remove files, components, routes, migrations. */\n  \"code\",\n] as const;\n\nexport type AppliedBy = (typeof APPLIED_BY)[number];\n\n// ---------------------------------------------------------------------------\n// Type guards\n// ---------------------------------------------------------------------------\n\nexport function isProofVerb(value: unknown): value is ProofVerb {\n  return (\n    typeof value === \"string\" &&\n    (PROOF_VERBS as readonly string[]).includes(value)\n  );\n}\n\nexport function isProofKind(value: unknown): value is ProofKind {\n  return (\n    typeof value === \"string\" &&\n    (PROOF_KINDS as readonly string[]).includes(value)\n  );\n}\n\nexport function isRlsClassification(\n  value: unknown,\n): value is RlsClassification {\n  return (\n    typeof value === \"string\" &&\n    (RLS_CLASSIFICATIONS as readonly string[]).includes(value)\n  );\n}\n\nexport function isPolicyCommand(value: unknown): value is PolicyCommand {\n  return (\n    typeof value === \"string\" &&\n    (POLICY_COMMANDS as readonly string[]).includes(value)\n  );\n}\n\nexport function isModuleKind(value: unknown): value is ModuleKind {\n  return (\n    typeof value === \"string\" &&\n    (MODULE_KINDS as readonly string[]).includes(value)\n  );\n}\n\nexport function isAppliedBy(value: unknown): value is AppliedBy {\n  return (\n    typeof value === \"string\" &&\n    (APPLIED_BY as readonly string[]).includes(value)\n  );\n}\n","// Import External Packages\n// Import Local Imports\n// Import Core Dependencies\n// Import Shared Dependencies\n// Import Extension Dependencies\n\n// ---------------------------------------------------------------------------\n// Portable proof vocabulary — the single source of truth for closed value\n// lists that BOTH the TypeScript SDK and the dependency-free Node scripts\n// (`proof_verify.mjs`, `proof_drift.mjs`, `proof_coverage.mjs`) must agree on.\n//\n// Why a .mjs file inside a TypeScript package: those scripts run under plain\n// `node` with no compile step and must stay fast-starting, so they cannot\n// import `vocabulary.ts`. Everything here is therefore plain JS, and the\n// TypeScript side derives its union types from these arrays\n// (`(typeof ACTION_CHANGE_KINDS)[number]` in mission-types.ts), so adding or\n// renaming a value in exactly one place updates the validators, the drift\n// script, coverage, and the types together. The JSDoc `@type {const}` casts\n// are what preserve the literal element types for that derivation.\n//\n// Only vocabularies needed by the .mjs scripts live here; TS-only\n// vocabularies stay in `vocabulary.ts`.\n// ---------------------------------------------------------------------------\n\n/**\n * Change kinds an `expectedChanges.actions[]` declaration may allow, and the\n * facets a modified action decomposes into. Like tables, EVERY facet of a\n * change must be declared for the change to be covered — a mission expecting\n * an invariant declaration to change does not thereby authorize an RBAC/auth\n * middleware change on the same action.\n *\n *   - `middleware_changed`: a scanner-observed guard (auth / tenantIsolation\n *     / rbac) appeared, disappeared, or flipped.\n *   - `invariants_changed`: the `withProof({ invariants })` list changed.\n *   - `service_role_mutations_changed`: the set of tables the action writes\n *     through the service-role client changed.\n *   - `metadata_changed`: verb, object, acceptsWorkspaceId, internalOnly, or\n *     usesDirectUpdateTag changed.\n */\nexport const ACTION_CHANGE_KINDS = /** @type {const} */ ([\n  \"added\",\n  \"removed\",\n  \"middleware_changed\",\n  \"invariants_changed\",\n  \"service_role_mutations_changed\",\n  \"metadata_changed\",\n]);\n\n/**\n * Change kinds an `expectedChanges.tables[]` declaration may allow, and the\n * facets a modified table decomposes into. Same coverage rule as actions:\n * declaring `columns_added` on a table does not authorize a policy change\n * that rode along on the same table.\n */\nexport const TABLE_CHANGE_KINDS = /** @type {const} */ ([\n  \"added\",\n  \"removed\",\n  \"columns_added\",\n  \"columns_removed\",\n  \"rls_classification_changed\",\n  \"policies_changed\",\n]);\n\n/**\n * The only helpers whose `emittedBy` stamp counts as tenant-isolation\n * evidence, split by target.\n *\n * Identity matters because helpers differ in who chooses the `kind`:\n * `assert.httpResponse` records the caller's kind verbatim, so its stamp on a\n * `tenant_isolation` assertion would prove only that an HTTP probe ran — not\n * that anything checked cross-tenant visibility. Isolation OF A TABLE is\n * exactly what `assert.tenantIsolation` proves, so table targets accept only\n * it; action-ref targets also accept `assert.authorization`, whose action\n * probes record the cross-tenant invariant they actually establish.\n */\nexport const TENANT_ISOLATION_TABLE_HELPERS = /** @type {const} */ ([\n  \"assert.tenantIsolation\",\n]);\n\n/** Allowed stamps for tenant-isolation claims against non-table targets (action refs). */\nexport const TENANT_ISOLATION_ACTION_HELPERS = /** @type {const} */ ([\n  \"assert.tenantIsolation\",\n  \"assert.authorization\",\n]);\n","// Import External Packages\n// Import Local Imports\nimport type { ProofKind } from \"./vocabulary\";\n// Import Core Dependencies\n// Import Shared Dependencies\n// Import Extension Dependencies\n\n// ---------------------------------------------------------------------------\n// Trace artifact types\n//\n// These are the durable shape written to `.proof/traces/<proofId>.json`.\n//\n// Two separate identifiers on purpose:\n//   - `proofId`    — per-file id; what _this_ proof verifies (e.g. \"auth-login-admin\",\n//                    \"workspace-invite-tenant-isolation\"). The filename is keyed on it,\n//                    so proofs never collide.\n//   - `missionId`  — optional external ticket reference (e.g. \"M-042\"). A single mission\n//                    typically has multiple proofs (happy_path + tenant_isolation +\n//                    authorization), each with its own file. The v1 mission-manifest\n//                    validator groups by `missionId` and checks that every\n//                    `trace_must_prove` entry has at least one matching passing step\n//                    across the group.\n// ---------------------------------------------------------------------------\n\n/**\n * The evidential role an assertion plays.\n *\n *   - `primary` — the claim the proof exists to make. For an authorization or\n *                 tenant-isolation proof that is a refusal (\"the outsider could\n *                 NOT read the row\"); for a happy_path proof it is a success\n *                 (\"the user reached their workspace\"). This is what a mission's\n *                 `trace_must_prove` entry matches by default.\n *   - `control` — a companion assertion proving the primary probe was capable of\n *                 failing at all: \"the operation that SHOULD be permitted still\n *                 succeeded\", or \"the row the primary probe looked for genuinely\n *                 exists and is readable by someone.\"\n *\n * The distinction is load-bearing, not cosmetic. A refusal probe alone cannot\n * tell \"RLS correctly hid this row\" apart from \"there was no row / the grant\n * denies everyone / the table name was a typo\" — every one of those yields zero\n * rows and would record a passing assertion. The control is what makes the zero\n * mean something.\n *\n * Because the validator matches `trace_must_prove` on `{ kind, target,\n * passed: true }`, controls MUST be labelled: otherwise a control (which by\n * design passes) could satisfy a requirement all on its own and the primary\n * probe would never be checked at all.\n *\n * Naming note: an earlier draft called these `negative` / `positive_control`.\n * That reads backwards for `happy_path`, whose primary claim is a success, so\n * the roles are named by evidential function instead. Both older names are\n * accepted as deprecated aliases wherever a role is parsed.\n */\nexport type AssertionRole = \"primary\" | \"control\";\n\n/**\n * Concrete operation exercised by an assertion. Mutation inventory keys claims\n * by kind + target + operation so a SELECT mutation cannot silently stand in\n * for an untested UPDATE/DELETE or action invocation.\n */\nexport type ProofOperation =\n  | \"select\"\n  | \"insert\"\n  | \"update\"\n  | \"delete\"\n  | \"invoke\"\n  | \"request\";\n\n/** Deprecated role spellings accepted on input and normalized to AssertionRole. */\nexport const ASSERTION_ROLE_ALIASES: Readonly<Record<string, AssertionRole>> = {\n  negative: \"primary\",\n  positive_control: \"control\",\n};\n\n/**\n * Normalize a role from an artifact or manifest. `undefined` means `primary`:\n * traces written before schemaVersion 2 carry no role, and their assertions\n * were all primary claims.\n */\nexport function normalizeAssertionRole(role: unknown): AssertionRole | null {\n  if (role === undefined || role === null) return \"primary\";\n  if (role === \"primary\" || role === \"control\") return role;\n  if (typeof role === \"string\" && role in ASSERTION_ROLE_ALIASES) {\n    return ASSERTION_ROLE_ALIASES[role];\n  }\n  return null;\n}\n\n/**\n * What an assertion concluded.\n *\n * `passed` / `failed` are the two verdicts a boolean can carry. The other two\n * exist because \"we did not find out\" is a real outcome that a boolean has to\n * round to one side or the other, and rounding it to `false` is indistinguishable\n * from a genuine failure while rounding it to `true` is how a suite quietly stops\n * proving anything:\n *\n *   - `incomplete` — the probe ran but could not reach a verdict (a precondition\n *                    was missing, a dependency was unavailable).\n *   - `skipped`    — the probe was deliberately not run, e.g. a tenant-isolation\n *                    direction with no fixture rows on that side.\n *\n * Neither counts as evidence: both carry `passed: false`, so neither can satisfy\n * a mission requirement. The status is what lets a consumer tell them apart from\n * a real failure, and stops a skip from disappearing into \"one fewer assertion\".\n */\nexport type AssertionStatus = \"passed\" | \"failed\" | \"incomplete\" | \"skipped\";\n\n/** Derive the status of an assertion that predates the field. */\nexport function normalizeAssertionStatus(\n  status: unknown,\n  passed: boolean,\n): AssertionStatus {\n  if (\n    status === \"passed\" ||\n    status === \"failed\" ||\n    status === \"incomplete\" ||\n    status === \"skipped\"\n  ) {\n    return status;\n  }\n  return passed ? \"passed\" : \"failed\";\n}\n\n/**\n * A single structured assertion recorded during a step. Produced by the\n * `assert.*` helpers via `recordAssertion(...)`. Hand-written `expect(...)`\n * calls inside a step do NOT appear here — only helper-driven assertions do,\n * because the v1 mission-manifest validator matches on\n * `{ kind, target, passed: true, role }` and needs a closed, machine-readable\n * surface.\n */\nexport interface TraceAssertion {\n  /** Category from the closed `PROOF_KINDS` vocabulary. */\n  kind: ProofKind;\n  /** The thing asserted against: table, route, action, etc. */\n  target: string;\n  /** Concrete operation the probe exercised. */\n  operation?: ProofOperation;\n  /**\n   * Whether this specific assertion held. Remains the authoritative field for\n   * the validator and for consumers: only `true` is evidence.\n   */\n  passed: boolean;\n  /**\n   * Why `passed` has the value it has. Omitted is derived from `passed`, so\n   * traces written before this field stay readable.\n   */\n  status?: AssertionStatus;\n  /**\n   * Evidential role. Omitted is treated as `\"primary\"` by the validator for\n   * backward compatibility with traces written before schemaVersion 2.\n   */\n  role?: AssertionRole;\n  /** Optional human-readable note for failure triage. */\n  detail?: string;\n  /**\n   * Which SDK helper produced this assertion, e.g. `\"assert.tenantIsolation\"`.\n   *\n   * Stamped by the SDK itself through an internal channel that the public\n   * `recordAssertion(...)` entry point cannot reach: a value supplied by spec\n   * code is stripped before the assertion is recorded. Absent means the\n   * assertion was recorded directly by a spec via `recordAssertion(...)`.\n   *\n   * The distinction is evidential. A helper-emitted assertion went through the\n   * helper's vacuity controls, ground-truth re-reads, and role bookkeeping; a\n   * spec-recorded assertion asserts whatever the spec chose to write into it.\n   * The mission validator therefore requires helper provenance for\n   * `tenant_isolation` requirements (a hand-rolled isolation probe has none of\n   * `assert.tenantIsolation`'s protections), and a mission can demand it for\n   * any requirement via `trace_must_prove[].evidence: \"helper\"`.\n   *\n   * For `tenant_isolation` the stamp is also identity-checked, not merely\n   * present-checked — see TENANT_ISOLATION_TABLE_HELPERS. `assert.httpResponse`\n   * records whatever `kind` its caller passes, so \"some helper emitted this\"\n   * is not the same claim as \"the isolation probe ran\".\n   */\n  emittedBy?: string;\n}\n\n/**\n * The only helpers whose stamp counts as tenant-isolation evidence, split by\n * target (tables are stricter than action refs). The single runtime source is\n * [`portable-vocabulary.mjs`](./portable-vocabulary.mjs), which the\n * dependency-free Node scripts (`proof_verify.mjs`, `proof_coverage.mjs`)\n * import directly; see there for the identity rationale.\n */\nexport {\n  TENANT_ISOLATION_ACTION_HELPERS,\n  TENANT_ISOLATION_TABLE_HELPERS,\n} from \"./portable-vocabulary.mjs\";\n\n/**\n * A single step inside a proof.\n * Produced by `t.step({ intent, kind, target }, async () => { ... })`.\n */\nexport interface TraceStep {\n  /** Human-readable description of what the step attempted. */\n  intent: string;\n  /** Category of the step, from closed vocabulary. */\n  kind: ProofKind;\n  /** The thing the step targets: action name, table, route, etc. */\n  target: string;\n  /** What the step observed (returned by the step callback). */\n  observation: string;\n  /** Whether the step's assertions held. */\n  passed: boolean;\n  /** Optional: who the step acted as (email, role, seed identifier). */\n  actor?: string;\n  /** Optional: which workspace the step operated in. */\n  workspaceId?: string;\n  /** Wall-clock duration of the step callback. */\n  durationMs: number;\n  /** On failure, the error message captured. */\n  error?: string;\n  /**\n   * Structured assertions recorded by `assert.*` helpers during this step.\n   * Empty or omitted for steps that only use `expect(...)` directly.\n   * The v1 mission-manifest validator matches `trace_must_prove` entries\n   * against this array.\n   */\n  assertions?: TraceAssertion[];\n}\n\n/**\n * Current per-proof trace artifact schema version.\n *\n * 2 — adds `role` and `status` to assertions and the `schemaVersion` /\n *     `specFile` / `specHash` / `commit` / `dirty` provenance fields below.\n *     Consumers written against v1 keep working: every v1 field is still present\n *     with the same meaning, and both new assertion fields are derivable when\n *     absent.\n *\n * `commit`, `dirty`, and `mutation` arrived after v2 shipped and did not bump\n * it: they are optional additions, and the contract's rule is that additive\n * fields do not move a version. A consumer that needs them must treat absence\n * as \"unknown\" anyway, since normal runs have no mutation and a non-git\n * checkout cannot supply code provenance.\n */\nexport const TRACE_ARTIFACT_SCHEMA_VERSION = 2;\n\n/**\n * Provenance attached only when the mutation harness deliberately plants a\n * defect. A red mutation trace means the check detected the named defect; it\n * must never be mistaken for a real application regression.\n */\nexport interface TraceMutation {\n  /** Stable mutation identifier from the repository-owned mutation catalog. */\n  id: string;\n  /** Always true; makes the intentional nature explicit to copied consumers. */\n  planted: true;\n}\n\n/**\n * A trace artifact — one proof's worth of evidence.\n * Written atomically to `.proof/traces/<proofId>.json` when the proof\n * completes (pass or fail).\n */\nexport interface TraceArtifact {\n  /**\n   * Pinned to TRACE_ARTIFACT_SCHEMA_VERSION. Absent on traces written by\n   * SDK versions before provenance was added.\n   */\n  schemaVersion?: number;\n  /**\n   * Repo-relative path of the spec file that produced this trace, e.g.\n   * `e2e/proofs/workspace-invite.proof.ts`. Lets a reviewer go from a claim\n   * straight to the code that made it.\n   */\n  specFile?: string;\n  /**\n   * First 12 hex chars of the SHA-256 of the spec file's contents. Two runs\n   * claiming the same proof with different hashes were produced by different\n   * code — which is the whole question when a previously-red proof turns\n   * green.\n   */\n  specHash?: string;\n  /**\n   * Full SHA of the commit that was checked out while the proof ran. `specHash`\n   * pins the spec that made the claim; this pins the application it was made\n   * against, which is what lets an external ledger say \"red at X, green at Y\".\n   *\n   * Absent outside a git checkout. On a CI `pull_request` run this is the\n   * ephemeral merge commit the checkout created — accurate about what was\n   * tested, but not a commit you can return to later.\n   */\n  commit?: string;\n  /**\n   * Whether the working tree had uncommitted changes when the proof ran. A pass\n   * from a dirty tree is evidence about code that exists nowhere but one laptop,\n   * so a consumer gating on traces should be able to refuse it. Absent when it\n   * could not be determined, which is not the same as `false`.\n   */\n  dirty?: boolean;\n  /**\n   * Present only for intentional red runs produced by `proof:mutate`.\n   * Stored inside the trace so provenance survives artifact renames/copies.\n   */\n  mutation?: TraceMutation;\n  /**\n   * Per-file identifier for this proof. Used as the filename stem and as the\n   * join key when the v1 mission-manifest validator looks for a matching\n   * passing step for a `trace_must_prove` entry.\n   */\n  proofId: string;\n  /**\n   * Optional reference to the external mission (ticket) this proof belongs\n   * to. Multiple proofs share one `missionId`. Absent in v0.5 local runs\n   * that are not tied to a mission.\n   */\n  missionId?: string;\n  /** ISO 8601 timestamp of proof start. */\n  timestamp: string;\n  /** Total wall-clock duration across all steps. */\n  durationMs: number;\n  /** True only if every step passed. */\n  passed: boolean;\n  /** Ordered list of steps as they were executed. */\n  steps: TraceStep[];\n}\n\n/**\n * Options accepted by `trace.proof(...)`. A bare string is treated as\n * `{ proofId: string }` — the common v0.5 case where no mission is attached.\n */\nexport interface ProofOptions {\n  proofId: string;\n  missionId?: string;\n}\n\n/**\n * The handle passed to a proof callback. Provides the step recorder.\n */\nexport interface TraceRecorder {\n  step<T extends StepResult | void>(\n    opts: StepOptions,\n    fn: () => Promise<T>,\n  ): Promise<T>;\n}\n\nexport interface StepOptions {\n  intent: string;\n  kind: ProofKind;\n  target: string;\n  actor?: string;\n  workspaceId?: string;\n}\n\n/**\n * Optional payload returned by a step callback. If the callback returns\n * `void` the step is still recorded with `observation: \"\"`.\n */\nexport interface StepResult {\n  observation?: string;\n}\n","// ---------------------------------------------------------------------------\n// Mission manifest types.\n//\n// A *mission manifest* is the JSON artifact an external orchestrator or a\n// developer in manual mode writes to `.proof/current-mission.json` to\n// tell `pnpm proof:verify` what the PR must prove. The validator at\n// `src/node/validate-mission.ts` cross-references each\n// requirement against the fresh `.proof/capabilities.json`, `.proof/schema.json`,\n// and the aggregated trace.\n//\n// Shape is pinned by contract — additive changes bump nothing, breaking\n// changes bump `schemaVersion` at the top of the manifest. Consumers should\n// assert `schemaVersion === 1` and fail loudly otherwise.\n// ---------------------------------------------------------------------------\n\nimport type { AssertionRole } from \"./trace-types\";\nimport {\n  ACTION_CHANGE_KINDS,\n  TABLE_CHANGE_KINDS,\n} from \"./portable-vocabulary.mjs\";\nimport type {\n  PolicyCommand,\n  ProofKind,\n  ProofVerb,\n  RlsClassification,\n} from \"./vocabulary\";\n\n/**\n * Manifest schema version. Deliberately still 1 after the July 2026 validator\n * work: `trace_must_prove[].role` and `.proofId` are OPTIONAL additions, so\n * every v1 manifest is still shape-valid and consumers need not regenerate\n * anything. Note that validation did get stricter — a `control` assertion can\n * no longer satisfy a requirement — so a manifest that passed on a vacuous\n * probe before may now (correctly) fail. That is a behaviour tightening, not a\n * shape change, and bumping the version would have forced a rewrite of every\n * existing manifest for no benefit.\n */\nexport const MISSION_MANIFEST_SCHEMA_VERSION = 1;\n\nexport interface CapabilityRequirement {\n  /** Matches `createAction({ functionName: <name> })` exactly. */\n  name: string;\n  /** Module folder name (e.g. `\"issues\"`, not `\"__business-logic/issues\"`). */\n  module: string;\n  /** One of PROOF_VERBS. */\n  verb: ProofVerb;\n  /** Free-form noun, lowercased by convention (e.g. `\"issue\"`, `\"workspace\"`). */\n  object: string;\n  /** Optional: invariants that the action's `withProof({ invariants })` must advertise. */\n  invariants?: readonly string[];\n}\n\nexport interface SchemaRequirement {\n  /** Unqualified public-schema table name. */\n  table: string;\n  /** Columns that must exist on the table. Order-insensitive. */\n  required_columns: readonly string[];\n  /** One of RLS_CLASSIFICATIONS. */\n  rls_classification: RlsClassification;\n}\n\n/**\n * \"No policy on this table targets this role for these commands.\"\n *\n * Exists because `rls_classification` is one label per table and Postgres RLS is\n * per-command: `audit_logs` being \"admin readable, service writable\" cannot be\n * said with a single label, and the label a manifest picks would have to be a\n * lie in one direction or the other.\n *\n * Checks reachability, not the predicate — `USING` and `WITH CHECK` are not read.\n * A policy `TO authenticated USING (is_super_admin())` counts as targeting\n * `authenticated`, so \"this role may act only under condition X\" is not\n * expressible here and belongs in `trace_must_prove`, where something exercises\n * it. Write prohibitions (\"members never INSERT into the audit log\") are the\n * natural fit.\n *\n * Deliberately only the prohibition, never \"a policy must exist\". A policy's\n * existence is weak evidence — it says a rule was written, not that it works —\n * and the thing that makes a permission real is a passing proof, which belongs in\n * `trace_must_prove`. A prohibition is different: it is a claim that can fail\n * dangerously and silently, and it is checkable from the migrations alone.\n */\nexport interface PolicyProhibition {\n  /** Unqualified public-schema table name. */\n  table: string;\n  /**\n   * Database role that must not be granted access, e.g. `\"authenticated\"` or\n   * `\"anon\"`. A policy with no `TO` clause defaults to `PUBLIC` in Postgres and\n   * therefore counts as granting every role.\n   */\n  role: string;\n  /**\n   * Commands the prohibition covers. Omit to mean \"any command\". A policy\n   * declared `FOR ALL` matches whatever is listed here, because that is what it\n   * does in the database.\n   */\n  commands?: readonly PolicyCommand[];\n  /** Human-readable statement of the rule, echoed in the failure message. */\n  description: string;\n}\n\nexport interface TraceRequirement {\n  /** One of PROOF_KINDS. */\n  kind: ProofKind;\n  /**\n   * Free-form identifier the assertion emits. Must match an assertion's\n   * `target` exactly (e.g. table name for `tenant_isolation`, capability\n   * name for `authorization`).\n   */\n  target: string;\n  /** Human-readable statement of what should be proved. */\n  description: string;\n  /**\n   * Which evidential role must satisfy this requirement. Defaults to\n   * `\"primary\"`, which is almost always what you want: a `\"control\"`\n   * assertion passes by design and proves only that the probe was capable of\n   * failing, so it must never stand in for the claim itself.\n   *\n   * Accepts the deprecated spellings `\"negative\"` / `\"positive_control\"`.\n   */\n  role?: AssertionRole;\n  /**\n   * Optional: restrict matching to assertions emitted by this proof.\n   *\n   * By default a requirement may be satisfied by a matching assertion from\n   * ANY proof in the run. That is convenient but means an unrelated spec can\n   * unknowingly satisfy a mission's requirement. Set this when the mission\n   * cares that a SPECIFIC proof made the claim. Either way, the aggregated\n   * trace records which proof actually supplied the evidence.\n   */\n  proofId?: string;\n  /**\n   * What origin of assertion may satisfy this requirement.\n   *\n   *   - `\"helper\"` — only assertions stamped `emittedBy` by an SDK `assert.*`\n   *     helper count. Helper assertions went through the SDK's vacuity\n   *     controls and ground-truth re-reads; a spec-recorded assertion asserts\n   *     whatever the spec wrote into it.\n   *   - `\"any\"` — spec-recorded assertions (raw `recordAssertion`) count too.\n   *     Those claims remain backstopped by the mutation inventory, which is\n   *     why bespoke probes (RPC grants, column guards) stay expressible.\n   *\n   * `tenant_isolation` is always `\"helper\"`, and the stamp is additionally\n   * identity-checked (see TENANT_ISOLATION_TABLE_HELPERS in trace-types):\n   * declaring `evidence: \"any\"` for it is a `manifest_shape` error, so the\n   * mission gate and strict coverage can never disagree about whether a raw\n   * isolation assertion is admissible. Every other kind defaults to `\"any\"`.\n   */\n  evidence?: EvidenceOrigin;\n}\n\n/** Origin of assertion allowed to satisfy a `trace_must_prove` entry. */\nexport type EvidenceOrigin = \"helper\" | \"any\";\n\n/**\n * The evidence origin a requirement demands, applying the kind-based default.\n * Consumed directly by the compiled validator used by `proof-harness verify`.\n */\nexport function requiredEvidenceOrigin(\n  kind: ProofKind,\n  evidence: EvidenceOrigin | undefined,\n): EvidenceOrigin {\n  // Tenant isolation is helper-only regardless of what the manifest says: the\n  // shape validator rejects `evidence: \"any\"` for it, and this belt-and-braces\n  // keeps the matching honest even for a manifest that skipped shape checks.\n  if (kind === \"tenant_isolation\") return \"helper\";\n  return evidence ?? \"any\";\n}\n\nexport interface MissionRequirements {\n  capabilities_must_exist: readonly CapabilityRequirement[];\n  schema_must_contain: readonly SchemaRequirement[];\n  trace_must_prove: readonly TraceRequirement[];\n  /**\n   * Optional, so every existing v1 manifest stays shape-valid. Omitting it means\n   * \"no policy-level claims\", not \"policies are fine\".\n   */\n  policies_must_not_allow?: readonly PolicyProhibition[];\n}\n\n/**\n * Change kinds an action declaration may allow. Like tables, a modified\n * action is decomposed into facets and EVERY facet must be covered — a\n * mission expecting an invariant declaration to change does not thereby\n * authorize an RBAC/auth middleware change on the same action.\n *\n * Derived from the single runtime source in\n * [`portable-vocabulary.mjs`](./portable-vocabulary.mjs), which the\n * dependency-free Node scripts import directly; see there for the per-facet\n * meanings.\n */\nexport type ActionChangeKind = (typeof ACTION_CHANGE_KINDS)[number];\n\n/**\n * Change kinds a table declaration may allow. A \"modified\" table entry is\n * decomposed into facets, and EVERY facet must be covered by the declaration —\n * declaring `columns_added` on a table does not authorize a policy change on\n * the same table. Derived from `portable-vocabulary.mjs`.\n */\nexport type TableChangeKind = (typeof TABLE_CHANGE_KINDS)[number];\n\n// Re-exported so TS consumers get the runtime lists from the same import\n// site as the types they parameterize.\nexport { ACTION_CHANGE_KINDS, TABLE_CHANGE_KINDS };\n\n/** Exact-ref action declaration. A bare string ref means \"any change\". */\nexport interface ExpectedActionChange {\n  /** `<module>:<name>`, the same ref capabilities.json uses. */\n  ref: string;\n  /** Omit for \"any change to this action\". */\n  changes?: readonly ActionChangeKind[];\n}\n\n/** Table declaration. A bare string name means \"any tracked change\". */\nexport interface ExpectedTableChange {\n  name: string;\n  /** Omit for \"any tracked change to this table\". */\n  changes?: readonly TableChangeKind[];\n}\n\n/**\n * The proof-surface change budget a mission grants its PR.\n *\n * Everything else in the manifest states what MUST exist; this block bounds\n * what else MAY change on the surfaces drift tracks. Read by\n * the package drift engine, which diffs the regenerated\n * `capabilities.json` / `schema.json` / `package.json` / lockfile against the\n * PR's base and fails (`drift_undeclared`) on a high-severity delta outside\n * the declared budget.\n *\n * Scope is deliberately narrow-by-default:\n *\n *   - `modules` covers only ADDED actions in the named module (the\n *     new-module convenience). Modifying or removing an existing action is\n *     never authorized by a module declaration — a mission that expects a\n *     guard or signature change on an existing action must name the exact\n *     ref in `actions`, so \"add a small feature\" can never quietly license\n *     weakening an unrelated action in the same module.\n *   - String shorthands (\"issues\" in `tables`, \"issues:createIssue\" in\n *     `actions`) mean \"any change\" and are the coarse form; the object forms\n *     narrow to specific change kinds.\n *\n * Omitting the block keeps drift report-only, so every existing v1 manifest\n * behaves exactly as before.\n */\nexport interface ExpectedChanges {\n  /**\n   * Module leaf names (e.g. `\"issues\"`) in which NEW actions may appear.\n   * Does not authorize modification or removal of existing actions.\n   */\n  modules?: readonly string[];\n  /** Exact action refs that may change; see {@link ExpectedActionChange}. */\n  actions?: readonly (string | ExpectedActionChange)[];\n  /** Tables that may change; see {@link ExpectedTableChange}. */\n  tables?: readonly (string | ExpectedTableChange)[];\n  /**\n   * Runtime dependencies (`package.json` `dependencies`) that may be added,\n   * removed, or version-changed. Every runtime dependency delta is\n   * high-severity — a swap or downgrade changes shipped behavior as surely as\n   * an addition.\n   */\n  dependencies?: readonly string[];\n  /**\n   * Expect a lockfile-only resolution change (pnpm-lock.yaml differs while\n   * the package.json dependency surface does not). Rare and suspicious by\n   * default, hence explicitly declared rather than inferred.\n   */\n  lockfile?: boolean;\n}\n\nexport interface MissionManifest {\n  /** Pinned to MISSION_MANIFEST_SCHEMA_VERSION. */\n  schemaVersion: number;\n  /** Ticket id from the consumer's kanban (e.g. `\"M-042\"`). */\n  missionId: string;\n  /** Short human-readable title. */\n  missionTitle: string;\n  /** Product repo slug (informational). */\n  productRepo?: string;\n  /** PR branch name (informational). */\n  prBranch?: string;\n  /** ISO-8601 timestamp the manifest was generated. */\n  createdAt: string;\n  requirements: MissionRequirements;\n  /**\n   * Optional drift bound; see {@link ExpectedChanges}. Absent means the drift\n   * report is informational only.\n   */\n  expectedChanges?: ExpectedChanges;\n  /** Free-form notes for reviewers / the coding agent. */\n  acceptanceNotes?: string;\n}\n\n// ---------------------------------------------------------------------------\n// Validation result types\n// ---------------------------------------------------------------------------\n\nexport type ValidationCategory =\n  | \"capability_missing\"\n  | \"capability_mismatch\"\n  | \"schema_missing\"\n  | \"schema_column_missing\"\n  | \"schema_rls_mismatch\"\n  /** A policy grants access the manifest declared must not exist. */\n  | \"schema_policy_permits\"\n  | \"trace_missing\"\n  /**\n   * A passing assertion matched the requirement but was recorded directly by\n   * spec code (`recordAssertion`) where the requirement demands an SDK-helper\n   * origin (`evidence: \"helper\"`, the default for `tenant_isolation`).\n   */\n  | \"trace_unverified\"\n  | \"manifest_shape\"\n  /** The Playwright run itself exited non-zero. Reported by the CLI, not the validator. */\n  | \"proof_run\"\n  /** The run produced no trace artifacts at all, so there is nothing to validate. */\n  | \"no_traces\"\n  /**\n   * A trace in the directory was recorded against a different commit than the\n   * current run — leftover evidence that cannot speak for the code under review.\n   * Reported by the CLI, which knows the run's commit; the validator sees only\n   * the bundle it is handed.\n   */\n  | \"stale_trace\";\n\n/**\n * Which proof supplied the evidence for a satisfied `trace_must_prove` entry.\n *\n * Recorded for every requirement — satisfied or not — so a reviewer can audit\n * the mapping instead of trusting that \"0 issues\" meant the right proof made\n * the claim. Requirements are matched against all assertions in the run, so\n * without this the attribution would be invisible.\n */\nexport interface RequirementEvidence {\n  kind: ProofKind;\n  target: string;\n  role: AssertionRole;\n  satisfied: boolean;\n  /** proofId of the trace whose assertion satisfied it, when satisfied. */\n  proofId?: string;\n  /** Spec file that produced that trace, when known. */\n  specFile?: string;\n  /** The satisfying assertion's `detail`, verbatim. */\n  detail?: string;\n  /**\n   * The satisfying assertion's helper provenance, when it has one. Absent\n   * means the evidence was recorded directly by spec code.\n   */\n  emittedBy?: string;\n}\n\nexport interface ValidationIssue {\n  category: ValidationCategory;\n  /** Human-readable summary including expected vs found. */\n  message: string;\n  /** Structured context for machine consumers (optional). */\n  context?: Record<string, unknown>;\n}\n\nexport interface ValidationResult {\n  missionId: string;\n  ok: boolean;\n  issues: ValidationIssue[];\n  /** Attribution for every `trace_must_prove` entry, in manifest order. */\n  evidence?: RequirementEvidence[];\n}\n","// Import External Packages\n// Import Local Imports\nimport type { AppliedBy, ModuleKind } from \"./vocabulary\";\n// Import Core Dependencies\n// Import Shared Dependencies\n// Import Extension Dependencies\n\n// ---------------------------------------------------------------------------\n// What a module declares about itself.\n//\n// Written to be read by a model rather than a person, and the reason is cost:\n// without it a planner needs the codebase in its context, which grows with\n// every extension we write. With it, a planner retrieves one small file.\n//\n// **Declare only what the code cannot say.** Tables, dependencies, actions and\n// proof coverage are all derivable from source, and a written copy of a\n// derivable fact is a fact that will be wrong later and say nothing about it.\n// What is left — what this is FOR, and what must be settled before it can be\n// used — is the part no compiler knows.\n//\n// Everything declared here is checked against the code by\n// `pnpm proof:modules:check`. A descriptor that can be wrong silently is a\n// liability with a nice format.\n//\n// Note on the name: \"manifest\" in this repo means the *mission* manifest\n// (`.proof/current-mission.json`), which gates CI. This is a module\n// *descriptor*, and the two are unrelated.\n// ---------------------------------------------------------------------------\n\nexport const MODULE_DESCRIPTOR_SCHEMA_VERSION = 1;\n\n/**\n * Where a buyer's answer has to land, so the code agent that applies it does\n * not have to rediscover the seams — and so a rename breaks CI instead of\n * quietly misleading the next agent.\n *\n * Two forms, both checkable:\n *\n *   \"app/__core/legal-notices/src/pages/imprint.tsx\"        — the file must exist\n *   \"app/__core/user-auth/src/config.ts#MFA_POLICY\"         — ...and contain that identifier\n *\n * Seams routinely sit **outside** the declaring module. Answering \"we do not\n * need an Impressum\" touches the page, its route, the shared footer and\n * `llm.txt`; an agent that only knows about `legal-notices` deletes one of the\n * four and leaves three links pointing at a 404. That is the whole reason this\n * field exists.\n */\nexport type ModuleSeam = string;\n\n/**\n * Something the buyer chooses between before this module can be used.\n *\n * Declared by the module rather than known by the planner, so a planner's\n * context stays flat as the library grows from one extension to thirty.\n *\n * **A question the buyer cannot answer does not belong here.** Anything needing\n * technical judgement is a `ModuleDefault` and we own it; asking a dentist\n * about webhook retry semantics is not consultation, it is abdication.\n */\nexport interface ModuleDecision {\n  /** snake_case, unique across every module. A planner keys answers by it. */\n  id: string;\n  /** In the buyer's language. They must be able to answer it unaided. */\n  ask: string;\n  /** Why it is being asked, in terms of what changes for them. */\n  because: string;\n  options: {\n    value: string;\n    /** What choosing this gets them, again in their language. */\n    means: string;\n  }[];\n  /** How the answer reaches the code. The planner's cost signal. */\n  applied_by: AppliedBy;\n  /** Every place the answer lands. Checked to still exist. */\n  applies: ModuleSeam[];\n}\n\n/**\n * A value the buyer supplies rather than picks — a legal name, a domain, a\n * support address.\n *\n * Separate from `decisions` because these are not choices and forcing them into\n * one would mean options that are not options. Separate from `defaults` because\n * nothing can be built until they exist: this is the planner's answer to \"what\n * must I collect before I dispatch anything?\".\n */\nexport interface ModuleInput {\n  /** snake_case, unique across every module. */\n  id: string;\n  /** In the buyer's language. */\n  ask: string;\n  /** What breaks or looks wrong if it is left as shipped. */\n  because: string;\n  /** A concrete illustration, so nobody has to guess the format. */\n  example: string;\n  /** False when the template's placeholder is survivable for a while. */\n  required: boolean;\n  applies: ModuleSeam[];\n}\n\n/**\n * Something we decided on the buyer's behalf.\n *\n * Recorded rather than asked, so a planner can answer \"what else could change?\"\n * without putting a question in front of someone who has no opinion on invite\n * expiry windows. The code agent gets the seam either way.\n */\nexport interface ModuleDefault {\n  /** snake_case, unique across every module. */\n  id: string;\n  /** What the template does today, in one plain sentence. */\n  is: string;\n  /** Where it is set. Checked to still exist. */\n  where: ModuleSeam;\n}\n\n/**\n * The declared half — everything a person writes. The derived half is added by\n * `proof-harness modules`.\n */\nexport interface ModuleMeta {\n  /** Directory name. Checked against where the file sits. */\n  id: string;\n  kind: ModuleKind;\n  /**\n   * What this is for, in a sentence a buyer would recognise.\n   *\n   * The field a planner leans on hardest and the only one nothing can verify —\n   * so it is short, and reviewed whenever the module changes.\n   */\n  purpose: string;\n  /**\n   * Environment variables this module needs.\n   *\n   * Declared rather than derived because need is transitive: the notification\n   * system reaches Resend through `@shared/email`, so no grep of its own source\n   * finds `RESEND_API_KEY`. Checked against `.env.local.example`, and anything\n   * the module reads directly must appear here.\n   */\n  env: string[];\n  decisions: ModuleDecision[];\n  inputs: ModuleInput[];\n  defaults: ModuleDefault[];\n}\n\n/**\n * A descriptor plus everything the scanner read from the source.\n *\n * This is what lands in `.proof/modules.json` and what a planner actually\n * reads. Nothing below `purpose` is hand-written.\n */\nexport interface ScannedModule extends ModuleMeta {\n  /** Repo-relative, `/` separators. */\n  path: string;\n  /** Tables this module's own migrations create. */\n  entities: string[];\n  /** Core / extension / business modules it imports. Never declared. */\n  requires: string[];\n  /** Shared utilities it imports. Not installable, so not a dependency to order. */\n  uses_shared: string[];\n  /** From `capabilities.json`: what this module can be asked to do. */\n  actions: { name: string; verb: string | null; object: string | null }[];\n  /**\n   * How battle-tested it is. Derived, and eventually the reason an installed\n   * module costs a buyer less than a built one: somebody has already shown\n   * these checks can fail.\n   */\n  proven: { specs: number; mutations: number };\n}\n\n/**\n * The generated artifact. Deterministic and unordered-by-nothing: every list is\n * sorted and there is no timestamp, so two runs on one tree are byte-identical.\n */\nexport interface ModulesArtifact {\n  schemaVersion: number;\n  modules: ScannedModule[];\n  /**\n   * Tables no descriptor claims — today the ones owned by `__shared` modules,\n   * which are utilities nobody installs and so carry no descriptor.\n   *\n   * Listed rather than omitted. A planner that cannot see `audit_logs` will\n   * eventually promise to build it.\n   */\n  unowned_tables: { table: string; module: string; path: string }[];\n}\n"],"mappings":";AAkBO,IAAM,cAAc;AAAA,EACzB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AASO,IAAM,cAAc;AAAA,EACzB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AASO,IAAM,sBAAsB;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AA+BO,IAAM,eAAe;AAAA;AAAA,EAE1B;AAAA;AAAA,EAEA;AAAA;AAAA,EAEA;AAAA;AAAA,EAEA;AACF;AAYO,IAAM,aAAa;AAAA;AAAA,EAExB;AAAA;AAAA,EAEA;AAAA;AAAA,EAEA;AACF;AAQO,SAAS,YAAY,OAAoC;AAC9D,SACE,OAAO,UAAU,YAChB,YAAkC,SAAS,KAAK;AAErD;AAEO,SAAS,YAAY,OAAoC;AAC9D,SACE,OAAO,UAAU,YAChB,YAAkC,SAAS,KAAK;AAErD;AAEO,SAAS,oBACd,OAC4B;AAC5B,SACE,OAAO,UAAU,YAChB,oBAA0C,SAAS,KAAK;AAE7D;AASO,SAAS,aAAa,OAAqC;AAChE,SACE,OAAO,UAAU,YAChB,aAAmC,SAAS,KAAK;AAEtD;AAEO,SAAS,YAAY,OAAoC;AAC9D,SACE,OAAO,UAAU,YAChB,WAAiC,SAAS,KAAK;AAEpD;;;AC3FO,IAAM;AAAA;AAAA,EAAuD;AAAA,IAClE;AAAA,EACF;AAAA;AAGO,IAAM;AAAA;AAAA,EAAwD;AAAA,IACnE;AAAA,IACA;AAAA,EACF;AAAA;;;ACdO,IAAM,yBAAkE;AAAA,EAC7E,UAAU;AAAA,EACV,kBAAkB;AACpB;AAOO,SAAS,uBAAuB,MAAqC;AAC1E,MAAI,SAAS,UAAa,SAAS,KAAM,QAAO;AAChD,MAAI,SAAS,aAAa,SAAS,UAAW,QAAO;AACrD,MAAI,OAAO,SAAS,YAAY,QAAQ,wBAAwB;AAC9D,WAAO,uBAAuB,IAAI;AAAA,EACpC;AACA,SAAO;AACT;AAuBO,SAAS,yBACd,QACA,QACiB;AACjB,MACE,WAAW,YACX,WAAW,YACX,WAAW,gBACX,WAAW,WACX;AACA,WAAO;AAAA,EACT;AACA,SAAO,SAAS,WAAW;AAC7B;AAqHO,IAAM,gCAAgC;;;AC1MtC,IAAM,kCAAkC;;;ACRxC,IAAM,mCAAmC;","names":[]}

package/dist/trace-types-DkIzq-l9.d.ts

@@ -0,0 +1,333 @@
+/**
+ * Verb — the action a capability performs.
+ * Used as metadata in `withProof({ verb: ... })`.
+ */
+declare const PROOF_VERBS: readonly ["create", "read", "update", "delete", "invoke", "transfer"];
+type ProofVerb = (typeof PROOF_VERBS)[number];
+/**
+ * Kind — the category of a trace step / assertion.
+ * Used in `trace_must_prove` manifest entries and emitted by `assert.*`
+ * helpers and `trace.step({ kind })` calls.
+ */
+declare const PROOF_KINDS: readonly ["happy_path", "tenant_isolation", "authorization", "validation", "error_handling", "idempotency"];
+type ProofKind = (typeof PROOF_KINDS)[number];
+/**
+ * RLS classification — how a table is scoped under Row Level Security.
+ * Emitted by the migration parser (v1). Defined here so v0.5 helpers and
+ * future tooling share the same vocabulary.
+ */
+declare const RLS_CLASSIFICATIONS: readonly ["workspace_scoped", "user_scoped", "admin_only", "public_read", "service_only", "unclassified"];
+type RlsClassification = (typeof RLS_CLASSIFICATIONS)[number];
+/**
+ * The commands a Postgres RLS policy can cover, as the migration parser reports
+ * them.
+ *
+ * `rls_classification` gives a table one label, which is a useful summary and a
+ * poor description: real policies are per-command, so a table can be readable
+ * only by admins while being writable only by the service role. `ALL` is Postgres'
+ * own wildcard and matches every command, which is why a prohibition on any single
+ * command has to consider it.
+ */
+declare const POLICY_COMMANDS: readonly ["SELECT", "INSERT", "UPDATE", "DELETE", "ALL"];
+type PolicyCommand = (typeof POLICY_COMMANDS)[number];
+/**
+ * Module kind — which of four very different things a module is.
+ *
+ * The field a planner reads first, because it decides cost and risk at once.
+ * A module moving from `generated` to `extension` is work that will never be
+ * paid for twice, and it should be visible in a diff.
+ */
+declare const MODULE_KINDS: readonly ["core", "extension", "business", "generated"];
+type ModuleKind = (typeof MODULE_KINDS)[number];
+/**
+ * How a buyer's answer reaches the code.
+ *
+ * The only technical field a planner needs, because it is what separates a
+ * cheap dispatch from an expensive one. Most of this template is `code`: the
+ * survey behind this vocabulary found exactly one real feature flag and about
+ * twenty-five decisions that mean deleting routes and components.
+ */
+declare const APPLIED_BY: readonly ["config", "content", "code"];
+type AppliedBy = (typeof APPLIED_BY)[number];
+declare function isProofVerb(value: unknown): value is ProofVerb;
+declare function isProofKind(value: unknown): value is ProofKind;
+declare function isRlsClassification(value: unknown): value is RlsClassification;
+declare function isModuleKind(value: unknown): value is ModuleKind;
+declare function isAppliedBy(value: unknown): value is AppliedBy;
+
+/**
+ * The evidential role an assertion plays.
+ *
+ *   - `primary` — the claim the proof exists to make. For an authorization or
+ *                 tenant-isolation proof that is a refusal ("the outsider could
+ *                 NOT read the row"); for a happy_path proof it is a success
+ *                 ("the user reached their workspace"). This is what a mission's
+ *                 `trace_must_prove` entry matches by default.
+ *   - `control` — a companion assertion proving the primary probe was capable of
+ *                 failing at all: "the operation that SHOULD be permitted still
+ *                 succeeded", or "the row the primary probe looked for genuinely
+ *                 exists and is readable by someone."
+ *
+ * The distinction is load-bearing, not cosmetic. A refusal probe alone cannot
+ * tell "RLS correctly hid this row" apart from "there was no row / the grant
+ * denies everyone / the table name was a typo" — every one of those yields zero
+ * rows and would record a passing assertion. The control is what makes the zero
+ * mean something.
+ *
+ * Because the validator matches `trace_must_prove` on `{ kind, target,
+ * passed: true }`, controls MUST be labelled: otherwise a control (which by
+ * design passes) could satisfy a requirement all on its own and the primary
+ * probe would never be checked at all.
+ *
+ * Naming note: an earlier draft called these `negative` / `positive_control`.
+ * That reads backwards for `happy_path`, whose primary claim is a success, so
+ * the roles are named by evidential function instead. Both older names are
+ * accepted as deprecated aliases wherever a role is parsed.
+ */
+type AssertionRole = "primary" | "control";
+/**
+ * Concrete operation exercised by an assertion. Mutation inventory keys claims
+ * by kind + target + operation so a SELECT mutation cannot silently stand in
+ * for an untested UPDATE/DELETE or action invocation.
+ */
+type ProofOperation = "select" | "insert" | "update" | "delete" | "invoke" | "request";
+/** Deprecated role spellings accepted on input and normalized to AssertionRole. */
+declare const ASSERTION_ROLE_ALIASES: Readonly<Record<string, AssertionRole>>;
+/**
+ * Normalize a role from an artifact or manifest. `undefined` means `primary`:
+ * traces written before schemaVersion 2 carry no role, and their assertions
+ * were all primary claims.
+ */
+declare function normalizeAssertionRole(role: unknown): AssertionRole | null;
+/**
+ * What an assertion concluded.
+ *
+ * `passed` / `failed` are the two verdicts a boolean can carry. The other two
+ * exist because "we did not find out" is a real outcome that a boolean has to
+ * round to one side or the other, and rounding it to `false` is indistinguishable
+ * from a genuine failure while rounding it to `true` is how a suite quietly stops
+ * proving anything:
+ *
+ *   - `incomplete` — the probe ran but could not reach a verdict (a precondition
+ *                    was missing, a dependency was unavailable).
+ *   - `skipped`    — the probe was deliberately not run, e.g. a tenant-isolation
+ *                    direction with no fixture rows on that side.
+ *
+ * Neither counts as evidence: both carry `passed: false`, so neither can satisfy
+ * a mission requirement. The status is what lets a consumer tell them apart from
+ * a real failure, and stops a skip from disappearing into "one fewer assertion".
+ */
+type AssertionStatus = "passed" | "failed" | "incomplete" | "skipped";
+/** Derive the status of an assertion that predates the field. */
+declare function normalizeAssertionStatus(status: unknown, passed: boolean): AssertionStatus;
+/**
+ * A single structured assertion recorded during a step. Produced by the
+ * `assert.*` helpers via `recordAssertion(...)`. Hand-written `expect(...)`
+ * calls inside a step do NOT appear here — only helper-driven assertions do,
+ * because the v1 mission-manifest validator matches on
+ * `{ kind, target, passed: true, role }` and needs a closed, machine-readable
+ * surface.
+ */
+interface TraceAssertion {
+    /** Category from the closed `PROOF_KINDS` vocabulary. */
+    kind: ProofKind;
+    /** The thing asserted against: table, route, action, etc. */
+    target: string;
+    /** Concrete operation the probe exercised. */
+    operation?: ProofOperation;
+    /**
+     * Whether this specific assertion held. Remains the authoritative field for
+     * the validator and for consumers: only `true` is evidence.
+     */
+    passed: boolean;
+    /**
+     * Why `passed` has the value it has. Omitted is derived from `passed`, so
+     * traces written before this field stay readable.
+     */
+    status?: AssertionStatus;
+    /**
+     * Evidential role. Omitted is treated as `"primary"` by the validator for
+     * backward compatibility with traces written before schemaVersion 2.
+     */
+    role?: AssertionRole;
+    /** Optional human-readable note for failure triage. */
+    detail?: string;
+    /**
+     * Which SDK helper produced this assertion, e.g. `"assert.tenantIsolation"`.
+     *
+     * Stamped by the SDK itself through an internal channel that the public
+     * `recordAssertion(...)` entry point cannot reach: a value supplied by spec
+     * code is stripped before the assertion is recorded. Absent means the
+     * assertion was recorded directly by a spec via `recordAssertion(...)`.
+     *
+     * The distinction is evidential. A helper-emitted assertion went through the
+     * helper's vacuity controls, ground-truth re-reads, and role bookkeeping; a
+     * spec-recorded assertion asserts whatever the spec chose to write into it.
+     * The mission validator therefore requires helper provenance for
+     * `tenant_isolation` requirements (a hand-rolled isolation probe has none of
+     * `assert.tenantIsolation`'s protections), and a mission can demand it for
+     * any requirement via `trace_must_prove[].evidence: "helper"`.
+     *
+     * For `tenant_isolation` the stamp is also identity-checked, not merely
+     * present-checked — see TENANT_ISOLATION_TABLE_HELPERS. `assert.httpResponse`
+     * records whatever `kind` its caller passes, so "some helper emitted this"
+     * is not the same claim as "the isolation probe ran".
+     */
+    emittedBy?: string;
+}
+
+/**
+ * A single step inside a proof.
+ * Produced by `t.step({ intent, kind, target }, async () => { ... })`.
+ */
+interface TraceStep {
+    /** Human-readable description of what the step attempted. */
+    intent: string;
+    /** Category of the step, from closed vocabulary. */
+    kind: ProofKind;
+    /** The thing the step targets: action name, table, route, etc. */
+    target: string;
+    /** What the step observed (returned by the step callback). */
+    observation: string;
+    /** Whether the step's assertions held. */
+    passed: boolean;
+    /** Optional: who the step acted as (email, role, seed identifier). */
+    actor?: string;
+    /** Optional: which workspace the step operated in. */
+    workspaceId?: string;
+    /** Wall-clock duration of the step callback. */
+    durationMs: number;
+    /** On failure, the error message captured. */
+    error?: string;
+    /**
+     * Structured assertions recorded by `assert.*` helpers during this step.
+     * Empty or omitted for steps that only use `expect(...)` directly.
+     * The v1 mission-manifest validator matches `trace_must_prove` entries
+     * against this array.
+     */
+    assertions?: TraceAssertion[];
+}
+/**
+ * Current per-proof trace artifact schema version.
+ *
+ * 2 — adds `role` and `status` to assertions and the `schemaVersion` /
+ *     `specFile` / `specHash` / `commit` / `dirty` provenance fields below.
+ *     Consumers written against v1 keep working: every v1 field is still present
+ *     with the same meaning, and both new assertion fields are derivable when
+ *     absent.
+ *
+ * `commit`, `dirty`, and `mutation` arrived after v2 shipped and did not bump
+ * it: they are optional additions, and the contract's rule is that additive
+ * fields do not move a version. A consumer that needs them must treat absence
+ * as "unknown" anyway, since normal runs have no mutation and a non-git
+ * checkout cannot supply code provenance.
+ */
+declare const TRACE_ARTIFACT_SCHEMA_VERSION = 2;
+/**
+ * Provenance attached only when the mutation harness deliberately plants a
+ * defect. A red mutation trace means the check detected the named defect; it
+ * must never be mistaken for a real application regression.
+ */
+interface TraceMutation {
+    /** Stable mutation identifier from the repository-owned mutation catalog. */
+    id: string;
+    /** Always true; makes the intentional nature explicit to copied consumers. */
+    planted: true;
+}
+/**
+ * A trace artifact — one proof's worth of evidence.
+ * Written atomically to `.proof/traces/<proofId>.json` when the proof
+ * completes (pass or fail).
+ */
+interface TraceArtifact {
+    /**
+     * Pinned to TRACE_ARTIFACT_SCHEMA_VERSION. Absent on traces written by
+     * SDK versions before provenance was added.
+     */
+    schemaVersion?: number;
+    /**
+     * Repo-relative path of the spec file that produced this trace, e.g.
+     * `e2e/proofs/workspace-invite.proof.ts`. Lets a reviewer go from a claim
+     * straight to the code that made it.
+     */
+    specFile?: string;
+    /**
+     * First 12 hex chars of the SHA-256 of the spec file's contents. Two runs
+     * claiming the same proof with different hashes were produced by different
+     * code — which is the whole question when a previously-red proof turns
+     * green.
+     */
+    specHash?: string;
+    /**
+     * Full SHA of the commit that was checked out while the proof ran. `specHash`
+     * pins the spec that made the claim; this pins the application it was made
+     * against, which is what lets an external ledger say "red at X, green at Y".
+     *
+     * Absent outside a git checkout. On a CI `pull_request` run this is the
+     * ephemeral merge commit the checkout created — accurate about what was
+     * tested, but not a commit you can return to later.
+     */
+    commit?: string;
+    /**
+     * Whether the working tree had uncommitted changes when the proof ran. A pass
+     * from a dirty tree is evidence about code that exists nowhere but one laptop,
+     * so a consumer gating on traces should be able to refuse it. Absent when it
+     * could not be determined, which is not the same as `false`.
+     */
+    dirty?: boolean;
+    /**
+     * Present only for intentional red runs produced by `proof:mutate`.
+     * Stored inside the trace so provenance survives artifact renames/copies.
+     */
+    mutation?: TraceMutation;
+    /**
+     * Per-file identifier for this proof. Used as the filename stem and as the
+     * join key when the v1 mission-manifest validator looks for a matching
+     * passing step for a `trace_must_prove` entry.
+     */
+    proofId: string;
+    /**
+     * Optional reference to the external mission (ticket) this proof belongs
+     * to. Multiple proofs share one `missionId`. Absent in v0.5 local runs
+     * that are not tied to a mission.
+     */
+    missionId?: string;
+    /** ISO 8601 timestamp of proof start. */
+    timestamp: string;
+    /** Total wall-clock duration across all steps. */
+    durationMs: number;
+    /** True only if every step passed. */
+    passed: boolean;
+    /** Ordered list of steps as they were executed. */
+    steps: TraceStep[];
+}
+/**
+ * Options accepted by `trace.proof(...)`. A bare string is treated as
+ * `{ proofId: string }` — the common v0.5 case where no mission is attached.
+ */
+interface ProofOptions {
+    proofId: string;
+    missionId?: string;
+}
+/**
+ * The handle passed to a proof callback. Provides the step recorder.
+ */
+interface TraceRecorder {
+    step<T extends StepResult | void>(opts: StepOptions, fn: () => Promise<T>): Promise<T>;
+}
+interface StepOptions {
+    intent: string;
+    kind: ProofKind;
+    target: string;
+    actor?: string;
+    workspaceId?: string;
+}
+/**
+ * Optional payload returned by a step callback. If the callback returns
+ * `void` the step is still recorded with `observation: ""`.
+ */
+interface StepResult {
+    observation?: string;
+}
+
+export { type AppliedBy as A, type ModuleKind as M, PROOF_KINDS as P, RLS_CLASSIFICATIONS as R, type StepOptions as S, type TraceArtifact as T, type TraceAssertion as a, APPLIED_BY as b, ASSERTION_ROLE_ALIASES as c, type AssertionRole as d, type AssertionStatus as e, MODULE_KINDS as f, PROOF_VERBS as g, type ProofKind as h, type ProofOperation as i, type ProofOptions as j, type ProofVerb as k, type RlsClassification as l, type StepResult as m, TRACE_ARTIFACT_SCHEMA_VERSION as n, type TraceMutation as o, type TraceRecorder as p, type TraceStep as q, isAppliedBy as r, isModuleKind as s, isProofKind as t, isProofVerb as u, isRlsClassification as v, normalizeAssertionRole as w, normalizeAssertionStatus as x, type PolicyCommand as y };