create-cmp-cli 0.23.0 → 0.25.0

package/packages/harness/src/lib/harness-lock.mjs

@@ -8,19 +8,27 @@
 //              Answered LOCALLY, offline, on every lane run. Needs nothing
 //              but the tree and this file.
 //
-//   AUTHENTICITY  "is my lane the real published @create-cmp/harness@X?"
-//              Answered REMOTELY, on request, by comparing this file's
-//              `sha256` against the published version's — `create-cmp
-//              upgrade --harness` does it, and so can any third party
-//              holding a receipt.
+//   AUTHENTICITY  "is my lane the real published prooflane-harness@X?"
+//              NOT ANSWERED ANYWHERE IN THIS REPO — see below. The per-file
+//              map this lock records is what such a check would compare
+//              against a published artifact; nothing performs the comparison.
 //
-// Being honest about that split matters. Someone who edits the lane AND
-// rewrites this lock defeats the local check — of course they do; it is a
-// checksum, not a signature. What it cannot survive is the remote comparison,
-// because the attacker cannot change what the registry published under that
-// version number. Local integrity catches the accident and the drift (an
-// agent "fixing" a lane file, a half-applied upgrade); the remote comparison
-// catches the lie. Neither claim is stretched to cover the other's job.
+// Being honest about that split matters, and this comment was not. It used to
+// say `create-cmp upgrade --harness` performed the remote comparison. It does
+// not and never has: that command reads the version out of a LOCAL
+// packages/harness/package.json and re-locks from local bytes
+// (src/commands/upgrade.mjs:410-413). The only registry call in the tree packs
+// `create-cmp-cli@<v>` as an upgrade's merge base. So the sentence promising
+// that "the attacker cannot change what the registry published" described a
+// defence that does not exist — in the module whose whole job is to be precise
+// about which question it answers, which is the failure this harness exists to
+// refuse (ADR-0008, which found it).
+//
+// What is true: someone who edits the lane AND rewrites this lock defeats the
+// local check — of course they do; it is a checksum, not a signature. Local
+// integrity catches the accident and the drift (an agent "fixing" a lane file,
+// a half-applied upgrade). It catches no lie, and until a remote comparison is
+// built, nothing here does.
 //
 // The lock is deliberately NOT a .mjs file, so it is not part of the region it
 // describes — a manifest inside its own manifest could never settle.
@@ -30,10 +38,16 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { hashHarnessRegion, compareHarnessRegion } from "./harness-region.mjs";
+import { hashHarnessRegion, compareHarnessRegion, isAdopterOwned } from "./harness-region.mjs";
 
 export const LOCK_PATH = "qa/harness.lock.json";
-export const LOCK_SCHEMA = "cmp-harness-lock/1";
+// ADR-0007 deferred this one with a condition: the lock's schema string
+// "finishes that journey with the package work, not in this PR". That work has
+// landed — the lock has written `name: "prooflane-harness"` since the package
+// rename, which is the split ADR-0007 itself pointed at as observable in the
+// tree. The condition is met, so the journey finishes here. Nothing reads the
+// field; `readHarnessLock` parses the file and never inspects it.
+export const LOCK_SCHEMA = "prooflane-harness-lock/1";
 
 /**
  * Read the lock, or null when it is absent or unparsable. An unreadable lock
@@ -61,7 +75,7 @@ export function readHarnessLock(root) {
  * @param {{name?: string, version: string}} harness identity to record
  * @returns {{sha256: string, fileCount: number}}
  */
-export function writeHarnessLock(root, { name = "@create-cmp/harness", version }) {
+export function writeHarnessLock(root, { name = "prooflane-harness", version }) {
   if (typeof version !== "string" || version.length === 0) {
     throw new Error("writeHarnessLock: a harness version is required");
   }
@@ -109,6 +123,8 @@ export function checkHarnessIntegrity(root) {
       missing: [],
       extra: [],
       fileCount: region.fileCount,
+      engineFiles: region.engineFiles,
+      vacuous: region.engineFiles === 0,
     };
   }
 
@@ -123,6 +139,12 @@ export function checkHarnessIntegrity(root) {
     missing: cmp.missing,
     extra: cmp.extra,
     fileCount: region.fileCount,
+    // ADR-0010: how much of this region is the LANE, and whether it is a lane
+    // at all. `status` is deliberately untouched — a region of three
+    // declarations genuinely IS unmodified since it was locked; it is simply
+    // not a lane, and that is a different question from the one status answers.
+    engineFiles: region.engineFiles,
+    vacuous: region.engineFiles === 0,
   };
 }
 
