@qmilab/lodestar-core 0.1.5 → 0.2.0

package/dist/schemas/sentinel.d.ts

@@ -0,0 +1,134 @@
+import { z } from "zod";
+/**
+ * Sentinel alerts — the wire format a Sentinel emits when it pattern-matches
+ * a suspicious shape in the event stream.
+ *
+ * Design lock: `docs/architecture/sentinels.md` (and Q7 of
+ * `docs/architecture/reflection-pass.md`, which settled the execution model).
+ * The short version:
+ *
+ * - Sentinels are an async tail of the event stream. They never block the
+ *   Action Kernel; they emit `sentinel.alerted@1` events and a future
+ *   (additive) `arbitrate` hook honours them on the *next* action that
+ *   depends on a flagged subject.
+ * - This is a governance event, not an Observation. Like
+ *   `reflection.completed@1`, the payload is the event payload directly and
+ *   is NOT registered in the observation schema registry.
+ *
+ * Core owns the wire format only. The base class, the runner, and the
+ * concrete sentinels live in `@qmilab/lodestar-harness`.
+ */
+/**
+ * What a sentinel alert is *about*. Kept deliberately small — the four
+ * epistemic-chain nouns a v0 sentinel can point at.
+ *
+ * `belief` is the load-bearing kind for the eventual kernel hook: the
+ * `arbitrate` lookup scopes recent alerts to a candidate action's
+ * `belief_dependencies`, so a sentinel that names a belief gates the next
+ * action that leans on it. `tool_sequence` is a synthetic subject — its
+ * `id` identifies the *completion* of a matched sequence (the id of the
+ * final action in the run), since no single chain-noun owns the pattern.
+ */
+export declare const SentinelSubjectSchema: z.ZodObject<{
+    kind: z.ZodEnum<["belief", "action", "decision", "tool_sequence"]>;
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    kind: "belief" | "decision" | "action" | "tool_sequence";
+}, {
+    id: string;
+    kind: "belief" | "decision" | "action" | "tool_sequence";
+}>;
+export type SentinelSubject = z.infer<typeof SentinelSubjectSchema>;
+/**
+ * Triage weight. `critical` is reserved for patterns that, left unflagged,
+ * map onto a concrete attack (e.g. the read → external-egress → write
+ * exfiltration shape). `warning` is the default for "under-supported but
+ * not obviously hostile". `info` is for advisory signal a calibrator may
+ * later promote or demote.
+ */
+export declare const SentinelSeveritySchema: z.ZodEnum<["info", "warning", "critical"]>;
+export type SentinelSeverity = z.infer<typeof SentinelSeveritySchema>;
+/**
+ * The payload of a `sentinel.alerted@1` event.
+ *
+ * `observed_event_ids` lists exactly the events the sentinel read to reach
+ * this conclusion; they are also the alert envelope's `causal_parent_ids`,
+ * so `lodestar report` can walk back from an alert to the events that
+ * triggered it.
+ *
+ * `detail` is rule-specific structured context (offending belief ids, the
+ * matched tool run, the confidence that tripped the floor, …). It is a
+ * record rather than a discriminated union so a new sentinel can ship
+ * without a core schema bump; the human-readable `message` is always
+ * present so an alert is legible without decoding `detail`.
+ *
+ * Every field is required (no optionals besides `rationale_id`) so the
+ * event-log writer's canonical hash and `JSON.stringify` never disagree on
+ * a dropped `undefined` key — the same discipline the firewall audit
+ * events follow.
+ */
+export declare const SentinelAlertPayloadSchema: z.ZodObject<{
+    alert_id: z.ZodString;
+    sentinel_name: z.ZodString;
+    rule: z.ZodString;
+    severity: z.ZodEnum<["info", "warning", "critical"]>;
+    subject: z.ZodObject<{
+        kind: z.ZodEnum<["belief", "action", "decision", "tool_sequence"]>;
+        id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        kind: "belief" | "decision" | "action" | "tool_sequence";
+    }, {
+        id: string;
+        kind: "belief" | "decision" | "action" | "tool_sequence";
+    }>;
+    message: z.ZodString;
+    observed_event_ids: z.ZodArray<z.ZodString, "many">;
+    detail: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    detected_at: z.ZodString;
+    /**
+     * Reserved. A sentinel may attach a generated Explanation id here, the
+     * way reflection proposals carry one. v0 sentinels rely on `message` +
+     * `detail` and leave this unset (omitted entirely, not `undefined`, so
+     * the canonical hash stays stable).
+     */
+    rationale_id: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    subject: {
+        id: string;
+        kind: "belief" | "decision" | "action" | "tool_sequence";
+    };
+    detail: Record<string, unknown>;
+    observed_event_ids: string[];
+    alert_id: string;
+    sentinel_name: string;
+    rule: string;
+    severity: "info" | "warning" | "critical";
+    detected_at: string;
+    rationale_id?: string | undefined;
+}, {
+    message: string;
+    subject: {
+        id: string;
+        kind: "belief" | "decision" | "action" | "tool_sequence";
+    };
+    detail: Record<string, unknown>;
+    observed_event_ids: string[];
+    alert_id: string;
+    sentinel_name: string;
+    rule: string;
+    severity: "info" | "warning" | "critical";
+    detected_at: string;
+    rationale_id?: string | undefined;
+}>;
+export type SentinelAlertPayload = z.infer<typeof SentinelAlertPayloadSchema>;
+/**
+ * Event-type literal and version. Use the constants rather than the bare
+ * string so a future rename is grep-safe — same convention as
+ * `REFLECTION_COMPLETED_EVENT_TYPE`.
+ */
+export declare const SENTINEL_ALERTED_EVENT_TYPE: "sentinel.alerted";
+export declare const SENTINEL_ALERTED_SCHEMA_VERSION: "1";
+//# sourceMappingURL=sentinel.d.ts.map

