comisai 1.0.45 → 1.0.46

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

@@ -0,0 +1,41 @@
+/**
+ * MsTeamsConversationStorePort — the persisted map from a conversation id to the
+ * {@link ConversationReference} routing tuple a proactive send needs. A reply rides
+ * the inbound activity's own `serviceUrl`/tenant; a PROACTIVE send (cron,
+ * heartbeat, an unsolicited notice) has no inbound activity, so it recovers
+ * `{serviceUrl, tenantId, threadId}` from this store. The reference is captured
+ * (upserted) on EVERY inbound activity so the freshest routing tuple is stored.
+ *
+ * The domain record {@link ConversationReference}, its `z.strictObject` schema, and
+ * its parser live in `../domain/msteams-conversation-reference.ts` (ports are
+ * type-only); this file declares the store contract over that record.
+ *
+ * SECURITY: the reference carries ROUTING only — there is no credential field and
+ * no message-content field, so the store is content-free by interface design. A
+ * persisted `serviceUrl` remains untrusted at read: the send path re-validates it
+ * against the host allowlist before it is used.
+ *
+ * @module
+ */
+import type { Result } from "@comis/shared";
+import type { ConversationReference } from "../domain/msteams-conversation-reference.js";
+/**
+ * The conversation-reference store. Both methods are `Result`-returning and never
+ * throw (a corrupt row degrades to `err`). `capture` is an upsert refreshed on
+ * every inbound activity; `get` recovers the freshest reference for a proactive
+ * send, or `ok(undefined)` when the conversation was never captured.
+ */
+export interface MsTeamsConversationStorePort {
+    /**
+     * Persist (upsert) the reference keyed by the conversation id, refreshing the
+     * routing tuple + `updatedAt`. Called on every inbound activity. The
+     * implementation also prunes expired rows and caps table growth on capture.
+     */
+    capture(reference: ConversationReference): Promise<Result<void, Error>>;
+    /**
+     * Return the freshest stored reference for a conversation id, or
+     * `ok(undefined)` when none has been captured. The send path consults this when
+     * the caller supplies no inbound `serviceUrl` (the proactive case).
+     */
+    get(conversationId: string): Promise<Result<ConversationReference | undefined, Error>>;
+}

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

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * MsTeamsConversationStorePort — the persisted map from a conversation id to the
+ * {@link ConversationReference} routing tuple a proactive send needs. A reply rides
+ * the inbound activity's own `serviceUrl`/tenant; a PROACTIVE send (cron,
+ * heartbeat, an unsolicited notice) has no inbound activity, so it recovers
+ * `{serviceUrl, tenantId, threadId}` from this store. The reference is captured
+ * (upserted) on EVERY inbound activity so the freshest routing tuple is stored.
+ *
+ * The domain record {@link ConversationReference}, its `z.strictObject` schema, and
+ * its parser live in `../domain/msteams-conversation-reference.ts` (ports are
+ * type-only); this file declares the store contract over that record.
+ *
+ * SECURITY: the reference carries ROUTING only — there is no credential field and
+ * no message-content field, so the store is content-free by interface design. A
+ * persisted `serviceUrl` remains untrusted at read: the send path re-validates it
+ * against the host allowlist before it is used.
+ *
+ * @module
+ */
+export {};

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

@@ -1,18 +1,18 @@
 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
+ * OutcomeSignalPort: the SEGREGATED hexagonal boundary for the verified-learning
+ * outcome signal — 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
+ * proxy. 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
+ * This is a deliberately separate port — like {@link MemoryUsefulnessStore} it 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)
+ * and injects the adapter). Any agent-side consumer (skill 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).
@@ -28,7 +28,7 @@ import type { Result } from "@comis/shared";
  * 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`
+ * pool. Mirrors {@link UsefulnessScope}'s shape with `now`
  * OPTIONAL (the resolve read path does not bookkeep a clock).
  */
 export interface LearningScope {
@@ -46,10 +46,10 @@ export interface LearningScope {
 /**
  * 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
+ * source, observedAt)`: re-observing the same tuple is a no-op (a UNIQUE-
+ * constraint 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).
+ * bus events).
  */
 export interface OutcomeObservation {
     /** Tenant partition (isolation boundary). */
@@ -70,8 +70,15 @@ export interface OutcomeObservation {
     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). */
+    /** Opaque used-skill ids attributed to this trajectory — ids only, never bodies; absent when no skill use was attributed. */
     usedSkillIds?: string[];
+    /**
+     * Content-free procedure descriptor for this trajectory — the run's bounded tool-NAME
+     * set (the pre-flight footprint); NAMES only, never args/bodies/secrets. Absent when no
+     * cap-mapped tool call sites were declared. Persisted JSON-encoded to `procedure_descriptor`;
+     * NOT part of any key/index (the sha256 id tuple is untouched).
+     */
+    procedureDescriptor?: ReadonlyArray<string>;
     /** Injected epoch ms the observation was made (part of the idempotency tuple). */
     observedAt: number;
 }