@@ -133,6 +155,19 @@ export function checkHarnessIntegrity(root) {
  * @returns {string}
  */
 export function describeIntegrity(r) {
+  // ADR-0010, AND THIS IS THE REACHABLE HALF OF IT. `status` is honest — a
+  // region of declarations really is unmodified since it was locked — so a
+  // caller rendering that status alone says "N files verified" over a lane that
+  // holds no lane. Every caller that checks a tree it does not LIVE in reaches
+  // this: `create-cmp upgrade --harness` and `harden` print it over an
+  // arbitrary project directory, `prooflane upgrade` over the adopter's root,
+  // and a hosted checker over a repo it fetched. The shipped lane cannot (it
+  // derives its root from its own location, so its own module is always in the
+  // region) — which is exactly why the fix belongs in the shared voice rather
+  // than in one step.
+  if (r.vacuous) {
+    return `${r.name ?? "harness"} ${r.version ?? "?"} — ${r.fileCount} file(s) locked and NONE of them engine code: this is not a lane, and nothing here can vouch for one`;
+  }
   if (r.status === "intact") {
     // The region digest rides beside the version: two lanes can carry the same
     // package version with different content (create-cmp-showcase, 2026-09-03 —
@@ -144,9 +179,42 @@ export function describeIntegrity(r) {
   if (r.status === "unlocked") {
     return `no ${LOCK_PATH} — this app's lane version is unrecorded`;
   }
+  // NAME THE FILES. This used to report counts only — "1 unrecorded" — while
+  // holding the paths in `r.extra` and never showing them. The first adopter to
+  // hit it was following our own README, whose step 1 writes a file that is in
+  // HARNESS_DECLARATIONS: a correct refusal they could not act on, because the
+  // one fact that makes it actionable was in the object and not in the sentence.
+  // Evidence-or-silence: a gate that refuses names what it refused over.
   const parts = [];
-  if (r.modified.length) parts.push(`${r.modified.length} modified`);
-  if (r.missing.length) parts.push(`${r.missing.length} missing`);
-  if (r.extra.length) parts.push(`${r.extra.length} unrecorded`);
-  return `${r.name ?? "harness"} ${r.version ?? "?"} — ${parts.join(", ")}`;
+  const show = (list, label) => {
+    if (!list.length) return;
+    const head = list.slice(0, 3).join(", ");
+    parts.push(`${list.length} ${label}: ${head}${list.length > 3 ? `, +${list.length - 3} more` : ""}`);
+  };
+  show(r.modified, "modified");
+  show(r.missing, "missing");
+  show(r.extra, "unrecorded");
+  // WHICH command helps depends on WHOSE files differ, and the two answers are
+  // opposites. An adopter editing their own profile or declaration is doing the
+  // one thing the harness tells them to do (the profile header says "This file
+  // is YOURS"), and the cure is to re-take the lock. A machine-owned file
+  // differing is a fork, and re-taking the lock over THAT would make every
+  // later receipt vouch for code the harness has never seen. Naming one command
+  // for both is how the first adopter to edit their profile got a lane that
+  // could not be un-failed: `harness init` refused ("already exists") and
+  // `upgrade --harness` refused (no create-cmp.json).
+  //
+  // CONDITIONAL on purpose. `isAdopterOwned` is a name rule and cannot know
+  // whether a given profile is one the ENGINE vendors (`qa/lib/profiles/cmp/`
+  // in every stamped Compose app) — teaching this module a profile id is the
+  // coupling Stage 0 removed. So this offers the command rather than asserting
+  // the ownership; `create-cmp harness relock` is where the decision is made,
+  // and it refuses a shipped profile by name.
+  const differing = [...r.modified, ...r.missing, ...r.extra];
+  const fix = differing.every(isAdopterOwned)
+    ? " — if these are yours (your profile, your declarations), re-lock with `create-cmp harness relock`"
+    : r.extra.length && !r.modified.length && !r.missing.length
+      ? " — re-lock with `create-cmp upgrade --harness`, or remove the file if it should not be there"
+      : "";
+  return `${r.name ?? "harness"} ${r.version ?? "?"} — ${parts.join("; ")}${fix}`;
 }

package/packages/harness/src/lib/harness-manifest.mjs

@@ -0,0 +1,208 @@
+// harness-manifest.mjs — WHICH STACK PROFILE this project uses, and where it
+// keeps the things the lane reads. The lane's own reader of
+// qa/harness-manifest.json.
+//
+// WHY THE LANE READS IT NOW. The manifest existed before this file — written
+// for the console, read by seven console modules and zero lane modules — so
+// the lane kept hardcoding one project's layout (composeApp/src, qa/e2e, the
+// Compose step pack imported by name) while the console beside it had learned
+// to ask. This closes that: the lane resolves the manifest first, loads the
+// profile it names (qa/lib/profile-loader.mjs), and only then knows what a
+// "step" or a "test root" is for this project.
+//
+// THERE IS NO DEFAULT PROFILE (decision 3, 2026-09-04). The Compose profile is
+// a profile like any other; a privileged default would be the coupling this
+// removes wearing a different name. So an ABSENT manifest is a refusal that
+// names the command which writes one:
+//
+//   a stamped app (create-cmp.json present)  →  create-cmp upgrade --harness
+//                                                derives it from what it knows
+//   a foreign repo, any stack                 →  create-cmp harness init
+//                                                writes the manifest, a working
+//                                                profile, the surface and the
+//                                                lock, then runs Rule 0
+//
+// A PRESENT-BUT-MALFORMED manifest is refused too, naming every problem at
+// once — never silently defaulted, for the reason the console's reader gives:
+// a lane that falls back to the wrong layout reports an honest-looking absence
+// of files that exist ten characters away.
+//
+// The shape is FLAT: the layout fields sit beside `schema` and `profile`, not
+// under a nested `layout` key. The console's reader validates field-by-field
+// and refuses unknown keys, and a stamped app must satisfy both readers with
+// one file. (Stage 0.5 unifies the two readers; the flat shape is what both
+// accept today.)
+//
+// SINGLE SOURCE OF TRUTH: packages/harness/src/lib/harness-manifest.mjs in the
+// create-cmp repo. The copy in a generated project's qa/lib/ is vendored
+// byte-identical at scaffold time — edit the package source, then run
+// `node scripts/sync-harness.mjs`.
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** Where a project declares its profile and layout. Required for the lane to run. */
+export const MANIFEST_REL_PATH = "qa/harness-manifest.json";
+
+/** The manifest schema this lane writes and understands. */
+export const MANIFEST_SCHEMA = "harness-manifest/2";
+
+/** Layout fields that are single project-relative paths. */
+export const LAYOUT_PATH_FIELDS = ["receipt", "architectureDoc", "specs", "approvals"];
+/** Layout fields that are non-empty lists. `packs` is informational (console). */
+export const LAYOUT_LIST_FIELDS = ["citationRoots", "packs"];
+const META_FIELDS = ["schema", "profile"];
+const KNOWN_FIELDS = new Set([...META_FIELDS, ...LAYOUT_PATH_FIELDS, ...LAYOUT_LIST_FIELDS]);
+
+/** A profile id is one path segment, lowercase, dash-separated — it becomes a directory name. */
+export const PROFILE_ID_RE = /^[a-z][a-z0-9-]*$/;
+
+function pathProblem(field, value) {
+  if (typeof value !== "string" || value.trim() === "") return `${field} must be a non-empty string`;
+  if (value.startsWith("/") || /^[A-Za-z]:[\\/]/.test(value)) return `${field} must be relative to the project root (got "${value}")`;
+  if (value.includes("\\")) return `${field} must use "/" separators (got "${value}")`;
+  if (value.split("/").some((seg) => seg === "..")) return `${field} may not escape the project root (got "${value}")`;
+  return null;
+}
+
+/**
+ * Every contract violation in a parsed manifest, or [] when it is valid. Never
+ * throws — a caller prints all defects at once rather than the first.
+ * @param {unknown} parsed
+ * @returns {string[]}
+ */
+export function manifestProblems(parsed) {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return ["the manifest must be a JSON object"];
+  const problems = [];
+  for (const key of Object.keys(parsed)) {
+    if (!KNOWN_FIELDS.has(key)) problems.push(`unknown field "${key}" (known: ${[...KNOWN_FIELDS].join(", ")})`);
+  }
+  if ("schema" in parsed && (typeof parsed.schema !== "string" || !parsed.schema.startsWith("harness-manifest/"))) {
+    problems.push(`schema must be a string of the form "harness-manifest/<n>" (got ${JSON.stringify(parsed.schema)})`);
+  }
+  // The profile is the one REQUIRED field: without it the lane cannot know
+  // what a step is for this project, and guessing is the bug this file closes.
+  if (!("profile" in parsed)) {
+    problems.push(`profile is required — add "profile": { "id": "<profile>" } naming the stack profile under qa/lib/profiles/`);
+  } else {
+    const p = parsed.profile;
+    if (!p || typeof p !== "object" || Array.isArray(p)) problems.push("profile must be an object { id, version? }");
+    else {
+      if (typeof p.id !== "string" || !PROFILE_ID_RE.test(p.id)) {
+        problems.push(`profile.id must match ${PROFILE_ID_RE} — it names a directory under qa/lib/profiles/ (got ${JSON.stringify(p.id)})`);
+      }
+      if ("version" in p && typeof p.version !== "string") problems.push("profile.version must be a string when present");
+      for (const key of Object.keys(p)) {
+        if (key !== "id" && key !== "version") problems.push(`profile has an unknown field "${key}" (known: id, version)`);
+      }
+    }
+  }
+  for (const field of LAYOUT_PATH_FIELDS) {
+    if (!(field in parsed)) continue;
+    const p = pathProblem(field, parsed[field]);
+    if (p) problems.push(p);
+  }
+  for (const field of LAYOUT_LIST_FIELDS) {
+    if (!(field in parsed)) continue;
+    const list = parsed[field];
+    if (!Array.isArray(list) || list.length === 0) {
+      problems.push(`${field} must be a non-empty array of strings`);
+      continue;
+    }
+    list.forEach((entry, i) => {
+      const p =
+        field === "citationRoots"
+          ? pathProblem(`${field}[${i}]`, entry)
+          : typeof entry === "string" && entry.trim()
+            ? null
+            : `${field}[${i}] must be a non-empty string`;
+      if (p) problems.push(p);
+    });
+  }
+  return problems;
+}
+
+/**
+ * The refusal for a MISSING manifest — which names the command that writes
+ * one, because the two kinds of project get there differently.
+ * @param {string} root
+ * @returns {string}
+ */
+export function absentManifestReason(root) {
+  const stamped = fs.existsSync(path.join(root, "create-cmp.json"));
+  const how = stamped
+    ? "This is a create-cmp app: run `create-cmp upgrade --harness` and it will write the manifest from what it already knows."
+    : "Run `create-cmp harness init` — it writes the manifest, a working profile for this project, the verified surface and the lock, then proves the lane returns.";
+  return (
+    `${MANIFEST_REL_PATH} is missing — the lane cannot run without knowing which stack profile this project uses, ` +
+    `and there is no default. ${how}`
+  );
+}
+
+/**
+ * Resolve the project's manifest.
+ *
+ * @param {string} root project root
+ * @returns {{ok: true, manifest: object, relPath: string}
+ *         | {ok: false, absent: boolean, reason: string, relPath: string}}
+ *   absent  true when no file exists (the reason names the command that writes one)
+ *           false when a file exists and is unusable (the reason names every problem)
+ */
+export function resolveHarnessManifest(root) {
+  const file = path.join(root, ...MANIFEST_REL_PATH.split("/"));
+  if (!fs.existsSync(file)) {
+    return { ok: false, absent: true, relPath: MANIFEST_REL_PATH, reason: absentManifestReason(root) };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (err) {
+    return {
+      ok: false,
+      absent: false,
+      relPath: MANIFEST_REL_PATH,
+      reason: `${MANIFEST_REL_PATH} is not valid JSON (${err && err.message ? err.message : String(err)}) — fix it; no layout is assumed while a manifest is present`,
+    };
+  }
+  const problems = manifestProblems(parsed);
+  if (problems.length) {
+    return {
+      ok: false,
+      absent: false,
+      relPath: MANIFEST_REL_PATH,
+      reason: `${MANIFEST_REL_PATH} is malformed: ${problems.join("; ")} — fix it; no layout is assumed while a manifest is present`,
+    };
+  }
+  return { ok: true, manifest: parsed, relPath: MANIFEST_REL_PATH };
+}
+
+/**
+ * A manifest for a profile, with optional layout overrides — what `attach`
+ * writes after its interview and what a stamper ships.
+ * @param {string} profileId
+ * @param {object} [layout] layout fields to carry (validated on write)
+ * @returns {object}
+ */
+export function manifestFor(profileId, layout = {}) {
+  return { schema: MANIFEST_SCHEMA, profile: { id: profileId }, ...layout };
+}
+
+/**
+ * Write a manifest — after validating it. A writer that could put an invalid
+ * manifest on disk would hand the next lane run a refusal it created itself.
+ * @param {string} root
+ * @param {object} manifest
+ * @returns {{ok: true, relPath: string} | {ok: false, reason: string}}
+ */
+export function writeHarnessManifest(root, manifest) {
+  const problems = manifestProblems(manifest);
+  if (problems.length) return { ok: false, reason: `refusing to write an invalid manifest: ${problems.join("; ")}` };
+  try {
+    const file = path.join(root, ...MANIFEST_REL_PATH.split("/"));
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
+    return { ok: true, relPath: MANIFEST_REL_PATH };
+  } catch (err) {
+    return { ok: false, reason: err && err.message ? err.message : String(err) };
+  }
+}

package/packages/harness/src/lib/harness-region.mjs

@@ -64,6 +64,18 @@ export const HARNESS_DIRS = ["qa", "qa/lib"];
  */
 export const HARNESS_TEST_DIR = "qa/test";
 
+/**
+ * STACK PROFILES — qa/lib/profiles/<id>/**. Every `.mjs` under it, recursively,
+ * is machine-owned: a profile is the set of gates, tiers and steps the lane
+ * runs for this project, loaded by id from qa/harness-manifest.json
+ * (qa/lib/profile-loader.mjs). An edited profile that stayed outside the lock
+ * could redefine what "done" means and still have the lane vouch for the
+ * result — GATE-RULES Rule 2, the layer you changed cannot certify itself.
+ * Named and recursive on purpose, like HARNESS_TEST_DIR: a nested directory
+ * enters the region only by someone widening the rule here, never by shape.
+ */
+export const HARNESS_PROFILES_DIR = "qa/lib/profiles";
+
 /**
  * DECLARATIONS the lane READS to decide what it attests — locked for the same
  * reason verify.mjs is. payment-blueprint's planted proof (2026-09-03): remove
@@ -77,6 +89,88 @@ export const HARNESS_TEST_DIR = "qa/test";
  */
 export const HARNESS_DECLARATIONS = ["qa/verified-surface.json", "qa/harness-manifest.json"];
 
+/**
+ * MACHINE-OWNED files that are not .mjs and not declarations. Today: the
+ * provenance record (lib/harness-source.mjs) — which artifact was vendored and
+ * where it came from, written by init and rewritten by upgrade.
+ *
+ * It is in the region for one reason: inside it, the record is inside
+ * `lock.files` and inside `inputs.hash`, so a hand-edited origin FAILs
+ * harnessIntegrity by name. Provenance is offered as no kind of check
+ * (ADR-0008), and that is precisely why it must not also be silently editable —
+ * a field nothing verifies and anyone can rewrite is worse than an absent one.
+ *
+ * It is deliberately NOT in HARNESS_DECLARATIONS, though it sits beside them:
+ * that list is what `harness relock` may re-baseline, and an adopter re-locking
+ * their own edited provenance is the one outcome this must never allow.
+ *
+ * Absent is fine everywhere — `listHarnessFiles` lists what exists, so a lane
+ * installed before this file existed has an unchanged region and an unchanged
+ * lock.
+ */
+export const HARNESS_GENERATED = ["qa/harness-source.json"];
+
+/**
+ * Of the locked region, WHICH files does the adopter author?
+ *
+ * The region is one lock but two kinds of file, and conflating them is what
+ * bricked the first foreign adopter (2026-09-05). `harness init` generates
+ * qa/lib/profiles/<id>/index.mjs with a header that says "This file is YOURS",
+ * and the README tells adopters to correct qa/harness-manifest.json and
+ * qa/verified-surface.json — then the first such edit FAILs harnessIntegrity
+ * with no command that could re-take the lock. Their profile is inside the
+ * lock for a good reason (an edited gate pack must not certify itself
+ * silently), so the answer is not to unlock it; it is to name the subset a
+ * re-lock may cover:
+ *
+ *   qa/lib/profiles/<id>/**        the profile they wrote — <id> REQUIRED, so a
+ *                                  loose qa/lib/profiles/*.mjs stays machine-owned
+ *   HARNESS_DECLARATIONS           the two files the lane READS from them
+ *
+ * Everything else — every .mjs directly under qa/ and qa/lib/, and qa/test/**
+ * — is engine code. An edit there is a fork, and `create-cmp harness relock`
+ * refuses it rather than re-baselining a lane the harness has never seen.
+ *
+ * This rule is deliberately NAME-based and stack-free: it says nothing about
+ * which profile ids the engine itself vendors (`create-cmp harness relock`
+ * layers that on, from the harness package it ships with — the core does not
+ * learn a profile id). So a vendored lane can use this to point a failing
+ * adopter at the right command; the command is where the gate actually is.
+ *
+ * @param {string} relPath project-relative path, "/"-separated
+ * @returns {boolean}
+ */
+export function isAdopterOwned(relPath) {
+  if (!isHarnessFile(relPath)) return false;
+  if (HARNESS_DECLARATIONS.includes(relPath)) return true;
+  const prefix = `${HARNESS_PROFILES_DIR}/`;
+  return relPath.startsWith(prefix) && relPath.slice(prefix.length).includes("/");
+}
+
+/**
+ * Is this region member ENGINE CODE — the lane itself, as opposed to what the
+ * lane reads about itself or the profile the adopter wrote?
+ *
+ * The three exclusions are the region's non-engine halves: the declarations
+ * (`qa/verified-surface.json`, `qa/harness-manifest.json`), the generated
+ * provenance record, and `qa/lib/profiles/<id>/**` — an adopter's own pack is
+ * theirs, and a region holding a profile and no spine is still a lane with no
+ * engine in it.
+ *
+ * ADR-0010: a region with zero of these is VACUOUS. It reads `intact` because
+ * it genuinely is unmodified since it was locked — it is simply not a lane.
+ *
+ * @param {string} relPath project-relative path, "/"-separated
+ * @returns {boolean}
+ */
+export function isEngineModule(relPath) {
+  if (!isHarnessFile(relPath)) return false;
+  if (HARNESS_DECLARATIONS.includes(relPath)) return false;
+  if (HARNESS_GENERATED.includes(relPath)) return false;
+  if (relPath.startsWith(`${HARNESS_PROFILES_DIR}/`)) return false;
+  return relPath.endsWith(".mjs");
+}
+
 /**
  * Is this project-relative path part of the machine-owned harness region?
  * @param {string} relPath project-relative path, "/"-separated
@@ -85,8 +179,10 @@ export const HARNESS_DECLARATIONS = ["qa/verified-surface.json", "qa/harness-man
 export function isHarnessFile(relPath) {
   if (typeof relPath !== "string") return false;
   if (HARNESS_DECLARATIONS.includes(relPath)) return true;
+  if (HARNESS_GENERATED.includes(relPath)) return true;
   if (!relPath.endsWith(".mjs")) return false;
   if (relPath.startsWith(`${HARNESS_TEST_DIR}/`)) return true;
+  if (relPath.startsWith(`${HARNESS_PROFILES_DIR}/`)) return true;
   const dir = relPath.includes("/") ? relPath.slice(0, relPath.lastIndexOf("/")) : "";
   return HARNESS_DIRS.includes(dir);
 }
@@ -127,10 +223,11 @@ export function listHarnessFiles(root) {
     }
   }
   walkMjs(path.join(root, HARNESS_TEST_DIR), HARNESS_TEST_DIR, found);
+  walkMjs(path.join(root, HARNESS_PROFILES_DIR), HARNESS_PROFILES_DIR, found);
   // A declaration directly under qa/ is already seen by the scan above (it is
   // a harness file by name); the explicit loop covers one that lives deeper.
   // Deduplicated so no path is hashed twice.
-  for (const rel of HARNESS_DECLARATIONS) {
+  for (const rel of [...HARNESS_DECLARATIONS, ...HARNESS_GENERATED]) {
     if (fs.existsSync(path.join(root, ...rel.split("/")))) found.push(rel);
   }
   return [...new Set(found)].sort();
@@ -161,7 +258,14 @@ export function hashHarnessRegion(root) {
     files[rel] = h;
     digest.update(rel, "utf8").update("\0").update(h, "utf8").update("\n");
   }
-  return { sha256: digest.digest("hex"), fileCount: rels.length, files };
+  return {
+    sha256: digest.digest("hex"),
+    fileCount: rels.length,
+    // ADR-0010: how many of those files are the LANE. `fileCount` counts the
+    // region; this counts the engine in it, and zero is the vacuous self-vouch.
+    engineFiles: rels.filter(isEngineModule).length,
+    files,
+  };
 }
 
 /**

package/packages/harness/src/lib/harness-source.mjs

@@ -0,0 +1,142 @@
+// WHERE THIS LANE'S BYTES CAME FROM — ADR-0008's provenance, as a file.
+//
+// THE DECISION THIS IMPLEMENTS. ADR-0008 (accepted 2026-09-08) settled that the
+// harness is ALWAYS vendored: pinning is how the bytes arrive, never how they
+// are trusted, so there is one kind of receipt. What resolution adds is
+// PROVENANCE — `source ∈ {local, registry, git}` — "recorded because the
+// resolver knows it, and never counted as a check by anything."
+//
+// WHAT IT BUYS, precisely, and it is one thing. A checker with a network needs
+// to know WHICH artifact to fetch before comparing it to `lock.files`, and
+// whether fetching one is meaningful at all. `name` + `version` + `source` are
+// those fetch coordinates. Without them a reader cannot tell a receipt naming a
+// version that was never published from one naming a version they can pull —
+// and the published core HAS sat versions behind this tree, so both exist.
+//
+// IT IS NOT A CHECK, AND MUST NEVER READ AS ONE. It is exactly as forgeable as
+// the `version` beside it. Nothing gates on it, no verdict consults it, and a
+// notary that compares the lock against a registry reports that as ITS finding,
+// dated and named — never as a property of the receipt (ADR-0008; NORTH-STAR
+// §8.2's "notarisation is not examination").
+//
+// WHY IT IS A FILE IN THE LOCKED REGION rather than a field in the lock. Two
+// reasons, and the second is the load-bearing one:
+//
+//   1. The lock cannot hash itself, so a `source` written there sits outside
+//      every digest — the one place an editor's change leaves no trace.
+//   2. Inside the region it is inside `lock.files` AND inside `inputs.hash`,
+//      so editing it FAILs harnessIntegrity by name. Provenance is offered as
+//      no kind of check; that is no reason to make it silently editable.
+//
+// It is machine-owned, NOT adopter-owned: `harness relock` re-baselines the
+// files an adopter authors, and provenance is not one of them. An adopter who
+// hand-edits this file gets a refusal naming it, which is the correct outcome —
+// the alternative is a lane that will re-lock a forged origin without comment.
+//
+// ABSENT MEANS UNRECORDED, never `local`. Every receipt minted before this
+// existed has no provenance, and inventing one for them would be the precise
+// falsehood the field was added to prevent.
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * The package whose bytes a lane is made of. Named here because four writers
+ * record it — `prooflane init`, `prooflane upgrade`, the stamp and
+ * `upgrade --harness` — and a provenance record naming the wrong package is
+ * exactly the falsehood this file exists to prevent.
+ */
+export const HARNESS_PKG_NAME = "prooflane-harness";
+
+/** Project-relative path of the provenance record. */
+export const SOURCE_PATH = "qa/harness-source.json";
+
+export const SOURCE_SCHEMA = "prooflane-harness-source/1";
+
+/**
+ * How the bytes arrived. The enum is ADR-0008's and gains no fourth value here:
+ * an unknown origin is an ABSENT record, not a new word.
+ *
+ *   registry  a package manager placed them (resolved from node_modules)
+ *   local     copied from a path on this machine — a checkout, a workspace
+ *   git       cloned from a repository
+ */
+export const SOURCE_KINDS = Object.freeze(["local", "registry", "git"]);
+
+/**
+ * Read the record, or null when there is none or it is unusable.
+ *
+ * Unparseable reads as ABSENT rather than throwing: a malformed provenance file
+ * must not stop a lane from running, because provenance is not a check. The
+ * integrity gate is what notices the file changed; this reader's job is only to
+ * answer "what does it say", and "nothing usable" is a valid answer.
+ *
+ * @param {string} root project root
+ * @returns {{name: string, version: string, source: string|null}|null}
+ */
+export function readHarnessSource(root) {
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(path.join(root, ...SOURCE_PATH.split("/")), "utf8"));
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const name = typeof parsed.name === "string" && parsed.name ? parsed.name : null;
+  const version = typeof parsed.version === "string" && parsed.version ? parsed.version : null;
+  if (!name || !version) return null;
+  const source = SOURCE_KINDS.includes(parsed.source) ? parsed.source : null;
+  return { name, version, source };
+}
+
+/**
+ * Write the record. Deterministic by construction — no timestamp, no host, no
+ * user. A field that changes on every run would make the region's digest move
+ * for no reason and turn `harnessIntegrity` into noise; and the question this
+ * answers ("which artifact, from where") has no time in it.
+ *
+ * @param {string} root project root
+ * @param {{name: string, version: string, source?: string|null}} rec
+ * @returns {{name: string, version: string, source: string|null}}
+ */
+export function writeHarnessSource(root, { name, version, source = null }) {
+  if (typeof name !== "string" || !name) throw new Error("writeHarnessSource: a package name is required");
+  if (typeof version !== "string" || !version) throw new Error("writeHarnessSource: a version is required");
+  const kind = SOURCE_KINDS.includes(source) ? source : null;
+  const body = { schema: SOURCE_SCHEMA, name, version, source: kind };
+  const abs = path.join(root, ...SOURCE_PATH.split("/"));
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, `${JSON.stringify(body, null, 2)}\n`);
+  return { name, version, source: kind };
+}
+
+/**
+ * What a package manager's own record says about where a dependency came from,
+ * for the one project that has the answer: the adopter's lockfile.
+ *
+ * DERIVED, NEVER ASSUMED. The tempting shortcut is "it is in node_modules, so
+ * it came from the registry" — and that is false for the common local-tarball
+ * install, which is exactly how this repo's own Stage 1 gate installs the
+ * harness. A wrong provenance is worse than none: it tells a checker to fetch
+ * an artifact that was never published and to conclude something from failing.
+ * So the answer comes from `resolved` in the lockfile, and anything it does not
+ * cover reads as null — unrecorded.
+ *
+ * @param {string} root project root
+ * @param {string} pkgName
+ * @returns {string|null} one of SOURCE_KINDS, or null when unknowable
+ */
+export function resolvedSourceKind(root, pkgName) {
+  let lock;
+  try {
+    lock = JSON.parse(fs.readFileSync(path.join(root, "package-lock.json"), "utf8"));
+  } catch {
+    return null;
+  }
+  const entry = lock?.packages?.[`node_modules/${pkgName}`] ?? lock?.dependencies?.[pkgName];
+  const resolved = typeof entry?.resolved === "string" ? entry.resolved : null;
+  if (!resolved) return null;
+  if (/^https?:\/\//.test(resolved)) return "registry";
+  if (/^file:/.test(resolved)) return "local";
+  if (/^git(\+|:)/.test(resolved)) return "git";
+  return null;
+}