@oscharko-dev/keiko-memory-governance 0.2.0

package/dist/suppression.js

@@ -0,0 +1,85 @@
+// Retrieval-suppression predicate.
+//
+// isMemorySuppressedFromRetrieval is a pure function consumed by the retrieval layer
+// (#210) to filter result sets. It maps the discriminated MemoryStatus enum to a
+// suppression reason and also applies two derived rules:
+//
+//   - validity.validUntil <= nowMs   →   "expired"   (regardless of status)
+//   - provenance.confidence <= staleConfidenceThreshold  →  "stale-low-confidence"
+//
+// Default staleConfidenceThreshold is 0.3 — same conservative floor consolidation uses
+// (#208 _constants.ts STALE_CONFIDENCE_DEFAULT 0.3) so the two layers agree on what
+// counts as low-confidence. The threshold is a `<=` comparison: a record exactly at
+// the threshold is suppressed.
+//
+// The contracts MemoryStatus enum is the single source of truth: every legal status
+// branches to a deterministic suppression decision. A future widening of MemoryStatus
+// surfaces as an exhaustiveness compile error here.
+import { GovernanceError } from "./errors.js";
+const DEFAULT_STALE_CONFIDENCE_THRESHOLD = 0.3;
+const NOT_SUPPRESSED = { suppressed: false };
+function isFiniteInRange(value, min, max) {
+    return Number.isFinite(value) && value >= min && value <= max;
+}
+function resolveThreshold(options) {
+    const threshold = options.staleConfidenceThreshold ?? DEFAULT_STALE_CONFIDENCE_THRESHOLD;
+    if (isFiniteInRange(threshold, 0, 1))
+        return threshold;
+    throw new GovernanceError("invalid-threshold", `staleConfidenceThreshold must be a finite number in [0, 1] (got ${String(threshold)})`);
+}
+function statusSuppression(status) {
+    switch (status) {
+        case "archived":
+            return { suppressed: true, reason: "archived" };
+        case "forgotten":
+            return { suppressed: true, reason: "forgotten" };
+        case "conflicted":
+            return { suppressed: true, reason: "conflicted" };
+        case "rejected":
+            return { suppressed: true, reason: "rejected" };
+        case "expired":
+            // Validity-based "expired" is checked separately below so an explicit `expired`
+            // status carries the same surface reason whether the retrieval index pinned it via
+            // status or derived it from the validity window.
+            return { suppressed: true, reason: "expired" };
+        case "proposed":
+            return { suppressed: true, reason: "proposed" };
+        case "accepted":
+        case "superseded":
+            // accepted/superseded are pass-through here. Superseded records are still readable
+            // in audit views; the retrieval layer applies its own includeSuperseded toggle on
+            // top of this predicate. Review queues surface proposed records through direct
+            // status filtering rather than retrieval.
+            return null;
+        default: {
+            const _exhaustive = status;
+            void _exhaustive;
+            return null;
+        }
+    }
+}
+function validitySuppression(memory, nowMs) {
+    if (memory.validity.validUntil === undefined)
+        return null;
+    if (memory.validity.validUntil > nowMs)
+        return null;
+    return { suppressed: true, reason: "expired" };
+}
+function confidenceSuppression(memory, threshold) {
+    if (memory.provenance.confidence > threshold)
+        return null;
+    return { suppressed: true, reason: "stale-low-confidence" };
+}
+export function isMemorySuppressedFromRetrieval(memory, nowMs, options = {}) {
+    const threshold = resolveThreshold(options);
+    const byStatus = statusSuppression(memory.status);
+    if (byStatus !== null)
+        return byStatus;
+    const byValidity = validitySuppression(memory, nowMs);
+    if (byValidity !== null)
+        return byValidity;
+    const byConfidence = confidenceSuppression(memory, threshold);
+    if (byConfidence !== null)
+        return byConfidence;
+    return NOT_SUPPRESSED;
+}

package/dist/types.d.ts

