@oscharko-dev/keiko-contracts 0.2.0

package/dist/local-knowledge.js

@@ -0,0 +1,63 @@
+// Public type contracts for the Local Knowledge Connector surface (Epic #189, Issue #191).
+// Pure types and pure validators only — no IO, no clock reads, no hashing, no randomness, no
+// filesystem access. Leaf-package rule (ADR-0019 direction 1): no `@oscharko-dev/keiko-*`
+// imports may appear in this module. The schemaVersion discriminant follows the same
+// evolution rule as CONNECTED_CONTEXT_SCHEMA_VERSION (ADR-0010 D2): a breaking change
+// introduces a NEW literal member rather than mutating "1".
+//
+// Foundry IQ composition (issue #191): KnowledgeSource, KnowledgeCapsule, and CapsuleSet are
+// modelled as three separate concepts. Every document-derived record (DocumentRecord,
+// ChunkRecord, VectorRecord, CitationReference, RetrievalReference) carries explicit
+// capsuleId + sourceId + documentId lineage so a single global knowledge pool is
+// unrepresentable in the type system.
+//
+// Browser safety: `ChunkRecord` carries `safeExcerptHash`, not raw extracted text, so the
+// contract surface remains safe to send to a browser surface without re-redaction. Raw
+// content lives only inside the local-knowledge runtime, never on the wire.
+// ─── Schema version ───────────────────────────────────────────────────────────
+export const LOCAL_KNOWLEDGE_SCHEMA_VERSION = "1";
+export const EMBEDDING_VECTOR_METRICS = [
+    "cosine",
+    "euclidean",
+    "dot",
+];
+export const KNOWLEDGE_SOURCE_SCOPE_KINDS = [
+    "folder",
+    "repository",
+    "files",
+];
+export const CAPSULE_LIFECYCLE_STATES = [
+    "draft",
+    "indexing",
+    "ready",
+    "stale",
+    "deleting",
+    "error",
+];
+export const CAPSULE_RETRIEVAL_EFFORTS = [
+    "minimal",
+    "default",
+    "deep",
+];
+export const CAPSULE_OUTPUT_MODES = [
+    "answers",
+    "snippets",
+    "raw",
+];
+export const CAPSULE_ANSWER_GROUNDING_POLICIES = [
+    "require-citations",
+    "require-citations-or-state-no-evidence",
+    "best-effort",
+];
+// ─── Capsule management wire types (Slice 4 / Issue #189) ─────────────────────
+// Bounded limits matching the spec (≤16 keys, key ≤128, value ≤1024 chars).
+export const CAPSULE_METADATA_MAX_KEYS = 16;
+export const CAPSULE_METADATA_KEY_MAX_CHARS = 128;
+export const CAPSULE_METADATA_VALUE_MAX_CHARS = 1024;
+// Maximum members in a capsule set (non-destructive composition cap).
+export const CAPSULE_SET_MAX_MEMBERS = 16;
+export const CONNECTOR_NODE_KINDS = [
+    "files-window",
+    "local-knowledge",
+    "conversation-center",
+];

package/dist/memory-audit-events.d.ts

