@oscharko-dev/keiko-contracts 0.2.0

package/dist/memory-records.js

@@ -0,0 +1,22 @@
+// Memory record contracts for the Governed Enterprise Memory Vault (Epic #204, Issue
+// #205). Split from `memory.ts` to keep each file under the 400-LOC budget. Pure types
+// only — no IO, no clock reads, no randomness. Leaf-package rule (ADR-0019 direction 1):
+// no `@oscharko-dev/keiko-*` imports.
+//
+// Foundational invariants encoded structurally:
+//  1. `MemoryRecord.scope` is the discriminated scope coordinate from `MemoryScope`.
+//     A record without a concrete scope coordinate cannot be constructed, so two records
+//     at "different scopes" are NEVER structurally equal — the discriminator owns identity.
+//  2. `MemoryRecord.provenance` is REQUIRED on every durable memory. There is no optional
+//     escape hatch. The capture layer (#207) MUST attach provenance before the record can
+//     be persisted.
+//  3. `MemoryRecord.sensitivity` lives on the provenance envelope because sensitivity is
+//     intrinsic to the SOURCE of the memory, not a downstream label. A record cannot be
+//     re-classified by mutating a separate field; sensitivity changes require a
+//     supersession.
+//  4. Timestamps are epoch milliseconds (number). JSON-friendly and Date-free so the type
+//     surface is browser-safe and round-trip-stable.
+export const MEMORY_STRUCTURED_PAYLOAD_KINDS = [
+    "string-list",
+    "key-value",
+];

package/dist/memory-retrieval-validation.d.ts

@@ -0,0 +1,6 @@
+import type { MemoryRetrievalRequest } from "./memory-operations.js";
+import type { MemoryScope } from "./memory.js";
+import { type MemoryValidation } from "./memory-validation.js";
+export declare function validateMemoryRetrievalRequest(input: unknown): MemoryValidation<MemoryRetrievalRequest>;
+export declare function isScopeReachable(candidate: MemoryScope, authorized: readonly MemoryScope[]): boolean;
+//# sourceMappingURL=memory-retrieval-validation.d.ts.map

package/dist/memory-retrieval-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-retrieval-validation.d.ts","sourceRoot":"","sources":["../src/memory-retrieval-validation.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AA2EpF,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,GACb,gBAAgB,CAAC,sBAAsB,CAAC,CAgB1C;AAsBD,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,WAAW,EACtB,UAAU,EAAE,SAAS,WAAW,EAAE,GACjC,OAAO,CAQT"}

package/dist/memory-retrieval-validation.js

