@sanctuary-framework/mcp-server 1.2.13 → 1.2.15

package/dist/index.d.ts

@@ -4356,108 +4356,6 @@ declare class MalformedPrincipalPolicyError extends Error {
  */
 declare function loadPrincipalPolicy(storagePath: string): Promise<PrincipalPolicy>;
 
-/**
- * Sanctuary MCP Server — SHR Generator
- *
- * Generates a Sovereignty Health Report from current server state,
- * signs it with a specified identity, and returns the complete signed SHR.
- */
-
-/**
- * Observed L4 reputation state used by the emitter. Callers gather these
- * facts from the reputation store + audit log; the emitter derives
- * degradations from them. Keeping evidence as plain data keeps the
- * generator synchronous and easy to test.
- */
-interface L4Evidence {
-    /** Total attestations attributed to the signing identity */
-    attestation_count: number;
-    /** Count of attestations at each sovereignty tier */
-    tier_distribution: Record<SovereigntyTier, number>;
-    /** ISO timestamp of most recent attestation, or null when none exist */
-    most_recent_attestation_at: string | null;
-    /** Count of attestations with outcome_result === "disputed" */
-    dispute_count: number;
-    /** Attestation count per context label (optional; used by dashboard) */
-    context_breakdown?: Record<string, number>;
-    /**
-     * True iff the `reputation_publish` tool has been successfully invoked
-     * for this identity (i.e., there is at least one success audit entry).
-     */
-    verascore_linked: boolean;
-    /**
-     * Optional overrides for the emitter thresholds. Defaults apply when
-     * omitted or when a field is missing.
-     */
-    thresholds?: {
-        freshness_window_days?: number;
-        low_tier_dominance_threshold?: number;
-    };
-}
-interface SHRGeneratorOptions {
-    config: SanctuaryConfig;
-    identityManager: IdentityManager;
-    masterKey: Uint8Array;
-    /** Override validity window (milliseconds). Default: 1 hour. */
-    validityMs?: number;
-    /**
-     * Optional L4 reputation evidence. When provided, the generator emits
-     * L4 degradations (NO_REPUTATION_HISTORY, LOW_TIER_DOMINANCE,
-     * STALE_REPUTATION, DISPUTE_ON_RECORD, NO_VERASCORE_LINK) accordingly
-     * and downgrades `layers.l4.status` to `degraded` when any fire.
-     * When omitted, L4 is left at "active" (backward-compatible).
-     */
-    l4Evidence?: L4Evidence;
-    /**
-     * Clock override for deterministic testing of staleness behavior.
-     * Defaults to the current wall clock.
-     */
-    now?: Date;
-}
-/**
- * Generate and sign a Sovereignty Health Report.
- *
- * @param identityId - Which identity to sign with (defaults to primary)
- * @param opts - Generator dependencies
- * @returns The signed SHR, or an error string
- */
-declare function generateSHR(identityId: string | undefined, opts: SHRGeneratorOptions): SignedSHR | string;
-
-/**
- * Sanctuary v1.1 Operator Hub API Constants
- *
- * Routes, prefixes, and small enums shared across the hub modules.
- * The hub API surface is consumed by the v1.1 dashboard UI (Prompt 8).
- *
- * Local-only invariant:
- * Every route here describes activity inside a single fortress on a single
- * operator's machine. Cross-fortress, fleet, and public-federation routes
- * are out of scope.
- */
-
-/**
- * Inbox-resolve actions. The router rejects any other action token.
- */
-declare const HUB_INBOX_ACTIONS: readonly ["approve", "deny", "dismiss"];
-type HubInboxAction = (typeof HUB_INBOX_ACTIONS)[number];
-/**
- * Agent-control actions surfaced by `POST /api/hub/agents/:id/:action`.
- *
- * `pause` / `resume` / `restart` are control-plane operations that the
- * underlying harness may execute immediately; they are not Tier 1.
- *
- * `unwrap` and `lockdown` are Tier 1 operations per the Principal Policy
- * loader. Hub endpoints for these MUST enqueue an `approval_pending` inbox
- * item rather than execute directly. Tier 1 approval gates remain in force
- * from the dashboard. The dashboard never auto-approves Tier 1 work.
- */
-declare const HUB_AGENT_CONTROL_ACTIONS: readonly ["pause", "resume", "restart", "unwrap", "lockdown"];
-type HubAgentControlAction = (typeof HUB_AGENT_CONTROL_ACTIONS)[number];
-
-/** Channel-template identifiers per the five-template canonical starter set. */
-declare const CHANNEL_TEMPLATE_IDS: readonly ["request-approve-act", "read-then-report", "scheduled-digest", "plan-draft-only", "fortress-relay"];
-type ChannelTemplateId = (typeof CHANNEL_TEMPLATE_IDS)[number];
-
 /**
  * Sanctuary MCP Server — Intelligence Substrate Selector Types
  *
@@ -5102,28 +5000,445 @@ declare class SubstrateSelector {
      * doesn't pre-spawn HTTP clients for substrates the operator never
      * touches.
      */
-    private buildHandle;
-    private disabledHandle;
-    private localHandle;
-    private veniceHandle;
-    private frontierHandle;
-    private probeSurfaceHealth;
-    private makeBadge;
-    private fallbackAction;
+    private buildHandle;
+    private disabledHandle;
+    private localHandle;
+    private veniceHandle;
+    private frontierHandle;
+    private probeSurfaceHealth;
+    private makeBadge;
+    private fallbackAction;
+    /**
+     * Internal hook for the Privacy Filter Tier 2 commit. Lets a redactor
+     * audit-emit a `pii_redaction_event` payload through the selector
+     * without exposing the AuditLog binding directly to redactor
+     * implementations.
+     */
+    emitRedactionEvent(args: {
+        surface: Surface;
+        substrate: SubstrateChoice;
+        matchCount: number;
+        filterTier: 1 | 2;
+    }): void;
+    private emit;
+}
+
+/**
+ * Sanctuary v1.3 WP-V1.3-1 Sentinel Finding Store.
+ *
+ * Encrypted at-rest persistence for sentinel findings. Sibling to the
+ * Upsilon-3 aggregator-store: same fortress-master-key-derived HKDF
+ * subkey shape, AAD-bound to the finding_id, retention-aware.
+ *
+ * Storage layout:
+ *   namespace: `_sentinel_findings`
+ *   key:       `finding.{finding_id}` (one record per finding)
+ *   payload:   AES-256-GCM ciphertext of the JSON-serialized record.
+ *   key:       `l2-sentinel-finding-v1` HKDF subkey of fortress master.
+ *   AAD:       UTF-8 bytes of `finding_id`.
+ *
+ * Multi-fortress isolation: HKDF subkey derives from the fortress
+ * master key. Two fortresses never produce identical encryption keys
+ * for identical finding_ids.
+ *
+ * Retention: 30 days default, mirroring the audit-log envelope and the
+ * aggregator payload store.
+ */
+
+interface SentinelFindingStoreOptions {
+    storage: StorageBackend;
+    masterKey: Uint8Array;
+    fortressId: string;
+    /** Operator-tunable retention window. Default 30 days. */
+    retentionDays?: number;
+    /** Wall-clock provider for deterministic tests. */
+    now?: () => Date;
+}
+declare class SentinelFindingStore {
+    private readonly storage;
+    private readonly encryptionKey;
+    private readonly fortressId;
+    private readonly retentionDays;
+    private readonly now;
+    constructor(opts: SentinelFindingStoreOptions);
+    /**
+     * Persist a finding. Truncates the operator-visible summary to
+     * SENTINEL_SUMMARY_MAX_CHARS so the dashboard render stays bounded.
+     * Returns the retention deadline so callers can audit it.
+     */
+    saveFinding(finding: SentinelFinding): Promise<string>;
+    /** Load a single finding by id, or null when absent / corrupted. */
+    loadFinding(findingId: string): Promise<SentinelFinding | null>;
+    /**
+     * List findings, newest first. Optional filters: since (ISO 8601),
+     * severity, sentinel_id, agent_id, limit. Default limit 100.
+     */
+    listFindings(opts?: {
+        since?: string;
+        severity?: SentinelSeverity;
+        sentinelId?: string;
+        agentId?: string;
+        limit?: number;
+    }): Promise<SentinelFinding[]>;
+    /**
+     * Drop expired findings. Returns the count removed.
+     */
+    pruneExpired(now?: Date): Promise<{
+        pruned: number;
+    }>;
+    private decode;
+}
+
+/**
+ * Sanctuary v1.3 WP-V1.3-1 Sentinel Baseline Pack (Castle Layer 2 anchor)
+ *
+ * Shared types for the Sentinel observation surface.
+ *
+ * Castle-walking discipline:
+ *  - Castle Layer 1 (Castle Wall) blocks unauthorized egress at the kernel
+ *    boundary. That is the enforcement layer.
+ *  - Castle Layer 2 (Sentinels) observes server-local data only and surfaces
+ *    anomalies. NO outbound network. NO blocking. Findings flow into the
+ *    operator surface they already check.
+ *  - Castle Layer 3 (Cooperative MCP) is the agent contract. Sentinels do
+ *    not wrap agent tools and do not negotiate with agents.
+ *
+ * Phi-1 ships the framework + the egress-volume watcher. Phi-2 through
+ * Phi-5 add credential-usage, cross-agent-chatter, suspicious-tool-call,
+ * and anomaly-trigger sentinels against this same shape.
+ */
+
+/** Severity tier returned by `Sentinel.evaluate()`. */
+type SentinelSeverity = "info" | "warn" | "alert";
+/**
+ * Read-only context handed to every sentinel on subscribe + evaluate.
+ * Sentinels do NOT receive a writable storage handle and do NOT receive
+ * an outbound HTTP client. The substrate selector is the single
+ * outbound-capable surface; Phi-1 sentinels do not exercise it but
+ * Phi-2/3/4/5 may want to invoke a local LLM for reasoning.
+ */
+interface SentinelContext {
+    /** Stable per-fortress identifier; multi-fortress isolation pivot. */
+    fortressId: string;
+    /** Audit log read API. Sentinels MUST NOT call append() through this. */
+    auditLog: AuditLog;
+    /** Optional substrate selector for LLM-backed reasoning. v1.3 Phi-1 unused. */
+    substrateSelector?: SubstrateSelector;
+    /** Wall-clock provider. Tests inject a deterministic clock. */
+    now: () => Date;
+    /**
+     * Optional read view of the per-fortress sentinel finding store
+     * (Phi-1 surface). First-order sentinels (Phi-1/2/3/4) do not need
+     * this; the Phi-5 meta-sentinel reads it to detect patterns ACROSS
+     * other sentinels' findings (compound finding, fortress-wide count
+     * spikes, novel sentinel-ID combinations). The dispatcher attaches
+     * the store automatically on `subscribeSentinel`; tests can omit it
+     * when constructing a context literal for a first-order watcher.
+     *
+     * Multi-fortress isolation rides on the store's existing key shape:
+     * the store is constructed per-fortress from the fortress master
+     * key, so two fortresses' stores produce distinct ciphertext for
+     * identical finding-ids and one fortress's read cannot decode
+     * another fortress's findings.
+     */
+    findingStore?: SentinelFindingStore;
+}
+/**
+ * One observation a sentinel produced. Persisted under the sentinel
+ * findings store + emitted as an audit event +
+ * surfaced to the operator dashboard.
+ */
+interface SentinelFinding {
+    /** Stable per-fortress finding id (UUID v4). */
+    finding_id: string;
+    /** Identifier of the sentinel that produced this finding. */
+    sentinel_id: string;
+    severity: SentinelSeverity;
+    /**
+     * Optional agent-id this finding pertains to. Absent when the finding
+     * is fortress-wide (e.g. cross-agent chatter spike).
+     */
+    agent_id?: string;
+    /** Operator-friendly one-liner. Truncated to 240 chars on persist. */
+    summary: string;
+    /**
+     * Structured payload. Schema varies per sentinel but every payload is
+     * a flat record of JSON-serializable values.
+     */
+    details: Record<string, unknown>;
+    /** ISO 8601 timestamp at evaluation time. */
+    observed_at: string;
+    /**
+     * Audit-log entries that triggered this finding. Sentinels populate
+     * with `${entry.timestamp}:${entry.operation}` tuples (mirrors the
+     * aggregator's audit_log_entry_id shape from Upsilon-1).
+     */
+    evidence_audit_ids: string[];
+    /** Stable fortress id stamped at emit. Multi-fortress isolation pivot. */
+    fortress_id: string;
+}
+
+/**
+ * Sanctuary v1.3 WP-V1.3-5 Pi-1 Honeypot Authoring types + audit ops.
+ *
+ * OPENS WP-V1.3-5 Honeypot Authoring. Operator writes a honeypot in
+ * plain English; the compiler maps the English to a structured
+ * TrapSpec; the runtime registers trap-handlers in the dashboard
+ * route table; trap activations emit `honeypot_triggered` audit
+ * events AND sentinel findings (Pi-1 reuses Phi-1's finding store so
+ * traps surface in the existing sentinel UX).
+ *
+ * Pi-1 ships the http_endpoint trap class only; Pi-2 adds filesystem,
+ * Pi-3 adds tool_call, Pi-4 adds credential. Architectural shape:
+ * TrapSpec is a discriminated union keyed by `trap_class` so new
+ * trap classes extend by adding a union arm + a runtime handler.
+ *
+ * Castle-walking discipline:
+ *  - Trap responses are server-local (404 or 500 returned to the
+ *    caller). No outbound surface from the trap path itself.
+ *  - The compile call routes through the substrate selector at the
+ *    `template-suggestion` surface (canonical outbound LLM channel
+ *    for template-shape generation; Rho-1 header strip applies).
+ *  - Trap findings route through the Phi-1 finding store, the
+ *    existing canonical pipeline for Castle Layer 2 observability.
+ */
+
+/** Operator-friendly trap class enum. */
+type TrapClass = "http_endpoint" | "filesystem" | "tool_call" | "credential";
+/**
+ * HTTP-endpoint trap trigger. The runtime matches incoming requests
+ * against `path_pattern` (glob-style with `*` and `**`); `method`
+ * narrows to a specific HTTP method when set, otherwise any method
+ * fires. `expected_caller_types` is operator-recorded metadata that
+ * surfaces in the finding's evidence; the runtime does not gate on
+ * it (caller identity is observed, not constrained, at the trap
+ * boundary).
+ */
+interface HttpEndpointTrigger {
+    kind: "http_endpoint";
+    path_pattern: string;
+    method?: string;
+    expected_caller_types: string[];
+}
+/**
+ * Filesystem trap trigger (Pi-2). The runtime monitor observes
+ * filesystem-shaped operations the operator declared sensitive and
+ * fires when a matching operation is reported through
+ * `FilesystemTrapMonitor.observe(...)`. Pi-2 ships the monitor as a
+ * pure observation primitive; specific wiring (proxy-call accesses,
+ * state-store reads, future tool-call instrumentation) attaches in
+ * follow-up PRs by calling the monitor's observe API.
+ *
+ * `ops` declares which operations the operator cares about; an
+ * `observe()` call whose `operation` is not in this set will not
+ * fire the trap.
+ */
+interface FilesystemTrigger {
+    kind: "filesystem";
+    /**
+     * Filesystem-path glob with `*` (one segment) / `**` (multiple
+     * segments). Anchored at both ends per the Pi-1 glob contract.
+     */
+    path_pattern: string;
+    /** Operations the trap fires on. */
+    ops: FilesystemOp[];
+    /** Operator-recorded metadata; not gated on. */
+    expected_caller_types: string[];
+}
+/** Filesystem operations recognized by the monitor. */
+type FilesystemOp = "read" | "write" | "delete" | "list";
+/**
+ * Discriminated-union trigger keyed by `kind`. The outer `trap_class`
+ * field on TrapSpec keeps the operator-facing taxonomy; the inner
+ * `kind` discriminator on the trigger is what TypeScript narrows on
+ * inside runtime handlers + the registry's matching code.
+ */
+type TrapTrigger = HttpEndpointTrigger | FilesystemTrigger;
+/**
+ * One compiled trap. Persisted by the registry, deployed to the
+ * runtime route table, and used by the finding emitter when a trap
+ * triggers. Pi-1 shipped http_endpoint only; Pi-2 adds filesystem
+ * via the `kind`-discriminated trigger union.
+ */
+interface TrapSpec {
+    trap_id: string;
+    trap_class: TrapClass;
+    trigger: TrapTrigger;
+    finding_severity: SentinelSeverity;
+    english_text: string;
+    explanation_paragraph: string;
+    compiled_at: string;
+}
+
+/**
+ * Sanctuary v1.3 WP-V1.3-5 Pi-2 Trap Store.
+ *
+ * Encrypted at-rest persistence for deployed honeypot TrapSpecs.
+ * Sibling to Phi-1's SentinelFindingStore: same fortress-master-key-
+ * derived HKDF subkey shape, AAD-bound to the trap_id, per-fortress
+ * scoped.
+ *
+ * Storage layout:
+ *   namespace: `_honeypot_traps`
+ *   key:       `trap.{trap_id}` (one record per deployed trap)
+ *   payload:   AES-256-GCM ciphertext of the JSON-serialized spec.
+ *   key:       `l2-honeypot-trap-v1` HKDF subkey of fortress master.
+ *   AAD:       UTF-8 bytes of `trap_id`.
+ *
+ * Multi-fortress isolation: HKDF subkey derives from the fortress
+ * master key. Two fortresses never produce identical encryption keys
+ * for identical trap_ids; a fortress that reads another fortress's
+ * encrypted record cannot decrypt it.
+ *
+ * Persistence contract:
+ *   - save(spec): write the spec under its trap_id. Idempotent;
+ *     re-saves overwrite.
+ *   - delete(trapId): remove the record. Idempotent.
+ *   - loadAll(): rehydrate every persisted spec. Used at boot to
+ *     populate the in-memory TrapRegistry. Corrupted records are
+ *     dropped (best-effort recovery: a malformed entry should not
+ *     block the rest of the fortress).
+ *
+ * Pi-2 ships traps with no retention window (traps stay deployed
+ * until explicitly undeployed). The store mirrors SentinelFindingStore's
+ * AES-256-GCM envelope shape but omits retention deadlines.
+ */
+
+interface TrapStoreOptions {
+    storage: StorageBackend;
+    masterKey: Uint8Array;
+    fortressId: string;
+}
+declare class TrapStore {
+    private readonly storage;
+    private readonly encryptionKey;
+    private readonly fortressId;
+    constructor(opts: TrapStoreOptions);
+    /** Persist (or overwrite) one trap. Returns the trap_id on success. */
+    save(spec: TrapSpec): Promise<string>;
+    /**
+     * Remove one trap by id. Returns true when a record was removed,
+     * false when no record existed (idempotent).
+     */
+    delete(trapId: string): Promise<boolean>;
+    /**
+     * Load every persisted trap. Used at boot to repopulate the
+     * in-memory TrapRegistry. Corrupted records are silently skipped
+     * so one malformed entry never blocks the rest of the fortress's
+     * traps from rehydrating.
+     *
+     * Returns the specs sorted by `compiled_at` ascending so the
+     * in-memory registry's insertion order matches the original
+     * deploy order (relevant for Pi-1's "first-deployed wins on
+     * overlapping match" contract).
+     */
+    loadAll(): Promise<TrapSpec[]>;
+    /** Read-only fortress-id getter. */
+    getFortressId(): string;
+    private decode;
+}
+
+/**
+ * Sanctuary MCP Server — SHR Generator
+ *
+ * Generates a Sovereignty Health Report from current server state,
+ * signs it with a specified identity, and returns the complete signed SHR.
+ */
+
+/**
+ * Observed L4 reputation state used by the emitter. Callers gather these
+ * facts from the reputation store + audit log; the emitter derives
+ * degradations from them. Keeping evidence as plain data keeps the
+ * generator synchronous and easy to test.
+ */
+interface L4Evidence {
+    /** Total attestations attributed to the signing identity */
+    attestation_count: number;
+    /** Count of attestations at each sovereignty tier */
+    tier_distribution: Record<SovereigntyTier, number>;
+    /** ISO timestamp of most recent attestation, or null when none exist */
+    most_recent_attestation_at: string | null;
+    /** Count of attestations with outcome_result === "disputed" */
+    dispute_count: number;
+    /** Attestation count per context label (optional; used by dashboard) */
+    context_breakdown?: Record<string, number>;
+    /**
+     * True iff the `reputation_publish` tool has been successfully invoked
+     * for this identity (i.e., there is at least one success audit entry).
+     */
+    verascore_linked: boolean;
+    /**
+     * Optional overrides for the emitter thresholds. Defaults apply when
+     * omitted or when a field is missing.
+     */
+    thresholds?: {
+        freshness_window_days?: number;
+        low_tier_dominance_threshold?: number;
+    };
+}
+interface SHRGeneratorOptions {
+    config: SanctuaryConfig;
+    identityManager: IdentityManager;
+    masterKey: Uint8Array;
+    /** Override validity window (milliseconds). Default: 1 hour. */
+    validityMs?: number;
+    /**
+     * Optional L4 reputation evidence. When provided, the generator emits
+     * L4 degradations (NO_REPUTATION_HISTORY, LOW_TIER_DOMINANCE,
+     * STALE_REPUTATION, DISPUTE_ON_RECORD, NO_VERASCORE_LINK) accordingly
+     * and downgrades `layers.l4.status` to `degraded` when any fire.
+     * When omitted, L4 is left at "active" (backward-compatible).
+     */
+    l4Evidence?: L4Evidence;
     /**
-     * Internal hook for the Privacy Filter Tier 2 commit. Lets a redactor
-     * audit-emit a `pii_redaction_event` payload through the selector
-     * without exposing the AuditLog binding directly to redactor
-     * implementations.
+     * Clock override for deterministic testing of staleness behavior.
+     * Defaults to the current wall clock.
      */
-    emitRedactionEvent(args: {
-        surface: Surface;
-        substrate: SubstrateChoice;
-        matchCount: number;
-        filterTier: 1 | 2;
-    }): void;
-    private emit;
+    now?: Date;
 }