@@ -0,0 +1,73 @@
+import type { MemoryAuditInitiatorSurface, MemoryId, MemoryScope } from "./memory-barrel.js";
+export declare const MEMORY_AUDIT_EVENT_SCHEMA_VERSION: "1";
+export declare const MEMORY_AUDIT_EVENT_SUMMARY_MAX_CHARS = 240;
+export type MemoryAuditEventKind = "memory:proposed" | "memory:accepted" | "memory:rejected" | "memory:updated" | "memory:superseded" | "memory:pinned" | "memory:unpinned" | "memory:archived" | "memory:forgotten" | "memory:retrieved" | "memory:workflow-used" | "memory:workflow-omitted" | "memory:workflow-write-candidate";
+export declare const MEMORY_AUDIT_EVENT_KINDS: readonly MemoryAuditEventKind[];
+interface MemoryAuditEventEnvelope {
+    readonly schemaVersion: typeof MEMORY_AUDIT_EVENT_SCHEMA_VERSION;
+    readonly eventId: string;
+    readonly occurredAt: number;
+    readonly initiatorSurface: MemoryAuditInitiatorSurface;
+    readonly summary: string;
+}
+export type MemoryAuditEvent = (MemoryAuditEventEnvelope & {
+    readonly kind: "memory:proposed";
+    readonly memoryId: MemoryId;
+    readonly scope: MemoryScope;
+}) | (MemoryAuditEventEnvelope & {
+    readonly kind: "memory:accepted";
+    readonly memoryId: MemoryId;
+    readonly scope: MemoryScope;
+}) | (MemoryAuditEventEnvelope & {
+    readonly kind: "memory:rejected";
+    readonly memoryId: MemoryId;
+    readonly scope: MemoryScope;
+}) | (MemoryAuditEventEnvelope & {
+    readonly kind: "memory:updated";
+    readonly memoryId: MemoryId;
+    readonly scope: MemoryScope;
+}) | (MemoryAuditEventEnvelope & {
+    readonly kind: "memory:superseded";
+    readonly oldMemoryId: MemoryId;
+    readonly newMemoryId: MemoryId;
+    readonly scope: MemoryScope;
+}) | (MemoryAuditEventEnvelope & {
+    readonly kind: "memory:pinned";
+    readonly memoryId: MemoryId;
+    readonly scope: MemoryScope;
+}) | (MemoryAuditEventEnvelope & {
+    readonly kind: "memory:unpinned";
+    readonly memoryId: MemoryId;
+    readonly scope: MemoryScope;
+}) | (MemoryAuditEventEnvelope & {
+    readonly kind: "memory:archived";
+    readonly memoryId: MemoryId;
+    readonly scope: MemoryScope;
+}) | (MemoryAuditEventEnvelope & {
+    readonly kind: "memory:forgotten";
+    readonly memoryId: MemoryId;
+    readonly scope: MemoryScope;
+    readonly tombstoned: boolean;
+}) | (MemoryAuditEventEnvelope & {
+    readonly kind: "memory:retrieved";
+    readonly scopes: readonly MemoryScope[];
+    readonly matchedMemoryIds: readonly MemoryId[];
+}) | (MemoryAuditEventEnvelope & {
+    readonly kind: "memory:workflow-used";
+    readonly workflowRunId: string;
+    readonly usedMemoryIds: readonly MemoryId[];
+}) | (MemoryAuditEventEnvelope & {
+    readonly kind: "memory:workflow-omitted";
+    readonly workflowRunId: string;
+    readonly scopes: readonly MemoryScope[];
+    readonly omittedMemoryId: MemoryId;
+    readonly reason: string;
+}) | (MemoryAuditEventEnvelope & {
+    readonly kind: "memory:workflow-write-candidate";
+    readonly workflowRunId: string;
+    readonly source: "workflow-success" | "workflow-correction";
+    readonly scope: MemoryScope;
+    readonly proposedMemoryIds: readonly MemoryId[];
+});
+export {};
+//# sourceMappingURL=memory-audit-events.d.ts.map

package/dist/memory-audit-events.d.ts.map

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

package/dist/memory-audit-events.js

