@nextcommerce/campaigns-os 1.41.2 → 1.43.2

package/src/finding-cause.mjs

@@ -1,3 +1,4 @@
+import { campaignIdentitiesMatch } from "./spec-source-identity.mjs";
 // Per-finding cause class — "did the change under test cause this?"
 //
 // A run that surfaces eleven findings, none of them caused by the change being
@@ -340,12 +341,13 @@ import { readRunRecordsForTarget } from "./run-record.mjs";
  * against a non-adjacent one and report findings introduced in between as
  * pre-existing.
  */
-export function findPriorRunRecord({ baseDir, mapId = null, currentRunId = null } = {}) {
+export function findPriorRunRecord({ baseDir, mapId = null, localSpecId = null, currentRunId = null } = {}) {
   if (!text(baseDir)) return null;
   for (const entry of readRunRecordsForTarget(baseDir)) {
     const record = entry?.record;
     if (!record || typeof record !== "object" || Array.isArray(record)) continue;
     if (currentRunId && record.run_id === currentRunId) continue;
+    if (localSpecId && !campaignIdentitiesMatch(record.identity, { local_spec_id: localSpecId })) continue;
     if (text(mapId) && text(record.identity?.map_id) !== text(mapId)) continue;
     return record;
   }
@@ -376,7 +378,9 @@ function readPriorVerdictFile(path) {
 // verdicts are filed and matched under the names the record itself stores.
 function recordIdentityForDiscovery(record) {
   return {
-    spec: { map_id: text(record?.identity?.map_id) || null },
+    // This is a read-side comparison, not an artifact writer. Preserve even an
+    // invalid local marker so discovery rejects it instead of using its Map ID.
+    spec: { map_id: text(record?.identity?.map_id) || null, local_spec_id: record?.identity?.local_spec_id ?? null },
     campaign: { public_route_slug: text(record?.identity?.campaign_slug) || null },
   };
 }
@@ -444,8 +448,8 @@ function locateExternalPriorVerdict({ targetRepo, record, ref }) {
  * The single-record boundary is unchanged: this still reads the final attempt
  * of exactly one earlier run, never a merged view across runs.
  */
-export function loadPriorQaVerdict({ baseDir, targetRepo = null, mapId = null, currentRunId = null } = {}) {
-  const record = findPriorRunRecord({ baseDir, mapId, currentRunId });
+export function loadPriorQaVerdict({ baseDir, targetRepo = null, mapId = null, localSpecId = null, currentRunId = null } = {}) {
+  const record = findPriorRunRecord({ baseDir, mapId, localSpecId, currentRunId });
   if (!record) return { verdict: null, record: null, path: null, reason: "no_prior_run" };
   const ref = (Array.isArray(record.artifacts) ? record.artifacts : []).findLast((artifact) => artifact?.kind === "qa_verdict");
   const refPath = text(ref?.path);
@@ -468,8 +472,8 @@ export function loadPriorQaVerdict({ baseDir, targetRepo = null, mapId = null, c
  * carries these, so doctor cause labels work against existing history with no
  * upgrade window. Returns `{ prior, record, reason }`.
  */
-function loadPriorDoctorFindings({ baseDir, mapId = null, currentRunId = null } = {}) {
-  const record = findPriorRunRecord({ baseDir, mapId, currentRunId });
+function loadPriorDoctorFindings({ baseDir, mapId = null, localSpecId = null, currentRunId = null } = {}) {
+  const record = findPriorRunRecord({ baseDir, mapId, localSpecId, currentRunId });
   if (!record) return { prior: null, record: null, reason: "no_prior_run" };
   const prior = priorSetFromRunRecordDoctor(record);
   if (!prior) return { prior: null, record, reason: "prior_run_without_doctor_observations" };
@@ -492,9 +496,9 @@ function loadPriorDoctorFindings({ baseDir, mapId = null, currentRunId = null }
  * raw map id) have no Run Record home, so they get `unknown` / `no_prior_run`
  * throughout — which is the truth, not a silence.
  */
-export function annotateQaAssertionCauses(assertions, { baseDir = null, targetRepo = null, mapId = null, currentRunId = null, isFinding } = {}) {
+export function annotateQaAssertionCauses(assertions, { baseDir = null, targetRepo = null, mapId = null, localSpecId = null, currentRunId = null, isFinding } = {}) {
   const lookup = baseDir
-    ? loadPriorQaVerdict({ baseDir, targetRepo, mapId, currentRunId })
+    ? loadPriorQaVerdict({ baseDir, targetRepo, mapId, localSpecId, currentRunId })
     : { verdict: null, record: null, path: null, reason: "no_prior_run" };
   const prior = lookup.verdict ? priorSetFromVerdict(lookup.verdict, { isFinding }) : null;
   const noPriorReason = lookup.reason || "no_prior_run";
@@ -528,9 +532,9 @@ const CAUSE_SUMMARY_SCHEMA = "campaigns-os-finding-cause/v0";
  * The doctor twin. `errors` and `warnings` are the doctor output's own arrays;
  * both are stamped in place. Returns the same summary shape.
  */
-export function annotateDoctorIssueCauses({ errors = [], warnings = [], baseDir = null, mapId = null, currentRunId = null } = {}) {
+export function annotateDoctorIssueCauses({ errors = [], warnings = [], baseDir = null, mapId = null, localSpecId = null, currentRunId = null } = {}) {
   const lookup = baseDir
-    ? loadPriorDoctorFindings({ baseDir, mapId, currentRunId })
+    ? loadPriorDoctorFindings({ baseDir, mapId, localSpecId, currentRunId })
     : { prior: null, record: null, reason: "no_prior_run" };
   const noPriorReason = lookup.reason || "no_prior_run";
   const findings = [];

package/src/install-invocation.mjs

@@ -0,0 +1,29 @@
+// How this install spells the commands it prints. ROOT resolves `..` from this
+// file, so the module must stay directly under src/ to name the package root.
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { invocationPrefixFor } from "./install-mode.mjs";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+// Every command this CLI PRODUCES for an operator or agent to copy is spelled
+// once, here, for the install it runs from (see install-mode.mjs): bare
+// `campaigns-os` from a checkout, `npx --no-install campaigns-os` from a
+// campaign folder that pins the toolkit, `npx --yes <spec>` from an npx cache.
+// Result payloads are never rewritten after the fact — a path, a quoted
+// argument or a data value that happens to contain the words is left exactly
+// as it is.
+function cmd(verb, rest = "") {
+  const prefix = invocationPrefixFor(ROOT);
+  return `${prefix} ${verb}${rest ? ` ${rest}` : ""}`;
+}
+
+// A registry command (gate actions, checkpoint remediations) is stored in its
+// canonical bare form so internal bookkeeping can match on it; this spells
+// it for the current install at the moment it is emitted.
+function asInvocation(command) {
+  if (typeof command !== "string" || !command.startsWith("campaigns-os ")) return command;
+  return `${invocationPrefixFor(ROOT)} ${command.slice("campaigns-os ".length)}`;
+}
+
+export { ROOT, cmd, asInvocation };

package/src/invocation.mjs

@@ -0,0 +1,179 @@
+// Invocation policy: which cross-cutting steps run around a command, and in
+// what order. One owner for rules that used to be restated at each step — the
+// pre-dispatch bypasses, the stale-session sweep and its root, the ambient
+// run-session read, the lifecycle wrapper, the journal exemptions, the
+// commands that implement --dry-run, and the QA auto-end trigger.
+//
+// The declaration below is data: a class, a sweep root kind and a few flags
+// per command, and per subcommand only where the subcommand differs from its
+// command. It describes kernel behaviour and is never a permission
+// interpreter: contracts/effects.v1.json is bound to it by a test, never read
+// here. The steps themselves (the sweep, the ambient read, the journal append,
+// the auto-end, every handler) stay in cli.mjs and are handed to
+// runInvocation() as functions; this module decides only whether and when each
+// runs. It imports nothing from cli.mjs.
+
+import { runWithRefusalScope, withCommandLifecycle } from "./lifecycle.mjs";
+
+// Frozen all the way down, so a caller handed a subcommand list cannot edit it.
+const frozen = (value) => { if (value && typeof value === "object") Object.values(value).forEach(frozen); return Object.freeze(value); };
+
+// The steps each pre-dispatch class runs. `auth` and `inline` commands run
+// their handler in place: no sweep, no ambient read, no wrapper, no journal.
+// `inspection` still resolves the ambient session and is wrapped, but never
+// sweeps or journals. `projection` (`readback`) is wrapped only: its --packet
+// is an override naming the Build Packet to project, not a session locator.
+// Read as one, the named file was loaded whole past readback's own size bound,
+// and a valid override exited 1 whenever some active session was bound to a
+// different packet; neither belongs to a command declared read-only.
+const CLASS_STEPS = frozen({
+  auth: [], inline: [],
+  inspection: ["wrapper", "ambient"],
+  projection: ["wrapper"],
+  standard: ["wrapper", "ambient", "sweep", "journal"],
+});
+
+// Every top-level command, in the order did-you-mean breaks ties. Fields:
+// `class` (default "standard"); `sweepRoot` ("target": the --target directory,
+// "session": the run-session root; default none); `dryRun` (the command
+// implements --dry-run); `journalExempt`; `journalExemptWhen` (exempt when the
+// `given` flag is set and the `unlessBare` flag is not bare: an inspection must
+// not append to a delivered campaign's active run);
+// `subcommands` (the only subcommand names that resolve; others inherit the
+// command's entry and are refused by the handler).
+//
+// `dryRun` marks only the commands that IMPLEMENT the flag. It reaches every
+// handler through a permissive parseArgs, and an exemption scoped to the flag
+// alone once fired on commands that ignore it: `qa run --dry-run` placed orders
+// while writing no journal entry, and carried the flag into its own auto-end,
+// which assembled no Run Record and left the session open. A command without
+// `dryRun` given --dry-run journals if it otherwise would, and is not refused.
+const COMMANDS = frozen({
+  help: { journalExempt: true },
+  login: { class: "auth" },
+  logout: { class: "auth" },
+  demo: { class: "inline" },
+  tooling: { subcommands: ["diagnose", "setup", "status"] },
+  sdk: { subcommands: ["storage-check"] },
+  readback: { class: "projection" },
+  start: { sweepRoot: "target" },
+  "prepare-build": { sweepRoot: "target" },
+  build: { sweepRoot: "target" },
+  doctor: { journalExemptWhen: { given: "packet", unlessBare: "write" } },
+  bundle: { subcommands: ["check"] },
+  standardize: {},
+  theme: { subcommands: ["generate", "inspect", "waive"] },
+  checkpoint: { subcommands: ["waive"] },
+  polish: { subcommands: ["capture"] },
+  "validate-assembly-report": {},
+  "install-agent-context": { dryRun: true },
+  "install-skills": { dryRun: true },
+  "page-kit": { subcommands: ["parity", "sync"] },
+  spec: { subcommands: ["derive"] },
+  next: { subcommands: ["build", "deploy", "polish", "qa", "setup"] },
+  qa: { subcommands: ["install-browser", "parity", "policy", "promote", "publish", "resolve", "run", "waive"] },
+  findings: { subcommands: ["add", "export", "harvest", "list"] },
+  "run-record": { dryRun: true },
+  telemetry: { subcommands: ["list", "off", "on", "status"] },
+  run: { subcommands: ["end", "start", "status"] },
+});
+
+// Where a subcommand's policy differs from its command's entry. Matched on the
+// explicit subcommand token only: bare `run` defaults to `status` inside its
+// handler, but is not `run status` here, so it journals.
+const SUBCOMMAND_OVERRIDES = frozen({
+  "tooling diagnose": { class: "inline" },
+  "tooling setup": { class: "inline" },
+  "sdk storage-check": { class: "inspection" },
+  "theme waive": { dryRun: true },
+  "checkpoint waive": { dryRun: true },
+  "page-kit sync": { dryRun: true },
+  "spec derive": { dryRun: true },
+  "qa publish": { dryRun: true },
+  "qa run": { autoEnd: true },
+  "run start": { sweepRoot: "session" },
+  "run end": { sweepRoot: "session", dryRun: true },
+  "run status": { journalExempt: true },
+});
+
+export const commandNames = () => Object.keys(COMMANDS);
+
+export const subcommandNames = (command) => (Object.hasOwn(COMMANDS, command) && COMMANDS[command].subcommands) || frozen([]);
+
+// A run opted out of sessions altogether: no stale sweep, and no intake
+// auto-start (which reads this predicate from here).
+export const optsOutOfRunSession = (args) => args["no-run-session"] === true;
+
+// The policy for one invocation. Two --dry-run predicates are deliberate and
+// differ: on a command implementing the flag, its PRESENCE suppresses the
+// sweep (a valued flag the handler will refuse still does nothing first), while
+// only a bare `--dry-run` exempts the journal (the install commands accept a
+// valued flag as a dry run and still journal it). The sweep writes a Run
+// Record, deletes the session file and (under consent) remits — every effect
+// --dry-run promises not to have — so the stale session stays stale until a
+// real invocation closes it. --no-write suppresses both too: inheriting it
+// into the closeout suppressed the Run Record but still deleted the session
+// file. A refused invocation never journals either; that rule is per outcome,
+// not per argv, and stays with the journal append.
+export function resolveInvocationPolicy(command, args) {
+  const subcommand = subcommandNames(command).includes(args._[1]) ? args._[1] : null;
+  const rule = { class: "standard", ...(Object.hasOwn(COMMANDS, command) && COMMANDS[command]), ...(subcommand && SUBCOMMAND_OVERRIDES[`${command} ${subcommand}`]) };
+  const steps = CLASS_STEPS[rule.class];
+  const noWrite = args["no-write"] === true;
+  const implementsDryRun = rule.dryRun === true;
+  const sweepSuppressed = optsOutOfRunSession(args) || noWrite || (Object.hasOwn(args, "dry-run") && implementsDryRun);
+  const inspection = Boolean(rule.journalExemptWhen && args[rule.journalExemptWhen.given] && args[rule.journalExemptWhen.unlessBare] !== true);
+  return Object.freeze({
+    class: rule.class,
+    wrapper: steps.includes("wrapper"), ambient: steps.includes("ambient"),
+    sweepRoot: steps.includes("sweep") && !sweepSuppressed ? rule.sweepRoot || null : null,
+    journalExempt: !steps.includes("journal") || rule.journalExempt === true || noWrite || (args["dry-run"] === true && implementsDryRun) || inspection,
+    implementsDryRun, autoEnd: rule.autoEnd === true,
+  });
+}
+
+// The sequence main() delegates to. `steps` are cli.mjs mechanisms:
+//   dispatch(command, args, { recorder?, ambient?, sessionHolder? }?)
+//   closeOutStaleRunSessions(rootKind, args) -> the closed-out stale sessions
+//   ambientRunSession(args) -> the active session, or null
+//   lifecycleIdentity(args, ambient) -> { argvShape, runId }
+//   persistLifecycle(args, command, lifecycle, sessionHolder, thrown)
+//   autoEndAfterQa(args, sessionHolder, thrown, implementsDryRun)
+// Order: normalise argv, open the refusal scope, run an unwrapped class in
+// place, else sweep, read the ambient session, and wrap dispatch; on finish
+// (success or error) journal unless exempt, then run the QA auto-end. The
+// sweep precedes the ambient read so a stale session at the root is closed out
+// (findRunSession ignores it) rather than abandoned with no Run Record. The
+// wrapper re-throws unchanged, so the exit code is the command's own; a
+// command that throws is recorded too. Persistence stays opt-in: with no
+// --lifecycle-journal, CAMPAIGNS_OS_LIFECYCLE_LOG or active session nothing is
+// written.
+export async function runInvocation(args, steps) {
+  // `npx … campaigns-os <command>` hands the bin its own name as the first
+  // positional: it is the program name, not a command.
+  if (args._[0] === "campaigns-os") args._.shift();
+  const command = args._[0] || "help";
+  const policy = resolveInvocationPolicy(command, args);
+  // One refusal scope per invocation, so a refusal is visible only to this
+  // invocation's persistence step.
+  return runWithRefusalScope(async () => {
+    if (!policy.wrapper) return steps.dispatch(command, args);
+    const sweptStale = policy.sweepRoot ? await steps.closeOutStaleRunSessions(policy.sweepRoot, args) : [];
+    const ambient = policy.ambient ? steps.ambientRunSession(args) : null;
+    // Per invocation, never module state: an intake that opens or joins a run
+    // session mid-command publishes it here, so this command's own entry is
+    // persisted into it.
+    const sessionHolder = { current: ambient, autoStarted: false, adopted: false, qaResult: null, sweptStale };
+    await withCommandLifecycle(
+      {
+        command,
+        ...steps.lifecycleIdentity(args, ambient),
+        onFinish: async (lifecycle, thrown) => {
+          if (!policy.journalExempt) steps.persistLifecycle(args, command, lifecycle, sessionHolder, thrown);
+          if (policy.autoEnd) await steps.autoEndAfterQa(args, sessionHolder, thrown, policy.implementsDryRun);
+        },
+      },
+      (recorder) => steps.dispatch(command, args, { recorder, ambient, sessionHolder }),
+    );
+  });
+}

package/src/lifecycle.mjs

@@ -78,10 +78,11 @@ export function runWithRefusalScope(fn) {
  * the throw, because the paths that catch a refusal to render it (waiveOrRefuse)
  * hand onFinish no error to inspect. The cost of marking early is that a
  * `refused()` built inside a `try` that discards it would suppress the journal
- * entry for an invocation whose handler did run. No call site does that today
- * (no `requireArg` sits inside a `try`), and none may: if you need to probe
- * whether an argument is present, test for it — do not construct a refusal
- * speculatively.
+ * entry for an invocation whose handler did run. The optional QA progress
+ * probe checks for a packet before its swallowing `try`; closeRunSession runs
+ * its nested run-record attempt in a separate refusal scope. Keep those
+ * boundaries: if you need to probe an argument, test for it rather than
+ * constructing a refusal speculatively.
  */
 export function refused(message) {
   const store = refusalScope.getStore();

package/src/polish-node.mjs

@@ -1,3 +1,4 @@
+import { campaignIdentitiesMatch, localSpecIdentityFields } from "./spec-source-identity.mjs";
 import { createHash } from "node:crypto";
 import { HIDDEN_EAGER_MEDIA_ACTIONS } from "./gate-actions.mjs";
 import { dirname, join, resolve } from "node:path";
@@ -330,8 +331,8 @@ export function createPolishCaptureBinding({ packet, report, plan, packetPath, t
   const slug = captureCampaignSlug(packet, report);
   const packetMapId = nonemptyString(packet?.spec?.map_id);
   const reportMapId = nonemptyString(report?.identity?.map_id);
-  if (!packetMapId || packetMapId !== reportMapId) {
-    throw new Error("polish capture requires matching packet and Assembly Report map identities.");
+  if (!campaignIdentitiesMatch(packet?.spec, report?.identity)) {
+    throw new Error("polish capture requires matching packet and Assembly Report campaign identities.");
   }
   const buildFingerprint = currentBuildFingerprint(report);
   if (!buildFingerprint) throw new Error("polish capture requires a strict current Assembly Report build fingerprint.");
@@ -360,6 +361,7 @@ export function createPolishCaptureBinding({ packet, report, plan, packetPath, t
       resolved_path: resolvedPacketPath,
       resolved_target_repo: resolvedTargetRepo,
       map_id: packetMapId,
+      ...localSpecIdentityFields(packet.spec),
       campaign_slug: slug,
       route_root: nonemptyString(packet?.campaign?.route_root),
       target_repo: nonemptyString(packet?.assembly?.target_repo),
@@ -368,6 +370,7 @@ export function createPolishCaptureBinding({ packet, report, plan, packetPath, t
       run_id: runId,
       identity: {
         map_id: reportMapId,
+        ...localSpecIdentityFields(report.identity),
         public_route_slug: nonemptyString(report?.identity?.public_route_slug),
         spec_hash: nonemptyString(report?.identity?.spec_hash),
       },

package/src/private-template-source.mjs

@@ -83,7 +83,7 @@ function privateTemplateSourcesPath() {
 }
 
 // No caching, recomputed per call — matches certifiedTemplateFamilies()'s
-// existing convention (cli.mjs) so a long-lived process never serves a stale
+// existing convention (src/doctor/checks.mjs) so a long-lived process never serves a stale
 // allowlist after an edit.
 export function loadPrivateTemplateSources() {
   const path = privateTemplateSourcesPath();

package/src/progress-node.mjs

@@ -1,10 +1,12 @@
+import { campaignSpecIdentity, campaignIdentitiesMatch, localSpecIdentityFields } from "./spec-source-identity.mjs";
 // Best-effort producer adapter. Sanitized immutable bytes are durable before delivery.
 import {randomBytes,createHash} from 'node:crypto';
-import {mkdirSync,readFileSync,writeFileSync,renameSync,rmSync,readdirSync,lstatSync} from 'node:fs';
+import {mkdirSync,readFileSync,writeFileSync,renameSync,rmSync,readdirSync} from 'node:fs';
 import {join,resolve,dirname} from 'node:path';
 import {PROGRESS_SCHEMA_VERSION,PROGRESS_STAGES,PROGRESS_STAGE_STATUSES,PROGRESS_CONTINUATIONS,PROGRESS_ACTION_IDS,PROGRESS_GATE_IDS,canonicalProgressJson,progressSnapshotId,verifyProgressSnapshot} from './progress.mjs';
 import {specMaterialHash} from './spec-identity.mjs';
 import {sameFile} from './fs-identity.mjs';
+import {withDirectoryLock} from './directory-lock.mjs';
 import {resolveConsent,CANONICAL_REMIT_SCOPE,normalizeConsentScope,announceDefaultOnTelemetry} from './consent.mjs';
 import {boundedResponseText,isLoopbackHostname} from './remit.mjs';
 export const PROGRESS_OBSERVATION = Symbol('canonical progress observation');
@@ -46,7 +48,7 @@ export function projectProgressObservation({workspace,context,report,doctor,cont
   const aligned=contextBound&&mapId&&localMapId===mapId&&baseline?.map_id===mapId&&baseline?.algorithm==='map-store-v1'&&hash(baseline.hash)&&localHash&&localHash===hash(baseline.local_spec_material_hash);
   const build=hash(doctor?.derived?.build_output_fingerprint?.value);
   const recordedBuild=hash(report?.stages?.assembly?.build_fingerprint);
-  const reportBound=doctor?.derived?.prepare_build_gate?.binding_failure!==true&&contextBound&&mapId&&localMapId===mapId&&report?.identity?.map_id===mapId&&localHash&&localHash===hash(report?.identity?.spec_material_hash);
+  const reportBound=doctor?.derived?.prepare_build_gate?.binding_failure!==true&&contextBound&&campaignIdentitiesMatch(packet?.spec,campaignSpecIdentity(spec))&&campaignIdentitiesMatch(packet?.spec,report?.identity)&&localHash&&localHash===hash(report?.identity?.spec_material_hash);
   const qaSource=hash(report?.stages?.qa?.evidence?.source_build_fingerprint);
   const verdict=qaResult?.verdict;
   const qa=verdict?{
@@ -60,7 +62,7 @@ export function projectProgressObservation({workspace,context,report,doctor,cont
   const preview=typeof packet?.deploy?.preview_url==='string'&&packet.deploy.preview_url?packet.deploy.preview_url:null;
   return {
     schema_version:PROGRESS_SCHEMA_VERSION,package_version:packageVersion,producer:qaResult?'qa':'next',
-    identity:{map_id:mapId,map_revision_hash:contextBound&&baseline?.map_id===mapId?hash(baseline?.hash):(localMapId===mapId?hash(spec?.spec_identity?.spec_hash||spec?.spec_hash):null),map_revision_algorithm:'map-store-v1',saved_revision_alignment:aligned?'aligned':'unconfirmed',local_spec_material_hash:localHash,local_spec_material_algorithm:'campaign-spec-material-v1',build_fingerprint:build,build_fingerprint_algorithm:'sha256-manifest/v1'},
+    identity:{map_id:mapId,...localSpecIdentityFields(packet?.spec),map_revision_hash:mapId?(contextBound&&baseline?.map_id===mapId?hash(baseline?.hash):(localMapId===mapId?hash(spec?.spec_identity?.spec_hash||spec?.spec_hash):null)):null,map_revision_algorithm:'map-store-v1',saved_revision_alignment:aligned?'aligned':'unconfirmed',local_spec_material_hash:localHash,local_spec_material_algorithm:'campaign-spec-material-v1',build_fingerprint:build,build_fingerprint_algorithm:'sha256-manifest/v1'},
     stages:PROGRESS_STAGES.map(stage=>{
       const status=reportBound?accepted(report?.stages?.[stage]?.status,PROGRESS_STAGE_STATUSES):'unknown';
       const source=stage==='assembly'?recordedBuild:stage==='qa'?qaSource:null;
@@ -70,39 +72,9 @@ export function projectProgressObservation({workspace,context,report,doctor,cont
     continuation:{stage,blocked:continuation?.ok!==true||(Array.isArray(continuation?.divergences)&&continuation.divergences.length>0)||stage==='unknown'||gates.some(gate=>['blocked','unknown'].includes(gate.state))||actions.includes('unknown'),divergent:Array.isArray(continuation?.divergences)&&continuation.divergences.length>0,action_ids:actions,gates},qa,
   };
 }
-async function lock(dir,fn,{budgetMs=1500}={}) {
-  const path=join(dir,'.allocation-lock'); const start=Date.now();const token=randomBytes(16).toString('hex');
-  const abandoned=(unownedMtime=null)=>{
-    try {
-      const stat=lstatSync(path);if(!stat.isDirectory()||stat.isSymbolicLink())return false;
-      const owner=read(join(path,'owner.json'));
-      if(Number.isInteger(owner?.pid)&&owner.pid>0&&typeof owner.token==='string') {
-        try {process.kill(owner.pid,0);return false;}catch(error){return error.code==='ESRCH';}
-      }
-      // A killed process can leave the directory before writing its owner.
-      // Give a live allocator ample time to finish that tiny synchronous gap.
-      return Date.now()-(unownedMtime??stat.mtimeMs)>10000;
-    }catch{return false;}
-  };
-  const recover=()=>{
-    if(!abandoned())return;
-    let originalMtime;try{originalMtime=lstatSync(path).mtimeMs;}catch{return;}
-    const claim=join(path,'.recovery');
-    // Only this exclusive claimant can rename the old lock. An interrupted
-    // recovery claim fails closed for explicit offline recovery; recursively
-    // stealing recovery claims would reintroduce a check/rename race.
-    try {mkdirSync(claim);atomic(join(claim,'owner.json'),{pid:process.pid,token});}catch{return;}
-    let moved=false;
-    try {
-      if(!abandoned(originalMtime))return;
-      const tomb=`${path}.abandoned-${token}`;
-      renameSync(path,tomb);moved=true;rmSync(tomb,{recursive:true,force:true});
-    }catch{}finally{if(!moved&&read(join(claim,'owner.json'))?.token===token){try{rmSync(claim,{recursive:true,force:true});}catch{}}}
-  };
-  while (true) {
-    try {mkdirSync(path);atomic(join(path,'owner.json'),{pid:process.pid,token});break;}catch(error){if(error.code!=='EEXIST'||Date.now()-start>=budgetMs)throw new Error('progress.lock_unavailable');recover();await new Promise(resolve=>setTimeout(resolve,20));}
-  }
-  try{return await fn();}finally{if(read(join(path,'owner.json'))?.token===token)rmSync(path,{recursive:true,force:true});}
+function lock(dir,fn,{budgetMs=1500}={}) {
+  const lockPath=join(dir,'.allocation-lock');
+  return withDirectoryLock(lockPath,fn,{budgetMs,unavailable:()=>Object.assign(new Error('progress.lock_unavailable'),{lockPath})});
 }
 export async function persistProgressObservation(observation,{dir,now=()=>new Date(),historyLimit=32}={}) {
   mkdirSync(dir,{recursive:true,mode:0o700});
@@ -170,7 +142,7 @@ export async function observeProgress(args,continuation,{qaResult=null,packageVe
     if(remit.state==='failed')warn('[campaigns-os] Progress delivery pending; the local observation is retained. Lifecycle result is unchanged.');
     return {...remit,snapshot_id:snapshot.snapshot_id,reused};
   } catch(error) {
-    if(error?.message==='progress.lock_unavailable')warn('[campaigns-os] Progress allocation lock occupied; wait for the current writer. For abandoned or interrupted recovery, stop target writers and follow the offline lock recovery in docs/progress-snapshots.md. Lifecycle result is unchanged.');
+    if(error?.message==='progress.lock_unavailable')warn(`[campaigns-os] Progress allocation lock occupied${error.lockPath?` at ${error.lockPath}`:''}; wait for the current writer. If it stays occupied (an abandoned, ownerless or interrupted lock), stop all campaigns-os writers for this target, then remove that lock directory (docs/progress-snapshots.md). Lifecycle result is unchanged.`);
     else warn('[campaigns-os] Progress observation unavailable; lifecycle result is unchanged.');
     return {state:'failed',reason:'capture_unavailable'};
   }

package/src/progress.mjs

@@ -22,7 +22,7 @@ const str = pattern => ({type:'string', pattern});
 const hash = {type:['string','null'], pattern:'^sha256:[0-9a-f]{64}$'};
 const opaque = {type:['string','null'], pattern:'^[A-Za-z0-9_-]{1,64}$'};
 const enumeration = values => ({enum:values});
-const object = properties => ({type:'object', additionalProperties:false, required:Object.keys(properties), properties});
+const object = (properties, optional=[]) => ({type:'object', additionalProperties:false, required:Object.keys(properties).filter(key=>!optional.includes(key)), properties});
 export const PROGRESS_SNAPSHOT_SCHEMA = {
   $schema:'https://json-schema.org/draft/2020-12/schema',
   $id:'https://nextcommerce.com/schemas/campaigns-os-progress-snapshot.v0.schema.json',
@@ -32,10 +32,10 @@ export const PROGRESS_SNAPSHOT_SCHEMA = {
     stream_id:str('^progress_[0-9a-f]{32}$'), sequence:{type:'integer',minimum:1,maximum:2147483647},
     previous_snapshot_id:hash, observed_at:str('^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$'),
     package_version:str('^\\d{1,6}\\.\\d{1,6}\\.\\d{1,6}$'), producer:enumeration(['next','qa']),
-    identity:object({map_id:opaque,map_revision_hash:hash,map_revision_algorithm:{const:'map-store-v1'},
+    identity:object({map_id:opaque,local_spec_id:str('^[A-Za-z0-9_-]{1,64}$'),map_revision_hash:hash,map_revision_algorithm:{const:'map-store-v1'},
       saved_revision_alignment:enumeration(['aligned','unconfirmed']),local_spec_material_hash:hash,
       local_spec_material_algorithm:{const:'campaign-spec-material-v1'},build_fingerprint:hash,
-      build_fingerprint_algorithm:{const:'sha256-manifest/v1'}}),
+      build_fingerprint_algorithm:{const:'sha256-manifest/v1'}},['local_spec_id']),
     stages:{type:'array',minItems:6,maxItems:6,items:object({stage:enumeration(PROGRESS_STAGES),status:enumeration(PROGRESS_STAGE_STATUSES),
       build_binding:enumeration(['matching','unconfirmed']),source_build_fingerprint:hash})},
     preview:object({present:{type:'boolean'},url_hash:hash}),
@@ -46,6 +46,7 @@ export const PROGRESS_SNAPSHOT_SCHEMA = {
       binding:enumeration(['matching','unconfirmed']),publish_state:enumeration(['skipped','ok','failed','unknown'])})]},
   }),
 };
+
 export function canonicalProgressJson(value) {
   if (Array.isArray(value)) return `[${value.map(canonicalProgressJson).join(',')}]`;
   if (value && typeof value === 'object') return `{${Object.keys(value).sort().map(key=>`${JSON.stringify(key)}:${canonicalProgressJson(value[key])}`).join(',')}}`;
@@ -92,6 +93,7 @@ export function validateProgressSnapshot(value) {
   }
   if (!check(value,PROGRESS_SNAPSHOT_SCHEMA)) errors.push('progress.invalid_shape');
   if (!errors.length && (new Set(value.stages.map(stage=>stage.stage)).size!==6 || value.stages.some((stage,index)=>stage.stage!==PROGRESS_STAGES[index]))) errors.push('progress.invalid_stages');
+  if (!errors.length && value.identity.local_spec_id && (value.identity.map_id || value.identity.map_revision_hash || value.identity.saved_revision_alignment !== 'unconfirmed')) errors.push('progress.invalid_local_identity');
   if (!errors.length && value.identity.saved_revision_alignment==='aligned' && (!value.identity.map_id||!value.identity.map_revision_hash||!value.identity.local_spec_material_hash)) errors.push('progress.invalid_alignment');
   if (!errors.length && value.continuation.gates.some(gate=>gate.id==='unknown'&&gate.state!=='unknown')) errors.push('progress.unsupported_authority');
   if (!errors.length && value.sequence===1 && value.previous_snapshot_id!==null) errors.push('progress.invalid_chain');

package/src/proof-policy.mjs

@@ -4,7 +4,7 @@
 //
 // `qa.proof_policy.order_path_depth` is seeded by prepare-build/start and
 // mirrored into `report.proof_policy` at the same moment. The two are compared
-// by `assessPurchaseProofCoverage` (cli.mjs): a disagreement is `unknown`,
+// by `assessPurchaseProofCoverage` (src/doctor/next-step.mjs): a disagreement is `unknown`,
 // never one side's value. Doctor, `next` and the coverage reason all describe
 // that state through the single action below, so the command an operator is
 // told to run is spelled once. A leaf: gate-actions only.

package/src/qa-analytics-correctness.mjs

@@ -228,6 +228,9 @@ export function assessReceiptPurchase(receiptAnalytics = {}, options = {}) {
     receipts.push({
       plan_id: planId,
       receipt_url: redactUrlQuery(attempt.receiptUrl),
+      // The settled document location the receipt capture was read from
+      // (#500); null when it was not recorded.
+      receipt_document_url: redactUrlQuery(attempt.receiptDocumentUrl) || null,
       measured,
       scope: measured ? scope : null,
       purchase_fired: measured && !!effective.fired,