@@ -80,7 +87,7 @@ export interface OutcomeObservation {
  * 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
+ * NO reward (fail-closed); coverage telemetry must NOT count
  * `unknown` as resolved.
  */
 export interface ResolvedOutcome {
@@ -92,7 +99,7 @@ export interface ResolvedOutcome {
     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). */
+    /** Opaque used-skill ids attributed to this trajectory — ids only; empty when no skill use was attributed. */
     usedSkillIds: string[];
 }
 /** Result of an age-based prune sweep over the ledger. */
@@ -104,7 +111,7 @@ 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
+     * `ON CONFLICT … DO NOTHING` (the UNIQUE-constraint backstop) plus a
      * deterministic-hash id so a replay upserts even if the row was deleted.
      * Returns `ok(undefined)` on success; never throws.
      */
@@ -113,15 +120,15 @@ export interface OutcomeSignalPort {
      * 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
+     * and derives no learning (fail-closed). 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
+     * `observability-store.prune`). Mandatory anti-DoS on the append-only ledger;
+     * runs at daemon startup regardless of the per-agent
      * enable flag. Synchronous (a single SQLite transaction).
      */
     prune(retentionDays: number): OutcomePruneResult;
@@ -129,20 +136,28 @@ export interface OutcomeSignalPort {
      * 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
+     * Exists so a consumer (skill synthesis) 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.
+     * instead of guessing an id from a session view. This matters because outcomes
+     * are keyed by the per-turn `traceId`, NOT the `sessionKey`: a consumer that
+     * calls `resolve(sessionKey)` always fuses 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}.
+     *
+     * Each entry also carries the turn's content-free `procedureDescriptor` when one was
+     * recorded — the ordered tool-NAME sequence + counts read back from the ledger (NAMES
+     * only, never args/bodies). Absent when the turn ran no cap-mapped tool call sites (or
+     * the stored value was corrupt — it degrades to absent, never throws). The reflection
+     * source attaches it onto each `ReflectionSourceTrajectory` so procedure information
+     * reaches the reflection engine (whose string transcript drops tool_use/tool_result blocks).
      */
     listTrajectoryIds?(scope: LearningScope): Promise<Result<Array<{
         trajectoryId: string;
         sessionId: string;
+        procedureDescriptor?: ReadonlyArray<string>;
     }>, Error>>;
 }

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

@@ -21,7 +21,7 @@ export interface OutputGuardPort {
     }): 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
+     * redact it to `[REDACTED:known_secret]`. 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.

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

@@ -1,17 +1,17 @@
 /**
- * OutwardSendLedgerPort — the three-state outward-send ledger (Phase 216,
- * ONCE-01..ONCE-04). It makes an irreversible outward send (a chat-platform
+ * OutwardSendLedgerPort — the outward-send ledger. 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).
+ * idempotency pair allocated by `DurableRunPort.allocateOutwardStep`.
  *
  * 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
+ * unrepresentable, so the recovery scan can never mis-route a row to "replay".
+ * The store's Zod row schema enforces the same union at
  * read.
  *
- * SECURITY (T-216-03): the record carries `contentDigest` (a sha256 set by the
+ * SECURITY: 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.
  *
@@ -19,26 +19,26 @@
  */
 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).
+ * The closed outward-send lifecycle. The crash-recovery scan branches on this
+ * exact five-member set:
+ *   - `send_attempt_started` — `begin` written BEFORE the platform call.
  *   - `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.
+ *   - `failed`              — a permanent failure; 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).
+ * The verdict a reconcile produces for an `unknown_after_send` row.
  * `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).