@@ -0,0 +1,44 @@
+// Memory audit event surface for the Governed Enterprise Memory Vault (Epic #204, Issue
+// #214). Pure types only — no IO, no clock reads, no randomness. Leaf-package rule
+// (ADR-0019 direction 1): no `@oscharko-dev/keiko-*` imports.
+//
+// `MemoryAuditEvent` is the AUDIT-LAYER projection of the vault's structural `MemoryEvent`
+// (defined inside keiko-memory-vault). The vault emits low-level state-change events
+// ("memory:inserted", "memory:updated", "memory:deleted", "memory:tombstoned", "edge:*",
+// "embedding:upserted"); the audit bridge (`keiko-server/memory-audit-handler`) MAPS each
+// structural event into one of the SEMANTIC kinds in this file by reading the new record's
+// status, comparing against a previous-status cache, and classifying the transition.
+//
+// Retrieval/workflow-specific kinds are NOT emitted by the vault. They are surfaced here
+// so the audit ledger has a single closed type for every memory-touching audit signal.
+// Retrieval and workflow integration layers emit them directly via `recordMemoryAudit(...)`.
+// They are listed in `MEMORY_AUDIT_EVENT_KINDS` so the closed enum is stable across schema
+// versions.
+//
+// Audit invariant (mirrors `MemoryAuditRecord`): NEVER carry raw memory body or payload.
+// `summary` is a short, REDACTED rationale (bounded length). `scope` and IDs are
+// non-secret; scope-coordinate strings are run through the audit redactor at persist time
+// in case a user-supplied identifier happens to match a credential shape.
+// ─── Schema version ───────────────────────────────────────────────────────────
+// Pinned to "1". A breaking change introduces a NEW literal member rather than mutating
+// "1" — the same evolution rule as `MEMORY_SCHEMA_VERSION` and the other contract surfaces.
+export const MEMORY_AUDIT_EVENT_SCHEMA_VERSION = "1";
+// Maximum length for `summary`. Audit ledger summaries are dense human-readable strings,
+// not bodies. The bound matches `MEMORY_SUMMARY_MAX_CHARS` (240 chars) used in the audit
+// record validator so the two audit surfaces stay aligned at the boundary.
+export const MEMORY_AUDIT_EVENT_SUMMARY_MAX_CHARS = 240;
+export const MEMORY_AUDIT_EVENT_KINDS = [
+    "memory:proposed",
+    "memory:accepted",
+    "memory:rejected",
+    "memory:updated",
+    "memory:superseded",
+    "memory:pinned",
+    "memory:unpinned",
+    "memory:archived",
+    "memory:forgotten",
+    "memory:retrieved",
+    "memory:workflow-used",
+    "memory:workflow-omitted",
+    "memory:workflow-write-candidate",
+];

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

@@ -0,0 +1,4 @@
+import type { MemoryAuditRecord } from "./memory-operations.js";
+import { type MemoryValidation } from "./memory-validation.js";
+export declare function validateMemoryAuditRecord(input: unknown): MemoryValidation<MemoryAuditRecord>;
+//# sourceMappingURL=memory-audit-validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory-audit-validation.d.ts","sourceRoot":"","sources":["../src/memory-audit-validation.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAIhE,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,wBAAwB,CAAC;AAgJhC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAAC,iBAAiB,CAAC,CAqB7F"}

package/dist/memory-audit-validation.js

