proof-harness 0.1.0-next.4 → 0.1.0-next.5

package/COMPATIBILITY.md

@@ -11,7 +11,7 @@ Consumers must pin an exact prerelease version, for example:
 ```json
 {
   "devDependencies": {
-    "proof-harness": "0.1.0-next.4"
+    "proof-harness": "0.1.0-next.5"
   }
 }
 ```
@@ -27,6 +27,31 @@ versions rather than guessing how to interpret them.
 
 ## Prerelease migration notes
 
+### 0.1.0-next.5
+
+No artifact schema or protocol changes. Three behavioral changes:
+
+- **`seed.workspace` no longer writes `type`.** The insert carries only
+  `name` plus caller-supplied values — the harness never invents a column
+  value it wasn't given. A schema whose `workspaces` table has required
+  columns without defaults (the conventional template's `type` included)
+  must supply them via `seed.workspace(name, { columns: { … } })` or the new
+  `workspaceColumns` option on `assert.tenantIsolation`, or add a database
+  default.
+- **`createProofServiceClient` refuses non-local targets.** Any
+  `NEXT_PUBLIC_SUPABASE_URL` whose parsed hostname is not
+  `localhost`/`127.0.0.1`/`[::1]` aborts as `unsafe_database` before a
+  client is constructed, because the suite deletes the users and workspaces
+  it seeds. CI setups reaching Supabase through a docker-network hostname
+  call `allowProofServiceHosts(["<host>"])` in code; there is no environment
+  override.
+- **`modules-check` gains an accept-list.** `.proof/module-policy.json`
+  (`schemaVersion: 1`, `acceptedUndescribed: [{ module, reason }]`) lets an
+  adopting consumer record undescribed required-root modules as visible debt
+  instead of turning the check off. Entries that stop applying fail as
+  `module_policy_stale`. Absent file = no acceptances; existing consumers
+  are unaffected.
+
 ### 0.1.0-next.4
 
 No entry-point, artifact schema, or protocol changes. The `mutate` command

package/PROOF_SDK_CONTRACT.md

@@ -941,6 +941,28 @@ operation }` assertion has neither a matching mutation nor a valid entry in
   `.proof/mutation-policy.json`, pinned to the current spec hash and a passing
   positive control. A changed/deleted claim, changed spec, missing control, or
   newly added mutation makes the acceptance stale and fails inventory.
+- **A proof run cannot target a hosted database.** `createProofServiceClient`
+  parses `NEXT_PUBLIC_SUPABASE_URL` and hard-aborts as `unsafe_database` on
+  any hostname that is not local — matched on the parsed hostname, never by
+  substring, so `localhost.example.com` does not pass. The suite deletes the
+  auth users and workspaces it seeds; against a hosted project that failure
+  is silent and unrecoverable. There is deliberately no environment-variable
+  override: a genuinely disposable non-local host (a docker-network CI
+  hostname) is allowed in code via `allowProofServiceHosts`, where a reviewer
+  sees it. The mutation runner applies the same refusal to its psql target.
+- **The harness never invents a column value it wasn't given.** Anywhere the
+  package writes to a consumer-owned table, the values are caller-supplied or
+  the column is omitted — tenancy shape is a consumer decision.
+  `seed.workspace` writes only `name`; a schema that requires more states it
+  via `seed.workspace(name, { columns })` or `workspaceColumns` on
+  `assert.tenantIsolation`.
+- **Accepted descriptor gaps expire.** `proof:modules:check` accepts an
+  undescribed required-root module only through `.proof/module-policy.json`
+  (`schemaVersion: 1`, `acceptedUndescribed: [{ module, reason }]`), each
+  entry carrying a written reason, and prints the accepted backlog on every
+  run. An acceptance whose module gains a descriptor or no longer exists
+  fails as `module_policy_stale`, so paid-down debt leaves the file rather
+  than lingering as invisible permission.
 - **A mutation that is not demonstrably live cannot judge a proof.** The
   mutation runner never (re)applies migrations; it starts (or adopts) the
   shared dev server before the first defect is planted, then reads each

package/README.md

@@ -17,7 +17,7 @@ Public prereleases are published under the npm `next` tag. Pin an exact
 prerelease version while the API is stabilizing:
 
 ```sh