+ * reconcile.
  */
 export type ReconcileOutcome = "sent" | "not_sent" | "unresolved";
 /**
- * A single outward-send ledger row. Content-free (T-216-03): `contentDigest`
+ * A single outward-send ledger row. Content-free: `contentDigest`
  * only, never the body. `(rootRunId, stepIndex)` is the UNIQUE idempotency key.
  */
 export interface OutwardSendRecord {
@@ -58,7 +58,7 @@ export interface OutwardSendRecord {
     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). */
+    /** sha256 of the message content — NEVER the body itself. */
     readonly contentDigest: string;
     /** The reconcile verdict, present once a reconcile has resolved the row. */
     readonly reconcileOutcome?: ReconcileOutcome;
@@ -74,24 +74,24 @@ export interface OutwardSendBeginInput {
     readonly agentId: string;
     readonly channelType: string;
     readonly channelId: string;
-    /** sha256 of the content — content-free key, never the body (T-216-03). */
+    /** sha256 of the content — content-free key, never the body. */
     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
+ * never throws. The SQLite adapter 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,
+     * 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
+     * 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.
@@ -109,18 +109,18 @@ export interface OutwardSendLedgerPort {
      */
     commit(rootRunId: string, stepIndex: number, platformMessageId: string): Promise<Result<void, Error>>;
     /**
-     * ONCE-04 — transition to `failed` (a permanent failure) and record `errorKind`.
+     * 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`)
+     * 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
+     * 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.
      */

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

@@ -1,18 +1,18 @@
 // 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
+ * OutwardSendLedgerPort — the outward-send ledger. 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).
+ * idempotency pair allocated by `DurableRunPort.allocateOutwardStep`.
  *
  * 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
+ * unrepresentable, so the recovery scan can never mis-route a row to "replay".
+ * The store's Zod row schema enforces the same union at
  * read.
  *
- * SECURITY (T-216-03): the record carries `contentDigest` (a sha256 set by the
+ * SECURITY: 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.
  *

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

@@ -39,9 +39,9 @@ export interface PluginPort {
  * API exposed to plugins during registration.
  *
  * 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.
+ * optional priority ordering. `registerHook` is deliberately the only
+ * registration entrypoint — there are no tool / HTTP route / config-schema
+ * registration surfaces (they would have zero in-tree callers).
  */
 export interface PluginRegistryApi {
     /**

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

@@ -10,43 +10,43 @@ export interface ImageGenInput {
     size?: string;
     /** Whether to run safety checker on output (default: true) */
     safetyChecker?: boolean;
-    /** IN-01: optional reference image (edit/img2img) — base64 + mime, resolved by the handler. */
+    /** Optional reference image (edit/img2img) — base64 + mime, resolved by the handler. */
     referenceImage?: {
         data: string;
         mimeType: string;
     };
-    /** IN-02/CFG-02: optional model override (validated by the handler against the provider's list). */
+    /** Optional model override (validated by the handler against the provider's list). */
     model?: string;
 }
 /**
  * Output from image generation providers.
  *
- * `costUsd`/`model`/`provider` are OPTIONAL and ADDITIVE (OBS-01/03, Phase 186):
+ * `costUsd`/`model`/`provider` are OPTIONAL and ADDITIVE:
  * the pi-ai adapter (`toImageGenOutput`) maps them from `AssistantImages`
- * (`usage.cost.total`/`model`/`provider`), but the legacy fal/openai skills
+ * (`usage.cost.total`/`model`/`provider`), but the fal/openai skills
  * adapters that also implement `ImageGenerationPort` simply leave them unset —
- * a text-only/legacy return `{ buffer, mimeType }` is still valid.
+ * a minimal `{ buffer, mimeType }` return is still valid.
  */
 export interface ImageGenOutput {
     /** Raw image bytes */
     buffer: Buffer;
     /** MIME type of the image (e.g., "image/png") */
     mimeType: string;
-    /** OBS-03 — generation cost in USD (pi-ai `Usage.cost.total`); unset when the
-     *  provider reports no usage or a legacy adapter does not map it. */
+    /** Generation cost in USD (pi-ai `Usage.cost.total`); unset when the
+     *  provider reports no usage or the adapter does not map it. */
     costUsd?: number;
-    /** OBS-01/03 — the model id that produced the image (e.g. "gpt-image-1"). */
+    /** The model id that produced the image (e.g. "gpt-image-1"). */
     model?: string;
-    /** OBS-01/03 — the executing provider id (e.g. "openai", "google"). */
+    /** The executing provider id (e.g. "openai", "google"). */
     provider?: string;
 }
 /**
  * Image generation port — concrete hexagonal boundary for image-generation
  * adapters (OpenAI gpt-image-1, fal.ai, etc.).
  *
- * Inlined the previous `Provider<TInput, TOutput>` generic into this
- * concrete interface: the generic had a single consumer
- * (`ImageGenerationPort`), and the optional `estimateCost` field had zero
+ * Deliberately a concrete interface, not a `Provider<TInput, TOutput>`
+ * generic: a generic would have a single consumer
+ * (`ImageGenerationPort`), and an optional `estimateCost` field would have zero
  * production callers.
  */
 export interface ImageGenerationPort {
@@ -58,14 +58,14 @@ export interface ImageGenerationPort {
     execute(input: ImageGenInput): Promise<Result<ImageGenOutput, Error>>;
 }
 /**
- * Input for a video generation request (text-to-video baseline; the full
- * image-to-video variant-selection lands Phase 191). All fields beyond `prompt`
- * are optional and provider-validated.
+ * Input for a video generation request (text-to-video, plus image-to-video via
+ * `referenceImage`). All fields beyond `prompt` are optional and
+ * provider-validated.
  */
 export interface VideoGenInput {
     /** Text prompt describing the desired video */
     prompt: string;
-    /** Clip length in normalized seconds; the adapter encodes per backend (Phase 191) */
+    /** Clip length in normalized seconds; the adapter encodes per backend */
     durationSecs?: number;
     /** "16:9" | "9:16" | "1:1" (provider-validated) */
     aspectRatio?: string;
@@ -77,22 +77,22 @@ export interface VideoGenInput {
     negativePrompt?: string;
     /** Deterministic seed (provider-dependent) */
     seed?: number;
-    /** Phase 188 / 191 (IN-01): SSRF-resolved first-frame reference image for
-     *  image-to-video — base64 + mime, resolved by the handler. This singular field
-     *  is the PRIMARY and (Phase 191) the ONLY consumed image input: each adapter
-     *  variant-selects on its presence (FAL swaps to its /image-to-video endpoint;
-     *  Veo/Grok add the image on the same model). */
+    /** SSRF-resolved first-frame reference image for image-to-video — base64 +
+     *  mime, resolved by the handler. This singular field is the PRIMARY and the
+     *  ONLY consumed image input: each adapter variant-selects on its presence
+     *  (FAL swaps to its /image-to-video endpoint; Veo/Grok add the image on the
+     *  same model). */
     referenceImage?: {
         data: string;
         mimeType: string;
     };
-    /** Phase 191 (IN-01) — FORWARD-COMPAT SCAFFOLDING, NOT consumed this phase.
-     *  Additional reference images for i2v, each with a role. `referenceImage` (the
-     *  first-frame) stays the primary, sole-consumed singular input this phase;
-     *  multi-ref consumption (Veo lastFrame/referenceImages, Grok reference_images,
-     *  FAL first-last-frame) is a LOCKED fast-follow deferral. This optional field
-     *  is byte-compatible scaffolding so the future phase is additive-only — no
-     *  adapter reads it yet. Each `ref` is the SSRF-resolved { data, mimeType }. */
+    /** FORWARD-COMPAT SCAFFOLDING — NOT consumed yet. Additional reference
+     *  images for i2v, each with a role. `referenceImage` (the first-frame) stays
+     *  the primary, sole-consumed singular input; multi-ref consumption (Veo
+     *  lastFrame/referenceImages, Grok reference_images, FAL first-last-frame) is
+     *  a deliberate deferral. This optional field is byte-compatible scaffolding
+     *  so future consumption is additive-only — no adapter reads it yet. Each
+     *  `ref` is the SSRF-resolved { data, mimeType }. */
     referenceImages?: {
         ref: {
             data: string;
@@ -107,12 +107,12 @@ export interface VideoGenInput {
  * An in-flight job handle — the durable `submit()` result.
  *
  * `jobId` is the OPAQUE provider id (e.g. the FAL `request_id`): it is stable
- * across `poll()` calls and contains NO secret (VPORT-03). It is safe to log;
+ * across `poll()` calls and contains NO secret. It is safe to log;
  * the bearer token / `FAL_KEY` that authenticated the submit is never part of
- * it. The runtime no-secret assertion lands in Plan 03's adapter test.
+ * it. The runtime no-secret assertion lives in the adapter tests.
  */
 export interface VideoGenJob {
-    /** Opaque, stable-across-poll, secret-free provider request id (VPORT-03) */
+    /** Opaque, stable-across-poll, secret-free provider request id */
     jobId: string;
     /** The executing backend id (e.g. "fal") */
     provider: string;
@@ -121,9 +121,9 @@ export interface VideoGenJob {
 }
 /**
  * A `poll()` snapshot. `state` is the normalized lifecycle; `done` is the only
- * terminal-success state (`failed` short-circuits the poll loop in Plan 03).
+ * terminal-success state (`failed` short-circuits the poll loop).
  *
- * `errorKind`/`hint` are OPTIONAL and ADDITIVE (Phase 190 WR-01): when an adapter
+ * `errorKind`/`hint` are OPTIONAL and ADDITIVE: when an adapter
  * can classify a terminal `failed` state at poll time (a Veo `operation.error`, a
  * Grok `status:"failed"|"expired"`), it threads the SAME classified
  * `{ videoErrorKind, hint }` it produces on the in-turn `execute()` path onto the
@@ -139,17 +139,17 @@ export interface VideoGenJob {
 export interface VideoJobStatus {
     jobId: string;
     state: "pending" | "done" | "failed";
-    /** WR-01 — the classified domain error kind on a terminal `failed` snapshot. */
+    /** The classified domain error kind on a terminal `failed` snapshot. */
     errorKind?: VideoErrorKind;
-    /** WR-01 — the actionable, secret-free operator hint paired with `errorKind`. */
+    /** The actionable, secret-free operator hint paired with `errorKind`. */
     hint?: string;
 }
 /**
  * Output of a completed render.
  *
  * `durationSecs`/`costUsd`/`model`/`provider`/`sourceUrl` are OPTIONAL and
- * ADDITIVE (mirror `ImageGenOutput`): a legacy/minimal return is still a valid
- * `{ buffer, mimeType }`.
+ * ADDITIVE (mirror `ImageGenOutput`): a minimal `{ buffer, mimeType }` return
+ * is still valid.
  */
 export interface VideoGenOutput {
     /** Raw video bytes (downloaded from the expiring provider URL) */
@@ -164,7 +164,7 @@ export interface VideoGenOutput {
     model?: string;
     /** The executing provider id (e.g. "fal", "google") */
     provider?: string;
-    /** DEL-01 — the (expiring) provider URL retained for the buffer-vs-link
+    /** The (expiring) provider URL retained for the buffer-vs-link
      *  delivery choice; the buffer is the durable artifact. */
     sourceUrl?: string;
 }
@@ -175,28 +175,28 @@ export interface VideoGenOutput {
  * Unlike `ImageGenerationPort`, video is an async submit→poll→download
  * lifecycle: renders take 30 s–5 min and can outlive the originating turn. The
  * port therefore exposes the discrete `submit`/`poll`/`fetchResult` steps (so
- * Phase 189's background poller can drive the loop externally byte-for-byte)
+ * the daemon's background poller can drive the loop externally byte-for-byte)
  * AND an inline `execute()` convenience that runs the bounded poll-loop in one
- * call (the Phase 188 baseline; Plan 03 wires the loop).
+ * call.
  */
 export interface VideoGenerationPort {
     /** Unique provider identifier (e.g., "fal", "veo", "grok") */
     readonly id: string;
     /** Whether the provider is currently available (API key present, etc.) */
     isAvailable(): boolean;
-    /** Submit a render; capture the durable opaque jobId (VPORT-03). */
+    /** Submit a render; capture the durable opaque jobId. */
     submit(input: VideoGenInput): Promise<Result<VideoGenJob, Error>>;
     /** Poll a submitted job's status (idempotent; jobId stable). */
     poll(job: VideoGenJob): Promise<Result<VideoJobStatus, Error>>;
     /** Fetch + download the finished result to a buffer. `opts` bounds the
-     *  download (WR-01): an optional abort signal (the operator deadline; threaded
+     *  download: an optional abort signal (the operator deadline; threaded
      *  by `execute`) and a byte cap (defaulted by the adapter). */
     fetchResult(job: VideoGenJob, opts?: {
         signal?: AbortSignal;
         maxBytes?: number;
     }): Promise<Result<VideoGenOutput, Error>>;
-    /** Inline convenience: submit + bounded poll-loop + fetchResult (Plan 03
-     *  wires the loop; a deadline overrun surfaces as `job_timeout`). */
+    /** Inline convenience: submit + bounded poll-loop + fetchResult (a deadline
+     *  overrun surfaces as `job_timeout`). */
     execute(input: VideoGenInput, opts: {
         timeoutMs: number;
         pollIntervalMs: number;

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

@@ -1,6 +1,6 @@
 /**
- * Reflection delta-op TYPES — the v2.31 Reflection engine's byte-stable
- * doc-refresh vocabulary (REFLECT-04). A Mental Model doc's `structuredBody` is a
+ * Reflection delta-op TYPES — the Reflection engine's byte-stable
+ * doc-refresh vocabulary. A Mental Model doc's `structuredBody` is a
  * section-list AST (`{ sections: { id, heading, body }[] }`); a reflect refresh of
  * an EXISTING doc emits a list of typed {@link DeltaOp}s (add / replace / remove a
  * section) rather than rewriting the whole body.
@@ -14,10 +14,10 @@
  *
  * The store widens `MentalModel`/`AdmitMentalModelInput` with
  * `structuredBody?: StructuredBody` (importing the type from HERE); the agent
- * reflection job (Plan 04) parses the LLM's delta-ops into {@link DeltaOp}s,
+ * reflection job parses the LLM's delta-ops into {@link DeltaOp}s,
  * applies them against the prior doc's AST via `applyDeltaOps`, and renders the
  * result for the `body` column. An ABSENT prior AST ⇒ the job treats the topic as
- * a NEW doc (synthesize fresh — Assumption A6).
+ * a NEW doc (synthesize fresh).
  *
  * @module
  */
@@ -47,8 +47,8 @@ export interface StructuredBody {
      * The corroboration cluster's COMMON-CORE opening-request tokens (the shared procedure,
      * per-instance specifics dropped — `commonCoreTokens`). Stored so reuse attribution
      * (`topicMatchedSkillNames`) can credit a SURFACED skill on a turn that instantiates its
-     * procedure WITHOUT the model having to explicitly `read` the SKILL.md. Optional — legacy /
-     * seeded docs omit it (those never auto-credit, only the explicit-read path). NOT rendered
+     * procedure WITHOUT the model having to explicitly `read` the SKILL.md. Optional — docs
+     * stored without it (e.g. seeded docs) never auto-credit, only the explicit-read path. NOT rendered
      * into the `body` markdown (`renderStructuredBody` ignores it).
      */
     topicTokens?: string[];

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

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Reflection delta-op TYPES — the v2.31 Reflection engine's byte-stable
- * doc-refresh vocabulary (REFLECT-04). A Mental Model doc's `structuredBody` is a
+ * Reflection delta-op TYPES — the Reflection engine's byte-stable
+ * doc-refresh vocabulary. A Mental Model doc's `structuredBody` is a
  * section-list AST (`{ sections: { id, heading, body }[] }`); a reflect refresh of
  * an EXISTING doc emits a list of typed {@link DeltaOp}s (add / replace / remove a
  * section) rather than rewriting the whole body.
@@ -15,10 +15,10 @@
  *
  * The store widens `MentalModel`/`AdmitMentalModelInput` with
  * `structuredBody?: StructuredBody` (importing the type from HERE); the agent
- * reflection job (Plan 04) parses the LLM's delta-ops into {@link DeltaOp}s,
+ * reflection job parses the LLM's delta-ops into {@link DeltaOp}s,
  * applies them against the prior doc's AST via `applyDeltaOps`, and renders the
  * result for the `body` column. An ABSENT prior AST ⇒ the job treats the topic as
- * a NEW doc (synthesize fresh — Assumption A6).
+ * a NEW doc (synthesize fresh).
  *
  * @module
  */