@@ -0,0 +1,151 @@
+// Pure validators for the memory audit ledger envelope (Epic #204, Issue #205). Sibling
+// of `memory-operations-validation.ts` and `memory-retrieval-validation.ts`.
+//
+// Audit invariant: a `MemoryAuditRecord.summary` MUST NOT carry credential-shaped content.
+// This is defence in depth — the audit ledger persists summaries directly to evidence
+// storage (#214), so a leaked secret would otherwise bypass body-only redaction sweeps.
+// The shape check is `looksLikeSecretShape` from memory-validation.ts.
+import { MEMORY_AUDIT_INITIATOR_SURFACES, MEMORY_UPDATE_FIELDS } from "./memory-operations.js";
+import { MEMORY_AUDIT_ACTION_KINDS, MEMORY_EDGE_KINDS } from "./memory.js";
+import { looksLikeSecretShape, validateMemoryScope, } from "./memory-validation.js";
+import { MEMORY_REASON_MAX_CHARS, MEMORY_SUMMARY_MAX_CHARS, isFiniteNonNegativeNumber, isMember, isNonEmptyTrimmedString, isRecord, isSafeText, pushNestedErrors, validateMemoryIdString, validateSchemaVersionLiteral, } from "./memory-internal.js";
+// Required field names per audit-action kind. Adding a new kind extends this map AND the
+// `MemoryAuditAction` discriminated union; the validator complains when a present action
+// is missing a required field for its kind.
+const AUDIT_ACTION_KIND_FIELDS = new Map([
+    ["proposed", ["proposalId", "scope"]],
+    ["accepted", ["proposalId", "memoryId", "scope"]],
+    ["rejected", ["proposalId", "reason"]],
+    ["updated", ["memoryId", "fieldsChanged"]],
+    ["superseded", ["oldMemoryId", "newMemoryId", "edgeId", "edgeKind"]],
+    ["pinned", ["memoryId"]],
+    ["unpinned", ["memoryId"]],
+    ["archived", ["memoryId"]],
+    ["forgotten", ["memoryId", "scope", "reason"]],
+    ["retrieved", ["scopes", "matchedMemoryIds"]],
+]);
+function validateAuditScopeArrayField(value, errors) {
+    if (!Array.isArray(value) || value.length === 0) {
+        errors.push("action.scopes must be a non-empty array");
+        return;
+    }
+    for (const scope of value) {
+        pushNestedErrors("action", validateMemoryScope(scope), errors);
+    }
+}
+function validateAuditMatchedIds(value, errors) {
+    if (!Array.isArray(value)) {
+        errors.push("action.matchedMemoryIds must be an array");
+        return;
+    }
+    for (const id of value) {
+        if (!isNonEmptyTrimmedString(id)) {
+            errors.push("action.matchedMemoryIds entry must be a non-empty string");
+            return;
+        }
+    }
+}
+function validateAuditFieldsChanged(value, errors) {
+    if (!Array.isArray(value) || value.length === 0) {
+        errors.push("action.fieldsChanged must be a non-empty array");
+        return;
+    }
+    for (const field of value) {
+        if (!isMember(field, MEMORY_UPDATE_FIELDS)) {
+            errors.push(`action.fieldsChanged entry must be one of ${MEMORY_UPDATE_FIELDS.join("|")}`);
+            return;
+        }
+    }
+}
+function validateAuditActionFieldShapes(action, errors) {
+    if ("scope" in action) {
+        pushNestedErrors("action", validateMemoryScope(action.scope), errors);
+    }
+    if ("scopes" in action) {
+        validateAuditScopeArrayField(action.scopes, errors);
+    }
+    if ("matchedMemoryIds" in action) {
+        validateAuditMatchedIds(action.matchedMemoryIds, errors);
+    }
+    if ("fieldsChanged" in action) {
+        validateAuditFieldsChanged(action.fieldsChanged, errors);
+    }
+    validateOptionalAuditIdField("action.proposalId", action.proposalId, errors);
+    validateOptionalAuditIdField("action.memoryId", action.memoryId, errors);
+    validateOptionalAuditIdField("action.edgeId", action.edgeId, errors);
+    validateOptionalAuditIdField("action.oldMemoryId", action.oldMemoryId, errors);
+    validateOptionalAuditIdField("action.newMemoryId", action.newMemoryId, errors);
+    if ("edgeKind" in action && !isMember(action.edgeKind, MEMORY_EDGE_KINDS)) {
+        errors.push(`action.edgeKind must be one of ${MEMORY_EDGE_KINDS.join("|")}`);
+    }
+    if ("reason" in action && !isSafeText(action.reason, MEMORY_REASON_MAX_CHARS)) {
+        errors.push("action.reason must be a bounded control-free non-empty string");
+    }
+}
+function validateOptionalAuditIdField(field, value, errors) {
+    if (value === undefined) {
+        return;
+    }
+    validateMemoryIdString(field, value, errors);
+}
+function validateAuditActionKindShape(action, errors) {
+    if (!isMember(action.kind, MEMORY_AUDIT_ACTION_KINDS)) {
+        errors.push(`action.kind must be one of ${MEMORY_AUDIT_ACTION_KINDS.join("|")}`);
+        return;
+    }
+    const expected = AUDIT_ACTION_KIND_FIELDS.get(action.kind);
+    if (expected === undefined) {
+        errors.push(`action.kind ${action.kind} is missing field expectations`);
+        return;
+    }
+    for (const field of expected) {
+        if (!(field in action)) {
+            errors.push(`action.${field} is required for kind=${action.kind}`);
+        }
+    }
+    validateAuditActionFieldShapes(action, errors);
+}
+function validateAuditRecordCore(input, errors) {
+    validateSchemaVersionLiteral(input, errors);
+    validateMemoryIdString("auditRecord.id", input.id, errors);
+    if (!isMember(input.actionKind, MEMORY_AUDIT_ACTION_KINDS)) {
+        errors.push(`auditRecord.actionKind must be one of ${MEMORY_AUDIT_ACTION_KINDS.join("|")}`);
+    }
+    if (!isMember(input.initiatorSurface, MEMORY_AUDIT_INITIATOR_SURFACES)) {
+        errors.push(`auditRecord.initiatorSurface must be one of ${MEMORY_AUDIT_INITIATOR_SURFACES.join("|")}`);
+    }
+    if (input.initiatorReviewerId !== undefined &&
+        !isNonEmptyTrimmedString(input.initiatorReviewerId)) {
+        errors.push("auditRecord.initiatorReviewerId must be a non-empty string when set");
+    }
+    if (!isFiniteNonNegativeNumber(input.occurredAt)) {
+        errors.push("auditRecord.occurredAt must be a finite non-negative number");
+    }
+    if (!isSafeText(input.summary, MEMORY_SUMMARY_MAX_CHARS)) {
+        errors.push("auditRecord.summary must be a bounded control-free non-empty string");
+    }
+    else if (looksLikeSecretShape(input.summary)) {
+        errors.push("auditRecord.summary must not carry credential-shaped content");
+    }
+}
+export function validateMemoryAuditRecord(input) {
+    if (!isRecord(input)) {
+        return { ok: false, errors: ["auditRecord must be an object"] };
+    }
+    const errors = [];
+    validateAuditRecordCore(input, errors);
+    if (!isRecord(input.action)) {
+        errors.push("auditRecord.action must be an object");
+    }
+    else {
+        if (isMember(input.actionKind, MEMORY_AUDIT_ACTION_KINDS) &&
+            input.action.kind !== input.actionKind) {
+            errors.push("auditRecord.action.kind must match auditRecord.actionKind");
+        }
+        validateAuditActionKindShape(input.action, errors);
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true, value: input };
+}

