@opengeni/db 0.17.1 → 0.19.0

package/src/memory-domain.ts

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import type { KnowledgeMemoryKind } from "@opengeni/contracts";
+import { stableJson, type KnowledgeMemoryKind } from "@opengeni/contracts";
 
 // Workspace Memory V1 — pure domain logic (gates + render + canonical prompt
 // text). No database access: everything here is unit-testable in isolation and
@@ -32,6 +32,365 @@ export const MEMORY_SEARCH_MAX_LIMIT = 20;
 /** Statuses an agent may see: active (agent-written) ∪ approved (curated). */
 export const AGENT_VISIBLE_MEMORY_STATUSES = ["active", "approved"] as const;
 
+/** Maximum normalized label length. Labels are relevance hints, never authority. */
+export const MEMORY_LABEL_MAX_CHARS = 64;
+/** Maximum labels stored on one memory. */
+export const MEMORY_LABEL_MAX_COUNT = 16;
+/** Maximum normalized namespace length, including hierarchy separators. */
+export const MEMORY_NAMESPACE_MAX_CHARS = 128;
+/** Maximum normalized durable-role key length. */
+export const MEMORY_ROLE_KEY_MAX_CHARS = 64;
+/** Maximum subject identifier length stored in typed scope/authority columns. */
+export const MEMORY_SUBJECT_ID_MAX_CHARS = 1024;
+
+const MEMORY_SELECTOR_SEGMENT_PATTERN = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+export type MemoryScopeType = "workspace" | "user" | "role" | "session" | "ephemeral" | "legacy";
+
+export type MemoryScopeSpec =
+  | { type: "workspace" }
+  | { type: "user"; subjectId: string }
+  | { type: "role"; roleKey: string }
+  | { type: "session"; sessionId: string }
+  | { type: "ephemeral"; sessionId: string; validUntil: string }
+  | { type: "legacy"; legacyScope: string };
+
+export type MemoryRelationshipType =
+  | "derived_from"
+  | "supersedes"
+  | "corrects"
+  | "conflicts_with"
+  | "related_to"
+  | "depends_on"
+  | "applies_to";
+
+export const MEMORY_RELATIONSHIP_TYPES = [
+  "derived_from",
+  "supersedes",
+  "corrects",
+  "conflicts_with",
+  "related_to",
+  "depends_on",
+  "applies_to",
+] as const satisfies readonly MemoryRelationshipType[];
+
+const SYMMETRIC_MEMORY_RELATIONSHIPS = new Set<MemoryRelationshipType>([
+  "conflicts_with",
+  "related_to",
+]);
+
+export type MemoryOperationType =
+  | "reclassify"
+  | "archive"
+  | "relationship_add"
+  | "relationship_remove"
+  | "supersede"
+  | "correct";
+
+type MemoryOperationPlanBase = {
+  operationId: string;
+  operationType: MemoryOperationType;
+  targetMemoryId: string;
+  expectedTargetVersion: number;
+};
+
+export type MemoryOperationPlan =
+  | (MemoryOperationPlanBase & {
+      operationType: "reclassify";
+      scope: MemoryScopeSpec;
+      namespace: string;
+      labels: string[];
+    })
+  | (MemoryOperationPlanBase & { operationType: "archive" })
+  | (MemoryOperationPlanBase & {
+      operationType: "relationship_add" | "relationship_remove";
+      relatedMemoryId: string;
+      expectedRelatedVersion: number;
+      relationshipType: MemoryRelationshipType;
+    })
+  | (MemoryOperationPlanBase & {
+      operationType: "supersede" | "correct";
+      relatedMemoryId: string;
+      expectedRelatedVersion: number;
+    });
+
+export type MemoryOperationPlanInput =
+  | (Omit<MemoryOperationPlanBase, "operationType"> & {
+      operationType: "reclassify";
+      scope: MemoryScopeSpec;
+      namespace?: string | null;
+      labels?: readonly string[] | null;
+    })
+  | (Omit<MemoryOperationPlanBase, "operationType"> & { operationType: "archive" })
+  | (Omit<MemoryOperationPlanBase, "operationType"> & {
+      operationType: "relationship_add" | "relationship_remove";
+      relatedMemoryId: string;
+      expectedRelatedVersion: number;
+      relationshipType: MemoryRelationshipType;
+    })
+  | (Omit<MemoryOperationPlanBase, "operationType"> & {
+      operationType: "supersede" | "correct";
+      relatedMemoryId: string;
+      expectedRelatedVersion: number;
+    });
+
+export type MemoryRevertPlan = {
+  operationId: string;
+  appliedOperationId: string;
+};
+
+export type MemoryRevertPlanInput = MemoryRevertPlan;
+
+function normalizeSelectorSegment(value: string, label: string): string {
+  const normalized = value.trim().toLowerCase().replace(/\s+/g, "-");
+  if (!MEMORY_SELECTOR_SEGMENT_PATTERN.test(normalized)) {
+    throw new Error(
+      `${label} must be a lowercase slug using letters, numbers, dot, underscore, or dash`,
+    );
+  }
+  return normalized;
+}
+
+function normalizeUuid(value: string, label: string): string {
+  const normalized = value.trim().toLowerCase();
+  if (!UUID_PATTERN.test(normalized)) {
+    throw new Error(`${label} must be a UUID`);
+  }
+  return normalized;
+}
+
+function normalizePositiveVersion(value: number, label: string): number {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(`${label} must be a positive safe integer`);
+  }
+  return value;
+}
+
+/** Normalize one bounded memory label. Invalid selectors fail closed. */
+export function normalizeMemoryLabel(label: string): string {
+  const normalized = normalizeSelectorSegment(label, "memory label");
+  if (normalized.length > MEMORY_LABEL_MAX_CHARS) {
+    throw new Error(`memory label exceeds ${MEMORY_LABEL_MAX_CHARS} characters`);
+  }
+  return normalized;
+}
+
+/** Normalize, de-duplicate, sort, and bound memory labels deterministically. */
+export function normalizeMemoryLabels(labels: readonly string[] | null | undefined): string[] {
+  const normalized = new Set((labels ?? []).map(normalizeMemoryLabel));
+  if (normalized.size > MEMORY_LABEL_MAX_COUNT) {
+    throw new Error(`memory labels exceed the ${MEMORY_LABEL_MAX_COUNT}-label limit`);
+  }
+  return [...normalized].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+}
+
+/** Normalize a hierarchical namespace such as `engineering/backend`. */
+export function normalizeMemoryNamespace(namespace: string | null | undefined): string {
+  const raw = namespace?.trim() || "general";
+  const normalized = raw
+    .split("/")
+    .map((segment) => normalizeSelectorSegment(segment, "memory namespace segment"))
+    .join("/");
+  if (normalized.length > MEMORY_NAMESPACE_MAX_CHARS) {
+    throw new Error(`memory namespace exceeds ${MEMORY_NAMESPACE_MAX_CHARS} characters`);
+  }
+  return normalized;
+}
+
+export function normalizeMemoryRoleKey(roleKey: string): string {
+  const normalized = normalizeSelectorSegment(roleKey, "memory role key");
+  if (normalized.length > MEMORY_ROLE_KEY_MAX_CHARS) {
+    throw new Error(`memory role key exceeds ${MEMORY_ROLE_KEY_MAX_CHARS} characters`);
+  }
+  return normalized;
+}
+
+export function normalizeMemoryScope(scope: MemoryScopeSpec): MemoryScopeSpec {
+  switch (scope.type) {
+    case "workspace":
+      return { type: "workspace" };
+    case "user": {
+      const subjectId = scope.subjectId.trim();
+      if (!subjectId || subjectId.length > MEMORY_SUBJECT_ID_MAX_CHARS) {
+        throw new Error(
+          `memory user scope requires a subject id of at most ${MEMORY_SUBJECT_ID_MAX_CHARS} characters`,
+        );
+      }
+      return { type: "user", subjectId };
+    }
+    case "role":
+      return { type: "role", roleKey: normalizeMemoryRoleKey(scope.roleKey) };
+    case "session":
+      return { type: "session", sessionId: normalizeUuid(scope.sessionId, "memory session id") };
+    case "ephemeral": {
+      const validUntil = new Date(scope.validUntil);
+      if (!Number.isFinite(validUntil.getTime())) {
+        throw new Error("ephemeral memory scope requires a valid expiry timestamp");
+      }
+      return {
+        type: "ephemeral",
+        sessionId: normalizeUuid(scope.sessionId, "ephemeral memory session id"),
+        validUntil: validUntil.toISOString(),
+      };
+    }
+    case "legacy": {
+      const legacyScope = scope.legacyScope.trim();
+      if (!legacyScope || legacyScope.length > MEMORY_NAMESPACE_MAX_CHARS) {
+        throw new Error("legacy memory scope must be a non-empty bounded string");
+      }
+      return { type: "legacy", legacyScope };
+    }
+  }
+}
+
+export function isMemoryScopeApplicable(
+  scope: MemoryScopeSpec,
+  context: {
+    subjectId?: string | null;
+    roleKey?: string | null;
+    sessionId?: string | null;
+    now?: Date | string;
+  },
+): boolean {
+  const normalized = normalizeMemoryScope(scope);
+  switch (normalized.type) {
+    case "workspace":
+      return true;
+    case "user":
+      return Boolean(context.subjectId) && normalized.subjectId === context.subjectId;
+    case "role":
+      return (
+        Boolean(context.roleKey) && normalized.roleKey === normalizeMemoryRoleKey(context.roleKey!)
+      );
+    case "session":
+      return Boolean(context.sessionId) && normalized.sessionId === context.sessionId;
+    case "ephemeral": {
+      if (!context.sessionId || normalized.sessionId !== context.sessionId) return false;
+      const now = context.now instanceof Date ? context.now : new Date(context.now ?? Date.now());
+      return Number.isFinite(now.getTime()) && now.getTime() < Date.parse(normalized.validUntil);
+    }
+    case "legacy":
+      return false;
+  }
+}
+
+export function canonicalMemoryRelationship(input: {
+  sourceMemoryId: string;
+  targetMemoryId: string;
+  relationshipType: MemoryRelationshipType;
+}): {
+  sourceMemoryId: string;
+  targetMemoryId: string;
+  relationshipType: MemoryRelationshipType;
+} {
+  const sourceMemoryId = normalizeUuid(input.sourceMemoryId, "source memory id");
+  const targetMemoryId = normalizeUuid(input.targetMemoryId, "target memory id");
+  if (sourceMemoryId === targetMemoryId) {
+    throw new Error("a memory relationship must connect two distinct memories");
+  }
+  if (!(MEMORY_RELATIONSHIP_TYPES as readonly string[]).includes(input.relationshipType)) {
+    throw new Error(`unsupported memory relationship type: ${input.relationshipType}`);
+  }
+  if (
+    SYMMETRIC_MEMORY_RELATIONSHIPS.has(input.relationshipType) &&
+    targetMemoryId < sourceMemoryId
+  ) {
+    return {
+      sourceMemoryId: targetMemoryId,
+      targetMemoryId: sourceMemoryId,
+      relationshipType: input.relationshipType,
+    };
+  }
+  return { sourceMemoryId, targetMemoryId, relationshipType: input.relationshipType };
+}
+
+/** Build the canonical, bounded operation plan consumed by the database lifecycle function. */
+export function normalizeMemoryOperationPlan(input: MemoryOperationPlanInput): MemoryOperationPlan {
+  const base = {
+    operationId: normalizeUuid(input.operationId, "memory operation id"),
+    operationType: input.operationType,
+    targetMemoryId: normalizeUuid(input.targetMemoryId, "target memory id"),
+    expectedTargetVersion: normalizePositiveVersion(
+      input.expectedTargetVersion,
+      "expected target memory version",
+    ),
+  } as const;
+
+  switch (input.operationType) {
+    case "reclassify":
+      return {
+        ...base,
+        operationType: "reclassify",
+        scope: normalizeMemoryScope(input.scope),
+        namespace: normalizeMemoryNamespace(input.namespace),
+        labels: normalizeMemoryLabels(input.labels),
+      };
+    case "archive":
+      return { ...base, operationType: "archive" };
+    case "relationship_add":
+    case "relationship_remove": {
+      const relatedMemoryId = normalizeUuid(input.relatedMemoryId, "related memory id");
+      const expectedRelatedVersion = normalizePositiveVersion(
+        input.expectedRelatedVersion,
+        "expected related memory version",
+      );
+      const relationship = canonicalMemoryRelationship({
+        sourceMemoryId: base.targetMemoryId,
+        targetMemoryId: relatedMemoryId,
+        relationshipType: input.relationshipType,
+      });
+      const endpointsWereSwapped = relationship.sourceMemoryId !== base.targetMemoryId;
+      return {
+        ...base,
+        operationType: input.operationType,
+        targetMemoryId: relationship.sourceMemoryId,
+        relatedMemoryId: relationship.targetMemoryId,
+        expectedTargetVersion: endpointsWereSwapped
+          ? expectedRelatedVersion
+          : base.expectedTargetVersion,
+        expectedRelatedVersion: endpointsWereSwapped
+          ? base.expectedTargetVersion
+          : expectedRelatedVersion,
+        relationshipType: relationship.relationshipType,
+      };
+    }
+    case "supersede":
+    case "correct": {
+      const relatedMemoryId = normalizeUuid(input.relatedMemoryId, "replacement memory id");
+      if (relatedMemoryId === base.targetMemoryId) {
+        throw new Error("a memory cannot supersede or correct itself");
+      }
+      return {
+        ...base,
+        operationType: input.operationType,
+        relatedMemoryId,
+        expectedRelatedVersion: normalizePositiveVersion(
+          input.expectedRelatedVersion,
+          "expected replacement memory version",
+        ),
+      };
+    }
+  }
+}
+
+/** Stable SHA-256 identity for one already-normalized operation plan. */
+export function hashMemoryOperationPlan(plan: MemoryOperationPlan): string {
+  return createHash("sha256").update(stableJson(plan), "utf8").digest("hex");
+}
+
+export function normalizeMemoryRevertPlan(input: MemoryRevertPlanInput): MemoryRevertPlan {
+  return {
+    operationId: normalizeUuid(input.operationId, "memory revert operation id"),
+    appliedOperationId: normalizeUuid(input.appliedOperationId, "applied memory operation id"),
+  };
+}
+
+/** Stable SHA-256 identity for one already-normalized revert plan. */
+export function hashMemoryRevertPlan(plan: MemoryRevertPlan): string {
+  return createHash("sha256").update(stableJson(plan), "utf8").digest("hex");
+}
+
 // ---------------------------------------------------------------------------
 // Kinds → block sections
 // ---------------------------------------------------------------------------

