@oscharko-dev/keiko-memory-governance 0.2.0

package/dist/forget.js

@@ -0,0 +1,142 @@
+// Forget / delete selection + envelope construction.
+//
+// Two pure functions:
+//
+//   selectMemoriesForForget — filters a caller-supplied MemoryRecord array down to the
+//   subset matched by a ForgetSelector. Default `protectPinned: true` excludes pinned
+//   memories (the user must explicitly unpin first). Default `protectArchived: false`
+//   does NOT exclude archived memories (they are already out of active retrieval; a
+//   retention sweep is allowed to re-select them).
+//
+//   buildForgetOperations — maps each selected MemoryRecord to a MemoryForget envelope.
+//   The contracts type literally pins `userAcknowledgedDestructive` to the literal
+//   `true`, so the envelope cannot structurally be constructed without acknowledgement.
+//   Every envelope is revalidated through validateMemoryForget before returning.
+//
+// The two-stage shape is deliberate: callers can present the selection to the user for
+// confirmation (MemoriaViva UI #211) before materialising the destructive envelopes.
+import { validateMemoryForget } from "@oscharko-dev/keiko-contracts/memory";
+import { GovernanceError } from "./errors.js";
+// ─── Scope coordinate equality ────────────────────────────────────────────────
+// Pure: two scopes match when their discriminator AND coordinate field match exactly.
+// Implemented via a canonical "kind:coordinate" string projection to collapse the
+// per-kind branching (memory pattern from issue #205 scopeCoordinateKey).
+function scopeCoordinateKey(scope) {
+    switch (scope.kind) {
+        case "user":
+            return `user:${scope.userId}`;
+        case "workspace":
+            return `workspace:${scope.workspaceId}`;
+        case "project":
+            return `project:${scope.projectId}`;
+        case "workflow":
+            return `workflow:${scope.workflowDefinitionId}`;
+        case "global":
+            return "global:";
+        default: {
+            const _exhaustive = scope;
+            void _exhaustive;
+            return "unknown:";
+        }
+    }
+}
+function scopeEquals(a, b) {
+    return scopeCoordinateKey(a) === scopeCoordinateKey(b);
+}
+// ─── Per-selector filter predicates ───────────────────────────────────────────
+function matchById(record, selector) {
+    return record.id === selector.memoryId;
+}
+function matchByScope(record, selector) {
+    return scopeEquals(record.scope, selector.scope);
+}
+function matchByType(record, selector) {
+    return scopeEquals(record.scope, selector.scope) && record.type === selector.type;
+}
+function matchBySourceConversation(record, selector) {
+    if (!scopeEquals(record.scope, selector.scope))
+        return false;
+    return record.provenance.sourceConversationId === selector.sourceConversationId;
+}
+function matchByTimeWindow(record, selector, nowMs) {
+    if (!scopeEquals(record.scope, selector.scope))
+        return false;
+    return record.createdAt <= nowMs - selector.olderThanMs;
+}
+function assertSelectorWellFormed(selector) {
+    if (selector.kind === "by-time-window") {
+        if (!Number.isFinite(selector.olderThanMs) || selector.olderThanMs < 0) {
+            throw new GovernanceError("invalid-selector-input", "by-time-window olderThanMs must be a finite non-negative number");
+        }
+    }
+}
+function applySelector(record, selector, nowMs) {
+    switch (selector.kind) {
+        case "by-id":
+            return matchById(record, selector);
+        case "by-scope":
+            return matchByScope(record, selector);
+        case "by-type":
+            return matchByType(record, selector);
+        case "by-source-conversation":
+            return matchBySourceConversation(record, selector);
+        case "by-time-window":
+            return matchByTimeWindow(record, selector, nowMs);
+        default: {
+            // Exhaustiveness gate: a future widening of ForgetSelector surfaces here at
+            // compile time and at runtime as an unsupported-selector error.
+            const _exhaustive = selector;
+            void _exhaustive;
+            throw new GovernanceError("unsupported-selector", "unknown ForgetSelector kind");
+        }
+    }
+}
+// ─── Selection ────────────────────────────────────────────────────────────────
+export function selectMemoriesForForget(memories, selector, options) {
+    assertSelectorWellFormed(selector);
+    const protectPinned = options.protectPinned ?? true;
+    const protectArchived = options.protectArchived ?? false;
+    const selected = [];
+    for (const record of memories) {
+        if (protectPinned && record.pinned)
+            continue;
+        if (protectArchived && record.status === "archived")
+            continue;
+        if (record.status === "forgotten")
+            continue;
+        if (!applySelector(record, selector, options.nowMs))
+            continue;
+        selected.push(record);
+    }
+    return selected;
+}
+// ─── Envelope construction ────────────────────────────────────────────────────
+const DEFAULT_FORGET_REASON = "user-requested forget";
+function buildForgetEnvelope(record, context, options) {
+    const env = {
+        schemaVersion: "1",
+        memoryId: record.id,
+        reviewerId: context.reviewerId,
+        forgottenAt: context.nowMs,
+        reason: options.reason ?? DEFAULT_FORGET_REASON,
+        userAcknowledgedDestructive: true,
+    };
+    const v = validateMemoryForget(env);
+    if (!v.ok) {
+        throw new GovernanceError("envelope-validation-failed", `forget envelope failed contracts validation for memory ${record.id}`, v.errors);
+    }
+    return env;
+}
+export function buildForgetOperations(memories, context, options) {
+    // `writeTombstone` is currently observed only at the storage seam (vault #206 writes
+    // an audit tombstone unconditionally). The flag remains on the option bundle as a
+    // future-extension surface and as a forcing function for caller intent — the BFF
+    // route handler MUST decide consciously whether the destructive operation is
+    // tombstone-yielding.
+    void options.writeTombstone;
+    const envelopes = [];
+    for (const record of memories) {
+        envelopes.push(buildForgetEnvelope(record, context, options));
+    }
+    return envelopes;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { KEIKO_MEMORY_GOVERNANCE_VERSION } from "./version.js";
+export type { BuildForgetOperationsOptions, ConflictPair, ConflictReason, ConflictResolution, ForgetSelector, ForgetSelectorKind, GovernanceContext, SelectMemoriesForForgetOptions, StatusTransition, } from "./types.js";
+export { FORGET_SELECTOR_KINDS } from "./types.js";
+export { GovernanceError, type GovernanceErrorCode } from "./errors.js";
+export { buildCorrection, type BuildCorrectionInput, type CorrectionEnvelopes, } from "./correction.js";
+export { buildConflictTransitions, type ConflictTransitionResult, detectConflictPair, } from "./conflict.js";
+export { buildForgetOperations, selectMemoriesForForget } from "./forget.js";
+export { buildExpirationUpdate, supersededValidity } from "./retention.js";
+export { buildArchiveOperation, buildPinOperation, buildUnpinOperation } from "./status-ops.js";
+export { isMemorySuppressedFromRetrieval, type SuppressionOptions, type SuppressionReason, type SuppressionResult, } from "./suppression.js";
+export { effectiveStrength, planMemoryMaintenance, MEMORY_MAINTENANCE_DEFAULTS, type MemoryAccessStatLike, type MemoryMaintenancePlan, type MemoryMaintenancePolicy, type PlanMaintenanceOptions, } from "./maintenance.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,+BAA+B,EAAE,MAAM,cAAc,CAAC;AAG/D,YAAY,EACV,4BAA4B,EAC5B,YAAY,EACZ,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,8BAA8B,EAC9B,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGnD,OAAO,EAAE,eAAe,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGxE,OAAO,EACL,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,wBAAwB,EACxB,KAAK,wBAAwB,EAC7B,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAG7E,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAG3E,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAGhG,OAAO,EACL,+BAA+B,EAC/B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,2BAA2B,EAC3B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,GAC5B,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,29 @@
+// Public surface of @oscharko-dev/keiko-memory-governance (Epic #204 child #209).
+// Keeping this file the SOLE entry point prevents downstream packages from reaching into
+// private modules (ADR-0019 trust rule 7). Internal modules are package-private.
+//
+// Every function in this barrel is pure: same input + same `GovernanceContext` =>
+// byte-identical output. The package never reads a clock, never invokes randomness, never
+// touches the filesystem. The caller supplies `nowMs` and a `reviewerId` through
+// `GovernanceContext`. Every returned envelope is REVALIDATED through the
+// `@oscharko-dev/keiko-contracts` validators before being returned; a construction bug
+// surfaces as a `GovernanceError("envelope-validation-failed", …)` rather than letting an
+// invalid envelope cross the API boundary.
+export { KEIKO_MEMORY_GOVERNANCE_VERSION } from "./version.js";
+export { FORGET_SELECTOR_KINDS } from "./types.js";
+// ─── Errors ──────────────────────────────────────────────────────────────────
+export { GovernanceError } from "./errors.js";
+// ─── Correction ──────────────────────────────────────────────────────────────
+export { buildCorrection, } from "./correction.js";
+// ─── Conflict ────────────────────────────────────────────────────────────────
+export { buildConflictTransitions, detectConflictPair, } from "./conflict.js";
+// ─── Forget ──────────────────────────────────────────────────────────────────
+export { buildForgetOperations, selectMemoriesForForget } from "./forget.js";
+// ─── Retention ───────────────────────────────────────────────────────────────
+export { buildExpirationUpdate, supersededValidity } from "./retention.js";
+// ─── Pin / unpin / archive ───────────────────────────────────────────────────
+export { buildArchiveOperation, buildPinOperation, buildUnpinOperation } from "./status-ops.js";
+// ─── Retrieval suppression ───────────────────────────────────────────────────
+export { isMemorySuppressedFromRetrieval, } from "./suppression.js";
+// ─── Maintenance planner (#204) ──────────────────────────────────────────────
+export { effectiveStrength, planMemoryMaintenance, MEMORY_MAINTENANCE_DEFAULTS, } from "./maintenance.js";

package/dist/maintenance.d.ts

@@ -0,0 +1,33 @@
+import type { MemoryId, MemoryRecord } from "@oscharko-dev/keiko-contracts/memory";
+export interface MemoryAccessStatLike {
+    readonly lastAccessedAt: number;
+    readonly accessCount: number;
+    readonly outcomeCount?: number;
+    readonly utilitySum?: number;
+}
+export interface MemoryMaintenancePolicy {
+    readonly halfLifeMs: number;
+    readonly promoteStrength: number;
+    readonly archiveMaxStrength: number;
+    readonly archiveMinAgeMs: number;
+    readonly forgetArchivedMinAgeMs: number;
+    readonly forgetProposedMaxStrength: number;
+    readonly forgetProposedMinAgeMs: number;
+    readonly maxForgetPerRun: number;
+}
+export declare const MEMORY_MAINTENANCE_DEFAULTS: MemoryMaintenancePolicy;
+export interface MemoryMaintenancePlan {
+    readonly promote: MemoryId[];
+    readonly archive: MemoryId[];
+    readonly forget: {
+        id: MemoryId;
+        reason: string;
+    }[];
+}
+export interface PlanMaintenanceOptions {
+    readonly nowMs: number;
+    readonly policy?: Partial<MemoryMaintenancePolicy>;
+}
+export declare function effectiveStrength(record: MemoryRecord, stat: MemoryAccessStatLike | undefined, nowMs: number, halfLifeMs?: number): number;
+export declare function planMemoryMaintenance(records: readonly MemoryRecord[], accessStats: ReadonlyMap<MemoryId, MemoryAccessStatLike>, options: PlanMaintenanceOptions): MemoryMaintenancePlan;
+//# sourceMappingURL=maintenance.d.ts.map

package/dist/maintenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance.d.ts","sourceRoot":"","sources":["../src/maintenance.ts"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAInF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAI7B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;IAC3C,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAID,eAAO,MAAM,2BAA2B,EAAE,uBASzC,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,QAAQ,EAAE,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,QAAQ,EAAE,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE;QAAE,EAAE,EAAE,QAAQ,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACrD;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACpD;AAgCD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,oBAAoB,GAAG,SAAS,EACtC,KAAK,EAAE,MAAM,EACb,UAAU,GAAE,MAA+C,GAC1D,MAAM,CAMR;AAsID,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,WAAW,EAAE,WAAW,CAAC,QAAQ,EAAE,oBAAoB,CAAC,EACxD,OAAO,EAAE,sBAAsB,GAC9B,qBAAqB,CAiBvB"}

