@lucern/graph-primitives 0.1.0-alpha.2

package/dist/ontologyDefinitions.js

@@ -0,0 +1,635 @@
+import { v } from 'convex/values';
+import { componentsGeneric, queryGeneric, mutationGeneric } from 'convex/server';
+
+// src/ontologyDefinitions.ts
+
+// ../access-control/src/auth.ts
+async function getCurrentUserId(ctx) {
+  const identity = await ctx.auth.getUserIdentity();
+  return identity?.subject ?? null;
+}
+var permissiveReturn = v.optional(v.any());
+var looseJsonObject = v.record(v.string(), v.any());
+var looseJsonArray = v.array(v.any());
+v.union(
+  v.string(),
+  v.number(),
+  v.boolean(),
+  v.null(),
+  looseJsonObject,
+  looseJsonArray
+);
+componentsGeneric();
+var mutation = mutationGeneric;
+var query = queryGeneric;
+
+// src/ontologyHelpers.ts
+var ONTOLOGY_KEY_REGEX = /^[a-z][a-z0-9-]*[a-z0-9]$/;
+function validateOntologyKey(key) {
+  const normalized = key.trim().toLowerCase();
+  if (normalized.length < 2) {
+    return {
+      valid: false,
+      normalized,
+      error: "Ontology key must be at least 2 characters."
+    };
+  }
+  if (normalized.length > 64) {
+    return {
+      valid: false,
+      normalized,
+      error: "Ontology key must be at most 64 characters."
+    };
+  }
+  if (!ONTOLOGY_KEY_REGEX.test(normalized)) {
+    return {
+      valid: false,
+      normalized,
+      error: "Ontology key must start with a letter, contain only lowercase letters, digits, and hyphens, and not end with a hyphen."
+    };
+  }
+  return { valid: true, normalized };
+}
+function validateVersionString(version) {
+  return /^\d+\.\d+\.\d+$/.test(version);
+}
+function mergeOntologyLayers(parent, child, parentKey, childKey) {
+  const entityMap = /* @__PURE__ */ new Map();
+  for (const et of parent.entityTypes) {
+    entityMap.set(et.value, et);
+  }
+  for (const et of child.entityTypes) {
+    entityMap.set(et.value, et);
+  }
+  const edgeMap = /* @__PURE__ */ new Map();
+  for (const edge of parent.edgeTypes) {
+    edgeMap.set(edge.value, edge);
+  }
+  for (const edge of child.edgeTypes) {
+    edgeMap.set(edge.value, edge);
+  }
+  return {
+    entityTypes: Array.from(entityMap.values()),
+    edgeTypes: Array.from(edgeMap.values()),
+    layers: [parentKey, childKey]
+  };
+}
+
+// src/ontologyDefinitions.ts
+async function requireAuth(ctx) {
+  const userId = await getCurrentUserId(ctx);
+  if (!userId) {
+    throw new Error("Authentication required.");
+  }
+  return userId;
+}
+async function logAudit(ctx, args) {
+  await ctx.db.insert("epistemicAudit", {
+    entityType: args.entityType,
+    entityId: args.entityId,
+    changeType: args.changeType,
+    changedAt: Date.now(),
+    changedBy: args.changedBy,
+    isAgent: false,
+    previousState: args.previousState ?? null,
+    newState: args.newState ?? null
+  });
+}
+var getOntologyDefinition = query({
+  args: { id: v.id("ontologyDefinitions") },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.id);
+  }
+});
+var getOntologyDefinitionByKey = query({
+  args: {
+    ontologyKey: v.string(),
+    tenantId: v.optional(v.string())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    if (args.tenantId) {
+      return await ctx.db.query("ontologyDefinitions").withIndex(
+        "by_tenant_ontologyKey",
+        (q) => q.eq("tenantId", args.tenantId).eq("ontologyKey", args.ontologyKey)
+      ).first();
+    }
+    return await ctx.db.query("ontologyDefinitions").withIndex(
+      "by_tenant_ontologyKey",
+      (q) => q.eq("tenantId", void 0).eq("ontologyKey", args.ontologyKey)
+    ).first();
+  }
+});
+var listOntologyDefinitions = query({
+  args: {
+    tenantId: v.optional(v.string()),
+    tier: v.optional(
+      v.union(v.literal("platform"), v.literal("pack"), v.literal("tenant"))
+    ),
+    status: v.optional(
+      v.union(
+        v.literal("draft"),
+        v.literal("active"),
+        v.literal("deprecated"),
+        v.literal("archived")
+      )
+    )
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    if (args.tenantId && args.status) {
+      const status = args.status;
+      return await ctx.db.query("ontologyDefinitions").withIndex(
+        "by_tenant_status",
+        (q) => q.eq("tenantId", args.tenantId).eq("status", status)
+      ).collect();
+    }
+    if (args.status) {
+      const status = args.status;
+      return await ctx.db.query("ontologyDefinitions").withIndex("by_status", (q) => q.eq("status", status)).collect();
+    }
+    if (args.tier) {
+      const tier = args.tier;
+      return await ctx.db.query("ontologyDefinitions").withIndex("by_tier", (q) => q.eq("tier", tier)).collect();
+    }
+    return await ctx.db.query("ontologyDefinitions").collect();
+  }
+});
+var getOntologyVersion = query({
+  args: {
+    ontologyKey: v.string(),
+    version: v.string()
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    return await ctx.db.query("ontologyVersions").withIndex(
+      "by_ontologyKey_version",
+      (q) => q.eq("ontologyKey", args.ontologyKey).eq("version", args.version)
+    ).first();
+  }
+});
+var listOntologyVersions = query({
+  args: {
+    ontologyId: v.id("ontologyDefinitions"),
+    status: v.optional(
+      v.union(
+        v.literal("draft"),
+        v.literal("published"),
+        v.literal("deprecated")
+      )
+    )
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const all = await ctx.db.query("ontologyVersions").withIndex("by_ontologyId", (q) => q.eq("ontologyId", args.ontologyId)).collect();
+    if (args.status) {
+      return all.filter((versionDoc) => versionDoc.status === args.status);
+    }
+    return all;
+  }
+});
+var getPublishedVersion = query({
+  args: { ontologyId: v.id("ontologyDefinitions") },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const published = await ctx.db.query("ontologyVersions").withIndex("by_ontologyId", (q) => q.eq("ontologyId", args.ontologyId)).collect();
+    const publishedOnly = published.filter(
+      (versionDoc) => versionDoc.status === "published"
+    );
+    if (publishedOnly.length === 0) {
+      return null;
+    }
+    publishedOnly.sort((a, b) => (b.publishedAt ?? 0) - (a.publishedAt ?? 0));
+    return publishedOnly[0];
+  }
+});
+var resolveEffectiveOntology = query({
+  args: { ontologyId: v.id("ontologyDefinitions") },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const MAX_DEPTH = 3;
+    const chain = [];
+    let currentId = args.ontologyId;
+    for (let depth = 0; depth < MAX_DEPTH && currentId; depth++) {
+      const ontologyId = currentId;
+      const def = await ctx.db.get(ontologyId);
+      if (!def) {
+        break;
+      }
+      const defTyped = def;
+      const versions = await ctx.db.query("ontologyVersions").withIndex("by_ontologyId", (q) => q.eq("ontologyId", ontologyId)).collect();
+      const published = versions.filter((ver) => ver.status === "published").sort(
+        (a, b) => (b.publishedAt ?? 0) - (a.publishedAt ?? 0)
+      );
+      chain.unshift({
+        def: defTyped,
+        version: published[0] ?? null
+      });
+      currentId = defTyped.parentOntologyId;
+    }
+    if (chain.length === 0) {
+      return null;
+    }
+    let merged = {
+      entityTypes: [],
+      edgeTypes: [],
+      layers: []
+    };
+    for (const { def, version } of chain) {
+      if (!version) {
+        merged.layers.push(def.ontologyKey);
+        continue;
+      }
+      const previousLayerKey = merged.layers.at(-1) ?? def.ontologyKey;
+      merged = mergeOntologyLayers(
+        merged,
+        {
+          entityTypes: version.entityTypes,
+          edgeTypes: version.edgeTypes
+        },
+        previousLayerKey,
+        def.ontologyKey
+      );
+    }
+    return merged;
+  }
+});
+var createOntologyDefinition = mutation({
+  args: {
+    ontologyKey: v.string(),
+    name: v.string(),
+    description: v.optional(v.string()),
+    tenantId: v.optional(v.string()),
+    tier: v.union(
+      v.literal("platform"),
+      v.literal("pack"),
+      v.literal("tenant")
+    ),
+    parentOntologyId: v.optional(v.id("ontologyDefinitions"))
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const userId = await requireAuth(ctx);
+    const keyResult = validateOntologyKey(args.ontologyKey);
+    if (!keyResult.valid) {
+      throw new Error(keyResult.error ?? "Invalid ontology key");
+    }
+    const existing = await ctx.db.query("ontologyDefinitions").withIndex(
+      "by_tenant_ontologyKey",
+      (q) => q.eq("tenantId", args.tenantId).eq("ontologyKey", keyResult.normalized)
+    ).first();
+    if (existing) {
+      throw new Error(
+        `Ontology "${keyResult.normalized}" already exists for tenant ${args.tenantId ?? "(platform)"}.`
+      );
+    }
+    if (args.parentOntologyId) {
+      const parent = await ctx.db.get(args.parentOntologyId);
+      if (!parent) {
+        throw new Error("Parent ontology definition not found.");
+      }
+    }
+    const now = Date.now();
+    const id = await ctx.db.insert("ontologyDefinitions", {
+      ontologyKey: keyResult.normalized,
+      name: args.name,
+      description: args.description,
+      tenantId: args.tenantId,
+      tier: args.tier,
+      parentOntologyId: args.parentOntologyId,
+      status: "draft",
+      createdBy: userId,
+      createdAt: now,
+      updatedAt: now
+    });
+    await logAudit(ctx, {
+      entityType: "ontologyDefinition",
+      entityId: id,
+      changeType: "created",
+      changedBy: userId,
+      previousState: null,
+      newState: {
+        ontologyKey: keyResult.normalized,
+        name: args.name,
+        tier: args.tier
+      }
+    });
+    return { id, ontologyKey: keyResult.normalized };
+  }
+});
+var updateOntologyDefinition = mutation({
+  args: {
+    id: v.id("ontologyDefinitions"),
+    name: v.optional(v.string()),
+    description: v.optional(v.string()),
+    status: v.optional(
+      v.union(v.literal("draft"), v.literal("active"), v.literal("deprecated"))
+    )
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const userId = await requireAuth(ctx);
+    const def = await ctx.db.get(args.id);
+    if (!def) {
+      throw new Error("Ontology definition not found.");
+    }
+    if (def.status === "archived") {
+      throw new Error("Cannot update an archived ontology definition.");
+    }
+    const previousState = {
+      name: def.name,
+      description: def.description,
+      status: def.status
+    };
+    const patch = { updatedAt: Date.now() };
+    if (args.name !== void 0) {
+      patch.name = args.name;
+    }
+    if (args.description !== void 0) {
+      patch.description = args.description;
+    }
+    if (args.status !== void 0) {
+      patch.status = args.status;
+    }
+    await ctx.db.patch(args.id, patch);
+    await logAudit(ctx, {
+      entityType: "ontologyDefinition",
+      entityId: args.id,
+      changeType: "updated",
+      changedBy: userId,
+      previousState,
+      newState: patch
+    });
+    return { success: true };
+  }
+});
+var archiveOntologyDefinition = mutation({
+  args: { id: v.id("ontologyDefinitions") },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const userId = await requireAuth(ctx);
+    const def = await ctx.db.get(args.id);
+    if (!def) {
+      throw new Error("Ontology definition not found.");
+    }
+    if (def.status === "archived") {
+      return { success: true };
+    }
+    await ctx.db.patch(args.id, { status: "archived", updatedAt: Date.now() });
+    await logAudit(ctx, {
+      entityType: "ontologyDefinition",
+      entityId: args.id,
+      changeType: "archived",
+      changedBy: userId,
+      previousState: { status: def.status },
+      newState: { status: "archived" }
+    });
+    return { success: true };
+  }
+});
+var createOntologyVersion = mutation({
+  args: {
+    ontologyId: v.id("ontologyDefinitions"),
+    version: v.string(),
+    entityTypes: v.array(
+      v.object({
+        value: v.string(),
+        label: v.string(),
+        description: v.optional(v.string()),
+        schema: v.optional(v.any()),
+        subtypes: v.optional(
+          v.array(
+            v.object({
+              value: v.string(),
+              label: v.string(),
+              description: v.optional(v.string())
+            })
+          )
+        )
+      })
+    ),
+    edgeTypes: v.array(
+      v.object({
+        value: v.string(),
+        label: v.string(),
+        description: v.optional(v.string()),
+        sourceTypes: v.optional(v.array(v.string())),
+        targetTypes: v.optional(v.array(v.string())),
+        constraintSeverity: v.optional(
+          v.union(v.literal("warn"), v.literal("info"))
+        )
+      })
+    ),
+    releaseNotes: v.optional(v.string())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const userId = await requireAuth(ctx);
+    if (!validateVersionString(args.version)) {
+      throw new Error(
+        `Invalid version string "${args.version}". Must be in X.Y.Z format.`
+      );
+    }
+    const def = await ctx.db.get(args.ontologyId);
+    if (!def) {
+      throw new Error("Ontology definition not found.");
+    }
+    if (def.status === "archived") {
+      throw new Error("Cannot add versions to an archived ontology.");
+    }
+    const existing = await ctx.db.query("ontologyVersions").withIndex(
+      "by_ontologyKey_version",
+      (q) => q.eq("ontologyKey", def.ontologyKey).eq("version", args.version)
+    ).first();
+    if (existing) {
+      throw new Error(
+        `Version "${args.version}" already exists for ontology "${def.ontologyKey}".`
+      );
+    }
+    const now = Date.now();
+    const id = await ctx.db.insert("ontologyVersions", {
+      ontologyId: args.ontologyId,
+      ontologyKey: def.ontologyKey,
+      version: args.version,
+      status: "draft",
+      entityTypes: args.entityTypes,
+      edgeTypes: args.edgeTypes,
+      releaseNotes: args.releaseNotes,
+      createdAt: now
+    });
+    await logAudit(ctx, {
+      entityType: "ontologyVersion",
+      entityId: id,
+      changeType: "created",
+      changedBy: userId,
+      previousState: null,
+      newState: {
+        ontologyKey: def.ontologyKey,
+        version: args.version,
+        entityTypeCount: args.entityTypes.length,
+        edgeTypeCount: args.edgeTypes.length
+      }
+    });
+    return { id, version: args.version };
+  }
+});
+var updateDraftVersion = mutation({
+  args: {
+    id: v.id("ontologyVersions"),
+    entityTypes: v.optional(
+      v.array(
+        v.object({
+          value: v.string(),
+          label: v.string(),
+          description: v.optional(v.string()),
+          schema: v.optional(v.any()),
+          subtypes: v.optional(
+            v.array(
+              v.object({
+                value: v.string(),
+                label: v.string(),
+                description: v.optional(v.string())
+              })
+            )
+          )
+        })
+      )
+    ),
+    edgeTypes: v.optional(
+      v.array(
+        v.object({
+          value: v.string(),
+          label: v.string(),
+          description: v.optional(v.string()),
+          sourceTypes: v.optional(v.array(v.string())),
+          targetTypes: v.optional(v.array(v.string())),
+          constraintSeverity: v.optional(
+            v.union(v.literal("warn"), v.literal("info"))
+          )
+        })
+      )
+    ),
+    releaseNotes: v.optional(v.string())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const userId = await requireAuth(ctx);
+    const ver = await ctx.db.get(args.id);
+    if (!ver) {
+      throw new Error("Ontology version not found.");
+    }
+    if (ver.status !== "draft") {
+      throw new Error(
+        `Cannot update a ${ver.status} version. Only draft versions are editable.`
+      );
+    }
+    const patch = {};
+    if (args.entityTypes !== void 0) {
+      patch.entityTypes = args.entityTypes;
+    }
+    if (args.edgeTypes !== void 0) {
+      patch.edgeTypes = args.edgeTypes;
+    }
+    if (args.releaseNotes !== void 0) {
+      patch.releaseNotes = args.releaseNotes;
+    }
+    await ctx.db.patch(args.id, patch);
+    await logAudit(ctx, {
+      entityType: "ontologyVersion",
+      entityId: args.id,
+      changeType: "updated",
+      changedBy: userId,
+      previousState: { status: ver.status },
+      newState: patch
+    });
+    return { success: true };
+  }
+});
+var publishOntologyVersion = mutation({
+  args: {
+    id: v.id("ontologyVersions"),
+    ontologyId: v.optional(v.id("ontologyDefinitions"))
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const userId = await requireAuth(ctx);
+    const ver = await ctx.db.get(args.id);
+    if (!ver) {
+      throw new Error("Ontology version not found.");
+    }
+    if (args.ontologyId && ver.ontologyId !== args.ontologyId) {
+      throw new Error(
+        "Version does not belong to the specified ontology definition."
+      );
+    }
+    if (ver.status !== "draft") {
+      throw new Error(
+        `Cannot publish a ${ver.status} version. Only draft versions can be published.`
+      );
+    }
+    const now = Date.now();
+    await ctx.db.patch(args.id, {
+      status: "published",
+      publishedBy: userId,
+      publishedAt: now
+    });
+    const def = await ctx.db.get(ver.ontologyId);
+    if (def && def.status === "draft") {
+      await ctx.db.patch(ver.ontologyId, {
+        status: "active",
+        updatedAt: now
+      });
+    }
+    await logAudit(ctx, {
+      entityType: "ontologyVersion",
+      entityId: args.id,
+      changeType: "published",
+      changedBy: userId,
+      previousState: { status: "draft" },
+      newState: { status: "published", publishedAt: now }
+    });
+    return { success: true, publishedAt: now };
+  }
+});
+var deprecateOntologyVersion = mutation({
+  args: {
+    id: v.id("ontologyVersions"),
+    ontologyId: v.optional(v.id("ontologyDefinitions"))
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const userId = await requireAuth(ctx);
+    const ver = await ctx.db.get(args.id);
+    if (!ver) {
+      throw new Error("Ontology version not found.");
+    }
+    if (args.ontologyId && ver.ontologyId !== args.ontologyId) {
+      throw new Error(
+        "Version does not belong to the specified ontology definition."
+      );
+    }
+    if (ver.status === "deprecated") {
+      return { success: true };
+    }
+    if (ver.status !== "published") {
+      throw new Error(
+        `Cannot deprecate a ${ver.status} version. Only published versions can be deprecated.`
+      );
+    }
+    await ctx.db.patch(args.id, { status: "deprecated" });
+    await logAudit(ctx, {
+      entityType: "ontologyVersion",
+      entityId: args.id,
+      changeType: "deprecated",
+      changedBy: userId,
+      previousState: { status: "published" },
+      newState: { status: "deprecated" }
+    });
+    return { success: true };
+  }
+});
+
+export { archiveOntologyDefinition, createOntologyDefinition, createOntologyVersion, deprecateOntologyVersion, getOntologyDefinition, getOntologyDefinitionByKey, getOntologyVersion, getPublishedVersion, listOntologyDefinitions, listOntologyVersions, publishOntologyVersion, resolveEffectiveOntology, updateDraftVersion, updateOntologyDefinition };
+//# sourceMappingURL=ontologyDefinitions.js.map
+//# sourceMappingURL=ontologyDefinitions.js.map