comisai 1.0.41 → 1.0.44

package/node_modules/@comis/core/dist/ports/memory-usefulness-store.d.ts

@@ -0,0 +1,114 @@
+import type { Result } from "@comis/shared";
+import type { LearningScope } from "./outcome-signal-port.js";
+/**
+ * MemoryUsefulnessStore: the SEGREGATED hexagonal boundary for the recall-utility
+ * feedback loop — the durable per-memory signal of whether a recalled
+ * memory was actually USED (attributed) or IGNORED, so recall can learn from
+ * outcomes (the leapfrog Hindsight structurally cannot follow — `access_count`
+ * is dead schema there; HINDSIGHT_VS_COMIS.md #7).
+ *
+ * This is a NEW port — it deliberately does NOT widen the security-reviewed
+ * `MemoryPort` (store/search/delete). Per design §3.2 that surface is never
+ * widened for agent use; new capabilities arrive as their own segregated port
+ * (the same pattern as `MemoryConsolidationStore` §6.5 / `MemoryEntityStore`
+ * §3.2). The sole adapter is in @comis/memory (it owns the `db` handle and runs
+ * all SQL); the agent read path (recall scoring) consumes this port TYPE from
+ * @comis/core — it cannot import @comis/memory (the agent↛memory build cut). No
+ * new authority is granted beyond a scoped read/write within the caller's own
+ * (tenant, agent).
+ *
+ * This file is type-only (mirrors reranker.ts): no zod, no @comis/memory import.
+ */
+/**
+ * The isolation boundary for every usefulness operation. Every
+ * statement in the sole adapter filters on `(tenantId, agentId)` and the table
+ * PRIMARY KEY keys on `(tenant_id, agent_id, memory_id)` — this is a
+ * load-bearing SECURITY scope in a multi-agent DB, not a nicety: a write under
+ * one (tenant, agent) must NEVER be visible to a read under another, even when
+ * the `memory_id` is identical.
+ *
+ * SIMPLIFY-02: UNIFIED onto the canonical {@link LearningScope} — the isolation
+ * fields are NOT re-declared (the 15× per-port repetition the collapse kills).
+ * A thin alias that DERIVES `tenantId`/`agentId` from `LearningScope`, re-narrows
+ * the injected clock `now` to REQUIRED (the `recordUsage`/`recordFailure` write
+ * paths), AND carries the usefulness-specific `intent?` per-query bucket key
+ * (an ADDITIONAL key, NEVER a relaxation of the (tenant, agent) isolation scope).
+ */
+export type UsefulnessScope = LearningScope & {
+    /**
+     * Injected epoch ms for `last_useful_at` bookkeeping. REQUIRED on the
+     * usefulness write path. NEVER `Date.now()` — the caller supplies it from an
+     * injected clock so the write path stays deterministic/testable.
+     */
+    now: number;
+    /**
+     * Optional query-INTENT bucket. When present, the read fetches /
+     * the write records the per-intent usefulness signal (a memory's usefulness FOR
+     * THAT intent); when OMITTED the adapter resolves the GLOBAL bucket (intent="")
+     * — byte-identical to the prior behaviour. The closed-union value comes from the agent's
+     * deterministic `classifyIntent` (LLM-free); typed here as a plain string so
+     * @comis/core takes no @comis/agent dependency. NOT a security
+     * boundary — (tenantId, agentId) remain the isolation scope; intent is an
+     * ADDITIONAL key, never a relaxation.
+     *
+     * Because `readUsefulness` takes `Omit<UsefulnessScope, "now">`, this optional
+     * field flows to BOTH `recordUsage` (the write) AND the read automatically.
+     */
+    intent?: string;
+};
+/**
+ * Per-memory usefulness signal. Counts only — no content ever enters
+ * this layer (content-free, like the `memory:*` bus events). A memory id with no
+ * persisted row is absent from `readUsefulness`'s Map (→ a neutral factor in
+ * score.ts), so these counts only ever start at the values written.
+ */
+export interface UsefulnessSignal {
+    /** Times this memory was recalled AND attributed as used. */
+    usedCount: number;
+    /** Times recalled but NOT used. */
+    ignoredCount: number;
+    /** Epoch ms of the last "used" attribution (absent until first use). */
+    lastUsefulAt?: number;
+    /**
+     * WR-03 (RANK-01): outcome-attributed task FAILURE count — surfaced ONLY when > 0
+     * (absent for a clean memory, like `lastUsefulAt`). It is the NEGATIVE-reward signal
+     * the OFFLINE bandit feed consumes (a memory in the `recalled_ids` of a `failure`/
+     * `corrected` trajectory accrues it, corroboration-gated). The recall HOT PATH
+     * (`score.ts` `usefulnessNorm`) reads ONLY `usedCount`/`ignoredCount` and IGNORES this
+     * field, so projecting it is byte-identical for recall ranking — it exists for the
+     * bandit's posterior, not the live score.
+     */
+    failureCount?: number;
+}
+export interface MemoryUsefulnessStore {
+    /**
+     * WRITE. Increment `used_count` for `usedIds` and `ignored_count`
+     * for `ignoredIds`, upserting the (tenant, agent, memory_id) row; set
+     * `last_useful_at = scope.now` for `usedIds`. Idempotent at the row level
+     * (INSERT ... ON CONFLICT DO UPDATE) — re-running over the same ids increments,
+     * never duplicates rows. Empty `usedIds` AND empty `ignoredIds` → no-op
+     * `ok(undefined)` (no transaction). The caller (the attribution path) produces
+     * DISJOINT sets; a stray id appearing in both is touched used-before-ignored.
+     */
+    recordUsage(usedIds: string[], ignoredIds: string[], scope: UsefulnessScope): Promise<Result<void, Error>>;
+    /**
+     * READ. Bulk-fetch the usefulness signal for `memoryIds`, scoped to
+     * (tenant, agent). Returns a Map keyed by memory id; ids with no persisted row
+     * are ABSENT from the map (→ a neutral 1.0 factor in score.ts). Empty input →
+     * empty map, no query.
+     */
+    readUsefulness(memoryIds: string[], scope: Omit<UsefulnessScope, "now">): Promise<Result<Map<string, UsefulnessSignal>, Error>>;
+    /**
+     * WRITE (FORGET-02). Accrue an outcome-attributed task FAILURE for `memoryId`
+     * — increment `failure_count` on the (tenant, agent, memory_id, intent) bucket
+     * (first touch INSERTs failure_count=1). `failure_count` is a DISTINCT signal
+     * from `ignored_count`: a correct-but-unused memory accrues `ignored_count`
+     * (recalled-but-not-cited), NEVER `failure_count`; only a memory in the
+     * `recalled_ids` of a `failure`/`corrected` trajectory accrues here — and the
+     * caller (the daemon reward seam) gates that on the anti-induced-eviction
+     * corroboration rule (FORGET-03). Idempotent at the row level
+     * (INSERT ... ON CONFLICT DO UPDATE). The (tenant, agent) filter is the
+     * load-bearing isolation boundary; `intent` is an ADDITIONAL key.
+     */
+    recordFailure(memoryId: string, scope: UsefulnessScope): Promise<Result<void, Error>>;
+}

