@sanctuary-framework/mcp-server 1.2.5 → 1.2.7

package/dist/index.d.ts

@@ -5315,6 +5315,212 @@ declare class ConciergeMemoryStore {
     private withLock;
 }
 
+/**
+ * Sanctuary MCP Server, Operator Chat, Concierge Query Grammar
+ *
+ * WP-V1.3-9 Tau-4 (criterion (d) of the v1.3 scope-lock revision). Builds
+ * on Tau-3 (PR #171, dynamic context router). The grammar layer parses
+ * operator queries into structured parameters: time ranges, agent names,
+ * event types, and a free-form intent residual. Tau-3 fetchers receive
+ * the parsed hints alongside the query so the substrate sees the most
+ * relevant data slice.
+ *
+ * The module is pure: rule-based extraction, no I/O, no clock side
+ * effects beyond the optional `now` parameter for deterministic tests.
+ * The optional LLM-assist fallback is invoked by the caller when the
+ * rule-based parser produces low confidence.
+ *
+ * Castle-walking discipline:
+ * - No new outbound surface; the LLM-assist fallback routes through the
+ *   substrate selector at the same `concierge` surface Tau-3 already
+ *   uses.
+ * - Encryption boundaries hold: this module receives plain strings
+ *   already produced inside the fortress.
+ * - Failure-mode handling is fail-soft: low-confidence parses surface a
+ *   structured fallback menu so the operator sees what the concierge
+ *   can answer, never a silent drop.
+ *
+ * Privacy invariant:
+ * The runtime `ParsedQuery` carries `intent_phrase` (free-form residual
+ * pulled from the operator's query) for the router's own consumption.
+ * The audit emission MUST NOT include `intent_phrase`; consumers serialize
+ * via `auditSafeSummary()` which strips it. See `OperatorConciergeChatPayload`
+ * safe-metadata invariant in `contracts/v1.2/operator-chat-events.ts`.
+ *
+ * Out of scope here (Tau-5 + later):
+ * - Agent-context awareness (proactive parsing without an explicit
+ *   query). Tau-4 parses off explicit query content only.
+ * - Voice input or natural-language-as-API surface (defer to v1.5+).
+ * - Cross-fortress concierge query (defer to v1.4 cross-tenant scope).
+ * - Window markers like "around the time of <event>" that require an
+ *   audit-log lookup to resolve. Tau-4 ships static patterns only.
+ */
+
+/**
+ * A resolved time range. `relative_label` carries the original token
+ * ("yesterday", "past hour", etc.) when the range was derived from a
+ * relative pattern, so consumers can render operator-readable copy.
+ */
+interface ParsedTimeRange {
+    start: Date;
+    end: Date;
+    relative_label?: string;
+}
+/**
+ * Stable structured-failure flags surfaced when the parser cannot
+ * resolve a token confidently. The strings are enum-like (no free text)
+ * so the audit emission stays safe-metadata-only and the dashboard can
+ * group by cause.
+ */
+type AmbiguityFlag = "unknown_time_token" | "unknown_agent_token" | "unknown_event_token" | "ambiguous_time_range" | "no_signal_extracted";
+/**
+ * Runtime parsed-query shape. Used by the router to thread parameters
+ * into context fetchers, and by the structured-fallback menu builder.
+ *
+ * `intent_phrase` is the residual after time/agent/event tokens are
+ * stripped, useful for router-level intent routing. It carries operator
+ * query content and MUST NOT be serialized into the audit log.
+ */
+interface ParsedQuery {
+    time_range: ParsedTimeRange | null;
+    agent_names: string[];
+    event_types: string[];
+    intent_phrase: string;
+    ambiguity_flags: AmbiguityFlag[];
+    /** 0..1; 1.0 = every component resolved cleanly. */
+    parse_confidence: number;
+}
+/**
+ * Read-only registry view consumed by `parseQuery` for agent-name
+ * extraction. The grammar matches operator query tokens against the
+ * `agent_id` field of each record (case-insensitive, prefix-or-exact).
+ *
+ * Wired from `HubAgentRegistrySource.list()` at the service layer; tests
+ * can hand a literal array. Both shapes are accepted so callers do not
+ * have to wrap a hub registry in an adapter just to feed the parser.
+ */
+type AgentRegistryView = readonly {
+    agent_id: string;
+}[] | {
+    list: () => readonly {
+        agent_id: string;
+    }[];
+};
+/**
+ * Optional LLM-assist completion. Invoked by `parseQueryWithLlmAssist`
+ * when the rule-based parse confidence is below `LLM_ASSIST_THRESHOLD`.
+ * The classifier sees the query plus the partial parse and may return
+ * `null` (no completion) or a partial-shape patch the caller merges.
+ *
+ * The runtime caller (operator-chat-service) MUST route this through
+ * the substrate selector at the `concierge` surface so no new outbound
+ * channel opens. See Castle-walking discipline at the top of the file.
+ */
+type LlmAssistGrammarCompletion = (query: string, partial: ParsedQuery) => Promise<Partial<{
+    time_range: ParsedTimeRange;
+    agent_names: string[];
+    event_types: string[];
+}> | null>;
+
+/**
+ * Sanctuary MCP Server, Operator Chat, Concierge Dynamic Context Router
+ *
+ * WP-V1.3-9 Tau-3 (criterion (c) of the v1.3 scope-lock revision). Builds
+ * on Tau-1 (PR #164, concierge memory store) and Tau-2 (PR #166, multi-turn
+ * coherence read-fold path). At each operator turn the concierge fetches
+ * live data relevant to the operator's query and folds it into context
+ * between the static Sanctuary reference and the prior-turns fold.
+ *
+ * Tau-4 (PR #_, criterion (d)) layers an operator-query grammar on top:
+ * the caller (`operator-chat-service`) parses the query into a
+ * `ParsedQuery` via `concierge-query-grammar`, threads the result into
+ * `classifyQuery` + `foldContext`, and the matches carry the parsed
+ * grammar through to fetchers as `FetcherHints` (time range + agent
+ * names + event types). Existing fetcher implementations that do not
+ * read the second argument continue to work unchanged.
+ *
+ * The module is intentionally pure: keyword classification + a small
+ * amount of hint extraction + a fold orchestrator that calls caller-
+ * provided fetchers. The wiring layer assembles the concrete fetchers
+ * (templates registry, agent registry, audit log, sentinel store, etc.)
+ * so this module stays test-isolatable and composable.
+ *
+ * Castle-walking discipline:
+ * - No new outbound surface; the optional auxiliary classifier is invoked
+ *   through the substrate selector by the caller (the service threads the
+ *   classifier callback through, this module never owns the channel).
+ * - Encryption boundaries hold for the underlying data sources; this
+ *   module receives plain strings already produced inside the fortress.
+ * - Failure-mode handling is fail-soft: a fetcher failure omits its
+ *   category from the fold and surfaces an audit event through the
+ *   caller's onFetcherFailure hook. The user-facing concierge query is
+ *   never broken by a context-assembly failure.
+ *
+ * Out of scope here (Tau-5):
+ * - Agent-context awareness (proactive folding without an explicit
+ *   query). The router still routes off explicit query content only.
+ */
+
+/**
+ * Closed enum of categories the router may classify a query into. Adding
+ * a category requires updating: this enum, the keyword table, the
+ * fetcher interface, every wiring fetcher, and the test surface.
+ */
+type ContextCategory = "templates" | "agent_state" | "agent_activity" | "audit_log" | "sentinel_findings" | "anomaly_alerts" | "recent_receipts" | "verascore_deltas";
+/**
+ * Structured hints passed to fetchers as the optional second argument
+ * (Tau-4). Derived from `ParsedQuery` by the router; fetchers are free
+ * to read or ignore individual fields. Tau-3 fetchers that take no
+ * second argument continue to work because the slot is optional.
+ */
+interface FetcherHints {
+    /** Time range derived from the operator's query, when one resolved. */
+    time_range?: {
+        start: Date;
+        end: Date;
+        relative_label?: string;
+    };
+    /**
+     * All agent names the parser matched against the registry, in the
+     * order they surfaced. Distinct from the `agentNameHint` first arg
+     * (which carries only the first match for back-compat).
+     */
+    agent_names?: readonly string[];
+    /**
+     * Event-type names the parser matched against the canonical audit-
+     * event-class enumeration. Already filtered to the closed set.
+     */
+    event_types?: readonly string[];
+}
+/**
+ * Caller-supplied data sources. Each fetcher returns plain text the
+ * router stitches into the rendered section. Returning the empty string
+ * (or whitespace only) is treated as "nothing to fold for this category"
+ * and the category drops out of the final categoriesIncluded list.
+ *
+ * Tau-4 extends every fetcher with an optional `hints?: FetcherHints`
+ * argument carrying the parsed-query attachments (time range, agent
+ * names, event types). Fetchers that ignore the argument continue to
+ * compile; fetchers that consume it can scope queries against the
+ * audit log, activity feed, etc., to the operator's stated window.
+ */
+interface ContextFetchers {
+    templates: (hints?: FetcherHints) => Promise<string>;
+    agent_state: (agentNameHint: string | null, hints?: FetcherHints) => Promise<string>;
+    agent_activity: (agentNameHint: string | null, hints?: FetcherHints) => Promise<string>;
+    audit_log: (hints?: FetcherHints) => Promise<string>;
+    sentinel_findings: (hints?: FetcherHints) => Promise<string>;
+    anomaly_alerts: (hints?: FetcherHints) => Promise<string>;
+    recent_receipts: (hints?: FetcherHints) => Promise<string>;
+    verascore_deltas: (hints?: FetcherHints) => Promise<string>;
+}
+/**
+ * Auxiliary classifier the caller may supply for the LLM-assist fallback
+ * path. Invoked only when keyword classification returns zero matches
+ * AND the query is non-trivial (>= 8 chars, not a clear greeting).
+ */
+type LlmAssistClassifier = (query: string, categories: readonly ContextCategory[]) => Promise<ContextCategory | "none">;
+
 /**
  * Sanctuary MCP Server — Operator Chat Service
  *
@@ -5461,6 +5667,50 @@ interface OperatorChatServiceDeps {
      * implementation run.
      */
     conciergeClock?: () => number;
