@nextcommerce/campaigns-os 1.37.3 → 1.43.1

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/progress-node.mjs

@@ -1,3 +1,4 @@
+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';
@@ -46,7 +47,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 +61,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;

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/qa-node.mjs

@@ -1,3 +1,4 @@
+import { campaignSpecIdentity, resolveCampaignIdentity, campaignIdentitiesMatch } from "./spec-source-identity.mjs";
 import { expectedBinding, createBindingScriptLoader, observeBinding, bindingAssertion } from './qa-binding-evidence.mjs';
 import { shellToken } from "./shell-token.mjs";
 import { requiredActionText } from "./gate-actions.mjs";
@@ -13,7 +14,7 @@ import {
 import { singleLineFragment } from "./text-safety.mjs";
 import { absentOrMalformed } from "./fs-identity.mjs";
 import { DEFAULT_PROXY_BASE, fetchSpecByMapId } from "./spec-fetch.mjs";
-import { specMaterialHash } from "./spec-identity.mjs";
+import { specMaterialHash, specHashesMatch } from "./spec-identity.mjs";
 import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
 import { PLAYWRIGHT_INSTALL_HINT } from "./browser-launch.mjs";
 import { dirname, join, relative, resolve, isAbsolute } from "node:path";
@@ -60,6 +61,10 @@ import {
 import { resolveConsent } from "./consent.mjs";
 import { markDoctorSidecarStale } from "./doctor-sidecar.mjs";
 import { commitAssemblyReport } from "./stage-ledger.mjs";
+// Tags a refusal raised before a qa handler runs, so the CLI's lifecycle
+// persist step suppresses the journal append from one place. lifecycle.mjs
+// imports nothing from this repository, so this cannot be circular.
+import { refused, refusing } from "./lifecycle.mjs";
 import { campaignSidecarPaths, explicitReportPath, resolveCampaignWorkspace, targetRepoFor } from "./campaign-workspace.mjs";
 import { loadParityFixture } from "./qa-parity-fixture.mjs";
 import { assessParityCapture, resolveParityScenario, runParityCapture } from "./qa-parity-capture.mjs";
@@ -99,7 +104,7 @@ Usage:
   campaigns-os qa policy set --packet <campaign-runtime.build.json> [--allowed-domains-confirmed true|false] [--deploy-target <target>] [--preview-url <url>] [--production-url <url>] [--order-path-depth <off|common|full>] [--json]
   campaigns-os qa waive --packet <campaign-runtime.build.json> --assertion analytics-correctness:purchase-fires --reason "<why>" [--waived-by <who>] [--report <assembly-report.json>] [--json]
   campaigns-os qa promote --packet <campaign-runtime.build.json> --verdict <full-verdict.json> [--json]   # project one explicit qa-output verdict to the committed .campaign-runtime/qa-verdict.json sidecar
-  campaigns-os qa publish --packet <campaign-runtime.build.json> [--verdict <full-verdict.json>] [--republish] [--proxy-base <url>] [--json]   # post an already-stored verdict to the QA portal; no re-run, no orders
+  campaigns-os qa publish --packet <campaign-runtime.build.json> [--verdict <full-verdict.json>] [--republish] [--proxy-base <url>] [--dry-run] [--json]   # post an already-stored verdict to the QA portal; no re-run, no orders
   campaigns-os qa resolve <map-id> --spec <campaign-spec.json> [--base-url <url>]
   campaigns-os qa run <map-id> --spec <campaign-spec.json> --base-url <url>
   campaigns-os qa run --site <page-kit-target-repo> --base-url <url> --family <family> [--slug <slug>] [--browser]   # L7: QA a built _site/ with no packet/spec
@@ -146,6 +151,10 @@ Options:
                                   per the Run Record (already_published), an untrusted one, or one for another
                                   campaign. Exit 2 on a refusal, 1 on a failed post, 0 when published.
   --republish                     qa publish: post a verdict its Run Record already records as published.
+  --dry-run                       qa publish: run every refusal check and print what would be posted (endpoint,
+                                  verdict run id, payload bytes) without the POST. Nothing is sent and the Run
+                                  Record is not stamped; a refusal still exits 2, a clean dry run exits 0
+                                  (--json: dry_run, would_publish, would_post).
   --no-remit                     When an ambient run session is active, write the local Run Record but skip Run Telemetry remit.
   --auth-cookie <cookie>          Cookie header for protected previews.
   --browser                       Run Playwright-rendered browser checks after static Node checks.
@@ -250,7 +259,7 @@ export async function runQaCli(args, { ambient = null } = {}) {
     return result;
   }
   if (subcommand === "policy") {
-    if (args._[2] !== "set") throw new Error(`Unknown qa policy command. Use: ${cmd("qa")} policy set --packet <campaign-runtime.build.json>`);
+    if (args._[2] !== "set") throw refused(`Unknown qa policy command. Use: ${cmd("qa")} policy set --packet <campaign-runtime.build.json>`);
     const result = updateQaPolicy(args);
     output(result, args);
     return result;
@@ -281,7 +290,7 @@ export async function runQaCli(args, { ambient = null } = {}) {
     process.exitCode = result.ok ? 0 : 1;
     return result;
   }
-  throw new Error(`Unknown qa command: ${subcommand}`);
+  throw refused(`Unknown qa command: ${subcommand}`);
 }
 
 // The package-owned browser install, runnable from any install mode. It is
@@ -337,8 +346,19 @@ async function resolveQaInputs(args, {
   readJsonFile = readJson,
   loadCampaignEntry = loadPageKitCampaignEntry,
 } = {}) {
+  // Selector flags without a non-empty value are argv-only refusals for both
+  // qa run and qa resolve. Check them before checkpoint preflight or site reads.
+  for (const flag of ["packet", "site", "built", "map-id"]) {
+    if (Object.hasOwn(args, flag) && !stringArg(args[flag])) {
+      throw refused(`Missing value for --${flag}`);
+    }
+  }
   if (args.packet && args.spec) {
-    throw new Error("Packet QA does not accept --spec; it always uses packet.spec.local_path.");
+    throw refused("Packet QA does not accept --spec; it always uses packet.spec.local_path.");
+  }
+  // No non-empty campaign selector in argv is also decided before any read.
+  if (![args.packet, args.site, args.built, args._[2], args["map-id"]].some(stringArg)) {
+    throw refused("QA requires a Map ID. Provide --packet or positional <map-id>.");
   }
   // Non-packet mode (learnings L7): QA a `campaign-build`'d page-kit campaign
   // that has only a built _site/ and a served URL — no Build Packet, no Map ID,
@@ -363,7 +383,13 @@ async function resolveQaInputs(args, {
   const mapId = stringArg(args["map-id"])
     || stringArg(args._[2])
     || stringArg(packet?.spec?.map_id);
-  if (!mapId) throw new Error("QA requires a Map ID. Provide --packet or positional <map-id>.");
+  // A named packet has been read by checkpoint preflight. Its missing or
+  // conflicting identity is a handler failure, not an argv-only refusal.
+  const localSpecId = packet?.spec?.local_spec_id ?? null;
+  if (!mapId && !localSpecId) throw new Error("QA requires a Map ID or a local-spec packet. The named Build Packet has no campaign identity.");
+  if (packet && localSpecId != null && (!resolveCampaignIdentity(packet.spec) || mapId)) {
+    throw new Error("Local-spec packet QA cannot use a Map ID override or an ambiguous identity.");
+  }
 
   const proxyBase = stringArg(args["proxy-base"]) || DEFAULT_PROXY_BASE;
   const inputBaseUrl = normalizeBaseUrl(stringArg(args["base-url"]) || packet?.deploy?.preview_url || packet?.deploy?.production_url || null);
@@ -388,6 +414,13 @@ async function resolveQaInputs(args, {
     specSource = `${proxyBase.replace(/\/+$/, "")}/api/spec/${encodeURIComponent(mapId)}`;
   }
 
+  if (!packet && rawSpec?.spec_identity?.local_spec_id != null) {
+    throw new Error("Local-spec QA requires --packet; a local spec cannot be published under a Map ID.");
+  }
+  if (packet && (localSpecId != null || rawSpec?.spec_identity?.local_spec_id != null)
+    && !campaignIdentitiesMatch(packet.spec, campaignSpecIdentity(rawSpec))) {
+    throw new Error("Packet local_spec_id does not match the local CampaignSpec identity. Re-run prepare-build from the intended spec.");
+  }
   const normalized = normalizeSpec(rawSpec);
   const publicRouteSlug = resolvePublicRouteSlug({ packet, spec: normalized, rawSpec });
   const baseUrl = normalizeQaBaseUrl(inputBaseUrl, publicRouteSlug);
@@ -433,6 +466,7 @@ async function resolveQaInputs(args, {
     packetPath,
     packet,
     mapId,
+    localSpecId,
     publicRouteSlug,
     proxyBase,
     baseUrl,
@@ -462,6 +496,10 @@ function resolvePacketCheckpointPreflight(args, {
 } = {}) {
   const packetPath = resolve(String(args.packet));
   const packet = readJsonFile(packetPath);
+  if (packet?.spec?.local_spec_id != null && (!resolveCampaignIdentity(packet.spec)
+    || stringArg(args["map-id"]) || stringArg(args._?.[2]))) {
+    throw new Error("Local-spec packet QA cannot use a Map ID override or an ambiguous identity.");
+  }
   const specPath = stringArg(args.spec)
     ? resolve(String(args.spec))
     : stringArg(packet?.spec?.local_path)
@@ -497,6 +535,10 @@ function resolvePacketCheckpointPreflight(args, {
       report = null;
     }
   }
+  if (packet?.spec?.local_spec_id != null && (!reportMatchesPacketIdentity(report, packet)
+    || (specStatus === "ok" && !specHashesMatch(report.identity?.spec_material_hash, computeSpecHash(rawSpec))))) {
+    throw new Error("Local-spec QA requires the matching Assembly Report and current spec material hash. Re-run prepare-build after a material revision; do not reuse foreign or stale proof.");
+  }
   const checkpointGates = [
     evaluatePageKitStoreProfile({
       specCampaign: rawSpec?.campaign || null,
@@ -532,12 +574,9 @@ function resolvePacketCheckpointPreflight(args, {
 
 function reportMatchesPacketIdentity(report, packet) {
   if (!isPlainObject(report) || !isPlainObject(report.identity)) return false;
-  const packetMapId = stringArg(packet?.spec?.map_id);
-  const reportMapId = stringArg(report.identity.map_id);
   const packetSlug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
   const reportSlug = normalizePublicRouteSlug(report.identity.public_route_slug);
-  return !!packetMapId
-    && packetMapId === reportMapId
+  return campaignIdentitiesMatch(packet?.spec, report.identity)
     && !!packetSlug
     && packetSlug === reportSlug;
 }
@@ -624,7 +663,8 @@ function resolvedFromBlockedCheckpointPreflight(preflight, args) {
     brandContractStatus: "not_evaluated",
     packetPath: preflight.packetPath,
     packet: preflight.packet,
-    mapId: stringArg(preflight.packet?.spec?.map_id) || "unknown-map",
+    mapId: stringArg(preflight.packet?.spec?.map_id) || (preflight.packet?.spec?.local_spec_id ? null : "unknown-map"),
+    localSpecId: preflight.packet?.spec?.local_spec_id ?? null,
     publicRouteSlug,
     proxyBase: stringArg(args["proxy-base"]) || DEFAULT_PROXY_BASE,
     baseUrl: inputBaseUrl,
@@ -650,18 +690,18 @@ function resolvedFromBlockedCheckpointPreflight(preflight, args) {
 // yields "not_applicable" rather than blocking, so browser QA still runs the
 // residue/placeholder/demo gates. Test orders are not attempted (no policy).
 export function resolveQaInputsFromSite(args) {
-  const targetRepo = resolve(String(args.site || args.built));
-  const scope = resolveBuiltSiteScope(targetRepo, { slug: stringArg(args.slug) });
-  if (!scope.ok) {
-    throw new Error(scope.error || `Could not resolve a built campaign from ${targetRepo}.`);
-  }
   const baseUrl = normalizeBaseUrl(stringArg(args["base-url"]));
   if (!baseUrl) {
-    throw new Error("Non-packet site QA requires --base-url <served-campaign-root> so built pages have a fetchable URL.");
+    throw refused("Non-packet site QA requires --base-url <served-campaign-root> so built pages have a fetchable URL.");
   }
   const templateFamily = stringArg(args.family);
   if (!templateFamily) {
-    throw new Error("Non-packet site QA requires --family <template-family> so residue, placeholder, and demo-asset gates can load the family brand contract.");
+    throw refused("Non-packet site QA requires --family <template-family> so residue, placeholder, and demo-asset gates can load the family brand contract.");
+  }
+  const targetRepo = resolve(String(args.site || args.built));
+  const scope = resolveBuiltSiteScope(targetRepo, { slug: stringArg(args.slug) });
+  if (!scope.ok) {
+    throw new Error(scope.error || `Could not resolve a built campaign from ${targetRepo}.`);
   }
   const brandContract = loadBrandContract(templateFamily);
   if (brandContract.status !== "loaded" || !brandContract.contract) {
@@ -1490,6 +1530,7 @@ function resolvePayload(resolved, { routeProbe = null } = {}) {
     ok: status !== "blocked" && status !== "routes_unresolved",
     status,
     map_id: resolved.mapId,
+    ...(resolved.localSpecId ? { local_spec_id: resolved.localSpecId } : {}),
     ...(resolved.packetPath ? { packet_path: resolved.packetPath } : {}),
     ...reportPathField(resolved),
     ...(resolved.proxyBase && resolved.proxyBase !== DEFAULT_PROXY_BASE ? { proxy_base: resolved.proxyBase } : {}),
@@ -1726,7 +1767,7 @@ const REMOVED_QA_POLICY_FLAGS = ["test-orders-allowed", "sandbox-test-card-confi
 
 function updateQaPolicy(args) {
   const packetPath = args.packet ? resolve(args.packet) : null;
-  if (!packetPath) throw new Error("qa policy set requires --packet <campaign-runtime.build.json>.");
+  if (!packetPath) throw refused("qa policy set requires --packet <campaign-runtime.build.json>.");
   const packet = readJson(packetPath);
   packet.campaign ||= {};
   packet.deploy ||= {};
@@ -1735,12 +1776,15 @@ function updateQaPolicy(args) {
   // Test Orders have no permission flag. The two flags that once set one
   // were removed with their packet fields in supported surface 1.28.0; a
   // script still passing them gets told so instead of a silent no-op.
+  // This check and the setOptional* value checks below run after reading only
+  // the packet and before the packet write: refusals, so they journal nothing.
   const removedFlags = REMOVED_QA_POLICY_FLAGS.filter((flag) => flag in args);
   if (removedFlags.length) {
-    throw new Error(`qa policy set: ${removedFlags.map((flag) => `--${flag}`).join(" and ")} ${removedFlags.length > 1 ? "were" : "was"} removed in supported surface 1.28.0 (test orders run from --test-order <mode> alone; there is no permission flag). Drop the flag${removedFlags.length > 1 ? "s" : ""}. Accepted: --allowed-domains-confirmed, --deploy-target, --preview-url, --production-url, --order-path-depth.`);
+    throw refused(`qa policy set: ${removedFlags.map((flag) => `--${flag}`).join(" and ")} ${removedFlags.length > 1 ? "were" : "was"} removed in supported surface 1.28.0 (test orders run from --test-order <mode> alone; there is no permission flag). Drop the flag${removedFlags.length > 1 ? "s" : ""}. Accepted: --allowed-domains-confirmed, --deploy-target, --preview-url, --production-url, --order-path-depth.`);
   }
-  // Validated with the other argv checks, before anything is written.
-  const orderPathDepth = parseOrderPathDepthFlag(args, { command: "qa policy set" });
+  // Validated with the other argv checks, before anything is written: a
+  // refusal at this call site, like the removed-flag check above.
+  const orderPathDepth = refusing(() => parseOrderPathDepthFlag(args, { command: "qa policy set" }));
 
   const changed = [];
   setOptionalBoolean(packet.campaign, "allowed_domains_confirmed", args, "allowed-domains-confirmed", changed);
@@ -1810,21 +1854,24 @@ const WAIVABLE_QA_ASSERTIONS = Object.freeze(["analytics-correctness:purchase-fi
 // report.theme.waiver: { reason, waived_by, waived_at }.
 export function qaWaive(args) {
   const packetPath = args.packet ? resolve(args.packet) : null;
-  if (!packetPath) throw new Error("qa waive requires --packet <campaign-runtime.build.json>.");
+  if (!packetPath) throw refused("qa waive requires --packet <campaign-runtime.build.json>.");
   const packet = readJson(packetPath);
+  // The three flag checks run after reading only argv and the packet, ahead of
+  // the report lookup: refusals, so they journal nothing. The missing report
+  // below is a handler failure and is journaled.
   const assertionId = stringArg(args.assertion);
   if (!assertionId) {
-    throw new Error(`qa waive requires --assertion <id>. Waivable assertions: ${WAIVABLE_QA_ASSERTIONS.join(", ")}.`);
+    throw refused(`qa waive requires --assertion <id>. Waivable assertions: ${WAIVABLE_QA_ASSERTIONS.join(", ")}.`);
   }
   if (!WAIVABLE_QA_ASSERTIONS.includes(assertionId)) {
-    throw new Error(
+    throw refused(
       `qa waive does not accept --assertion "${assertionId}". The waiver lane is scoped to exactly: ${WAIVABLE_QA_ASSERTIONS.join(", ")}. `
       + "Extending the lane to another assertion is a design decision, not a flag.",
     );
   }
   const reason = stringArg(args.reason);
   if (!reason) {
-    throw new Error("qa waive requires --reason \"<why this failing blocker is acceptable for this campaign>\".");
+    throw refused("qa waive requires --reason \"<why this failing blocker is acceptable for this campaign>\".");
   }
   const workspace = resolveCampaignWorkspace(packetPath, {
     packet,
@@ -1998,15 +2045,25 @@ function parityReplayEvidence(bundle) {
   return { order, capture, baselineCapture, orders: Array.isArray(bundle.orders) ? bundle.orders : [order] };
 }
 
+// The up-front half of the `--max-order-creations` check. The validator is
+// SHARED with the order-creation budget, which every browser path builds after
+// a browser has launched and orders may already have been created; a throw from
+// there is a handler failure and must still be journaled, so the refusal tag
+// cannot live inside the validator. It goes here via `refusing()`, at the two
+// entries that check the flag before anything is resolved or launched, where a
+// bad value has cost the operator nothing. Message and exit code are the
+// validator's own.
+const refuseBadOrderCreationLimit = (args) => refusing(() => validatedOrderCreationLimit(args));
+
 async function runParityQa(args) {
   // Checked here as well as on the budget itself: the budget is built after a
   // browser has launched, and a flag the operator typed wrong should cost them
   // nothing. The budget stays the authority — this is fail-fast, not the gate.
-  validatedOrderCreationLimit(args);
+  refuseBadOrderCreationLimit(args);
   const fixturePath = stringArg(args.fixture);
   const scenarioId = stringArg(args.scenario) || stringArg(args._[2]);
-  if (!fixturePath) throw new Error("QA parity requires --fixture <parity-fixture.json>.");
-  if (!scenarioId) throw new Error("QA parity requires --scenario <scenario-id>.");
+  if (!fixturePath) throw refused("QA parity requires --fixture <parity-fixture.json>.");
+  if (!scenarioId) throw refused("QA parity requires --scenario <scenario-id>.");
 
   const fixture = await loadParityFixture(resolve(fixturePath));
   const scenario = resolveParityScenario(fixture, scenarioId);
@@ -2072,7 +2129,7 @@ async function runParityQa(args) {
 async function runQa(args, options = {}) {
   // Fail-fast before anything resolves or launches. The authoritative check
   // lives on the creation budget itself, which every browser path builds.
-  validatedOrderCreationLimit(args);
+  refuseBadOrderCreationLimit(args);
   const resolved = await resolveQaInputs(args);
   return runResolvedQa(args, resolved, options);
 }
@@ -2279,12 +2336,14 @@ async function finalizeQaRun({ args, resolved, runId, startedAt, assertions, tes
     baseDir: resolved.packetPath ? dirname(resolved.packetPath) : null,
     targetRepo: resolved.packetPath ? targetRepoFor(resolved.packetPath, resolved.packet) : null,
     mapId: resolved.mapId,
+    localSpecId: resolved.localSpecId,
     currentRunId: runId,
     isFinding: isFindingAssertion,
   });
   const verdict = createVerdict({
     runId,
     mapId: resolved.mapId,
+    localSpecId: resolved.localSpecId,
     publicRouteSlug: resolved.publicRouteSlug || null,
     campaignRefId: resolved.spec.campaign?.ref_id || null,
     specVersion: resolved.specVersion,
@@ -2338,7 +2397,9 @@ async function finalizeQaRun({ args, resolved, runId, startedAt, assertions, tes
   // config, or scope mismatch should be visible on the QA path too, not just
   // on remit (Kilo review, PR #177).
   const consent = resolveConsent({ proxyBase: resolved.proxyBase });
-  const publishDecision = decidePublishVerdict({ args, portalManaged: resolved.portalManaged === true, consent });
+  const publishDecision = resolved.localSpecId
+    ? { publish: false, reason: "local_spec", flag_invalid: false }
+    : decidePublishVerdict({ args, portalManaged: resolved.portalManaged === true, consent });
   if (publishDecision.flag_invalid) {
     process.stderr.write(`[campaigns-os] --post-verdict "${args["post-verdict"]}" is not a recognized value (use true|1|yes|y|on or false|0|no|n|off); the flag was ignored and the default publish decision applied.\n`);
   }
@@ -2358,6 +2419,7 @@ async function finalizeQaRun({ args, resolved, runId, startedAt, assertions, tes
     status: verdict.disposition,
     run_id: verdict.run_id,
     map_id: resolved.mapId,
+    ...(resolved.localSpecId ? { local_spec_id: resolved.localSpecId } : {}),
     public_route_slug: resolved.publicRouteSlug || null,
     ...reportPathField(resolved),
     base_url: resolved.baseUrl,
@@ -2983,7 +3045,7 @@ function output(value, args) {
   }
   if (value.verdict) {
     console.log(`QA run complete.`);
-    console.log(`Map ID: ${value.map_id}`);
+    console.log(`${value.local_spec_id ? "Local spec ID" : "Map ID"}: ${value.local_spec_id || value.map_id}`);
     console.log(`Base URL: ${value.base_url || "(missing)"}`);
     printEntryUrlLines(value.entry_urls);
     console.log(`Run ID: ${value.run_id}`);
@@ -3016,7 +3078,7 @@ function output(value, args) {
   }
   console.log(`QA resolve complete.`);
   console.log(`Status: ${value.status}`);
-  console.log(`Map ID: ${value.map_id}`);
+  console.log(`${value.local_spec_id ? "Local spec ID" : "Map ID"}: ${value.local_spec_id || value.map_id}`);
   console.log(`Spec: ${value.spec_source}`);
   console.log(`Base URL: ${value.base_url || "(missing)"}`);
   printEntryUrlLines(value.entry_urls);
@@ -3166,7 +3228,9 @@ export function qaResolveNextProofLines(value) {
   return [
     `Next expected proof: ${qaRunCommandFromResolve(value)}`,
     `Entry URL(s) resolved: ${formatEntryUrlsForProof(value.entry_urls)}`,
-    "Typed-card test orders use global test cards (no transactions/no permission gate); QA publishes to the portal by default.",
+    value.local_spec_id
+      ? "Typed-card test orders use global test cards (no transactions/no permission gate); local-spec QA stays in the repository."
+      : "Typed-card test orders use global test cards (no transactions/no permission gate); QA publishes to the portal by default.",
   ];
 }
 
@@ -3232,16 +3296,21 @@ function stringArg(value) {
   return typeof value === "string" && value.trim() ? value.trim() : null;
 }
 
+// setOptionalBoolean and setOptionalString serve `qa policy set` only, ahead of
+// its packet write, so a bad value there is a refusal. booleanArg itself stays
+// untagged: it is shared with `qa run`'s analytics leg, which calls it mid-run,
+// where a throw is a handler failure — so the tag goes on this call site
+// (`refusing()`), not in the validator.
 function setOptionalBoolean(target, property, args, key, changed) {
   if (!(key in args)) return;
-  const value = booleanArg(args[key], key);
+  const value = refusing(() => booleanArg(args[key], key));
   setIfChanged(target, property, value, changed);
 }
 
 function setOptionalString(target, property, args, key, changed) {
   if (!(key in args)) return;
   const value = stringArg(args[key]);
-  if (!value) throw new Error(`--${key} requires a value.`);
+  if (!value) throw refused(`--${key} requires a value.`);
   setIfChanged(target, property, value, changed);
 }