package/dist/schemas/sentinel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentinel.d.ts","sourceRoot":"","sources":["../../src/schemas/sentinel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;EAGhC,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,4CAA0C,CAAA;AAC7E,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAErE;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;IAkBrC;;;;;OAKG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEH,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAE7E;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,oBAA8B,CAAA;AACtE,eAAO,MAAM,+BAA+B,KAAe,CAAA"}

package/dist/schemas/sentinel.js

@@ -0,0 +1,97 @@
+import { z } from "zod";
+import { TimestampSchema } from "./common.js";
+/**
+ * Sentinel alerts — the wire format a Sentinel emits when it pattern-matches
+ * a suspicious shape in the event stream.
+ *
+ * Design lock: `docs/architecture/sentinels.md` (and Q7 of
+ * `docs/architecture/reflection-pass.md`, which settled the execution model).
+ * The short version:
+ *
+ * - Sentinels are an async tail of the event stream. They never block the
+ *   Action Kernel; they emit `sentinel.alerted@1` events and a future
+ *   (additive) `arbitrate` hook honours them on the *next* action that
+ *   depends on a flagged subject.
+ * - This is a governance event, not an Observation. Like
+ *   `reflection.completed@1`, the payload is the event payload directly and
+ *   is NOT registered in the observation schema registry.
+ *
+ * Core owns the wire format only. The base class, the runner, and the
+ * concrete sentinels live in `@qmilab/lodestar-harness`.
+ */
+/**
+ * What a sentinel alert is *about*. Kept deliberately small — the four
+ * epistemic-chain nouns a v0 sentinel can point at.
+ *
+ * `belief` is the load-bearing kind for the eventual kernel hook: the
+ * `arbitrate` lookup scopes recent alerts to a candidate action's
+ * `belief_dependencies`, so a sentinel that names a belief gates the next
+ * action that leans on it. `tool_sequence` is a synthetic subject — its
+ * `id` identifies the *completion* of a matched sequence (the id of the
+ * final action in the run), since no single chain-noun owns the pattern.
+ */
+export const SentinelSubjectSchema = z.object({
+    kind: z.enum(["belief", "action", "decision", "tool_sequence"]),
+    id: z.string().min(1),
+});
+/**
+ * Triage weight. `critical` is reserved for patterns that, left unflagged,
+ * map onto a concrete attack (e.g. the read → external-egress → write
+ * exfiltration shape). `warning` is the default for "under-supported but
+ * not obviously hostile". `info` is for advisory signal a calibrator may
+ * later promote or demote.
+ */
+export const SentinelSeveritySchema = z.enum(["info", "warning", "critical"]);
+/**
+ * The payload of a `sentinel.alerted@1` event.
+ *
+ * `observed_event_ids` lists exactly the events the sentinel read to reach
+ * this conclusion; they are also the alert envelope's `causal_parent_ids`,
+ * so `lodestar report` can walk back from an alert to the events that
+ * triggered it.
+ *
+ * `detail` is rule-specific structured context (offending belief ids, the
+ * matched tool run, the confidence that tripped the floor, …). It is a
+ * record rather than a discriminated union so a new sentinel can ship
+ * without a core schema bump; the human-readable `message` is always
+ * present so an alert is legible without decoding `detail`.
+ *
+ * Every field is required (no optionals besides `rationale_id`) so the
+ * event-log writer's canonical hash and `JSON.stringify` never disagree on
+ * a dropped `undefined` key — the same discipline the firewall audit
+ * events follow.
+ */
+export const SentinelAlertPayloadSchema = z.object({
+    alert_id: z.string().min(1),
+    sentinel_name: z.string().min(1).describe("Stable name of the emitting sentinel."),
+    rule: z
+        .string()
+        .min(1)
+        .describe("Stable id of the specific rule/pattern that fired within the sentinel."),
+    severity: SentinelSeveritySchema,
+    subject: SentinelSubjectSchema,
+    message: z.string().min(1).describe("Human-readable account of what tripped the sentinel."),
+    observed_event_ids: z
+        .array(z.string())
+        .min(1)
+        .describe("The events the sentinel read to reach this alert; also the alert's causal parents."),
+    detail: z
+        .record(z.string(), z.unknown())
+        .describe("Rule-specific structured context. May be empty; never undefined."),
+    detected_at: TimestampSchema,
+    /**
+     * Reserved. A sentinel may attach a generated Explanation id here, the
+     * way reflection proposals carry one. v0 sentinels rely on `message` +
+     * `detail` and leave this unset (omitted entirely, not `undefined`, so
+     * the canonical hash stays stable).
+     */
+    rationale_id: z.string().optional(),
+});
+/**
+ * Event-type literal and version. Use the constants rather than the bare
+ * string so a future rename is grep-safe — same convention as
+ * `REFLECTION_COMPLETED_EVENT_TYPE`.
+ */
+export const SENTINEL_ALERTED_EVENT_TYPE = "sentinel.alerted";
+export const SENTINEL_ALERTED_SCHEMA_VERSION = "1";
+//# sourceMappingURL=sentinel.js.map