+    /**
+     * WP-V1.3-9 Tau-3: caller-supplied fetchers for dynamic context
+     * injection. When wired alongside the substrate selector, every
+     * `sendConcierge` round-trip routes the operator's query through the
+     * concierge-context-router and folds matching live data into the
+     * substrate prompt between the static Sanctuary reference and the
+     * prior-turns fold. Omit to disable dynamic context (the static
+     * reference + prior-turns paths keep working unchanged).
+     */
+    conciergeContextFetchers?: ContextFetchers;
+    /**
+     * WP-V1.3-9 Tau-3: optional LLM-assist classifier for queries that
+     * fail keyword classification. Coordinator-CTO bake: when wired, the
+     * service routes the auxiliary classifier call through the substrate
+     * selector at the same `concierge` surface, so the auxiliary call
+     * shares the operator's substrate choice and never opens a new
+     * outbound surface.
+     */
+    conciergeContextLlmAssist?: LlmAssistClassifier;
+    /**
+     * WP-V1.3-9 Tau-3: rough token budget for the dynamic-context fold.
+     * Defaults to `DEFAULT_CONCIERGE_DYNAMIC_CONTEXT_BUDGET` (2000).
+     */
+    conciergeDynamicContextBudget?: number;
+    /**
+     * WP-V1.3-9 Tau-4: read-only registry view consumed by the operator-
+     * query grammar to extract agent-name parameters. Wired from
+     * `HubAgentRegistrySource.list()` at the hub-service layer; absent
+     * services skip agent-name extraction (the grammar still resolves
+     * time ranges and event types). The registry is read at every
+     * `sendConcierge` call so newly-wrapped agents are visible without
+     * service reconstruction.
+     */
+    conciergeAgentRegistry?: AgentRegistryView;
+    /**
+     * WP-V1.3-9 Tau-4: optional LLM-assist completion for low-confidence
+     * grammar parses. When wired alongside the substrate selector, the
+     * service routes the call through the substrate selector at the
+     * `concierge` surface, so the grammar fallback shares the operator's
+     * substrate choice and never opens a new outbound surface. Distinct
+     * from `conciergeContextLlmAssist`, which classifies queries into
+     * fetcher categories; this hook completes structured grammar fields.
+     */
+    conciergeGrammarLlmAssist?: LlmAssistGrammarCompletion;
 }
 declare class OperatorChatService {
     private store;
@@ -5476,6 +5726,11 @@ declare class OperatorChatService {
     private historyTokenBudget;
     private sessionTtlMs;
     private clock;
+    private contextFetchers?;
+    private contextLlmAssist?;
+    private dynamicContextBudget;
+    private agentRegistry?;
+    private grammarLlmAssist?;
     /**
      * In-memory thread_id assigned to the active concierge session.
      * The first sendConcierge call after construction allocates a fresh
@@ -5556,10 +5811,13 @@ declare class OperatorChatService {
      *   ## Sanctuary reference
      *   <static domain reference block>
      *
+     *   ## Live fortress context          ← WP-V1.3-9 Tau-3, when present
+     *   ### <Category>
+     *   <fetcher payload>
+     *
      *   ## Prior conversation             ← WP-V1.3-9 Tau-2, when present
      *   OPERATOR: ...
      *   CONCIERGE: ...
-     *   ---
      *
      *   ## Recent activity
      *   <recentActivity output>
@@ -5579,6 +5837,35 @@ declare class OperatorChatService {
      * serialization is the canonical path for v1.3.
      */
     private assembleConciergeContext;
+    /**
+     * Run the WP-V1.3-9 Tau-3 dynamic-context fold for a single round-
+     * trip. Fail-soft on every axis: missing fetchers short-circuit to
+     * an empty fold, fetcher failures emit a per-category audit event
+     * and are omitted from the rendered section, an LLM-assist failure
+     * proceeds with no fold. Returns the rendered section + the list of
+     * categories whose data made it into the section (used for the
+     * round-trip audit emission).
+     *
+     * Tau-4: receives the pre-parsed `ParsedQuery` and forwards it as the
+     * `parsed` opt to `foldContext`, so fetchers see the structured
+     * `FetcherHints` derived from it.
+     */
+    private runDynamicContextFold;
+    /**
+     * WP-V1.3-9 Tau-4: parse the (PII-filtered) operator query into a
+     * `ParsedQuery`. Routes through the LLM-assist completion hook when
+     * configured and the rule-based parse is below
+     * `LLM_ASSIST_THRESHOLD`. Always returns a parse object (never
+     * throws) so the audit emission can carry the result unconditionally.
+     */
+    private runGrammarParse;
+    /**
+     * Emit the WP-V1.3-9 Tau-3 fetcher-failure audit event. Pulled out
+     * of the fold path so the dynamic-context handler stays readable.
+     * Emits with `result: "failure"` since the named category dropped
+     * from the rendered section for this round-trip.
+     */
+    private emitContextFetcherFailed;
     /**
      * Render the prior-conversation section with token-budget enforcement
      * (WP-V1.3-9 Tau-2). Drops oldest turns first when the rendered
@@ -6069,6 +6356,87 @@ interface V11Bindings {
     operatorChatService?: OperatorChatService;
 }
 
+/**
+ * Sanctuary v1.3 WP-V1.3-10 Cross-Harness Approval Inbox Upsilon-3
+ *
+ * At-rest encrypted persistence for full request payloads tied to
+ * AggregatedApproval entries. Sibling store to ApprovalAggregator: the
+ * aggregator's own entry record (status, provenance, hashes) is persisted
+ * by the aggregator class under `_approval_aggregator`; this store holds
+ * the original request payload separately under
+ * `_approval_aggregator_payloads` so the operator can replay the full
+ * payload after a server restart.
+ *
+ * Storage layout:
+ *   namespace: `_approval_aggregator_payloads`
+ *   key:       `payload.{aggregator_id}` (one record per approval)
+ *   payload:   AES-256-GCM ciphertext of the JSON-serialised bundle.
+ *   key:       `l2-approval-aggregator-payload-v1` HKDF subkey of fortress
+ *              master.
+ *   AAD:       UTF-8 bytes of `aggregator_id`. Swapping records across
+ *              aggregator_ids breaks the auth tag. Castle-walking
+ *              discipline: the encryption boundary holds even against
+ *              on-disk shuffle.
+ *
+ * Retention:
+ * Each bundle carries an ISO-8601 `retention_until`. `pruneExpired()`
+ * iterates payloads and drops entries whose retention_until is in the
+ * past. Default retention is 30 days, mirroring the audit-log retention
+ * envelope. Operator override flows through the aggregator's deps.
+ *
+ * Multi-fortress isolation:
+ * The HKDF subkey is derived from the fortress master key. Two
+ * fortresses never produce identical encryption keys for identical
+ * aggregator_ids. Isolation is enforced cryptographically; the AAD
+ * binds the ciphertext to a specific aggregator_id within a fortress.
+ */
+
+interface AggregatorPayloadStoreOptions {
+    /** Storage backend that persists the encrypted bundles. */
+    storage: StorageBackend;
+    /** 32-byte fortress master key. */
+    masterKey: Uint8Array;
+    /** Stable fortress id stamped on every bundle for audit clarity. */
+    fortressId: string;
+    /** Operator-tunable retention window. Default 30 days. */
+    retentionDays?: number;
+}
+/**
+ * Encrypted, AAD-bound, retention-aware payload persistence for the
+ * cross-harness approval inbox.
+ */
+declare class AggregatorPayloadStore {
+    private readonly storage;
+    private readonly encryptionKey;
+    private readonly fortressId;
+    private readonly retentionDays;
+    constructor(opts: AggregatorPayloadStoreOptions);
+    /**
+     * Persist `payload` under the given aggregator_id. Idempotent; calling
+     * twice with the same id rewrites the bundle (retention_until is
+     * recomputed). Returns the bundle's retention_until ISO-8601 timestamp
+     * so callers can log it.
+     */
+    savePayload(aggregatorId: string, payload: unknown): Promise<string>;
+    /**
+     * Read the persisted payload for the aggregator_id. Returns null if no
+     * bundle exists, the bundle is corrupted, or AAD binding fails.
+     */
+    loadPayload(aggregatorId: string): Promise<unknown>;
+    /**
+     * Delete the persisted payload. Returns true when a bundle was removed,
+     * false when none existed.
+     */
+    deletePayload(aggregatorId: string): Promise<boolean>;
+    /**
+     * Drop expired payload bundles. Returns the count of bundles pruned.
+     * Caller wires this into the cocoon-unlock initialization path.
+     */
+    pruneExpired(now?: Date): Promise<{
+        pruned: number;
+    }>;
+}
+
 /**
  * Sanctuary v1.3 WP-V1.3-10 Cross-Harness Approval Inbox Upsilon-1
  *
@@ -6106,6 +6474,19 @@ interface V11Bindings {
  *  - `expired`: pending past TTL on a `list()` poll without a resolution.
  */
 type AggregatedApprovalStatus = "pending" | "approved" | "denied" | "timeout" | "expired";
+/**
+ * One step in the Castle Architecture enforcement chain that led to this
+ * approval. Layers are: l1 (Castle Wall, OS-level egress), l2 (Sentinel +
+ * cooperative MCP gate), l3 (selective disclosure), l4 (reputation).
+ * v1.3 Upsilon-3 ships the schema; default resolver populates a single
+ * `l2` entry. Future Castle Wall wiring will extend the chain when a
+ * payload's egress was first observed by the kernel filter.
+ */
+interface EnforcementLayerEvent {
+    layer: "l1" | "l2" | "l3" | "l4";
+    event: string;
+    timestamp: string;
+}
 /**
  * Normalized record the aggregator stores per approval. Field set is
  * additive-stable; new fields go behind `?` so existing dashboards keep
@@ -6150,6 +6531,31 @@ interface AggregatedApproval {
      * (the cross-link signal lives on the aggregator side only).
      */
     hub_inbox_item_id?: string;
+    /**
+     * Castle Architecture enforcement-layer chain that led to this
+     * approval. Populated by the optional `resolveEnforcementChain` deps
+     * hook; default returns a single `l2` step (cooperative MCP gate
+     * fired). Persisted with the entry so the operator-replay surface can
+     * render the enforcement context after a server restart. v1.3
+     * Upsilon-3.
+     */
+    enforcement_chain?: EnforcementLayerEvent[];
+    /**
+     * Aggregator revision number stamped at entry creation. Stable across
+     * status transitions. Used by the v1.4 mobile companion sync API to
+     * separate "added" from "changed" deltas (created_at_revision >
+     * sinceRevision means added; otherwise it is a status change).
+     * v1.3 Upsilon-4.
+     */
+    created_at_revision?: number;
+    /**
+     * Aggregator revision number stamped at the last mutation (creation,
+     * resolution, expiration). Sync-API consumers compare against the
+     * revision they last saw to compute the delta. Monotonically
+     * increasing per fortress; gaps are normal (one bump per mutation).
+     * v1.3 Upsilon-4.
+     */
+    last_modified_revision?: number;
 }
 /**
  * Source-context resolver. Called once per ingest to map gate context to
@@ -6206,11 +6612,35 @@ type ApprovalAggregatorUnsubscribe = () => void;
 interface ApprovalAggregatorEmit {
     /**
      * `aggregated` on first ingest, `resolved` on a status leaving pending,
-     * `deduped` when an ingest dropped because the same dedup key was seen.
+     * `deduped` when an ingest dropped because the same dedup key was seen,
+     * `removed` when an entry was pruned (v1.3 Upsilon-4).
      */
-    type: "aggregated" | "resolved" | "deduped";
+    type: "aggregated" | "resolved" | "deduped" | "removed";
     entry: AggregatedApproval;
 }
