@ego-z/contracts 0.11.2 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ego-z/contracts",
-  "version": "0.11.2",
+  "version": "0.13.0",
   "description": "Wire-format type contracts shared between EgoZ backend, SDK, MCP and console. Type-only — no runtime artifacts.",
   "types": "./src/index.d.ts",
   "exports": {
@@ -15,7 +15,9 @@
     "NOTICE"
   ],
   "scripts": {
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "check:consumers": "node scripts/check-consumer-ranges.js",
+    "prepublishOnly": "npm run check:consumers"
   },
   "keywords": [
     "egoz",

package/src/controlled.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @ego-z/contracts — controlled orchestration mode.
+ *
+ * Wire vocabulary for the staged turn machine. Everything here is metadata:
+ * stage names, outcomes, counts, timings, a verdict and a score. The plan's
+ * `evidenceQueries` strings NEVER cross the wire and are never persisted.
+ */
+
+// ============================================================================
+// Locked vocabularies. THIS FILE IS THEIR ONLY DECLARATION — 02/03/04/05/07/08
+// cite it, none of them restate it. VerifyMode (050), VerifyVerdict (051, on
+// egoz_eval_results.verdict only), VerifyCheck (051, containment check on
+// egoz_eval_results.failed_checks), EvalRunMode (051) and EvalRunStatus (051)
+// have a DB CHECK; the rest are JSONB keys / wire enums (D16).
+// OrchestrationMode and MessageFailureReason are CHECKed too but are declared
+// elsewhere — OrchestrationMode in tenant.d.ts — so this file does not own them.
+// ============================================================================
+
+/** Mirrors `egoz_tenant_configs.verify_mode` CHECK (migration 050). */
+export type VerifyMode = 'off' | 'observe' | 'enforce';
+
+/** The nine canonical stages, in execution order. */
+export type ControlledStage =
+    | 'admit' | 'assess' | 'retrieve' | 'rank' | 'compose'
+    | 'execute' | 'verify' | 'repair' | 'finalize';
+
+/**
+ * What happened to a stage. SPLIT from the *reason* deliberately: fusing them
+ * (`'skipped_budget' | 'skipped_voice' | …`) makes "degradation rate by reason"
+ * unqueryable from JSONB without a LIKE on the enum, and it makes every new
+ * reason a change to the outcome vocabulary. `outcome` answers "did it run",
+ * `reason` answers "why not" — see `StageSkipReason`.
+ *
+ * `short_circuited` is a REASON, not an outcome: an extension hook returning a
+ * result means the stage did not run, which is `'skipped'`.
+ */
+export type ControlledStageOutcome = 'ran' | 'skipped' | 'degraded' | 'aborted';
+
+/** Present iff `outcome` is `'skipped'` or `'degraded'`. Never on `'ran'`. */
+export type StageSkipReason =
+    | 'budget_exhausted'    // wall-clock or assist-call budget spent
+    | 'voice_mode'          // voiceMode reduced path (D5)
+    | 'plan_not_required'   // the TurnPlan said this stage is unnecessary
+    | 'config_off'          // verify_mode='off', ragEnabled=false, …
+    | 'short_circuited'     // an extension hook returned a result
+    | 'parse_failed'        // assist model returned prose; fell back to a default
+    | 'provider_error';     // the assist call itself failed
+
+/** Mirrors `egoz_eval_results.verdict` CHECK (migration 051). */
+export type VerifyVerdict = 'pass' | 'repairable' | 'degraded';
+
+export type VerifyCheck =
+    | 'schema' | 'tool_honesty' | 'plan_completion' | 'grounding';
+
+export type TurnComplexity = 'trivial' | 'standard' | 'complex';
+
+/**
+ * Mirrors `egoz_eval_runs.mode` CHECK (migration 051). `dry` stubs every tool
+ * call from the case fixture; `live` executes for real. Anything that defaults
+ * this value defaults it to `'dry'`.
+ */
+export type EvalRunMode = 'dry' | 'live';
+
+/** Mirrors `egoz_eval_runs.status` CHECK (migration 051). */
+export type EvalRunStatus =
+    | 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
+
+// ============================================================================
+// Wire shapes
+// ============================================================================
+
+/** Routing decision from `assess`. `evidenceQueries` is deliberately absent. */
+export interface TurnPlanWire {
+    complexity: TurnComplexity;
+    needsEvidence: boolean;
+    needsTools: boolean;
+    verify: 'none' | 'schema' | 'grounding';
+}
+
+export interface ControlledStageReport {
+    name: ControlledStage;
+    ms: number;
+    outcome: ControlledStageOutcome;
+    /** Why it did not run. Present iff outcome is 'skipped' or 'degraded'. */
+    reason?: StageSkipReason;
+}
+
+/**
+ * Per-turn controlled-mode report. Mirrors `egoz_messages.metadata.controlled`
+ * exactly, so the wire and the durable record can never drift.
+ *
+ * THIS INTERFACE IS THE COMPLETE KEY SET. `metadata.controlled` is the always-on
+ * durable channel (D12) and `GET_CONTROLLED_SUMMARY`
+ * (`07-observability-and-evaluation.md`) reads it by literal JSONB key — a metric
+ * that reads a key not declared here returns NULL for every row, silently. Docs
+ * 03/05/07/08 cite this type; they do not maintain parallel key lists.
+ *
+ * WHY SO MANY OPTIONALS: the batch that produces a field ships after the batch
+ * that publishes this type. `stages` is the only key a controlled turn can
+ * always produce (B2). `plan` / `assistCalls` / `assistTokens` arrive with
+ * `assess` (B3); the chunk counts with `retrieve`/`rank` (B4); the verdict block
+ * with `verify` (B5); the repair block with `repair` (B6). They are optional
+ * because they are genuinely ABSENT, not zero — 07's metric 7
+ * (`chunksKept / chunksRetrieved`) and metric 4 (`assistTokens / total_tokens`)
+ * cannot tell a stamped placeholder from a measurement, so a required field
+ * would enter every turn in the B2→B4 window into those metrics as fabricated
+ * data. `IS NULL` separates "that batch had not shipped" from "we retrieved
+ * nothing"; `= 0` does not.
+ */
+export interface ControlledTurnMeta {
+    /** Absent until B3 — a turn with no `assess` stage has no plan, not an empty one. */
+    plan?: TurnPlanWire;
+    /** Always present on a controlled turn: all nine stages, in order (D12). */
+    stages: ControlledStageReport[];
+
+    /** How many evidence queries `assess` produced (0-3). COUNT ONLY (D17). */
+    evidenceQueries?: number;
+    /** Raw chunks returned by `retrieve` across all queries, pre-`rank`. */
+    chunksRetrieved?: number;
+    /**
+     * Chunks that survived `rank`'s dedup + cap and entered the prompt.
+     * The canonical name for what 07's metric 7 calls "evidence yield"
+     * (`chunksKept / chunksRetrieved`) and what 03 drafted as `evidenceChunks`.
+     * Counted separately from the existing `kbSearchCalls` / `kbChunksUsed`,
+     * which stay the KB-tool-during-`execute` counters.
+     */
+    chunksKept?: number;
+
+    /** LLM calls made by assess + verify + repair-critique. Bounded at 3. */
+    assistCalls?: number;
+    assistTokens?: number;
+    /** Resolved assist model id. Absent when it fell back to the main model. */
+    assistModel?: string;
+
+    verdict?: VerifyVerdict;
+    /** 0..1 from `computeVerdictScore`. Absent when verify_mode = 'off'. */
+    score?: number;
+    /** Named `failedChecks` everywhere. Not `checksFailed`. */
+    failedChecks?: VerifyCheck[];
+
+    /** True when one bounded repair attempt ran (enforce mode only). */
+    repaired?: boolean;
+    /** Which check drove the repair. Absent when `repaired` is false. */
+    repairReason?: VerifyCheck;
+}

package/src/index.d.ts

@@ -92,3 +92,4 @@ export * from './thread';
 export * from './personality';
 export * from './user-memory';
 export * from './search';
+export * from './controlled';

package/src/stream.d.ts

@@ -55,6 +55,24 @@ export interface AskStreamDeltaEvent {
     type: 'delta';
     /** Token (or token-like fragment) appended to the running answer. */
     content: string;
+    /**
+     * Whether this delta is part of the model's pre-tool narration
+     * ('thinking' — text emitted by an iteration that also asked for a
+     * tool call) or the terminal reply ('final' — the last iteration's
+     * text, no further tool calls follow).
+     *
+     * Consumers can use this to render two channels: a secondary
+     * "thinking out loud" strip and the primary answer body. A single
+     * 'thinking' iteration streams live token-by-token; the 'final'
+     * delta is flushed as one event at iteration end so its label is
+     * known when it lands (the alternative would be a post-hoc
+     * correction event, which was rejected).
+     *
+     * Optional so a consumer pinned to an older contract version still
+     * parses the frame. Absent only on the pre-phase emit sites that
+     * predate the field.
+     */
+    phase?: 'thinking' | 'final';
 }
 
 export interface AskStreamToolCallingEvent {

package/src/tenant.d.ts

@@ -59,6 +59,24 @@ export type TenantStatus =
     | 'suspended'
     | 'terminated';
 
+/**
+ * Per-tenant `/ask` pipeline (mirrors `egoz_tenant_configs.orchestration_mode`
+ * CHECK constraint, migrations 022 + 050). Promoted here from
+ * `backend/egoz/modules/tenant-config/interfaces.ts` in B1 (D15) so the backend,
+ * the console, the SDK and MCP stop hand-copying the literal pair.
+ *
+ * - `classic`    — rule intent classifier + pre-fetched RAG. The DB default;
+ *                  no tenant moves off it automatically.
+ * - `agentic`    — single base prompt, KB offered as a tool, LLM-driven
+ *                  retrieval (Phase 10).
+ * - `controlled` — the nine-stage machine: admit → assess → retrieve → rank →
+ *                  compose → execute → verify → repair → finalize.
+ *
+ * Widening this union is additive for producers and breaking for a consumer
+ * doing an exhaustive `never` switch — which is why it moved as a minor bump.
+ */
+export type OrchestrationMode = 'classic' | 'agentic' | 'controlled';
+
 /**
  * Billing plan (Phase 1.5, two-plan model — migration 035). Drives usage
  * quotas (e.g. monthly /ask limit).