+/**
+ * Generate and sign a Sovereignty Health Report.
+ *
+ * @param identityId - Which identity to sign with (defaults to primary)
+ * @param opts - Generator dependencies
+ * @returns The signed SHR, or an error string
+ */
+declare function generateSHR(identityId: string | undefined, opts: SHRGeneratorOptions): SignedSHR | string;
+
+/**
+ * Sanctuary v1.1 Operator Hub API Constants
+ *
+ * Routes, prefixes, and small enums shared across the hub modules.
+ * The hub API surface is consumed by the v1.1 dashboard UI (Prompt 8).
+ *
+ * Local-only invariant:
+ * Every route here describes activity inside a single fortress on a single
+ * operator's machine. Cross-fortress, fleet, and public-federation routes
+ * are out of scope.
+ */
+
+/**
+ * Inbox-resolve actions. The router rejects any other action token.
+ */
+declare const HUB_INBOX_ACTIONS: readonly ["approve", "deny", "dismiss"];
+type HubInboxAction = (typeof HUB_INBOX_ACTIONS)[number];
+/**
+ * Agent-control actions surfaced by `POST /api/hub/agents/:id/:action`.
+ *
+ * `pause` / `resume` / `restart` are control-plane operations that the
+ * underlying harness may execute immediately; they are not Tier 1.
+ *
+ * `unwrap` and `lockdown` are Tier 1 operations per the Principal Policy
+ * loader. Hub endpoints for these MUST enqueue an `approval_pending` inbox
+ * item rather than execute directly. Tier 1 approval gates remain in force
+ * from the dashboard. The dashboard never auto-approves Tier 1 work.
+ */
+declare const HUB_AGENT_CONTROL_ACTIONS: readonly ["pause", "resume", "restart", "unwrap", "lockdown"];
+type HubAgentControlAction = (typeof HUB_AGENT_CONTROL_ACTIONS)[number];
+
+/** Channel-template identifiers per the five-template canonical starter set. */
+declare const CHANNEL_TEMPLATE_IDS: readonly ["request-approve-act", "read-then-report", "scheduled-digest", "plan-draft-only", "fortress-relay"];
+type ChannelTemplateId = (typeof CHANNEL_TEMPLATE_IDS)[number];
 
 /**
  * Sanctuary MCP Server — Operator Chat Types
@@ -7258,161 +7573,6 @@ declare class ApprovalAggregator {
     private hydrate;
 }
 
-/**
- * Sanctuary v1.3 WP-V1.3-1 Sentinel Finding Store.
- *
- * Encrypted at-rest persistence for sentinel findings. Sibling to the
- * Upsilon-3 aggregator-store: same fortress-master-key-derived HKDF
- * subkey shape, AAD-bound to the finding_id, retention-aware.
- *
- * Storage layout:
- *   namespace: `_sentinel_findings`
- *   key:       `finding.{finding_id}` (one record per finding)
- *   payload:   AES-256-GCM ciphertext of the JSON-serialized record.
- *   key:       `l2-sentinel-finding-v1` HKDF subkey of fortress master.
- *   AAD:       UTF-8 bytes of `finding_id`.
- *
- * Multi-fortress isolation: HKDF subkey derives from the fortress
- * master key. Two fortresses never produce identical encryption keys
- * for identical finding_ids.
- *
- * Retention: 30 days default, mirroring the audit-log envelope and the
- * aggregator payload store.
- */
-
-interface SentinelFindingStoreOptions {
-    storage: StorageBackend;
-    masterKey: Uint8Array;
-    fortressId: string;
-    /** Operator-tunable retention window. Default 30 days. */
-    retentionDays?: number;
-    /** Wall-clock provider for deterministic tests. */
-    now?: () => Date;
-}
-declare class SentinelFindingStore {
-    private readonly storage;
-    private readonly encryptionKey;
-    private readonly fortressId;
-    private readonly retentionDays;
-    private readonly now;
-    constructor(opts: SentinelFindingStoreOptions);
-    /**
-     * Persist a finding. Truncates the operator-visible summary to
-     * SENTINEL_SUMMARY_MAX_CHARS so the dashboard render stays bounded.
-     * Returns the retention deadline so callers can audit it.
-     */
-    saveFinding(finding: SentinelFinding): Promise<string>;
-    /** Load a single finding by id, or null when absent / corrupted. */
-    loadFinding(findingId: string): Promise<SentinelFinding | null>;
-    /**
-     * List findings, newest first. Optional filters: since (ISO 8601),
-     * severity, sentinel_id, agent_id, limit. Default limit 100.
-     */
-    listFindings(opts?: {
-        since?: string;
-        severity?: SentinelSeverity;
-        sentinelId?: string;
-        agentId?: string;
-        limit?: number;
-    }): Promise<SentinelFinding[]>;
-    /**
-     * Drop expired findings. Returns the count removed.
-     */
-    pruneExpired(now?: Date): Promise<{
-        pruned: number;
-    }>;
-    private decode;
-}
-
-/**
- * Sanctuary v1.3 WP-V1.3-1 Sentinel Baseline Pack (Castle Layer 2 anchor)
- *
- * Shared types for the Sentinel observation surface.
- *
- * Castle-walking discipline:
- *  - Castle Layer 1 (Castle Wall) blocks unauthorized egress at the kernel
- *    boundary. That is the enforcement layer.
- *  - Castle Layer 2 (Sentinels) observes server-local data only and surfaces
- *    anomalies. NO outbound network. NO blocking. Findings flow into the
- *    operator surface they already check.
- *  - Castle Layer 3 (Cooperative MCP) is the agent contract. Sentinels do
- *    not wrap agent tools and do not negotiate with agents.
- *
- * Phi-1 ships the framework + the egress-volume watcher. Phi-2 through
- * Phi-5 add credential-usage, cross-agent-chatter, suspicious-tool-call,
- * and anomaly-trigger sentinels against this same shape.
- */
-
-/** Severity tier returned by `Sentinel.evaluate()`. */
-type SentinelSeverity = "info" | "warn" | "alert";
-/**
- * Read-only context handed to every sentinel on subscribe + evaluate.
- * Sentinels do NOT receive a writable storage handle and do NOT receive
- * an outbound HTTP client. The substrate selector is the single
- * outbound-capable surface; Phi-1 sentinels do not exercise it but
- * Phi-2/3/4/5 may want to invoke a local LLM for reasoning.
- */
-interface SentinelContext {
-    /** Stable per-fortress identifier; multi-fortress isolation pivot. */
-    fortressId: string;
-    /** Audit log read API. Sentinels MUST NOT call append() through this. */
-    auditLog: AuditLog;
-    /** Optional substrate selector for LLM-backed reasoning. v1.3 Phi-1 unused. */
-    substrateSelector?: SubstrateSelector;
-    /** Wall-clock provider. Tests inject a deterministic clock. */
-    now: () => Date;
-    /**
-     * Optional read view of the per-fortress sentinel finding store
-     * (Phi-1 surface). First-order sentinels (Phi-1/2/3/4) do not need
-     * this; the Phi-5 meta-sentinel reads it to detect patterns ACROSS
-     * other sentinels' findings (compound finding, fortress-wide count
-     * spikes, novel sentinel-ID combinations). The dispatcher attaches
-     * the store automatically on `subscribeSentinel`; tests can omit it
-     * when constructing a context literal for a first-order watcher.
-     *
-     * Multi-fortress isolation rides on the store's existing key shape:
-     * the store is constructed per-fortress from the fortress master
-     * key, so two fortresses' stores produce distinct ciphertext for
-     * identical finding-ids and one fortress's read cannot decode
-     * another fortress's findings.
-     */
-    findingStore?: SentinelFindingStore;
-}
-/**
- * One observation a sentinel produced. Persisted under the sentinel
- * findings store + emitted as an audit event +
- * surfaced to the operator dashboard.
- */
-interface SentinelFinding {
-    /** Stable per-fortress finding id (UUID v4). */
-    finding_id: string;
-    /** Identifier of the sentinel that produced this finding. */
-    sentinel_id: string;
-    severity: SentinelSeverity;
-    /**
-     * Optional agent-id this finding pertains to. Absent when the finding
-     * is fortress-wide (e.g. cross-agent chatter spike).
-     */
-    agent_id?: string;
-    /** Operator-friendly one-liner. Truncated to 240 chars on persist. */
-    summary: string;
-    /**
-     * Structured payload. Schema varies per sentinel but every payload is
-     * a flat record of JSON-serializable values.
-     */
-    details: Record<string, unknown>;
-    /** ISO 8601 timestamp at evaluation time. */
-    observed_at: string;
-    /**
-     * Audit-log entries that triggered this finding. Sentinels populate
-     * with `${entry.timestamp}:${entry.operation}` tuples (mirrors the
-     * aggregator's audit_log_entry_id shape from Upsilon-1).
-     */
-    evidence_audit_ids: string[];
-    /** Stable fortress id stamped at emit. Multi-fortress isolation pivot. */
-    fortress_id: string;
-}
-
 /**
  * Sanctuary v1.3 WP-V1.3-1 Sentinel base class.
  *
@@ -8035,6 +8195,69 @@ declare class HandoffEventBridge {
     emit(entry: HandoffEntry): void;
 }
 
+/**
+ * Sanctuary v1.3 WP-V1.3-5 Pi-1 Trap Registry.
+ *
+ * Per-fortress in-memory registry of deployed honeypot traps. Holds
+ * the live TrapSpec set + provides path-matching for the runtime
+ * dispatcher.
+ *
+ * Lifecycle:
+ *   deploy(spec):         activates the trap; idempotent on trap_id.
+ *   undeploy(trapId):     removes the trap; returns whether anything
+ *                         was actually removed (idempotent).
+ *   list():               returns the live trap set as a fresh array.
+ *   findMatching(path,m): returns the first trap matching the request.
+ *
+ * Castle-walking discipline:
+ *   - Read-only path against deployed traps; mutating calls land here
+ *     deliberately from the management routes.
+ *   - No outbound surface; the registry is purely server-local state.
+ *   - Per-fortress isolation: one registry instance per fortress. The
+ *     dispatcher wires one registry per dashboard instance.
+ *
+ * Path-matching glob:
+ *   *   matches one path segment (no slashes)
+ *   **  matches multiple path segments (zero or more, including
+ *       slashes)
+ *   anything else is a literal character. The pattern is anchored at
+ *   both ends so `/admin` does NOT match `/admin/foo`; the operator
+ *   must use `/admin/**` to match prefix-style.
+ */
+
+interface TrapMatchInput {
+    /** Request URL path. */
+    path: string;
+    /** Uppercased HTTP method. */
+    method: string;
+}
+declare class TrapRegistry {
+    private readonly traps;
+    /**
+     * Deploy a trap. Idempotent on `trap_id`: re-deploying replaces the
+     * previous spec for that id. Returns true on first deploy, false on
+     * re-deploy (so callers can branch audit emission).
+     */
+    deploy(spec: TrapSpec): boolean;
+    /**
+     * Undeploy by trap_id. Returns true when a trap was removed, false
+     * when no trap had that id (idempotent).
+     */
+    undeploy(trapId: string): boolean;
+    /** List deployed traps. Returns a fresh array; mutation is safe. */
+    list(): TrapSpec[];
+    /** Look up a single trap by id. */
+    get(trapId: string): TrapSpec | undefined;
+    /**
+     * Find the first trap matching the request. Iteration order is
+     * insertion order; operators who deploy multiple overlapping traps
+     * see the earliest-deployed one fire. Tests cover this contract.
+     */
+    findMatching(input: TrapMatchInput): TrapSpec | undefined;
+    /** Drop every trap. Tests use this between runs; not surfaced via API. */
+    clear(): void;
+}
+
 interface DashboardConfig {
     port: number;
     host: string;
@@ -8131,6 +8354,13 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
     private workflowStateTracker;
     private handoffAuditLog;
     private handoffOperatorId;
+    private honeypotRegistry;
+    private honeypotFindingStore;
+    private honeypotAuditLog;
+    private honeypotOperatorId;
+    private honeypotFortressId;
+    private honeypotSelector;
+    private honeypotStore;
     constructor(config: DashboardConfig);
     /**
      * Inject dependencies after construction.
@@ -8199,6 +8429,38 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
          */
         workflowStateTracker?: WorkflowStateTracker | null;
     }): void;
