proof-harness 0.1.0-next.12 → 0.1.0-next.14

package/COMPATIBILITY.md

@@ -27,10 +27,112 @@ versions rather than guessing how to interpret them.
 
 ## Prerelease migration notes
 
-### 0.1.0-next.12 — independent isolation fixtures and column ACL recovery (candidate)
-
-Not yet published. Keep the existing consumer pin until this release is reviewed
-and published; then pin exactly `proof-harness@0.1.0-next.12`.
+### 0.1.0-next.14 — isolated parallel proof gate (release candidate)
+
+Prepared for review, not yet published. Existing serial commands and assertion
+APIs remain supported. After a reviewed publication, consumers adopting the
+parallel gate must pin exactly `proof-harness@0.1.0-next.14` and update their
+lockfile. Do not switch the required release check before parity validation.
+
+The optional `plan`, `verify --plan`, `mutate --plan`, `controls --plan`,
+`finalize`, and `aggregate` commands divide complete proof specs among isolated
+checkouts. No product claims, fixtures, policies or mutation catalogs move into
+the package. Trace schema 2, mission schema 1 and health protocol 1 are unchanged.
+Parallel plans, stage records, execution reports and acceptance reports have
+separate version-1 contracts. They require the exact same harness version,
+source contents, commit, lockfile, generated schema/capabilities, configs,
+catalogs, policies and CI run/attempt throughout a run.
+
+Required integration for parallel execution:
+
+1. Add `.proof/parallel/` to the consumer's generated-output ignores (or configure
+   `artifacts.parallel`). Use fresh checkouts and fresh output directories for
+   each run. Downloaded artifacts also belong under this excluded directory.
+2. Declare `parallel.postChecks` in the protected consumer config as a nonempty
+   array of command argv arrays. Include the consumer's existing database
+   permission and browser permission controls. The package executes every
+   declared command in `finalize`, retains failures, and requires the checks at
+   aggregation. These are consumer trust inputs; the package invents none.
+3. Use one shared planning job, isolated shard jobs, and an always-run final
+   aggregation job. Each shard owns its checkout, local database, dev server,
+   fake services, browser state, build outputs and recovery journal. Two shards
+   cannot share one checkout. Workers remain one within each shard, and
+   mutation retries remain zero. An active-stage lock prevents concurrent stage
+   execution within a checkout.
+4. Regenerate schema/capabilities and perform the existing structural preflight
+   on the same source in each job. Generated artifacts must be deterministic.
+   Keep the existing database baseline and pre-mutation permission checks.
+   The planner uses Playwright discovery, including specs with no mutations;
+   a scoped baseline runs only the assigned complete specs. Automatic mutations
+   are derived from that fresh evidence and rederived from combined evidence
+   during aggregation.
+5. Run `finalize` and upload that shard's directory even when a preceding
+   mutation/control command fails. Keep matrix `fail-fast: false`. A missing,
+   cancelled or failed stage cannot satisfy the final gate. Preserve the
+   existing required check name on the final aggregation job.
+6. Compare serial and parallel runs of the same commit on separate environments:
+   complete test/claim/mutation/control inventories, coverage, exceptions and
+   post-run checks must agree. Validate the packed package and run the
+   consumer's full validation. Measure at least three complete green CI runs
+   before making the parallel gate required. Include setup, artifact transfer,
+   planning and aggregation in the runtime target; package timings omit those
+   external costs. Retain a serial command for investigation and comparison.
+
+Every discovered baseline test must pass and emit trace evidence with matching
+Playwright execution identity. Skipped tests and expected failures cannot count
+as a complete baseline. Baseline retries retain their configured behavior and
+all attempts appear in execution reports. Playwright project dependencies are
+currently rejected by planning: provision shared prerequisites explicitly in
+consumer setup instead. Proof specs must not depend on another spec's fixtures
+or order. Mutation runs must produce complete, non-timeout execution reports as
+well as the correctly mapped failing assertions.
+
+`verify --spec <path> --traces-dir <fresh-directory>` and
+`mutate|controls --spec <path> --baseline-dir <directory>` also support focused
+local diagnosis; repeat `--spec` for multiple specs. They validate the selected
+baseline independently of unrelated old traces. Partial success is not full
+release acceptance. Full coverage and mission validation occur only after the
+parallel aggregator has validated every shard. A custom parallel output path
+must stay excluded from source identity through `artifacts.parallel`.
+
+Mutation summaries retain schema version 1 and add `outcome`, `restoration`,
+`cleanupErrors`, execution status and phase timings. Each mutation produces one
+lifecycle result. An unrelated red claim, missing evidence, timeout or failed
+plant is not reported as a proof that cannot fail. Restore failures retain the
+recovery journal and block acceptance independently of detection. Original
+execution errors and later cleanup errors remain separately available.
+
+Timing history is optional and influences balancing only. It cannot remove
+work or satisfy evidence. There is no evidence reuse or partial-job resume in
+this release: a rerun needs a new plan and all shard results from that attempt.
+After an interrupted local run, use the existing `mutate --recover` procedure
+before discarding its checkout or output; a successful recovery is not a passing
+parallel run. The next clean run must establish new evidence.
+
+
+### 0.1.0-next.13 — column-restricted tenant isolation (release candidate)
+
+Prepared for release. After publication, pin exactly `proof-harness@0.1.0-next.13`
+and update the lockfile. Add `columns` only where column grants require it, then
+rerun the baseline, coverage, mutation and control checks against the real database.
+Existing consumers that omit this option need no API changes.
+
+`assert.tenantIsolation` accepts optional `columns: ["id", "account_id"]` for
+private tables that grant customers only selected columns. The SDK uses the
+same projection for service ground truth, owner controls, and outsider probes.
+Only distinct plain column names are allowed; empty lists, wildcards, aliases,
+aggregates, casts and joins are rejected before fixture setup. Omitting the
+option retains the existing all-column query.
+
+This proves row isolation for the selected columns. Consumers must separately
+prove that private columns remain unreadable; do not grant extra columns to
+make a fixture pass. Existing positive-control, bidirectional, non-vacuity and
+provenance requirements are unchanged. No trace, mission, or health protocol migration is
+required. Adopt only an exact reviewed published package version.
+
+### 0.1.0-next.12 — independent isolation fixtures and column ACL recovery
+
+Published release. Pin exactly `proof-harness@0.1.0-next.12` when adopting these changes.
 
 `assert.tenantIsolation` now accepts a caller-owned `isolationFixture` instead of
 workspace seeding. Supply a stable fixture `id`, the matching `table`, an explicit

