@retrace-dev/core 0.1.0

package/dist/schema.d.ts

@@ -0,0 +1,708 @@
+/**
+ * Retrace core schema — the six dimensions of provenance:
+ * WHO (actor) · WHAT (action + artifacts + change) · WHEN (timestamp/seq)
+ * WHERE (location) · WHY (intent + caused_by) · HOW (method)
+ * plus integrity (hash chain).
+ *
+ * Deliberately close to W3C PROV (Agent / Activity / Entity) so we can export later.
+ */
+import { z } from "zod";
+export declare const ActorType: z.ZodEnum<["human", "agent", "system"]>;
+export type ActorType = z.infer<typeof ActorType>;
+export declare const Actor: z.ZodObject<{
+    type: z.ZodEnum<["human", "agent", "system"]>;
+    /** Stable identifier: email, agent name, service id */
+    id: z.ZodString;
+    display_name: z.ZodOptional<z.ZodString>;
+    /** For agents: model + version that performed the action */
+    model: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    /** Delegation: an agent acting for a human, or a sub-agent for a parent agent */
+    on_behalf_of: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "human" | "agent" | "system";
+    id: string;
+    display_name?: string | undefined;
+    model?: string | undefined;
+    version?: string | undefined;
+    on_behalf_of?: string | undefined;
+}, {
+    type: "human" | "agent" | "system";
+    id: string;
+    display_name?: string | undefined;
+    model?: string | undefined;
+    version?: string | undefined;
+    on_behalf_of?: string | undefined;
+}>;
+export type Actor = z.infer<typeof Actor>;
+/** Small controlled verb vocabulary. `other` requires `action_detail`. */
+export declare const Action: z.ZodEnum<["created", "edited", "deleted", "read", "executed", "approved", "rejected", "sent", "received", "moved", "renamed", "instructed", "committed", "merged", "other"]>;
+export type Action = z.infer<typeof Action>;
+/**
+ * PROV role of an artifact within an event: was it an input the activity `used`, an output it `generated`, or `both`
+ * (read then rewritten). Optional — absence means "unspecified" and is a legal, permanent state: events sealed before
+ * this field existed are never backfilled or re-hashed (absence is information).
+ *   Export mapping (for a future prov exporter): used → prov:used (Activity→Entity), generated → prov:wasGeneratedBy
+ *   (Entity→Activity), both → both edges, absent → degrades to prov:wasInfluencedBy.
+ *   Distinct from `derived_from`, which is Entity→Entity (prov:wasDerivedFrom) and unchanged. Invalidation (a deleted
+ *   artifact, prov:wasInvalidatedBy) is deliberately NOT a role — a deleted ref stays absent until that is a first-class edge.
+ */
+export declare const ArtifactRole: z.ZodEnum<["used", "generated", "both"]>;
+export type ArtifactRole = z.infer<typeof ArtifactRole>;
+export declare const ArtifactRef: z.ZodObject<{
+    /** Stable id for the thing being worked on, e.g. "repo:slcwitit/rpg#src/fight.ts" or "doc:abc123" */
+    id: z.ZodString;
+    kind: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    /** Lineage: this artifact was derived from these */
+    derived_from: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** PROV: input (used) / output (generated) / both. Body-only, hash-covered on new events; see ArtifactRole. */
+    role: z.ZodOptional<z.ZodEnum<["used", "generated", "both"]>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    kind?: string | undefined;
+    label?: string | undefined;
+    derived_from?: string[] | undefined;
+    role?: "used" | "generated" | "both" | undefined;
+}, {
+    id: string;
+    kind?: string | undefined;
+    label?: string | undefined;
+    derived_from?: string[] | undefined;
+    role?: "used" | "generated" | "both" | undefined;
+}>;
+export type ArtifactRef = z.infer<typeof ArtifactRef>;
+/**
+ * Default role of an artifact ref for an action verb, for when the caller says nothing. `undefined` = leave absent.
+ *   read → used · created/committed/merged → generated · edited/moved/renamed → both (the prior state is read, the new
+ *   one written) · executed/sent/received/approved/rejected → used (the thing run/sent/reviewed was an input; an OUTPUT
+ *   such as a deployment or report must be said by the caller) · deleted/instructed/other → absent.
+ * Adapters stamp what they authoritatively know and only fall back to this where the verb alone is the truth.
+ */
+export declare function defaultArtifactRole(action: Action): ArtifactRole | undefined;
+/** Fill `role` from defaultArtifactRole ONLY where a ref has none — a caller-supplied role is never overwritten. Refs
+ *  that get no default come back as they were (no `role` key, so hashes of role-less inputs are unaffected). */
+export declare function applyDefaultRoles<T extends ArtifactRef>(action: Action, artifacts: T[]): T[];
+export declare const Change: z.ZodObject<{
+    before_hash: z.ZodOptional<z.ZodString>;
+    after_hash: z.ZodOptional<z.ZodString>;
+    diff: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    before_hash?: string | undefined;
+    after_hash?: string | undefined;
+    diff?: string | undefined;
+    summary?: string | undefined;
+}, {
+    before_hash?: string | undefined;
+    after_hash?: string | undefined;
+    diff?: string | undefined;
+    summary?: string | undefined;
+}>;
+export declare const Location: z.ZodObject<{
+    /** repo path, doc section, URL, table, etc. */
+    path: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodString>;
+    device: z.ZodOptional<z.ZodString>;
+    system: z.ZodOptional<z.ZodString>;
+    /** Run/session id of the producing process (backlog #15; body-only, like every location field). On the MCP path
+     *  this is the harness's own session id when it exposes one (CLAUDE_CODE_SESSION_ID or GROK_SESSION_ID), so the same string appears on
+     *  events from the agent AND on the commits it drives. It is a *session* key — subagents share it — not a per-run id. */
+    session: z.ZodOptional<z.ZodString>;
+    /** The MCP client that drove the write, verbatim from the `initialize` handshake as "<name>@<version>" — e.g.
+     *  "claude-code@2.1.250", "cursor-vscode@1.7.3". Server-stamped only: it is evidence ABOUT the writer, so the
+     *  writer may not assert it (see SERVER_ONLY in the MCP server). */
+    client: z.ZodOptional<z.ZodString>;
+    /** IDE / agent-development environment hosting the actor, e.g. "orca". Deliberately distinct from `system` (the tool
+     *  that produced the event, "claude-code") and from `client` (which build of it): the IDE is the app AROUND both, and
+     *  neither of the other two can express it. Only stamped when the IDE identifies itself in the environment. */
+    ide: z.ZodOptional<z.ZodString>;
+    /** Isolated workspace within `ide` — an Orca worktree id, a codespace or devcontainer name. This is what tells two
+     *  parallel agents apart when they run the same project, on the same host, as the same actor. */
+    workspace: z.ZodOptional<z.ZodString>;
+    /** Whether the producing process had a controlling terminal: "tty" = a human at a keyboard, "agent" = spawned by a
+     *  harness with none. Linux-only today (read from /proc/self/stat); absent everywhere else, and absence is a legal
+     *  permanent state. EVIDENCE, never authority — it must not override the actor determination. */
+    surface: z.ZodOptional<z.ZodEnum<["tty", "agent"]>>;
+}, "strip", z.ZodTypeAny, {
+    system?: string | undefined;
+    path?: string | undefined;
+    url?: string | undefined;
+    environment?: string | undefined;
+    device?: string | undefined;
+    session?: string | undefined;
+    client?: string | undefined;
+    ide?: string | undefined;
+    workspace?: string | undefined;
+    surface?: "agent" | "tty" | undefined;
+}, {
+    system?: string | undefined;
+    path?: string | undefined;
+    url?: string | undefined;
+    environment?: string | undefined;
+    device?: string | undefined;
+    session?: string | undefined;
+    client?: string | undefined;
+    ide?: string | undefined;
+    workspace?: string | undefined;
+    surface?: "agent" | "tty" | undefined;
+}>;
+export type Location = z.infer<typeof Location>;
+export declare const Method: z.ZodObject<{
+    tool: z.ZodOptional<z.ZodString>;
+    /** Reference to instruction/prompt that drove this (id, hash, or short text) */
+    instruction: z.ZodOptional<z.ZodString>;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    automated: z.ZodOptional<z.ZodBoolean>;
+    tokens: z.ZodOptional<z.ZodNumber>;
+    cost_usd: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    params?: Record<string, unknown> | undefined;
+    tool?: string | undefined;
+    instruction?: string | undefined;
+    automated?: boolean | undefined;
+    tokens?: number | undefined;
+    cost_usd?: number | undefined;
+}, {
+    params?: Record<string, unknown> | undefined;
+    tool?: string | undefined;
+    instruction?: string | undefined;
+    automated?: boolean | undefined;
+    tokens?: number | undefined;
+    cost_usd?: number | undefined;
+}>;
+/** What a client submits. Server fills in id/seq/hash/prev_hash. */
+export declare const EventInput: z.ZodObject<{
+    project: z.ZodString;
+    actor: z.ZodObject<{
+        type: z.ZodEnum<["human", "agent", "system"]>;
+        /** Stable identifier: email, agent name, service id */
+        id: z.ZodString;
+        display_name: z.ZodOptional<z.ZodString>;
+        /** For agents: model + version that performed the action */
+        model: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+        /** Delegation: an agent acting for a human, or a sub-agent for a parent agent */
+        on_behalf_of: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "human" | "agent" | "system";
+        id: string;
+        display_name?: string | undefined;
+        model?: string | undefined;
+        version?: string | undefined;
+        on_behalf_of?: string | undefined;
+    }, {
+        type: "human" | "agent" | "system";
+        id: string;
+        display_name?: string | undefined;
+        model?: string | undefined;
+        version?: string | undefined;
+        on_behalf_of?: string | undefined;
+    }>;
+    action: z.ZodEnum<["created", "edited", "deleted", "read", "executed", "approved", "rejected", "sent", "received", "moved", "renamed", "instructed", "committed", "merged", "other"]>;
+    action_detail: z.ZodOptional<z.ZodString>;
+    artifacts: z.ZodArray<z.ZodObject<{
+        /** Stable id for the thing being worked on, e.g. "repo:slcwitit/rpg#src/fight.ts" or "doc:abc123" */
+        id: z.ZodString;
+        kind: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        /** Lineage: this artifact was derived from these */
+        derived_from: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** PROV: input (used) / output (generated) / both. Body-only, hash-covered on new events; see ArtifactRole. */
+        role: z.ZodOptional<z.ZodEnum<["used", "generated", "both"]>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        kind?: string | undefined;
+        label?: string | undefined;
+        derived_from?: string[] | undefined;
+        role?: "used" | "generated" | "both" | undefined;
+    }, {
+        id: string;
+        kind?: string | undefined;
+        label?: string | undefined;
+        derived_from?: string[] | undefined;
+        role?: "used" | "generated" | "both" | undefined;
+    }>, "many">;
+    change: z.ZodOptional<z.ZodObject<{
+        before_hash: z.ZodOptional<z.ZodString>;
+        after_hash: z.ZodOptional<z.ZodString>;
+        diff: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        before_hash?: string | undefined;
+        after_hash?: string | undefined;
+        diff?: string | undefined;
+        summary?: string | undefined;
+    }, {
+        before_hash?: string | undefined;
+        after_hash?: string | undefined;
+        diff?: string | undefined;
+        summary?: string | undefined;
+    }>>;
+    timestamp: z.ZodOptional<z.ZodString>;
+    duration_ms: z.ZodOptional<z.ZodNumber>;
+    location: z.ZodOptional<z.ZodObject<{
+        /** repo path, doc section, URL, table, etc. */
+        path: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        environment: z.ZodOptional<z.ZodString>;
+        device: z.ZodOptional<z.ZodString>;
+        system: z.ZodOptional<z.ZodString>;
+        /** Run/session id of the producing process (backlog #15; body-only, like every location field). On the MCP path
+         *  this is the harness's own session id when it exposes one (CLAUDE_CODE_SESSION_ID or GROK_SESSION_ID), so the same string appears on
+         *  events from the agent AND on the commits it drives. It is a *session* key — subagents share it — not a per-run id. */
+        session: z.ZodOptional<z.ZodString>;
+        /** The MCP client that drove the write, verbatim from the `initialize` handshake as "<name>@<version>" — e.g.
+         *  "claude-code@2.1.250", "cursor-vscode@1.7.3". Server-stamped only: it is evidence ABOUT the writer, so the
+         *  writer may not assert it (see SERVER_ONLY in the MCP server). */
+        client: z.ZodOptional<z.ZodString>;
+        /** IDE / agent-development environment hosting the actor, e.g. "orca". Deliberately distinct from `system` (the tool
+         *  that produced the event, "claude-code") and from `client` (which build of it): the IDE is the app AROUND both, and
+         *  neither of the other two can express it. Only stamped when the IDE identifies itself in the environment. */
+        ide: z.ZodOptional<z.ZodString>;
+        /** Isolated workspace within `ide` — an Orca worktree id, a codespace or devcontainer name. This is what tells two
+         *  parallel agents apart when they run the same project, on the same host, as the same actor. */
+        workspace: z.ZodOptional<z.ZodString>;
+        /** Whether the producing process had a controlling terminal: "tty" = a human at a keyboard, "agent" = spawned by a
+         *  harness with none. Linux-only today (read from /proc/self/stat); absent everywhere else, and absence is a legal
+         *  permanent state. EVIDENCE, never authority — it must not override the actor determination. */
+        surface: z.ZodOptional<z.ZodEnum<["tty", "agent"]>>;
+    }, "strip", z.ZodTypeAny, {
+        system?: string | undefined;
+        path?: string | undefined;
+        url?: string | undefined;
+        environment?: string | undefined;
+        device?: string | undefined;
+        session?: string | undefined;
+        client?: string | undefined;
+        ide?: string | undefined;
+        workspace?: string | undefined;
+        surface?: "agent" | "tty" | undefined;
+    }, {
+        system?: string | undefined;
+        path?: string | undefined;
+        url?: string | undefined;
+        environment?: string | undefined;
+        device?: string | undefined;
+        session?: string | undefined;
+        client?: string | undefined;
+        ide?: string | undefined;
+        workspace?: string | undefined;
+        surface?: "agent" | "tty" | undefined;
+    }>>;
+    /** WHY — free text reason */
+    intent: z.ZodOptional<z.ZodString>;
+    /** WHY — causal parent (event id). The instruction that led to this action. */
+    caused_by: z.ZodOptional<z.ZodString>;
+    method: z.ZodOptional<z.ZodObject<{
+        tool: z.ZodOptional<z.ZodString>;
+        /** Reference to instruction/prompt that drove this (id, hash, or short text) */
+        instruction: z.ZodOptional<z.ZodString>;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        automated: z.ZodOptional<z.ZodBoolean>;
+        tokens: z.ZodOptional<z.ZodNumber>;
+        cost_usd: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        params?: Record<string, unknown> | undefined;
+        tool?: string | undefined;
+        instruction?: string | undefined;
+        automated?: boolean | undefined;
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    }, {
+        params?: Record<string, unknown> | undefined;
+        tool?: string | undefined;
+        instruction?: string | undefined;
+        automated?: boolean | undefined;
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    }>>;
+    /** Client-provided idempotency key */
+    idempotency_key: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    project: string;
+    actor: {
+        type: "human" | "agent" | "system";
+        id: string;
+        display_name?: string | undefined;
+        model?: string | undefined;
+        version?: string | undefined;
+        on_behalf_of?: string | undefined;
+    };
+    action: "received" | "created" | "edited" | "deleted" | "read" | "executed" | "approved" | "rejected" | "sent" | "moved" | "renamed" | "instructed" | "committed" | "merged" | "other";
+    artifacts: {
+        id: string;
+        kind?: string | undefined;
+        label?: string | undefined;
+        derived_from?: string[] | undefined;
+        role?: "used" | "generated" | "both" | undefined;
+    }[];
+    action_detail?: string | undefined;
+    change?: {
+        before_hash?: string | undefined;
+        after_hash?: string | undefined;
+        diff?: string | undefined;
+        summary?: string | undefined;
+    } | undefined;
+    timestamp?: string | undefined;
+    duration_ms?: number | undefined;
+    location?: {
+        system?: string | undefined;
+        path?: string | undefined;
+        url?: string | undefined;
+        environment?: string | undefined;
+        device?: string | undefined;
+        session?: string | undefined;
+        client?: string | undefined;
+        ide?: string | undefined;
+        workspace?: string | undefined;
+        surface?: "agent" | "tty" | undefined;
+    } | undefined;
+    intent?: string | undefined;
+    caused_by?: string | undefined;
+    method?: {
+        params?: Record<string, unknown> | undefined;
+        tool?: string | undefined;
+        instruction?: string | undefined;
+        automated?: boolean | undefined;
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    } | undefined;
+    idempotency_key?: string | undefined;
+    tags?: string[] | undefined;
+}, {
+    project: string;
+    actor: {
+        type: "human" | "agent" | "system";
+        id: string;
+        display_name?: string | undefined;
+        model?: string | undefined;
+        version?: string | undefined;
+        on_behalf_of?: string | undefined;
+    };
+    action: "received" | "created" | "edited" | "deleted" | "read" | "executed" | "approved" | "rejected" | "sent" | "moved" | "renamed" | "instructed" | "committed" | "merged" | "other";
+    artifacts: {
+        id: string;
+        kind?: string | undefined;
+        label?: string | undefined;
+        derived_from?: string[] | undefined;
+        role?: "used" | "generated" | "both" | undefined;
+    }[];
+    action_detail?: string | undefined;
+    change?: {
+        before_hash?: string | undefined;
+        after_hash?: string | undefined;
+        diff?: string | undefined;
+        summary?: string | undefined;
+    } | undefined;
+    timestamp?: string | undefined;
+    duration_ms?: number | undefined;
+    location?: {
+        system?: string | undefined;
+        path?: string | undefined;
+        url?: string | undefined;
+        environment?: string | undefined;
+        device?: string | undefined;
+        session?: string | undefined;
+        client?: string | undefined;
+        ide?: string | undefined;
+        workspace?: string | undefined;
+        surface?: "agent" | "tty" | undefined;
+    } | undefined;
+    intent?: string | undefined;
+    caused_by?: string | undefined;
+    method?: {
+        params?: Record<string, unknown> | undefined;
+        tool?: string | undefined;
+        instruction?: string | undefined;
+        automated?: boolean | undefined;
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    } | undefined;
+    idempotency_key?: string | undefined;
+    tags?: string[] | undefined;
+}>;
+export type EventInput = z.infer<typeof EventInput>;
+export declare const Event: z.ZodObject<{
+    project: z.ZodString;
+    actor: z.ZodObject<{
+        type: z.ZodEnum<["human", "agent", "system"]>;
+        /** Stable identifier: email, agent name, service id */
+        id: z.ZodString;
+        display_name: z.ZodOptional<z.ZodString>;
+        /** For agents: model + version that performed the action */
+        model: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+        /** Delegation: an agent acting for a human, or a sub-agent for a parent agent */
+        on_behalf_of: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "human" | "agent" | "system";
+        id: string;
+        display_name?: string | undefined;
+        model?: string | undefined;
+        version?: string | undefined;
+        on_behalf_of?: string | undefined;
+    }, {
+        type: "human" | "agent" | "system";
+        id: string;
+        display_name?: string | undefined;
+        model?: string | undefined;
+        version?: string | undefined;
+        on_behalf_of?: string | undefined;
+    }>;
+    action: z.ZodEnum<["created", "edited", "deleted", "read", "executed", "approved", "rejected", "sent", "received", "moved", "renamed", "instructed", "committed", "merged", "other"]>;
+    action_detail: z.ZodOptional<z.ZodString>;
+    artifacts: z.ZodArray<z.ZodObject<{
+        /** Stable id for the thing being worked on, e.g. "repo:slcwitit/rpg#src/fight.ts" or "doc:abc123" */
+        id: z.ZodString;
+        kind: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        /** Lineage: this artifact was derived from these */
+        derived_from: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** PROV: input (used) / output (generated) / both. Body-only, hash-covered on new events; see ArtifactRole. */
+        role: z.ZodOptional<z.ZodEnum<["used", "generated", "both"]>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        kind?: string | undefined;
+        label?: string | undefined;
+        derived_from?: string[] | undefined;
+        role?: "used" | "generated" | "both" | undefined;
+    }, {
+        id: string;
+        kind?: string | undefined;
+        label?: string | undefined;
+        derived_from?: string[] | undefined;
+        role?: "used" | "generated" | "both" | undefined;
+    }>, "many">;
+    change: z.ZodOptional<z.ZodObject<{
+        before_hash: z.ZodOptional<z.ZodString>;
+        after_hash: z.ZodOptional<z.ZodString>;
+        diff: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        before_hash?: string | undefined;
+        after_hash?: string | undefined;
+        diff?: string | undefined;
+        summary?: string | undefined;
+    }, {
+        before_hash?: string | undefined;
+        after_hash?: string | undefined;
+        diff?: string | undefined;
+        summary?: string | undefined;
+    }>>;
+    duration_ms: z.ZodOptional<z.ZodNumber>;
+    location: z.ZodOptional<z.ZodObject<{
+        /** repo path, doc section, URL, table, etc. */
+        path: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        environment: z.ZodOptional<z.ZodString>;
+        device: z.ZodOptional<z.ZodString>;
+        system: z.ZodOptional<z.ZodString>;
+        /** Run/session id of the producing process (backlog #15; body-only, like every location field). On the MCP path
+         *  this is the harness's own session id when it exposes one (CLAUDE_CODE_SESSION_ID or GROK_SESSION_ID), so the same string appears on
+         *  events from the agent AND on the commits it drives. It is a *session* key — subagents share it — not a per-run id. */
+        session: z.ZodOptional<z.ZodString>;
+        /** The MCP client that drove the write, verbatim from the `initialize` handshake as "<name>@<version>" — e.g.
+         *  "claude-code@2.1.250", "cursor-vscode@1.7.3". Server-stamped only: it is evidence ABOUT the writer, so the
+         *  writer may not assert it (see SERVER_ONLY in the MCP server). */
+        client: z.ZodOptional<z.ZodString>;
+        /** IDE / agent-development environment hosting the actor, e.g. "orca". Deliberately distinct from `system` (the tool
+         *  that produced the event, "claude-code") and from `client` (which build of it): the IDE is the app AROUND both, and
+         *  neither of the other two can express it. Only stamped when the IDE identifies itself in the environment. */
+        ide: z.ZodOptional<z.ZodString>;
+        /** Isolated workspace within `ide` — an Orca worktree id, a codespace or devcontainer name. This is what tells two
+         *  parallel agents apart when they run the same project, on the same host, as the same actor. */
+        workspace: z.ZodOptional<z.ZodString>;
+        /** Whether the producing process had a controlling terminal: "tty" = a human at a keyboard, "agent" = spawned by a
+         *  harness with none. Linux-only today (read from /proc/self/stat); absent everywhere else, and absence is a legal
+         *  permanent state. EVIDENCE, never authority — it must not override the actor determination. */
+        surface: z.ZodOptional<z.ZodEnum<["tty", "agent"]>>;
+    }, "strip", z.ZodTypeAny, {
+        system?: string | undefined;
+        path?: string | undefined;
+        url?: string | undefined;
+        environment?: string | undefined;
+        device?: string | undefined;
+        session?: string | undefined;
+        client?: string | undefined;
+        ide?: string | undefined;
+        workspace?: string | undefined;
+        surface?: "agent" | "tty" | undefined;
+    }, {
+        system?: string | undefined;
+        path?: string | undefined;
+        url?: string | undefined;
+        environment?: string | undefined;
+        device?: string | undefined;
+        session?: string | undefined;
+        client?: string | undefined;
+        ide?: string | undefined;
+        workspace?: string | undefined;
+        surface?: "agent" | "tty" | undefined;
+    }>>;
+    intent: z.ZodOptional<z.ZodString>;
+    caused_by: z.ZodOptional<z.ZodString>;
+    method: z.ZodOptional<z.ZodObject<{
+        tool: z.ZodOptional<z.ZodString>;
+        /** Reference to instruction/prompt that drove this (id, hash, or short text) */
+        instruction: z.ZodOptional<z.ZodString>;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        automated: z.ZodOptional<z.ZodBoolean>;
+        tokens: z.ZodOptional<z.ZodNumber>;
+        cost_usd: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        params?: Record<string, unknown> | undefined;
+        tool?: string | undefined;
+        instruction?: string | undefined;
+        automated?: boolean | undefined;
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    }, {
+        params?: Record<string, unknown> | undefined;
+        tool?: string | undefined;
+        instruction?: string | undefined;
+        automated?: boolean | undefined;
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    }>>;
+    idempotency_key: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    id: z.ZodString;
+    seq: z.ZodNumber;
+    timestamp: z.ZodString;
+    prev_hash: z.ZodString;
+    hash: z.ZodString;
+    received_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    project: string;
+    actor: {
+        type: "human" | "agent" | "system";
+        id: string;
+        display_name?: string | undefined;
+        model?: string | undefined;
+        version?: string | undefined;
+        on_behalf_of?: string | undefined;
+    };
+    action: "received" | "created" | "edited" | "deleted" | "read" | "executed" | "approved" | "rejected" | "sent" | "moved" | "renamed" | "instructed" | "committed" | "merged" | "other";
+    artifacts: {
+        id: string;
+        kind?: string | undefined;
+        label?: string | undefined;
+        derived_from?: string[] | undefined;
+        role?: "used" | "generated" | "both" | undefined;
+    }[];
+    timestamp: string;
+    seq: number;
+    prev_hash: string;
+    hash: string;
+    received_at: string;
+    action_detail?: string | undefined;
+    change?: {
+        before_hash?: string | undefined;
+        after_hash?: string | undefined;
+        diff?: string | undefined;
+        summary?: string | undefined;
+    } | undefined;
+    duration_ms?: number | undefined;
+    location?: {
+        system?: string | undefined;
+        path?: string | undefined;
+        url?: string | undefined;
+        environment?: string | undefined;
+        device?: string | undefined;
+        session?: string | undefined;
+        client?: string | undefined;
+        ide?: string | undefined;
+        workspace?: string | undefined;
+        surface?: "agent" | "tty" | undefined;
+    } | undefined;
+    intent?: string | undefined;
+    caused_by?: string | undefined;
+    method?: {
+        params?: Record<string, unknown> | undefined;
+        tool?: string | undefined;
+        instruction?: string | undefined;
+        automated?: boolean | undefined;
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    } | undefined;
+    idempotency_key?: string | undefined;
+    tags?: string[] | undefined;
+}, {
+    id: string;
+    project: string;
+    actor: {
+        type: "human" | "agent" | "system";
+        id: string;
+        display_name?: string | undefined;
+        model?: string | undefined;
+        version?: string | undefined;
+        on_behalf_of?: string | undefined;
+    };
+    action: "received" | "created" | "edited" | "deleted" | "read" | "executed" | "approved" | "rejected" | "sent" | "moved" | "renamed" | "instructed" | "committed" | "merged" | "other";
+    artifacts: {
+        id: string;
+        kind?: string | undefined;
+        label?: string | undefined;
+        derived_from?: string[] | undefined;
+        role?: "used" | "generated" | "both" | undefined;
+    }[];
+    timestamp: string;
+    seq: number;
+    prev_hash: string;
+    hash: string;
+    received_at: string;
+    action_detail?: string | undefined;
+    change?: {
+        before_hash?: string | undefined;
+        after_hash?: string | undefined;
+        diff?: string | undefined;
+        summary?: string | undefined;
+    } | undefined;
+    duration_ms?: number | undefined;
+    location?: {
+        system?: string | undefined;
+        path?: string | undefined;
+        url?: string | undefined;
+        environment?: string | undefined;
+        device?: string | undefined;
+        session?: string | undefined;
+        client?: string | undefined;
+        ide?: string | undefined;
+        workspace?: string | undefined;
+        surface?: "agent" | "tty" | undefined;
+    } | undefined;
+    intent?: string | undefined;
+    caused_by?: string | undefined;
+    method?: {
+        params?: Record<string, unknown> | undefined;
+        tool?: string | undefined;
+        instruction?: string | undefined;
+        automated?: boolean | undefined;
+        tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    } | undefined;
+    idempotency_key?: string | undefined;
+    tags?: string[] | undefined;
+}>;
+export type Event = z.infer<typeof Event>;
+/**
+ * The schema surface a build understands, derived from the zod shapes themselves so it can never drift from the code.
+ *
+ * This exists because the failure it detects is SILENT: `POST /events` re-parses with `EventInput.safeParse`, and zod
+ * strips keys it does not know, so a producer running newer code than the deployment loses those fields with no error
+ * anywhere — the event is accepted, sealed and hashed without them. It has happened twice (`location.session`,
+ * `bacabed`; `location.client`/`ide`/`workspace`/`surface`, 2026-08-28), both times found by eye.
+ * `GET /api` publishes this, and `npm run check-deploy` diffs a deployment against the local build.
+ */
+export declare function schemaSurface(): {
+    event: string[];
+    location: string[];
+    artifact: string[];
+    actions: string[];
+};
+export declare const GENESIS_HASH: string;