package/dist/maintenance.js

@@ -0,0 +1,180 @@
+// Memory maintenance planner (#204) — the "consolidate + forget" decision engine.
+//
+// PURE: same input + same nowMs => byte-identical plan. No clock reads, no IO, no randomness. The
+// caller (BFF maintenance orchestrator) pre-fetches the records and the access stats, calls this to
+// compute a plan, and applies the plan back to the vault + audit ledger. The split mirrors the
+// consolidation engine: planning is a pure function, application is the impure caller's job.
+//
+// Each record receives AT MOST ONE decision. Priority (highest first): forget > archive > promote.
+// A pinned record is never decayed, archived, or forgotten (its strength is pinned to 1); it may
+// still be promoted since that only strengthens it.
+//
+// Strength model (human-memory analogue):
+//   base         = provenance.confidence                       (calibrated [0,1])
+//   freqBoost    = 1 + 0.15 * ln(1 + accessCount)              (recall strengthens)
+//   recencyFactor= exp(-ln2 * (now - lastTouch) / HALF_LIFE)   (disuse decays; 45-day half-life)
+//   utilityFactor= 0.5 + meanOutcomeUtility                    (outcome-gated; [0.5,1.5], default 1)
+//   strength     = pinned ? 1 : clamp(base * freqBoost * recencyFactor * utilityFactor, 0, 1)
+// lastTouch is the last access timestamp, falling back to createdAt when never accessed.
+//
+// OUTCOME-DRIVEN FORGETTING (#204, O-V1). Disuse is not the only reason to forget: a memory can be
+// recent and frequently recalled yet keep leading to the WRONG answer. `utilityFactor` folds the
+// mean of a memory's governed retention outcomes (proposal accepted/rejected, conflict won/lost,
+// accepted correction superseding its origin) into the strength: all-bad outcomes (mean 0) halve it
+// so the memory archives/forgets sooner; all-good (mean 1) raise it 1.5x so a proven-useful memory
+// resists disuse decay. With NO outcomes the factor is exactly 1 and the model is byte-identical to
+// the pre-O-V1 curve. The factor is bounded so outcomes shift, but never dominate, the prior signal.
+//
+// CONFIDENCE IS IMMUTABLE PROVENANCE (#204, O-V2). This pass NEVER overwrites provenance.confidence.
+// Confidence is the calibrated veridicality of a memory at capture time and is changed only by an
+// explicit, governed user correction/edit — never by a background job. "Reinforcement" and "decay"
+// are not persisted nudges to confidence (that conflated veridicality with activation, lost the
+// original value, and compounded non-idempotently as 0.6^n). Instead:
+//   - reinforcement-on-reuse is realised LIVE at retrieval time via the access-derived strength
+//     subscore (keiko-memory-retrieval strength.ts), and
+//   - disuse-decay is computed ON THE FLY here through `recencyFactor` inside `effectiveStrength`,
+//     which already gates archive/forget. So a faded memory still archives/forgets, but its
+//     provenance stays intact and every run is idempotent.
+const DAY_MS = 864e5;
+export const MEMORY_MAINTENANCE_DEFAULTS = {
+    halfLifeMs: 45 * DAY_MS,
+    promoteStrength: 0.45,
+    archiveMaxStrength: 0.2,
+    archiveMinAgeMs: 3 * DAY_MS,
+    forgetArchivedMinAgeMs: 30 * DAY_MS,
+    forgetProposedMaxStrength: 0.1,
+    forgetProposedMinAgeMs: 14 * DAY_MS,
+    maxForgetPerRun: 25,
+};
+function clamp01(n) {
+    if (n < 0)
+        return 0;
+    if (n > 1)
+        return 1;
+    return n;
+}
+function recencyFactorOf(record, stat, nowMs, halfLifeMs) {
+    // Only a genuine recall advances the recency anchor. An outcome-only row (accessCount 0, written
+    // by recordOutcome before the memory was ever recalled) carries no "last use", so recency falls
+    // back to createdAt — exactly as a never-tracked memory does. For every real access row
+    // (accessCount >= 1) this is byte-identical to the prior `stat.lastAccessedAt ?? createdAt`.
+    const lastTouch = stat !== undefined && stat.accessCount > 0 ? stat.lastAccessedAt : record.createdAt;
+    return Math.exp((-Math.LN2 * (nowMs - lastTouch)) / halfLifeMs);
+}
+// Outcome-gated utility factor (#204, O-V1). Mean utility of the memory's recorded retention
+// outcomes mapped linearly onto [0.5, 1.5]; no outcomes => exactly 1 (strength model unchanged).
+function utilityFactor(stat) {
+    const count = stat?.outcomeCount ?? 0;
+    if (count <= 0)
+        return 1;
+    const meanUtility = clamp01((stat?.utilitySum ?? 0) / count);
+    return 0.5 + meanUtility;
+}
+export function effectiveStrength(record, stat, nowMs, halfLifeMs = MEMORY_MAINTENANCE_DEFAULTS.halfLifeMs) {
+    if (record.pinned)
+        return 1;
+    const base = record.provenance.confidence;
+    const freqBoost = 1 + 0.15 * Math.log1p(stat?.accessCount ?? 0);
+    const recencyFactor = recencyFactorOf(record, stat, nowMs, halfLifeMs);
+    return clamp01(base * freqBoost * recencyFactor * utilityFactor(stat));
+}
+function isValidityExpired(record, nowMs) {
+    const until = record.validity.validUntil;
+    return until !== undefined && until <= nowMs;
+}
+function shouldForget(c, p, nowMs) {
+    if (isValidityExpired(c.record, nowMs))
+        return "validity-expired";
+    // Multi-condition prune guard (#204, O-V5). Hard-deleting an archived memory requires it to be
+    // BOTH aged out AND genuinely faint — never age alone. The archive ROUTE accepts any memory
+    // regardless of strength (a user can deliberately archive a high-confidence record to
+    // de-prioritise it), so age-only pruning would silently delete a still-valuable, explicitly-kept
+    // memory 30 days on. Reusing `archiveMaxStrength` as the faintness floor keeps the policy
+    // symmetric: a record is pruned only once it is at least as faint as the bar that would archive
+    // it. Archive (de-prioritise) is not consent to delete; only disuse is.
+    if (c.record.status === "archived" &&
+        c.ageMs > p.forgetArchivedMinAgeMs &&
+        c.strength < p.archiveMaxStrength) {
+        return "archived-aged-out";
+    }
+    if (c.record.status === "proposed" &&
+        c.strength < p.forgetProposedMaxStrength &&
+        c.accessCount === 0 &&
+        c.ageMs > p.forgetProposedMinAgeMs) {
+        return "proposed-faint-aged-out";
+    }
+    return null;
+}
+function shouldArchive(c, p) {
+    return (c.record.status === "accepted" &&
+        c.strength < p.archiveMaxStrength &&
+        c.ageMs > p.archiveMinAgeMs);
+}
+function shouldPromote(c, p) {
+    return (c.record.status === "proposed" &&
+        c.record.provenance.sensitivity === "public" &&
+        c.strength >= p.promoteStrength);
+}
+function decideForLive(c, p, nowMs) {
+    if (!c.record.pinned) {
+        const forgetReason = shouldForget(c, p, nowMs);
+        if (forgetReason !== null)
+            return { kind: "forget", reason: forgetReason };
+        if (shouldArchive(c, p))
+            return { kind: "archive" };
+    }
+    if (shouldPromote(c, p))
+        return { kind: "promote" };
+    return { kind: "none" };
+}
+function buildContext(record, stat, nowMs, policy) {
+    return {
+        record,
+        stat,
+        strength: effectiveStrength(record, stat, nowMs, policy.halfLifeMs),
+        ageMs: nowMs - record.createdAt,
+        accessCount: stat?.accessCount ?? 0,
+    };
+}
+function applyDecision(acc, c, decision) {
+    const id = c.record.id;
+    switch (decision.kind) {
+        case "forget":
+            acc.forgetCandidates.push({ id, reason: decision.reason ?? "forget", strength: c.strength });
+            return;
+        case "archive":
+            acc.archive.push(id);
+            return;
+        case "promote":
+            acc.promote.push(id);
+            return;
+        case "none":
+            return;
+    }
+}
+// Forget is bounded per run and ordered by ascending strength so the faintest memories go first.
+// Ties break on id for determinism.
+function boundForget(candidates, maxForgetPerRun) {
+    return [...candidates]
+        .sort((a, b) => a.strength !== b.strength ? a.strength - b.strength : a.id.localeCompare(b.id))
+        .slice(0, maxForgetPerRun)
+        .map((c) => ({ id: c.id, reason: c.reason }));
+}
+export function planMemoryMaintenance(records, accessStats, options) {
+    const policy = { ...MEMORY_MAINTENANCE_DEFAULTS, ...options.policy };
+    const acc = {
+        promote: [],
+        archive: [],
+        forgetCandidates: [],
+    };
+    for (const record of records) {
+        const stat = accessStats.get(record.id);
+        const ctx = buildContext(record, stat, options.nowMs, policy);
+        applyDecision(acc, ctx, decideForLive(ctx, policy, options.nowMs));
+    }
+    return {
+        promote: acc.promote,
+        archive: acc.archive,
+        forget: boundForget(acc.forgetCandidates, policy.maxForgetPerRun),
+    };
+}