package/node_modules/@comis/core/dist/ports/memory-usefulness-store.js

@@ -0,0 +1 @@
+export {};

package/node_modules/@comis/core/dist/ports/memory.d.ts

@@ -15,6 +15,15 @@ export interface MemorySearchOptions {
     tags?: string[];
     /** Filter by agent ID (when provided, only return memories created by this agent) */
     agentId?: string;
+    /** Read-side NL temporal-range filter. Epoch ms; ANDed onto the ALREADY-scoped
+     *  query (tenant_id = ? AND agent_id = ? AND occurred_at BETWEEN ? AND ?) — it can only
+     *  NARROW, never widen scope (§5.2). Absent → no range filter (recall unchanged). Both
+     *  `search` and `searchLanes` carry MemorySearchOptions, so this threads to both with no
+     *  signature change; the SQLite WHERE clause is added in hybrid-search.ts. */
+    occurredAtRange?: {
+        start: number;
+        end: number;
+    };
 }
 /**
  * A search result with relevance score.
@@ -24,16 +33,6 @@ export interface MemorySearchResult {
     /** Similarity score (0-1), present when vector search is used */
     score?: number;
 }
-/**
- * Fields that can be updated on a memory entry.
- */
-export interface MemoryUpdateFields {
-    content?: string;
-    tags?: string[];
-    trustLevel?: "system" | "learned" | "external";
-    embedding?: number[];
-    expiresAt?: number;
-}
 /**
  * MemoryPort: The hexagonal architecture boundary for persistent memory.
  *
@@ -52,14 +51,6 @@ export interface MemoryPort {
      * @returns The stored entry, or an error
      */
     store(entry: MemoryEntry): Promise<Result<MemoryEntry, Error>>;