-pnpm add proof-harness@0.1.0-next.4
+pnpm add proof-harness@0.1.0-next.5
 ```
 
 The package exposes environment-specific entry points:
@@ -32,6 +32,34 @@ See [PROOF_SDK_CONTRACT.md](./PROOF_SDK_CONTRACT.md) for the consumer contract
 and [COMPATIBILITY.md](./COMPATIBILITY.md) for protocol/schema compatibility
 and consumer pinning requirements.
 
+## Portability map
+
+The package has two layers; consumers should know which one they are leaning
+on:
+
+- **Assumes nothing about your schema** — trace recording and the assertion
+  vocabulary, mission validation, coverage and its ratchet, drift, mutation
+  testing, module checks, and the CLI. These read your generated schema and
+  config, or take what you give them.
+- **Assumes the conventional Supabase/workspace layout** — `seed.*` (a
+  `workspaces` table with a `name` column, a `workspace_members` join table,
+  and a `public.users` mirror maintained by a `handle_new_user` trigger) and
+  `assert.tenantIsolation`, which seeds through those helpers. The seed
+  helpers never invent column values: a schema that requires more than the
+  helpers are given states it via `seed.workspace(name, { columns })` or
+  `workspaceColumns` on `assert.tenantIsolation`.
+
+The `/api/proof/*` routes and the `NEXT_PUBLIC_SUPABASE_URL` /
+`SUPABASE_SECRET_KEY` environment names are documented protocol rather than
+template leakage.
+
+`createProofServiceClient` refuses every non-local Supabase target
+(`unsafe_database`): the proof suite deletes the auth users and workspaces it
+seeds, so a hosted project must never be reachable. A genuinely disposable
+non-local host — a docker-network hostname in CI — is allowed explicitly in
+code via `allowProofServiceHosts`; there is deliberately no environment
+override.
+
 The package also provides one `proof-harness` executable with `scan`, `parse`,
 `registry`, `build`, `verify`, `coverage`, `inventory`, `drift`, `modules`,
 `modules-check`, and `mutate` subcommands. Commands read repository paths from

package/cli/config.mjs

@@ -19,6 +19,7 @@ const DEFAULT_CONFIG = Object.freeze({
     coverage: ".proof/coverage-policy.json",
     mutation: ".proof/mutation-policy.json",
     migration: ".proof/migration-policy.json",
+    module: ".proof/module-policy.json",
   },
   roots: {
     source: "app",

package/cli/engines/proof_module_check.mjs

@@ -17,7 +17,12 @@
 //   module_missing        every core/extension module HAS a descriptor. The one
 //                         that matters most — without it, deleting a descriptor
 //                         makes every other check on that module vanish and CI
-//                         stays green.
+//                         stays green. A module may instead be accepted as
+//                         undescribed in .proof/module-policy.json with a
+//                         written reason (module_policy / module_policy_stale
+//                         guard that file), so an adopting consumer pays the
+//                         descriptor debt down module by module instead of
+//                         switching the check off.
 //   module_identity       id matches its directory; kind matches its root
 //   module_shape          the descriptor is actually the shape it claims
 //   module_question_shape ids unique and snake_case, options real and distinct,
@@ -58,6 +63,7 @@ process.on("warning", (warning) => {
 
 const MODULES_PATH = CONFIG.artifacts.modules;
 const ENV_EXAMPLE = CONFIG.repository.envExample;
+const MODULE_POLICY_PATH = CONFIG.policies.module;
 const DESCRIPTOR = "module.meta.ts";
 
 /** Roots that must carry a descriptor, and the kind each implies. */
@@ -193,22 +199,148 @@ function findCycles(modules) {
   );
 }
 
