@nextcommerce/campaigns-os 1.41.2 → 1.43.1

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/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";
@@ -345,9 +346,20 @@ 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 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,
   // no CampaignSpec. Scope (pages + funnel types) is resolved from the built
@@ -371,15 +383,13 @@ async function resolveQaInputs(args, {
   const mapId = stringArg(args["map-id"])
     || stringArg(args._[2])
     || stringArg(packet?.spec?.map_id);
-  // A refusal to identify a campaign, not a failure to QA one: with no
-  // --packet, no --site/--built and no positional <map-id>, every read above
-  // was skipped and `qa run` has nothing to work on. Tagged on both paths, not
-  // just the empty one — the journal question is whether the CLI reached a
-  // handler's WORK, and a missing-identity refusal decides that before any
-  // spec is fetched, any browser launches and anything is written. (When a
-  // packet WAS named, it has been read by here; the packet read is a lookup
-  // for the same identity question, and one message cannot be two verdicts.)
-  if (!mapId) throw refused("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);
@@ -404,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);
@@ -449,6 +466,7 @@ async function resolveQaInputs(args, {
     packetPath,
     packet,
     mapId,
+    localSpecId,
     publicRouteSlug,
     proxyBase,
     baseUrl,
@@ -478,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)
@@ -513,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,
@@ -548,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;
 }
@@ -640,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,
@@ -666,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) {
@@ -1506,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 } : {}),
@@ -2311,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,
@@ -2370,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`);
   }
@@ -2390,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,
@@ -3015,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}`);
@@ -3048,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);
@@ -3198,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.",
   ];
 }
 

package/src/qa-publish.mjs