-    /**
-     * Retrieve a memory entry by its ID.
-     *
-     * @param id - The UUID of the memory entry
-     * @param tenantId - Tenant scope (defaults to "default")
-     * @returns The entry if found, or undefined if not found, or an error
-     */
-    retrieve(id: string, tenantId?: string): Promise<Result<MemoryEntry | undefined, Error>>;
     /**
      * Search for memory entries using text/vector similarity.
      *
@@ -70,14 +61,38 @@ export interface MemoryPort {
      */
     search(sessionKey: SessionKey, query: string | number[], options?: MemorySearchOptions): Promise<Result<MemorySearchResult[], Error>>;
     /**
-     * Update fields on an existing memory entry.
+     * OPTIONAL: search returning the FTS-ranked and vector-ranked
+     * candidate lists SEPARATELY — the un-fused split.
      *
-     * @param id - The UUID of the entry to update
-     * @param fields - The fields to update
-     * @param tenantId - Tenant scope (defaults to "default")
-     * @returns The updated entry, or an error
+     * Where {@link search} fuses the FTS + vector lanes INTERNALLY (RRF, weights
+     * 1.0/1.5) and returns ONE merged scored list, `searchLanes` returns the two
+     * ranked lists UN-fused so a downstream layer (the agent's `fuse()`) can fuse
+     * them with OPERATOR-TUNABLE per-lane weights and report TRUE per-lane
+     * candidate counts. It is the SAME search over the SAME tenant-scoped rows,
+     * just un-fused — NOT a new authority surface.
+     *
+     * Contract for an implementer:
+     * - Over-fetch the SAME `limit * 2` per lane that the fused `search` path
+     *   over-fetches, so the candidate pools entering fusion match the fused path.
+     * - Return RAW hydrated lanes — do NOT apply `minScore` (that filter moves to
+     *   the fusion/recall layer, applied AFTER fusion).
+     * - Resolve the embedding exactly as `search` does; an absent/zero-length
+     *   embedding (or no vector backend) yields an EMPTY `vector` lane.
+     * - Each lane is ordered most-relevant-first (rank 1 = first).
+     *
+     * This method is OPTIONAL: an adapter MAY omit it. Callers that find it absent
+     * MUST fall back to {@link search} (the single-lane path) — this is a
+     * graceful-degrade, not a compatibility toggle.
+     *
+     * @param sessionKey - Session context to scope the search (tenant isolation)
+     * @param query - Text query or embedding vector
+     * @param options - Search filters and limits (minScore is IGNORED here)
+     * @returns The two ranked, hydrated candidate lists, or an error
      */