+    /**
+     * v1.3 WP-V1.3-5 Pi-1 Honeypot Authoring: bind the per-fortress
+     * trap registry + finding store + audit log + operator id. Once
+     * set, two surfaces activate:
+     *   1. Front-of-dispatch trap-trigger hook: every request runs
+     *      through `handleHoneypotTriggerIfMatch` BEFORE legacy/v1.1/
+     *      sentinel/coordination routing. Matching traps return 404
+     *      and the request never reaches the regular dispatcher.
+     *   2. Management API at /api/honeypot/* routes through
+     *      `handleHoneypotRoute`.
+     *
+     * The optional `selector` opt wires the LLM compile path; absent
+     * selector forces the heuristic compile path (which still produces
+     * a usable TrapSpec with warnings).
+     */
+    setHoneypotRegistry(opts: {
+        registry: TrapRegistry | null;
+        findingStore?: SentinelFindingStore | null;
+        auditLog?: AuditLog | null;
+        operatorId?: string | null;
+        fortressId?: string | null;
+        selector?: SubstrateSelector | null;
+        /**
+         * Pi-2: encrypted at-rest persistence for the deployed traps. When
+         * non-null, the management API's deploy + undeploy handlers write
+         * through to the store so the fortress keeps its trap deployment
+         * across restart. Boot rehydration is the host's responsibility:
+         * call `store.loadAll()` and `registry.deploy(spec)` for each
+         * persisted spec BEFORE calling this method.
+         */
+        store?: TrapStore | null;
+    }): void;
     /**
      * v1.3 WP-V1.3-10 dispatch entry point. Called from `handleRequest`
      * before the legacy approval route table. Returns true when served.
@@ -8216,6 +8478,21 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      * when a HandoffLog has been bound. Returns true when served.
      */
     private dispatchCoordination;