package/dist/memory-barrel.d.ts

@@ -0,0 +1,15 @@
+export type { ConversationId, EvidenceManifestId, MemoryAuditActionKind, MemoryAuditRecordId, MemoryEdgeId, MemoryEdgeKind, MemoryId, MemoryProposalId, MemoryReviewerId, MemoryScope, MemoryScopeKind, MemorySensitivity, MemorySourceKind, MemoryStatus, MemoryType, ProjectId, UserId, WorkflowDefinitionId, WorkflowRunId, WorkspaceId, } from "./memory.js";
+export { MEMORY_AUDIT_ACTION_KINDS, MEMORY_EDGE_KINDS, MEMORY_SCHEMA_VERSION, MEMORY_SCOPE_KINDS, MEMORY_SENSITIVITIES, MEMORY_SOURCE_KINDS, MEMORY_STATUSES, MEMORY_STATUS_TRANSITIONS, MEMORY_TYPES, } from "./memory.js";
+export type { MemoryEdge, MemoryModelIdentity, MemoryProvenance, MemoryRecord, MemoryRetentionHint, MemoryStructuredPayload, MemoryStructuredPayloadKind, MemoryValidityInterval, } from "./memory-records.js";
+export { MEMORY_STRUCTURED_PAYLOAD_KINDS } from "./memory-records.js";
+export type { MemoryAcceptance, MemoryArchive, MemoryAuditAction, MemoryAuditInitiatorSurface, MemoryAuditRecord, MemoryForget, MemoryPin, MemoryProposal, MemoryRejection, MemoryRetrievalRequest, MemorySupersession, MemoryUnpin, MemoryUpdate, MemoryUpdateField, } from "./memory-operations.js";
+export { MEMORY_AUDIT_INITIATOR_SURFACES, MEMORY_UPDATE_FIELDS } from "./memory-operations.js";
+export type { MemoryValidation, MemoryValidationFail, MemoryValidationOk, StaleModelMetadataInput, StatusTransitionCheck, } from "./memory-validation.js";
+export { checkStatusTransition, hasStaleModelMetadata, looksLikeSecretShape, validateMemoryEdge, validateMemoryProvenance, validateMemoryScope, validateMemoryStructuredPayload, validateMemoryValidityInterval, } from "./memory-validation.js";
+export { validateMemoryAcceptance, validateMemoryArchive, validateMemoryForget, validateMemoryPin, validateMemoryProposal, validateMemoryRejection, validateMemorySupersession, validateMemoryUnpin, validateMemoryUpdate, } from "./memory-operations-validation.js";
+export { isScopeReachable, validateMemoryRetrievalRequest } from "./memory-retrieval-validation.js";
+export { validateMemoryAuditRecord } from "./memory-audit-validation.js";
+export type { MemoryAuditEvent, MemoryAuditEventKind } from "./memory-audit-events.js";
+export { MEMORY_AUDIT_EVENT_KINDS, MEMORY_AUDIT_EVENT_SCHEMA_VERSION, MEMORY_AUDIT_EVENT_SUMMARY_MAX_CHARS, } from "./memory-audit-events.js";
+export { assertNeverMemoryType, isMemoryEdge, isMemoryRecord, validateMemoryRecord, } from "./memory-record-validation.js";
+//# sourceMappingURL=memory-barrel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory-barrel.d.ts","sourceRoot":"","sources":["../src/memory-barrel.ts"],"names":[],"mappings":"AASA,YAAY,EACV,cAAc,EACd,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,SAAS,EACT,MAAM,EACN,oBAAoB,EACpB,aAAa,EACb,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,EACf,yBAAyB,EACzB,YAAY,GACb,MAAM,aAAa,CAAC;AAGrB,YAAY,EACV,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,uBAAuB,EACvB,2BAA2B,EAC3B,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,+BAA+B,EAAE,MAAM,qBAAqB,CAAC;AAGtE,YAAY,EACV,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,2BAA2B,EAC3B,iBAAiB,EACjB,YAAY,EACZ,SAAS,EACT,cAAc,EACd,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAClB,WAAW,EACX,YAAY,EACZ,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,+BAA+B,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAG/F,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,wBAAwB,EACxB,mBAAmB,EACnB,+BAA+B,EAC/B,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,0BAA0B,EAC1B,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,mCAAmC,CAAC;AAG3C,OAAO,EAAE,gBAAgB,EAAE,8BAA8B,EAAE,MAAM,kCAAkC,CAAC;AAGpG,OAAO,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAGzE,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACvF,OAAO,EACL,wBAAwB,EACxB,iCAAiC,EACjC,oCAAoC,GACrC,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,qBAAqB,EACrB,YAAY,EACZ,cAAc,EACd,oBAAoB,GACrB,MAAM,+BAA+B,CAAC"}