-    update(id: string, fields: MemoryUpdateFields, tenantId?: string): Promise<Result<MemoryEntry, Error>>;
+    searchLanes?(sessionKey: SessionKey, query: string | number[], options?: MemorySearchOptions): Promise<Result<{
+        fts: MemorySearchResult[];
+        vector: MemorySearchResult[];
+    }, Error>>;
     /**
      * Delete a memory entry by its ID.
      *
@@ -87,11 +102,43 @@ export interface MemoryPort {
      */
     delete(id: string, tenantId?: string): Promise<Result<boolean, Error>>;
     /**
-     * Clear all memory entries for a session.
-     * Use with caution -- this is destructive.
+     * Phase 172 (DIST-05): Delete all memory entries matching a session key
+     * + tenant+agent scope. Covers BOTH paired-conversation memories and
+     * LCD-distilled episodic memories (both store source_session_key on the
+     * memories row). The ON DELETE CASCADE on lcd_memory_provenance.memory_id
+     * handles provenance row cleanup automatically.
+     *
+     * R4-scoped: scope.tenantId + scope.agentId are REQUIRED — never deletes
+     * cross-tenant or cross-agent rows. Returns count of deleted memories rows,
+     * or an error.
+     *
+     * OPTIONAL: existing MemoryPort implementations do not need to implement
+     * this until 172-03 adds the concrete SQL in sqlite-memory-adapter.ts.
+     * The session-archive.ts handler gates on `deps.memoryPort.deleteBySessionKey`.
+     */
+    deleteBySessionKey?(sessionKey: string, scope: {
+        tenantId: string;
+        agentId: string;
+    }): Promise<Result<number, Error>>;
+    /**
+     * Phase 172 (DIST-05, WR-02): List the memory ids for a (sessionKey, tenant,
+     * agent) scope WITHOUT deleting them. Called by the
+     * `session.reset_conversation --memory` handler BEFORE `deleteBySessionKey`
+     * runs, so the captured ids can be passed to
+     * `purgeConsolidatedDerivedFrom(..., thisSessionIds)` — making the
+     * `--purge-derived` sweep match "observations derived from THIS session" rather
+     * than the coarse "any observation with a dangling source id" (which would
+     * over-delete unrelated observations that already had a prior dangling source).
+     *
+     * R4-scoped: filters on `source_session_key` AND `tenant_id` AND `agent_id`,
+     * matching `deleteBySessionKey`'s scope exactly. Returns the ids (possibly
+     * empty), or an error.
      *
-     * @param sessionKey - Session context to scope the clear
-     * @returns The number of entries deleted, or an error
+     * OPTIONAL: the handler gates on `deps.memoryPort.listMemoryIdsBySessionKey`;
+     * when absent, the purge falls back to its coarse session-agnostic behavior.
      */
-    clear(sessionKey: SessionKey): Promise<Result<number, Error>>;
+    listMemoryIdsBySessionKey?(sessionKey: string, scope: {
+        tenantId: string;
+        agentId: string;
+    }): Promise<Result<string[], Error>>;
 }

package/node_modules/@comis/core/dist/ports/outcome-signal-port.d.ts