+// ---------------------------------------------------------------------------
+// Module policy
+//
+// A consumer adopting the package with existing undescribed modules would
+// otherwise face an all-or-nothing gate: write every considered descriptor
+// before the check can pass once, or switch the check off — and a check that
+// is off finds nothing at all. `.proof/module-policy.json` turns the wall
+// into the same ratchet coverage uses: a module may be accepted as
+// undescribed WITH a written reason, the listing is the visible backlog, and
+// an entry that no longer applies fails as stale so paid-down debt leaves
+// the file.
+// ---------------------------------------------------------------------------
+
+function readModulePolicy(policyPath) {
+  const empty = { acceptedUndescribed: [] };
+  if (!fs.existsSync(policyPath)) return { policy: empty, problems: [] };
+  try {
+    const policy = JSON.parse(fs.readFileSync(policyPath, "utf8"));
+    if (policy.schemaVersion !== 1) {
+      return {
+        policy: empty,
+        problems: [
+          {
+            category: "module_policy",
+            message: `${policyPath} has unsupported schemaVersion ${policy.schemaVersion ?? "<missing>"}; expected 1.`,
+          },
+        ],
+      };
+    }
+    return { policy, problems: [] };
+  } catch (error) {
+    return {
+      policy: empty,
+      problems: [
+        {
+          category: "module_policy",
+          message: `cannot read ${policyPath}: ${error instanceof Error ? error.message : String(error)}`,
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * Judge every undescribed module against the accepted-undescribed policy.
+ *
+ * `missing` is `[{ root, name, kind }]` for required-root modules without a
+ * descriptor; `described` is the set of module ids that have one. Returns the
+ * problems to report and the acceptances that applied, so the caller can make
+ * the surviving debt visible without opening the file.
+ */
+export function evaluateModulePolicy({
+  missing,
+  described,
+  policy,
+  policyPath,
+  descriptor = DESCRIPTOR,
+}) {
+  const problems = [];
+  const entries = Array.isArray(policy?.acceptedUndescribed)
+    ? policy.acceptedUndescribed
+    : [];
+
+  const byModule = new Map();
+  for (const entry of entries) {
+    if (
+      typeof entry?.module !== "string" ||
+      typeof entry?.reason !== "string" ||
+      entry.reason.trim() === ""
+    ) {
+      problems.push({
+        category: "module_policy",
+        message: `${policyPath}: every acceptedUndescribed entry needs a "module" path and a non-empty "reason", found ${JSON.stringify(entry)}. An acceptance without a written reason is not a decision anybody can revisit.`,
+      });
+      continue;
+    }
+    if (byModule.has(entry.module)) {
+      problems.push({
+        category: "module_policy",
+        message: `${policyPath}: duplicate acceptedUndescribed entry for "${entry.module}".`,
+      });
+      continue;
+    }
+    byModule.set(entry.module, entry);
+  }
+
+  const accepted = [];
+  const usedModules = new Set();
+  for (const { root, name, kind } of missing) {
+    const key = `${root}/${name}`;
+    const acceptance = byModule.get(key);
+    if (acceptance) {
+      usedModules.add(key);
+      accepted.push(acceptance);
+      continue;
+    }
+    problems.push({
+      category: "module_missing",
+      message: `expected ${root}/${name}/${descriptor} to exist, found nothing. Without a descriptor this module is invisible to a planner, and every other check on it silently does not run.`,
+      suggestion:
+        `Add ${root}/${name}/${descriptor} declaring at least id, kind and purpose (kind: "${kind}"), ` +
+        `or record the module in ${policyPath} under acceptedUndescribed with a durable reason — the listing is the backlog.`,
+    });
+  }
+
+  const describedIds = new Set(described);
+  for (const [key, entry] of byModule) {
+    if (usedModules.has(key)) continue;
+    const basename = key.split("/").at(-1);
+    const why = describedIds.has(basename)
+      ? "the module now has a descriptor — delete the acceptance"
+      : "no required-root module directory matches that path — delete or fix the acceptance";
+    problems.push({
+      category: "module_policy_stale",
+      message: `${policyPath}: acceptance for "${entry.module}" no longer applies: ${why}.`,
+    });
+  }
+
+  return { problems, accepted };
+}
+
 // ---------------------------------------------------------------------------
 // Checks
 // ---------------------------------------------------------------------------
 
-function checkCoverage(modules, problems) {
+function checkCoverage(modules, policyResult, problems) {
   const described = new Set(modules.map((m) => m.id));
+  const missing = [];
   for (const { root, kind } of REQUIRED_ROOTS) {
     for (const name of directoriesIn(root)) {
       if (described.has(name)) continue;
-      problems.push({
-        category: "module_missing",
-        message: `expected ${root}/${name}/${DESCRIPTOR} to exist, found nothing. Without a descriptor this module is invisible to a planner, and every other check on it silently does not run.`,
-        suggestion: `Add ${root}/${name}/${DESCRIPTOR} declaring at least id, kind and purpose (kind: "${kind}").`,
-      });
+      missing.push({ root, name, kind });
     }
   }
+  const outcome = evaluateModulePolicy({
+    missing,
+    described,
+    policy: policyResult.policy,
+    policyPath: MODULE_POLICY_PATH,
+  });
+  problems.push(...policyResult.problems, ...outcome.problems);
+  return outcome.accepted;
 }
 
 function checkIdentity(mod, problems) {
@@ -429,7 +561,11 @@ async function main() {
   const seenIds = new Map();
   const problems = [];
 
-  checkCoverage(modules, problems);
+  const acceptedUndescribed = checkCoverage(
+    modules,
+    readModulePolicy(MODULE_POLICY_PATH),
+    problems,
+  );
   for (const mod of modules) {
     checkIdentity(mod, problems);
     checkShape(mod, MODULE_KINDS, problems);
@@ -442,7 +578,16 @@ async function main() {
 
   if (asJson) {
     console.log(
-      JSON.stringify({ modules: modules.length, problems, cycles }, null, 2),
+      JSON.stringify(
+        {
+          modules: modules.length,
+          acceptedUndescribed,
+          problems,
+          cycles,
+        },
+        null,
+        2,
+      ),
     );
   }
 
@@ -475,10 +620,20 @@ async function main() {
     );
   }
 
+  if (acceptedUndescribed.length > 0) {
+    console.log(
+      `[proof:modules:check] ${acceptedUndescribed.length} module(s) accepted as undescribed by ${MODULE_POLICY_PATH} — that listing is the backlog:`,
+    );
+    for (const entry of acceptedUndescribed) {
+      console.log(`  - ${entry.module}: ${entry.reason}`);
+    }
+  }
+
   console.log(
     `[proof:modules:check] ${modules.length} module descriptor(s) verified against source: ` +
       `${decisions} decision(s), ${inputs} input(s), ${defaults} default(s), ` +
-      `${artifact.unowned_tables?.length ?? 0} unowned table(s).`,
+      `${artifact.unowned_tables?.length ?? 0} unowned table(s), ` +
+      `${acceptedUndescribed.length} accepted undescribed module(s).`,
   );
 }
 
@@ -495,4 +650,4 @@ if (invokedDirectly) {
   });
 }
 
-export { main, seamProblem, findCycles };
+export { main, seamProblem, findCycles, readModulePolicy };

package/dist/{fixture-B-dmnG5G.d.ts → fixture-DwDOegDK.d.ts}

@@ -25,8 +25,16 @@ declare const seed: {
      *
      * Bypasses RLS via the service-role client, so it works even when no user
      * is authenticated.
+     *
+     * The insert writes only `name` plus whatever `opts.columns` supplies: the
+     * harness never invents a column value it wasn't given, because tenancy
+     * shape is a consumer decision. A schema whose `workspaces` table requires
+     * more than `name` (a NOT NULL column without a default) states those
+     * values here — or via `workspaceColumns` on `assert.tenantIsolation`.
      */
-    workspace(name: string): Promise<SeedWorkspace>;
+    workspace(name: string, opts?: {
+        columns?: Record<string, unknown>;
+    }): Promise<SeedWorkspace>;
     /**
      * Create an auth user with the given credentials and attach them to the
      * provided workspace with the given role. Relies on the `handle_new_user`

package/dist/playwright.d.ts

@@ -1,7 +1,7 @@
 import { Page, APIResponse } from '@playwright/test';
 import { SupabaseClient } from '@supabase/supabase-js';
 import { A as ActionResult } from './action-types-C3OmHRyH.js';
-import { P as ProofFixtureContext, a as ProofFixtureFactory } from './fixture-B-dmnG5G.js';
+import { P as ProofFixtureContext, a as ProofFixtureFactory } from './fixture-DwDOegDK.js';
 import { h as ProofKind, d as AssertionRole, a as TraceAssertion, j as ProofOptions, q as TraceStep, m as StepResult, S as StepOptions } from './trace-types-DkIzq-l9.js';
 
 declare const actAsUser: {
@@ -146,6 +146,13 @@ interface TenantIsolationBaseOptions {
      * runs don't collide on error paths where teardown is skipped.
      */
     tag?: string;
+    /**
+     * Extra column values for the two seeded workspaces, forwarded to
+     * `seed.workspace`. The harness itself writes only `name`; a schema whose
+     * `workspaces` table requires more (a NOT NULL column without a default)
+     * states those values here.
+     */
+    workspaceColumns?: Record<string, unknown>;
 }
 /**
  * Tenant fixture source.

package/dist/playwright.js

@@ -599,6 +599,27 @@ var trace = {
 
 // src/server/service-client.ts
 import { createClient as createClient2 } from "@supabase/supabase-js";
+var LOCAL_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+var extraAllowedHosts = /* @__PURE__ */ new Set();
+function proofServiceHostProblem(rawUrl, allowedHosts = extraAllowedHosts) {
+  let hostname;
+  try {
+    hostname = new URL(rawUrl).hostname;
+  } catch {
+    return `NEXT_PUBLIC_SUPABASE_URL is not a parseable URL (${JSON.stringify(rawUrl)}), so it cannot be verified as local`;
+  }
+  if (LOCAL_HOSTS.has(hostname) || allowedHosts.has(hostname)) return null;
+  return `NEXT_PUBLIC_SUPABASE_URL points at a non-local Supabase (host: ${hostname})`;
+}
+function assertProofServiceUrlIsSafe(rawUrl) {
+  const problem = proofServiceHostProblem(rawUrl);
+  if (!problem) return;
+  throw new Error(
+    `[PROOF_FAIL] unsafe_database: expected a local Supabase target, found ${problem}
+  file: src/server/service-client.ts
+  suggestion: The proof suite seeds and DELETES auth users and workspaces, so it refuses every non-local database. Point NEXT_PUBLIC_SUPABASE_URL at a local stack (pnpm exec supabase start). A genuinely disposable non-local host (for example a docker-network hostname in CI) must be allowed in code via allowProofServiceHosts([...]); there is deliberately no environment-variable override.`
+  );
+}
 function requireProofEnv(name) {
   const value = process.env[name];
   if (!value) {
@@ -611,8 +632,10 @@ function requireProofEnv(name) {
   return value;
 }
 function createProofServiceClient() {
+  const url = requireProofEnv("NEXT_PUBLIC_SUPABASE_URL");
+  assertProofServiceUrlIsSafe(url);
   return createClient2(
-    requireProofEnv("NEXT_PUBLIC_SUPABASE_URL"),
+    url,
     requireProofEnv("SUPABASE_SECRET_KEY"),
     {
       auth: {
@@ -668,12 +691,18 @@ var seed = {
    *
    * Bypasses RLS via the service-role client, so it works even when no user
    * is authenticated.
+   *
+   * The insert writes only `name` plus whatever `opts.columns` supplies: the
+   * harness never invents a column value it wasn't given, because tenancy
+   * shape is a consumer decision. A schema whose `workspaces` table requires
+   * more than `name` (a NOT NULL column without a default) states those
+   * values here — or via `workspaceColumns` on `assert.tenantIsolation`.
    */
-  async workspace(name) {
+  async workspace(name, opts) {
     const sb = createProofServiceClient();
     const { data, error, status } = await sb.from("workspaces").insert({
-      name,
-      type: "team"
+      ...opts?.columns,
+      name
     }).select("id, name, owner_id").single();
     if (error || !data) {
       failSeed(
@@ -1469,8 +1498,12 @@ var assertMethods = {
     const scope = opts.scope ?? "workspace";
     const scopeColumn = opts.scopeColumn ?? (scope === "user" ? "user_id" : "workspace_id");
     validateTenantIsolationCriterion(table, scopeColumn, opts.criterion);
-    const orgA = await seed.workspace(`Proof OrgA ${tag}`);
-    const orgB = await seed.workspace(`Proof OrgB ${tag}`);
+    const orgA = await seed.workspace(`Proof OrgA ${tag}`, {
+      columns: opts.workspaceColumns
+    });
+    const orgB = await seed.workspace(`Proof OrgB ${tag}`, {
+      columns: opts.workspaceColumns
+    });
     const userA = await seed.user({
       email: `proof-a-${tag}@proof.test`,
       password: `ProofPass!${tag}1`,