+/**
+ * Sync-API delta returned by `getSync()`. v1.3 Upsilon-4. Mobile
+ * companions poll this for cheap state-sync without re-fetching the
+ * full inbox. The `revision` field on the response is the aggregator's
+ * current revision; pass it back as `sinceRevision` on the next call.
+ *
+ * `added` carries entries created after `sinceRevision`. `changed`
+ * carries entries that existed at `sinceRevision` but have transitioned
+ * status (resolved, expired) since. `removed` carries the
+ * aggregator_ids of entries pruned after `sinceRevision`.
+ *
+ * Tombstone caveat: removal tombstones live in-process memory. Server
+ * restart clears them. Mobile clients reconnecting after the server
+ * restarted MUST re-bootstrap from `list()` rather than rely on the
+ * sync delta. The v1.4 mobile companion build wires the bootstrap-on-
+ * reconnect flow; v1.3 documents the constraint.
+ */
+interface ApprovalAggregatorSyncDelta {
+    revision: number;
+    added: AggregatedApproval[];
+    changed: AggregatedApproval[];
+    removed: string[];
+}
 /**
  * Constructor dependencies. `pendingTtlMs` and `maxListLimit` default to
  * coordinator-CTO defaults; tests pass overrides for deterministic timing.
@@ -6238,6 +6668,23 @@ interface ApprovalAggregatorDeps {
      * hub inbox store.
      */
     resolveHubInboxItemId?: (event: ApprovalGateEvent) => string | undefined;
