comisai 1.0.44 → 1.0.46

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

@@ -2,21 +2,20 @@ import type { Result } from "@comis/shared";
 import type { LearningScope } from "./outcome-signal-port.js";
 import type { StructuredBody } from "./reflection-port.js";
 /**
- * MentalModelStorePort: the SEGREGATED hexagonal boundary for the v2.31 Mental
- * Model doc store (generalized from the v2.26 Verified Learning WS2 / SKILL-01
- * procedural store) — the durable `mental_models` table of admitted advisory
+ * MentalModelStorePort: the SEGREGATED hexagonal boundary for the Mental
+ * Model doc store — the durable `mental_models` table of admitted advisory
  * docs, each at `trust=learned` (a learned doc can NEVER be `system`). A row is
  * a `kind ∈ {skill, profile, topic}` doc; it admits a validated candidate
  * (`admit`), reads by name / lists (`get` / `list(scope, kind?)`), and runs the
  * lifecycle transitions a proof count / failure drives
  * (`promote` / `demote` / `evict`).
  *
- * This is a NEW port — like {@link OutcomeSignalPort} it deliberately does NOT
+ * This is a SEPARATE port — like {@link OutcomeSignalPort} it deliberately does NOT
  * widen the security-reviewed `MemoryPort`. The sole ADAPTER lives in
  * @comis/memory (it owns the `db` handle and runs all SQL); the store is invoked
  * DAEMON-SIDE (the daemon injects the adapter into the synthesis job). Any
  * agent-side consumer imports this port TYPE only — it cannot import
- * @comis/memory (the agent↛memory build cut, the structural SEC-01 boundary).
+ * @comis/memory (the agent↛memory build cut, a structural security boundary).
  *
  * This file is type-only (mirrors outcome-signal-port.ts): no zod, no
  * @comis/memory import. Every method threads the {@link LearningScope}
@@ -28,16 +27,16 @@ import type { StructuredBody } from "./reflection-port.js";
 /**
  * One admitted mental-model doc row (the type-only mirror of the `mental_models`
  * table). `trustLevel` is the LITERAL `"learned"` (never a widened `string`) —
- * the type-layer mirror of the DB `CHECK (trust_level IN ('learned'))` keystone
- * (SEC-01 T-201-04): a learned doc cannot be `system` even at the type layer.
+ * the type-layer mirror of the DB `CHECK (trust_level IN ('learned'))` keystone:
+ * a learned doc cannot be `system` even at the type layer.
  * `kind` tags the doc family; `mutating` drives the approval gate; `proofCount`
  * drives promote/demote; `sourceTrajIds` is the opaque provenance.
  *
- * NOTE: `structuredBody` (the v2.31 Reflection section-AST) IS now mirrored
- * (Phase 223 / REFLECT-04) — `get`/`list` surface it (undefined when the
+ * NOTE: `structuredBody` (the Reflection section-AST) IS mirrored —
+ * `get`/`list` surface it (undefined when the
  * `structured_body` column is NULL or holds garbage) so a reflect refresh can
- * delta-op against the prior doc. `history` (the FOLD-01 bi-temporal supersede
- * trail) IS now mirrored too (Phase 225) — `get`/`list` surface the appended
+ * delta-op against the prior doc. `history` (the bi-temporal supersede
+ * trail) IS mirrored too — `get`/`list` surface the appended
  * prior-body array (undefined when the `history` column is NULL or corrupt).
  */
 export interface MentalModel {
@@ -66,30 +65,42 @@ export interface MentalModel {
     /** Opaque source-trajectory ids the doc was distilled from — provenance (ids only). */
     sourceTrajIds: ReadonlyArray<string>;
     /**
-     * The Reflection section-AST (v2.31 / REFLECT-04) — the structured form a
+     * The Reflection section-AST — the structured form a
      * delta-op refresh reads and writes. `undefined` when the `structured_body`
      * column is NULL (a doc never reflected, or whose AST failed to parse). Render
      * to the `body` markdown via `renderStructuredBody`.
      */
     structuredBody?: StructuredBody | undefined;
     /**
-     * The FOLD-01 bi-temporal supersede trail (Phase 225) — the ordered (oldest-
+     * The bi-temporal supersede trail — the ordered (oldest-
      * first) array of prior bodies a {@link MentalModelStorePort.supersede} appended,
      * each `{ previousContent, changedAt }`. `undefined` when the `history` column is
      * NULL (a doc never superseded) or holds corrupt JSON (degrade-to-absent, never a
-     * throw). The shape mirrors `MemoryEntry["history"]` (the 224 FORGET-04 precedent).
+     * throw). The shape mirrors `MemoryEntry["history"]`.
      */
     history?: ReadonlyArray<{
         previousContent: string;
         changedAt: number;
     }> | undefined;
+    /**
+     * The deterministic tool-NAME footprint of a learned PROCEDURE doc (advisory) —
+     * the read-side mirror of the write-side `required_tools` bind. `undefined` for a
+     * user-intent skill / profile / topic (the `required_tools` column is NULL), or
+     * when the column holds corrupt JSON (degrade-to-absent, never a throw). It is
+     * the SURFACE DISCRIMINATOR: the learned-skill surface caps the procedure-doc
+     * subset (`requiredTools` populated) at a per-agent budget, leaving user-intent
+     * skills + topic docs on a separate, uncapped path. Content-free (tool NAMES
+     * only); advisory — the model re-authors the run under its already-permissioned
+     * tools, this is not an executable surface.
+     */
+    requiredTools?: ReadonlyArray<string>;
     /** Injected epoch ms the row was admitted. */
     createdAt: number;
 }
 /**
  * The write payload for {@link MentalModelStorePort.admit} — the admitted
  * subset of a validated candidate. `trustLevel` is intentionally NOT a field:
- * the adapter ALWAYS writes `"learned"` (the SEC-01 keystone is enforced at the
+ * the adapter ALWAYS writes `"learned"` (the trust keystone is enforced at the
  * store, never supplied by the caller). The id is derived (the deterministic
  * (tenant, agent, kind, topicKey, name) hash), so it is not supplied either.
  * `kind`/`topicKey` are OPTIONAL — omitted ⇒ the adapter applies `'skill'`/`''`,
@@ -103,7 +114,7 @@ export interface AdmitMentalModelInput {
     /** The doc body (rendered markdown — typically `renderStructuredBody(structuredBody)`). */
     body: string;
     /**
-     * The Reflection section-AST (v2.31 / REFLECT-04) — bound to `structured_body`
+     * The Reflection section-AST — bound to `structured_body`
      * (JSON) so a later reflect refresh can delta-op against it. Omitted ⇒ the
      * column is written NULL (a doc with no structured form). Updated in lockstep
      * with `body` on a re-admit (the idempotent upsert).
@@ -115,6 +126,20 @@ export interface AdmitMentalModelInput {
     kind?: "skill" | "profile" | "topic";
     /** The topic key for a 'topic' doc — omitted ⇒ `''`. */
     topicKey?: string;
+    /**
+     * DETERMINISTIC required-tools footprint (content-free tool NAMES) bound to the
+     * `required_tools` column — the procedure run derives it from the AUDITED
+     * descriptor (NEVER LLM-authored; INV-4). Omitted ⇒ the column is written NULL
+     * (the user-intent skill path). Advisory only: the model re-authors the run under
+     * its already-permissioned tools; this is metadata, not an executable surface.
+     */
+    requiredTools?: ReadonlyArray<string>;
+    /**
+     * The advisory params schema bound to the `params_schema` column — a fixed
+     * content-free value (`"{}"`) for a procedure doc (advisory docs have no replay
+     * parameters). Omitted ⇒ NULL.
+     */
+    paramsSchema?: string;
     /** Initial proof count at admission (capped LOW regardless of cluster size — anti-domination). */
     proofCount: number;
     /** Confidence in [0, 1]. */
@@ -131,7 +156,7 @@ export interface MentalModelStorePort {
      * adapter forces `trust_level = 'learned'` (never trusts the caller) and uses
      * a deterministic id so a replay upserts even if the row was evicted. Returns
      * `ok({ id, admitted })`; never throws. Unresolved scope fails-closed with
-     * `err(...)` — never widens to a shared/global pool (SEC-01).
+     * `err(...)` — never widens to a shared/global pool.
      */
     admit(input: AdmitMentalModelInput, scope: LearningScope): Promise<Result<{
         id: string;
@@ -154,7 +179,7 @@ export interface MentalModelStorePort {
      * but the `candidate → active` transition fires ONLY when crossing the proof
      * bar — i.e. when `proof_count + 1 >= promoteAtProofCount` (the caller-supplied
      * threshold; default policy 3). A single attributed success bumps the count
-     * without activating (the D2 / T-202-04 premature-trust mitigation): a candidate
+     * without activating (the premature-trust mitigation): a candidate
      * at `promoteAtProofCount=3` stays `candidate` after the 1st and 2nd promote and
      * becomes `active` on the 3rd. An already-`active` skill keeps bumping
      * `proof_count` but never changes state. `trust_level` is never touched. Scoped
@@ -170,23 +195,24 @@ export interface MentalModelStorePort {
      * WRITE (name-keyed promote — the reuse-outcome loop entry point). Resolve the
      * skill NAME to its deterministic `(tenant, agent, name)` hash id INTERNALLY and
      * apply {@link promote}'s proof-bar transition, returning whether a row actually
-     * changed. The reuse-attribution carrier (ATTR-01) holds skill NAMES, not ids;
+     * changed. The reuse-attribution carrier holds skill NAMES, not ids;
      * keeping the id derivation in the adapter (one place) avoids leaking the hash
      * formula to callers. `changed === false` means NO row matched the
      * `(tenant, agent, name)` (an unknown/evicted name) — the caller must NOT count
-     * it as a promotion or emit a telemetry event (the 0-row-write-lies fix). Scoped
+     * it as a promotion or emit a telemetry event (a 0-row write must never be
+     * reported as a success). Scoped
      * to `(tenant, agent)`; unresolved scope fails-closed with `err(...)`.
      */
     promoteByName(name: string, scope: LearningScope, promoteAtProofCount: number): Promise<Result<{
         changed: boolean;
     }, Error>>;
     /**
-     * FOLD-01 bi-temporal supersede (Phase 225). A profile/topic doc CORRECTION
+     * Bi-temporal supersede. A profile/topic doc CORRECTION
      * UPDATEs the named doc's `body` (and `structuredBody` when supplied) and APPENDs
      * the PRIOR body to `history` (`{ previousContent, changedAt }`, oldest-first); the
      * row is UPDATEd, never DELETEd — deletion stays reserved for the security
-     * eviction path ({@link evict}). Mirrors the 224 `SqliteMemoryAdapter.supersede`
-     * FORGET-04 model exactly: the untrusted body passes `validateMemoryWrite` BEFORE
+     * eviction path ({@link evict}). Mirrors the `SqliteMemoryAdapter.supersede`
+     * model exactly: the untrusted body passes `validateMemoryWrite` BEFORE
      * the transaction (a `critical` body — secret egress / dangerous command — is
      * rejected with `err`, never persisted; a `warn` is permitted because the row's
      * trust is the fixed `'learned'`), the SELECT-incumbent → history-append → UPDATE
@@ -195,7 +221,7 @@ export interface MentalModelStorePort {
      * escalate trust. Returns `"superseded"` on a successful revise, `"not-found"`
      * when no scoped incumbent matched (no row written), or `err` (firewall-rejected,
      * parse fault, or DB error — the transaction rolled back). Unresolved scope
-     * fails-closed with `err(...)` — never widens to a shared/global pool (SEC-01).
+     * fails-closed with `err(...)` — never widens to a shared/global pool.
      */
     supersede(input: {
         name: string;
@@ -206,7 +232,7 @@ export interface MentalModelStorePort {
      * WRITE (name-keyed demote — the reuse-outcome loop entry point). Resolve the
      * skill NAME to its hash id INTERNALLY and apply {@link demote}, returning whether
      * a row's STATE actually moved. A demote only transitions `active`/`candidate` →
-     * `stale`; the UPDATE's WHERE pins `state IN ('active','candidate')` (WR-06) so a
+     * `stale`; the UPDATE's WHERE pins `state IN ('active','candidate')` so a
      * row in a TERMINAL state (`stale`/`archived`) — like an unknown/evicted name —
      * matches 0 rows and yields `changed === false` (the `updated_at` rewrite never
      * fakes a transition). The caller must NOT count or emit when `changed === false`.

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

@@ -6,14 +6,14 @@ import type { LearningScope } from "./outcome-signal-port.js";
  * (the cause→effect links between memories, and the one-hop lane that surfaces
  * memories causally connected to the seed hits).
  *
- * 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
+ * This is a deliberately separate port — it does NOT widen the security-reviewed
+ * `MemoryPort` (store/search/delete). That surface is never
  * widened for agent use; new capabilities arrive as their own segregated port
- * (the same pattern as `MemoryEntityStore` §6.3, `MemoryTemporalStore` and
+ * (the same pattern as `MemoryEntityStore`, `MemoryTemporalStore` and
  * `MemoryUsefulnessStore`). The sole adapter is in @comis/memory (it owns the
  * `db` handle and runs all SQL over the additive `memory_causal_edges` table);
- * the agent-side write path (memory-review-job, Wave 2) and read path
- * (memory-recall, Wave 3) consume this port TYPE from @comis/core — they cannot
+ * the agent-side write path (memory-review-job) and read path
+ * (memory-recall) consume this port TYPE from @comis/core — they cannot
  * import @comis/memory (the agent↛memory build cut). No new authority is granted
  * beyond link/read within the caller's own (tenant, agent) scope.
  *
@@ -33,8 +33,9 @@ import type { LearningScope } from "./outcome-signal-port.js";
  * DB, not a nicety: an edge written under one (tenant, agent) must NEVER be
  * returned for another scope by memory-id coincidence.
  *
- * SIMPLIFY-02: UNIFIED onto the canonical {@link LearningScope} — the isolation
- * fields are NOT re-declared (the 15× per-port repetition the collapse kills).
+ * Unified onto the canonical {@link LearningScope} — the isolation
+ * fields are NOT re-declared here (one canonical definition instead of a
+ * per-port copy).
  * A thin alias that DERIVES `tenantId`/`agentId` from `LearningScope` and
  * re-narrows the injected clock `now` to REQUIRED (the `linkCausal` write path).
  */

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

@@ -3,24 +3,21 @@ import type { MemoryEntry } from "../domain/memory-entry.js";
 /**
  * MemoryConsolidationStore: the SEGREGATED maintenance boundary for the LIVE
  * read + deletion-reconciliation surface over consolidated observation rows
- * (`proof_count IS NOT NULL`, the column-flag model §4.1).
+ * (`proof_count IS NOT NULL` is the column flag marking a consolidated row).
  *
- * Phase 226 (SIMPLIFY-02): TRIMMED to its live surface. The consolidation CRON
- * (the WRITER — clustering raw memories into observations) was retired in phase
- * 225, so its writer methods (`listConsolidationCandidates` / `applyConsolidation`
- * / `foldIntoExisting` / `knnDistances` surprisal-gate / `markReasoned`
- * deductive-drain) + their candidate/plan input types are gone (grep-proven: 0
- * live, non-cron callers). What REMAINS are three methods with live, non-cron
- * consumers that must keep working:
+ * The port is deliberately limited to this read/maintenance surface — there is
+ * no consolidation-writer surface (no clustering of raw memories into
+ * observations). Its three methods each have a live consumer that must keep
+ * working:
  *   - `listObservations`             — the `comis memory` observation listing
  *                                      (daemon `memory.observations` handler).
- *   - `unlinkDeletedSources`         — DIST-05 deletion reconciliation after
+ *   - `unlinkDeletedSources`         — deletion reconciliation after
  *   - `purgeConsolidatedDerivedFrom`   `session.reset_conversation --memory`.
  *
- * This is a NEW port — it deliberately does NOT widen the security-reviewed
- * agent-facing `MemoryPort` (store/search/delete). Per design §3.2 that surface
+ * This is a SEPARATE port — it deliberately does NOT widen the security-reviewed
+ * agent-facing `MemoryPort` (store/search/delete). That surface
  * is never widened for agent use; new maintenance capabilities arrive as their
- * own segregated port (the same pattern as `MemoryEntityStore` §6.5, guarding
+ * own segregated port (the same pattern as `MemoryEntityStore`, guarding
  * against Elevation of Privilege). The sole adapter lives in the memory package
  * (it owns the `db` handle and runs all SQL); the daemon injects the concrete
  * adapter; consumers import this port TYPE only (the agent↛memory build cut).
@@ -37,7 +34,7 @@ export interface MemoryConsolidationStore {
      */
     listObservations(agentId: string, tenantId: string, limit: number): Promise<Result<MemoryEntry[], Error>>;
     /**
-     * Phase 172 (DIST-05): Unlink the given session's memory ids from all
+     * Unlink the given session's memory ids from all
      * consolidated observations after those source memories were deleted by
      * `session.reset_conversation --memory`.
      *
@@ -57,7 +54,7 @@ export interface MemoryConsolidationStore {
      * source id no longer present in `memories` for this tenant is treated as
      * deleted. See the adapter for the exact predicate.
      *
-     * R4 (WR-05): scoped on `tenant_id` AND `agent_id` — matching
+     * Scoped on `tenant_id` AND `agent_id` — matching
      * `deleteBySessionKey`'s (tenant, agent) scope exactly. A cross-tenant OR
      * cross-agent observation is a fail-closed no-op (never touched). Returns the
      * count of orphan observations deleted.
@@ -69,13 +66,13 @@ export interface MemoryConsolidationStore {
      */
     unlinkDeletedSources(sessionKey: string, tenantId: string, agentId: string): Promise<Result<number, Error>>;
     /**
-     * Phase 172 (DIST-05): Nuclear escalation — delete EVERY consolidated
+     * Nuclear escalation — delete EVERY consolidated
      * observation derived from THIS session's deleted memory ids. Use ONLY when
      * `--purge-derived` is explicitly requested — it is destructive (an observation
      * corroborated by OTHER sessions is STILL deleted when it also cites a
      * this-session source) and cannot be undone.
      *
-     * WR-02 (session-scoped, not coarse): the predicate is
+     * Session-scoped, not coarse: the predicate is
      * `source_ids ∩ thisSessionIds ≠ ∅` — an observation is purged ONLY if it
      * references one of THIS session's memory ids (captured BEFORE the delete via
      * `MemoryPort.listMemoryIdsBySessionKey`). An UNRELATED observation that merely
@@ -83,7 +80,7 @@ export interface MemoryConsolidationStore {
      * session's purge) is NOT touched. When `thisSessionIds` is empty, nothing is
      * purged.
      *
-     * R4 (WR-05): scoped on `tenant_id` AND `agent_id` — a cross-tenant or
+     * Scoped on `tenant_id` AND `agent_id` — a cross-tenant or
      * cross-agent observation is a fail-closed no-op. Returns the count purged.
      *
      * @param sessionKey - The session key to purge derived observations for (audit)

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

@@ -4,13 +4,13 @@ import type { Result } from "@comis/shared";
  * re-rank — a bulk, (tenant, agent)-scoped read of the embedding VECTORS
  * for an already-ranked candidate id set, so the agent-side `mmrRerank` can run
  * `λ·rel − (1−λ)·maxCosineToSelected` over the candidates' ACTUAL embeddings (not
- * a lexical proxy — the locked decision #3).
+ * a lexical proxy).
  *
- * 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
+ * This is a deliberately separate port — it does NOT widen the security-reviewed
+ * `MemoryPort` (store/search/delete). That surface is never
  * widened for agent use; new capabilities arrive as their own segregated port
  * (the same pattern as `MemoryUsefulnessStore` / `MemoryTemporalStore` /
- * `MemoryConsolidationStore` §6.5). The sole adapter is in
+ * `MemoryConsolidationStore`). The sole adapter is in
  * @comis/memory (it owns the `db` handle and runs all SQL); the agent read path
  * (recall MMR) consumes this port TYPE from @comis/core — it cannot import
  * @comis/memory (the agent↛memory build cut). No new authority is granted beyond
@@ -28,7 +28,7 @@ export interface MemoryEmbeddingStore {
      * ABSENT from the map (→ MMR treats it as having no diversity signal; < 2
      * embedded candidates → MMR no-ops, byte-identical recall).
      *
-     * Scope is the load-bearing SQL isolation (V4 access control, §5.2). Because
+     * Scope is the load-bearing SQL access-control isolation. Because
      * this returns the raw VECTORS for a caller-supplied id set (not non-identifying
      * distance scalars), the adapter MUST filter `tenant_id = ? AND agent_id = ?`
      * (JOINing `memories`) — a vector under one (tenant, agent) must NEVER be

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

@@ -6,10 +6,10 @@ import type { LearningScope } from "./outcome-signal-port.js";
  * recall (the people/things/topics memories mention, and the one-hop lane that
  * surfaces memories sharing them).
  *
- * 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
+ * This is a deliberately separate port — it does NOT widen the security-reviewed
+ * `MemoryPort` (store/search/delete). That surface is never
  * widened for agent use; new capabilities arrive as their own segregated port
- * (the same pattern as `MemoryConsolidationStore` §6.5). The sole adapter is in
+ * (the same pattern as `MemoryConsolidationStore`). The sole adapter is in
  * @comis/memory (it owns the `db` handle and runs all SQL); the agent-side
  * write path (memory-review-job) and read path (memory-recall) consume this
  * port TYPE from @comis/core — they cannot import @comis/memory (the
@@ -25,9 +25,9 @@ import type { LearningScope } from "./outcome-signal-port.js";
  * tenants) must NEVER collapse to one entity row or surface each other's
  * memories even when an entity name is identical.
  *
- * SIMPLIFY-02: UNIFIED onto the canonical {@link LearningScope} (`{tenantId,
- * agentId, now?}`) — the isolation fields are NOT re-declared here (that was the
- * 15× per-port repetition the collapse kills). This is a thin alias that DERIVES
+ * Unified onto the canonical {@link LearningScope} (`{tenantId,
+ * agentId, now?}`) — the isolation fields are NOT re-declared here (one
+ * canonical definition instead of a per-port copy). This is a thin alias that DERIVES
  * `tenantId`/`agentId` from `LearningScope` and re-narrows the injected clock
  * `now` to REQUIRED (the entity write path — `resolveAndLink` — bookkeeps
  * `first_seen`/`last_seen` from it; NEVER `Date.now()`).

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

@@ -2,13 +2,13 @@ import type { Result } from "@comis/shared";
 import type { LearningScope } from "./outcome-signal-port.js";
 /**
  * MemoryLifecyclePort: the SEGREGATED hexagonal boundary for the per-(tenant,
- * agent) memory LIFECYCLE sweep (Track C). A periodic,
+ * agent) memory LIFECYCLE sweep. A periodic,
  * KEYLESS maintenance pass that, in the LIVE policy, soft-evicts each non-exempt
  * candidate that is DORMANT past `maxDormantDays` OR corroborated-wrong
  * (`failure_count >= failureEvictionFloor`). Tier promote/demote moves remain a
  * deferred step (`promoted`/`demoted` stay 0).
  *
- * This is a NEW port — like MemoryUsefulnessStore /
+ * This is a SEPARATE port — like MemoryUsefulnessStore /
  * UserRepresentationStore / TripleStorePort it deliberately does NOT widen the
  * security-reviewed `MemoryPort` (store/search/delete). New capabilities arrive
  * as their own segregated port. The sole adapter is in @comis/memory (it owns the
@@ -19,11 +19,11 @@ import type { LearningScope } from "./outcome-signal-port.js";
  * agent↛memory build cut). No new authority is granted beyond a scoped sweep
  * within the caller's own (tenant, agent).
  *
- * LIVE soft eviction (FORGET-01) — when the policy is eviction-enabled (the daemon
+ * LIVE soft eviction — when the policy is eviction-enabled (the daemon
  * threads `learningForgetting.eviction.enabled` ∧ `.enabled`), the sweep soft-evicts
  * each non-exempt candidate that is DORMANT past `maxDormantDays` OR corroborated-wrong
  * (`failure_count >= failureEvictionFloor`), where exempt = pinned ∨
- * `trust_level='system'` ∨ high-`proof_count` (FORGET-03), reporting a real `evicted`
+ * `trust_level='system'` ∨ high-`proof_count`, reporting a real `evicted`
  * count. With the eviction behavior OFF (the default) the sweep stays DORMANT — it
  * scans but applies NOTHING (`evicted`/`demoted` = 0; the byte-identity guarantee).
  * Tier demote/promote moves are still deferred (`promoted`/`demoted` stay 0). The
@@ -44,7 +44,7 @@ import type { LearningScope } from "./outcome-signal-port.js";
 export type MemoryTier = "durable" | "ephemeral";
 /**
  * The PER-CALL eviction-behavior override the daemon threads from each agent's
- * `learningForgetting` config (FORGET-06). The lifecycle store is constructed ONCE and
+ * `learningForgetting` config. The lifecycle store is constructed ONCE and
  * shared across agents, but the eviction policy is PER-AGENT — so the behavior gate rides
  * the sweep CALL (this override), not the constructor: agent A can sweep eviction-on while
  * agent B sweeps DORMANT on the same store. Omitted → the store's constructor policy (the
@@ -55,9 +55,9 @@ export interface MemoryLifecycleEvictionOverride {
     evictionEnabled?: boolean;
     /**
      * The corroborated-`failure_count` floor at/above which a NON-EXEMPT memory is
-     * soft-evicted — the reachable wrongness-eviction path (FORGET-02, the
-     * EVI-STRENGTH-FLOOR fix). Each `failure_count` increment is corroboration-gated;
-     * the FORGET-03 exemptions (pinned / system / high-proof) still gate it, so an
+     * soft-evicted — the reachable wrongness-eviction path.
+     * Each `failure_count` increment is corroboration-gated;
+     * the exemptions (pinned / system / high-proof) still gate it, so an
      * induced-failure attacker cannot evict a well-corroborated memory. Omitted ⇒ the
      * store default.
      */
@@ -69,8 +69,8 @@ export interface MemoryLifecycleEvictionOverride {
  * SECURITY scope in a multi-agent DB, not a nicety: a sweep run under one
  * (tenant, agent) must NEVER touch (promote/demote/evict) another scope's rows.
  *
- * SIMPLIFY-02: UNIFIED onto the canonical {@link LearningScope} — the isolation
- * fields are NOT re-declared (the 15× per-port repetition the collapse kills).
+ * UNIFIED onto the canonical {@link LearningScope} — the isolation
+ * fields are NOT re-declared per port (no drift-prone repetition).
  * A thin alias that DERIVES `tenantId`/`agentId` from `LearningScope`, re-narrows
  * the injected clock `now` to REQUIRED (the sweep's dormancy/age math), AND
  * carries the lifecycle-specific per-call eviction `policy?` override.
@@ -85,7 +85,7 @@ export type MemoryLifecycleScope = LearningScope & {
      */
     now: number;
     /**
-     * PER-CALL eviction-behavior override (FORGET-06). The daemon threads the per-agent
+     * PER-CALL eviction-behavior override. The daemon threads the per-agent
      * `learningForgetting` eviction policy here so the shared store evicts per-agent. When
      * present its fields take precedence over the store's constructor policy for THIS sweep;
      * when omitted the constructor policy applies (DORMANT by default — byte-identical).
@@ -123,26 +123,26 @@ export interface MemoryLifecyclePort {
      *
      * LIVE soft eviction is gated on an eviction-enabled policy
      * (`learningForgetting`): when ON, the two-disjunct candidacy (dormancy OR the
-     * corroborated-failure floor), minus the FORGET-03 exemptions, is soft-evicted
+     * corroborated-failure floor), minus the pinned/system/high-proof exemptions, is soft-evicted
      * (`evicted` is real); when OFF (the default) the sweep scans but applies NOTHING
      * (`evicted`/`demoted` 0 — byte-identity). Tier moves remain deferred
      * (`promoted`/`demoted` 0). With the cron knob off it is not even registered (a
      * default agent runs no sweep → byte-identical).
      *
-     * NOTE: the SQLite adapter implements this; the daemon cron
-     * wiring land in the implementation phases that follow.
+     * NOTE: the SQLite adapter in @comis/memory implements this; the daemon
+     * cron is the sole caller.
      */
     runLifecycleSweep(scope: MemoryLifecycleScope): Promise<Result<LifecycleSweepReport, Error>>;
     /**
-     * REVERSAL PATH (FORGET-04). Un-evict a previously soft-evicted memory on
+     * REVERSAL PATH. Un-evict a previously soft-evicted memory on
      * renewed usefulness: clears its `evicted_at` marker (back to NULL) so the row
      * returns to recall. Soft eviction is reversible by design — the raw row was
      * never deleted, only marked. Scoped to the caller's `(tenant, agent)` ONLY:
      * an un-evict under one scope can NEVER clear another scope's marker (the same
      * load-bearing isolation boundary as the sweep). Idempotent — un-evicting a
-     * live (or absent) row is a no-op `ok(...)`. Called by the daemon reward seam
-     * when a previously-evicted memory becomes useful again (a later plan wires the
-     * caller); the store exposes the capability here.
+     * live (or absent) row is a no-op `ok(...)`. The daemon reward seam is the
+     * intended caller — invoked when a previously-evicted memory becomes useful
+     * again; the store exposes the capability here.
      */
     unevict(memoryId: string, scope: MemoryLifecycleScope): Promise<Result<void, Error>>;
 }

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

@@ -3,10 +3,10 @@ import type { MemorySearchResult } from "./memory.js";
 /**
  * MemoryPinnedStore: the SEGREGATED hexagonal boundary for pinned-memory recall.
  *
- * 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
+ * This is a deliberately separate port — it does NOT widen the security-reviewed
+ * `MemoryPort` (store/search/delete). That surface is never
  * widened for agent use; new capabilities arrive as their own segregated port
- * (the same pattern as `MemoryEntityStore` §6.5). The sole adapter is in
+ * (the same pattern as `MemoryEntityStore`). The sole adapter is in
  * @comis/memory (it owns the `db` handle and runs all SQL); the agent-side
  * read path (memory-recall) consumes this port TYPE from @comis/core — it
  * cannot import @comis/memory (the agent↛memory build cut). No new authority

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

@@ -5,10 +5,10 @@ import type { MemorySearchResult } from "./memory.js";
  * recall (the "what else happened around then" lane — given the seed memories'
  * event times, surface OTHER memories near those times).
  *
- * 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
+ * This is a deliberately separate port — it does NOT widen the security-reviewed
+ * `MemoryPort` (store/search/delete). That surface is never
  * widened for agent use; new capabilities arrive as their own segregated port
- * (the same pattern as `MemoryEntityStore` §6.3 and `MemoryUsefulnessStore`).
+ * (the same pattern as `MemoryEntityStore` and `MemoryUsefulnessStore`).
  * The sole adapter is in @comis/memory (it owns the `db` handle and
  * runs the windowed SQL over the EXISTING `memories.occurred_at` column — NO new
  * table); the agent-side read path (memory-recall) consumes this port TYPE from

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

@@ -4,14 +4,14 @@ 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).
+ * outcomes rather than from raw access counts (an access counter alone cannot
+ * distinguish a memory that helped from one that was merely fetched).
  *
- * 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
+ * This is a deliberately separate port — it does NOT widen the security-reviewed
+ * `MemoryPort` (store/search/delete). That surface is never widened for agent
+ * use; new capabilities arrive as their own segregated port
+ * (the same pattern as `MemoryConsolidationStore` and `MemoryEntityStore`).
+ * 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
@@ -27,8 +27,9 @@ import type { LearningScope } from "./outcome-signal-port.js";
  * 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).
+ * Unified onto the canonical {@link LearningScope} — the isolation
+ * fields are NOT re-declared here (one canonical definition instead of a
+ * per-port copy).
  * 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
@@ -44,8 +45,8 @@ export type UsefulnessScope = LearningScope & {
     /**
      * 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
+     * THAT intent); when OMITTED the adapter resolves the GLOBAL bucket
+     * (intent=""). 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
@@ -70,7 +71,7 @@ export interface UsefulnessSignal {
     /** 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
+     * 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
@@ -99,14 +100,14 @@ export interface MemoryUsefulnessStore {
      */
     readUsefulness(memoryIds: string[], scope: Omit<UsefulnessScope, "now">): Promise<Result<Map<string, UsefulnessSignal>, Error>>;
     /**
-     * WRITE (FORGET-02). Accrue an outcome-attributed task FAILURE for `memoryId`
+     * WRITE. 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
+     * corroboration rule. 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.
      */

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

@@ -17,7 +17,7 @@ export interface MemorySearchOptions {
     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
+     *  NARROW, never widen scope. 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?: {
@@ -102,18 +102,17 @@ export interface MemoryPort {
      */
     delete(id: string, tenantId?: string): Promise<Result<boolean, Error>>;
     /**
-     * Phase 172 (DIST-05): Delete all memory entries matching a session key
+     * 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.
+     * Isolation-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.
+     * OPTIONAL: a MemoryPort implementation MAY omit this method.
      * The session-archive.ts handler gates on `deps.memoryPort.deleteBySessionKey`.
      */
     deleteBySessionKey?(sessionKey: string, scope: {
@@ -121,7 +120,7 @@ export interface MemoryPort {
         agentId: string;
     }): Promise<Result<number, Error>>;
     /**
-     * Phase 172 (DIST-05, WR-02): List the memory ids for a (sessionKey, tenant,
+     * 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
@@ -130,9 +129,9 @@ export interface MemoryPort {
      * 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.
+     * Isolation-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.
      *
      * OPTIONAL: the handler gates on `deps.memoryPort.listMemoryIdsBySessionKey`;
      * when absent, the purge falls back to its coarse session-agnostic behavior.