+    /**
+     * v1.3 WP-V1.3-5 Pi-1 dispatch entry point. Routes
+     * `/api/honeypot/*` requests through the honeypot management
+     * router when a registry has been bound. Returns true when served.
+     */
+    private dispatchHoneypot;
+    /**
+     * v1.3 WP-V1.3-5 Pi-1 front-of-dispatch trap-trigger hook. Examines
+     * every request BEFORE legacy/v1.1/sentinel/coordination routing.
+     * Returns true when a deployed trap matched the request and the
+     * handler emitted the audit event + sentinel finding + plausible
+     * 404 response. Returns false when no trap matched; caller
+     * continues with normal routing.
+     */
+    private dispatchHoneypotTrap;
     /**
      * v1.1 dispatch entry point. Called from `handleRequest` before the
      * legacy route table. Returns true when the request was served by v1.1
@@ -8302,6 +8579,14 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      */
     private pruneRateLimits;
     private handleRequest;
+    /**
+     * v1.3 WP-V1.3-5 Pi-1: post-honeypot-trap request continuation. The
+     * front-of-dispatch trap-trigger hook may short-circuit a request;
+     * when it does not, this method runs the original dispatch ladder.
+     * Pulled out as a helper so the trap-hook + non-trap paths share
+     * one code path through every downstream dispatcher.
+     */
+    private continueHandleRequest;
     private handleLegacyRequest;
     /**
      * SEC-012: Exchange a long-lived auth token (in Authorization header)