+    /**
+     * Optional at-rest payload store. When provided, the aggregator
+     * persists each request payload via `savePayload` on ingest, and
+     * rehydrates payloads on `getFullPayload` if the in-memory map lost
+     * them (e.g. after a server restart). Upsilon-3 surface; absent in
+     * Upsilon-1 / Upsilon-2 deployments, where payloads remain in-memory
+     * only.
+     */
+    payloadStore?: AggregatorPayloadStore;
+    /**
+     * Optional resolver for the Castle Architecture enforcement chain
+     * leading to this approval. Default returns a single `l2` step
+     * (cooperative MCP gate fired). When the Castle Wall (Layer 1) ships,
+     * its kernel-filter observer can populate richer chains by passing a
+     * resolver here.
+     */
+    resolveEnforcementChain?: (event: ApprovalGateEvent) => EnforcementLayerEvent[];
 }
 /**
  * Aggregator state. The map is hydrated lazily from the encrypted
@@ -6254,6 +6701,8 @@ declare class ApprovalAggregator {
     private readonly now;
     private readonly resolveSourceContext;
     private readonly resolveHubInboxItemId;
+    private readonly payloadStore;
+    private readonly resolveEnforcementChain;
     /** Cached entries by `aggregator_id`. */
     private readonly entries;
     /** Dedup index: `${harness}|${agent}|${audit_id}` -> aggregator_id. */