package/src/memory-governance-schema.ts

@@ -0,0 +1,162 @@
+import { sql } from "drizzle-orm";
+import {
+  check,
+  index,
+  integer,
+  jsonb,
+  pgTable,
+  text,
+  timestamp,
+  uniqueIndex,
+  uuid,
+} from "drizzle-orm/pg-core";
+
+// Foreign keys, immutable-history triggers, and lifecycle-only mutation guards
+// live in migration 0152. Keeping this leaf cycle-free lets schema.ts expose the
+// additive memory governance tables without importing knowledgeMemories here.
+export const knowledgeMemoryRelationships = pgTable(
+  "knowledge_memory_relationships",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id").notNull(),
+    workspaceId: uuid("workspace_id").notNull(),
+    sourceMemoryId: uuid("source_memory_id").notNull(),
+    targetMemoryId: uuid("target_memory_id").notNull(),
+    relationshipType: text("relationship_type").notNull(),
+    version: integer("version").notNull().default(1),
+    createdByEventId: uuid("created_by_event_id").notNull(),
+    removedByEventId: uuid("removed_by_event_id"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    removedAt: timestamp("removed_at", { withTimezone: true }),
+  },
+  (table) => ({
+    activeDirectedEdge: uniqueIndex("knowledge_memory_relationships_active_edge_uq")
+      .on(table.workspaceId, table.sourceMemoryId, table.targetMemoryId, table.relationshipType)
+      .where(sql`${table.removedByEventId} is null`),
+    activeSymmetricEdge: uniqueIndex("knowledge_memory_relationships_active_symmetric_edge_uq")
+      .on(
+        table.workspaceId,
+        table.relationshipType,
+        sql`least(${table.sourceMemoryId}, ${table.targetMemoryId})`,
+        sql`greatest(${table.sourceMemoryId}, ${table.targetMemoryId})`,
+      )
+      .where(
+        sql`${table.removedByEventId} is null and ${table.relationshipType} in ('conflicts_with', 'related_to')`,
+      ),
+    source: index("knowledge_memory_relationships_source_idx").on(
+      table.workspaceId,
+      table.sourceMemoryId,
+      table.createdAt.desc(),
+      table.id,
+    ),
+    target: index("knowledge_memory_relationships_target_idx").on(
+      table.workspaceId,
+      table.targetMemoryId,
+      table.createdAt.desc(),
+      table.id,
+    ),
+    typeValid: check(
+      "knowledge_memory_relationships_type_chk",
+      sql`${table.relationshipType} in ('derived_from', 'supersedes', 'corrects', 'conflicts_with', 'related_to', 'depends_on', 'applies_to')`,
+    ),
+    distinctEndpoints: check(
+      "knowledge_memory_relationships_distinct_chk",
+      sql`${table.sourceMemoryId} <> ${table.targetMemoryId}`,
+    ),
+    versionPositive: check("knowledge_memory_relationships_version_chk", sql`${table.version} > 0`),
+    removedShape: check(
+      "knowledge_memory_relationships_removed_shape_chk",
+      sql`(${table.removedByEventId} is null and ${table.removedAt} is null) or (${table.removedByEventId} is not null and ${table.removedAt} is not null)`,
+    ),
+    workspaceIdentity: uniqueIndex("knowledge_memory_relationships_workspace_id_uq").on(
+      table.workspaceId,
+      table.id,
+    ),
+  }),
+);
+
+export const knowledgeMemoryLifecycleEvents = pgTable(
+  "knowledge_memory_lifecycle_events",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id").notNull(),
+    workspaceId: uuid("workspace_id").notNull(),
+    operationId: uuid("operation_id").notNull(),
+    action: text("action").notNull(),
+    operationType: text("operation_type").notNull(),
+    targetMemoryId: uuid("target_memory_id").notNull(),
+    relatedMemoryId: uuid("related_memory_id"),
+    relationshipId: uuid("relationship_id"),
+    relationshipType: text("relationship_type"),
+    actorKind: text("actor_kind").notNull(),
+    actorSubjectId: text("actor_subject_id").notNull(),
+    actorSessionId: uuid("actor_session_id"),
+    actorTurnId: uuid("actor_turn_id"),
+    actorAttemptId: uuid("actor_attempt_id"),
+    actorExecutionGeneration: integer("actor_execution_generation"),
+    planHash: text("plan_hash").notNull(),
+    beforeState: jsonb("before_state").$type<Record<string, unknown>>().notNull(),
+    afterState: jsonb("after_state").$type<Record<string, unknown>>().notNull(),
+    revertsEventId: uuid("reverts_event_id"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    operationAction: uniqueIndex("knowledge_memory_lifecycle_events_operation_action_uq").on(
+      table.workspaceId,
+      table.operationId,
+      table.action,
+    ),
+    oneRevert: uniqueIndex("knowledge_memory_lifecycle_events_one_revert_uq")
+      .on(table.revertsEventId)
+      .where(sql`${table.revertsEventId} is not null`),
+    targetTimeline: index("knowledge_memory_lifecycle_events_target_timeline_idx").on(
+      table.workspaceId,
+      table.targetMemoryId,
+      table.createdAt.desc(),
+      table.id,
+    ),
+    actorTimeline: index("knowledge_memory_lifecycle_events_actor_timeline_idx").on(
+      table.workspaceId,
+      table.actorKind,
+      table.actorSubjectId,
+      table.createdAt.desc(),
+      table.id,
+    ),
+    actionValid: check(
+      "knowledge_memory_lifecycle_events_action_chk",
+      sql`${table.action} in ('apply', 'revert')`,
+    ),
+    operationValid: check(
+      "knowledge_memory_lifecycle_events_operation_chk",
+      sql`${table.operationType} in ('reclassify', 'archive', 'relationship_add', 'relationship_remove', 'supersede', 'correct')`,
+    ),
+    relationshipShape: check(
+      "knowledge_memory_lifecycle_events_relationship_chk",
+      sql`(${table.operationType} in ('relationship_add', 'relationship_remove', 'supersede', 'correct') and ${table.relatedMemoryId} is not null and ${table.relationshipId} is not null and ${table.relationshipType} is not null) or (${table.operationType} in ('reclassify', 'archive') and ${table.relatedMemoryId} is null and ${table.relationshipId} is null and ${table.relationshipType} is null)`,
+    ),
+    actorValid: check(
+      "knowledge_memory_lifecycle_events_actor_chk",
+      sql`${table.actorKind} in ('subject', 'service') and length(btrim(${table.actorSubjectId})) between 1 and 1024`,
+    ),
+    attemptShape: check(
+      "knowledge_memory_lifecycle_events_attempt_shape_chk",
+      sql`(${table.actorSessionId} is null and ${table.actorTurnId} is null and ${table.actorAttemptId} is null and ${table.actorExecutionGeneration} is null) or (${table.actorSessionId} is not null and ${table.actorTurnId} is not null and ${table.actorAttemptId} is not null and ${table.actorExecutionGeneration} > 0)`,
+    ),
+    planHashShape: check(
+      "knowledge_memory_lifecycle_events_plan_hash_chk",
+      sql`${table.planHash} ~ '^[a-f0-9]{64}$'`,
+    ),
+    stateShape: check(
+      "knowledge_memory_lifecycle_events_state_chk",
+      sql`jsonb_typeof(${table.beforeState}) = 'object' and jsonb_typeof(${table.afterState}) = 'object' and not (${table.beforeState} ?| array['text', 'sourceRefs', 'source_refs', 'metadata', 'embedding']) and not (${table.afterState} ?| array['text', 'sourceRefs', 'source_refs', 'metadata', 'embedding'])`,
+    ),
+    revertShape: check(
+      "knowledge_memory_lifecycle_events_revert_shape_chk",
+      sql`(${table.action} = 'apply' and ${table.revertsEventId} is null) or (${table.action} = 'revert' and ${table.revertsEventId} is not null)`,
+    ),
+    workspaceIdentity: uniqueIndex("knowledge_memory_lifecycle_events_workspace_id_uq").on(
+      table.workspaceId,
+      table.id,
+    ),
+  }),
+);