package/dist/retention.d.ts

@@ -0,0 +1,5 @@
+import type { MemoryRecord, MemoryUpdate, MemoryValidityInterval } from "@oscharko-dev/keiko-contracts/memory";
+import type { GovernanceContext } from "./types.js";
+export declare function supersededValidity(record: MemoryRecord, nowMs: number): MemoryValidityInterval | null;
+export declare function buildExpirationUpdate(memory: MemoryRecord, newValidUntilMs: number, context: GovernanceContext): MemoryUpdate;
+//# sourceMappingURL=retention.d.ts.map

package/dist/retention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.d.ts","sourceRoot":"","sources":["../src/retention.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,sBAAsB,EACvB,MAAM,sCAAsC,CAAC;AAI9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AASpD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,MAAM,GACZ,sBAAsB,GAAG,IAAI,CAK/B;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,YAAY,EACpB,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,iBAAiB,GACzB,YAAY,CAiCd"}

package/dist/retention.js

@@ -0,0 +1,54 @@
+// Expiration / retention update builder.
+//
+// buildExpirationUpdate produces a MemoryUpdate envelope that patches ONLY the validity
+// interval. The semantics are:
+//   - validFrom is preserved from the existing record (an expiration update never
+//     rewrites the underlying fact's start time).
+//   - validUntil is set to the new value supplied by the caller.
+//
+// Throws GovernanceError('invalid-validity-window') if newValidUntilMs <= validFrom,
+// because a zero-or-negative-duration validity is structurally meaningless and would
+// also fail the contracts validateMemoryValidityInterval rule downstream.
+import { validateMemoryUpdate } from "@oscharko-dev/keiko-contracts/memory";
+import { GovernanceError } from "./errors.js";
+// Bi-temporal-lite (#204, C1): the validity interval for a record being SUPERSEDED at `nowMs` — its
+// belief window CLOSED at the moment its replacement takes over. With this, "what did we believe as
+// of date T" is answerable (validFrom <= T AND (validUntil IS NULL OR validUntil > T)) and a closed
+// window drops out of default retrieval automatically. Returns null when closing would not form a
+// valid interval (nowMs <= validFrom) or would EXTEND an already-closed window (existing validUntil
+// <= nowMs), so an already-expired fact is never silently un-expired. Pure; no validation throw —
+// the caller applies it as an additive patch alongside the status transition.
+export function supersededValidity(record, nowMs) {
+    const { validFrom, validUntil } = record.validity;
+    if (!Number.isFinite(nowMs) || nowMs <= validFrom)
+        return null;
+    if (validUntil !== undefined && validUntil <= nowMs)
+        return null;
+    return { validFrom, validUntil: nowMs };
+}
+export function buildExpirationUpdate(memory, newValidUntilMs, context) {
+    if (!Number.isFinite(newValidUntilMs)) {
+        throw new GovernanceError("invalid-validity-window", "newValidUntilMs must be a finite number");
+    }
+    if (newValidUntilMs <= memory.validity.validFrom) {
+        throw new GovernanceError("invalid-validity-window", "newValidUntilMs must be strictly greater than memory.validity.validFrom", [
+            `validFrom: ${String(memory.validity.validFrom)}`,
+            `newValidUntilMs: ${String(newValidUntilMs)}`,
+        ]);
+    }
+    const update = {
+        schemaVersion: "1",
+        memoryId: memory.id,
+        reviewerId: context.reviewerId,
+        updatedAt: context.nowMs,
+        validityPatch: {
+            validFrom: memory.validity.validFrom,
+            validUntil: newValidUntilMs,
+        },
+    };
+    const v = validateMemoryUpdate(update);
+    if (!v.ok) {
+        throw new GovernanceError("envelope-validation-failed", "expiration update failed contracts validation", v.errors);
+    }
+    return update;
+}

