@ai-matrx/associations 0.3.0 → 0.5.0

package/dist/core/index.js

@@ -423,6 +423,7 @@ var ENTITY_TYPE_METADATA = {
   "platform_actor_session": { token: "platform_actor_session", schema: "platform", table: "actor_session", label: "Actor session", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "platform_actor_token": { token: "platform_actor_token", schema: "platform", table: "actor_token", label: "Actor token", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "platform_actor_token_event": { token: "platform_actor_token_event", schema: "platform", table: "actor_token_event", label: "Actor token event", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
+  "platform_continued_access": { token: "platform_continued_access", schema: "platform", table: "continued_access", label: "Continued Access", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "platform_outcome_event": { token: "platform_outcome_event", schema: "platform", table: "outcome_event", label: "Outcome Event", baseTier: 1, isComponent: false, isModule: false, isListed: true, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "platform_outsider_consumer": { token: "platform_outsider_consumer", schema: "platform", table: "outsider_consumer", label: "Outsider consumer", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "platform_saved_view": { token: "platform_saved_view", schema: "platform", table: "saved_view", label: "Saved view", baseTier: 1, isComponent: false, isModule: false, isListed: true, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
@@ -451,6 +452,7 @@ var ENTITY_TYPE_METADATA = {
   "research_tag": { token: "research_tag", schema: "research", table: "rs_tag", label: "Research Tag", baseTier: 1, isComponent: true, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: "name", contentRole: null, referenceCategory: null },
   "research_template": { token: "research_template", schema: "research", table: "rs_template", label: "Research Template", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: true, titleColumn: "name", contentRole: null, referenceCategory: null },
   "research_topic": { token: "research_topic", schema: "research", table: "rs_topic", label: "Research Topic", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: true, titleColumn: "name", contentRole: null, referenceCategory: null },
+  "route_manifest_entry": { token: "route_manifest_entry", schema: "platform", table: "route_manifest", label: "Route Manifest Entry", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "rulebook": { token: "rulebook", schema: "platform", table: "rulebook", label: "Rulebook", baseTier: 1, isComponent: false, isModule: false, isListed: true, scopeable: true, category: "Knowledge", referencePickable: true, titleColumn: "name", contentRole: "source", referenceCategory: null },
   "sandbox_instance": { token: "sandbox_instance", schema: "public", table: "sandbox_instances", label: "Sandbox Instance", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "sch_agent_task": { token: "sch_agent_task", schema: "scheduler", table: "sch_agent_task", label: "Agent Task Config", baseTier: 1, isComponent: true, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
@@ -529,6 +531,7 @@ var ENTITY_TYPE_METADATA = {
   "seo_topic": { token: "seo_topic", schema: "seo", table: "topic", label: "SEO Topic", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: "seo", referencePickable: true, titleColumn: "name", contentRole: null, referenceCategory: null },
   "seo_web_analytics_daily": { token: "seo_web_analytics_daily", schema: "seo", table: "web_analytics_daily", label: "Web Analytics Daily", baseTier: 1, isComponent: true, isModule: false, isListed: false, scopeable: true, category: "marketing", referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "shared_canvas_item": { token: "shared_canvas_item", schema: "canvas", table: "shared_canvas_items", label: "Shared Canvas Item", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: true, titleColumn: "title", contentRole: null, referenceCategory: null },
+  "short_link": { token: "short_link", schema: "platform", table: "short_links", label: "Short Link", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "skill": { token: "skill", schema: "skill", table: "definition", label: "Skill", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: "Skills", referencePickable: true, titleColumn: "label", contentRole: "utility", referenceCategory: null },
   "skill_render_definition": { token: "skill_render_definition", schema: "skill", table: "render_definition", label: "Skill Render Definition", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: "Skills", referencePickable: true, titleColumn: "label", contentRole: null, referenceCategory: null },
   "sms_consent": { token: "sms_consent", schema: "communication", table: "sms_consent", label: "SMS Consent", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
@@ -1076,6 +1079,7 @@ var ENTITY_TYPE_TOKENS = [
   "platform_actor_session",
   "platform_actor_token",
   "platform_actor_token_event",
+  "platform_continued_access",
   "platform_outcome_event",
   "platform_outsider_consumer",
   "platform_saved_view",
@@ -1104,6 +1108,7 @@ var ENTITY_TYPE_TOKENS = [
   "research_tag",
   "research_template",
   "research_topic",
+  "route_manifest_entry",
   "rulebook",
   "sandbox_instance",
   "sch_agent_task",
@@ -1182,6 +1187,7 @@ var ENTITY_TYPE_TOKENS = [
   "seo_topic",
   "seo_web_analytics_daily",
   "shared_canvas_item",
+  "short_link",
   "skill",
   "skill_render_definition",
   "sms_consent",
@@ -2655,6 +2661,122 @@ function createAssociationHelpers(service) {
   };
 }
 
+// src/core/commentsService.ts
+function toComment(row) {
+  return {
+    id: row.id,
+    orgId: row.organization_id ?? null,
+    entityType: row.entity_type,
+    entityId: row.entity_id,
+    parentId: row.parent_id ?? null,
+    body: row.body,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    createdBy: row.created_by ?? null,
+    author: {
+      email: row.author_email ?? null,
+      displayName: row.author_display_name ?? null,
+      avatarUrl: row.author_avatar_url ?? null
+    }
+  };
+}
+function createCommentsService(deps) {
+  const { dataSource, identity, guards } = deps;
+  const { ok: ok2, err: err2, mapPgError, mapPgErrorPair } = deps.rpc;
+  return {
+    /**
+     * All comments on `${entityType}:${entityId}`, org-filtered by RLS
+     * inside the RPC, ordered oldest→newest. Build the thread from each
+     * row's `parentId` (top-level comments have `parentId === null`).
+     */
+    async listForEntity(entityType, entityId) {
+      try {
+        identity.requireUserId();
+        const token = guards.normalizeEntityToken(entityType);
+        const invalid = firstError(
+          guards.checkToken("entityType", token),
+          guards.checkUuid("entityId", entityId)
+        );
+        if (invalid) return { ok: false, error: invalid };
+        const { data, error } = await dataSource.rpc("cmt_list", {
+          p_entity_type: token,
+          p_entity_id: entityId
+        });
+        if (error) return err2(...mapPgErrorPair(error));
+        const rows = Array.isArray(data) ? data : [];
+        return ok2({ comments: rows.map(toComment) });
+      } catch (e) {
+        return { ok: false, error: mapPgError(e) };
+      }
+    },
+    /**
+     * Post `body` on `${entityType}:${entityId}`; pass `parentId` to reply.
+     * Returns the new comment id.
+     */
+    async add(args) {
+      try {
+        identity.requireUserId();
+        const token = guards.normalizeEntityToken(args.entityType);
+        const invalid = firstError(
+          guards.checkToken("entityType", token),
+          guards.checkUuid("entityId", args.entityId),
+          args.parentId != null ? guards.checkUuid("parentId", args.parentId) : null
+        );
+        if (invalid) return { ok: false, error: invalid };
+        if (!args.body || args.body.trim().length === 0) {
+          return err2("invalid_argument", "comment body must be non-empty");
+        }
+        const { data, error } = await dataSource.rpc("cmt_add", {
+          p_entity_type: token,
+          p_entity_id: args.entityId,
+          p_body: args.body,
+          p_parent_id: args.parentId ?? void 0,
+          p_org_id: args.orgId ?? void 0
+        });
+        if (error) return err2(...mapPgErrorPair(error));
+        if (!data || typeof data !== "string") {
+          return err2("internal", "cmt_add returned no comment id");
+        }
+        return ok2({ id: data });
+      } catch (e) {
+        return { ok: false, error: mapPgError(e) };
+      }
+    },
+    /** Replace a comment's body. Author-only; the RPC rejects everyone else. */
+    async edit(id, body) {
+      try {
+        identity.requireUserId();
+        const invalid = guards.checkUuid("commentId", id);
+        if (invalid) return { ok: false, error: invalid };
+        if (!body || body.trim().length === 0) {
+          return err2("invalid_argument", "comment body must be non-empty");
+        }
+        const { error } = await dataSource.rpc("cmt_edit", {
+          p_id: id,
+          p_body: body
+        });
+        if (error) return err2(...mapPgErrorPair(error));
+        return ok2(null);
+      } catch (e) {
+        return { ok: false, error: mapPgError(e) };
+      }
+    },
+    /** Soft-delete a comment. Author or org member; enforced server-side. */
+    async remove(id) {
+      try {
+        identity.requireUserId();
+        const invalid = guards.checkUuid("commentId", id);
+        if (invalid) return { ok: false, error: invalid };
+        const { error } = await dataSource.rpc("cmt_delete", { p_id: id });
+        if (error) return err2(...mapPgErrorPair(error));
+        return ok2(null);
+      } catch (e) {
+        return { ok: false, error: mapPgError(e) };
+      }
+    }
+  };
+}
+
 // src/core/store.ts
 function associationsKey(type, id) {
   return `${type}:${id}`;
@@ -2671,6 +2793,12 @@ var IDLE_CATEGORIES = Object.freeze({
   fetchedAt: null,
   error: null
 });
+var IDLE_COMMENTS = Object.freeze({
+  status: "idle",
+  comments: Object.freeze([]),
+  fetchedAt: null,
+  error: null
+});
 function createAssociationsStore(config) {
   if (!config || typeof config.dataSource?.rpc !== "function") {
     throw new Error(
@@ -2704,12 +2832,16 @@ function createAssociationsStore(config) {
   const titles = createTitlesService(deps, candidates);
   const entityRows = createEntityRowsService(deps, titles);
   const helpers = createAssociationHelpers(associations);
+  const comments = createCommentsService(deps);
   const assocByKey = /* @__PURE__ */ new Map();
   const assocSubs = /* @__PURE__ */ new Map();
   const assocInFlight = /* @__PURE__ */ new Map();
   const catByDim = /* @__PURE__ */ new Map();
   const catSubs = /* @__PURE__ */ new Map();
   const catInFlight = /* @__PURE__ */ new Map();
+  const cmtByKey = /* @__PURE__ */ new Map();
+  const cmtSubs = /* @__PURE__ */ new Map();
+  const cmtInFlight = /* @__PURE__ */ new Map();
   function notifyAssoc(key) {
     const subs = assocSubs.get(key);
     if (subs) for (const cb of [...subs]) cb();
@@ -2726,6 +2858,14 @@ function createAssociationsStore(config) {
     catByDim.set(dimension, entry);
     notifyCat(dimension);
   }
+  function notifyCmt(key) {
+    const subs = cmtSubs.get(key);
+    if (subs) for (const cb of [...subs]) cb();
+  }
+  function setCmt(key, entry) {
+    cmtByKey.set(key, entry);
+    notifyCmt(key);
+  }
   async function load(type, id, opts = {}) {
     const force = opts.force ?? false;
     if (!type || !id) return;
@@ -2815,6 +2955,49 @@ function createAssociationsStore(config) {
     catInFlight.set(dimension, promise);
     return promise;
   }
+  async function loadComments(type, id, opts = {}) {
+    const force = opts.force ?? false;
+    if (!type || !id) return;
+    const key = associationsKey(type, id);
+    const entry = cmtByKey.get(key);
+    if (!force && entry?.status === "ready") return;
+    const pending = cmtInFlight.get(key);
+    if (!force && entry?.status === "loading" && pending) return pending;
+    const prev = cmtByKey.get(key);
+    setCmt(key, {
+      status: "loading",
+      comments: prev?.comments ?? [],
+      fetchedAt: prev?.fetchedAt ?? null,
+      // Retain the visible failure while a retry is pending (same contract
+      // as the association cache).
+      error: prev?.error ?? null
+    });
+    const promise = (async () => {
+      try {
+        const res = await comments.listForEntity(type, id);
+        if (isAssociationsRpcErr(res)) {
+          const before = cmtByKey.get(key);
+          setCmt(key, {
+            status: "error",
+            comments: before?.comments ?? [],
+            fetchedAt: before?.fetchedAt ?? null,
+            error: res.error.message
+          });
+        } else {
+          setCmt(key, {
+            status: "ready",
+            comments: res.data.comments,
+            fetchedAt: Date.now(),
+            error: null
+          });
+        }
+      } finally {
+        cmtInFlight.delete(key);
+      }
+    })();
+    cmtInFlight.set(key, promise);
+    return promise;
+  }
   return {
     // ── associations ─────────────────────────────────────────────────────
     getEdges(type, id) {
@@ -2885,6 +3068,9 @@ function createAssociationsStore(config) {
       const dims = [...catByDim.keys()];
       catByDim.clear();
       for (const dim of dims) notifyCat(dim);
+      const cmtKeys = [...cmtByKey.keys()];
+      cmtByKey.clear();
+      for (const key of cmtKeys) notifyCmt(key);
     },
     // ── categories ───────────────────────────────────────────────────────
     getCategories(dimension) {
@@ -2959,6 +3145,52 @@ function createAssociationsStore(config) {
       await loadCategories(args.dimension, { force: true });
       return { ok: true, id: res.data.id };
     },
+    // ── comments (W6) ────────────────────────────────────────────────────
+    getComments(type, id) {
+      if (!type || !id) return IDLE_COMMENTS;
+      return cmtByKey.get(associationsKey(type, id)) ?? IDLE_COMMENTS;
+    },
+    loadComments,
+    subscribeComments(key, cb) {
+      let subs = cmtSubs.get(key);
+      if (!subs) {
+        subs = /* @__PURE__ */ new Set();
+        cmtSubs.set(key, subs);
+      }
+      subs.add(cb);
+      return () => {
+        subs.delete(cb);
+        if (subs.size === 0) cmtSubs.delete(key);
+      };
+    },
+    async addComment(args) {
+      const res = await comments.add(args);
+      if (isAssociationsRpcErr(res)) {
+        return { ok: false, error: res.error.message };
+      }
+      await loadComments(args.entityType, args.entityId, { force: true });
+      return { ok: true, id: res.data.id };
+    },
+    async editComment(args) {
+      const res = await comments.edit(args.id, args.body);
+      if (isAssociationsRpcErr(res)) {
+        return { ok: false, error: res.error.message };
+      }
+      await loadComments(args.entityType, args.entityId, { force: true });
+      return { ok: true, id: args.id };
+    },
+    async deleteComment(args) {
+      const res = await comments.remove(args.id);
+      if (isAssociationsRpcErr(res)) {
+        return { ok: false, error: res.error.message };
+      }
+      await loadComments(args.entityType, args.entityId, { force: true });
+      return { ok: true, id: args.id };
+    },
+    invalidateComments(type, id) {
+      const key = associationsKey(type, id);
+      if (cmtByKey.delete(key)) notifyCmt(key);
+    },
     // ── seams ────────────────────────────────────────────────────────────
     titles,
     favorites,
@@ -2966,7 +3198,7 @@ function createAssociationsStore(config) {
     entityRows,
     helpers,
     registry,
-    services: { associations, categories },
+    services: { associations, categories, comments },
     registerEntityOverlay: registry.registerEntityOverlay,
     errorSink,
     identity: config.identity
@@ -2997,7 +3229,11 @@ var DEMANDED_RPC_NAMES = [
   "ues_list",
   "ues_get_bulk",
   "ues_touch",
-  "reference_search_candidates"
+  "reference_search_candidates",
+  "cmt_list",
+  "cmt_add",
+  "cmt_edit",
+  "cmt_delete"
 ];
 
 // src/core/assertDemandedSchema.ts
@@ -3062,7 +3298,17 @@ var PROBE_ARGS = {
   ues_get_bulk: { p_entity_type: "__probe__", p_entity_ids: [BAD_UUID] },
   ues_touch: { p_entity_type: "__probe__", p_entity_id: BAD_UUID },
   // candidates
-  reference_search_candidates: { p_token: "__probe__", p_limit: 1 }
+  reference_search_candidates: { p_token: "__probe__", p_limit: 1 },
+  // comments (W6) — every fn takes a uuid arg, so the unparseable sentinel
+  // guarantees 22P02 before any SECURITY DEFINER body runs (no write occurs).
+  cmt_list: { p_entity_type: "__probe__", p_entity_id: BAD_UUID },
+  cmt_add: {
+    p_entity_type: "__probe__",
+    p_entity_id: BAD_UUID,
+    p_body: "__probe__"
+  },
+  cmt_edit: { p_id: BAD_UUID, p_body: "__probe__" },
+  cmt_delete: { p_id: BAD_UUID }
 };
 function isMissingFunctionError(error) {
   if (!error || typeof error !== "object") return false;
@@ -3138,6 +3384,70 @@ function isContentSourceEdge(sourceType, metadata) {
   if (isMembershipMetadata(metadata)) return false;
   return true;
 }
+
+// src/core/categoryHierarchy.ts
+function buildCategoryHierarchy(categories) {
+  const byId = new Map(categories.map((category) => [category.id, category]));
+  const hasHierarchy = categories.some(
+    (category) => category.parentId !== null && byId.has(category.parentId)
+  );
+  if (!hasHierarchy) {
+    return {
+      items: categories.map((category) => ({
+        category,
+        depth: 0,
+        parent: null,
+        displayName: category.name
+      })),
+      roots: categories.filter((category) => category.parentId === null),
+      hasHierarchy: false
+    };
+  }
+  const roots = categories.filter(
+    (category) => category.parentId === null || !byId.has(category.parentId)
+  );
+  const childrenByParent = /* @__PURE__ */ new Map();
+  for (const category of categories) {
+    if (!category.parentId || !byId.has(category.parentId)) continue;
+    const children = childrenByParent.get(category.parentId) ?? [];
+    children.push(category);
+    childrenByParent.set(category.parentId, children);
+  }
+  const items = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const root of roots) {
+    items.push({
+      category: root,
+      depth: 0,
+      parent: null,
+      displayName: root.name
+    });
+    seen.add(root.id);
+    for (const child of childrenByParent.get(root.id) ?? []) {
+      items.push({
+        category: child,
+        depth: 1,
+        parent: root,
+        displayName: `${root.name} / ${child.name}`
+      });
+      seen.add(child.id);
+    }
+  }
+  for (const category of categories) {
+    if (seen.has(category.id)) continue;
+    items.push({
+      category,
+      depth: 0,
+      parent: null,
+      displayName: category.name
+    });
+  }
+  return {
+    items,
+    roots: categories.filter((category) => category.parentId === null),
+    hasHierarchy: true
+  };
+}
 export {
   DEFAULT_ORG_COLUMN,
   DEFAULT_OWNER_COLUMN,
@@ -3145,12 +3455,14 @@ export {
   SELF_TEST_MISSING_RPC,
   assertDemandedSchema,
   associationsKey,
+  buildCategoryHierarchy,
   createAssociationGuards,
   createAssociationHelpers,
   createAssociationsService,
   createAssociationsStore,
   createCandidatesService,
   createCategoriesService,
+  createCommentsService,
   createEntityRegistry,
   createEntityRowsService,
   createFavoritesService,