@@ -0,0 +1,148 @@
+import type { Result } from "@comis/shared";
+/**
+ * OutcomeSignalPort: the SEGREGATED hexagonal boundary for the v2.26 Verified
+ * Learning outcome signal (WS1) — the durable record of a finished trajectory's
+ * net task-outcome (success / failure / corrected / unknown) so that ALL
+ * learning can gate on a real task-outcome signal instead of a text-overlap
+ * proxy (design §WS1). It captures raw observations (`observe`), fuses them
+ * precedence-first into one resolved verdict (`resolve`), and bounds the
+ * append-only ledger by age (`prune`).
+ *
+ * This is a NEW port — like {@link MemoryUsefulnessStore} it deliberately does
+ * NOT widen the security-reviewed `MemoryPort` (store/search/delete). The sole
+ * adapter lives in @comis/memory (it owns the `db` handle and runs all SQL);
+ * the outcome capture is invoked DAEMON-SIDE (the daemon depends on everything
+ * and injects the adapter). Any future agent-side consumer (Phase 201 synthesis)
+ * imports this port TYPE only — it cannot import @comis/memory (the agent↛memory
+ * build cut). No new authority is granted beyond a scoped read/write within the
+ * caller's own (tenant, agent).
+ *
+ * This file is type-only (mirrors memory-usefulness-store.ts): no zod, no
+ * @comis/memory import. There is no memory-specific error type — every method
+ * returns `Result<T, Error>` from @comis/shared.
+ */
+/**
+ * The isolation boundary for every outcome operation. The sole adapter filters
+ * every statement on `(tenantId, agentId)` and the table keys on
+ * `(tenant_id, agent_id, trajectory_id, …)` — this is a load-bearing SECURITY
+ * scope in a multi-agent DB (an observation under one (tenant, agent) must NEVER
+ * be visible to a read under another), not a nicety. Unresolved `(tenant, agent)`
+ * MUST fail-closed (raise/err) at the adapter — never default to a shared/global
+ * pool (SEC-01, design §9). Mirrors {@link UsefulnessScope}'s shape with `now`
+ * OPTIONAL (the resolve read path does not bookkeep a clock).
+ */
+export interface LearningScope {
+    /** Tenant partition (isolation boundary). */
+    tenantId: string;
+    /** Agent partition (isolation boundary). */
+    agentId: string;
+    /**
+     * Optional injected epoch ms. NEVER `Date.now()` — when a write path needs a
+     * clock the caller supplies it from an injected clock so the path stays
+     * deterministic/testable. Absent on the read (`resolve`) path.
+     */
+    now?: number;
+}
+/**
+ * A single raw outcome observation captured from one signal source for one
+ * trajectory. Idempotent at the row level on `(tenantId, agentId, trajectoryId,
+ * source, observedAt)`: re-observing the same tuple is a no-op (the design's
+ * UNIQUE backstop). Counts/ids/closed-enums only — NO message bodies or
+ * model-asserted trust ever enter this layer (content-free, like the `memory:*`
+ * bus events). `usedSkillIds` is an EMPTY sink in P0 (populated Phase 201).
+ */
+export interface OutcomeObservation {
+    /** Tenant partition (isolation boundary). */
+    tenantId: string;
+    /** Agent partition (isolation boundary). */
+    agentId: string;
+    /** Conversation/session identity the trajectory belongs to. */
+    sessionId: string;
+    /** The trajectory identity (the stable `traceId` the trajectory + `comis explain` key on). */
+    trajectoryId: string;
+    /** The observed outcome from THIS source (closed union). */
+    outcome: "success" | "failure" | "corrected" | "unknown";
+    /** Which signal produced this observation (closed union). */
+    source: "tool" | "pipeline" | "correction" | "judge" | "reaction" | "explicit";
+    /** Source-reported confidence in [0, 1]. For the judge this is reward-capped in CODE, never trusted. */
+    confidence: number;
+    /** Optional sender-trust tag (reaction/correction provenance); never raises trust. */
+    senderTrust?: string;
+    /** Opaque recalled-memory ids attributed to this trajectory — ids only, never bodies. */
+    recalledIds?: string[];
+    /** Opaque used-skill ids — EMPTY in P0 (the WS2 attribution that populates it lands Phase 201). */
+    usedSkillIds?: string[];
+    /** Injected epoch ms the observation was made (part of the idempotency tuple). */
+    observedAt: number;
+}
+/**
+ * The fused verdict for one trajectory: the single net outcome after
+ * precedence-first fusion (tool/pipeline > judge > reaction; max-confidence
+ * within a tier) across every persisted observation. A finished trajectory with
+ * no resolvable signal fuses to `outcome: "unknown"` and derives NO learning /
+ * NO reward (fail-closed, OUTCOME-05); coverage telemetry must NOT count
+ * `unknown` as resolved.
+ */
+export interface ResolvedOutcome {
+    /** The fused net outcome (closed union). */
+    outcome: "success" | "failure" | "corrected" | "unknown";
+    /** Confidence of the winning tier's contributing observation. */
+    confidence: number;
+    /** The sources that contributed to the verdict (closed-union members, deduped). */
+    sources: Array<"tool" | "pipeline" | "correction" | "judge" | "reaction" | "explicit">;
+    /** Opaque recalled-memory ids attributed to this trajectory — ids only. */
+    recalledIds: string[];
+    /** Opaque used-skill ids — EMPTY sink in P0 (populated Phase 201). */
+    usedSkillIds: string[];
+}
+/** Result of an age-based prune sweep over the ledger. */
+export interface OutcomePruneResult {
+    /** Rows deleted (older than the retention cutoff). */
+    changes: number;
+}
+export interface OutcomeSignalPort {
+    /**
+     * WRITE (idempotent). Persist one raw outcome observation, upserting the
+     * `(tenantId, agentId, trajectoryId, source, observedAt)` row via
+     * `ON CONFLICT … DO NOTHING` (the design's UNIQUE backstop) plus a
+     * deterministic-hash id so a replay upserts even if the row was deleted.
+     * Returns `ok(undefined)` on success; never throws.
+     */
+    observe(obs: OutcomeObservation): Promise<Result<void, Error>>;
+    /**
+     * READ. Fuse every persisted observation for `trajectoryId` (scoped to
+     * `(tenant, agent)`) into one {@link ResolvedOutcome}, precedence-first then
+     * by confidence. When no tier resolves, returns `ok({ outcome: "unknown", … })`
+     * and derives no learning (fail-closed, OUTCOME-05). Unresolved scope
+     * fails-closed with `err(...)` at the adapter — never a shared/global pool.
+     */
+    resolve(trajectoryId: string, scope: LearningScope): Promise<Result<ResolvedOutcome, Error>>;
+    /**
+     * Age-based housekeeping. Delete every observation older than
+     * `systemNowMs() - retentionDays * 86_400_000` (mirrors
+     * `observability-store.prune`). Mandatory anti-DoS on the append-only ledger
+     * (OUTCOME-07 / §V12); runs at daemon startup regardless of the per-agent
+     * enable flag. Synchronous (a single SQLite transaction).
+     */
+    prune(retentionDays: number): OutcomePruneResult;
+    /**
+     * READ. Enumerate the DISTINCT per-turn `(trajectoryId, sessionId)` pairs the
+     * ledger holds for this `(tenant, agent)` scope, most-recent-first (bounded).
+     *
+     * Exists so a consumer (skill synthesis, WS2) can discover the REAL per-turn
+     * trajectory identities the outcome signal is keyed on and `resolve()` each —
+     * instead of guessing an id from a session view. This closes the live-2026-06-18
+     * defect where the synthesis source emitted the `sessionKey` while outcomes are
+     * keyed by the per-turn `traceId`, so `resolve(sessionKey)` always fused to
+     * `unknown` and NO skill could ever be selected on the single-agent path.
+     *
+     * OPTIONAL: only the sqlite adapter implements it; a consumer MUST fail-closed
+     * (treat absent / `err` as "no source trajectories") rather than fall back to a
+     * non-resolvable identity. Scoped + fail-closed on an unresolved scope, exactly
+     * like {@link resolve}.
+     */
+    listTrajectoryIds?(scope: LearningScope): Promise<Result<Array<{
+        trajectoryId: string;
+        sessionId: string;
+    }>, Error>>;
+}