@@ -0,0 +1,108 @@
+// Pure validators for memory retrieval (Epic #204, Issue #205). Sibling of
+// `memory-operations-validation.ts`. Split into its own module so each file stays under
+// the 400-LOC budget, and so the retrieval surface — which downstream packages (#210)
+// will iterate on more aggressively than the rest — has a stable, narrow import path.
+//
+// `isScopeReachable` lives here next to the retrieval-request validator because the same
+// caller that constructs the request needs to verify, before issuing it, that each scope
+// it intends to query is in the authorized set. Both helpers are pure and clock-free.
+import { MEMORY_STATUSES, MEMORY_TYPES } from "./memory.js";
+import { validateMemoryScope } from "./memory-validation.js";
+import { MEMORY_BODY_MAX_CHARS, isFiniteNonNegativeNumber, isFinitePositiveInteger, isMember, isRecord, isSafeText, pushNestedErrors, validateSchemaVersionLiteral, validateTags, } from "./memory-internal.js";
+function validateRetrievalScopes(input, errors) {
+    if (!Array.isArray(input) || input.length === 0) {
+        errors.push("retrieval.scopes must be a non-empty array");
+        return;
+    }
+    for (const candidate of input) {
+        pushNestedErrors("retrieval", validateMemoryScope(candidate), errors);
+    }
+}
+function validateRetrievalEnumFilter(field, values, allowed, errors) {
+    if (values === undefined) {
+        return;
+    }
+    if (!Array.isArray(values) || values.length === 0) {
+        errors.push(`retrieval.${field} must be a non-empty array when set`);
+        return;
+    }
+    for (const value of values) {
+        if (!isMember(value, allowed)) {
+            errors.push(`retrieval.${field} entry must be one of ${allowed.join("|")}`);
+            return;
+        }
+    }
+}
+function validateRetrievalNumericLimit(field, value, errors) {
+    if (value === undefined) {
+        return;
+    }
+    if (!isFinitePositiveInteger(value)) {
+        errors.push(`retrieval.${field} must be a positive integer when set`);
+    }
+}
+function validateRetrievalFilters(input, errors) {
+    validateRetrievalEnumFilter("typeFilter", input.typeFilter, MEMORY_TYPES, errors);
+    validateRetrievalEnumFilter("statusFilter", input.statusFilter, MEMORY_STATUSES, errors);
+    if (input.textQuery !== undefined && !isSafeText(input.textQuery, MEMORY_BODY_MAX_CHARS)) {
+        errors.push("retrieval.textQuery must be a bounded control-free string when set");
+    }
+    if (input.tagsFilter !== undefined) {
+        validateTags("retrieval.tagsFilter", input.tagsFilter, errors);
+    }
+}
+function validateRetrievalBudgetAndToggles(input, errors) {
+    validateRetrievalNumericLimit("maxResults", input.maxResults, errors);
+    validateRetrievalNumericLimit("maxBodyChars", input.maxBodyChars, errors);
+    if (input.includeArchived !== undefined && typeof input.includeArchived !== "boolean") {
+        errors.push("retrieval.includeArchived must be a boolean when set");
+    }
+    if (input.includeSuperseded !== undefined && typeof input.includeSuperseded !== "boolean") {
+        errors.push("retrieval.includeSuperseded must be a boolean when set");
+    }
+}
+export function validateMemoryRetrievalRequest(input) {
+    if (!isRecord(input)) {
+        return { ok: false, errors: ["retrieval must be an object"] };
+    }
+    const errors = [];
+    validateSchemaVersionLiteral(input, errors);
+    if (!isFiniteNonNegativeNumber(input.requestedAt)) {
+        errors.push("retrieval.requestedAt must be a finite non-negative number");
+    }
+    validateRetrievalScopes(input.scopes, errors);
+    validateRetrievalFilters(input, errors);
+    validateRetrievalBudgetAndToggles(input, errors);
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true, value: input };
+}
+// A canonical coordinate string per scope. Distinct scope kinds always produce strings
+// with distinct kind prefixes, so a `userId` equal to a `workspaceId` cannot collide.
+// `global` carries a fixed coordinate so set membership remains a pure string compare.
+function scopeCoordinateKey(scope) {
+    switch (scope.kind) {
+        case "global":
+            return "global:";
+        case "user":
+            return `user:${scope.userId}`;
+        case "workspace":
+            return `workspace:${scope.workspaceId}`;
+        case "project":
+            return `project:${scope.projectId}`;
+        case "workflow":
+            return `workflow:${scope.workflowDefinitionId}`;
+    }
+}
+// A candidate scope is reachable when an authorized scope shares the same canonical
+// coordinate. This is the type-level anchor for the no-cross-scope-visibility invariant.
+export function isScopeReachable(candidate, authorized) {
+    const target = scopeCoordinateKey(candidate);
+    for (const scope of authorized) {
+        if (scopeCoordinateKey(scope) === target) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/memory-validation.d.ts

@@ -0,0 +1,31 @@
+import type { MemoryEdge, MemoryProvenance, MemoryRecord, MemoryStructuredPayload, MemoryValidityInterval } from "./memory-records.js";
+import type { MemoryScope, MemoryStatus } from "./memory.js";
+export interface MemoryValidationOk<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+export interface MemoryValidationFail {
+    readonly ok: false;
+    readonly errors: readonly string[];
+}
+export type MemoryValidation<T> = MemoryValidationOk<T> | MemoryValidationFail;
+export declare function looksLikeSecretShape(value: string): boolean;
+export interface StatusTransitionCheck {
+    readonly ok: boolean;
+    readonly reason?: string;
+}
+export declare function checkStatusTransition(from: MemoryStatus, to: MemoryStatus): StatusTransitionCheck;
+export declare function validateMemoryScope(input: unknown): MemoryValidation<MemoryScope>;
+export declare function validateMemoryValidityInterval(input: unknown): MemoryValidation<MemoryValidityInterval>;
+export declare function validateMemoryProvenance(input: unknown): MemoryValidation<MemoryProvenance>;
+export declare function validateMemoryStructuredPayload(input: unknown): MemoryValidation<MemoryStructuredPayload>;
+export declare function validateMemoryEdge(input: unknown): MemoryValidation<MemoryEdge>;
+export interface StaleModelMetadataInput {
+    readonly record: Pick<MemoryRecord, "provenance">;
+    readonly activeIdentitiesByProvider: ReadonlyMap<string, {
+        readonly modelId: string;
+        readonly modelRevision?: string;
+    }>;
+}
+export declare function hasStaleModelMetadata(input: StaleModelMetadataInput): boolean;
+//# sourceMappingURL=memory-validation.d.ts.map

package/dist/memory-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-validation.d.ts","sourceRoot":"","sources":["../src/memory-validation.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAuB7D,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AACD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AACD,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,kBAAkB,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC;AA2D/E,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAO3D;AAKD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,YAAY,GAAG,qBAAqB,CAejG;AA0BD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAajF;AAGD,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,GACb,gBAAgB,CAAC,sBAAsB,CAAC,CAmB1C;AAuBD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAAC,gBAAgB,CAAC,CAmC3F;AAoCD,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,OAAO,GACb,gBAAgB,CAAC,uBAAuB,CAAC,CAoB3C;AA+BD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAuB/E;AAMD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;IAClD,QAAQ,CAAC,0BAA0B,EAAE,WAAW,CAC9C,MAAM,EACN;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAC9D,CAAC;CACH;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAoB7E"}

package/dist/memory-validation.js

@@ -0,0 +1,318 @@
+// Pure validators for the Governed Enterprise Memory Vault contracts (Epic #204, Issue
+// #205). No filesystem, no clock, no crypto, no randomness — every helper inspects the
+// structure of an `unknown` payload and reports which invariants failed. Producers and
+// consumers wire these at trust-boundary edges (BFF, audit, capture, retrieval).
+//
+// Result envelopes follow the local-knowledge convention: a discriminated
+// `{ ok: true; value } | { ok: false; errors }` so branches stay throw-free. Errors are
+// short, machine-readable strings — one per failed invariant — for deterministic
+// evaluation-harness diffs.
+//
+// Operation envelope validators (proposal/acceptance/rejection/update/etc.) live in the
+// sibling module `memory-operations-validation.ts` to keep both files under the 400-LOC
+// budget.
+import { MEMORY_EDGE_KINDS, MEMORY_SCOPE_KINDS, MEMORY_SENSITIVITIES, MEMORY_SOURCE_KINDS, MEMORY_STATUSES, MEMORY_STATUS_TRANSITIONS, } from "./memory.js";
+import { MEMORY_STRUCTURED_PAYLOAD_KINDS } from "./memory-records.js";
+import { FORBIDDEN_CONTROL_RE, MEMORY_RATIONALE_MAX_CHARS, isFiniteNonNegativeNumber, isMember, isNonEmptyTrimmedString, isRecord, isSafeText, isUnitInterval, validateOptionalReference, } from "./memory-internal.js";
+// ─── Unsafe-content heuristics (secret-shape only, no allow/block list) ──────
+// Audit-record defence-in-depth: rejects credential-shaped strings on the AUDIT SUMMARY
+// path (validateMemoryAuditRecord). The PRIMARY secret-prevention gate is the capture
+// layer (#207), which scans candidate memory body/payload before construction. This
+// helper is intentionally NOT applied to record.body or proposal.body — body scanning is
+// owned end-to-end by the capture layer so callers cannot route around the policy by
+// constructing records directly. Shape-based: we test the SHAPE of the string, not a
+// list of providers, so the heuristic stays useful across vendor changes.
+//
+// Pattern coverage — intentionally narrow (high precision over high recall):
+//   COVERED:  sk- (OpenAI-style), AKIA (AWS), gh[pousr]_ (GitHub tokens),
+//             xox[abporsu]- (Slack), three-part JWTs, PEM private keys,
+//             long contiguous digit runs that resemble a payment-card PAN.
+//   EXCLUDED: opaque "Bearer <token>" (catches only JWT-encoded bearers),
+//             URL-embedded credentials (https://user:pass@host),
+//             generic password=, secret=, key= form-encoded values.
+//             These classes are intentionally deferred to the capture layer
+//             (#207), where context-aware redaction can avoid false positives
+//             on legitimate non-secret strings.
+const SECRET_SHAPE_PATTERNS = [
+    /\bsk-[A-Za-z0-9_-]{20,}\b/,
+    /\bAKIA[0-9A-Z]{16}\b/,
+    /\bgh[pousr]_[A-Za-z0-9]{36,}\b/,
+    /\bxox[abporsu]-[A-Za-z0-9-]{10,}\b/,
+    /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/,
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+];
+const PAN_SHAPE_RE = /\b(?:\d[ -]?){13,19}\b/g;
+function passesLuhn(value) {
+    let sum = 0;
+    let shouldDouble = false;
+    for (let index = value.length - 1; index >= 0; index -= 1) {
+        let digit = Number(value[index]);
+        if (shouldDouble) {
+            digit *= 2;
+            if (digit > 9) {
+                digit -= 9;
+            }
+        }
+        sum += digit;
+        shouldDouble = !shouldDouble;
+    }
+    return sum % 10 === 0;
+}
+function hasPaymentCardPanShape(value) {
+    for (const match of value.matchAll(PAN_SHAPE_RE)) {
+        const candidate = match[0].replaceAll(/[ -]/g, "");
+        if (candidate.length >= 13 && candidate.length <= 19 && passesLuhn(candidate)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function looksLikeSecretShape(value) {
+    for (const re of SECRET_SHAPE_PATTERNS) {
+        if (re.test(value)) {
+            return true;
+        }
+    }
+    return hasPaymentCardPanShape(value);
+}
+export function checkStatusTransition(from, to) {
+    if (!isMember(from, MEMORY_STATUSES)) {
+        return { ok: false, reason: `unknown from-status: ${String(from)}` };
+    }
+    if (!isMember(to, MEMORY_STATUSES)) {
+        return { ok: false, reason: `unknown to-status: ${String(to)}` };
+    }
+    if (from === to) {
+        return { ok: false, reason: `no-op transition: ${from} → ${to}` };
+    }
+    const allowed = MEMORY_STATUS_TRANSITIONS[from];
+    if (!allowed.includes(to)) {
+        return { ok: false, reason: `illegal transition: ${from} → ${to}` };
+    }
+    return { ok: true };
+}
+// ─── Scope ────────────────────────────────────────────────────────────────────
+// The validator checks that the coordinate field that MUST be present for the given kind
+// is a non-empty string. Scope-CROSSING legality (i.e. "can a request at scope X read a
+// record at scope Y") is an authorization decision belonging to downstream layers; this
+// validator only proves the scope itself is well-formed.
+function validateScopeCoordinate(input, errors) {
+    const kind = input.kind;
+    if (kind === "global") {
+        return;
+    }
+    if (kind === "user" && !isNonEmptyTrimmedString(input.userId)) {
+        errors.push("scope.userId must be a non-empty string for kind=user");
+    }
+    if (kind === "workspace" && !isNonEmptyTrimmedString(input.workspaceId)) {
+        errors.push("scope.workspaceId must be a non-empty string for kind=workspace");
+    }
+    if (kind === "project" && !isNonEmptyTrimmedString(input.projectId)) {
+        errors.push("scope.projectId must be a non-empty string for kind=project");
+    }
+    if (kind === "workflow" && !isNonEmptyTrimmedString(input.workflowDefinitionId)) {
+        errors.push("scope.workflowDefinitionId must be a non-empty string for kind=workflow");
+    }
+}
+export function validateMemoryScope(input) {
+    if (!isRecord(input)) {
+        return { ok: false, errors: ["scope must be an object"] };
+    }
+    if (!isMember(input.kind, MEMORY_SCOPE_KINDS)) {
+        return { ok: false, errors: [`scope.kind must be one of ${MEMORY_SCOPE_KINDS.join("|")}`] };
+    }
+    const errors = [];
+    validateScopeCoordinate(input, errors);
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true, value: input };
+}
+// ─── Validity interval ────────────────────────────────────────────────────────
+export function validateMemoryValidityInterval(input) {
+    if (!isRecord(input)) {
+        return { ok: false, errors: ["validity must be an object"] };
+    }
+    const errors = [];
+    if (!isFiniteNonNegativeNumber(input.validFrom)) {
+        errors.push("validity.validFrom must be a finite non-negative number");
+    }
+    if (input.validUntil !== undefined) {
+        if (!isFiniteNonNegativeNumber(input.validUntil)) {
+            errors.push("validity.validUntil must be a finite non-negative number when set");
+        }
+        else if (isFiniteNonNegativeNumber(input.validFrom) && input.validUntil < input.validFrom) {
+            errors.push("validity.validUntil must be greater than or equal to validFrom");
+        }
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true, value: input };
+}
+// ─── Provenance ───────────────────────────────────────────────────────────────
+function validateModelIdentity(input, errors) {
+    const identity = input.modelIdentity;
+    if (identity === undefined) {
+        return;
+    }
+    if (!isRecord(identity)) {
+        errors.push("provenance.modelIdentity must be an object when set");
+        return;
+    }
+    if (!isNonEmptyTrimmedString(identity.provider)) {
+        errors.push("provenance.modelIdentity.provider must be a non-empty string");
+    }
+    if (!isNonEmptyTrimmedString(identity.modelId)) {
+        errors.push("provenance.modelIdentity.modelId must be a non-empty string");
+    }
+    if (identity.modelRevision !== undefined && !isNonEmptyTrimmedString(identity.modelRevision)) {
+        errors.push("provenance.modelIdentity.modelRevision must be a non-empty string when set");
+    }
+}
+export function validateMemoryProvenance(input) {
+    if (!isRecord(input)) {
+        return { ok: false, errors: ["provenance must be an object"] };
+    }
+    const errors = [];
+    if (!isMember(input.sourceKind, MEMORY_SOURCE_KINDS)) {
+        errors.push(`provenance.sourceKind must be one of ${MEMORY_SOURCE_KINDS.join("|")}`);
+    }
+    validateOptionalReference("provenance.sourceConversationId", input.sourceConversationId, errors);
+    validateOptionalReference("provenance.sourceWorkflowRunId", input.sourceWorkflowRunId, errors);
+    validateOptionalReference("provenance.sourceEvidenceManifestId", input.sourceEvidenceManifestId, errors);
+    if (!isFiniteNonNegativeNumber(input.capturedAt)) {
+        errors.push("provenance.capturedAt must be a finite non-negative number");
+    }
+    validateModelIdentity(input, errors);
+    if (!isUnitInterval(input.confidence)) {
+        errors.push("provenance.confidence must be a finite number in [0, 1]");
+    }
+    if (!isMember(input.sensitivity, MEMORY_SENSITIVITIES)) {
+        errors.push(`provenance.sensitivity must be one of ${MEMORY_SENSITIVITIES.join("|")}`);
+    }
+    if (input.captureRationale !== undefined &&
+        !isSafeText(input.captureRationale, MEMORY_RATIONALE_MAX_CHARS)) {
+        errors.push("provenance.captureRationale must be a bounded control-free string when set");
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true, value: input };
+}
+// ─── Structured payload ───────────────────────────────────────────────────────
+function validateStringListPayload(input, errors) {
+    if (!Array.isArray(input.items)) {
+        errors.push("payload.items must be an array for kind=string-list");
+        return;
+    }
+    for (const item of input.items) {
+        if (typeof item !== "string" || item.length === 0 || FORBIDDEN_CONTROL_RE.test(item)) {
+            errors.push("payload.items entry must be a non-empty control-free string");
+            return;
+        }
+    }
+}
+function validateKeyValuePayload(input, errors) {
+    if (!Array.isArray(input.entries)) {
+        errors.push("payload.entries must be an array for kind=key-value");
+        return;
+    }
+    for (const entry of input.entries) {
+        if (!isRecord(entry) ||
+            !isNonEmptyTrimmedString(entry.key) ||
+            typeof entry.value !== "string" ||
+            FORBIDDEN_CONTROL_RE.test(entry.value)) {
+            errors.push("payload.entries entry must have a non-empty key and a control-free string value");
+            return;
+        }
+    }
+}
+export function validateMemoryStructuredPayload(input) {
+    if (!isRecord(input)) {
+        return { ok: false, errors: ["payload must be an object"] };
+    }
+    if (!isMember(input.kind, MEMORY_STRUCTURED_PAYLOAD_KINDS)) {
+        return {
+            ok: false,
+            errors: [`payload.kind must be one of ${MEMORY_STRUCTURED_PAYLOAD_KINDS.join("|")}`],
+        };
+    }
+    const errors = [];
+    if (input.kind === "string-list") {
+        validateStringListPayload(input, errors);
+    }
+    else {
+        validateKeyValuePayload(input, errors);
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true, value: input };
+}
+// ─── Edge ─────────────────────────────────────────────────────────────────────
+function validateEdgeEndpoints(input, errors) {
+    if (!isNonEmptyTrimmedString(input.fromMemoryId)) {
+        errors.push("edge.fromMemoryId must be a non-empty string");
+    }
+    if (!isNonEmptyTrimmedString(input.toMemoryId)) {
+        errors.push("edge.toMemoryId must be a non-empty string");
+    }
+    if (isNonEmptyTrimmedString(input.fromMemoryId) &&
+        isNonEmptyTrimmedString(input.toMemoryId) &&
+        input.fromMemoryId === input.toMemoryId) {
+        errors.push("edge.fromMemoryId and edge.toMemoryId must differ");
+    }
+}
+function validateEdgeOptionalFields(input, errors) {
+    if (input.confidence !== undefined && !isUnitInterval(input.confidence)) {
+        errors.push("edge.confidence must be a finite number in [0, 1] when set");
+    }
+    if (input.provenanceSummary !== undefined &&
+        !isSafeText(input.provenanceSummary, MEMORY_RATIONALE_MAX_CHARS)) {
+        errors.push("edge.provenanceSummary must be a bounded control-free string when set");
+    }
+}
+export function validateMemoryEdge(input) {
+    if (!isRecord(input)) {
+        return { ok: false, errors: ["edge must be an object"] };
+    }
+    const errors = [];
+    if (input.schemaVersion !== "1") {
+        errors.push('edge.schemaVersion must be the literal "1"');
+    }
+    if (!isNonEmptyTrimmedString(input.id)) {
+        errors.push("edge.id must be a non-empty string");
+    }
+    validateEdgeEndpoints(input, errors);
+    if (!isMember(input.kind, MEMORY_EDGE_KINDS)) {
+        errors.push(`edge.kind must be one of ${MEMORY_EDGE_KINDS.join("|")}`);
+    }
+    if (!isFiniteNonNegativeNumber(input.createdAt)) {
+        errors.push("edge.createdAt must be a finite non-negative number");
+    }
+    validateEdgeOptionalFields(input, errors);
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true, value: input };
+}
+export function hasStaleModelMetadata(input) {
+    const identity = input.record.provenance.modelIdentity;
+    if (identity === undefined) {
+        return false;
+    }
+    const active = input.activeIdentitiesByProvider.get(identity.provider);
+    if (active === undefined) {
+        return true;
+    }
+    if (active.modelId !== identity.modelId) {
+        return true;
+    }
+    if (identity.modelRevision !== undefined &&
+        active.modelRevision !== undefined &&
+        identity.modelRevision !== active.modelRevision) {
+        return true;
+    }
+    return false;
+}

package/dist/memory-workflow-port.d.ts

@@ -0,0 +1,26 @@
+import type { MemoryId, MemoryScope } from "./memory.js";
+export interface MemoryWorkflowContext {
+    readonly text: string;
+    readonly includedMemoryIds: readonly MemoryId[];
+}
+export interface MemoryUsedEvent {
+    readonly memoryIds: readonly MemoryId[];
+    readonly scopes: readonly MemoryScope[];
+    readonly reason: string;
+}
+export interface MemoryOmittedEvent {
+    readonly memoryId: MemoryId;
+    readonly reason: string;
+}
+export interface MemoryWriteCandidateEvent {
+    readonly proposalSummary: string;
+    readonly scope: MemoryScope;
+    readonly source: "workflow-success" | "workflow-correction";
+}
+export interface MemoryWorkflowPort {
+    readonly getContextForWorkflow: (scopes: readonly MemoryScope[], queryText?: string, budgetTokens?: number) => Promise<MemoryWorkflowContext>;
+    readonly onMemoryUsed?: (event: MemoryUsedEvent) => void;
+    readonly onMemoryOmitted?: (event: MemoryOmittedEvent) => void;
+    readonly onMemoryWriteCandidate?: (event: MemoryWriteCandidateEvent) => void;
+}
+//# sourceMappingURL=memory-workflow-port.d.ts.map

package/dist/memory-workflow-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-workflow-port.d.ts","sourceRoot":"","sources":["../src/memory-workflow-port.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAOzD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,iBAAiB,EAAE,SAAS,QAAQ,EAAE,CAAC;CACjD;AAKD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAOD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAOD,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,GAAG,qBAAqB,CAAC;CAC7D;AAED,MAAM,WAAW,kBAAkB;IAIjC,QAAQ,CAAC,qBAAqB,EAAE,CAC9B,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,SAAS,CAAC,EAAE,MAAM,EAClB,YAAY,CAAC,EAAE,MAAM,KAClB,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAIpC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IAKzD,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAG/D,QAAQ,CAAC,sBAAsB,CAAC,EAAE,CAAC,KAAK,EAAE,yBAAyB,KAAK,IAAI,CAAC;CAC9E"}

package/dist/memory-workflow-port.js

@@ -0,0 +1,13 @@
+// Workflow-facing port for the Governed Enterprise Memory Vault (Epic #204, Issue #213).
+// Pure type contract — no runtime logic, no IO, no clock, no randomness. Leaf-package rule
+// (ADR-0019 direction 1): no `@oscharko-dev/keiko-*` imports may appear in this module; all
+// referenced types come from sibling modules inside @oscharko-dev/keiko-contracts.
+//
+// Boundary intent: workflow packages (`keiko-workflows`, future `keiko-evaluations`) accept
+// an OPTIONAL `MemoryWorkflowPort` so they can compose pre-run memory context and emit
+// post-run lifecycle events for the audit ledger and MemoriaViva UI. Memory is READ-ONLY
+// from the workflow's perspective — the port cannot grant write/execution authority. Apply
+// gates (#6 applyEnabled, patch limits, scope guards) remain the sole write surface
+// (epic §Architecture Invariants 1+2). The workflow remains fully backward-compatible when
+// the port is absent: the field is optional and every callback is optional.
+export {};

package/dist/memory.d.ts

@@ -0,0 +1,81 @@
+export declare const MEMORY_SCHEMA_VERSION: "1";
+declare const MemoryIdBrand: unique symbol;
+declare const MemoryProposalIdBrand: unique symbol;
+declare const MemoryEdgeIdBrand: unique symbol;
+declare const MemoryAuditRecordIdBrand: unique symbol;
+declare const MemoryReviewerIdBrand: unique symbol;
+declare const UserIdBrand: unique symbol;
+declare const WorkspaceIdBrand: unique symbol;
+declare const ProjectIdBrand: unique symbol;
+declare const WorkflowDefinitionIdBrand: unique symbol;
+declare const ConversationIdBrand: unique symbol;
+declare const WorkflowRunIdBrand: unique symbol;
+declare const EvidenceManifestIdBrand: unique symbol;
+export type MemoryId = string & {
+    readonly [MemoryIdBrand]: true;
+};
+export type MemoryProposalId = string & {
+    readonly [MemoryProposalIdBrand]: true;
+};
+export type MemoryEdgeId = string & {
+    readonly [MemoryEdgeIdBrand]: true;
+};
+export type MemoryAuditRecordId = string & {
+    readonly [MemoryAuditRecordIdBrand]: true;
+};
+export type MemoryReviewerId = string & {
+    readonly [MemoryReviewerIdBrand]: true;
+};
+export type UserId = string & {
+    readonly [UserIdBrand]: true;
+};
+export type WorkspaceId = string & {
+    readonly [WorkspaceIdBrand]: true;
+};
+export type ProjectId = string & {
+    readonly [ProjectIdBrand]: true;
+};
+export type WorkflowDefinitionId = string & {
+    readonly [WorkflowDefinitionIdBrand]: true;
+};
+export type ConversationId = string & {
+    readonly [ConversationIdBrand]: true;
+};
+export type WorkflowRunId = string & {
+    readonly [WorkflowRunIdBrand]: true;
+};
+export type EvidenceManifestId = string & {
+    readonly [EvidenceManifestIdBrand]: true;
+};
+export type MemoryScopeKind = "user" | "workspace" | "project" | "workflow" | "global";
+export declare const MEMORY_SCOPE_KINDS: readonly MemoryScopeKind[];
+export type MemoryScope = {
+    readonly kind: "user";
+    readonly userId: UserId;
+} | {
+    readonly kind: "workspace";
+    readonly workspaceId: WorkspaceId;
+} | {
+    readonly kind: "project";
+    readonly projectId: ProjectId;
+} | {
+    readonly kind: "workflow";
+    readonly workflowDefinitionId: WorkflowDefinitionId;
+} | {
+    readonly kind: "global";
+};
+export type MemoryType = "episodic" | "semantic-fact" | "procedural" | "preference" | "correction" | "decision" | "negative" | "pinned";
+export declare const MEMORY_TYPES: readonly MemoryType[];
+export type MemorySensitivity = "public" | "confidential" | "restricted";
+export declare const MEMORY_SENSITIVITIES: readonly MemorySensitivity[];
+export type MemoryStatus = "proposed" | "accepted" | "rejected" | "superseded" | "archived" | "forgotten" | "conflicted" | "expired";
+export declare const MEMORY_STATUSES: readonly MemoryStatus[];
+export declare const MEMORY_STATUS_TRANSITIONS: Readonly<Record<MemoryStatus, readonly MemoryStatus[]>>;
+export type MemorySourceKind = "explicit-user-instruction" | "accepted-correction" | "workflow-outcome" | "consolidation" | "system-default";
+export declare const MEMORY_SOURCE_KINDS: readonly MemorySourceKind[];
+export type MemoryEdgeKind = "related" | "derived-from" | "supersedes" | "corrects" | "conflicts-with" | "temporal-precedes";
+export declare const MEMORY_EDGE_KINDS: readonly MemoryEdgeKind[];
+export type MemoryAuditActionKind = "proposed" | "accepted" | "rejected" | "updated" | "superseded" | "pinned" | "unpinned" | "archived" | "forgotten" | "retrieved";
+export declare const MEMORY_AUDIT_ACTION_KINDS: readonly MemoryAuditActionKind[];
+export {};
+//# sourceMappingURL=memory.d.ts.map

package/dist/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"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"}