@ego-z/contracts 0.11.0

package/src/tenant.d.ts

@@ -0,0 +1,222 @@
+/**
+ * @ego-z/contracts — `/egoz/tenants/*` wire types (project CRUD).
+ *
+ * `Tenant` is what the Console calls "Project" — same row, two names.
+ * The wire shape preserves `snake_case` field names because that's the
+ * actual JSON the backend has always emitted and the console has always
+ * consumed. Renaming to camelCase here would be a breaking wire change
+ * (every API caller would need to update) and is deliberately out of
+ * scope for the additive Phase 9 sweep. If/when we ever do that
+ * migration, this is the file the major-version bump touches.
+ *
+ * Drift cleaned up:
+ *   - Backend `Tenant` used `Date` for `created_at` / `updated_at` /
+ *     `attestation_signed_at`; wire and console already used ISO
+ *     strings. Backend `formatTenant` now emits ISO via the same
+ *     pattern as Tools and RAG.
+ */
+
+// ============================================================================
+// Locked vocabularies (mirror DB CHECK constraints)
+// ============================================================================
+
+/**
+ * Compliance tier (mirrors `egoz_tenants.compliance_tier` CHECK
+ * constraint, migration 010). Phase 1 services `'standard'` only;
+ * the rest are forward-compat for Phase 2.
+ */
+export type ComplianceTier =
+    | 'standard'
+    | 'pending_review'
+    | 'gdpr'
+    | 'hipaa'
+    | 'enterprise'
+    | 'pending_upgrade';
+
+/**
+ * Data residency region (mirrors `egoz_tenants.data_residency_region`
+ * CHECK constraint, migration 010). Phase 1 deploys only to
+ * `'eu-west'`; the rest are forward-compat.
+ */
+export type DataResidencyRegion =
+    | 'us-east'
+    | 'us-west'
+    | 'eu-west'
+    | 'eu-central'
+    | 'ap-south'
+    | 'ap-east';
+
+/**
+ * Operational tenant status (mirrors `egoz_tenants.status` CHECK
+ * constraint). The legacy `is_active` boolean still exists in
+ * Phase 1 and is NOT auto-synced with `status` — both fields are
+ * independent until Phase 1.5 deprecates `is_active`.
+ */
+export type TenantStatus =
+    | 'active'
+    | 'pending_review'
+    | 'flagged'
+    | 'suspended'
+    | 'terminated';
+
+/**
+ * Billing plan (Phase 1.5, two-plan model — migration 035). Drives usage
+ * quotas (e.g. monthly /ask limit).
+ *
+ *   - `id_ego`   — "Id Ego": free, pay-as-you-go via BYOK, capped limits.
+ *                  Default for self-service signup.
+ *   - `superego` — "Superego": $20/mo, higher (but still capped) limits.
+ */
+export type TenantPlan = 'id_ego' | 'superego';
+
+/**
+ * Industry classification driving the signup gate (Phase 1.5+).
+ * The regulated entries (`'healthcare'`, `'finance'`, `'insurance'`,
+ * `'government'`, `'legal'`) auto-route new tenants to
+ * `status: 'pending_review'`.
+ */
+export type TenantIndustry =
+    | 'saas'
+    | 'ecommerce'
+    | 'marketing'
+    | 'education'
+    | 'media'
+    | 'travel'
+    | 'real_estate'
+    | 'productivity'
+    | 'other'
+    | 'healthcare'
+    | 'finance'
+    | 'insurance'
+    | 'government'
+    | 'legal';
+
+// ============================================================================
+// TenantWire — the canonical row shape (snake_case on the wire)
+// ============================================================================
+
+/**
+ * Wire-format tenant row. Returned by every `/egoz/tenants/*` response.
+ *
+ * **Field naming.** This is the only wire shape in the contracts
+ * package that uses `snake_case`. It's preserved verbatim from the
+ * legacy backend → JSON path because the Console already consumes
+ * `snake_case` here too. Treat the inconsistency as fixed-by-history,
+ * not a goal — net change would be breaking, with zero behavioural
+ * value.
+ */
+export interface TenantWire {
+    id: string;
+    name: string;
+    /** URL-safe slug, unique per parent (when `parent_tenant_id` is set). */
+    slug: string;
+    description?: string;
+    is_active: boolean;
+    /** ISO 8601 timestamp. */
+    created_at: string;
+    /** ISO 8601 timestamp. */
+    updated_at: string;
+
+    // Phase 1 compliance posture (migration 010) ----------------------
+    compliance_tier: ComplianceTier;
+    data_residency_region: DataResidencyRegion;
+    /**
+     * UUID of the parent tenant when this row is a sub-project. `null`
+     * for top-level tenants. Sub-projects share their parent's
+     * `compliance_tier` for billing purposes (enforced at the service
+     * layer, not the DB).
+     */
+    parent_tenant_id: string | null;
+    industry: TenantIndustry | null;
+    /** ISO 8601 timestamp. `null` until the operator signs an attestation. */
+    attestation_signed_at: string | null;
+    attestation_version: string | null;
+    status: TenantStatus;
+    /** Billing plan (migrations 023/035). Drives usage quotas. Default 'id_ego'. */
+    plan: TenantPlan;
+
+    // Time-boxed debug mode (migration 037). Populated on the LIST response
+    // (joined from tenant_configs); omitted where the query does not join it.
+    // `debug_enabled` is resolved server-side as `debug_until > NOW()`.
+    debug_enabled?: boolean;
+    /** ISO 8601 expiry backing `debug_enabled`; null when off/expired. */
+    debug_until?: string | null;
+}
+
+// ============================================================================
+// Request bodies (what the client SENDS)
+// ============================================================================
+
+/**
+ * Wire body of `POST /egoz/tenants`.
+ *
+ * Notable absences:
+ *   - `compliance_tier`, `status`     — server-derived from `industry`
+ *                                       at signup (Phase 1C / Strategy A).
+ *                                       Non-regulated industry →
+ *                                       `'standard'` + `'active'`;
+ *                                       regulated industry (healthcare,
+ *                                       finance, insurance, government,
+ *                                       legal) → `'pending_review'` on
+ *                                       both. Manual tier moves stay an
+ *                                       admin operation via
+ *                                       `TenantUpdateBody`.
+ *   - `is_active`, timestamps         — server-managed.
+ */
+export interface TenantCreateBody {
+    name: string;
+    slug?: string;
+    description?: string;
+
+    industry?: TenantIndustry;
+    data_residency_region?: DataResidencyRegion;
+    parent_tenant_id?: string | null;
+    /** ISO 8601 timestamp string the operator submits at signup. */
+    attestation_signed_at?: string;
+    attestation_version?: string;
+}
+
+/**
+ * Wire body of `PUT /egoz/tenants/:tenantId`. Every field is optional —
+ * the backend applies `COALESCE`-style partial updates. `tenantId` is
+ * the URL param, not the body.
+ *
+ * `compliance_tier` and `status` are admin operations; Phase 1 has no
+ * role gating on these — Phase 1.5 will introduce admin-only
+ * enforcement.
+ */
+export interface TenantUpdateBody {
+    name?: string;
+    description?: string;
+    is_active?: boolean;
+
+    industry?: TenantIndustry;
+    data_residency_region?: DataResidencyRegion;
+    parent_tenant_id?: string | null;
+    compliance_tier?: ComplianceTier;
+    status?: TenantStatus;
+    attestation_signed_at?: string;
+    attestation_version?: string;
+}
+
+// ============================================================================
+// Response data shapes (carried inside `EgozApiResponse.data`)
+// ============================================================================
+
+export interface TenantListResponseData {
+    tenants: TenantWire[];
+}
+
+export interface TenantGetResponseData {
+    tenant: TenantWire;
+}
+
+/**
+ * Returned by `POST /egoz/tenants`. Wrapping the row in `tenant`
+ * (rather than returning it raw) matches the rest of the create
+ * surfaces and keeps room for additive metadata (creation source,
+ * downstream side effects, …) without a major version bump.
+ */
+export interface TenantCreatedResponseData {
+    tenant: TenantWire;
+}

