@nextcommerce/campaigns-os 1.33.0

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

@@ -0,0 +1,438 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nextcommerce.com/schemas/campaigns-os-qa-verdict.v0.schema.json",
+  "title": "Campaigns OS QA Verdict v0",
+  "description": "The full QA verdict `campaigns-os qa run` writes under qa-output/<map-id>/<run-id>.json and publishes to the QA portal receiver. Contract identity is campaigns-os-qa-verdict/v0; the emitted schema_version FIELD is the literal \"1.0\" (it predates the slash-versioned naming convention, and the receiving Worker validates that same literal — changing the emitted value is a breaking shape change). Additions to v0 are expected; consumers must tolerate unknown fields, so additionalProperties stays true. Full verdicts carry live storefront URLs, request evidence, and order references and are gitignored — the committed form is the allowlist projection described by campaigns-os-qa-verdict-sidecar.v0.schema.json. Trust semantics: the CLI never emits trusted/trust_level/verified_at; the QA verdict receiver stamps them server-side at ingest, so they appear only on records read back from the portal. Schema-validity is NOT trust — a forged record can be shape-valid. Every downstream consumer MUST filter or segregate records carrying trusted: false. See docs/qa-and-test-orders.md (Verdict schema and trust semantics).",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schema_version",
+    "run_id",
+    "campaign_slug",
+    "spec_version",
+    "spec_hash",
+    "started_at",
+    "completed_at",
+    "runtime",
+    "disposition",
+    "assertions",
+    "test_orders",
+    "exceptions"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "1.0",
+      "description": "The emitted schema-version literal. \"1.0\" is the campaigns-os-qa-verdict/v0 shape; both src/qa-verdict.mjs validateVerdict and the portal receiver reject any other value."
+    },
+    "run_id": {
+      "type": "string",
+      "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}."
+    },
+    "campaign_slug": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Carries the Campaign Map ID for schema back-compat; the true public route slug rides alongside as public_route_slug so consumers stop conflating the two."
+    },
+    "public_route_slug": {
+      "type": ["string", "null"],
+      "description": "The campaign's public route slug. null (or absent on verdicts emitted before the field existed) when no slug was resolved."
+    },
+    "campaign_ref_id": {
+      "type": ["integer", "null"],
+      "description": "The platform campaign ref id from the CampaignSpec, when available."
+    },
+    "spec_version": {
+      "type": "string",
+      "minLength": 1,
+      "description": "CampaignSpec schema version the run validated against (e.g. \"4.3\"), or a runner-scoped marker such as \"parity-fixture-<version>\" for fixture-driven parity runs."
+    },
+    "spec_hash": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Hash of the CampaignSpec the run used, prefixed with the algorithm (e.g. \"sha256:<hex>\")."
+    },
+    "started_at": {
+      "type": "string",
+      "minLength": 1,
+      "description": "ISO 8601 timestamp the QA run started."
+    },
+    "completed_at": {
+      "type": "string",
+      "minLength": 1,
+      "description": "ISO 8601 timestamp the verdict was finalized."
+    },
+    "runtime": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The producing runtime identity, e.g. \"campaigns-os-node-qa@0.1.0-alpha.0\"."
+    },
+    "operator": {
+      "type": "string",
+      "description": "Best-effort local operator identity (e.g. \"<user>@local\"). Empty string when unresolvable. NOT verified attribution — see the trust fields."
+    },
+    "base_url": {
+      "type": "string",
+      "description": "The --base-url or packet deploy URL the run resolved pages against. Omitted when the run had none. URL-bearing: emptied from the committed sidecar projection."
+    },
+    "entry_urls": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/pageUrlRef" },
+      "description": "One entry-page reference per funnel topology. URL-bearing: emptied ([]) in the committed sidecar projection."
+    },
+    "page_urls": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/pageUrlRef" },
+      "description": "Every resolved page URL across the run's funnel topologies, deduplicated by URL. URL-bearing: emptied ([]) in the committed sidecar projection."
+    },
+    "tested_urls": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/pageUrlRef" },
+      "description": "Pages that produced an http:<page_id> assertion, joined back to the known page references. URL-bearing: emptied ([]) in the committed sidecar projection."
+    },
+    "disposition": {
+      "type": "string",
+      "enum": ["ready", "ready_with_exceptions", "blocked"],
+      "description": "Derived from the assertions (and the commercial section's status): any unwaived failing blocker => blocked; any warn/manual_review/waived assertion or a proven commercial mismatch => ready_with_exceptions; otherwise ready. Waived is never clean. ready_with_waivers is the doctor/next checkpoint term, never a verdict disposition."
+    },
+    "assertions": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/assertion" },
+      "description": "The flat assertion list every QA leg serializes into. The portal receiver caps validation at 500 entries."
+    },
+    "test_orders": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/testOrder" },
+      "description": "One entry per typed-card browser test order the run drove, with persisted-order verification and sanitized request evidence."
+    },
+    "exceptions": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/exception" },
+      "description": "Derived projection of every assertion that failed, warned, needs manual review, or carries warn/blocker severity — the quick exception read without re-scanning assertions."
+    },
+    "commercial": {
+      "$ref": "#/$defs/commercial",
+      "description": "The commercial parity section, present on runs where calculate scenarios were planned (or explicitly recorded as unavailable). Absent on verdicts emitted before the leg existed."
+    },
+    "trusted": {
+      "type": "boolean",
+      "description": "SERVER-STAMPED, never CLI-emitted: the QA verdict receiver classifies each submission at ingest and stamps the stored record. false means the record arrived without the ingest credential (an anonymous submission) — shape-valid but unattributed. Present only on records read back from the receiver. Every downstream consumer MUST filter or segregate records with trusted: false; campaigns-os itself refuses to promote such a record into the committed sidecar and excludes it from run-record verdict inference."
+    },
+    "trust_level": {
+      "type": "string",
+      "enum": ["anonymous", "shared_secret"],
+      "description": "SERVER-STAMPED companion to trusted: how the submission authenticated. anonymous pairs with trusted: false; shared_secret pairs with trusted: true."
+    },
+    "verified_at": {
+      "type": ["string", "null"],
+      "description": "SERVER-STAMPED companion to trusted: ISO 8601 instant the receiver verified the ingest credential. null on untrusted records."
+    }
+  },
+  "$defs": {
+    "pageBinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema_version",
+        "observation",
+        "outcome",
+        "reason",
+        "source_kinds",
+        "identity"
+      ],
+      "properties": {
+        "schema_version": {
+          "const": "campaigns-os-page-binding/v0"
+        },
+        "observation": {
+          "const": "static_declaration"
+        },
+        "outcome": {
+          "enum": [
+            "match",
+            "mismatch",
+            "unknown"
+          ]
+        },
+        "reason": {
+          "enum": [
+            "credential_comparison",
+            "page_unavailable",
+            "conflicting_declarations",
+            "conflicting_expected",
+            "expected_unavailable",
+            "script_unavailable_or_limit",
+            "dynamic_unresolved",
+            "no_source"
+          ]
+        },
+        "source_kinds": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "enum": [
+              "meta",
+              "inline",
+              "config_script"
+            ]
+          }
+        },
+        "identity": {
+          "const": "not_verified"
+        }
+      },
+      "description": "Credential-free static declaration comparison, not observed execution or Campaign App identity. No keys, hashes, fragments, source URLs or inferred resource IDs."
+    },
+    "pageUrlRef": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["url"],
+      "properties": {
+        "funnel_id": { "type": ["string", "null"] },
+        "funnel_name": { "type": ["string", "null"] },
+        "page_id": { "type": ["string", "null"] },
+        "page_type": { "type": ["string", "null"] },
+        "label": { "type": ["string", "null"] },
+        "url": { "type": "string", "minLength": 1 }
+      },
+      "description": "A funnel-topology page reference: identity fields plus the resolved live URL."
+    },
+    "assertion": {
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^page-binding:"
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "then": {
+            "properties": {
+              "family": {
+                "const": "api-metadata"
+              },
+              "evidence": {
+                "$ref": "#/$defs/pageBinding"
+              }
+            },
+            "required": [
+              "evidence"
+            ]
+          }
+        }
+      ],
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["id", "family", "page", "status"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Stable assertion identity, e.g. \"http:checkout\", \"theme_gate.nothing_generatable\", \"analytics-correctness:purchase-fires\"."
+        },
+        "family": {
+          "type": "string",
+          "enum": [
+            "theme_gate",
+            "polish_gate",
+            "funnel-flow",
+            "meta-tags",
+            "api-metadata",
+            "browser-runtime",
+            "template_residue",
+            "pricing",
+            "browser-test-order",
+            "browser-receipt-rendering",
+            "analytics-correctness",
+            "analytics-parity",
+            "parity-capture"
+          ],
+          "description": "The canonical assertion-family vocabulary (QA_ASSERTION_FAMILY_VOCABULARY in src/qa-verdict.mjs; a drift test asserts set equality against the emitters). Append-only: a new emitter family is an additive schema change."
+        },
+        "page": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The page_id or label the assertion is about, or the reserved value \"campaign\" for campaign-level assertions."
+        },
+        "url": {
+          "type": "string",
+          "description": "The live page URL the assertion ran against, when page-scoped. URL-bearing: stripped from the committed sidecar projection."
+        },
+        "status": {
+          "type": "string",
+          "enum": ["pass", "fail", "warn", "skipped", "manual_review"]
+        },
+        "severity": {
+          "type": "string",
+          "enum": ["info", "warn", "blocker"],
+          "description": "Present on issue-bearing assertions. The portal receiver requires it when status is fail or warn."
+        },
+        "expected": { "type": "string" },
+        "actual": { "type": "string" },
+        "evidence": {
+          "type": "object",
+          "description": "Free-form structured evidence for this assertion (gate codes, capture summaries, blocked_by references, step ladders). Shape varies by family and is not individually contracted here. Stripped from the committed sidecar projection."
+        },
+        "waiver": { "$ref": "#/$defs/waiver" }
+      }
+    },
+    "waiver": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["reason", "waived_by", "waived_at"],
+      "properties": {
+        "reason": { "type": "string", "minLength": 1 },
+        "waived_by": { "type": "string", "minLength": 1 },
+        "waived_at": { "type": "string", "minLength": 1 }
+      },
+      "description": "A bounded named-human waiver riding an assertion. Any assertion carrying one keeps the disposition at ready_with_exceptions — waived is never clean."
+    },
+    "exception": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["id", "family", "page", "status", "severity"],
+      "properties": {
+        "id": { "type": ["string", "null"] },
+        "family": { "type": ["string", "null"] },
+        "page": { "type": ["string", "null"] },
+        "url": {
+          "type": ["string", "null"],
+          "description": "URL-bearing: null/absent in the committed sidecar projection."
+        },
+        "status": { "type": ["string", "null"] },
+        "severity": { "type": ["string", "null"] },
+        "expected": { "type": "string" },
+        "actual": { "type": "string" }
+      },
+      "description": "deriveExceptions output: the source assertion's identity fields. Values are nullable because the projection copies whatever the assertion carried."
+    },
+    "testOrder": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["path", "ok", "verification", "evidence"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The planned order path, e.g. \"checkout\", \"accept\", \"accept-decline-accept\", or a tier/coupon plan label such as \"checkout@tier:8\"."
+        },
+        "ok": { "type": "boolean" },
+        "plan_id": { "type": "string" },
+        "plan": {
+          "type": "object",
+          "description": "Summary of a spec-derived tier/coupon plan (--test-order tiers), when the order ran under one."
+        },
+        "next_order_id": { "type": ["string", "null"] },
+        "ref_id": { "type": ["string", "null"] },
+        "qa_email": {
+          "type": ["string", "null"],
+          "description": "Always the redaction marker (\"[redacted-qa-email]\") — the generated QA email itself never enters the verdict."
+        },
+        "is_test": { "type": ["boolean", "null"] },
+        "payment_method": { "type": ["string", "null"] },
+        "card": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": { "last4": { "type": "string" } },
+          "description": "Card last4 only; full test-card numbers never enter the verdict."
+        },
+        "checkout_url": { "type": "string" },
+        "final_url": { "type": ["string", "null"] },
+        "cart_state": { "type": ["object", "null"] },
+        "receipt_line_items": { "type": "array" },
+        "final_receipt_line_items": { "type": "array" },
+        "vouchers": { "type": "array" },
+        "discount_total": { "type": ["number", "null"] },
+        "upsell": { "type": "object" },
+        "upsell_steps": { "type": "array" },
+        "receipt_rendering": { "type": "object" },
+        "data_layer": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "The order's SDK data layer across every page the path visited after checkout (campaigns-os#325): exactly one dl_purchase in window.NextDataLayer whose transaction_id is this order's number or ref id. The SDK raises dl_purchase on the first ref_id page that fetches the order back (the upsell page on a funnel with one, the receipt otherwise) and dedupes it on every later page, so the reading is the whole post-checkout journey, never a snapshot of the terminal document. Present only when the path placed an order; the analytics-correctness:data-layer-purchase:<path> assertion is its judgment. Counts are per the SDK's own array, never the mirrored window.dataLayer, so a GTM adapter re-push is not a duplicate; dl_upsell_purchase is a different event and is never counted. An unhooked or unreadable layer is recorded as measured: false with null counts, not as a zero reading.",
+          "required": ["layer", "event", "measured", "outcome", "ok", "reason"],
+          "properties": {
+            "layer": { "const": "NextDataLayer" },
+            "event": { "const": "dl_purchase" },
+            "required": { "type": "boolean" },
+            "measured": { "type": "boolean", "description": "false when the array could not be read; every count below is then null." },
+            "count": { "type": ["integer", "null"], "minimum": 0, "description": "dl_purchase pushes to the layer across every page after the order." },
+            "expected_order_refs": { "type": "array", "items": { "type": "string" }, "description": "The placed order's number and ref id, either of which the SDK may report as transaction_id." },
+            "observed_transaction_ids": { "type": ["array", "null"], "items": { "type": ["string", "null"] }, "description": "transaction_id of each dl_purchase, in push order." },
+            "order_ref_match": { "type": ["boolean", "null"], "description": "Whether a dl_purchase named the placed order; null when nothing could be matched." },
+            "outcome": { "type": "string", "enum": ["pass", "absent", "duplicate", "mismatch", "order_ref_unknown", "unmeasured"], "description": "pass = one event naming the order; absent = none; duplicate = more than one (the #302 fail); mismatch = one event naming another order or none; order_ref_unknown = one event but the run recorded no order reference (manual review); unmeasured = the layer could not be hooked or read (blocker)." },
+            "ok": { "type": ["boolean", "null"] },
+            "reason": { "type": "string" }
+          }
+        },
+        "verification": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "verified": { "type": "boolean" },
+            "order_create_status": { "type": ["integer", "null"] },
+            "order_read_status": { "type": ["integer", "null"] },
+            "total_incl_tax": { "type": ["string", "null"] },
+            "currency": { "type": ["string", "null"] },
+            "order_create_observation": { "type": "string" },
+            "error": { "type": ["string", "null"] }
+          },
+          "description": "Persisted-order read-back verification — the authoritative proof path."
+        },
+        "evidence": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "steps": {
+              "type": "array",
+              "description": "The step-ladder: ordered, individually timed named steps ({step, status, started_at, duration_ms, detail?, evidence?, error?}), appended as each finishes so a crash still leaves the ladder up to the failure point."
+            },
+            "events": {
+              "type": "object",
+              "description": "Sanitized network/console event capture. Checkout request bodies and generated QA emails are redacted before serialization."
+            },
+            "order_request_seen": { "type": "boolean" },
+            "spreedly_tokenized": { "type": "boolean" }
+          }
+        }
+      }
+    },
+    "commercial": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["schema_version", "status"],
+      "properties": {
+        "schema_version": { "const": "campaigns-os-commercial-parity/v0" },
+        "status": {
+          "type": "string",
+          "enum": ["pass", "mismatch", "incomplete", "not_applicable", "not_run"],
+          "description": "mismatch keeps the verdict at ready_with_exceptions; incomplete preserves the disposition derived from ordinary assertions and never invents an exception."
+        },
+        "coverage_complete": { "type": "boolean" },
+        "findings": {
+          "type": "array",
+          "description": "Proven contract-governed claim mismatches, serialized deterministically into the flat assertions array as warn-severity pricing assertions."
+        },
+        "issues": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["code"],
+            "properties": {
+              "code": { "type": "string", "minLength": 1 },
+              "count": { "type": "integer" }
+            }
+          },
+          "description": "Sanitized capture/proxy/limit issue codes with counts. An issue records incomplete evidence; it never invents a mismatch."
+        }
+      },
+      "description": "The compact commercial-parity report: counters over checked pages, scenarios, and claims, plus findings and issues. Counter fields are additive and not individually contracted here."
+    }
+  }
+}