@@ -6266,12 +6715,63 @@ declare class ApprovalAggregator {
     private hydrated;
     /** Active SSE listeners. */
     private readonly listeners;
+    /**
+     * Monotonic revision counter, bumped on every mutation (ingest of new
+     * entry, resolve, expire, delete). Hydrated from max(last_modified_revision)
+     * across persisted entries on first read; in-memory after that. v1.3
+     * Upsilon-4.
+     */
+    private currentRevision;
+    /**
+     * Removal tombstones: aggregator_id -> revision at removal. Used by the
+     * sync API to surface "removed" entries to mobile consumers between
+     * polls. In-memory only; server restart clears tombstones (mobile
+     * bootstraps via `list()` on reconnect). v1.3 Upsilon-4.
+     */
+    private readonly removedTombstones;
     constructor(deps: ApprovalAggregatorDeps);
     /**
      * Subscribe an event listener. Returns an unsubscribe fn. SSE handlers
      * use this to forward aggregator emissions to the dashboard.
      */
     onEvent(listener: (event: ApprovalAggregatorEmit) => void): ApprovalAggregatorUnsubscribe;
+    /**
+     * Current aggregator revision. v1.3 Upsilon-4. Mobile companions
+     * poll the lightweight `/revision` route to detect that something
+     * changed before fetching a full sync delta.
+     */
+    getRevision(): Promise<number>;
+    /**
+     * Compute a delta since `sinceRevision`. v1.3 Upsilon-4. Mobile
+     * clients poll this for cheap state-sync. Behavior:
+     *  - `added`: entries whose `created_at_revision > sinceRevision`.
+     *  - `changed`: entries that existed at `sinceRevision` but had a
+     *    status transition (resolve, expire) since.
+     *  - `removed`: aggregator_ids deleted after `sinceRevision`.
+     *  - `revision`: current aggregator revision; pass this back as
+     *    `sinceRevision` on the next call.
+     *
+     * `limit` caps the total count returned across all three lists,
+     * prioritized as added -> changed -> removed (newer-state first).
+     * When more changes exist than fit, the next call with the returned
+     * revision will pick up the rest because each entry's
+     * last_modified_revision is unchanged by truncation.
+     */
+    getSync(opts?: {
+        sinceRevision?: number;
+        limit?: number;
+    }): Promise<ApprovalAggregatorSyncDelta>;
+    /**
+     * Delete an entry. Drops the in-memory record, the persisted bundle,
+     * and the at-rest payload (if a payload store is wired). Records a
+     * tombstone with the new revision so sync-API consumers see a
+     * `removed` delta. Returns true when an entry was deleted, false on
+     * unknown id. v1.3 Upsilon-4. Reserved for v1.4+ retention housekeeping;
+     * Upsilon-4 ships the surface so mobile sync-API tests can exercise the
+     * removal path.
+     */
+    deleteEntry(aggregatorId: string): Promise<boolean>;
+    private nextRevision;
     /**
      * Ingest a gate event. Returns the aggregator entry on first sight,
      * `null` when deduped. Resolution events update the existing record;
@@ -6292,10 +6792,48 @@ declare class ApprovalAggregator {
     }): Promise<AggregatedApproval[]>;
     /**
      * Return the original (unhashed) request payload for the entry. Returns
-     * `null` when the entry is unknown or the payload was evicted (e.g. the
-     * process restarted; payloads are in-memory only at v1.3 Upsilon-1).
+     * `null` when the entry is unknown. When the in-memory payload map has
+     * been evicted (e.g. after a server restart) and a `payloadStore` was
+     * provided, the at-rest bundle is decrypted and the in-memory map is
+     * refilled. Audit emission lives on the `*WithAudit` variant; this base
+     * accessor is silent so internal callers can read without polluting the
+     * audit trail.
      */
     getFullPayload(aggregatorId: string): Promise<unknown>;
+    /**
+     * Return the entry record for the given id, or null when unknown.
+     * Idempotent. v1.3 Upsilon-3.
+     */
+    getEntry(aggregatorId: string): Promise<AggregatedApproval | null>;
+    /**
+     * Audited variant of `getFullPayload`. Emits the
+     * `cross_harness_approval_payload_decrypted` audit event before
+     * returning. Used by the operator-facing /payload replay route.
+     * v1.3 Upsilon-3.
+     */
+    getFullPayloadWithAudit(aggregatorId: string, operatorId: string): Promise<unknown>;
+    /**
+     * Return the audit-log entries that led to and surround this approval.
+     * Best-effort matching: aggregator-side emissions (AGGREGATED, RESOLVED,
+     * DEDUPED, replay events) all carry `details.aggregator_id` and link
+     * directly. Gate-side emissions (`gate_*:operation`) do not carry the
+     * aggregator id at v1.3, so they are matched via timestamp window
+     * (entry.created_at to entry.resolved_at + 1s, or expires_at + 1s while
+     * pending) and operation suffix. Emits AUDIT_TRAIL_VIEWED on call.
+     * v1.3 Upsilon-3.
+     */
+    getAuditTrail(aggregatorId: string, operatorId: string): Promise<AuditEntry[]>;
+    /**
+     * List historical (resolved) approvals. Excludes pending entries by
+     * design: `list()` is the pending-inbox surface and `getHistory()` is
+     * the resolved-replay surface. Emits REPLAYED on each call. v1.3
+     * Upsilon-3.
+     */
+    getHistory(opts: {
+        status?: AggregatedApprovalStatus;
+        sinceTs?: string;
+        limit?: number;
+    } | undefined, operatorId: string): Promise<AggregatedApproval[]>;
     /**
      * Resolve an entry. Used by both:
      *   1. The gate wire-up on channel-decision return.