@nextcommerce/campaigns-os 1.33.0

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

@@ -0,0 +1,343 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nextcommerce.com/schemas/campaigns-os-run-record.v0.schema.json",
+  "title": "Campaigns OS Run Record v0",
+  "description": "A per-run manifest for one Campaigns OS run. Keyed by one canonical run_id. References source artifacts by {path, schema_version, sha256, material_fingerprint} where available and carries normalized observation arrays — it does NOT re-embed full artifact bodies (so it survives upstream schema drift). Capture is always local; consent gates remit only. See docs/workflow-findings-sidecar.md (Run Telemetry).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "run_id",
+    "package_version",
+    "command",
+    "argv_shape",
+    "created_at",
+    "consent_state",
+    "remit_attempted"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "campaigns-os-run-record/v0"
+    },
+    "run_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The single canonical run identity, minted at the run boundary. Also the idempotency key for remit — the endpoint upserts on run_id so retries/reruns never double-count."
+    },
+    "package_version": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Version of the @nextcommerce/campaigns-os package that produced this record."
+    },
+    "surface_version": {
+      "type": ["string", "null"],
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "supported-surface version (contracts/supported-surface.json) of the toolkit that produced this record — the version signal consumers can segment on, since package_version has not moved off 0.1.0-alpha.0. Null when the manifest is unreadable."
+    },
+    "toolkit_commit": {
+      "type": ["string", "null"],
+      "pattern": "^[0-9a-f]{7,40}$",
+      "description": "Git commit the toolkit was installed from: package.json gitHead (stamped on git-dependency installs), else the checkout HEAD. Null when neither is available."
+    },
+    "command": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The command that ran, e.g. \"run-record\", \"start\", \"qa run\"."
+    },
+    "argv_shape": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "The flag NAMES present on the command line (e.g. \"--packet\", \"--write\"), never their raw values. Shape only — minimization."
+    },
+    "created_at": {
+      "type": "string",
+      "minLength": 1,
+      "description": "ISO 8601 timestamp the record was assembled."
+    },
+    "consent_state": {
+      "type": "string",
+      "enum": ["on", "off"],
+      "description": "Resolved telemetry consent at capture time. Gates remit only; capture is always local."
+    },
+    "consent_source": {
+      "type": ["string", "null"],
+      "enum": ["env", "file", "default", null],
+      "description": "Where consent_state was resolved from. \"default\" means unknown/non-interactive — fails closed to off."
+    },
+    "remit_attempted": {
+      "type": "boolean",
+      "description": "Whether a remit POST was attempted for this run."
+    },
+    "remit_state": {
+      "type": "string",
+      "enum": ["skipped", "pending", "ok", "failed"],
+      "description": "Crash-safe lifecycle state for remit. pending means local capture completed before a consented remit finished; skipped means no remit was attempted."
+    },
+    "remit_ok": {
+      "type": ["boolean", "null"],
+      "description": "Whether the remit POST succeeded. null when no attempt was made."
+    },
+    "remit_error": {
+      "type": ["string", "null"],
+      "description": "Error message from a failed remit, so a dropped send is visible and not silent. null on success or no attempt."
+    },
+    "remit_endpoint": {
+      "type": ["string", "null"],
+      "pattern": "^/",
+      "description": "Endpoint path the run was remitted to, e.g. \"/api/runs\". null when no attempt was made."
+    },
+    "remit_result": {
+      "type": ["string", "null"],
+      "enum": ["stored", "already_stored", "ok_unparsed_ack", "refused", "transport_error", null],
+      "description": "What the receiver answered, classified: stored (parsed 2xx), already_stored (409 — the receiver already holds this run_id), ok_unparsed_ack (2xx with a non-JSON body), refused (other non-2xx), transport_error (no answer). null when no attempt was made. The copy the receiver stores carries stored, by construction."
+    },
+    "remit_base_kind": {
+      "type": ["string", "null"],
+      "enum": ["canonical", "loopback", "proxy", null],
+      "description": "The remit base the send resolved to, as a kind rather than a host: canonical (the default endpoint), loopback (a receiver on localhost), or proxy (any other --proxy-base). null when no attempt was made."
+    },
+    "qa_verdict_publish": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "description": "The QA verdict publish outcome recorded for this run (surface 1.33.0): which verdict was posted to the QA portal, by which command, and what the receiver answered, classified into the same vocabulary as remit_result. Absent on records written before the field existed and on runs that produced no verdict. A later `qa publish` of the same verdict reads state ok as already published and refuses without --republish; a stored outcome is never downgraded by a later failed send.",
+      "required": ["verdict_run_id", "publisher", "attempted", "state"],
+      "properties": {
+        "verdict_run_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The QA verdict's own run_id (the verdict file name under qa-output/), which is the publish idempotency key. Distinct from this record's run_id."
+        },
+        "publisher": {
+          "type": "string",
+          "enum": ["qa run", "qa publish"],
+          "description": "The command that made this send: the run that produced the verdict, or a later qa publish of the stored copy."
+        },
+        "attempted": {
+          "type": "boolean",
+          "description": "Whether a publish POST was attempted for this verdict."
+        },
+        "ok": {
+          "type": ["boolean", "null"],
+          "description": "Whether the publish counts as landed (stored, already_stored or ok_unparsed_ack). null when no attempt was made."
+        },
+        "error": {
+          "type": ["string", "null"],
+          "description": "Error message from a failed or anomalous publish. null on a clean success or no attempt."
+        },
+        "endpoint": {
+          "type": ["string", "null"],
+          "pattern": "^/",
+          "description": "Endpoint path the verdict was posted to, e.g. \"/api/qa/verdicts\". null when no attempt was made."
+        },
+        "state": {
+          "type": "string",
+          "enum": ["skipped", "ok", "failed"],
+          "description": "skipped: publish was off for the run (no send). ok: the receiver's answer counts as stored. failed: refused or never answered."
+        },
+        "result": {
+          "type": ["string", "null"],
+          "enum": ["stored", "already_stored", "ok_unparsed_ack", "refused", "transport_error", null],
+          "description": "What the receiver answered, classified as remit_result is. null when no attempt was made."
+        },
+        "base_kind": {
+          "type": ["string", "null"],
+          "enum": ["canonical", "loopback", "proxy", null],
+          "description": "The proxy base the send resolved to, as a kind rather than a host. null when no attempt was made."
+        },
+        "published_at": {
+          "type": ["string", "null"],
+          "description": "ISO 8601 timestamp of the send that landed. null when the publish was skipped or failed."
+        }
+      }
+    },
+    "identity": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Best-effort run identity — the join keys that make telemetry useful. Missing identity never blocks capture.",
+      "properties": {
+        "map_id": { "type": ["string", "null"] },
+        "campaign_slug": { "type": ["string", "null"] },
+        "template_family": { "type": ["string", "null"] },
+        "entry_point_shape": {
+          "type": ["string", "null"],
+          "description": "How the run was entered, e.g. \"packet\", \"spec\", \"map-id\". Shape, not a raw path or id."
+        }
+      }
+    },
+    "artifacts": {
+      "type": "array",
+      "description": "References to this run's source artifacts. References, not copies — this is what survives upstream schema drift. schema_version/sha256/material_fingerprint are nullable for artifacts that are not on disk or whose hash/fingerprint could not be read.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "path"],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": [
+              "build_packet",
+              "build_brief",
+              "design_source_package",
+              "build_context",
+              "assembly_report",
+              "page_kit_build_summary",
+              "qa_verdict",
+              "findings_journal"
+            ]
+          },
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Relativized-or-hashed path. Never an absolute contributor filesystem path."
+          },
+          "schema_version": { "type": ["string", "null"] },
+          "sha256": { "type": ["string", "null"] },
+          "material_fingerprint": { "type": ["string", "null"] }
+        }
+      }
+    },
+    "observations": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Normalized observation arrays — the extracted structural signal. Codes/IDs/dispositions only, never raw artifact bodies.",
+      "properties": {
+        "doctor": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "status": { "type": ["string", "null"] },
+            "error_codes": { "type": "array", "items": { "type": "string" } },
+            "warning_codes": { "type": "array", "items": { "type": "string" } },
+            "ready_count": { "type": ["integer", "null"] }
+          }
+        },
+        "spec_validation_rule_ids": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "ruleId of every spec.validation violation that fired."
+        },
+        "adapter_decisions": {
+          "type": ["object", "null"],
+          "description": "Normalized adapter decision values (strategy enums), not source files."
+        },
+        "qa": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "disposition": { "type": ["string", "null"] },
+            "gap_classes": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Distinct assertion families that produced a QA exception (e.g. \"funnel-flow\", \"meta-tags\")."
+            }
+          }
+        },
+        "finding_ids": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "IDs of this run's Workflow Findings (the per-run findings snapshot, by reference). The journal is the single writer; this is an exact snapshot when findings carry run_id."
+        },
+        "findings_journal": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Integrity metadata for the findings journal snapshot. Present when malformed JSONL lines were skipped so the snapshot is visibly incomplete.",
+          "properties": {
+            "malformed_count": { "type": "integer" },
+            "malformed_lines": {
+              "type": "array",
+              "items": { "type": "integer" }
+            }
+          }
+        }
+      }
+    },
+    "surfaces": {
+      "type": "array",
+      "description": "Improvement surfaces this run's signal should inform. A list, not an enum — real signal is rarely one surface.",
+      "items": {
+        "type": "string",
+        "enum": [
+          "skill",
+          "cli",
+          "template",
+          "design-source",
+          "docs",
+          "spec-rule",
+          "platform"
+        ]
+      }
+    },
+    "primary_surface": {
+      "type": ["string", "null"],
+      "enum": [
+        "skill",
+        "cli",
+        "template",
+        "design-source",
+        "docs",
+        "spec-rule",
+        "platform",
+        null
+      ],
+      "description": "Optional best single-guess surface."
+    },
+    "surface_confidence": {
+      "type": ["string", "null"],
+      "description": "Optional free-form confidence hint for primary_surface, e.g. \"low\"."
+    },
+    "agent_usage": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional host-supplied agent runtime usage. Campaigns OS does not infer these values; outer runners provide them when available.",
+      "properties": {
+        "input_tokens": { "type": "integer", "minimum": 0 },
+        "output_tokens": { "type": "integer", "minimum": 0 },
+        "tool_output_tokens": { "type": "integer", "minimum": 0 },
+        "total_tokens": { "type": "integer", "minimum": 0 },
+        "elapsed_ms": { "type": "integer", "minimum": 0 },
+        "model": { "type": "string" },
+        "source": { "type": "string" }
+      }
+    },
+    "lifecycle": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "description": "Optional command-lifecycle signal for this run, correlated by run_id. See per-field descriptions.",
+      "properties": {
+        "run_id": { "type": ["string", "null"] },
+        "command": { "type": "string" },
+        "argv_shape": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Flag names present, never their values."
+        },
+        "exit_status": { "type": ["integer", "null"] },
+        "started_at": { "type": ["string", "null"] },
+        "completed_at": { "type": ["string", "null"] },
+        "duration_ms": { "type": ["number", "null"] },
+        "wall_clock_duration_ms": {
+          "type": ["number", "null"],
+          "description": "Elapsed wall-clock span from the earliest command start to the latest command completion. Kept separate from duration_ms, which sums active command execution time."
+        },
+        "stages": {
+          "type": "array",
+          "description": "Per-stage timings, populated by run-record aggregating the lifecycle journal for this run_id. One stage per command invocation (name = command), or `command:phase` when a command marked its own sub-phases.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name"],
+            "properties": {
+              "name": { "type": "string" },
+              "duration_ms": { "type": ["number", "null"] },
+              "exit_status": { "type": ["integer", "null"] }
+            }
+          }
+        },
+        "repair_loop_count": {
+          "type": ["integer", "null"],
+          "description": "Re-runs of any command within the run (a re-run is a repair loop: doctor -> fix -> doctor). 0 when each command ran once."
+        }
+      }
+    }
+  }
+}