package/schemas/campaigns-os-release-ledger.v1.schema.json

@@ -0,0 +1,162 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nextcommerce.com/schemas/campaigns-os-release-ledger.v1.schema.json",
+  "title": "Campaigns OS Release Ledger v1",
+  "description": "The append-only, agent-relevant release ledger. One ordered entry per accepted release or reviewed amendment; one change item per agent-relevant semantic change. An entry deliberately carries NO commit identifier: an entry cannot name the commit that contains it without being rewritten after the fact, so a consumer derives the introducing commit from Git history at the immutable target OID instead. Historical entries are never rewritten; a correction ships as a new amendment entry. A consumer that recognizes v1 accepts and preserves unknown additive properties without interpreting them; required fields, known types, and safety-critical enums remain strict.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schema_version", "entries"],
+  "properties": {
+    "schema_version": {
+      "const": "campaigns-os-release-ledger/v1"
+    },
+    "_note": {
+      "type": "string",
+      "description": "Free-text authoring note. Not consumed."
+    },
+    "entries": {
+      "type": "array",
+      "description": "Ordered oldest to newest. sequence is strictly increasing by 1 from 1, and date is non-decreasing.",
+      "items": { "$ref": "#/$defs/entry" }
+    }
+  },
+  "$defs": {
+    "entry": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "id",
+        "sequence",
+        "date",
+        "kind",
+        "surface_version",
+        "changelog_section",
+        "changelog_sha256",
+        "agent_impact",
+        "compatibility",
+        "migration",
+        "changes",
+        "entry_sha256"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^RL-[0-9]{4}$",
+          "description": "Stable, immutable entry identity. Never reused, never renumbered."
+        },
+        "sequence": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Position in the append-only order. Strictly increasing by 1."
+        },
+        "date": {
+          "type": "string",
+          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+          "description": "The acceptance date. Non-decreasing across entries."
+        },
+        "kind": {
+          "type": "string",
+          "enum": ["release", "amendment"],
+          "description": "release: a change to the repository. amendment: a reviewed correction to an earlier entry's meaning. An amendment is the ONLY entry kind permitted to carry change items that map to no changed path in its own commit range."
+        },
+        "amends": {
+          "type": "string",
+          "pattern": "^RL-[0-9]{4}$",
+          "description": "Required on kind: amendment; forbidden on kind: release. The earlier entry this corrects. The earlier entry's bytes are not touched."
+        },
+        "amendment_reason": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Required on kind: amendment. Why the earlier entry was wrong or incomplete."
+        },
+        "surface_version": {
+          "description": "The supported-surface version this entry accompanies, or null for a same-surface change. A surface_version change owes exactly one entry with that version.",
+          "oneOf": [
+            { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+            { "type": "null" }
+          ]
+        },
+        "changelog_section": {
+          "type": "string",
+          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(\\+agent\\.[0-9]+)?$",
+          "description": "The exact CHANGELOG.md section identifier this entry links to, as it appears in the heading '## [<id>] - <date>'. A surface release uses the bare version. A same-surface change uses '<current-version>+agent.<n>', which sorts at the same version and never claims a release that did not happen. Exactly one section may carry a given identifier."
+        },
+        "changelog_sha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "SHA-256 over the exact UTF-8 bytes of the linked changelog section body, heading line included, trailing whitespace trimmed. A body edit without a hash update fails the correspondence gate."
+        },
+        "agent_impact": {
+          "type": "string",
+          "minLength": 1,
+          "description": "What a downstream agent must do differently, in plain language. 'None' is a valid assertion but must be written, not omitted."
+        },
+        "compatibility": {
+          "type": "string",
+          "enum": ["compatible", "additive", "breaking"],
+          "description": "compatible: no consumer change. additive: new surface a consumer may adopt. breaking: an existing consumer stops working without action."
+        },
+        "migration": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The exact operator or consumer action, or the literal string 'none'. A breaking entry may not say 'none'."
+        },
+        "changes": {
+          "type": "array",
+          "minItems": 1,
+          "description": "One item per agent-relevant semantic change. Change identity is (class, path, surface_entry) and must be unique within this entry; later releases may record a new change to the same path.",
+          "items": { "$ref": "#/$defs/change" }
+        },
+        "entry_sha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "SHA-256 over the canonical JSON of this entry with entry_sha256 removed. Makes an in-place edit of a historical entry detectable even in a squashed history."
+        },
+        "introducing_commit": false,
+        "containing_commit": false
+      }
+    },
+    "change": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["class", "path", "surface_entry", "summary"],
+      "properties": {
+        "class": {
+          "type": "string",
+          "enum": [
+            "schema",
+            "hashed_surface",
+            "named_surface",
+            "cli_surface",
+            "skill",
+            "package_export",
+            "compatibility_policy",
+            "documentation",
+            "workflow",
+            "generated_runtime"
+          ],
+          "description": "The semantic class, defined once in contracts/agent-relevant-change-policy.v1.json. The enum here is checked against that file."
+        },
+        "path": {
+          "description": "The repository-relative path this change covers, or null when the class has no single path (a CLI flag, for example). A non-null path must classify to this item's class under the change policy.",
+          "oneOf": [
+            { "type": "string", "minLength": 1 },
+            { "type": "null" }
+          ]
+        },
+        "surface_entry": {
+          "description": "The contracts/supported-surface.json entry this change affects (a hashed path, a named path, a cli_commands name, a package_exports subpath, or a bin name), or null when the change touches no supported entry.",
+          "oneOf": [
+            { "type": "string", "minLength": 1 },
+            { "type": "null" }
+          ]
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1,
+          "description": "One sentence naming what changed, written for a consumer, not for the author."
+        }
+      }
+    }
+  }
+}