package/README.md

@@ -107,6 +107,87 @@ Disposable users that authenticate a Playwright page must call
 `assert.tenantIsolation({ page })` performs that browser cleanup automatically;
 the page is logged out when the helper returns.
 
+## Optional isolated parallel execution
+
+The next.14 release candidate adds spec-based sharding without changing the
+serial workflow. Adopt it only after review and publication; see the
+[required integration and parity checks](COMPATIBILITY.md#010-next14--isolated-parallel-proof-gate-release-candidate).
+
+The consumer supplies its own post-run commands in `proof.config.mjs`. For
+example, if these scripts exist and cover its database and browser controls:
+
+```js
+export default {
+  // Existing paths, catalogs and trust inputs remain here.
+  parallel: {
+    postChecks: [
+      ["pnpm", "test:permissions"],
+      ["pnpm", "test:profile-permissions"],
+    ],
+  },
+};
+```
+
+After the existing environment setup and structural preflight, create a plan:
+
+```sh
+pnpm exec proof-harness plan --shards 6 \
+  --controls-config proof.controls.config.mjs \
+  --out .proof/parallel/plan.json
+```
+
+Upload the plan for the shard jobs. Each gets a separate checkout, local
+Supabase stack and fake services. After its normal setup and preflight,
+download the plan and run these commands with its zero-based matrix index:
+
+```sh
+pnpm exec proof-harness verify --plan .proof/parallel/plan.json --shard 0
+pnpm exec proof-harness mutate --plan .proof/parallel/plan.json --shard 0
+pnpm exec proof-harness controls --plan .proof/parallel/plan.json --shard 0
+pnpm exec proof-harness finalize --plan .proof/parallel/plan.json --shard 0
+```
+
+Make `finalize` an `if: always()` step, followed by an always-run artifact upload
+of `.proof/parallel/shard-0/` including hidden files. Store each shard under its
+own name and download them as `inputs/shard-0`, `inputs/shard-1`, etc. under
+`.proof/parallel/`. Upload only the plan from the planning job; never distribute
+`environment.json` or `active-stage.lock` between runners. Use six matrix values
+`[0, 1, 2, 3, 4, 5]` with `fail-fast: false`; use fewer for a smaller repository.
+The final job downloads all shards and the plan, regenerates discovery inputs,
+and runs:
+
+```sh
+pnpm exec proof-harness aggregate --plan .proof/parallel/plan.json \
+  --inputs .proof/parallel/inputs
+```
+
+The final job must run even when a shard fails, and its status must also require
+successful planning and shard jobs. Only this complete gate replaces the
+consumer's existing required Proof check. Keep consumer structural, database
+baseline and pre-mutation permission checks in the workflow; `aggregate`
+validates the complete baseline/mission, strict coverage, independently derived
+mutation inventories, mapped failures, restoration and configured postchecks.
+
+GitHub's run ID and attempt identify the run automatically. For local tests,
+set a unique `PROOF_RUN_ID` in every checkout for the same run. Local shards need
+distinct servers and databases as well as checkouts. Do not run multiple shards
+against one mutable environment, even if their traces use different folders.
+
+Successful aggregation writes an acceptance report with stage durations, slow
+specs and total runner time under `.proof/parallel/aggregate-*/acceptance.json`.
+Pass a previous report with `plan --history <file>` to balance by measured spec
+costs. History changes scheduling only; current source and catalogs determine
+all required work. Mutation execution reports retain attempts and first errors;
+SDK fixture setup/cleanup steps provide additional diagnostics. Startup and
+compilation remain part of readiness/execution where no separate measurement
+exists. An 18-minute lane warning signals that CI overhead may push the overall
+Proof job beyond a 20-minute budget.
+
+This is additional parallel capacity, not a fixed runtime guarantee. Benchmark
+with the consumer before switching its required gate, and compare total billed
+runner-minutes as well as elapsed time. Keep caches limited to dependencies;
+do not reuse evidence, database state or mutable application builds.
+
 ## License
 
 Copyright 2026 The Nexus Collective GmbH.
@@ -157,6 +238,10 @@ privileged writes and requires action-boundary evidence even without workspace
 inputs or for internal actions. See [required migration steps](COMPATIBILITY.md)
 before adopting the exact version.
 
-Release candidate `0.1.0-next.12` adds caller-owned account/user isolation fixtures
+Release `0.1.0-next.12` adds caller-owned account/user isolation fixtures
 and restores column grants and grant options after table-privilege mutations.
-Keep existing pins until publication; see [migration requirements](COMPATIBILITY.md).
+See [migration requirements](COMPATIBILITY.md).
+
+Release candidate `0.1.0-next.13` adds optional readable-column selection to
+`assert.tenantIsolation` for tables with column grants. Private-column denial
+remains a separate consumer proof; see [migration requirements](COMPATIBILITY.md).

package/cli/config.mjs

@@ -10,6 +10,7 @@ const DEFAULT_CONFIG = Object.freeze({
     drift: ".proof/drift.json",
     mutations: ".proof/mutations",
     controlSensitivity: ".proof/control-sensitivity",
+    parallel: ".proof/parallel",
   },
   // The module-descriptor system (module.meta.ts → modules.json and its
   // checker) moved to the consumer template in 0.1.0-next.6: it serves the

package/cli/engines/proof_coverage.mjs

@@ -65,7 +65,7 @@ process.chdir(CONFIG.rootDir);
 
 const SCHEMA_PATH = CONFIG.artifacts.schema;
 const CAPABILITIES_PATH = CONFIG.artifacts.capabilities;
-const TRACES_DIR = CONFIG.artifacts.traces;
+let TRACES_DIR = CONFIG.artifacts.traces;
 const POLICY_PATH = CONFIG.policies.coverage;
 
 /**
@@ -744,6 +744,13 @@ function printReport(report) {
 
 export function main() {
   const args = process.argv.slice(2);
+  const directoryIndex = args.indexOf("--traces-dir");
+  if (directoryIndex >= 0) {
+    if (!args[directoryIndex + 1] || args[directoryIndex + 1].startsWith("--"))
+      throw new Error("--traces-dir requires a directory");
+    TRACES_DIR = args[directoryIndex + 1];
+    args.splice(directoryIndex, 2);
+  }
   const strict = args.includes("--strict");
   const asJson = args.includes("--json");
 

package/cli/engines/proof_execution_reporter.mjs

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/** Sidecar only: trace, mission and health contracts remain unchanged. */
+export default class ProofExecutionReporter {
+  onBegin(_config, suite) {
+    this.started = performance.now();
+    this.report = {
+      schemaVersion: 1,
+      token: process.env.PROOF_EXECUTION_TOKEN ?? null,
+      tests: suite.allTests().map((test) => ({
+        id: `${test.parent.project().name}:${test.id}:${test.repeatEachIndex}`,
+        spec: path
+          .relative(process.cwd(), test.location.file)
+          .split(path.sep)
+          .join("/"),
+        title: test.titlePath(),
+        expectedStatus: test.expectedStatus,
+        attempts: [],
+        fixtureSpans: [],
+      })),
+      errors: [],
+    };
+  }
+  onStepEnd(test, result, step) {
+    if (!["proof fixture setup", "proof fixture cleanup"].includes(step.title))
+      return;
+    const id = `${test.parent.project().name}:${test.id}:${test.repeatEachIndex}`;
+    this.report.tests
+      .find((t) => t.id === id)
+      .fixtureSpans.push({
+        phase: step.title,
+        retry: result.retry,
+        durationMs: step.duration,
+        failed: Boolean(step.error),
+      });
+  }
+  onTestEnd(test, result) {
+    const id = `${test.parent.project().name}:${test.id}:${test.repeatEachIndex}`;
+    this.report.tests
+      .find((t) => t.id === id)
+      .attempts.push({
+        retry: result.retry,
+        status: result.status,
+        durationMs: result.duration,
+        errors: result.errors.map((e) => e.message ?? String(e)),
+      });
+  }
+  onError(error) {
+    this.report?.errors.push(error.message ?? String(error));
+  }
+  onEnd(result) {
+    if (!this.report || !process.env.PROOF_EXECUTION_REPORT) return;
+    this.report.status = result.status;
+    this.report.durationMs = performance.now() - this.started;
+    fs.mkdirSync(path.dirname(process.env.PROOF_EXECUTION_REPORT), {
+      recursive: true,
+    });
+    fs.writeFileSync(
+      process.env.PROOF_EXECUTION_REPORT,
+      JSON.stringify(this.report, null, 2) + "\n",
+      { flag: "wx" },
+    );
+  }
+}

package/cli/engines/proof_inventory_build.mjs

@@ -0,0 +1,136 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isArtifactId, readTraceDirectory } from "../../dist/node.js";
+import { evidenceExclusions } from "../config.mjs";
+import { validateControlBaseline } from "./proof_control_sensitivity.mjs";
+import {
+  deriveAutomaticRlsMutations,
+  evaluateMutationClaimCoverage,
+  mutationCoversClaim,
+} from "./proof_mutation_inventory.mjs";
+
+function readMutationPolicy(MUTATION_POLICY_PATH) {
+  try {
+    const policy = JSON.parse(fs.readFileSync(MUTATION_POLICY_PATH, "utf8"));
+    if (policy.schemaVersion !== 1) {
+      return {
+        policy: { acceptedClaims: [] },
+        problems: [
+          `${MUTATION_POLICY_PATH} has unsupported schemaVersion ${policy.schemaVersion ?? "<missing>"}; expected 1`,
+        ],
+      };
+    }
+    return { policy, problems: [] };
+  } catch (error) {
+    return {
+      policy: { acceptedClaims: [] },
+      problems: [
+        `cannot read ${MUTATION_POLICY_PATH}: ${error instanceof Error ? error.message : String(error)}`,
+      ],
+    };
+  }
+}
+
+export function buildMutationInventory({
+  config: CONFIG,
+  mutations: catalog,
+  controlSensitivity: CONTROL_SENSITIVITY = false,
+  tracesDir: TRACE_DIR = CONFIG.artifacts.traces,
+  specs = /** @type {string[] | null} */ (null),
+}) {
+  if (!catalog.every((m) => isArtifactId(m.id) && typeof m.spec === "string"))
+    throw new Error("invalid mutation identity");
+  const MUTATIONS = specs
+    ? catalog.filter((m) => specs.includes(m.spec))
+    : catalog;
+  TRACE_DIR = path.resolve(CONFIG.rootDir, TRACE_DIR);
+  const MUTATION_POLICY_PATH = path.resolve(
+    CONFIG.rootDir,
+    CONFIG.policies.mutation,
+  );
+  const SCHEMA_PATH = path.resolve(CONFIG.rootDir, CONFIG.artifacts.schema);
+  if (CONTROL_SENSITIVITY) {
+    if (!CONFIG.controlSensitivityCatalog)
+      throw new Error(
+        "[PROOF_FAIL] control_contract: configure a separate controlSensitivityCatalog",
+      );
+    const traces = readTraceDirectory(TRACE_DIR, {
+      rootDir: CONFIG.rootDir,
+      excludedPaths: evidenceExclusions(CONFIG),
+    });
+    const ids = new Set();
+    const mutations = MUTATIONS.map((m) => {
+      if (ids.has(m.id)) throw new Error("duplicate control-sensitivity id");
+      ids.add(m.id);
+      return { ...m, resolvedControls: validateControlBaseline(m, traces) };
+    });
+    return {
+      mutations,
+      problems: [],
+      claims: [],
+      acceptedClaims: [],
+      uncoveredClaims: [],
+      uncoveredActionClaims: [],
+    };
+  }
+  const derived = deriveAutomaticRlsMutations({
+    tracesDir: TRACE_DIR,
+    rootDir: CONFIG.rootDir,
+    excludedPaths: evidenceExclusions(CONFIG),
+    schemaPath: SCHEMA_PATH,
+    explicitMutations: MUTATIONS,
+  });
+  const mutations = [...MUTATIONS, ...derived.mutations];
+  const ids = new Set();
+  const problems = [...derived.problems];
+
+  for (const mutation of mutations) {
+    if (ids.has(mutation.id)) {
+      problems.push(`duplicate mutation id "${mutation.id}"`);
+    }
+    ids.add(mutation.id);
+  }
+
+  const loadedPolicy = readMutationPolicy(MUTATION_POLICY_PATH);
+  if (specs)
+    loadedPolicy.policy = {
+      ...loadedPolicy.policy,
+      acceptedClaims: (loadedPolicy.policy.acceptedClaims ?? []).filter((c) =>
+        specs.includes(c.spec),
+      ),
+    };
+  const claimCoverage = evaluateMutationClaimCoverage({
+    claims: derived.claims,
+    evidence: derived.evidence,
+    mutations,
+    policy: loadedPolicy.policy,
+  });
+  problems.push(...loadedPolicy.problems, ...claimCoverage.problems);
+  for (const claim of claimCoverage.uncoveredClaims) {
+    problems.push(
+      `${claim.spec} has no mutation or accepted policy entry for ${claim.kind}:${claim.target}:${claim.operation}`,
+    );
+  }
+
+  const mutationsWithClaims = mutations.map((mutation) => ({
+    ...mutation,
+    resolvedClaims: derived.claims
+      .filter((claim) => mutationCoversClaim(mutation, claim))
+      .map((claim) => ({
+        kind: claim.kind,
+        target: claim.target,
+        operation: claim.operation,
+      })),
+  }));
+
+  return {
+    mutations: mutationsWithClaims,
+    problems,
+    claims: derived.claims,
+    acceptedClaims: claimCoverage.acceptedClaims,
+    uncoveredClaims: claimCoverage.uncoveredClaims,
+    uncoveredActionClaims: claimCoverage.uncoveredClaims.filter((claim) =>
+      /^[A-Za-z][\w-]*:[A-Za-z][\w-]*$/.test(claim.target),
+    ),
+  };
+}