package/node_modules/@comis/core/dist/ports/outcome-signal-port.js

@@ -0,0 +1 @@
+export {};

package/node_modules/@comis/core/dist/ports/output-guard.d.ts

@@ -19,4 +19,12 @@ export interface OutputGuardPort {
     scan(response: string, context?: {
         canaryToken?: string;
     }): Result<OutputGuardResult, Error>;
+    /**
+     * Register a runtime secret (e.g. a minted lease bearer) so subsequent scans
+     * redact it to `[REDACTED:known_secret]` — ENDPOINT-03 (Phase 211). The
+     * KNOWN_SECRET_MIN_LENGTH floor + longest-first ordering still apply: a value
+     * shorter than the floor (or empty/whitespace) is ignored, and a value already
+     * registered is deduplicated.
+     */
+    registerSecret(value: string): void;
 }

package/node_modules/@comis/core/dist/ports/outward-send-ledger.d.ts

@@ -0,0 +1,128 @@
+/**
+ * OutwardSendLedgerPort — the three-state outward-send ledger (Phase 216,
+ * ONCE-01..ONCE-04). It makes an irreversible outward send (a chat-platform
+ * message) exactly-once by keying every attempt on the `(rootRunId, stepIndex)`
+ * idempotency pair allocated by `DurableRunPort.allocateOutwardStep` (HIGH-1).
+ *
+ * The lifecycle is a CLOSED five-state union (AGENTS §2.8): `send_attempt_started`
+ * → `unknown_after_send` → (`committed` | `failed`), with `unresolved` for the
+ * honest "the reconcile could not tell" terminal. An out-of-band state is
+ * unrepresentable, so recovery (Wave 3) can never mis-route a row to "replay"
+ * (T-216-02). The store's Zod row schema (Plan 02) enforces the same union at
+ * read.
+ *
+ * SECURITY (T-216-03): the record carries `contentDigest` (a sha256 set by the
+ * caller), NEVER the message body — there is deliberately no `body`/`text` field
+ * on {@link OutwardSendRecord}, so the ledger is content-free by interface design.
+ *
+ * @module
+ */
+import type { Result } from "@comis/shared";
+/**
+ * The closed outward-send lifecycle. Recovery (Wave 3) branches on this exact
+ * five-member set:
+ *   - `send_attempt_started` — `begin` written BEFORE the platform call (ONCE-01).
+ *   - `unknown_after_send`   — written right BEFORE the platform call returns, so a
+ *                              crash mid-send leaves a row the recovery scan finds.
+ *   - `committed`            — the platform confirmed; `platformMessageId` is set.
+ *   - `failed`              — a permanent failure (ONCE-04); will not be replayed.
+ *   - `unresolved`         — the reconcile could not determine sent/not-sent; the
+ *                              row is parked + escalated rather than blindly replayed.
+ */
+export type OutwardSendState = "send_attempt_started" | "unknown_after_send" | "committed" | "failed" | "unresolved";
+/**
+ * The verdict a reconcile produces for an `unknown_after_send` row (ONCE-03).
+ * `unresolved` is a first-class designed outcome (the channel cannot tell), NOT
+ * a failure — a silent default-to-`sent` would be a double-send dressed as a
+ * reconcile (Pitfall 2).
+ */
+export type ReconcileOutcome = "sent" | "not_sent" | "unresolved";
+/**
+ * A single outward-send ledger row. Content-free (T-216-03): `contentDigest`
+ * only, never the body. `(rootRunId, stepIndex)` is the UNIQUE idempotency key.
+ */
+export interface OutwardSendRecord {
+    /** The ledger row id. */
+    readonly id: string;
+    /** The owning run — half of the idempotency key. */
+    readonly rootRunId: string;
+    /** The outward-send sequence number from `allocateOutwardStep` — the other half. */
+    readonly stepIndex: number;
+    /** The agent that issued the send. */
+    readonly agentId: string;
+    /** The channel type (e.g. "telegram"). */
+    readonly channelType: string;
+    /** The channel/chat/room identifier. */
+    readonly channelId: string;
+    /** The closed lifecycle state. */
+    readonly state: OutwardSendState;
+    /** The platform-assigned message id, present once `state === "committed"`. */
+    readonly platformMessageId?: string;
+    /** sha256 of the message content — NEVER the body itself (T-216-03). */
+    readonly contentDigest: string;
+    /** The reconcile verdict, present once a reconcile has resolved the row. */
+    readonly reconcileOutcome?: ReconcileOutcome;
+    /** How many send attempts this row has accrued. */
+    readonly attemptCount: number;
+    /** The last error description (errorKind / hint), present on a failed attempt. */
+    readonly lastError?: string;
+}
+/** The caller-supplied fields for `begin` — the store assigns id/state/attemptCount. */
+export interface OutwardSendBeginInput {
+    readonly rootRunId: string;
+    readonly stepIndex: number;
+    readonly agentId: string;
+    readonly channelType: string;
+    readonly channelId: string;
+    /** sha256 of the content — content-free key, never the body (T-216-03). */
+    readonly contentDigest: string;
+}
+/**
+ * The three-state outward-send ledger. Every method is `Result`-returning and
+ * never throws. The SQLite adapter (Plan 02) enforces the UNIQUE
+ * `(rootRunId, stepIndex)` constraint that makes a duplicate `begin` a no-op the
+ * caller treats as "already in flight".
+ */
+export interface OutwardSendLedgerPort {
+    /**
+     * ONCE-02 — the dedup read. Returns the existing row for this idempotency key,
+     * or `ok(undefined)` when no send has been attempted at this `(rootRunId,
+     * stepIndex)` yet. The send path consults this before issuing the platform call.
+     */
+    lookup(rootRunId: string, stepIndex: number): Promise<Result<OutwardSendRecord | undefined, Error>>;
+    /**
+     * ONCE-01 — write `state = send_attempt_started` for a new idempotency key. The
+     * UNIQUE `(rootRunId, stepIndex)` makes a duplicate `begin` an error the caller
+     * treats as "already in flight" (another attempt owns this send), so two
+     * concurrent attempts never both proceed to the platform.
+     */
+    begin(input: OutwardSendBeginInput): Promise<Result<void, Error>>;
+    /**
+     * Transition to `unknown_after_send` — written BEFORE the platform call returns,
+     * so a crash mid-send leaves a durable row the `listUnreconciled` scan finds and
+     * a reconcile can resolve (instead of a lost send or a blind replay).
+     */
+    markUnknown(rootRunId: string, stepIndex: number): Promise<Result<void, Error>>;
+    /**
+     * Transition to `committed` and record the `platformMessageId` — the platform
+     * confirmed the send. A committed row is the terminal success and is never replayed.
+     */
+    commit(rootRunId: string, stepIndex: number, platformMessageId: string): Promise<Result<void, Error>>;
+    /**
+     * ONCE-04 — transition to `failed` (a permanent failure) and record `errorKind`.
+     * A failed row is terminal and is not replayed.
+     */
+    markFailed(rootRunId: string, stepIndex: number, errorKind: string): Promise<Result<void, Error>>;
+    /**
+     * ONCE-03 — record the reconcile verdict (`sent` | `not_sent` | `unresolved`)
+     * for an `unknown_after_send` row. `unresolved` parks the row for escalation
+     * rather than replaying it.
+     */
+    resolveReconcile(rootRunId: string, stepIndex: number, outcome: ReconcileOutcome): Promise<Result<void, Error>>;
+    /**
+     * ONCE-03 — the recovery scan: every row whose state is still in flight
+     * (`unknown_after_send` or `send_attempt_started`). The recovery loop reconciles
+     * each against its channel's `reconcileSend?` and resolves it.
+     */
+    listUnreconciled(): Promise<Result<OutwardSendRecord[], Error>>;
+}

