comisai 1.0.44 → 1.0.46

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

@@ -2,12 +2,6 @@
  * ContextStorePort: hexagonal architecture boundary for the LCD (Lossless
  * Context DAG) message store.
  *
- * This is the NEW LCD lossless-store port introduced in v2.12 (Phase 127).
- * It reuses the `ContextStorePort` identifier that was DELETED in Phase 126
- * (the old DAG context-store port + its `Ctx*Row` DTOs), but it is a fresh,
- * unrelated interface — same name per CONTEXT.md decision Q2, NOT a revival
- * of the old contract. Do not resurrect the deleted `ctx_*` types.
- *
  * Type-only, NO zod (core ports are zero-runtime-zod by rule). Row DTOs live
  * in core/src/ports/context-store-types.ts.
  *
@@ -22,34 +16,34 @@ import type { AppendCondensedSummaryInput, AppendMessageInput, AppendProvenanceI
  * for the LCD engine.
  *
  * All operations are synchronous (better-sqlite3 is synchronous), matching
- * the SessionStorePort precedent. The 127 surface was intentionally minimal —
- * write + read only. Phase 129 adds the sanctioned summary + context_items
- * extension (the depth-0 LEAF half; condensation is Phase 130).
+ * the SessionStorePort precedent. The surface is intentionally minimal:
+ * the write + read core plus the sanctioned summary + context_items
+ * extension (depth-0 LEAF summaries and their condensation).
  */
 export interface ContextStorePort {
     /**
-     * Write path (F1): persist one message + its structured parts atomically.
+     * Write path: persist one message + its structured parts atomically.
      * `tokenCount` arrives pre-computed on the input (the store NEVER computes
      * tokens — the caller supplies it agent-side via `estimateMessageTokens`).
      */
     append(input: AppendMessageInput): void;
     /**
-     * Read path (F2): reconstruct all messages for the `scope`, ordered by seq.
+     * Read path: reconstruct all messages for the `scope`, ordered by seq.
      * Each `LcdMessage` carries its parts; provider-correct block emission is
      * pi-ai's job downstream — this port returns the faithful canonical rows.
-     * Scoped by (conversationId, agentId, tenantId) — full isolation (R4): two
-     * agents sharing one conversation_id never read each other's messages (WR-02).
+     * Scoped by (conversationId, agentId, tenantId) — full isolation: two
+     * agents sharing one conversation_id never read each other's messages.
      */
     getMessages(scope: ContextStoreScope): LcdMessage[];
     /**
-     * Compaction write path (C3): persist one leaf summary, link it to the
+     * Compaction write path: persist one leaf summary, link it to the
      * covered messages (FK RESTRICT — losslessness), and range-replace the
      * covered [startOrdinal, endOrdinal] message-refs in context_items with
      * one summary-ref — ALL in one transaction. Returns the new summaryId.
      */
     appendLeafSummary(input: AppendSummaryInput): string;
     /**
-     * Compaction write path (C2): persist one CONDENSED (depth>0) summary,
+     * Compaction write path: persist one CONDENSED (depth>0) summary,
      * link it to its CHILD SUMMARIES via lcd_summary_parents (FK RESTRICT on
      * the child — a condensed child is never deleted, losslessness), and
      * range-replace the covered [startOrdinal, endOrdinal] SUMMARY-refs in
@@ -60,8 +54,9 @@ export interface ContextStorePort {
     /**
      * Read path: the ordered model-facing context_items view (dense, gap-free
      * ordinals). Lazily seeded 1:1 from lcd_messages on first read for a
-     * conversation with no context_items rows (no migration — design §9).
-     * Scoped by (conversationId, agentId, tenantId) — full isolation (R4).
+     * conversation with no context_items rows (lazy seeding instead of a
+     * migration step).
+     * Scoped by (conversationId, agentId, tenantId) — full isolation.
      */
     getContextItems(scope: ContextStoreScope): LcdContextItem[];
     /**
@@ -70,12 +65,12 @@ export interface ContextStorePort {
      * `content` + pre-computed `tokenCount` when assembling the model-facing
      * context. Returned in insertion order; the assembler keys by id, not order.
      * `content` is the leaf plaintext and is NEVER logged (lossless store).
-     * Scoped by (conversationId, agentId, tenantId) — full isolation (R4).
+     * Scoped by (conversationId, agentId, tenantId) — full isolation.
      */
     getSummaries(scope: ContextStoreScope): LcdSummary[];
     /**
-     * EFF-01: Bounded read path — fetch only the message rows whose ids are in
-     * the provided set. Scoped by (conversationId, agentId, tenantId) — R4 isolation
+     * Bounded read path — fetch only the message rows whose ids are in
+     * the provided set. Scoped by (conversationId, agentId, tenantId) — isolation
      * identical to getMessages. Returns rows ordered by seq, same as getMessages.
      *
      * Returns [] when ids is empty (no DB query issued). Callers must collect
@@ -83,15 +78,15 @@ export interface ContextStorePort {
      */
     getMessagesByIds(scope: ContextStoreScope, ids: string[]): LcdMessage[];
     /**
-     * EFF-01: Bounded read path — fetch only the summary rows whose summaryIds are
-     * in the provided set. Scoped by (conversationId, agentId, tenantId) — R4 isolation
+     * Bounded read path — fetch only the summary rows whose summaryIds are
+     * in the provided set. Scoped by (conversationId, agentId, tenantId) — isolation
      * identical to getSummaries. Returns rows ordered by created_at, summary_id.
      *
      * Returns [] when ids is empty (no DB query issued).
      */
     getSummariesByIds(scope: ContextStoreScope, ids: string[]): LcdSummary[];
     /**
-     * EFF-01: the TOTAL count of persisted messages in the scope — a bounded
+     * The TOTAL count of persisted messages in the scope — a bounded
      * `COUNT(*)` that returns a single integer WITHOUT materializing any rows, so
      * it preserves the O(referenced-ids) read budget (no O(total-history) fetch).
      *
@@ -100,45 +95,45 @@ export interface ContextStorePort {
      * summarization (losslessness), so this total stays correct even after the
      * oldest message-refs collapse into summary-refs — unlike `getMessagesByIds`,
      * whose bounded result counts only the still-referenced subset. Scoped by
-     * (conversationId, agentId, tenantId) — full isolation (R4): a different agent
-     * sharing the conversation is never counted (WR-02). Returns 0 for an empty scope.
+     * (conversationId, agentId, tenantId) — full isolation: a different agent
+     * sharing the conversation is never counted. Returns 0 for an empty scope.
      */
     countMessages(scope: ContextStoreScope): number;
     /**
-     * E1 region walk: the immediate CHILD summaries of a condensed summary
+     * Region walk: the immediate CHILD summaries of a condensed summary
      * (the lcd_summary_parents condensed→child edge). Returns [] when the
      * summary has no children (a leaf) or does not exist. Scoped by
-     * (conversationId, agentId, tenantId) — full isolation (R4): a different
-     * agent sharing the conversation cannot reach this condensed edge (WR-02).
+     * (conversationId, agentId, tenantId) — full isolation: a different
+     * agent sharing the conversation cannot reach this condensed edge.
      */
     getSummaryChildren(scope: ContextStoreScope, parentSummaryId: string): LcdSummary[];
     /**
-     * E1 region walk: the message ids a LEAF summary covers
+     * Region walk: the message ids a LEAF summary covers
      * (the lcd_summary_messages leaf→message edge). Returns [] when the summary
      * covers no messages or does not exist. Scoped by (conversationId, agentId,
-     * tenantId) — full isolation (R4): a different agent cannot reach the covered
-     * ids of another agent's summary within the shared conversation (WR-02).
+     * tenantId) — full isolation: a different agent cannot reach the covered
+     * ids of another agent's summary within the shared conversation.
      */
     getSummaryMessages(scope: ContextStoreScope, summaryId: string): string[];
     /**
-     * E1 search: full-text search over THIS (conversation, agent)'s lossless
+     * Full-text search over THIS (conversation, agent)'s lossless
      * store — FTS5 MATCH when available, LIKE scan fallback otherwise. The `query`
      * MUST already be sanitized by the caller (sanitizeFts5Query lives in
-     * @comis/skills; @comis/memory cannot import it — PATTERNS gap #2). Scoped by
-     * (conversationId, agentId) — full isolation (R4): BOTH the FTS path AND the
-     * LIKE fallback filter agent_id so a different agent's hits never leak (WR-02,
-     * Pitfall 3). The conversation_id prefix carries the tenant boundary.
+     * @comis/skills; @comis/memory cannot import it). Scoped by
+     * (conversationId, agentId) — full isolation: BOTH the FTS path AND the
+     * LIKE fallback filter agent_id so a different agent's hits never leak.
+     * The conversation_id prefix carries the tenant boundary.
      *
-     * Returns an {@link LcdSearchResult} wrapper (OBS-01): `hits` is the
+     * Returns an {@link LcdSearchResult} wrapper: `hits` is the
      * FTS/trigram/scan result array; `lane` names the lane that served the query
      * ("word" word-FTS/LIKE, "tri" trigram twins, "scan" the bounded normalized
      * floor); `matchErrored` is true iff a MATCH threw and degraded to [] (an
      * errored zero-result is NOT a lane gap — signal purity); `scriptZeroHit` is the
      * dominant non-Latin {@link ScriptClass} when the search ran cleanly and
-     * returned zero hits (the §14.4 trigger generalized beyond CJK); `cjkZeroHit`
+     * returned zero hits (the zero-hit trigger, generalized beyond CJK); `cjkZeroHit`
      * stays as the derived `scriptZeroHit === "cjk"` boolean; `scanCapped` flags a
      * scan floor that hit its row cap. All diagnostics are content-free
-     * (enums/booleans, never the query text — I8); the caller's logging boundary
+     * (enums/booleans, never the query text); the caller's logging boundary
      * (skills/agent) emits the `script_zero_hit` event when `scriptZeroHit` is set.
      */
     searchLcd(scope: ContextStoreScope, query: string, opts: {
@@ -146,11 +141,11 @@ export interface ContextStorePort {
         scope?: "messages" | "summaries" | "both";
     }): LcdSearchResult;
     /**
-     * Per-conversation single-flight (R3, Plan 132-04): run `fn` on the queue
+     * Per-conversation single-flight: run `fn` on the queue
      * dedicated to `conversationId`. Serializes the live ingest write and the
-     * deferred (C4) compaction write so they cannot interleave on
+     * deferred compaction write so they cannot interleave on
      * (conversation_id, agent_id, tenant_id, seq) / the lcd_context_items ordinals
-     * — the integrity boundary the deferred second writer requires (Pitfall 2).
+     * — the integrity boundary the deferred second writer requires.
      * Operations on the same conversation are strictly one-at-a-time; operations
      * on different conversations run concurrently (the queue is per-conversation,
      * never a global lock). Accepts a synchronous OR async `fn` (the live ingest's
@@ -160,10 +155,10 @@ export interface ContextStorePort {
      */
     runOnConversation<T>(conversationId: string, fn: () => T | Promise<T>): Promise<T>;
     /**
-     * RR1 (Phase 164): Read the durable ingest cursor for this
+     * Read the durable ingest cursor for this
      * (conversation, agent, tenant) scope.
-     * Returns null when no row exists — new conversation or first run after the
-     * Phase 164 upgrade (the lcd_ingest_cursor table is added forward-only).
+     * Returns null when no row exists — a conversation that has never been
+     * ingested.
      * The caller interprets null as "no prior epoch: treat as epoch A with
      * ingestedLiveLen = 0" — the steady-state continue path.
      */
@@ -172,7 +167,7 @@ export interface ContextStorePort {
         ingestedLiveLen: number;
     } | null;
     /**
-     * RR1 (Phase 164): Atomically upsert the durable ingest cursor.
+     * Atomically upsert the durable ingest cursor.
      * MUST be called inside runOnConversation by the caller (lcd-store's
      * single-flight serializer ensures the cursor write and the message append
      * are serialized for the same conversation).
@@ -183,7 +178,7 @@ export interface ContextStorePort {
         ingestedLiveLen: number;
     }, updatedAt: number): void;
     /**
-     * RR4 (Phase 164): Delete ALL lcd_* rows for this (conversation, agent, tenant)
+     * Delete ALL lcd_* rows for this (conversation, agent, tenant)
      * scope in FK-safe dependency order:
      * lcd_summary_messages (RESTRICT FK) → lcd_summary_parents → lcd_context_items →
      * lcd_summaries → lcd_messages (CASCADE deletes lcd_message_parts) → lcd_ingest_cursor.
@@ -192,32 +187,31 @@ export interface ContextStorePort {
      * MUST be called inside runOnConversation so it serializes against live ingest.
      * Never throws; returns 0 on no-op (empty conversation).
      *
-     * T-164-01: the three-column scope filter (conversation_id, agent_id, tenant_id)
+     * The three-column scope filter (conversation_id, agent_id, tenant_id)
      * on every DELETE statement mirrors the lcd-store selectMsgs read isolation —
      * a cross-tenant or cross-agent wipe is impossible by construction.
      */
     deleteConversationLcd(scope: ContextStoreScope): number;
     /**
-     * Phase 172 (DIST-01): Write a provenance row linking a distilled episodic
+     * Write a provenance row linking a distilled episodic
      * memory to the LCD condensed summary it was distilled from.
      *
-     * Synchronous (better-sqlite3). R4-scoped via input.conversationId /
+     * Synchronous (better-sqlite3). Scoped via input.conversationId /
      * agentId / tenantId. No return value — the provenanceId is caller-supplied.
      *
-     * OPTIONAL: existing ContextStorePort implementations (e.g. test stubs) do
-     * not need to implement this until 172-03 adds the concrete SQL in lcd-store.ts.
+     * OPTIONAL: ContextStorePort implementations (e.g. test stubs) may omit it.
      * The distillation runner gates on `deps.lcdStore.appendProvenance != null`.
      */
     appendProvenance?(input: AppendProvenanceInput): void;
     /**
-     * Phase 172 (DIST-03): Mark an existing lcd_memory_provenance row as
+     * Mark an existing lcd_memory_provenance row as
      * superseded by a newer distilled memory (the pyramid rule).
      *
      * Sets `superseded_by = supersededByMemoryId` WHERE `summary_id = summaryId`
      * AND `tenant_id = tenantId` AND `agent_id = agentId` AND
      * `superseded_by IS NULL`. Synchronous. No-op when no matching row.
      *
-     * R4 (WR-01): the `tenantId`/`agentId` predicate is load-bearing — the UPDATE
+     * The `tenantId`/`agentId` predicate is load-bearing — the UPDATE
      * is on a multi-tenant table, so a summary_id collision under a different
      * scope must be a fail-closed no-op (never flip another scope's row).
      *
@@ -226,7 +220,7 @@ export interface ContextStorePort {
     markProvenanceSuperseded?(summaryId: string, supersededByMemoryId: string, tenantId: string, agentId: string): void;
 }
 /**
- * Phase 172 (DIST-03/recall): TYPE-ONLY read port for the lcd_memory_provenance
+ * TYPE-ONLY read port for the lcd_memory_provenance
  * table, consumed by the post-fusion provenance down-weighting pass in
  * createMemoryRecall (packages/agent/src/rag/memory-recall.ts).
  *
@@ -241,7 +235,7 @@ export interface ContextStorePort {
 export interface LcdProvenanceReadStore {
     /**
      * Return all provenance rows where summary_id = summaryId, scoped to
-     * (tenant, agent) for R4 isolation. Used by the post-fusion pass to
+     * (tenant, agent) for isolation. Used by the post-fusion pass to
      * identify same-conversation paired memories to down-weight.
      */
     getProvenanceForSummary(scope: ContextStoreScope, summaryId: string): Array<{
@@ -270,7 +264,7 @@ export interface LcdProvenanceReadStore {
 export interface ContextBrowsePort {
     /**
      * List the distinct LCD conversations owned by ONE agent within ONE tenant,
-     * most-recently-updated first, paginated. R4 (WR-02): filters by `agentId`
+     * most-recently-updated first, paginated. Filters by `agentId`
      * AND `tenantId`, so two agents that legitimately share one conversation_id
      * never see each other's conversations, and one tenant never sees another's.
      * Returns a page of metadata rows (IDs/counts/time-bounds only — NEVER any

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

@@ -3,12 +3,6 @@
  * ContextStorePort: hexagonal architecture boundary for the LCD (Lossless
  * Context DAG) message store.
  *
- * This is the NEW LCD lossless-store port introduced in v2.12 (Phase 127).
- * It reuses the `ContextStorePort` identifier that was DELETED in Phase 126
- * (the old DAG context-store port + its `Ctx*Row` DTOs), but it is a fresh,
- * unrelated interface — same name per CONTEXT.md decision Q2, NOT a revival
- * of the old contract. Do not resurrect the deleted `ctx_*` types.
- *
  * Type-only, NO zod (core ports are zero-runtime-zod by rule). Row DTOs live
  * in core/src/ports/context-store-types.ts.
  *

package/node_modules/@comis/core/dist/ports/delivery-mirror.d.ts

@@ -5,10 +5,8 @@
  * the agent's prompt on subsequent turns. This enables the agent to "see"
  * messages it sent to other channels/sessions, creating cross-session awareness.
  *
- * Session Mirroring.
- *
  * The createNoOpDeliveryMirror() factory lives at
- * ../delivery/no-op-delivery-mirror.ts; this file is now type-only.
+ * ../delivery/no-op-delivery-mirror.ts; this file is type-only.
  *
  * @module
  */

package/node_modules/@comis/core/dist/ports/delivery-mirror.js

@@ -6,10 +6,8 @@
  * the agent's prompt on subsequent turns. This enables the agent to "see"
  * messages it sent to other channels/sessions, creating cross-session awareness.
  *
- * Session Mirroring.
- *
  * The createNoOpDeliveryMirror() factory lives at
- * ../delivery/no-op-delivery-mirror.ts; this file is now type-only.
+ * ../delivery/no-op-delivery-mirror.ts; this file is type-only.
  *
  * @module
  */

package/node_modules/@comis/core/dist/ports/delivery-queue.d.ts

@@ -5,10 +5,8 @@
  * The queue uses at-least-once delivery semantics: messages are enqueued before
  * send, acknowledged on success, and retried on failure.
  *
- * Crash-Safe Delivery Queue.
- *
  * The createNoOpDeliveryQueue() factory lives at ../delivery/no-op-delivery-queue.ts;
- * this file is now type-only.
+ * this file is type-only.
  *
  * @module
  */
@@ -128,7 +126,7 @@ export interface DeliveryQueuePort {
     /**
      * Reset all rows with status='in_flight' to status='pending', clearing last_error.
      *
-     * Called once at daemon startup before the existing startup drain. Treats
+     * Called once at daemon startup before the startup drain. Treats
      * 'in_flight' as a process-local lease -- any in_flight row left over from a
      * prior daemon process is by definition stale and must be re-attempted.
      *

package/node_modules/@comis/core/dist/ports/delivery-queue.js

@@ -6,10 +6,8 @@
  * The queue uses at-least-once delivery semantics: messages are enqueued before
  * send, acknowledged on success, and retried on failure.
  *
- * Crash-Safe Delivery Queue.
- *
  * The createNoOpDeliveryQueue() factory lives at ../delivery/no-op-delivery-queue.ts;
- * this file is now type-only.
+ * this file is type-only.
  *
  * @module
  */

package/node_modules/@comis/core/dist/ports/durable-run.d.ts

@@ -1,12 +1,12 @@
 /**
- * DurableRunPort — the hexagonal boundary for the run-checkpoint store (Phase
- * 216, DUR-01/DUR-02/DUR-03/HB-01). A long-running agent run persists a
+ * DurableRunPort — the hexagonal boundary for the run-checkpoint store.
+ * A long-running agent run persists a
  * {@link DurableRunRecord} here so a daemon restart can find and resume it
  * (`listResumable`), keep it alive (`touchHeartbeat`), and refuse to re-mint a
  * revoked one (`invalidateForRevoke`).
  *
  * Every method is `Result`-returning and never throws — the same discipline as
- * {@link DeliveryQueuePort} and `VideoJobStore`. The SQLite adapter (Plan 02)
+ * {@link DeliveryQueuePort} and `VideoJobStore`. The SQLite adapter
  * implements it; reads degrade through the row mapper.
  *
  * @module
@@ -20,15 +20,15 @@ import type { DurableRunRecord } from "../domain/durable-run.js";
  */
 export interface DurableRunPort {
     /**
-     * DUR-01 — idempotent insert-or-update keyed on `rootRunId`. Writes the
+     * Idempotent insert-or-update keyed on `rootRunId`. Writes the
      * checkpoint fields; MUST NEVER touch the dedicated `outward_step` column
-     * (NEW-1 storage contract) — that counter is owned solely by
+     * — that counter is owned solely by
      * {@link DurableRunPort.allocateOutwardStep}, so a checkpoint between two
-     * outward sends cannot reset it and re-introduce HIGH-1.
+     * outward sends cannot reset it and cause a duplicate outward send.
      */
     upsertCheckpoint(record: DurableRunRecord): Promise<Result<void, Error>>;
     /**
-     * DUR-02 — the boot-resume scan: every record in status `running`. These are
+     * The boot-resume scan: every record in status `running`. These are
      * the runs a restarting daemon must resume (or orphan if un-resumable).
      */
     listResumable(): Promise<Result<DurableRunRecord[], Error>>;
@@ -46,20 +46,20 @@ export interface DurableRunPort {
     /** Flip a record to status `completed` — the run finished; resume skips it. */
     markCompleted(rootRunId: string): Promise<Result<void, Error>>;
     /**
-     * HB-01 — the keep-alive write: stamp `lastHeartbeatAt = atMs`. A run whose
+     * The keep-alive write: stamp `lastHeartbeatAt = atMs`. A run whose
      * heartbeat goes stale past the threshold is a crash candidate for the
      * orphan-sweep.
      */
     touchHeartbeat(rootRunId: string, atMs: number): Promise<Result<void, Error>>;
     /**
-     * DUR-03 — flip the record to status `revoked` so resume can NEVER re-mint it.
+     * Flip the record to status `revoked` so resume can NEVER re-mint it.
      * Called when the run's authority (lease/caps) is revoked out from under it; a
      * revoked checkpoint is terminal and is filtered out of `listResumable`.
      */
     invalidateForRevoke(rootRunId: string): Promise<Result<void, Error>>;
     /**
-     * HIGH-1 / ONCE-02 — atomically increment a monotonic per-`rootRunId` outward-
-     * send counter (the dedicated `outward_step` column, NEW-1) and return the NEW
+     * Atomically increment a monotonic per-`rootRunId` outward-
+     * send counter (the dedicated `outward_step` column) and return the NEW
      * index. The FIRST call returns 0, the second 1, etc. (the column seeds at the
      * -1 'never-sent' sentinel, so `outward_step + 1` yields 0 on the first call).
      *
@@ -72,11 +72,11 @@ export interface DurableRunPort {
      */
     allocateOutwardStep(rootRunId: string): Promise<Result<number, Error>>;
     /**
-     * FLEET-03 (Phase 220) — windowed status counts read DIRECTLY from
+     * Windowed status counts read DIRECTLY from
      * `durable_runs`. Crash-surviving: the row IS the durability, so this count
      * survives a hard crash that would lose an in-process lifecycle event. Counts
      * ONLY rows with `updated_at_ms >= sinceMs` (the fleet window), grouped by
-     * status; absent statuses default to 0. The `comis fleet` assembler (Plan 03)
+     * status; absent statuses default to 0. The `comis fleet` assembler
      * reads this for the orphaned/resumed/revoked/running counts alongside the
      * `health_signal` rows. Mirrors the obs store's `getRollingSpendUsd`
      * windowed-aggregate (`WHERE … >= ?`) precedent.

package/node_modules/@comis/core/dist/ports/durable-run.js

@@ -1,13 +1,13 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * DurableRunPort — the hexagonal boundary for the run-checkpoint store (Phase
- * 216, DUR-01/DUR-02/DUR-03/HB-01). A long-running agent run persists a
+ * DurableRunPort — the hexagonal boundary for the run-checkpoint store.
+ * A long-running agent run persists a
  * {@link DurableRunRecord} here so a daemon restart can find and resume it
  * (`listResumable`), keep it alive (`touchHeartbeat`), and refuse to re-mint a
  * revoked one (`invalidateForRevoke`).
  *
  * Every method is `Result`-returning and never throws — the same discipline as
- * {@link DeliveryQueuePort} and `VideoJobStore`. The SQLite adapter (Plan 02)
+ * {@link DeliveryQueuePort} and `VideoJobStore`. The SQLite adapter
  * implements it; reads degrade through the row mapper.
  *
  * @module

package/node_modules/@comis/core/dist/ports/egress-control.d.ts

@@ -1,14 +1,14 @@
 /**
  * EgressControlPort: the SEGREGATED hexagonal boundary for the terminal driver's
- * `network: listed-hosts` egress filter (§3.5). It materializes a
+ * `network: listed-hosts` egress filter. It materializes a
  * **no-secret host-allowlist CONNECT proxy** bound to the entry's `scope.hosts[]`
- * and returns a unix socket to bind-mount into the jail. A spike PROVED the
- * transport end-to-end on the VPS (allowlisted host -> 200, non-listed
+ * and returns a unix socket to bind-mount into the jail. The transport is
+ * proven end-to-end (allowlisted host -> 200, non-listed
  * -> 403, direct `--unshare-net` bypass -> rc=7, no route): a host-side allowlist
  * proxy on a unix socket, bridged into the jail by an in-jail loopback relay
  * exposed to the driven CLI as `HTTPS_PROXY=http://127.0.0.1:<port>`.
  *
- * This is DISTINCT from the credential broker (§3.9, an optional tier). The
+ * This is DISTINCT from the credential broker (an optional tier). The
  * broker injects an Authorization header to mint scoped credentials; this port
  * injects NOTHING into the stream — it is a pure CONNECT relay whose only job is
  * to gate the destination host against the operator allowlist. The two never

package/node_modules/@comis/core/dist/ports/egress-control.js

@@ -1,15 +1,15 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
  * EgressControlPort: the SEGREGATED hexagonal boundary for the terminal driver's
- * `network: listed-hosts` egress filter (§3.5). It materializes a
+ * `network: listed-hosts` egress filter. It materializes a
  * **no-secret host-allowlist CONNECT proxy** bound to the entry's `scope.hosts[]`
- * and returns a unix socket to bind-mount into the jail. A spike PROVED the
- * transport end-to-end on the VPS (allowlisted host -> 200, non-listed
+ * and returns a unix socket to bind-mount into the jail. The transport is
+ * proven end-to-end (allowlisted host -> 200, non-listed
  * -> 403, direct `--unshare-net` bypass -> rc=7, no route): a host-side allowlist
  * proxy on a unix socket, bridged into the jail by an in-jail loopback relay
  * exposed to the driven CLI as `HTTPS_PROXY=http://127.0.0.1:<port>`.
  *
- * This is DISTINCT from the credential broker (§3.9, an optional tier). The
+ * This is DISTINCT from the credential broker (an optional tier). The
  * broker injects an Authorization header to mint scoped credentials; this port
  * injects NOTHING into the stream — it is a pure CONNECT relay whose only job is
  * to gate the destination host against the operator allowlist. The two never

package/node_modules/@comis/core/dist/ports/execution-plan-port.d.ts

@@ -1,13 +1,13 @@
 /**
  * ExecutionPlanPort — read-only accessor for the Silent Execution Planner
- * (SEP) `ExecutionPlan` (spec §16.7 / §17.1).
+ * (SEP) `ExecutionPlan`.
  *
- * The milestone adds **no** `plan_state` tool — SEP is the canonical plan-state
- * source. The authoritative `ExecutionPlan` + `PlanStep` types live in
+ * There is deliberately **no** `plan_state` tool — SEP is the canonical
+ * plan-state source. The authoritative `ExecutionPlan` + `PlanStep` types live in
  * `@comis/agent` (`packages/agent/src/planner/types.ts`). This port re-declares
  * the **minimal read-only** shape in core so the gateway/ACP plan bridge can
- * render plan-state (`session/update { sessionUpdate: "plan" }`, §16.8) and the
- * chat-projection plan renderer (§8.3) can draw checkboxes WITHOUT the gateway
+ * render plan-state (`session/update { sessionUpdate: "plan" }`) and the
+ * chat-projection plan renderer can draw checkboxes WITHOUT the gateway
  * depending on `@comis/agent`. The implementation (agent/orchestrator) and the
  * consumer (gateway) are wired separately; this declares only the port
  * shape. Pure type-only file (no I/O, no logger).
@@ -25,7 +25,7 @@ export interface ReadonlyPlanStep {
     readonly status: "pending" | "in_progress" | "done" | "skipped";
     /**
      * Tool call IDs that contributed to completing this step. Optional — the
-     * projection MUST treat `undefined` as "no completions yet" (§16.7).
+     * projection MUST treat `undefined` as "no completions yet".
      */
     readonly completedBy?: readonly string[];
 }

package/node_modules/@comis/core/dist/ports/execution-plan-port.js

@@ -1,14 +1,14 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
  * ExecutionPlanPort — read-only accessor for the Silent Execution Planner
- * (SEP) `ExecutionPlan` (spec §16.7 / §17.1).
+ * (SEP) `ExecutionPlan`.
  *
- * The milestone adds **no** `plan_state` tool — SEP is the canonical plan-state
- * source. The authoritative `ExecutionPlan` + `PlanStep` types live in
+ * There is deliberately **no** `plan_state` tool — SEP is the canonical
+ * plan-state source. The authoritative `ExecutionPlan` + `PlanStep` types live in
  * `@comis/agent` (`packages/agent/src/planner/types.ts`). This port re-declares
  * the **minimal read-only** shape in core so the gateway/ACP plan bridge can
- * render plan-state (`session/update { sessionUpdate: "plan" }`, §16.8) and the
- * chat-projection plan renderer (§8.3) can draw checkboxes WITHOUT the gateway
+ * render plan-state (`session/update { sessionUpdate: "plan" }`) and the
+ * chat-projection plan renderer can draw checkboxes WITHOUT the gateway
  * depending on `@comis/agent`. The implementation (agent/orchestrator) and the
  * consumer (gateway) are wired separately; this declares only the port
  * shape. Pure type-only file (no I/O, no logger).

package/node_modules/@comis/core/dist/ports/file-lock.d.ts

@@ -1,9 +1,9 @@
 /**
  * FileLockPort: hexagonal architecture boundary for file-based mutual exclusion.
  *
- * The port is broad enough for THREE current consumers:
- *   - scheduler execution locks (cron-shaped, fixed timing — withExecutionLock today)
- *   - agent session write locks (30s stale, 3 retries, 500ms min timeout — LockedSessionStoreOptions today)
+ * The port is broad enough for THREE consumers:
+ *   - scheduler execution locks (cron-shaped, fixed timing — withExecutionLock)
+ *   - agent session write locks (30s stale, 3 retries, 500ms min timeout — LockedSessionStoreOptions)
  *   - agent OAuth credential/token locks (cross-process stale-lock recovery)
  *
  * Implementation: scheduler ships the canonical `createFileLock(): FileLockPort` factory
@@ -27,9 +27,9 @@ export interface LockOptions {
     /**
      * Lock-acquisition retry budget (default 3). Accepts either a bare number
      * (mapped to proper-lockfile { retries: N }) or the full proper-lockfile retry
-     * config object so callers like agent oauth-token-manager — which today passes
-     * { retries: 5, minTimeout: 50, maxTimeout: 1_000, factor: 2 } — can carry their
-     * existing tuning forward without semantic regression.
+     * config object so callers like the agent oauth-token-manager — which passes
+     * { retries: 5, minTimeout: 50, maxTimeout: 1_000, factor: 2 } — can express
+     * their full retry tuning.
      */
     readonly retries?: number | {
         retries: number;
@@ -42,10 +42,9 @@ export interface LockOptions {
     /**
      * Mtime update interval in ms for liveness proof (default 30_000).
      * Forwarded to proper-lockfile's `update` option. Zero or undefined disables
-     * the liveness ping; consumers like agent OAuth refresh use 5_000 to keep
-     * stale-detection in scheduler exec-lock's neighborhood without flapping.
-     * Lets agent's existing { staleMs: 30_000, updateMs: 5_000 } shape survive
-     * the retarget from withExecutionLock to createFileLock().withLock.
+     * the liveness ping; consumers like agent OAuth refresh pass
+     * { staleMs: 30_000, updateMs: 5_000 } to keep stale-detection in scheduler
+     * exec-lock's neighborhood without flapping.
      */
     readonly updateMs?: number;
 }
@@ -65,7 +64,7 @@ export interface FileLockPort {
     acquire(lockPath: string, opts?: LockOptions): Promise<Result<() => Promise<void>, LockError>>;
     /**
      * Release the lock at lockPath. Idempotent: double-release returns ok(undefined)
-     * (does not throw) — matches the existing finally{} swallow at session-write-lock.ts:127-131.
+     * (does not throw) — matches the finally{} swallow at session-write-lock.ts:127-131.
      */
     release(lockPath: string): Promise<Result<void, LockError>>;
     /**

package/node_modules/@comis/core/dist/ports/hook-types.d.ts

@@ -9,9 +9,9 @@ import type { SessionKey } from "../domain/session-key.js";
  * - Session: session_start, session_end
  * - Gateway: gateway_start, gateway_stop
  *
- * Tool / agent_end hook lanes (before_tool_call, after_tool_call,
- * tool_result_persist, agent_end) were removed — zero in-tree production
- * registrations.
+ * There are deliberately no tool / agent_end hook lanes (before_tool_call,
+ * after_tool_call, tool_result_persist, agent_end) — they would have zero
+ * in-tree production registrations.
  */
 export type HookName = "before_agent_start" | "before_compaction" | "after_compaction" | "before_delivery" | "after_delivery" | "session_start" | "session_end" | "gateway_start" | "gateway_stop";
 /** Hooks that return a result object to modify behavior (run sequentially). */

package/node_modules/@comis/core/dist/ports/index.js

@@ -1,9 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 // Port interfaces - Hexagonal architecture boundaries
-// Runtime values that previously lived alongside the type-only port
-// declarations were moved out of core/src/ports/. The curated re-exports at
-// ../exports/ports.ts retarget consumers to the new homes; this file
-// re-exports types only.
+// This barrel re-exports types only — no runtime values live in
+// core/src/ports/. The curated re-exports at ../exports/ports.ts point
+// consumers at the modules that own the runtime values.
 export {};
 // NOTE: the test-only stub factory in `__test-helpers/` is intentionally NOT
 // re-exported here. It must NEVER appear on this barrel (the architecture-grep