package/src/thread.d.ts

@@ -0,0 +1,248 @@
+/**
+ * @ego-z/contracts — `/egoz/threads/*` and
+ * `/egoz/tenants/:tenantId/threads/*` wire types.
+ *
+ * The conversation memory surface. `Thread` rows are produced by every
+ * `/ask` turn (via `ThreadService.getOrCreateThread`) and read back
+ * via the admin threads list / detail routes.
+ *
+ * Phase 6's `externalThreadId` already lives in `AskRequestBody` /
+ * `AskResponseData` / `AskStreamDoneEvent` (in `ask.d.ts` /
+ * `stream.d.ts`). This file lifts the FULL `Thread` and `Message`
+ * row shapes — what the threads-admin endpoints return — into the
+ * contracts package so the console mirror can't drift.
+ *
+ * Drift cleaned up:
+ *   - Backend `Thread` and `Message` used `Date` for `createdAt` /
+ *     `updatedAt`; wire and console already used ISO strings.
+ *     `formatThread` and `formatMessage` now emit ISO to match.
+ */
+
+import type { Intent } from './envelope';
+
+// ============================================================================
+// Locked vocabularies
+// ============================================================================
+
+/** Role of a message in the conversation turn. */
+export type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+
+/**
+ * Why a turn was stamped with `failedRecovery: true` by the
+ * orchestrator. Mirrors the CHECK constraint on
+ * `egoz_messages.failure_reason` (migration 014, Phase 5 / Layer 5).
+ * Adding a new entry requires a migration + orchestrator change in
+ * lockstep — the audit field exists to be queryable, not free-form.
+ */
+export type MessageFailureReason =
+    | 'tool_retry_storm'
+    | 'iteration_cap'
+    | 'max_calls_per_turn'
+    | 'unrecoverable_error';
+
+// ============================================================================
+// Supporting shapes
+// ============================================================================
+
+/**
+ * Tool-call request emitted by an `assistant` message. Shape matches
+ * the OpenAI Chat Completions tool-call envelope verbatim — that's
+ * what the orchestrator persists. `arguments` is a JSON string the
+ * caller must `JSON.parse` if they want the structured value;
+ * EgoZ doesn't decode it on the wire because it's already
+ * round-tripped through the LLM as text.
+ */
+export interface ToolCallWire {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+
+// ============================================================================
+// ThreadWire — the canonical row shape
+// ============================================================================
+
+/**
+ * Wire-format thread row. Returned by every threads-admin response and
+ * embedded in `ThreadWithMessagesWire`.
+ *
+ * `externalThreadId` is populated when the caller supplied one on the
+ * `/ask` that minted the row (Phase 6); `null` for legacy threads and
+ * for any caller that uses only the EgoZ UUID path.
+ */
+export interface ThreadWire {
+    id: string;
+    tenantId: string;
+    externalUserId: string | null;
+    /**
+     * Consumer-supplied conversation identifier (Phase 6). `null` for
+     * threads created before the column existed and for any caller
+     * that didn't supply one. Uniqueness is enforced per
+     * `(tenantId, externalThreadId)` among non-NULL rows by the
+     * `idx_egoz_threads_tenant_ext` partial unique index — see
+     * migration 017.
+     */
+    externalThreadId: string | null;
+    title: string | null;
+    metadata: Record<string, unknown>;
+    isActive: boolean;
+    /** ISO 8601 timestamp. */
+    createdAt: string;
+    /** ISO 8601 timestamp. */
+    updatedAt: string;
+}
+
+/**
+ * Thread row plus aggregate stats. Returned by the admin threads list
+ * endpoint so the operator-facing table can sort by activity without
+ * an N+1 fetch.
+ */
+export interface ThreadWithStatsWire extends ThreadWire {
+    messageCount: number;
+    totalTokens: number;
+}
+
+// ============================================================================
+// MessageWire — the canonical message-row shape
+// ============================================================================
+
+/**
+ * Wire-format message row. Carries the full per-turn audit trail —
+ * the LLM iteration's prompt/completion token split, the model id,
+ * the intent classification, the RAG context that was injected, and
+ * the Phase 5 failure-recovery flags.
+ *
+ * `toolCalls` is populated only on `role: 'assistant'` rows that
+ * requested a tool. `toolCallId` + `toolName` are populated only on
+ * `role: 'tool'` result rows.
+ */
+export interface MessageWire {
+    id: string;
+    threadId: string;
+    tenantId: string;
+    role: MessageRole;
+    content: string | null;
+    toolCalls: ToolCallWire[] | null;
+    toolCallId: string | null;
+    toolName: string | null;
+    intent: Intent | null;
+    ragContext: Record<string, unknown> | null;
+    promptTokens: number | null;
+    completionTokens: number | null;
+    totalTokens: number | null;
+    model: string | null;
+    /** Echo of `AskRequestBody.metadata` for audit. */
+    metadata: Record<string, unknown> | null;
+    /**
+     * `true` when this row's `content` was deliberately dropped under
+     * no-store (metadata-only) persistence — see
+     * `AskRequestBody.noStore` and the tenant's `persistMessageContent`
+     * setting (#5). Distinguishes an intentional NULL (the conversation
+     * text was never stored) from an incidental empty turn. Always
+     * `false` for tenants that persist content normally.
+     */
+    contentRedacted: boolean;
+    /**
+     * `true` when this turn triggered a Phase 5 tool-retry-storm
+     * backstop (dedup ≥ MAX_DUPLICATE_CALLS_BEFORE_FLAG / per-tool
+     * cap / outer iteration cap) or ended on an unrecoverable error
+     * class. Always `false` for non-assistant rows. Phase 5 /
+     * Layer 5 — drives the Tool Health "bad turns" filter.
+     */
+    failedRecovery: boolean;
+    /**
+     * Dominant cause when `failedRecovery === true`. `null`
+     * otherwise. See `MessageFailureReason` for the locked
+     * vocabulary.
+     */
+    failureReason: MessageFailureReason | null;
+    /**
+     * Manual operator incident flag on this turn — the CURRENT state
+     * (latest by `flaggedAt`; at most one `open` at a time). `null`/absent
+     * when the turn was never flagged. Additive (v0.5.2); populated only by
+     * the thread-detail read path, never on the /ask hot path. See
+     * `MessageIncidentWire`.
+     */
+    incident?: MessageIncidentWire | null;
+    /** ISO 8601 timestamp. */
+    createdAt: string;
+}
+
+/**
+ * Returned by the thread-detail endpoint. The full conversation —
+ * row + every message in chronological order.
+ */
+export interface ThreadWithMessagesWire {
+    thread: ThreadWire;
+    messages: MessageWire[];
+}
+
+// ============================================================================
+// Response data shapes (carried inside `EgozApiResponse.data`)
+// ============================================================================
+
+export interface ThreadListResponseData {
+    threads: ThreadWithStatsWire[];
+}
+
+export interface ThreadGetResponseData extends ThreadWithMessagesWire {}
+
+// ============================================================================
+// Message incidents — manual operator flagging of a turn
+//
+// The manual counterpart to the auto-set `failedRecovery`/`failureReason`
+// "bad turn" flags: an operator reviewing a conversation can flag a single
+// turn as an incident (with a reason + optional note), then later resolve it.
+// Metadata only — never message content. Stored in `egoz_message_incidents`
+// (migration 040); at most one `open` incident per message.
+// ============================================================================
+
+/**
+ * Why an operator flagged a turn. Locked vocabulary — mirrors the
+ * migration-040 CHECK constraint; adding a value requires a migration + this
+ * type in lockstep so the UI, filter SQL and DB can't drift.
+ */
+export type MessageIncidentReason =
+    | 'wrong_answer'
+    | 'hallucination'
+    | 'tool_failure'
+    | 'unsafe_content'
+    | 'policy_violation'
+    | 'other';
+
+/** Incident lifecycle. `open` on flag; `resolved` once an operator clears it. */
+export type MessageIncidentStatus = 'open' | 'resolved';
+
+/** A manual incident flag raised on a single message/turn. Metadata only. */
+export interface MessageIncidentWire {
+    id: string;
+    tenantId: string;
+    threadId: string;
+    messageId: string;
+    reason: MessageIncidentReason;
+    /** Optional free-text note from the operator who flagged. */
+    note: string | null;
+    status: MessageIncidentStatus;
+    /** User id who flagged (from the validated session), when known. */
+    flaggedBy: string | null;
+    /** ISO 8601 timestamp. */
+    flaggedAt: string;
+    /** User id who resolved; `null` while open. */
+    resolvedBy: string | null;
+    /** ISO 8601 timestamp; `null` while open. */
+    resolvedAt: string | null;
+}
+
+/** Body for `POST …/threads/:threadId/messages/:messageId/incident` (flag). */
+export interface FlagMessageIncidentBody {
+    reason: MessageIncidentReason;
+    note?: string;
+}
+
+/** Response data for both the flag and resolve endpoints. */
+export interface MessageIncidentResponseData {
+    incident: MessageIncidentWire;
+}