@bli-cockpit/telemetry-core 0.1.14 → 0.1.16

package/dist/decision-event-id.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Fold a label to its comparison form.
+ *
+ * Case and surrounding whitespace are not identity — `Brandon`, `brandon` and
+ * ` brandon ` are one actor, and treating them as three would defeat the whole
+ * point of clustering. Nothing else is touched. In particular no punctuation is
+ * stripped and no prefix is trimmed, because every such rule is a guess about
+ * what two labels have in common, and guessing is exactly what the person
+ * resolver refuses to do. This is the same case-fold-then-compare the resolver
+ * itself uses, kept deliberately as dumb as that one.
+ */
+export declare function normalizeActorLabel(rawLabel: string): string;
+/**
+ * The stable identity of an actor nobody can name yet.
+ *
+ * Derived from the label alone, so every event bearing that label — across
+ * files, across sources, across backfill runs, months apart — clusters under
+ * one id. That is what lets a person later say "this one is Brandon" once and
+ * have it mean something for all of them.
+ *
+ * The label kind is deliberately NOT part of the input. The same human appears
+ * as a queue field in one artifact and a brief variable in another; folding the
+ * kind in would split one stranger into several and put the corpus right back
+ * where it started.
+ */
+export declare function unresolvedActorId(rawLabel: string): string;
+export interface DecisionEventIdInput {
+    captureSource: string;
+    /**
+     * Hash of exactly the bytes that make up this one decision; null for a live
+     * hook firing, which has no artifact at all.
+     *
+     * "This one decision" and not "the file it arrived in", which is the whole
+     * point. A verdict JSON holds one decision, so its record is the file and the
+     * two hashes coincide. `merge-log.jsonl` holds thousands and gains another
+     * every time somebody merges, so its record is the single line — hashing the
+     * file there would change every id in it on the next append, and a re-import
+     * would write a second copy of the ledger instead of updating the rows it
+     * already has.
+     *
+     * Which snapshot of which file the record came out of is still worth knowing;
+     * it is kept as `source_artifact_hash_sha256`, beside `source_line_number`, as
+     * provenance. Neither is an identity input. Conflating the two jobs in one
+     * field is what made a growing ledger un-re-importable.
+     */
+    sourceRecordHashSha256: string | null;
+    kind: string;
+    /**
+     * Only for a live firing, which has no artifact to hash and no line to point
+     * at. Two hook firings a second apart are two events, and without this they
+     * would collapse into one.
+     */
+    occurredAt?: string | null;
+    /** Also live-firing only: same hook, same instant, different subject. */
+    subjectDiscriminator?: string | null;
+}
+/**
+ * The id of one decision event.
+ *
+ * Three consequences worth stating. Re-running the backfill is idempotent,
+ * because the same record always yields the same id no matter how much the file
+ * around it has grown or how far down it has been pushed. An *edited* record
+ * produces a new id rather than mutating an old one, which keeps the store
+ * append-only in the same way jarvis_corrections is — history is added to, never
+ * rewritten. And two byte-identical records collapse onto one row, which is the
+ * intended reading: in a ledger, identical bytes mean a hook wrote the same
+ * decision twice. If that is ever false the ledger format is underspecified, and
+ * the fix belongs there rather than in a tiebreaker here.
+ *
+ * The line number is deliberately absent. It is the one part of a record's
+ * position that a rotation or a compaction can change without the decision
+ * itself changing at all, and an id that moves when a file is renumbered is
+ * worse than a duplicate: it silently lands on some other decision's row.
+ */
+export declare function decisionEventId(input: DecisionEventIdInput): string;

package/dist/decision-event-id.js