@@ -0,0 +1,51 @@
+import type { ConversationId, MemoryId, MemoryReviewerId, MemoryScope, MemoryStatus, MemoryType } from "@oscharko-dev/keiko-contracts/memory";
+export interface GovernanceContext {
+    readonly reviewerId: MemoryReviewerId;
+    readonly nowMs: number;
+}
+export type ForgetSelector = {
+    readonly kind: "by-id";
+    readonly memoryId: MemoryId;
+} | {
+    readonly kind: "by-scope";
+    readonly scope: MemoryScope;
+} | {
+    readonly kind: "by-type";
+    readonly scope: MemoryScope;
+    readonly type: MemoryType;
+} | {
+    readonly kind: "by-source-conversation";
+    readonly scope: MemoryScope;
+    readonly sourceConversationId: ConversationId;
+} | {
+    readonly kind: "by-time-window";
+    readonly scope: MemoryScope;
+    readonly olderThanMs: number;
+};
+export type ForgetSelectorKind = ForgetSelector["kind"];
+export interface StatusTransition {
+    readonly memoryId: MemoryId;
+    readonly from: MemoryStatus;
+    readonly to: MemoryStatus;
+    readonly transitionedAt: number;
+}
+export type ConflictReason = "negation-flip" | "polarity-mismatch" | "value-mismatch";
+export interface ConflictPair {
+    readonly hasConflict: boolean;
+    readonly reason?: ConflictReason;
+}
+export interface ConflictResolution {
+    readonly winner: MemoryId;
+    readonly losers: readonly MemoryId[];
+}
+export interface SelectMemoriesForForgetOptions {
+    readonly nowMs: number;
+    readonly protectPinned?: boolean;
+    readonly protectArchived?: boolean;
+}
+export interface BuildForgetOperationsOptions {
+    readonly writeTombstone: boolean;
+    readonly reason?: string;
+}
+export declare const FORGET_SELECTOR_KINDS: readonly ForgetSelectorKind[];
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,cAAc,EACd,QAAQ,EACR,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,UAAU,EACX,MAAM,sCAAsC,CAAC;AAO9C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAWD,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GACpF;IACE,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,oBAAoB,EAAE,cAAc,CAAC;CAC/C,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnG,MAAM,MAAM,kBAAkB,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;AAOxD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAGD,MAAM,MAAM,cAAc,GAAG,eAAe,GAAG,mBAAmB,GAAG,gBAAgB,CAAC;AAEtF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;CAClC;AAMD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,CAAC;CACtC;AAOD,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,MAAM,WAAW,4BAA4B;IAM3C,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAuBD,eAAO,MAAM,qBAAqB,EAAE,SAAS,kBAAkB,EAMrD,CAAC"}

package/dist/types.js

@@ -0,0 +1,32 @@
+// Public type surface for @oscharko-dev/keiko-memory-governance (Epic #204 child #209).
+// Pure types only — no IO, no clock, no randomness. Every function exported from this
+// package consumes a `GovernanceContext` instead of reading the wall clock or generating
+// a reviewer id internally; the caller (BFF route handler, MemoriaViva UI, workflow
+// orchestrator) is the authoritative source of both.
+// ─── Correction options ───────────────────────────────────────────────────────
+// `buildCorrection` produces both a `correction`-type MemoryProposal AND a
+// MemorySupersession linking the old MemoryId to the new one. The caller persists the
+// proposal first (mint a new MemoryId at acceptance) and then applies the supersession
+// once it knows the freshly-minted id.
+//
+// We require the caller to supply `newMemoryIdHint`: the supersession envelope needs the
+// NEW memory id at construction time. The "correct" architecture would be a two-phase
+// commit — propose, accept-and-mint, supersede — but a single function returning both
+// envelopes is the operating contract #209 asks for. The hint is a placeholder that the
+// caller MUST replace with the real minted id before sending the supersession to the
+// audit ledger; the GovernanceError("supersession-needs-real-id") at the storage seam
+// catches a caller that forgets.
+//
+// The proposal carries a `proposalId` distinct from `newMemoryIdHint`; both flow through
+// the caller-supplied `newProposalId` and `newMemoryIdHint` factories so the builder
+// stays pure.
+// ─── Re-export the selector kind list at runtime ──────────────────────────────
+// Frozen at the value level so a downstream switch can iterate it without re-deriving the
+// literal set.
+export const FORGET_SELECTOR_KINDS = [
+    "by-id",
+    "by-scope",
+    "by-type",
+    "by-source-conversation",
+    "by-time-window",
+];

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const KEIKO_MEMORY_GOVERNANCE_VERSION: "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,+BAA+B,EAAG,OAAgB,CAAC"}

package/dist/version.js

@@ -0,0 +1 @@
+export const KEIKO_MEMORY_GOVERNANCE_VERSION = "0.1.0";

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@oscharko-dev/keiko-memory-governance",
+  "version": "0.2.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "MemoriaViva — Internal memory-governance package (Epic #204 child #209): pure-function envelope builders for user-driven corrections, conflict resolution, selective forgetting, expiration, pinning and archiving over Governed Enterprise Memory Vault records. Every public function returns a contracts-validated operation envelope (MemoryProposal / MemorySupersession / MemoryUpdate / MemoryForget / MemoryPin / MemoryUnpin / MemoryArchive) or a StatusTransition; the caller (vault #206, audit #214, MemoriaViva UI #211, retrieval #210) materialises the persistence side. Pinned memories cannot be silently selected for forget. No IO, no clock, no randomness (caller supplies nowMs). ADR-0019 direction rule 3i (governance may depend only on keiko-contracts and keiko-security). Not published independently.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "typecheck": "tsc -b tsconfig.json",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@oscharko-dev/keiko-contracts": "0.2.0",
+    "@oscharko-dev/keiko-security": "0.2.0"
+  }
+}