@nextcommerce/campaigns-os 1.37.3 → 1.43.1

package/schemas/campaigns-os-effects.v1.schema.json

@@ -0,0 +1,211 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nextcommerce.com/schemas/campaigns-os-effects.v1.schema.json",
+  "title": "Campaigns OS Declared Command Effects v1",
+  "description": "The shape of contracts/effects.v1.json: one row per supported invocation — a command, its subcommand, and the flag combination that changes what the invocation does to the world — stating what it writes, what it sends, the MCP-style annotations a tool face would carry, the effect tier, and the name of the node:test case that proves the row. The claim a row makes is two-sided and both sides are tested: nothing the row does not declare may change, and every declared effect whose `observed_in` names a condition must be seen in it. An effect the offline fixture cannot reach carries an empty `observed_in` and a `not_observed_reason`. Read this with docs/effects.md; scripts/check-effects.mjs enforces the parts a schema cannot (coverage of the supported CLI surface, and the existence of every named test case).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "contract_version", "vocabulary", "rows"],
+  "properties": {
+    "schema": {
+      "const": "campaigns-os-effects/v1",
+      "description": "A consumer should refuse a payload whose schema it does not recognize rather than reading the fields it happens to know."
+    },
+    "_note": { "type": "string" },
+    "contract_version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "The contract's own version, independent of the package's surface_version: adding a row is additive, changing a row's declared effect is not."
+    },
+    "vocabulary": {
+      "type": "object",
+      "description": "The words the rows use, defined once. A reader must not have to infer what `tier: \"C\"` or `{lifecycle-journal}` means from the rows that happen to use them.",
+      "additionalProperties": false,
+      "required": ["annotations", "tiers", "locations", "conditions", "effect_changing_flags", "test_scope", "observed_in", "preflight"],
+      "properties": {
+        "annotations": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["readOnlyHint", "destructiveHint", "openWorldHint", "idempotentHint"],
+          "properties": {
+            "readOnlyHint": { "type": "string" },
+            "destructiveHint": { "type": "string" },
+            "openWorldHint": { "type": "string" },
+            "idempotentHint": { "type": "string" }
+          }
+        },
+        "tiers": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["none", "A", "B", "C", "_ranking"],
+          "properties": {
+            "none": { "type": "string" },
+            "A": { "type": "string" },
+            "B": { "type": "string" },
+            "C": { "type": "string" },
+            "_ranking": { "type": "string" }
+          }
+        },
+        "locations": {
+          "type": "object",
+          "description": "The location tokens a row's write paths may use. A path pattern is relative to the token it opens with.",
+          "minProperties": 1,
+          "additionalProperties": { "type": "string" }
+        },
+        "conditions": {
+          "type": "object",
+          "description": "The five conditions every row is exercised under. The fifth, persisted_consent, is not a variant of the other four: it is the one that does not take the row's word for whether telemetry consent is on.",
+          "additionalProperties": false,
+          "required": ["no_session", "ambient_session", "stale_session", "lifecycle_log", "persisted_consent"],
+          "properties": {
+            "no_session": { "type": "string" },
+            "ambient_session": { "type": "string" },
+            "stale_session": { "type": "string" },
+            "lifecycle_log": { "type": "string" },
+            "persisted_consent": { "type": "string" }
+          }
+        },
+        "effect_changing_flags": {
+          "type": "array",
+          "description": "The flags that change what an invocation does to the world. Every one of them that appears on a CLI help usage line owes a row of its own; scripts/check-effects.mjs refuses the file when one does not have it. A flag that only changes the output shape (--json, --report) is deliberately absent.",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^--[a-z0-9-]+$" }
+        },
+        "test_scope": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["full", "preflight"],
+          "properties": { "full": { "type": "string" }, "preflight": { "type": "string" } }
+        },
+        "observed_in": { "type": "string" },
+        "preflight": { "type": "string" }
+      }
+    },
+    "rows": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/row" }
+    }
+  },
+  "$defs": {
+    "condition": {
+      "enum": ["no_session", "ambient_session", "stale_session", "lifecycle_log", "persisted_consent"]
+    },
+    "observed_in": {
+      "type": "array",
+      "description": "The conditions in which the effect test MUST see this effect. Empty declares an effect the offline fixture cannot reach, and then `not_observed_reason` is required.",
+      "items": { "$ref": "#/$defs/condition" },
+      "uniqueItems": true
+    },
+    "row": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command", "subcommand", "flags", "annotations", "tier", "writes", "sends", "effect_test", "test_scope", "notes"],
+      "properties": {
+        "command": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The top-level command, or the reserved `*refused*` for an invocation refused before its handler runs."
+        },
+        "subcommand": {
+          "description": "The subcommand as the help text spells it (`policy set` is one subcommand, not a subcommand and a flag), or null.",
+          "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }]
+        },
+        "flags": {
+          "type": "array",
+          "description": "The effect-changing flag combination this row is about. Empty is the base form. Flags that do not change what the invocation does to the world (--json, --report) are deliberately absent.",
+          "items": { "type": "string", "pattern": "^--[a-z0-9-]+$" },
+          "uniqueItems": true
+        },
+        "annotations": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["readOnlyHint", "destructiveHint", "openWorldHint", "idempotentHint"],
+          "properties": {
+            "readOnlyHint": { "type": "boolean" },
+            "destructiveHint": { "type": "boolean" },
+            "openWorldHint": { "type": "boolean" },
+            "idempotentHint": { "type": "boolean" }
+          }
+        },
+        "tier": { "enum": ["none", "A", "B", "C"] },
+        "writes": { "type": "array", "items": { "$ref": "#/$defs/write" } },
+        "sends": { "type": "array", "items": { "$ref": "#/$defs/send" } },
+        "effect_test": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The exact name of the node:test case in src/effects.test.mjs that proves this row. check-effects.mjs refuses a row whose case is not there."
+        },
+        "test_scope": { "enum": ["full", "preflight"] },
+        "preflight": { "$ref": "#/$defs/preflight" },
+        "notes": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Why the row says what it says, in a consumer's terms. A preflight row states what it cannot reach offline and what the case proves instead."
+        }
+      },
+      "if": { "properties": { "test_scope": { "const": "preflight" } }, "required": ["test_scope"] },
+      "then": {
+        "description": "A preflight row declares its allowances. The converse — a `full` row that carries them — is reported by scripts/check-effects.mjs, which can say which row it is.",
+        "required": ["preflight"],
+        "properties": { "preflight": { "$ref": "#/$defs/preflight" } }
+      }
+    },
+    "preflight": {
+      "type": "object",
+      "description": "What the preflight itself may do, declared independently of the effects the row declares for the invocation that gets past it. Without this, a write declared for the success path ({home}/** for a minted credential) also licensed the refusal to write anywhere under the home directory, and a destination a loopback receiver only stands in for licensed any request path at all.",
+      "additionalProperties": false,
+      "required": ["may_write", "may_contact"],
+      "properties": {
+        "may_write": {
+          "type": "array",
+          "description": "The ONLY paths the preflight may write, each a location token or a path under one. A pattern spanning segments (**) is refused by scripts/check-effects.mjs: an allowance that licenses a subtree licenses the home directory the preflight must not touch.",
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "may_contact": {
+          "type": "array",
+          "description": "The exact request paths the loopback receiver may see, matched literally against the request path. Empty means the preflight contacts nothing.",
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "write": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "when", "observed_in"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "A glob pattern (`*` within one segment, `**` across segments) opening with a location token from vocabulary.locations."
+        },
+        "when": { "type": "string", "minLength": 1 },
+        "observed_in": { "$ref": "#/$defs/observed_in" },
+        "not_observed_reason": { "type": "string", "minLength": 1 }
+      }
+    },
+    "send": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["destination", "what", "when", "requires_consent", "observed_in"],
+      "properties": {
+        "destination": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The endpoint, with the same location tokens. A destination of the form `{proxy-base}/<path>` pins the request path down, so the test can assert the declared destination IS the one contacted."
+        },
+        "what": { "type": "string", "minLength": 1 },
+        "when": { "type": "string", "minLength": 1 },
+        "requires_consent": {
+          "type": "boolean",
+          "description": "True when Run Telemetry consent gates the send. The effect test runs such a row with consent ON and a loopback receiver, so 'nothing was sent' can never be an artefact of consent being off."
+        },
+        "observed_in": { "$ref": "#/$defs/observed_in" },
+        "not_observed_reason": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/schemas/campaigns-os-progress-snapshot.v0.schema.json

@@ -71,6 +71,7 @@
         "build_fingerprint_algorithm"
       ],
       "properties": {
+        "local_spec_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" },
         "map_id": {
           "type": [
             "string",

package/schemas/campaigns-os-qa-verdict-sidecar.v0.schema.json

@@ -29,6 +29,7 @@
       "description": "Same literal as the full verdict — the sidecar is the same contract projected, not a second schema lineage."
     },
     "run_id": { "type": "string", "minLength": 1 },
+    "local_spec_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "Stable repository-owned CampaignSpec identity; never a saved Map ID. Keep unchanged across local revisions." },
     "campaign_slug": {
       "type": "string",
       "minLength": 1,

package/schemas/campaigns-os-qa-verdict.v0.schema.json

@@ -29,6 +29,7 @@
       "minLength": 1,
       "description": "The QA run identity, also the verdict filename under qa-output/<map-id>/. The portal receiver additionally restricts it to [A-Za-z0-9_-]{1,64}."
     },
+    "local_spec_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "Stable repository-owned CampaignSpec identity; never a saved Map ID. Keep unchanged across local revisions." },
     "campaign_slug": {
       "type": "string",
       "minLength": 1,

package/schemas/campaigns-os-readback.v2.schema.json

@@ -0,0 +1,267 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nextcommerce.com/schemas/campaigns-os-readback.v2.schema.json",
+  "title": "Campaigns OS Run-Artifact Readback v2",
+  "description": "The machine-readable projection `campaigns-os readback <target> --json` writes to stdout. It serializes exactly what the rendered text view computes over a run's already-emitted artifacts (Build Packet, doctor output, build context, assembly report, QA verdict, findings export) and adds no interpretation the text view does not also carry. The readback is read-only: it writes nothing under the target, starts no process, touches no network, and records no lifecycle entry. v2 differs from v1 in one field's meaning: staleness is assessed PER ARTIFACT, and the aggregate `stale` is true when ANY loaded artifact is stale, where v1 compared only the newest artifact and so reported a set fresh whenever its newest member was. Field semantics and the exact `clean` rule live in docs/readback.md; that document and this schema move together. A consumer that recognizes v2 accepts and preserves unknown additive properties without interpreting them.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schema_version",
+    "artifacts",
+    "packet_selection",
+    "staleness",
+    "doctor",
+    "skip_cascades",
+    "divergences",
+    "clean"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "campaigns-os-readback/v2",
+      "description": "A consumer should refuse a payload whose schema_version it does not recognize rather than reading the fields it happens to know."
+    },
+    "artifacts": {
+      "type": "array",
+      "description": "One record per artifact the readback projected, in the fixed render order (packet, doctor, context, report, qa_verdict, findings), restricted to the keys the caller asked for. The artifact's own parsed contents are deliberately absent: a consumer that wants an artifact's payload reads that artifact, so this projection never becomes an unversioned mirror of every upstream schema.",
+      "items": { "$ref": "#/$defs/artifact_row" }
+    },
+    "packet_selection": {
+      "description": "How the projected Build Packet was chosen, or null when a programmatic caller built a payload without a selection record. The CLI always supplies one.",
+      "oneOf": [{ "$ref": "#/$defs/packet_selection" }, { "type": "null" }]
+    },
+    "staleness": {
+      "description": "The per-artifact freshness assessment, or null when a programmatic caller built a payload without one. The CLI always supplies one.",
+      "oneOf": [{ "$ref": "#/$defs/staleness" }, { "type": "null" }]
+    },
+    "doctor": { "$ref": "#/$defs/doctor_summary" },
+    "skip_cascades": {
+      "type": "array",
+      "description": "Skipped QA assertions grouped by the failure that blocked them, derived from each skipped assertion's evidence.blocked_by. One record per distinct blocker, in first-seen order. Empty when no QA verdict loaded or none of its assertions were skipped. The grouping is the readback's own projection layer.",
+      "items": { "$ref": "#/$defs/skip_cascade" }
+    },
+    "divergences": {
+      "type": "array",
+      "description": "Where two artifacts record different states for one stage: the assembly report calls a stage completed while the QA verdict fails an assertion whose id is namespaced to that stage. One record per stage, in the order the failures were seen. The readback reports the disagreement and does not adjudicate it. This too is the readback's own layer.",
+      "items": { "$ref": "#/$defs/divergence" }
+    },
+    "clean": {
+      "type": "boolean",
+      "description": "True only when every artifact the readback found is loaded or absent (never unreadable or unrecognized), staleness is computable and NO loaded artifact is stale, staleness.unparseable_keys is empty (no loaded artifact recorded an age the readback could not read), divergences is empty, and doctor.error_count is zero. A readback-integrity flag, not a verdict: a blocked QA verdict whose artifacts all read cleanly is still clean, because the readback saw exactly what Campaigns OS recorded. docs/readback.md states the rule and its limits."
+    }
+  },
+  "$defs": {
+    "artifact_key": {
+      "type": "string",
+      "enum": ["packet", "doctor", "context", "report", "qa_verdict", "findings"]
+    },
+    "utc_timestamp": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+      "description": "ISO-8601 UTC at second precision with a Z suffix, rendered by the same formatter the text view uses so both modes name the same instant identically."
+    },
+    "artifact_row": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["key", "path", "state", "detail"],
+      "properties": {
+        "key": { "$ref": "#/$defs/artifact_key" },
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The path the readback read, as resolved from the target root, a --<artifact> override, or — for packet — Build Packet discovery. --example reports the bundled sample's paths relative to the package root so the sample's output is identical wherever the package is installed."
+        },
+        "state": {
+          "type": "string",
+          "enum": ["loaded", "absent", "unreadable", "unrecognized"],
+          "description": "loaded: read and recognized. absent: no file at that path. unreadable: the bytes could not be read or parsed (over the 32 MiB read bound, not UTF-8, not JSON). unrecognized: parsed, but not a shape this readback projects."
+        },
+        "detail": {
+          "type": "string",
+          "description": "The readback's explanation for a non-loaded state, or — for a loaded artifact named in staleness.unparseable_keys — the shape of the generated_at value that did not parse, so a consumer reading artifacts alone can see that this artifact's age was never established. The value itself is deliberately not reproduced here. The empty string for every other loaded artifact and for an absent one."
+        }
+      }
+    },
+    "packet_selection": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["mode", "signal", "selected", "candidates_considered", "rejected"],
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["explicit", "default", "discovered"],
+          "description": "explicit: the caller passed --packet. default: the chosen packet is the default-named campaign-runtime.build.json, including a target with no packet at all, where the default path is still the path reported absent. discovered: freshness selected a suffixed packet."
+        },
+        "signal": {
+          "type": "string",
+          "enum": ["explicit", "sole_candidate", "generated_at", "none"],
+          "description": "What decided it. Freshness is the packet's own recorded generated_at, never the file's modification time: an mtime is rewritten by a clone, a checkout, or a copy without any run having recorded anything, so content-only selection keeps discovery a pure function of the bytes on disk."
+        },
+        "selected": {
+          "description": "The file name discovery chose, or null when no discovery chose one (the explicit and none signals). The full path is the packet row's path in artifacts.",
+          "type": ["string", "null"]
+        },
+        "candidates_considered": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "description": "The file names of the valid candidates discovery compared, default-first then name order. Empty for explicit mode, where no discovery runs."
+        },
+        "rejected": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/rejected_candidate" },
+          "description": "Candidates discovery skipped. Root-level files matching the packet naming land here when they did not parse, were not an object, or did not declare a recognized packet schema_version. When no valid root candidate exists, a packet sitting only at .campaign-runtime/campaign-runtime.build.json is recorded here too: that sidecar location is not a discovery candidate, and the reason tells the caller to pass --packet."
+        }
+      }
+    },
+    "rejected_candidate": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["path", "reason"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "reason": { "type": "string", "minLength": 1 }
+      }
+    },
+    "staleness": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "computable",
+        "stale",
+        "stale_keys",
+        "unparseable_keys",
+        "artifacts",
+        "newest_key",
+        "head_time",
+        "head_detail",
+        "artifact_times"
+      ],
+      "properties": {
+        "computable": {
+          "type": "boolean",
+          "description": "True when at least one loaded artifact carried a parseable generated_at AND the checkout's HEAD reflog was readable."
+        },
+        "stale": {
+          "type": "boolean",
+          "description": "True when ANY loaded artifact's generated_at predates the last recorded HEAD movement. This is the v1 -> v2 change of meaning: v1 compared only the newest artifact, so one regenerated artifact reported the whole set fresh. Always false when computable is false; absence of the signal is not evidence of freshness."
+        },
+        "stale_keys": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/artifact_key" },
+          "description": "The stale artifact keys, in the fixed render order. Empty when nothing is stale or the comparison is not computable."
+        },
+        "unparseable_keys": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/artifact_key" },
+          "description": "The loaded artifacts that RECORDED a generated_at this readback could not parse, in the fixed render order. Their age was never established — they are neither fresh nor stale, they are absent from artifacts and artifact_times, and clean is false while this list is non-empty, because an unknown age must never read as a fresh one. Each one's artifact row carries the shape of the refused value in its detail. An artifact that carries NO generated_at key at all is a different case: it recorded no age to check, so it is absent from this list and is not by itself unclean (though with no other artifact carrying one, the comparison is not computable). Independent of computable and stale, which keep their meanings: a set whose only comparable artifact is fresh still reports stale false."
+        },
+        "artifacts": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/artifact_freshness" },
+          "description": "Every loaded artifact that carried a parseable generated_at, keyed by artifact key, in render order. An artifact with no parseable generated_at is neither fresh nor stale and is absent from this map; if it is the only artifact, the assessment is not computable. Where it recorded a generated_at that did not parse, unparseable_keys names it."
+        },
+        "newest_key": {
+          "description": "The artifact key holding the newest generated_at, or null when not computable. Information only in v2: it no longer decides the aggregate.",
+          "oneOf": [{ "$ref": "#/$defs/artifact_key" }, { "type": "null" }]
+        },
+        "head_time": {
+          "description": "The last recorded HEAD movement, or null when the reflog gave no usable time.",
+          "oneOf": [{ "$ref": "#/$defs/utc_timestamp" }, { "type": "null" }]
+        },
+        "head_detail": {
+          "type": "string",
+          "description": "Why head_time is null; the empty string when it is not."
+        },
+        "artifact_times": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/utc_timestamp" },
+          "description": "Every loaded artifact's parseable generated_at, keyed by artifact key. Carried unchanged from v1 for consumers that already read it; artifacts carries the same instants plus each one's verdict."
+        }
+      }
+    },
+    "artifact_freshness": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["generated_at", "stale"],
+      "properties": {
+        "generated_at": { "$ref": "#/$defs/utc_timestamp" },
+        "stale": {
+          "type": "boolean",
+          "description": "True when the last recorded HEAD movement is later than this artifact's generated_at. False when there is no HEAD signal to compare against."
+        }
+      }
+    },
+    "doctor_summary": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["present", "status", "error_count", "warning_count", "warning_groups"],
+      "properties": {
+        "present": {
+          "type": "boolean",
+          "description": "Whether a doctor output loaded. When false, status is null and both counts are 0: those zeros record an absence, not an observation."
+        },
+        "status": {
+          "type": ["string", "null"],
+          "description": "Doctor's own status string, unreinterpreted."
+        },
+        "error_count": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The length of doctor's errors list (0 when the field is missing or not a list)."
+        },
+        "warning_count": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The total number of object-shaped warnings grouped below."
+        },
+        "warning_groups": {
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["contract-static", "repo-observed"],
+          "description": "The readback's own two-way grouping of doctor warnings, carrying each warning as doctor wrote it. The labels are the readback's projection layer, not doctor's vocabulary.",
+          "properties": {
+            "contract-static": {
+              "type": "array",
+              "items": { "type": "object" },
+              "description": "Codes under the frontmatter.* prefixes. These restate the template family's shared frontmatter contract and repeat verbatim on every doctor pass while that contract is in force. Their persistence does not mean a flagged value is still unfixed, and their disappearance is not how a fix is confirmed. A gate must not treat these as repository state."
+            },
+            "repo-observed": {
+              "type": "array",
+              "items": { "type": "object" },
+              "description": "Every other code: not in the contract-static table, so its message reflects this repository, spec, or build as doctor saw it."
+            }
+          }
+        }
+      }
+    },
+    "skip_cascade": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["blocked_by", "families"],
+      "properties": {
+        "blocked_by": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The recorded blocking assertion, or the literal \"(no blocked_by recorded)\" when the verdict named none."
+        },
+        "families": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "The skipped assertions' families, falling back to the assertion id and then to \"(unnamed)\"."
+        }
+      }
+    },
+    "divergence": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["stage", "assertion_ids"],
+      "properties": {
+        "stage": { "type": "string", "minLength": 1 },
+        "assertion_ids": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "The failing QA assertion ids attributed to that stage."
+        }
+      }
+    }
+  }
+}

package/schemas/campaigns-os-run-record.v0.schema.json

@@ -155,6 +155,7 @@
       "additionalProperties": false,
       "description": "Best-effort run identity — the join keys that make telemetry useful. Missing identity never blocks capture.",
       "properties": {
+        "local_spec_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "Stable repository-owned CampaignSpec identity; never a saved Map ID. Keep unchanged across local revisions. Null or omitted means no local identity." },
         "map_id": { "type": ["string", "null"] },
         "campaign_slug": { "type": ["string", "null"] },
         "template_family": { "type": ["string", "null"] },