@@ -0,0 +1,79 @@
+// BLI-2425: the two ids a decision event depends on, derived the same way by
+// every writer.
+//
+// Both are deterministic on purpose, and for the same reason: the historical
+// backfill will be re-run. A hook that fires twice, a backfill script that dies
+// halfway and starts over, a corrected parser replayed against the same files —
+// all of those must land on the same rows rather than a second copy. Determinism
+// is what makes "ingest is idempotent" a property of the data instead of a
+// promise about the code.
+//
+// This lives beside the schema rather than in each writer because two writers
+// deriving an id two ways is the same bug as two resolvers deciding who someone
+// is: it produces two answers to a question that has one.
+import { createHash } from "node:crypto";
+/** How much of the digest we keep. Collision risk at 32 hex is not a concern at
+ *  a corpus of thousands, and short ids stay readable in a URL and a log line. */
+const ID_HEX_LENGTH = 32;
+function sha256Hex(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+/**
+ * Fold a label to its comparison form.
+ *
+ * Case and surrounding whitespace are not identity — `Brandon`, `brandon` and
+ * ` brandon ` are one actor, and treating them as three would defeat the whole
+ * point of clustering. Nothing else is touched. In particular no punctuation is
+ * stripped and no prefix is trimmed, because every such rule is a guess about
+ * what two labels have in common, and guessing is exactly what the person
+ * resolver refuses to do. This is the same case-fold-then-compare the resolver
+ * itself uses, kept deliberately as dumb as that one.
+ */
+export function normalizeActorLabel(rawLabel) {
+    return rawLabel.trim().toLowerCase();
+}
+/**
+ * The stable identity of an actor nobody can name yet.
+ *
+ * Derived from the label alone, so every event bearing that label — across
+ * files, across sources, across backfill runs, months apart — clusters under
+ * one id. That is what lets a person later say "this one is Brandon" once and
+ * have it mean something for all of them.
+ *
+ * The label kind is deliberately NOT part of the input. The same human appears
+ * as a queue field in one artifact and a brief variable in another; folding the
+ * kind in would split one stranger into several and put the corpus right back
+ * where it started.
+ */
+export function unresolvedActorId(rawLabel) {
+    const normalized = normalizeActorLabel(rawLabel);
+    return `ua_${sha256Hex(`decision-actor:${normalized}`).slice(0, ID_HEX_LENGTH)}`;
+}
+/**
+ * The id of one decision event.
+ *
+ * Three consequences worth stating. Re-running the backfill is idempotent,
+ * because the same record always yields the same id no matter how much the file
+ * around it has grown or how far down it has been pushed. An *edited* record
+ * produces a new id rather than mutating an old one, which keeps the store
+ * append-only in the same way jarvis_corrections is — history is added to, never
+ * rewritten. And two byte-identical records collapse onto one row, which is the
+ * intended reading: in a ledger, identical bytes mean a hook wrote the same
+ * decision twice. If that is ever false the ledger format is underspecified, and
+ * the fix belongs there rather than in a tiebreaker here.
+ *
+ * The line number is deliberately absent. It is the one part of a record's
+ * position that a rotation or a compaction can change without the decision
+ * itself changing at all, and an id that moves when a file is renumbered is
+ * worse than a duplicate: it silently lands on some other decision's row.
+ */
+export function decisionEventId(input) {
+    const parts = [
+        input.captureSource,
+        input.sourceRecordHashSha256 ?? "",
+        input.kind,
+        input.occurredAt ?? "",
+        input.subjectDiscriminator ?? "",
+    ];
+    return `de_${sha256Hex(parts.join("|")).slice(0, ID_HEX_LENGTH)}`;
+}

package/dist/decision-event.d.ts

@@ -0,0 +1,612 @@
+import { z } from "zod";
+export declare const DECISION_EVENT_ENVELOPE_VERSION = "decision-event.v1";
+/** A git commit sha. Sha256Schema is 64 hex and does not fit a 40-hex commit. */
+export declare const CommitShaSchema: z.ZodString;
+export declare const DecisionEventKindSchema: z.ZodEnum<{
+    delegation_issued: "delegation_issued";
+    review_verdict: "review_verdict";
+    human_approval: "human_approval";
+    intervention: "intervention";
+    takeover: "takeover";
+    rule_fired: "rule_fired";
+}>;
+export type DecisionEventKind = z.infer<typeof DecisionEventKindSchema>;
+/**
+ * Which artifact this event was read out of.
+ *
+ * Deliberately its own enum rather than a member added to CaptureSourceSchema.
+ * That enum describes what a collector watched on a coding machine; these are
+ * files a manager's harness wrote as a side effect of managing. Sharing the
+ * enum would imply a shared envelope, and the whole reason this path exists is
+ * that decision records have no session, no work context and no capture
+ * provenance to fill.
+ */
+export declare const DecisionCaptureSourceSchema: z.ZodEnum<{
+    claude_state_verdict_json: "claude_state_verdict_json";
+    claude_state_queue_jsonl: "claude_state_queue_jsonl";
+    claude_state_worker_brief: "claude_state_worker_brief";
+    claude_state_retro_jsonl: "claude_state_retro_jsonl";
+    claude_state_bypass_log: "claude_state_bypass_log";
+    claude_state_merge_log: "claude_state_merge_log";
+    hook_runtime: "hook_runtime";
+}>;
+export type DecisionCaptureSource = z.infer<typeof DecisionCaptureSourceSchema>;
+/** Which field of the source artifact produced this label. */
+export declare const ActorLabelKindSchema: z.ZodEnum<{
+    email: "email";
+    github_login: "github_login";
+    linear_email: "linear_email";
+    linear_user_id: "linear_user_id";
+    reviewer_session: "reviewer_session";
+    hook_operator: "hook_operator";
+    queue_field: "queue_field";
+    brief_variable: "brief_variable";
+}>;
+export type ActorLabelKind = z.infer<typeof ActorLabelKindSchema>;
+/** Whether the thing that acted was a person or something a person ran. */
+export declare const ActorClassSchema: z.ZodEnum<{
+    human: "human";
+    agent: "agent";
+}>;
+export type ActorClass = z.infer<typeof ActorClassSchema>;
+/**
+ * What the resolver concluded. These are the resolver's own four outcomes, kept
+ * apart rather than collapsed to null, because "nobody was named" and "somebody
+ * was named and we do not know them" call for different follow-up.
+ */
+export declare const ActorResolutionSchema: z.ZodEnum<{
+    resolved: "resolved";
+    unknown_person: "unknown_person";
+    ambiguous: "ambiguous";
+    no_person_named: "no_person_named";
+}>;
+export type ActorResolution = z.infer<typeof ActorResolutionSchema>;
+/**
+ * Who acted — resolved to a person when we know them, and stably identified
+ * when we do not.
+ *
+ * The second half is the part worth reading. A backfill of ~2,400 historical
+ * decisions predates the person spine, so a large share of them name somebody
+ * the roster has never heard of. Collapsing all of those to one null makes the
+ * corpus useless: unresolved actor #1, #2 and #3 become indistinguishable and
+ * "who did what, and when" is unanswerable even in principle.
+ *
+ * So every distinct unresolved label gets `unresolved_actor_id`, derived
+ * deterministically from the normalized label (see `unresolvedActorId`). Events
+ * from the same label cluster under the same id forever. Later a human asserts
+ * "unresolved actor X is Brandon" and every event under that id resolves at
+ * once, retroactively, without a single event row being rewritten — the
+ * assertion lives in its own append-only alias table.
+ *
+ * That is not fuzzy matching sneaking back in. The ban is on the machine
+ * guessing; a human asserting an identity is the sanctioned escape hatch, and
+ * it is the same shape as jarvis_corrections, where the human outranks the
+ * pipeline and nothing is edited in place.
+ */
+export declare const ActorRefSchema: z.ZodObject<{
+    raw_label: z.ZodNullable<z.ZodString>;
+    label_kind: z.ZodNullable<z.ZodEnum<{
+        email: "email";
+        github_login: "github_login";
+        linear_email: "linear_email";
+        linear_user_id: "linear_user_id";
+        reviewer_session: "reviewer_session";
+        hook_operator: "hook_operator";
+        queue_field: "queue_field";
+        brief_variable: "brief_variable";
+    }>>;
+    actor_class: z.ZodEnum<{
+        human: "human";
+        agent: "agent";
+    }>;
+    resolution: z.ZodEnum<{
+        resolved: "resolved";
+        unknown_person: "unknown_person";
+        ambiguous: "ambiguous";
+        no_person_named: "no_person_named";
+    }>;
+    person_id: z.ZodNullable<z.ZodString>;
+    unresolved_actor_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type ActorRef = z.infer<typeof ActorRefSchema>;
+/**
+ * The thing decided upon. `repo` is stored canonically as `owner/name` because
+ * the source artifacts disagree — the same pull request appears as
+ * `bli-cockpit` in the queue and `veetesh-glitch/bli-cockpit` in the verdict.
+ * Normalizing is an exact rule, never a prefix guess.
+ */
+export declare const DecisionSubjectSchema: z.ZodObject<{
+    repo: z.ZodNullable<z.ZodString>;
+    branch: z.ZodNullable<z.ZodString>;
+    ticket_id: z.ZodNullable<z.ZodString>;
+    pull_request_number: z.ZodNullable<z.ZodNumber>;
+    head_sha: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type DecisionSubject = z.infer<typeof DecisionSubjectSchema>;
+/**
+ * Where to go to see the thing itself. Pointers, never content — the prose
+ * these point at is exactly what v1 refuses to carry.
+ */
+export declare const DecisionEvidencePointerSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        claude_state_path: "claude_state_path";
+        github_pull_request: "github_pull_request";
+        linear_issue: "linear_issue";
+        commit: "commit";
+        reviewer_session_id: "reviewer_session_id";
+    }>;
+    locator: z.ZodString;
+}, z.core.$strict>;
+export type DecisionEvidencePointer = z.infer<typeof DecisionEvidencePointerSchema>;
+export declare const DecisionOutcomeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"delegation_issued">;
+    eta_minutes: z.ZodNullable<z.ZodNumber>;
+    model: z.ZodNullable<z.ZodString>;
+    auto_merge_authorized: z.ZodBoolean;
+    blast_radius_tags: z.ZodArray<z.ZodString>;
+    depends_on: z.ZodArray<z.ZodString>;
+    acceptance_criteria_count: z.ZodNumber;
+    scope_opens_with_why: z.ZodBoolean;
+    plan_step: z.ZodEnum<{
+        skipped: "skipped";
+        required: "required";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"review_verdict">;
+    verdict: z.ZodEnum<{
+        approve: "approve";
+        request_changes: "request_changes";
+        comment: "comment";
+    }>;
+    score: z.ZodNullable<z.ZodNumber>;
+    must_fix_count: z.ZodNumber;
+    should_fix_count: z.ZodNumber;
+    gate: z.ZodNullable<z.ZodEnum<{
+        CONTINUE: "CONTINUE";
+        ITERATE: "ITERATE";
+        BLOCK: "BLOCK";
+    }>>;
+    brief_contract_checked: z.ZodBoolean;
+    brief_missed_high_count: z.ZodNumber;
+    review_pass: z.ZodNumber;
+    reviewer_model: z.ZodNullable<z.ZodString>;
+    blast_radius: z.ZodNullable<z.ZodString>;
+    auto_merge_eligible: z.ZodNullable<z.ZodBoolean>;
+    needs_preview_signoff: z.ZodNullable<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"human_approval">;
+    approval_kind: z.ZodEnum<{
+        explicit_tap: "explicit_tap";
+        standing_tap: "standing_tap";
+        preview_confirmed: "preview_confirmed";
+        merge_authorized: "merge_authorized";
+        ruling: "ruling";
+    }>;
+    granted: z.ZodBoolean;
+    scope: z.ZodEnum<{
+        this_pr: "this_pr";
+        wave: "wave";
+        standing: "standing";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"intervention">;
+    intervention_kind: z.ZodEnum<{
+        ruling: "ruling";
+        hook_bypass: "hook_bypass";
+        send_back: "send_back";
+        scope_correction: "scope_correction";
+        decision_block: "decision_block";
+        re_review_requested: "re_review_requested";
+    }>;
+    self_reported: z.ZodBoolean;
+    hook_name: z.ZodNullable<z.ZodString>;
+    blocked_action: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"takeover">;
+    takeover_kind: z.ZodEnum<{
+        human_finished_work: "human_finished_work";
+        work_abandoned: "work_abandoned";
+        reassigned: "reassigned";
+        output_discarded: "output_discarded";
+    }>;
+    prior_actor: z.ZodObject<{
+        raw_label: z.ZodNullable<z.ZodString>;
+        label_kind: z.ZodNullable<z.ZodEnum<{
+            email: "email";
+            github_login: "github_login";
+            linear_email: "linear_email";
+            linear_user_id: "linear_user_id";
+            reviewer_session: "reviewer_session";
+            hook_operator: "hook_operator";
+            queue_field: "queue_field";
+            brief_variable: "brief_variable";
+        }>>;
+        actor_class: z.ZodEnum<{
+            human: "human";
+            agent: "agent";
+        }>;
+        resolution: z.ZodEnum<{
+            resolved: "resolved";
+            unknown_person: "unknown_person";
+            ambiguous: "ambiguous";
+            no_person_named: "no_person_named";
+        }>;
+        person_id: z.ZodNullable<z.ZodString>;
+        unresolved_actor_id: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    turns_before_takeover: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"rule_fired">;
+    hook_name: z.ZodString;
+    decision: z.ZodEnum<{
+        blocked: "blocked";
+        allowed: "allowed";
+        allowed_bypass: "allowed_bypass";
+        warned: "warned";
+    }>;
+    bypass_token_present: z.ZodBoolean;
+}, z.core.$strict>], "kind">;
+export type DecisionOutcome = z.infer<typeof DecisionOutcomeSchema>;
+export declare const DecisionEventSchema: z.ZodObject<{
+    decision_event_id: z.ZodString;
+    kind: z.ZodEnum<{
+        delegation_issued: "delegation_issued";
+        review_verdict: "review_verdict";
+        human_approval: "human_approval";
+        intervention: "intervention";
+        takeover: "takeover";
+        rule_fired: "rule_fired";
+    }>;
+    occurred_at: z.ZodString;
+    actor: z.ZodObject<{
+        raw_label: z.ZodNullable<z.ZodString>;
+        label_kind: z.ZodNullable<z.ZodEnum<{
+            email: "email";
+            github_login: "github_login";
+            linear_email: "linear_email";
+            linear_user_id: "linear_user_id";
+            reviewer_session: "reviewer_session";
+            hook_operator: "hook_operator";
+            queue_field: "queue_field";
+            brief_variable: "brief_variable";
+        }>>;
+        actor_class: z.ZodEnum<{
+            human: "human";
+            agent: "agent";
+        }>;
+        resolution: z.ZodEnum<{
+            resolved: "resolved";
+            unknown_person: "unknown_person";
+            ambiguous: "ambiguous";
+            no_person_named: "no_person_named";
+        }>;
+        person_id: z.ZodNullable<z.ZodString>;
+        unresolved_actor_id: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    subject: z.ZodObject<{
+        repo: z.ZodNullable<z.ZodString>;
+        branch: z.ZodNullable<z.ZodString>;
+        ticket_id: z.ZodNullable<z.ZodString>;
+        pull_request_number: z.ZodNullable<z.ZodNumber>;
+        head_sha: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    outcome: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"delegation_issued">;
+        eta_minutes: z.ZodNullable<z.ZodNumber>;
+        model: z.ZodNullable<z.ZodString>;
+        auto_merge_authorized: z.ZodBoolean;
+        blast_radius_tags: z.ZodArray<z.ZodString>;
+        depends_on: z.ZodArray<z.ZodString>;
+        acceptance_criteria_count: z.ZodNumber;
+        scope_opens_with_why: z.ZodBoolean;
+        plan_step: z.ZodEnum<{
+            skipped: "skipped";
+            required: "required";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"review_verdict">;
+        verdict: z.ZodEnum<{
+            approve: "approve";
+            request_changes: "request_changes";
+            comment: "comment";
+        }>;
+        score: z.ZodNullable<z.ZodNumber>;
+        must_fix_count: z.ZodNumber;
+        should_fix_count: z.ZodNumber;
+        gate: z.ZodNullable<z.ZodEnum<{
+            CONTINUE: "CONTINUE";
+            ITERATE: "ITERATE";
+            BLOCK: "BLOCK";
+        }>>;
+        brief_contract_checked: z.ZodBoolean;
+        brief_missed_high_count: z.ZodNumber;
+        review_pass: z.ZodNumber;
+        reviewer_model: z.ZodNullable<z.ZodString>;
+        blast_radius: z.ZodNullable<z.ZodString>;
+        auto_merge_eligible: z.ZodNullable<z.ZodBoolean>;
+        needs_preview_signoff: z.ZodNullable<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"human_approval">;
+        approval_kind: z.ZodEnum<{
+            explicit_tap: "explicit_tap";
+            standing_tap: "standing_tap";
+            preview_confirmed: "preview_confirmed";
+            merge_authorized: "merge_authorized";
+            ruling: "ruling";
+        }>;
+        granted: z.ZodBoolean;
+        scope: z.ZodEnum<{
+            this_pr: "this_pr";
+            wave: "wave";
+            standing: "standing";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"intervention">;
+        intervention_kind: z.ZodEnum<{
+            ruling: "ruling";
+            hook_bypass: "hook_bypass";
+            send_back: "send_back";
+            scope_correction: "scope_correction";
+            decision_block: "decision_block";
+            re_review_requested: "re_review_requested";
+        }>;
+        self_reported: z.ZodBoolean;
+        hook_name: z.ZodNullable<z.ZodString>;
+        blocked_action: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"takeover">;
+        takeover_kind: z.ZodEnum<{
+            human_finished_work: "human_finished_work";
+            work_abandoned: "work_abandoned";
+            reassigned: "reassigned";
+            output_discarded: "output_discarded";
+        }>;
+        prior_actor: z.ZodObject<{
+            raw_label: z.ZodNullable<z.ZodString>;
+            label_kind: z.ZodNullable<z.ZodEnum<{
+                email: "email";
+                github_login: "github_login";
+                linear_email: "linear_email";
+                linear_user_id: "linear_user_id";
+                reviewer_session: "reviewer_session";
+                hook_operator: "hook_operator";
+                queue_field: "queue_field";
+                brief_variable: "brief_variable";
+            }>>;
+            actor_class: z.ZodEnum<{
+                human: "human";
+                agent: "agent";
+            }>;
+            resolution: z.ZodEnum<{
+                resolved: "resolved";
+                unknown_person: "unknown_person";
+                ambiguous: "ambiguous";
+                no_person_named: "no_person_named";
+            }>;
+            person_id: z.ZodNullable<z.ZodString>;
+            unresolved_actor_id: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+        turns_before_takeover: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"rule_fired">;
+        hook_name: z.ZodString;
+        decision: z.ZodEnum<{
+            blocked: "blocked";
+            allowed: "allowed";
+            allowed_bypass: "allowed_bypass";
+            warned: "warned";
+        }>;
+        bypass_token_present: z.ZodBoolean;
+    }, z.core.$strict>], "kind">;
+    capture_source: z.ZodEnum<{
+        claude_state_verdict_json: "claude_state_verdict_json";
+        claude_state_queue_jsonl: "claude_state_queue_jsonl";
+        claude_state_worker_brief: "claude_state_worker_brief";
+        claude_state_retro_jsonl: "claude_state_retro_jsonl";
+        claude_state_bypass_log: "claude_state_bypass_log";
+        claude_state_merge_log: "claude_state_merge_log";
+        hook_runtime: "hook_runtime";
+    }>;
+    source_artifact_hash_sha256: z.ZodNullable<z.ZodString>;
+    source_line_number: z.ZodNullable<z.ZodNumber>;
+    rule_id: z.ZodNullable<z.ZodString>;
+    rulebook_version: z.ZodNullable<z.ZodString>;
+    host: z.ZodNullable<z.ZodString>;
+    evidence_pointers: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            claude_state_path: "claude_state_path";
+            github_pull_request: "github_pull_request";
+            linear_issue: "linear_issue";
+            commit: "commit";
+            reviewer_session_id: "reviewer_session_id";
+        }>;
+        locator: z.ZodString;
+    }, z.core.$strict>>;
+    attributes: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>]>>;
+    privacy_classification: z.ZodLiteral<"metadata">;
+}, z.core.$strict>;
+export type DecisionEvent = z.infer<typeof DecisionEventSchema>;
+export declare const DecisionEventEnvelopeSchema: z.ZodObject<{
+    envelope_version: z.ZodLiteral<"decision-event.v1">;
+    writer: z.ZodString;
+    writer_version: z.ZodString;
+    events: z.ZodArray<z.ZodObject<{
+        decision_event_id: z.ZodString;
+        kind: z.ZodEnum<{
+            delegation_issued: "delegation_issued";
+            review_verdict: "review_verdict";
+            human_approval: "human_approval";
+            intervention: "intervention";
+            takeover: "takeover";
+            rule_fired: "rule_fired";
+        }>;
+        occurred_at: z.ZodString;
+        actor: z.ZodObject<{
+            raw_label: z.ZodNullable<z.ZodString>;
+            label_kind: z.ZodNullable<z.ZodEnum<{
+                email: "email";
+                github_login: "github_login";
+                linear_email: "linear_email";
+                linear_user_id: "linear_user_id";
+                reviewer_session: "reviewer_session";
+                hook_operator: "hook_operator";
+                queue_field: "queue_field";
+                brief_variable: "brief_variable";
+            }>>;
+            actor_class: z.ZodEnum<{
+                human: "human";
+                agent: "agent";
+            }>;
+            resolution: z.ZodEnum<{
+                resolved: "resolved";
+                unknown_person: "unknown_person";
+                ambiguous: "ambiguous";
+                no_person_named: "no_person_named";
+            }>;
+            person_id: z.ZodNullable<z.ZodString>;
+            unresolved_actor_id: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+        subject: z.ZodObject<{
+            repo: z.ZodNullable<z.ZodString>;
+            branch: z.ZodNullable<z.ZodString>;
+            ticket_id: z.ZodNullable<z.ZodString>;
+            pull_request_number: z.ZodNullable<z.ZodNumber>;
+            head_sha: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+        outcome: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"delegation_issued">;
+            eta_minutes: z.ZodNullable<z.ZodNumber>;
+            model: z.ZodNullable<z.ZodString>;
+            auto_merge_authorized: z.ZodBoolean;
+            blast_radius_tags: z.ZodArray<z.ZodString>;
+            depends_on: z.ZodArray<z.ZodString>;
+            acceptance_criteria_count: z.ZodNumber;
+            scope_opens_with_why: z.ZodBoolean;
+            plan_step: z.ZodEnum<{
+                skipped: "skipped";
+                required: "required";
+            }>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"review_verdict">;
+            verdict: z.ZodEnum<{
+                approve: "approve";
+                request_changes: "request_changes";
+                comment: "comment";
+            }>;
+            score: z.ZodNullable<z.ZodNumber>;
+            must_fix_count: z.ZodNumber;
+            should_fix_count: z.ZodNumber;
+            gate: z.ZodNullable<z.ZodEnum<{
+                CONTINUE: "CONTINUE";
+                ITERATE: "ITERATE";
+                BLOCK: "BLOCK";
+            }>>;
+            brief_contract_checked: z.ZodBoolean;
+            brief_missed_high_count: z.ZodNumber;
+            review_pass: z.ZodNumber;
+            reviewer_model: z.ZodNullable<z.ZodString>;
+            blast_radius: z.ZodNullable<z.ZodString>;
+            auto_merge_eligible: z.ZodNullable<z.ZodBoolean>;
+            needs_preview_signoff: z.ZodNullable<z.ZodBoolean>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"human_approval">;
+            approval_kind: z.ZodEnum<{
+                explicit_tap: "explicit_tap";
+                standing_tap: "standing_tap";
+                preview_confirmed: "preview_confirmed";
+                merge_authorized: "merge_authorized";
+                ruling: "ruling";
+            }>;
+            granted: z.ZodBoolean;
+            scope: z.ZodEnum<{
+                this_pr: "this_pr";
+                wave: "wave";
+                standing: "standing";
+            }>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"intervention">;
+            intervention_kind: z.ZodEnum<{
+                ruling: "ruling";
+                hook_bypass: "hook_bypass";
+                send_back: "send_back";
+                scope_correction: "scope_correction";
+                decision_block: "decision_block";
+                re_review_requested: "re_review_requested";
+            }>;
+            self_reported: z.ZodBoolean;
+            hook_name: z.ZodNullable<z.ZodString>;
+            blocked_action: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"takeover">;
+            takeover_kind: z.ZodEnum<{
+                human_finished_work: "human_finished_work";
+                work_abandoned: "work_abandoned";
+                reassigned: "reassigned";
+                output_discarded: "output_discarded";
+            }>;
+            prior_actor: z.ZodObject<{
+                raw_label: z.ZodNullable<z.ZodString>;
+                label_kind: z.ZodNullable<z.ZodEnum<{
+                    email: "email";
+                    github_login: "github_login";
+                    linear_email: "linear_email";
+                    linear_user_id: "linear_user_id";
+                    reviewer_session: "reviewer_session";
+                    hook_operator: "hook_operator";
+                    queue_field: "queue_field";
+                    brief_variable: "brief_variable";
+                }>>;
+                actor_class: z.ZodEnum<{
+                    human: "human";
+                    agent: "agent";
+                }>;
+                resolution: z.ZodEnum<{
+                    resolved: "resolved";
+                    unknown_person: "unknown_person";
+                    ambiguous: "ambiguous";
+                    no_person_named: "no_person_named";
+                }>;
+                person_id: z.ZodNullable<z.ZodString>;
+                unresolved_actor_id: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>;
+            turns_before_takeover: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"rule_fired">;
+            hook_name: z.ZodString;
+            decision: z.ZodEnum<{
+                blocked: "blocked";
+                allowed: "allowed";
+                allowed_bypass: "allowed_bypass";
+                warned: "warned";
+            }>;
+            bypass_token_present: z.ZodBoolean;
+        }, z.core.$strict>], "kind">;
+        capture_source: z.ZodEnum<{
+            claude_state_verdict_json: "claude_state_verdict_json";
+            claude_state_queue_jsonl: "claude_state_queue_jsonl";
+            claude_state_worker_brief: "claude_state_worker_brief";
+            claude_state_retro_jsonl: "claude_state_retro_jsonl";
+            claude_state_bypass_log: "claude_state_bypass_log";
+            claude_state_merge_log: "claude_state_merge_log";
+            hook_runtime: "hook_runtime";
+        }>;
+        source_artifact_hash_sha256: z.ZodNullable<z.ZodString>;
+        source_line_number: z.ZodNullable<z.ZodNumber>;
+        rule_id: z.ZodNullable<z.ZodString>;
+        rulebook_version: z.ZodNullable<z.ZodString>;
+        host: z.ZodNullable<z.ZodString>;
+        evidence_pointers: z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                claude_state_path: "claude_state_path";
+                github_pull_request: "github_pull_request";
+                linear_issue: "linear_issue";
+                commit: "commit";
+                reviewer_session_id: "reviewer_session_id";
+            }>;
+            locator: z.ZodString;
+        }, z.core.$strict>>;
+        attributes: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>]>>;
+        privacy_classification: z.ZodLiteral<"metadata">;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type DecisionEventEnvelope = z.infer<typeof DecisionEventEnvelopeSchema>;

package/dist/decision-event.js

@@ -0,0 +1,406 @@
+// BLI-2425 / Tower Wave 1: what a person committed to, as a record.
+//
+// A decision event is one durable record that a person committed to something:
+// handed work to someone, judged work, approved a merge, stepped in, took work
+// over, or had a rule fire on them. It is not a session, not a turn, and not a
+// diff — the ambient path already owns those, and this vocabulary deliberately
+// does not touch it.
+//
+// Three properties drive every field below.
+//
+// 1. The actor is a person, resolved through the one resolver. No fuzzy
+//    matching, ever. But an unresolved actor is not a dead end either: it gets
+//    a stable id so that "who did what, and when" stays answerable before
+//    anybody knows the name, and so that one later human assertion resolves
+//    every event that actor ever produced at once. See ActorRefSchema.
+//
+// 2. The event carries pointers, never content. Verdict prose and brief bodies
+//    name client repos and quote people. v1 carries enums, counts, ids, hashes
+//    and evidence pointers. Nothing else. `privacy_classification` is pinned to
+//    the literal "metadata" rather than reusing the full enum, so the type
+//    system refuses a decision event that could legally carry raw evidence.
+//
+// 3. There is a rule slot even though no rule IDs exist yet. Nothing anywhere
+//    records which rules were in force when something happened. The slot ships
+//    nullable in v1 so Wave 2 fills it by backfill instead of by migration.
+//
+// This vocabulary is disjoint from KNOWN_EVENT_TYPES and payloadSchemas. No
+// kind here reuses a legacy event name and nothing here lands on
+// /api/events/emit. That separation is the point: the known three-way
+// event-vocabulary drift is not a dependency of this work.
+import { z } from "zod";
+import { IsoDateTimeSchema, JsonAttributeRecordSchema, NonEmptyStringSchema, Sha256Schema, VersionStringSchema, } from "./common.js";
+export const DECISION_EVENT_ENVELOPE_VERSION = "decision-event.v1";
+/** A git commit sha. Sha256Schema is 64 hex and does not fit a 40-hex commit. */
+export const CommitShaSchema = z.string().regex(/^[a-f0-9]{7,40}$/);
+// ---------------------------------------------------------------------------
+// Kinds
+// ---------------------------------------------------------------------------
+export const DecisionEventKindSchema = z.enum([
+    "delegation_issued",
+    "review_verdict",
+    "human_approval",
+    "intervention",
+    "takeover",
+    "rule_fired",
+]);
+/**
+ * Which artifact this event was read out of.
+ *
+ * Deliberately its own enum rather than a member added to CaptureSourceSchema.
+ * That enum describes what a collector watched on a coding machine; these are
+ * files a manager's harness wrote as a side effect of managing. Sharing the
+ * enum would imply a shared envelope, and the whole reason this path exists is
+ * that decision records have no session, no work context and no capture
+ * provenance to fill.
+ */
+export const DecisionCaptureSourceSchema = z.enum([
+    "claude_state_verdict_json",
+    "claude_state_queue_jsonl",
+    "claude_state_worker_brief",
+    "claude_state_retro_jsonl",
+    "claude_state_bypass_log",
+    "claude_state_merge_log",
+    "hook_runtime",
+]);
+// ---------------------------------------------------------------------------
+// Who
+// ---------------------------------------------------------------------------
+/** Which field of the source artifact produced this label. */
+export const ActorLabelKindSchema = z.enum([
+    "email",
+    "github_login",
+    "linear_email",
+    "linear_user_id",
+    "reviewer_session",
+    "hook_operator",
+    "queue_field",
+    "brief_variable",
+]);
+/** Whether the thing that acted was a person or something a person ran. */
+export const ActorClassSchema = z.enum(["human", "agent"]);
+/**
+ * What the resolver concluded. These are the resolver's own four outcomes, kept
+ * apart rather than collapsed to null, because "nobody was named" and "somebody
+ * was named and we do not know them" call for different follow-up.
+ */
+export const ActorResolutionSchema = z.enum([
+    "resolved",
+    "unknown_person",
+    "ambiguous",
+    "no_person_named",
+]);
+/**
+ * Who acted — resolved to a person when we know them, and stably identified
+ * when we do not.
+ *
+ * The second half is the part worth reading. A backfill of ~2,400 historical
+ * decisions predates the person spine, so a large share of them name somebody
+ * the roster has never heard of. Collapsing all of those to one null makes the
+ * corpus useless: unresolved actor #1, #2 and #3 become indistinguishable and
+ * "who did what, and when" is unanswerable even in principle.
+ *
+ * So every distinct unresolved label gets `unresolved_actor_id`, derived
+ * deterministically from the normalized label (see `unresolvedActorId`). Events
+ * from the same label cluster under the same id forever. Later a human asserts
+ * "unresolved actor X is Brandon" and every event under that id resolves at
+ * once, retroactively, without a single event row being rewritten — the
+ * assertion lives in its own append-only alias table.
+ *
+ * That is not fuzzy matching sneaking back in. The ban is on the machine
+ * guessing; a human asserting an identity is the sanctioned escape hatch, and
+ * it is the same shape as jarvis_corrections, where the human outranks the
+ * pipeline and nothing is edited in place.
+ */
+export const ActorRefSchema = z
+    .object({
+    /** Exactly what the artifact said, before any normalization. Kept forever. */
+    raw_label: NonEmptyStringSchema.max(300).nullable(),
+    label_kind: ActorLabelKindSchema.nullable(),
+    actor_class: ActorClassSchema,
+    resolution: ActorResolutionSchema,
+    /** The roster person, when the resolver found exactly one. */
+    person_id: NonEmptyStringSchema.nullable(),
+    /**
+     * The stable identity of an actor we cannot name yet. Set whenever a real
+     * label failed to resolve; null when the resolver matched, and null when
+     * the artifact named nobody at all (there is no actor to be stable about).
+     */
+    unresolved_actor_id: NonEmptyStringSchema.nullable(),
+})
+    .strict()
+    .superRefine((actor, context) => {
+    if (actor.resolution === "resolved") {
+        if (!actor.person_id) {
+            context.addIssue({
+                code: "custom",
+                path: ["person_id"],
+                message: "A resolved actor must carry the person it resolved to.",
+            });
+        }
+        if (actor.unresolved_actor_id) {
+            context.addIssue({
+                code: "custom",
+                path: ["unresolved_actor_id"],
+                message: "A resolved actor has no unresolved id. Carrying both invites two answers to one question.",
+            });
+        }
+        return;
+    }
+    if (actor.person_id) {
+        context.addIssue({
+            code: "custom",
+            path: ["person_id"],
+            message: "Only a resolved actor carries a person. An unresolved actor that names one is a guess.",
+        });
+    }
+    if (actor.resolution === "no_person_named") {
+        if (actor.raw_label) {
+            context.addIssue({
+                code: "custom",
+                path: ["raw_label"],
+                message: "no_person_named means the artifact named nobody. A label present here is a different outcome.",
+            });
+        }
+        if (actor.unresolved_actor_id) {
+            context.addIssue({
+                code: "custom",
+                path: ["unresolved_actor_id"],
+                message: "Nobody was named, so there is no actor to identify stably.",
+            });
+        }
+        return;
+    }
+    // unknown_person and ambiguous: a real label that we could not turn into
+    // exactly one person. Both must be stably identified, or the backfill loses
+    // the ability to tell two strangers apart.
+    if (!actor.raw_label) {
+        context.addIssue({
+            code: "custom",
+            path: ["raw_label"],
+            message: "An unresolved actor must keep the label it failed to resolve, or nobody can ever name it.",
+        });
+    }
+    if (!actor.unresolved_actor_id) {
+        context.addIssue({
+            code: "custom",
+            path: ["unresolved_actor_id"],
+            message: "An unresolved actor must carry a stable id so its events cluster and can be named later.",
+        });
+    }
+});
+// ---------------------------------------------------------------------------
+// What it was about
+// ---------------------------------------------------------------------------
+/**
+ * The thing decided upon. `repo` is stored canonically as `owner/name` because
+ * the source artifacts disagree — the same pull request appears as
+ * `bli-cockpit` in the queue and `veetesh-glitch/bli-cockpit` in the verdict.
+ * Normalizing is an exact rule, never a prefix guess.
+ */
+export const DecisionSubjectSchema = z
+    .object({
+    repo: NonEmptyStringSchema.max(200).nullable(),
+    branch: NonEmptyStringSchema.max(300).nullable(),
+    ticket_id: NonEmptyStringSchema.max(40).nullable(),
+    pull_request_number: z.number().int().positive().nullable(),
+    head_sha: CommitShaSchema.nullable(),
+})
+    .strict();
+/**
+ * Where to go to see the thing itself. Pointers, never content — the prose
+ * these point at is exactly what v1 refuses to carry.
+ */
+export const DecisionEvidencePointerSchema = z
+    .object({
+    kind: z.enum([
+        "claude_state_path",
+        "github_pull_request",
+        "linear_issue",
+        "commit",
+        "reviewer_session_id",
+    ]),
+    locator: NonEmptyStringSchema.max(500),
+})
+    .strict();
+// ---------------------------------------------------------------------------
+// Per-kind outcomes
+// ---------------------------------------------------------------------------
+// Each is deliberately small: counts and enums, no narrative. Where the source
+// artifact holds a list of prose items, only its length survives.
+const DelegationIssuedOutcomeSchema = z
+    .object({
+    kind: z.literal("delegation_issued"),
+    eta_minutes: z.number().int().nonnegative().nullable(),
+    model: NonEmptyStringSchema.max(120).nullable(),
+    auto_merge_authorized: z.boolean(),
+    blast_radius_tags: z.array(NonEmptyStringSchema.max(60)).max(40),
+    depends_on: z.array(NonEmptyStringSchema.max(40)).max(40),
+    acceptance_criteria_count: z.number().int().nonnegative(),
+    scope_opens_with_why: z.boolean(),
+    plan_step: z.enum(["required", "skipped"]),
+})
+    .strict();
+const ReviewVerdictOutcomeSchema = z
+    .object({
+    kind: z.literal("review_verdict"),
+    verdict: z.enum(["approve", "request_changes", "comment"]),
+    score: z.number().min(0).max(10).nullable(),
+    must_fix_count: z.number().int().nonnegative(),
+    should_fix_count: z.number().int().nonnegative(),
+    gate: z.enum(["CONTINUE", "ITERATE", "BLOCK"]).nullable(),
+    brief_contract_checked: z.boolean(),
+    brief_missed_high_count: z.number().int().nonnegative(),
+    review_pass: z.number().int().positive(),
+    reviewer_model: NonEmptyStringSchema.max(120).nullable(),
+    blast_radius: NonEmptyStringSchema.max(60).nullable(),
+    auto_merge_eligible: z.boolean().nullable(),
+    needs_preview_signoff: z.boolean().nullable(),
+})
+    .strict();
+const HumanApprovalOutcomeSchema = z
+    .object({
+    kind: z.literal("human_approval"),
+    approval_kind: z.enum([
+        "explicit_tap",
+        "standing_tap",
+        "preview_confirmed",
+        "merge_authorized",
+        "ruling",
+    ]),
+    granted: z.boolean(),
+    scope: z.enum(["this_pr", "wave", "standing"]),
+})
+    .strict();
+const InterventionOutcomeSchema = z
+    .object({
+    kind: z.literal("intervention"),
+    intervention_kind: z.enum([
+        "hook_bypass",
+        "send_back",
+        "scope_correction",
+        "decision_block",
+        "ruling",
+        "re_review_requested",
+    ]),
+    self_reported: z.boolean(),
+    hook_name: NonEmptyStringSchema.max(120).nullable(),
+    blocked_action: NonEmptyStringSchema.max(120).nullable(),
+})
+    .strict();
+/**
+ * Nothing writes this yet — failure handling is modeled nowhere, which the
+ * audit called the loudest misdelegation signal being invisible. It is
+ * specified now anyway, because adding a kind later is additive within v1 while
+ * reshaping the envelope later is not.
+ */
+const TakeoverOutcomeSchema = z
+    .object({
+    kind: z.literal("takeover"),
+    takeover_kind: z.enum([
+        "human_finished_work",
+        "work_abandoned",
+        "reassigned",
+        "output_discarded",
+    ]),
+    prior_actor: ActorRefSchema,
+    turns_before_takeover: z.number().int().nonnegative().nullable(),
+})
+    .strict();
+const RuleFiredOutcomeSchema = z
+    .object({
+    kind: z.literal("rule_fired"),
+    hook_name: NonEmptyStringSchema.max(120),
+    decision: z.enum(["allowed", "allowed_bypass", "blocked", "warned"]),
+    bypass_token_present: z.boolean(),
+})
+    .strict();
+export const DecisionOutcomeSchema = z.discriminatedUnion("kind", [
+    DelegationIssuedOutcomeSchema,
+    ReviewVerdictOutcomeSchema,
+    HumanApprovalOutcomeSchema,
+    InterventionOutcomeSchema,
+    TakeoverOutcomeSchema,
+    RuleFiredOutcomeSchema,
+]);
+// ---------------------------------------------------------------------------
+// The event
+// ---------------------------------------------------------------------------
+export const DecisionEventSchema = z
+    .object({
+    /**
+     * Deterministic, so re-running the backfill is idempotent and an edited
+     * record produces a new id rather than mutating an old one. Derived from the
+     * record's own bytes, never from the file around them — see
+     * `decisionEventId`.
+     */
+    decision_event_id: NonEmptyStringSchema.max(64),
+    kind: DecisionEventKindSchema,
+    occurred_at: IsoDateTimeSchema,
+    actor: ActorRefSchema,
+    subject: DecisionSubjectSchema,
+    outcome: DecisionOutcomeSchema,
+    capture_source: DecisionCaptureSourceSchema,
+    /**
+     * Which snapshot of which file this was read out of, and where in it. Both
+     * are provenance, not identity: a re-import of a ledger that has grown since
+     * refreshes them on the existing row. Identity comes from the record's own
+     * bytes instead, which is what lets that re-import update rather than
+     * duplicate — see `decisionEventId`.
+     */
+    source_artifact_hash_sha256: Sha256Schema.nullable(),
+    source_line_number: z.number().int().nonnegative().nullable(),
+    /**
+     * Which rule this event was governed by, once rules have IDs. Nullable in
+     * v1 on purpose: the slot exists so Wave 2 backfills into it rather than
+     * migrating for it.
+     */
+    rule_id: NonEmptyStringSchema.max(40).nullable(),
+    rulebook_version: VersionStringSchema.nullable(),
+    /**
+     * Which machine the decision was made on, straight from the ledger line.
+     *
+     * A column rather than an `attributes` key, and deliberately beside
+     * `rulebook_version`: both are provenance about the *decision* rather than
+     * about the actor, and "did the laptop behave differently from the desktop"
+     * is a group-by question. A jsonb key would answer it by digging.
+     *
+     * Nullable because both ledgers only started stamping `host` on 2026-08-04
+     * (BLI-2435). Every line before that legitimately has none, so absence is
+     * history rather than an error, and a record without one must ingest
+     * cleanly.
+     */
+    host: NonEmptyStringSchema.max(253).nullable(),
+    evidence_pointers: z.array(DecisionEvidencePointerSchema).max(20),
+    /**
+     * Small, flat, non-narrative extras. Enforced as scalar-or-scalar-array by
+     * the shared record schema, which is what keeps prose from arriving here
+     * under a different name.
+     */
+    attributes: JsonAttributeRecordSchema,
+    /**
+     * Pinned to the literal rather than the full enum. A decision event that
+     * could legally carry raw evidence is one that will eventually carry
+     * verdict prose, so the type system refuses it outright.
+     */
+    privacy_classification: z.literal("metadata"),
+})
+    .strict()
+    .superRefine((event, context) => {
+    if (event.outcome.kind !== event.kind) {
+        context.addIssue({
+            code: "custom",
+            path: ["outcome", "kind"],
+            message: `Outcome is ${event.outcome.kind} but the event says ${event.kind}.`,
+        });
+    }
+});
+export const DecisionEventEnvelopeSchema = z
+    .object({
+    envelope_version: z.literal(DECISION_EVENT_ENVELOPE_VERSION),
+    /** Who is uploading, e.g. the hook, or the one-off backfill run. */
+    writer: NonEmptyStringSchema.max(120),
+    writer_version: VersionStringSchema,
+    events: z.array(DecisionEventSchema).min(1).max(500),
+})
+    .strict();

package/dist/evidence-upload.d.ts

@@ -389,9 +389,9 @@ export type RawEvidenceUploadCommitResponse = z.infer<typeof RawEvidenceUploadCo
 export declare const CODEX_SESSION_ATTRIBUTION_STATES: readonly ["attributed", "attributed_fallback", "ambiguous", "unattributed", "skipped"];
 export declare const CodexSessionAttributionStateSchema: z.ZodEnum<{
     skipped: "skipped";
+    ambiguous: "ambiguous";
     attributed: "attributed";
     attributed_fallback: "attributed_fallback";
-    ambiguous: "ambiguous";
     unattributed: "unattributed";
 }>;
 export type CodexSessionAttributionState = z.infer<typeof CodexSessionAttributionStateSchema>;
@@ -423,9 +423,9 @@ export declare const CodexSessionAttributionSchema: z.ZodObject<{
     observed_at: z.ZodString;
     attribution_state: z.ZodEnum<{
         skipped: "skipped";
+        ambiguous: "ambiguous";
         attributed: "attributed";
         attributed_fallback: "attributed_fallback";
-        ambiguous: "ambiguous";
         unattributed: "unattributed";
     }>;
     attribution_reason: z.ZodString;
@@ -491,9 +491,9 @@ export declare const CodexSessionAttributionReportRequestSchema: z.ZodObject<{
         observed_at: z.ZodString;
         attribution_state: z.ZodEnum<{
             skipped: "skipped";
+            ambiguous: "ambiguous";
             attributed: "attributed";
             attributed_fallback: "attributed_fallback";
-            ambiguous: "ambiguous";
             unattributed: "unattributed";
         }>;
         attribution_reason: z.ZodString;

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export * from "./agent-artifacts.js";
 export * from "./common.js";
+export * from "./decision-event.js";
+export * from "./decision-event-id.js";
 export * from "./evidence-completeness.js";
 export * from "./evidence-upload.js";
 export * from "./ingest-dto.js";

package/dist/index.js

@@ -1,5 +1,7 @@
 export * from "./agent-artifacts.js";
 export * from "./common.js";
+export * from "./decision-event.js";
+export * from "./decision-event-id.js";
 export * from "./evidence-completeness.js";
 export * from "./evidence-upload.js";
 export * from "./ingest-dto.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/telemetry-core",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",