package/dist/status-ops.d.ts

@@ -0,0 +1,6 @@
+import type { MemoryArchive, MemoryPin, MemoryRecord, MemoryUnpin } from "@oscharko-dev/keiko-contracts/memory";
+import type { GovernanceContext } from "./types.js";
+export declare function buildPinOperation(memory: MemoryRecord, context: GovernanceContext, reason?: string): MemoryPin;
+export declare function buildUnpinOperation(memory: MemoryRecord, context: GovernanceContext, reason?: string): MemoryUnpin;
+export declare function buildArchiveOperation(memory: MemoryRecord, context: GovernanceContext, reason?: string): MemoryArchive;
+//# sourceMappingURL=status-ops.d.ts.map

package/dist/status-ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-ops.d.ts","sourceRoot":"","sources":["../src/status-ops.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EACV,aAAa,EACb,SAAS,EACT,YAAY,EACZ,WAAW,EACZ,MAAM,sCAAsC,CAAC;AAS9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGpD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,MAAM,GACd,SAAS,CAsBX;AAGD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,MAAM,GACd,WAAW,CAsBb;AA0BD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,MAAM,GACd,aAAa,CAkBf"}

package/dist/status-ops.js

@@ -0,0 +1,86 @@
+// Pin / unpin / archive envelope builders.
+//
+// Each builder is idempotency-rejecting: pinning an already-pinned memory throws
+// GovernanceError("idempotent-noop"), and likewise for unpin/archive. The check happens
+// BEFORE the envelope is constructed so the caller never receives a "valid" envelope
+// representing a no-op. Every emitted envelope is revalidated through the contracts
+// validator (validateMemoryPin / validateMemoryUnpin / validateMemoryArchive) as a
+// defence-in-depth guard against future contract drift.
+//
+// Archive additionally rejects memories whose current status forbids the transition to
+// archived (per MEMORY_STATUS_TRANSITIONS: archive is legal from accepted, superseded,
+// conflicted, expired — and ILLEGAL from proposed, rejected, archived, forgotten). The
+// check is delegated to the same checkStatusTransition helper the conflict layer uses so
+// the two layers agree on transition legality.
+import { checkStatusTransition, validateMemoryArchive, validateMemoryPin, validateMemoryUnpin, } from "@oscharko-dev/keiko-contracts/memory";
+import { GovernanceError } from "./errors.js";
+// ─── Pin ──────────────────────────────────────────────────────────────────────
+export function buildPinOperation(memory, context, reason) {
+    if (memory.pinned) {
+        throw new GovernanceError("idempotent-noop", `memory ${memory.id} is already pinned`, [
+            `memoryId: ${memory.id}`,
+        ]);
+    }
+    const env = {
+        schemaVersion: "1",
+        memoryId: memory.id,
+        reviewerId: context.reviewerId,
+        pinnedAt: context.nowMs,
+        ...(reason !== undefined ? { reason } : {}),
+    };
+    const v = validateMemoryPin(env);
+    if (!v.ok) {
+        throw new GovernanceError("envelope-validation-failed", "pin envelope failed contracts validation", v.errors);
+    }
+    return env;
+}
+// ─── Unpin ────────────────────────────────────────────────────────────────────
+export function buildUnpinOperation(memory, context, reason) {
+    if (!memory.pinned) {
+        throw new GovernanceError("idempotent-noop", `memory ${memory.id} is not pinned`, [
+            `memoryId: ${memory.id}`,
+        ]);
+    }
+    const env = {
+        schemaVersion: "1",
+        memoryId: memory.id,
+        reviewerId: context.reviewerId,
+        unpinnedAt: context.nowMs,
+        ...(reason !== undefined ? { reason } : {}),
+    };
+    const v = validateMemoryUnpin(env);
+    if (!v.ok) {
+        throw new GovernanceError("envelope-validation-failed", "unpin envelope failed contracts validation", v.errors);
+    }
+    return env;
+}
+// ─── Archive ──────────────────────────────────────────────────────────────────
+function assertArchivable(memory) {
+    if (memory.status === "archived") {
+        throw new GovernanceError("idempotent-noop", `memory ${memory.id} is already archived`, [
+            `memoryId: ${memory.id}`,
+        ]);
+    }
+    if (memory.status === "forgotten") {
+        throw new GovernanceError("memory-not-eligible", `memory ${memory.id} is forgotten and cannot be archived`, [`memoryId: ${memory.id}`, `status: ${memory.status}`]);
+    }
+    const check = checkStatusTransition(memory.status, "archived");
+    if (!check.ok) {
+        throw new GovernanceError("illegal-status-transition", check.reason ?? `illegal transition: ${memory.status} -> archived`, [`memoryId: ${memory.id}`, `from: ${memory.status}`, `to: archived`]);
+    }
+}
+export function buildArchiveOperation(memory, context, reason) {
+    assertArchivable(memory);
+    const env = {
+        schemaVersion: "1",
+        memoryId: memory.id,
+        reviewerId: context.reviewerId,
+        archivedAt: context.nowMs,
+        ...(reason !== undefined ? { reason } : {}),
+    };
+    const v = validateMemoryArchive(env);
+    if (!v.ok) {
+        throw new GovernanceError("envelope-validation-failed", "archive envelope failed contracts validation", v.errors);
+    }
+    return env;
+}

package/dist/suppression.d.ts

@@ -0,0 +1,11 @@
+import type { MemoryRecord } from "@oscharko-dev/keiko-contracts/memory";
+export type SuppressionReason = "archived" | "forgotten" | "conflicted" | "expired" | "proposed" | "rejected" | "stale-low-confidence";
+export interface SuppressionResult {
+    readonly suppressed: boolean;
+    readonly reason?: SuppressionReason;
+}
+export interface SuppressionOptions {
+    readonly staleConfidenceThreshold?: number;
+}
+export declare function isMemorySuppressedFromRetrieval(memory: MemoryRecord, nowMs: number, options?: SuppressionOptions): SuppressionResult;
+//# sourceMappingURL=suppression.d.ts.map

package/dist/suppression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suppression.d.ts","sourceRoot":"","sources":["../src/suppression.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,sCAAsC,CAAC;AAIvF,MAAM,MAAM,iBAAiB,GACzB,UAAU,GACV,WAAW,GACX,YAAY,GACZ,SAAS,GACT,UAAU,GACV,UAAU,GACV,sBAAsB,CAAC;AAE3B,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;CACrC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,wBAAwB,CAAC,EAAE,MAAM,CAAC;CAC5C;AA8DD,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CASnB"}