package/dist/memory-barrel.js

@@ -0,0 +1,20 @@
+// Single-import target for the Governed Enterprise Memory Vault contract surface
+// (Epic #204, Issue #205). Downstream packages import from
+// `@oscharko-dev/keiko-contracts/memory` and reach every memory type, every const tuple,
+// and every pure validator from here.
+//
+// Re-exports use the explicit `export type` form for type-only names and `export` for
+// value-emitting symbols because verbatimModuleSyntax is on in tsconfig.base.json.
+export { MEMORY_AUDIT_ACTION_KINDS, MEMORY_EDGE_KINDS, MEMORY_SCHEMA_VERSION, MEMORY_SCOPE_KINDS, MEMORY_SENSITIVITIES, MEMORY_SOURCE_KINDS, MEMORY_STATUSES, MEMORY_STATUS_TRANSITIONS, MEMORY_TYPES, } from "./memory.js";
+export { MEMORY_STRUCTURED_PAYLOAD_KINDS } from "./memory-records.js";
+export { MEMORY_AUDIT_INITIATOR_SURFACES, MEMORY_UPDATE_FIELDS } from "./memory-operations.js";
+export { checkStatusTransition, hasStaleModelMetadata, looksLikeSecretShape, validateMemoryEdge, validateMemoryProvenance, validateMemoryScope, validateMemoryStructuredPayload, validateMemoryValidityInterval, } from "./memory-validation.js";
+// ─── Operation validators ─────────────────────────────────────────────────────
+export { validateMemoryAcceptance, validateMemoryArchive, validateMemoryForget, validateMemoryPin, validateMemoryProposal, validateMemoryRejection, validateMemorySupersession, validateMemoryUnpin, validateMemoryUpdate, } from "./memory-operations-validation.js";
+// ─── Retrieval validator + scope reachability ────────────────────────────────
+export { isScopeReachable, validateMemoryRetrievalRequest } from "./memory-retrieval-validation.js";
+// ─── Audit record validator ──────────────────────────────────────────────────
+export { validateMemoryAuditRecord } from "./memory-audit-validation.js";
+export { MEMORY_AUDIT_EVENT_KINDS, MEMORY_AUDIT_EVENT_SCHEMA_VERSION, MEMORY_AUDIT_EVENT_SUMMARY_MAX_CHARS, } from "./memory-audit-events.js";
+// ─── Record validators + discriminator helpers ────────────────────────────────
+export { assertNeverMemoryType, isMemoryEdge, isMemoryRecord, validateMemoryRecord, } from "./memory-record-validation.js";

