@sentropic/track 0.12.0 → 0.13.0

package/dist/ingest/seam-schema.d.ts

@@ -0,0 +1,447 @@
+/** Semver of the seam v0 schema artifact itself (the contract-snapshot version, distinct from the
+ *  INGEST/READ contract versions it references). Bumped MINOR for additive schema growth. */
+export declare const SEAM_V0_SCHEMA_VERSION = "1.0.0";
+/** The frozen v0 seam JSON-Schema (Draft 2020-12) — a REAL envelope schema with a kind dispatch (validatable
+ *  by a standard validator). Pinned by `seam-schema.test.ts` (the snapshot gate + the WORK_EVENT_SCHEMA
+ *  wire-parity drift-gate). */
+export declare const SEAM_V0_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://sentropic.dev/schema/harness-track-seam/v0";
+    readonly title: "harness↔track seam v0";
+    readonly description: "The frozen v0 evidence seam: the WorkEvent envelope (the ROOT schema) with a kind-driven payload dispatch, the three seam payloads (scope.verification, acceptance.run, acceptance.link) + the harness-internal per-check VerificationRun the adapter fans out from. The harness EMITS these; track INGESTS them. Neither imports the other runtime.";
+    readonly version: "1.0.0";
+    readonly ingestContractVersion: "1.1.0";
+    readonly readContractVersion: "1.8.0";
+    readonly type: "object";
+    readonly required: readonly ["v", "kind", "payload"];
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly v: {
+            readonly const: 1;
+            readonly description: "Contract major. Unknown major ⇒ fail-closed reject.";
+        };
+        readonly kind: {
+            readonly enum: readonly ["scope.verification", "acceptance.run", "acceptance.link"];
+        };
+        readonly payload: {
+            readonly type: "object";
+            readonly description: "Per-kind shape enforced by the allOf/if-then dispatch below (NOT a bare {type:object}).";
+        };
+        readonly clientToken: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 256;
+            readonly description: "Delivery idempotency key, unique per emitted op. Grammar: verification-run:{runId}:{targetKind}:{targetId} (scope/acceptance branch) and …:acceptance:{evidenceId}:link:{criterionId} (per-link). Harness HASHES any component past the 256-char cap. Race-safe under track (workspace, clientToken) under-lock idempotency.";
+        };
+    };
+    readonly allOf: readonly [{
+        readonly if: {
+            readonly properties: {
+                readonly kind: {
+                    readonly const: "scope.verification";
+                };
+            };
+            readonly required: readonly ["kind"];
+        };
+        readonly then: {
+            readonly properties: {
+                readonly payload: {
+                    readonly $ref: "#/$defs/ScopeVerificationPayload";
+                };
+            };
+        };
+    }, {
+        readonly if: {
+            readonly properties: {
+                readonly kind: {
+                    readonly const: "acceptance.run";
+                };
+            };
+            readonly required: readonly ["kind"];
+        };
+        readonly then: {
+            readonly properties: {
+                readonly payload: {
+                    readonly $ref: "#/$defs/AcceptanceRunPayload";
+                };
+            };
+        };
+    }, {
+        readonly if: {
+            readonly properties: {
+                readonly kind: {
+                    readonly const: "acceptance.link";
+                };
+            };
+            readonly required: readonly ["kind"];
+        };
+        readonly then: {
+            readonly properties: {
+                readonly payload: {
+                    readonly $ref: "#/$defs/AcceptanceLinkPayload";
+                };
+            };
+        };
+    }];
+    readonly $defs: {
+        readonly VerificationCategory: {
+            readonly description: "Reserved enum (security pre-reserved). Validates/defaults the acceptance kind at the adapter; NOT a track wire payload field, NOT routing (routing is target-driven).";
+            readonly enum: readonly ["scope", "acceptance", "security"];
+        };
+        readonly Verdict: {
+            readonly description: "The adapter-DERIVED tri-state path verdict (NEVER the harness check result). Derived from violations+severity: any blocking ⇒ violation; advisory-only ⇒ conditional; none ⇒ clean.";
+            readonly enum: readonly ["clean", "violation", "conditional"];
+        };
+        readonly Severity: {
+            readonly description: "Per-violation severity (harness guarantees it is always set). Drives the Verdict derivation predicate.";
+            readonly enum: readonly ["advisory", "blocking"];
+        };
+        readonly EvidenceKind: {
+            readonly enum: readonly ["unit", "integration", "e2e", "manual"];
+        };
+        readonly RunResult: {
+            readonly description: "Binary (no conditional home for acceptance).";
+            readonly enum: readonly ["pass", "fail"];
+        };
+        readonly Violation: {
+            readonly description: "A scope.verification.violations[] entry is the deterministic JSON.stringify({severity,code,path,message}) projection (S2) — a display/index string track records VERBATIM and NEVER parses. The canonical detail is the full VerificationRun behind artifactLocator.";
+            readonly type: "object";
+            readonly required: readonly ["severity", "code", "path", "message"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly severity: {
+                    readonly $ref: "#/$defs/Severity";
+                };
+                readonly code: {
+                    readonly type: "string";
+                };
+                readonly path: {
+                    readonly type: "string";
+                };
+                readonly message: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly VerificationCheck: {
+            readonly description: "One check within a VerificationRun (per-CHECK target — one harness verify aggregates N checks across WPs/criteria). ≥1 target REQUIRED; a target-less check FAILS CLOSED at the adapter (never emitted).";
+            readonly type: "object";
+            readonly required: readonly ["category", "result", "target"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly category: {
+                    readonly $ref: "#/$defs/VerificationCategory";
+                };
+                readonly result: {
+                    readonly $ref: "#/$defs/RunResult";
+                };
+                readonly violations: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/Violation";
+                    };
+                };
+                readonly target: {
+                    readonly type: "object";
+                    readonly description: "At least ONE of scope|acceptance REQUIRED (both empty ⇒ FAIL-CLOSED, never auto-itemized/glob-routed). Routing is TARGET-driven, never category/path/branch.";
+                    readonly minProperties: 1;
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly scope: {
+                            readonly type: "object";
+                            readonly required: readonly ["wpRef"];
+                            readonly additionalProperties: false;
+                            readonly properties: {
+                                readonly wpRef: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                    readonly description: "The WP/spec-phase ItemId the verdict pertains to (the scope-target routing key = track scope.verification.wpRef).";
+                                };
+                            };
+                        };
+                        readonly acceptance: {
+                            readonly type: "object";
+                            readonly required: readonly ["evidenceId", "kind"];
+                            readonly additionalProperties: false;
+                            readonly properties: {
+                                readonly evidenceId: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                    readonly description: "A DETERMINISTIC, caller-supplied evidence key (M2=B). The adapter sets it on acceptance.link AND references it on acceptance.run — single-phase, replayable (no two-phase read).";
+                                };
+                                readonly kind: {
+                                    readonly $ref: "#/$defs/EvidenceKind";
+                                };
+                                readonly criterionIds: {
+                                    readonly type: "array";
+                                    readonly items: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        readonly VerificationRun: {
+            readonly description: "The harness-internal per-check artifact behind artifactLocator (published for contract-snapshot; NOT a track kind — track ingests its target-routed projection). runId here is the per-emitted-verdict PROJECTION id (globally unique per emitted verdict — the M1 invariant), distinct from any physical run id inside the full artifact.";
+            readonly type: "object";
+            readonly required: readonly ["runId", "runner", "commit", "artifactLocator", "checks"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly runId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly runner: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly commit: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly env: {
+                    readonly type: "string";
+                };
+                readonly artifactLocator: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly description: "Immutable, producer-owned locator string to THIS full JSON (S2). OPAQUE to track (records, never fetches/resolves/owns). Immutability is a PRODUCER guarantee track records, never verifies.";
+                };
+                readonly checks: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/VerificationCheck";
+                    };
+                };
+            };
+        };
+        readonly ScopeVerificationPayload: {
+            readonly description: "The scope-target projection (one per target.scope branch). 7 shipped fields + the NEW additive optional artifactLocator (S2). Non-empty strings carry minLength:1 to match the runtime asserter (assertVerificationRun).";
+            readonly type: "object";
+            readonly required: readonly ["runId", "runner", "commit", "verdict"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly runId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly description: "The per-emitted-verdict projection id (M1 invariant: globally unique per emitted verdict).";
+                };
+                readonly runner: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly commit: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly verdict: {
+                    readonly $ref: "#/$defs/Verdict";
+                };
+                readonly env: {
+                    readonly type: "string";
+                };
+                readonly wpRef: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly description: "IS target.scope.wpRef. Absent ⇒ a workspace-scoped synthetic-aggregate run (kept OPTIONAL — fail-closed-no-target is enforced ADAPTER-side, OQ-2). Non-empty when present (assertVerificationRun).";
+                };
+                readonly violations: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "The deterministic-stringify Violation projection (S2). Recorded VERBATIM; track never parses/re-matches.";
+                };
+                readonly artifactLocator: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly description: "NEW additive optional (S2). OPAQUE to track. Non-empty when present; dropped-when-absent (hash-minimal, old logs byte-identical).";
+                };
+            };
+        };
+        readonly AcceptanceRunPayload: {
+            readonly description: "The acceptance-target run (one per target.acceptance branch). UNCHANGED by the freeze. result = the check pass/result DIRECTLY (S3), never the derived verdict.";
+            readonly type: "object";
+            readonly required: readonly ["evidenceId", "commit", "env", "runner", "result"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly evidenceId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly description: "References the deterministic caller-supplied key minted on acceptance.link (M2=B) — so recordRun resolves without a two-phase read.";
+                };
+                readonly commit: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly env: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly runner: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly result: {
+                    readonly $ref: "#/$defs/RunResult";
+                };
+            };
+        };
+        readonly AcceptanceLinkPayload: {
+            readonly description: "One per criterionId under an acceptance branch. NEW additive optional evidenceId (M2=B): caller-supplied deterministic key; absent ⇒ shipped server-mint (back-compat).";
+            readonly type: "object";
+            readonly required: readonly ["criterionId", "kind", "locator"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly criterionId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly kind: {
+                    readonly $ref: "#/$defs/EvidenceKind";
+                };
+                readonly locator: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly evidenceId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly description: "NEW additive optional (M2=B). The deterministic caller-supplied evidence key the harness sets so acceptance.run can reference it. Non-empty when present (linkEvidence); absent ⇒ track mints server-side (shipped behavior).";
+                };
+            };
+        };
+        readonly WorkEventEnvelope: {
+            readonly description: "The v0 wire envelope (SHIPPED, unchanged by the freeze) — published as a $def for reference; the ROOT schema IS this envelope plus the kind dispatch. Any other top-level key is rejected fail-closed (WHO/trust come from the ingest CONTEXT). The harness emits a SEQUENCE of these (one per check-target branch), never a single VerificationRun envelope.";
+            readonly type: "object";
+            readonly required: readonly ["v", "kind", "payload"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly v: {
+                    readonly const: 1;
+                    readonly description: "Contract major. Unknown major ⇒ fail-closed reject.";
+                };
+                readonly kind: {
+                    readonly enum: readonly ["scope.verification", "acceptance.run", "acceptance.link"];
+                };
+                readonly payload: {
+                    readonly type: "object";
+                };
+                readonly clientToken: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 256;
+                    readonly description: "Delivery idempotency key, unique per emitted op. Grammar: verification-run:{runId}:{targetKind}:{targetId} (scope/acceptance branch) and …:acceptance:{evidenceId}:link:{criterionId} (per-link). Harness HASHES any component past the 256-char cap. Race-safe under track (workspace, clientToken) under-lock idempotency.";
+                };
+            };
+        };
+    };
+};
+/**
+ * The per-kind seam payload subschemas, addressed by kind (the dispatch targets). Exposed so the
+ * wire-parity drift-gate (`seam-schema.test.ts`) can derive {required, properties} per kind and assert
+ * equality with `WORK_EVENT_SCHEMA` — the canonical mapping from a WorkEventKind to its payload $def.
+ */
+export declare const SEAM_V0_PAYLOAD_DEFS: {
+    readonly 'scope.verification': {
+        readonly description: "The scope-target projection (one per target.scope branch). 7 shipped fields + the NEW additive optional artifactLocator (S2). Non-empty strings carry minLength:1 to match the runtime asserter (assertVerificationRun).";
+        readonly type: "object";
+        readonly required: readonly ["runId", "runner", "commit", "verdict"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly runId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "The per-emitted-verdict projection id (M1 invariant: globally unique per emitted verdict).";
+            };
+            readonly runner: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+            readonly commit: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+            readonly verdict: {
+                readonly $ref: "#/$defs/Verdict";
+            };
+            readonly env: {
+                readonly type: "string";
+            };
+            readonly wpRef: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "IS target.scope.wpRef. Absent ⇒ a workspace-scoped synthetic-aggregate run (kept OPTIONAL — fail-closed-no-target is enforced ADAPTER-side, OQ-2). Non-empty when present (assertVerificationRun).";
+            };
+            readonly violations: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "The deterministic-stringify Violation projection (S2). Recorded VERBATIM; track never parses/re-matches.";
+            };
+            readonly artifactLocator: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "NEW additive optional (S2). OPAQUE to track. Non-empty when present; dropped-when-absent (hash-minimal, old logs byte-identical).";
+            };
+        };
+    };
+    readonly 'acceptance.run': {
+        readonly description: "The acceptance-target run (one per target.acceptance branch). UNCHANGED by the freeze. result = the check pass/result DIRECTLY (S3), never the derived verdict.";
+        readonly type: "object";
+        readonly required: readonly ["evidenceId", "commit", "env", "runner", "result"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly evidenceId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "References the deterministic caller-supplied key minted on acceptance.link (M2=B) — so recordRun resolves without a two-phase read.";
+            };
+            readonly commit: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+            readonly env: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+            readonly runner: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+            readonly result: {
+                readonly $ref: "#/$defs/RunResult";
+            };
+        };
+    };
+    readonly 'acceptance.link': {
+        readonly description: "One per criterionId under an acceptance branch. NEW additive optional evidenceId (M2=B): caller-supplied deterministic key; absent ⇒ shipped server-mint (back-compat).";
+        readonly type: "object";
+        readonly required: readonly ["criterionId", "kind", "locator"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly criterionId: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+            readonly kind: {
+                readonly $ref: "#/$defs/EvidenceKind";
+            };
+            readonly locator: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+            readonly evidenceId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "NEW additive optional (M2=B). The deterministic caller-supplied evidence key the harness sets so acceptance.run can reference it. Non-empty when present (linkEvidence); absent ⇒ track mints server-side (shipped behavior).";
+            };
+        };
+    };
+};
+//# sourceMappingURL=seam-schema.d.ts.map

package/dist/ingest/seam-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seam-schema.d.ts","sourceRoot":"","sources":["../../src/ingest/seam-schema.ts"],"names":[],"mappings":"AAuBA;6FAC6F;AAC7F,eAAO,MAAM,sBAAsB,UAAU,CAAA;AAE7C;;+BAE+B;AAC/B,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+OjB,CAAA;AAEV;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAIvB,CAAA"}