@victframework/runtime 0.1.0

package/dist/agent-governance.d.ts

@@ -0,0 +1,285 @@
+import type { AgentActivationRecord, AgentCredentialPort } from './agent-types.js';
+/**
+ * Stage 06A — agent data-protection governance (MSTR-011).
+ *
+ * This module is the neutral foundation for the local data-protection
+ * baseline:
+ *
+ * - `AgentCredentialPort` — protected-only, just-in-time credential
+ *   resolution. Values never enter profiles, snapshots, messages, memory,
+ *   traces, streams, diagnostics, errors, exports, or databases. Provider
+ *   failures are converted into stable, non-echoing diagnostics; a failed
+ *   provider read never poisons later invocations; no process-wide cache
+ *   silently preserves rotated values.
+ * - `AgentGovernanceStore` — durable deletion intents, per-step receipts,
+ *   and persisted activation identity records. In-memory and SQLite
+ *   implementations share one conformance discipline (idempotent writes,
+ *   receipt deduplication).
+ * - `ConversationDeletionCoordinator` — governed conversation deletion
+ *   across the VICT application-domain store and the agent-framework memory store.
+ *   Cross-store atomicity is impossible and is NOT claimed: the
+ *   coordinator records durable intent, makes each step idempotent,
+ *   persists progress receipts, resumes safely after failure or process
+ *   restart, never resurrects deleted data, and reports truthful
+ *   partial/blocked status.
+ * - `ConversationExportService` — explicit, request-scoped export of only
+ *   the data the classification policy promises; credentials, registry
+ *   data, and raw protected traces are structurally excluded, and the
+ *   generated export is never retained or logged by this service.
+ */
+/** Stable sanitized credential-failure codes (never provider content). */
+export type AgentCredentialErrorCode = 'VICT_AGENT_CREDENTIAL_UNAVAILABLE';
+/** Error thrown for credential-resolution failures (stable, non-echoing). */
+export declare class AgentCredentialError extends Error {
+    readonly code: AgentCredentialErrorCode;
+    readonly credentialName: string;
+    constructor(credentialName: string);
+}
+/** A credential name: validated against the accepted credential-reference policy. */
+export declare function assertCredentialName(name: string): void;
+/**
+ * Wrap a credential provider with the protected-resolution discipline:
+ * - names are validated before reaching the provider;
+ * - provider exceptions are converted into stable sanitized failures whose
+ *   messages never include provider content;
+ * - values are never cached — every read passes through to the provider, so
+ *   rotation is observed and a rejected read cannot poison later reads.
+ */
+export declare function protectCredentialPort(port: AgentCredentialPort): AgentCredentialPort;
+/** Stable non-echoing failure for a missing required credential. */
+export declare function requireCredential(value: string | undefined, name: string): string;
+/** The durable deletion step a receipt covers. */
+export type AgentDeletionStep = 'application-domain' | 'memory-store';
+/** Deletion-intent lifecycle states. */
+export type AgentDeletionIntentState = 'pending' | 'application-domain-deleted' | 'completed';
+/** One durable per-step receipt. */
+export interface AgentDeletionStepReceipt {
+    readonly step: AgentDeletionStep;
+    /** Epoch-ms timestamp from the injected clock. */
+    readonly at: number;
+}
+/** A durable deletion intent with its recorded progress. */
+export interface AgentDeletionIntentRecord {
+    readonly intentId: string;
+    readonly conversationId: string;
+    readonly actorId: string;
+    readonly createdAt: number;
+    readonly state: AgentDeletionIntentState;
+    readonly receipts: readonly AgentDeletionStepReceipt[];
+}
+/** Durable agent-governance records: activation identity + deletion intents. */
+export interface AgentGovernanceStore {
+    /** Persist an activation identity record (idempotent by activationVersion; content collision fails). */
+    saveAgentActivation(record: AgentActivationRecord): Promise<void>;
+    /** Read one activation identity record. */
+    getAgentActivation(activationVersion: string): Promise<AgentActivationRecord | undefined>;
+    /** Record a deletion intent (idempotent by intentId; same content is a no-op, conflicting content fails). */
+    recordDeletionIntent(record: AgentDeletionIntentRecord): Promise<void>;
+    /** Read one deletion intent. */
+    getDeletionIntent(intentId: string): Promise<AgentDeletionIntentRecord | undefined>;
+    /** List intents that have not reached `completed`. */
+    listOpenDeletionIntents(): Promise<readonly AgentDeletionIntentRecord[]>;
+    /** Record one step receipt (idempotent per intentId + step: duplicates are no-ops). */
+    recordDeletionReceipt(intentId: string, step: AgentDeletionStep, at: number): Promise<void>;
+    /** Advance the intent state (forward-only; regressions fail). */
+    updateDeletionIntentState(intentId: string, state: AgentDeletionIntentState): Promise<void>;
+    /** List ALL deletion intents (open and completed), canonically ordered. */
+    listDeletionIntents(): Promise<readonly AgentDeletionIntentRecord[]>;
+    /** Close underlying resources, if any (sync or async, per implementation). */
+    close?(): Promise<void> | void;
+}
+/**
+ * The closed deletion-step domain. Both store adapters (in-memory and
+ * SQLite) enforce the SAME receipt-step domain at their API boundary so
+ * unknown (e.g. legacy or fabricated) steps are rejected with the same
+ * stable, non-echoing error BEFORE any mutation (adapter parity).
+ */
+export declare const DELETION_STEP_DOMAIN: ReadonlySet<string>;
+/** The exact stable, non-echoing rejection text shared by every adapter. */
+export declare const DELETION_RECEIPT_STEP_INVALID_MESSAGE = "VICT_AGENT_DELETION_RECEIPT_STEP_INVALID: the deletion receipt step must be a governed durable step.";
+/**
+ * Validate one deletion-receipt step against the closed domain (shared by
+ * the in-memory and SQLite adapters). Invalid or legacy steps are rejected
+ * with the SAME stable, non-echoing error on every adapter, before any
+ * durable mutation occurs.
+ */
+export declare function assertDeletionReceiptStep(step: unknown): asserts step is AgentDeletionStep;
+/**
+ * Shared invariant enforcement for in-memory and SQLite stores.
+ *
+ * Transitions are forward-only AND stepwise: a state may only move to the
+ * IMMEDIATELY next state in the lifecycle. Skipped transitions (for example
+ * `pending` directly to `completed`) are rejected — completion always
+ * requires both durable step receipts, which a skipped transition would
+ * fabricate. Same-state updates are idempotent no-ops.
+ */
+export declare function assertDeletionStateTransition(from: AgentDeletionIntentState, to: AgentDeletionIntentState): void;
+/**
+ * Receipt-enforced transition validation (shared by in-memory and SQLite
+ * stores): a state may only advance when the receipt of the step it
+ * ENTERS is durably recorded.
+ *
+ * - entering `application-domain-deleted` requires the durable
+ *   `application-domain` receipt;
+ * - entering `completed` requires BOTH durable step receipts.
+ *
+ * The check reads the ACTUAL STORED receipts — the caller must pass the
+ * receipts exactly as they exist in the same store, and each store must
+ * perform the check and the state update ATOMICALLY (one synchronous
+ * critical section in memory; one transaction in SQLite). A receipt-free
+ * two-step bypass (`pending → application-domain-deleted → completed`)
+ * therefore fails at the FIRST transition and leaves the stored state
+ * unchanged.
+ */
+export declare function assertDeletionStateTransitionWithReceipts(from: AgentDeletionIntentState, to: AgentDeletionIntentState, receipts: ReadonlyArray<{
+    readonly step: AgentDeletionStep;
+}>): void;
+/**
+ * Validate a deletion-intent record at the durable boundary (shared by the
+ * in-memory and SQLite stores). A NEW intent must start as `pending` with
+ * NO receipts — arbitrary initial states and fabricated receipts are
+ * rejected.
+ */
+export declare function assertDeletionIntentRecord(record: AgentDeletionIntentRecord): void;
+/** In-memory AgentGovernanceStore (tests and non-durable compositions). */
+export declare class InMemoryAgentGovernanceStore implements AgentGovernanceStore {
+    #private;
+    saveAgentActivation(record: AgentActivationRecord): Promise<void>;
+    getAgentActivation(activationVersion: string): Promise<AgentActivationRecord | undefined>;
+    recordDeletionIntent(record: AgentDeletionIntentRecord): Promise<void>;
+    getDeletionIntent(intentId: string): Promise<AgentDeletionIntentRecord | undefined>;
+    listOpenDeletionIntents(): Promise<readonly AgentDeletionIntentRecord[]>;
+    listDeletionIntents(): Promise<readonly AgentDeletionIntentRecord[]>;
+    recordDeletionReceipt(intentId: string, step: AgentDeletionStep, at: number): Promise<void>;
+    updateDeletionIntentState(intentId: string, state: AgentDeletionIntentState): Promise<void>;
+}
+/** The application-domain side of governed conversation deletion. */
+export interface AgentConversationDomainPort {
+    /**
+     * Delete the VICT application-domain conversation resource. Returns
+     * `{ deleted: true }` when a record was deleted and
+     * `{ deleted: false }` when it was already absent (idempotent).
+     */
+    deleteConversation(conversationId: string): Promise<{
+        readonly deleted: boolean;
+    }>;
+}
+/** The the agent framework-memory side of governed conversation deletion (adapter-owned). */
+export interface AgentMemoryDeletionPort {
+    /**
+     * Delete the the agent framework thread (and its messages/memory state) bound to the
+     * VICT conversation. Idempotent: returns `{ deleted: false }` when the
+     * thread was already absent.
+     */
+    deleteConversationThread(conversationId: string): Promise<{
+        readonly deleted: boolean;
+    }>;
+}
+/** Result of one governed deletion attempt. */
+export interface AgentDeletionOutcome {
+    /** `completed` when every governed step has a durable receipt. */
+    readonly status: 'completed' | 'pending';
+    readonly intentId: string;
+    readonly conversationId: string;
+    /** Steps with durable receipts after this attempt, in policy order. */
+    readonly completedSteps: readonly AgentDeletionStep[];
+}
+/** Options for the ConversationDeletionCoordinator. */
+export interface ConversationDeletionCoordinatorOptions {
+    readonly governance: AgentGovernanceStore;
+    readonly domain: AgentConversationDomainPort;
+    readonly memory: AgentMemoryDeletionPort;
+    /** Injected clock (epoch ms). */
+    readonly clock?: () => number;
+}
+/**
+ * Governed conversation deletion across stores (amendment §8.1, MSTR-011).
+ *
+ * Cross-store atomicity is impossible and is never claimed. The
+ * coordinator:
+ * 1. records the durable deletion intent BEFORE touching either store;
+ * 2. deletes the VICT application-domain resource through its governed
+ *    port and records a durable receipt;
+ * 3. deletes the the agent framework thread through the adapter port and records a
+ *    durable receipt;
+ * 4. advances the intent to `completed` only when both receipts exist.
+ *
+ * Every step is idempotent; receipts deduplicate; `recoverPending()`
+ * resumes safely after a crash at ANY boundary without duplicating
+ * receipts, losing completions, or resurrecting deleted data.
+ */
+export declare class ConversationDeletionCoordinator {
+    #private;
+    constructor(options: ConversationDeletionCoordinatorOptions);
+    /** Deterministic intent id per conversation (idempotent re-deletes). */
+    intentIdFor(conversationId: string): string;
+    deleteConversation(options: {
+        readonly conversationId: string;
+        readonly actorId: string;
+    }): Promise<AgentDeletionOutcome>;
+    /**
+     * Resume every open intent (crash recovery, process restart). Each open
+     * intent continues from its recorded receipts; completed steps are never
+     * re-executed against the stores... the underlying ports are idempotent
+     * besides, but receipts are authoritative: a recorded receipt means the
+     * step is durable and is NOT re-driven.
+     */
+    recoverPending(): Promise<{
+        readonly resumed: number;
+        readonly completed: number;
+        readonly pending: number;
+    }>;
+}
+/** One exported conversation message (classification-policy fields only). */
+export interface AgentConversationExportMessage {
+    readonly seq: number;
+    readonly role: 'user' | 'assistant' | 'system';
+    /** Epoch-ms creation time from the owning store. */
+    readonly createdAt: number;
+    /** Message text content (intentionally retained conversation content). */
+    readonly text: string;
+}
+/**
+ * The export payload: only what the classification policy promises. No
+ * credentials, no registry data, no raw traces, no operational history.
+ */
+export interface AgentConversationExport {
+    readonly conversationId: string;
+    readonly actorId: string;
+    readonly threadCreatedAt: number | null;
+    readonly messages: readonly AgentConversationExportMessage[];
+}
+/** The the agent framework-side export port (adapter-owned). */
+export interface AgentConversationMemoryExportPort {
+    exportConversationThread(conversationId: string): Promise<AgentConversationExport | undefined>;
+}
+/** Result of an export request. */
+export interface AgentConversationExportResult {
+    /** Deterministic structured export (ordering is meaningful). */
+    readonly export: AgentConversationExport;
+    /** The export is returned to the requestor and NOT retained anywhere. */
+    readonly retained: false;
+}
+/** Stable denial codes for exports. */
+export type AgentConversationExportErrorCode = 'VICT_AGENT_EXPORT_NOT_FOUND' | 'VICT_AGENT_EXPORT_ACTOR_MISMATCH';
+/** Error carrying a stable export denial (never raw content). */
+export declare class AgentConversationExportError extends Error {
+    readonly code: AgentConversationExportErrorCode;
+    constructor(code: AgentConversationExportErrorCode);
+}
+/**
+ * Governed conversation export (MSTR-011). Explicit and request-scoped:
+ * the requestor must present the owning actor identity; the export
+ * contains only classification-policy data; the result is handed to the
+ * caller and never logged or retained by the service.
+ */
+export declare class ConversationExportService {
+    #private;
+    constructor(options: {
+        readonly memory: AgentConversationMemoryExportPort;
+    });
+    export(options: {
+        readonly conversationId: string;
+        readonly actorId: string;
+    }): Promise<AgentConversationExportResult>;
+}