@@ -46,6 +46,7 @@ export const QA_PUBLISH_STATUSES = Object.freeze({
 // thrown error, so --json readers get a code to branch on.
 export const QA_PUBLISH_REFUSALS = Object.freeze({
   packet_required: "packet_required",
+  local_spec: "local_spec",
   order_flags_refused: "order_flags_refused",
   verdict_missing: "verdict_missing",
   verdict_unreadable: "verdict_unreadable",
@@ -218,6 +219,9 @@ async function attemptPublish(args, operations, dryRun) {
     return refusal(QA_PUBLISH_REFUSALS.packet_required, `Build Packet ${packetPath} is not readable (${error.code || error.message}).`);
   }
 
+  if (packet?.spec?.local_spec_id != null) {
+    return refusal(QA_PUBLISH_REFUSALS.local_spec, "Local-spec QA has no saved Map destination; keep its verdict in the repository. Portal publication requires a saved Map and fresh evidence.");
+  }
   const source = resolveStoredVerdictSource({ args, packetPath, packet, readJsonFile: ops.readJsonFile, exists: ops.exists });
   if (source.error) return source.error;
   let verdict;

package/src/qa-sidecar.mjs

@@ -1,3 +1,4 @@
+import { localSpecIdentityFields } from "./spec-source-identity.mjs";
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { dirname, join, resolve } from "node:path";
@@ -77,6 +78,7 @@ export function projectVerdictForSidecar(verdict, { generatedAt }) {
     schema_version: verdict.schema_version,
     run_id: verdict.run_id,
     campaign_slug: verdict.campaign_slug,
+    ...localSpecIdentityFields(verdict),
     ...(verdict.public_route_slug != null ? { public_route_slug: verdict.public_route_slug } : {}),
     ...(verdict.campaign_ref_id != null ? { campaign_ref_id: verdict.campaign_ref_id } : {}),
     spec_version: verdict.spec_version,

package/src/qa-verdict-discovery.mjs

@@ -1,3 +1,4 @@
+import { resolveCampaignIdentity, localQaIdentifier } from "./spec-source-identity.mjs";
 // QA verdict discovery: the one walk over the local verdicts a campaign has
 // written, with the projections each reader needs.
 //
@@ -28,11 +29,20 @@ function qaVerdictSlug(packet) {
 // the slug as identity. A verdict is this campaign's when its campaign_slug
 // is one of them.
 export function qaVerdictIdentifiers(packet) {
+  if (packet?.spec?.local_spec_id != null) {
+    const identity = resolveCampaignIdentity(packet.spec);
+    return identity?.kind === "local_spec" ? [localQaIdentifier(identity.id)] : [];
+  }
   return [...new Set([optionalString(packet?.spec?.map_id), qaVerdictSlug(packet)].filter(Boolean))];
 }
 
 export function qaVerdictIdentityMatch(verdict, packet) {
   const slug = optionalString(verdict?.campaign_slug);
+  if (packet?.spec?.local_spec_id != null || verdict?.local_spec_id != null) {
+    const identity = resolveCampaignIdentity(packet?.spec);
+    return identity?.kind === "local_spec" && verdict?.local_spec_id === identity.id
+      && slug === localQaIdentifier(identity.id);
+  }
   return Boolean(slug) && qaVerdictIdentifiers(packet).includes(slug);
 }
 
@@ -174,6 +184,7 @@ export function qaVerdictCandidateScore(candidate, packet) {
   const mapId = optionalString(packet?.spec?.map_id);
   const slug = qaVerdictSlug(packet);
   let score = 0;
+  if (packet?.spec?.local_spec_id && qaVerdictIdentityMatch(verdict, packet)) score += 100;
   if (mapId && verdict.campaign_slug === mapId) score += 100;
   if (slug && verdict.campaign_slug === slug) score += 80;
   if (verdict.schema_version === "1.0" || verdict.schema_version === "campaigns-os-qa-verdict/v0") score += 10;

package/src/qa-verdict-publish.mjs

@@ -42,6 +42,7 @@ export const QA_VERDICT_PUBLISH_STATES = Object.freeze(["skipped", "ok", "failed
  * must not claim a credential is travelling in clear.
  */
 export async function publishQaVerdict(verdict, proxyBase, { fetchImpl = globalThis.fetch, remitImpl = remit } = {}) {
+  if (verdict?.local_spec_id != null) return { ...skippedQaVerdictPublish(), reason: "local_spec" };
   let httpStatus = null;
   let response = null;
   let failure = null;

package/src/qa-verdict.mjs

@@ -1,3 +1,4 @@
+import { resolveCampaignIdentity, localQaIdentifier } from "./spec-source-identity.mjs";
 export const QA_SCHEMA_VERSION = "1.0";
 
 export const STATUS = Object.freeze({
@@ -95,6 +96,7 @@ function dispositionWithCommercial(assertions, commercial) {
 export function createVerdict({
   runId,
   mapId,
+  localSpecId = null,
   publicRouteSlug = null,
   campaignRefId = null,
   specVersion,
@@ -126,7 +128,8 @@ export function createVerdict({
     run_id: runId,
     // campaign_slug carries the Map ID for schema back-compat; the true public
     // route slug rides alongside so consumers stop conflating the two.
-    campaign_slug: mapId,
+    campaign_slug: localSpecId ? localQaIdentifier(localSpecId) : mapId,
+    ...(localSpecId ? { local_spec_id: localSpecId } : {}),
     public_route_slug: optionalString(publicRouteSlug),
     campaign_ref_id: campaignRefId,
     spec_version: specVersion,
@@ -208,6 +211,10 @@ export function deriveExceptions(assertions = []) {
 
 export function validateVerdict(verdict) {
   const errors = [];
+  if (verdict?.local_spec_id != null && (!resolveCampaignIdentity({ local_spec_id: verdict.local_spec_id })
+    || verdict.campaign_slug !== localQaIdentifier(verdict.local_spec_id))) {
+    errors.push("Local-spec verdict requires a valid local_spec_id and its local QA identifier.");
+  }
   if (!verdict || typeof verdict !== "object" || Array.isArray(verdict)) {
     return ["verdict: must be an object"];
   }

package/src/readback.mjs

@@ -1187,6 +1187,7 @@ function renderIdentity(views, lines) {
     const spec = packet.spec || {};
     const campaign = packet.campaign || {};
     if (spec.map_id) entries.push(["map_id", spec.map_id, "build packet"]);
+    if (spec.local_spec_id) entries.push(["local_spec_id", spec.local_spec_id, "build packet"]);
     if (campaign.public_route_slug) {
       entries.push(["public_route_slug", campaign.public_route_slug, "build packet"]);
     }
@@ -1194,7 +1195,7 @@ function renderIdentity(views, lines) {
     if (assembly.template_family) entries.push(["template_family", assembly.template_family, "build packet"]);
   } else if (doctor) {
     const derived = doctor.derived || {};
-    for (const field of ["map_id", "public_route_slug", "template_family"]) {
+    for (const field of ["map_id", "local_spec_id", "public_route_slug", "template_family"]) {
       if (derived[field]) entries.push([field, derived[field], "doctor output"]);
     }
   }

package/src/run-record-closeout.mjs

@@ -1,3 +1,4 @@
+import { campaignIdentitiesMatch } from "./spec-source-identity.mjs";
 // Run Record closeout recognition.
 //
 // `next` at stage "done" used to demand a Run Record unconditionally, because
@@ -93,13 +94,11 @@ function qaVerdictDigests(record) {
  * satisfy closeout — and `run-record` never re-emits under its id.
  */
 export function identityMatches(record, packet) {
-  const mapId = text(packet?.spec?.map_id);
   const slug = text(packet?.campaign?.public_route_slug);
   const identity = isObject(record?.identity) ? record.identity : {};
-  const recordMapId = text(identity.map_id);
   const recordSlug = text(identity.campaign_slug);
-  if (!mapId || !slug || !recordMapId || !recordSlug) return false;
-  return recordMapId === mapId && recordSlug === slug;
+  if (!slug || !recordSlug) return false;
+  return campaignIdentitiesMatch(identity, packet?.spec) && recordSlug === slug;
 }
 
 function outcome(reason_code, detail, entry = null) {

package/src/run-record.mjs

@@ -1,3 +1,4 @@
+import { localSpecIdentityFields, resolveCampaignIdentity } from "./spec-source-identity.mjs";
 // Run Telemetry — per-run Run Record capture for Campaigns OS.
 // See docs/workflow-findings-sidecar.md (Run Telemetry).
 //
@@ -155,6 +156,8 @@ export function validateRunRecord(record) {
   if (record.identity != null) {
     if (typeof record.identity !== "object" || Array.isArray(record.identity)) {
       add("record.identity", "identity must be an object when present.");
+    } else if (record.identity.local_spec_id != null && resolveCampaignIdentity(record.identity)?.kind !== "local_spec") {
+      add("record.identity.local_spec_id", "local_spec_id must be a canonical local ID with no saved Map identity.");
     }
   }
 
@@ -449,6 +452,7 @@ export function selectRunFindingIds(journal, runId) {
 function normalizeIdentity(identity = {}) {
   return {
     map_id: identity.map_id ?? null,
+    ...localSpecIdentityFields(identity),
     campaign_slug: identity.campaign_slug ?? null,
     template_family: identity.template_family ?? null,
     entry_point_shape: identity.entry_point_shape ?? null,

package/src/sidecar-bundle.mjs

@@ -84,6 +84,27 @@ function identityValuesAgree(identityField, left, right) {
 }
 
 function compareIdentity(errors, records, identityField) {
+  const local = identityField.local_spec_alternative;
+  if (local && records.get("build_packet")?.value?.spec?.local_spec_id != null) {
+    compareIdentity(errors, records, local);
+    // A local identity can never borrow a Map identity from another artifact.
+    for (const [kind, path] of Object.entries(identityField.artifact_paths)) {
+      if (kind === "qa_verdict") continue; // campaign_slug is the local QA storage key.
+      if (valueAt(records.get(kind)?.value, path) != null) {
+        errors.push(artifactFinding("bundle.identity.map_id_mismatch", kind,
+          "Local-spec bundle carries a saved Map identity.", "Regenerate artifacts from the same local CampaignSpec."));
+      }
+    }
+    return;
+  }
+  if (local) {
+    for (const [kind, path] of Object.entries(local.artifact_paths)) {
+      if (valueAt(records.get(kind)?.value, path) != null) {
+        errors.push(artifactFinding("bundle.identity.local_spec_id_mismatch", kind,
+          "Saved-Map bundle carries local-spec evidence.", "Regenerate artifacts from the same saved Map."));
+      }
+    }
+  }
   const label = identityField.name;
   const present = [];
   for (const [kind, path] of Object.entries(identityField.artifact_paths)) {

package/src/spec-source-identity.mjs

@@ -0,0 +1,44 @@
+// Stable campaign identity is separate from both the public route and the
+// material spec hash. Local IDs never identify a saved Map or a portal URL.
+export const LOCAL_SPEC_ID_PATTERN = "^[A-Za-z0-9_-]{1,64}$";
+const localIdPattern = new RegExp(LOCAL_SPEC_ID_PATTERN);
+const text = value => typeof value === "string" && value.trim() ? value.trim() : null;
+
+export function campaignSpecIdentity(spec) {
+  return {
+    map_id: spec?.spec_identity?.map_id ?? spec?.map_id ?? null,
+    local_spec_id: spec?.spec_identity?.local_spec_id ?? null,
+  };
+}
+
+export function resolveCampaignIdentity(fields) {
+  // Saved Map IDs retain their existing whitespace normalization. Local IDs
+  // are canonical, repository-owned tokens: never trim one into another ID.
+  const mapId = text(fields?.map_id);
+  const localId = fields?.local_spec_id;
+  if (localId != null) {
+    if (fields?.map_id != null || typeof localId !== "string" || !localIdPattern.test(localId)) return null;
+    return { kind: "local_spec", id: localId };
+  }
+  return mapId ? { kind: "saved_map", id: mapId } : null;
+}
+
+export function campaignIdentitiesMatch(left, right) {
+  const a = resolveCampaignIdentity(left);
+  const b = resolveCampaignIdentity(right);
+  return !!a && !!b && a.kind === b.kind && a.id === b.id;
+}
+
+export function localSpecIdentityFields(fields) {
+  if (fields?.local_spec_id == null) return {};
+  const identity = resolveCampaignIdentity(fields);
+  // Omitting a malformed marker would let a conflicting identity fall back to
+  // its Map ID. Writers must refuse it rather than silently change its kind.
+  if (identity?.kind !== "local_spec") throw new Error("Invalid local_spec_id or conflicting saved Map identity.");
+  return { local_spec_id: identity.id };
+}
+
+export function localQaIdentifier(localSpecId) {
+  if (typeof localSpecId !== "string" || !localIdPattern.test(localSpecId)) throw new Error("Invalid local_spec_id.");
+  return `local-spec-${localSpecId}`;
+}

package/src/stage-ledger.mjs

@@ -1,3 +1,4 @@
+import { campaignIdentitiesMatch } from "./spec-source-identity.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import { markDoctorSidecarStale, writeDoctorSidecar, writeJsonAtomic } from "./doctor-sidecar.mjs";
 import { STATUS as QA_STATUS } from "./qa-verdict.mjs";
@@ -377,7 +378,9 @@ export function qaGatePassedForCurrentBuild(report, gate, { buildFingerprint })
  */
 export function assemblyReportMatchesPacket(report, packet) {
   return isPlainObject(report)
-    && optionalString(report?.identity?.map_id) === optionalString(packet?.spec?.map_id)
+    && (report?.identity?.local_spec_id != null || packet?.spec?.local_spec_id != null
+      ? campaignIdentitiesMatch(report?.identity, packet?.spec)
+      : optionalString(report?.identity?.map_id) === optionalString(packet?.spec?.map_id))
     && optionalString(report?.identity?.public_route_slug) === optionalString(packet?.campaign?.public_route_slug);
 }