package/dist/schemas/sentinel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentinel.js","sourceRoot":"","sources":["../../src/schemas/sentinel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC;IAC/D,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACtB,CAAC,CAAA;AAGF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAA;AAG7E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,uCAAuC,CAAC;IAClF,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CAAC,wEAAwE,CAAC;IACrF,QAAQ,EAAE,sBAAsB;IAChC,OAAO,EAAE,qBAAqB;IAC9B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,sDAAsD,CAAC;IAC3F,kBAAkB,EAAE,CAAC;SAClB,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SACjB,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CAAC,oFAAoF,CAAC;IACjG,MAAM,EAAE,CAAC;SACN,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/B,QAAQ,CAAC,kEAAkE,CAAC;IAC/E,WAAW,EAAE,eAAe;IAC5B;;;;;OAKG;IACH,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACpC,CAAC,CAAA;AAGF;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,kBAA2B,CAAA;AACtE,MAAM,CAAC,MAAM,+BAA+B,GAAG,GAAY,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qmilab/lodestar-core",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Schemas and types for the Lodestar epistemic chain. Part of Lodestar, the trust layer for AI agents.",
   "license": "Apache-2.0",
   "author": "QMI Lab <hello@qmilab.com>",
@@ -34,12 +34,7 @@
       "default": "./dist/index.js"
     }
   },