package/node_modules/@comis/core/dist/ports/outward-send-ledger.js

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * OutwardSendLedgerPort — the three-state outward-send ledger (Phase 216,
+ * ONCE-01..ONCE-04). It makes an irreversible outward send (a chat-platform
+ * message) exactly-once by keying every attempt on the `(rootRunId, stepIndex)`
+ * idempotency pair allocated by `DurableRunPort.allocateOutwardStep` (HIGH-1).
+ *
+ * The lifecycle is a CLOSED five-state union (AGENTS §2.8): `send_attempt_started`
+ * → `unknown_after_send` → (`committed` | `failed`), with `unresolved` for the
+ * honest "the reconcile could not tell" terminal. An out-of-band state is
+ * unrepresentable, so recovery (Wave 3) can never mis-route a row to "replay"
+ * (T-216-02). The store's Zod row schema (Plan 02) enforces the same union at
+ * read.
+ *
+ * SECURITY (T-216-03): the record carries `contentDigest` (a sha256 set by the
+ * caller), NEVER the message body — there is deliberately no `body`/`text` field
+ * on {@link OutwardSendRecord}, so the ledger is content-free by interface design.
+ *
+ * @module
+ */
+export {};

package/node_modules/@comis/core/dist/ports/plugin.d.ts

@@ -1,6 +1,5 @@
 import type { Result } from "@comis/shared";
 import type { HookName, HookHandlerMap } from "./hook-types.js";