package/dist/memory-internal.d.ts

@@ -0,0 +1,26 @@
+export declare const MEMORY_BODY_MAX_CHARS = 4096;
+export declare const MEMORY_RATIONALE_MAX_CHARS = 1024;
+export declare const MEMORY_REASON_MAX_CHARS = 1024;
+export declare const MEMORY_TAG_MAX_CHARS = 64;
+export declare const MEMORY_TAGS_MAX_COUNT = 32;
+export declare const MEMORY_SUMMARY_MAX_CHARS = 512;
+export declare const FORBIDDEN_CONTROL_RE: RegExp;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function isNonEmptyTrimmedString(value: unknown): value is string;
+export declare function isFiniteNonNegativeNumber(value: unknown): value is number;
+export declare function isFinitePositiveInteger(value: unknown): value is number;
+export declare function isUnitInterval(value: unknown): value is number;
+export declare function isStringArray(value: unknown): value is readonly string[];
+export declare function isMember<T extends string>(value: unknown, allowed: readonly T[]): value is T;
+export declare function isSafeText(value: unknown, maxChars: number): value is string;
+export declare function validateTags(field: string, input: unknown, errors: string[]): void;
+export declare function validateRetentionHint(field: string, input: unknown, errors: string[]): void;
+export declare function validateOptionalReference(field: string, value: unknown, errors: string[]): void;
+export interface NestedValidation {
+    readonly ok: boolean;
+    readonly errors?: readonly string[];
+}
+export declare function pushNestedErrors(prefix: string, result: NestedValidation, errors: string[]): void;
+export declare function validateMemoryIdString(field: string, value: unknown, errors: string[]): void;
+export declare function validateSchemaVersionLiteral(input: Record<string, unknown>, errors: string[]): void;
+//# sourceMappingURL=memory-internal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory-internal.d.ts","sourceRoot":"","sources":["../src/memory-internal.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAC1C,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAC/C,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAC5C,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,qBAAqB,KAAK,CAAC;AACxC,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAK5C,eAAO,MAAM,oBAAoB,QAAqC,CAAC;AAEvE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEvE;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEzE;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEvE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE9D;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,MAAM,EAAE,CAExE;AAED,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC,CAE5F;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,IAAI,MAAM,CAQ5E;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAelF;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAc3F;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAO/F;AAKD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAOjG;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAI5F;AAED,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,MAAM,EAAE,MAAM,EAAE,GACf,IAAI,CAIN"}

package/dist/memory-internal.js