-  "files": [
-    "dist",
-    "src",
-    "README.md",
-    "LICENSE"
-  ],
+  "files": ["dist", "src", "README.md", "LICENSE"],
   "publishConfig": {
     "access": "public",
     "provenance": true

package/src/index.ts

@@ -28,5 +28,23 @@ export * from "./schemas/revision.js"
 // Event log envelope
 export * from "./schemas/event.js"
 
+// Reflection (Batch 4) — proposals and the reflection.completed@1 payload
+export * from "./schemas/reflection.js"
+
+// Calibration — the report wire format + the calibration.computed@1 payload
+export * from "./schemas/calibration.js"
+
+// Probe pack format (Batch 4) — the lodestar.probe-pack.json manifest contract
+export * from "./schemas/probe-pack.js"
+
+// Sentinels (Batch 4) — the sentinel.alerted@1 alert wire format
+export * from "./schemas/sentinel.js"
+
+// Action policy (Policy Kernel) — the Policy / PolicyRule document wire format
+export * from "./schemas/policy.js"
+
+// Approval workflow (Policy Kernel) — ApprovalRequest + approval.* event payloads
+export * from "./schemas/approval.js"
+
 // Schema registry
 export * as registry from "./registry.js"

package/src/schemas/action.ts

@@ -60,10 +60,27 @@ export type ActionContract = z.infer<typeof ActionContractSchema>
 
 /**
  * Phases an action passes through.
+ *
+ * `pending_approval` is the parked state: arbitration returned a `hold`
+ * (the Policy Kernel's three-valued verdict — see
+ * `docs/architecture/policy-kernel.md`), so the action is neither approved
+ * nor rejected. An `ApprovalRequest` is opened and the world stays
+ * untouched — the two-phase discipline forbids `execute()` from
+ * `pending_approval` exactly as it forbids it from `proposed`. Only an
+ * Action-Kernel `resolve()` un-parks it: `approval.granted` → `approved`
+ * (which then runs the normal `execute()` gate, so TOCTOU revalidation
+ * still fires), `approval.denied` / `approval.expired` → `rejected`.
+ *
+ * Distinct from `halted`, which is a *terminal* mid-execution stop
+ * (`executing → halted`); `pending_approval` is a *pre-execution* wait.
+ *
+ * Additive (ratified 2026-06-03, `policy-kernel.md`): existing logs
+ * without this value still parse; readers gain one case.
  */
 export const ActionPhaseSchema = z.enum([
   "proposed",
   "arbitrating",
+  "pending_approval",
   "approved",
   "rejected",
   "executing",
@@ -100,7 +117,9 @@ export type AuditEvent = z.infer<typeof AuditEventSchema>
  *
  * Actions are the seventh link in the epistemic chain.
  * The phase field tracks the action through propose → arbitrate
- * → approved/rejected → executing → completed/failed/halted.
+ * → approved/rejected/pending_approval → executing
+ * → completed/failed/halted. A `pending_approval` action awaits an
+ * `ApprovalRequest` resolution before it can reach `approved`.
  *
  * Every Action carries an ActionContract. The Policy Kernel evaluates
  * the contract against current trust assignments and approval requirements

package/src/schemas/approval.ts

@@ -0,0 +1,136 @@
+import { z } from "zod"
+import { SignatureSchema } from "./actor.js"
+import { TimestampSchema } from "./common.js"
+import { RequiredAuthoritySchema } from "./policy.js"
+
+/**
+ * The approval workflow wire formats — the first-class record of an action
+ * parked at `pending_approval` and the events that resolve it.
+ *
+ * Design lock: `docs/architecture/policy-kernel.md`, "The approval workflow".
+ * The discipline mirrors the sentinel / reflection governance events:
+ *
+ * - These are governance events, NOT Observations. Like `sentinel.alerted@1`,
+ *   each payload is the event payload directly and is NOT registered in the
+ *   observation schema registry.
+ * - Grant and deny are *distinct event types*, not one event with an
+ *   `approved` flag. The type *is* the verdict, so a redundant boolean (which
+ *   could disagree with the type on re-read) is omitted. When the resolution
+ *   folds back into the action via the Action Kernel's `resolve()`, it lands
+ *   in the action's existing `approval` field (`ApprovalEvent`), where a
+ *   single boolean is the natural shape — so the stream view
+ *   (type-discriminated) and the single-action view agree without duplicating
+ *   the verdict on the wire.
+ * - No optional field is ever set to `undefined` — it is omitted entirely when
+ *   unset (`deadline` and `reason` in particular), so the event-log writer's
+ *   `canonicalHash` (undefined → null) and `JSON.stringify` (drops the key)
+ *   cannot disagree on re-read.
+ *
+ * Core owns the wire format only. The lifecycle manager — opening a request on
+ * a hold, matching a resolution against `required_authority`, driving the
+ * Action-Kernel `resolve()` transition — lives in
+ * `@qmilab/lodestar-policy-kernel`.
+ */
+
+/**
+ * The payload of an `approval.requested@1` event: a parked action awaiting a
+ * human (or auto-rule) verdict. `reason` is the matched rule's reason,
+ * verbatim. `required_authority` says what an approver must be (checked
+ * against the resolver's `Actor`); an empty object means any configured
+ * resolver may approve.
+ *
+ * `deadline` is the proxy's hold timeout (the MCP path cannot hold a
+ * `tools/call` open indefinitely without tripping client timeouts); it is
+ * *omitted entirely* in the in-process `guard.wrap()` path, where a hold can
+ * simply await the resolver — never set to `undefined`.
+ */
+export const ApprovalRequestSchema = z.object({
+  request_id: z.string().min(1),
+  action_id: z.string().min(1).describe("the parked action, at phase pending_approval"),
+  reason: z.string().min(1).describe("the matched rule's reason, verbatim"),
+  required_authority: RequiredAuthoritySchema.describe(
+    "what an approver must be; checked against the resolver's Actor. Empty object = any configured resolver",
+  ),
+  requested_at: TimestampSchema,
+  deadline: TimestampSchema.optional().describe(
+    "ISO 8601 hold timeout (proxy path); omitted entirely in-process, never undefined",
+  ),
+})
+export type ApprovalRequest = z.infer<typeof ApprovalRequestSchema>
+
+/**
+ * The payload of an `approval.granted@1` event. The event *type* is the
+ * verdict — there is no `approved` boolean. `reason` (the approver's note) is
+ * omitted entirely when unset.
+ *
+ * `signature` is an optional Ed25519 signature over the canonical resolution
+ * document (`{ request_id, action_id, kind, approver_id, reason?, at }`),
+ * produced by the approver's private key. When present it makes the granted
+ * event **self-verifying in the log**: a reader can later re-check the grant
+ * came from an operator-pinned approver key, not merely trust that the proxy
+ * verified it at promotion time. Its `signer_id` equals `approver_id` (the same
+ * actor that resolved). Omitted entirely when unset (never `undefined`), so the
+ * canonical-hash discipline above carries through; the cross-process proxy path
+ * requires it (a forged side-channel grant cannot un-park an action), while the
+ * in-process resolver path may omit it (same trusted process, no forgery
+ * surface). Hash + verification live in `@qmilab/lodestar-policy-kernel`.
+ */
+export const ApprovalGrantedPayloadSchema = z.object({
+  request_id: z.string().min(1),
+  action_id: z.string().min(1),
+  approver_id: z.string().min(1).describe("actor_id of the resolver"),
+  reason: z.string().min(1).optional().describe("approver's note; omitted entirely when unset"),
+  at: TimestampSchema,
+  signature: SignatureSchema.optional().describe(
+    "Ed25519 signature over the canonical resolution; signer_id === approver_id; omitted entirely when unset",
+  ),
+})
+export type ApprovalGrantedPayload = z.infer<typeof ApprovalGrantedPayloadSchema>
+
+/**
+ * The payload of an `approval.denied@1` event. Identical shape to
+ * `approval.granted@1` — the verdict is carried by the event type, not a
+ * field. Defined as its own schema (rather than re-exporting one shared
+ * object) so the two event types stay independently evolvable. `signature`
+ * follows the same contract as the grant payload (a denial is also authority-
+ * bearing — it must not be forgeable into un-holding via a later grant either).
+ */
+export const ApprovalDeniedPayloadSchema = z.object({
+  request_id: z.string().min(1),
+  action_id: z.string().min(1),
+  approver_id: z.string().min(1).describe("actor_id of the resolver"),
+  reason: z.string().min(1).optional().describe("approver's note; omitted entirely when unset"),
+  at: TimestampSchema,
+  signature: SignatureSchema.optional().describe(
+    "Ed25519 signature over the canonical resolution; signer_id === approver_id; omitted entirely when unset",
+  ),
+})
+export type ApprovalDeniedPayload = z.infer<typeof ApprovalDeniedPayloadSchema>
+
+/**
+ * The payload of an `approval.expired@1` event: the deadline passed with no
+ * human resolution. Carries no `approver_id` — no actor resolved it; the
+ * passage of the deadline did. The Action Kernel transitions the parked action
+ * to `rejected` on receipt (a timed-out hold is a soft denial the agent
+ * re-proposes; durable resume is deferred — `policy-kernel.md`).
+ */
+export const ApprovalExpiredPayloadSchema = z.object({
+  request_id: z.string().min(1),
+  action_id: z.string().min(1),
+  at: TimestampSchema,
+})
+export type ApprovalExpiredPayload = z.infer<typeof ApprovalExpiredPayloadSchema>
+
+/**
+ * Event-type literals and versions. Use the constants rather than the bare
+ * strings so a future rename is grep-safe — same convention as
+ * `SENTINEL_ALERTED_EVENT_TYPE` and `REFLECTION_COMPLETED_EVENT_TYPE`.
+ */
+export const APPROVAL_REQUESTED_EVENT_TYPE = "approval.requested" as const
+export const APPROVAL_REQUESTED_SCHEMA_VERSION = "1" as const
+export const APPROVAL_GRANTED_EVENT_TYPE = "approval.granted" as const
+export const APPROVAL_GRANTED_SCHEMA_VERSION = "1" as const
+export const APPROVAL_DENIED_EVENT_TYPE = "approval.denied" as const
+export const APPROVAL_DENIED_SCHEMA_VERSION = "1" as const
+export const APPROVAL_EXPIRED_EVENT_TYPE = "approval.expired" as const
+export const APPROVAL_EXPIRED_SCHEMA_VERSION = "1" as const

package/src/schemas/belief.ts

@@ -19,7 +19,13 @@ import {
 export const TruthStatusSchema = z.enum(["unverified", "supported", "contradicted", "superseded"])
 export type TruthStatus = z.infer<typeof TruthStatusSchema>
 
-export const RetrievalStatusSchema = z.enum(["hidden", "restricted", "normal", "privileged_only", "blocked"])
+export const RetrievalStatusSchema = z.enum([
+  "hidden",
+  "restricted",
+  "normal",
+  "privileged_only",
+  "blocked",
+])
 export type RetrievalStatus = z.infer<typeof RetrievalStatusSchema>
 
 export const SecurityStatusSchema = z.enum(["clean", "suspicious", "quarantined", "malicious"])