-import type { z } from "zod";
 /**
  * PluginPort: The hexagonal architecture boundary for plugin extensions.
  *
@@ -36,24 +35,13 @@ export interface PluginPort {
      */
     deactivate?(): Promise<Result<void, Error>>;
 }
-/** Definition for a tool registered by a plugin */
-export interface PluginToolDefinition {
-    readonly name: string;
-    readonly description: string;
-    readonly parameters: Record<string, unknown>;
-    readonly execute: (params: Record<string, unknown>) => Promise<unknown>;
-}
-/** Definition for an HTTP route registered by a plugin */
-export interface PluginHttpRoute {
-    readonly method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
-    readonly path: string;
-    readonly handler: (req: unknown) => Promise<unknown>;
-}
 /**
  * API exposed to plugins during registration.
  *
- * Provides a type-safe way for plugins to register hook handlers,
- * tools, HTTP routes, and config schemas with optional priority ordering.
+ * Provides a type-safe way for plugins to register hook handlers with
+ * optional priority ordering. `registerHook` is the only surviving
+ * registration entrypoint — tool / HTTP route / config-schema registration
+ * surfaces were removed as they had zero in-tree callers.
  */
 export interface PluginRegistryApi {
     /**
@@ -66,12 +54,6 @@ export interface PluginRegistryApi {
     registerHook<K extends HookName>(hookName: K, handler: HookHandlerMap[K], options?: {
         priority?: number;
     }): void;
-    /** Register a tool that agents can invoke */
-    registerTool(tool: PluginToolDefinition): void;
-    /** Register an HTTP route on the gateway */
-    registerHttpRoute(route: PluginHttpRoute): void;
-    /** Register a config schema section for plugin-specific configuration */
-    registerConfigSchema(section: string, schema: z.ZodType): void;
 }
 /**
  * Internal representation of a registered hook handler.