@@ -0,0 +1,104 @@
+// Internal helpers shared by the memory contract validators (Epic #204, Issue #205).
+// NOT part of the public package surface. Other validator modules in this directory
+// import from here so primitive guards, bounded-text caps, and the control-character
+// safety gate stay defined exactly once.
+// Bounded text caps. Chosen to keep audit summaries and rationales safe to ship to a
+// browser surface without truncation, and to keep the body cap aligned with a comfortable
+// MemoriaViva card without scrolling.
+export const MEMORY_BODY_MAX_CHARS = 4096;
+export const MEMORY_RATIONALE_MAX_CHARS = 1024;
+export const MEMORY_REASON_MAX_CHARS = 1024;
+export const MEMORY_TAG_MAX_CHARS = 64;
+export const MEMORY_TAGS_MAX_COUNT = 32;
+export const MEMORY_SUMMARY_MAX_CHARS = 512;
+// Intentional control-range match — this is the safety gate. `no-control-regex` guards
+// against accidental matches, not deliberate ones.
+// eslint-disable-next-line no-control-regex
+export const FORBIDDEN_CONTROL_RE = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/;
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function isNonEmptyTrimmedString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+export function isFiniteNonNegativeNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+export function isFinitePositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+export function isUnitInterval(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+export function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+export function isMember(value, allowed) {
+    return typeof value === "string" && allowed.includes(value);
+}
+export function isSafeText(value, maxChars) {
+    if (typeof value !== "string") {
+        return false;
+    }
+    if (value.length === 0 || value.length > maxChars) {
+        return false;
+    }
+    return !FORBIDDEN_CONTROL_RE.test(value);
+}
+export function validateTags(field, input, errors) {
+    if (!isStringArray(input)) {
+        errors.push(`${field} must be a string array`);
+        return;
+    }
+    if (input.length > MEMORY_TAGS_MAX_COUNT) {
+        errors.push(`${field} must have at most ${String(MEMORY_TAGS_MAX_COUNT)} entries`);
+        return;
+    }
+    for (const tag of input) {
+        if (tag.length === 0 || tag.length > MEMORY_TAG_MAX_CHARS || FORBIDDEN_CONTROL_RE.test(tag)) {
+            errors.push(`${field} entry must be a non-empty bounded control-free string`);
+            return;
+        }
+    }
+}
+export function validateRetentionHint(field, input, errors) {
+    if (!isRecord(input)) {
+        errors.push(`${field} must be an object when set`);
+        return;
+    }
+    if (!isNonEmptyTrimmedString(input.policyKey)) {
+        errors.push(`${field}.policyKey must be a non-empty string`);
+    }
+    if (input.retainUntil !== undefined && !isFiniteNonNegativeNumber(input.retainUntil)) {
+        errors.push(`${field}.retainUntil must be a finite non-negative number when set`);
+    }
+    if (input.notes !== undefined && !isSafeText(input.notes, MEMORY_REASON_MAX_CHARS)) {
+        errors.push(`${field}.notes must be a bounded control-free string when set`);
+    }
+}
+export function validateOptionalReference(field, value, errors) {
+    if (value === undefined) {
+        return;
+    }
+    if (!isNonEmptyTrimmedString(value)) {
+        errors.push(`${field} must be a non-empty string when set`);
+    }
+}
+export function pushNestedErrors(prefix, result, errors) {
+    if (result.ok) {
+        return;
+    }
+    for (const reason of result.errors ?? []) {
+        errors.push(`${prefix}.${reason}`);
+    }
+}
+export function validateMemoryIdString(field, value, errors) {
+    if (!isNonEmptyTrimmedString(value)) {
+        errors.push(`${field} must be a non-empty string`);
+    }
+}
+export function validateSchemaVersionLiteral(input, errors) {
+    if (input.schemaVersion !== "1") {
+        errors.push('schemaVersion must be the literal "1"');
+    }
+}

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

@@ -0,0 +1,12 @@
+import type { MemoryAcceptance, MemoryArchive, MemoryForget, MemoryPin, MemoryProposal, MemoryRejection, MemorySupersession, MemoryUnpin, MemoryUpdate } from "./memory-operations.js";
+import { type MemoryValidation } from "./memory-validation.js";
+export declare function validateMemoryProposal(input: unknown): MemoryValidation<MemoryProposal>;
+export declare function validateMemoryAcceptance(input: unknown): MemoryValidation<MemoryAcceptance>;
+export declare function validateMemoryRejection(input: unknown): MemoryValidation<MemoryRejection>;
+export declare function validateMemoryUpdate(input: unknown): MemoryValidation<MemoryUpdate>;
+export declare function validateMemorySupersession(input: unknown): MemoryValidation<MemorySupersession>;
+export declare function validateMemoryPin(input: unknown): MemoryValidation<MemoryPin>;
+export declare function validateMemoryUnpin(input: unknown): MemoryValidation<MemoryUnpin>;
+export declare function validateMemoryArchive(input: unknown): MemoryValidation<MemoryArchive>;
+export declare function validateMemoryForget(input: unknown): MemoryValidation<MemoryForget>;
+//# sourceMappingURL=memory-operations-validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory-operations-validation.d.ts","sourceRoot":"","sources":["../src/memory-operations-validation.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,SAAS,EACT,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,WAAW,EACX,YAAY,EACb,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAKL,KAAK,gBAAgB,EACtB,MAAM,wBAAwB,CAAC;AAoChC,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAAC,cAAc,CAAC,CAyBvF;AA0BD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAAC,gBAAgB,CAAC,CAiB3F;AAGD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAAC,eAAe,CAAC,CAkBzF;AAgDD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAAC,YAAY,CAAC,CAyBnF;AAGD,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAAC,kBAAkB,CAAC,CA6B/F;AA2BD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAE7E;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAEjF;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAAC,aAAa,CAAC,CAkBrF;AAMD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAAC,YAAY,CAAC,CAqBnF"}