@ai-matrx/associations 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog — @ai-matrx/associations
 
+## 0.5.0 — 2026-08-29 (unreleased; W6 — the comments canonical UI)
+
+W6 per rulings C4/C18: the comments canonical UI is built IN this package —
+a GREENFIELD build (matrx-frontend had only a 165-line service, zero
+components), designed against the platform comments satellite
+(`platform.comments` behind the four `cmt_*` SECURITY-DEFINER RPCs, all
+four verified live: SECURITY DEFINER + authenticated EXECUTE on the
+platform DB).
+
+- **Demanded schema grows to 27 functions**: the `cmt_list` / `cmt_add` /
+  `cmt_edit` / `cmt_delete` family added to `DEMANDED_RPC_FAMILIES`,
+  regenerated from the live-generated DB contract; `assertDemandedSchema`
+  probes all four with the unparseable-uuid sentinel (every cmt_* fn takes
+  a uuid arg, so 22P02 fires before any body runs — zero side effects).
+- **`/core` — `createCommentsService`
+  (`src/core/commentsService.ts`)** — the `cmt_*` chokepoint, behavior
+  ported from matrx-frontend `features/comments/service/commentsService.ts`
+  with the package's guard wall added in front (entity token writes-strict
+  per C18 + legacy-alias normalization, uuid wall on entityId/parentId/
+  commentId, non-empty body). Access decisions stay in the RPCs (edit is
+  author-only, delete author-or-org-member, list org-filtered) — link ≠
+  grant, zero access decisions here.
+- **`/core` — the comment-thread cache slice on the store**
+  (`getComments` / `loadComments` / `subscribeComments` / `addComment` /
+  `editComment` / `deleteComment` / `invalidateComments`, +
+  `services.comments`; `invalidateAll` clears comment threads too): same
+  lifecycle contract as the association cache — per-key in-flight dedup,
+  ready short-circuit unless forced, pending retains previous comments AND
+  the visible error, stable frozen idle default, writes force-reload the
+  thread on success only.
+- **Root types (`src/comments.ts`)** — `PlatformComment` / `CommentAuthor`
+  / `CommentsEntry`, ported from `features/comments/types.ts` and renamed
+  to the package vocabulary.
+- **NEW `authorDisplay` port (`src/ports.ts` + provider)** — the package
+  cannot resolve user profiles itself; `cmt_list` denormalizes
+  email/displayName/avatarUrl and a host with a richer profile store
+  overrides them through this optional function port. DEGRADATION: absent →
+  the denormalized fields render as-is; a row with neither displayName nor
+  email shows "Unknown user" + the initial avatar. Never blank, never a
+  crash.
+- **`/react` — `useComments`** — the thread of comments on any entity
+  (token + id) via `useSyncExternalStore`; `currentUserId` is the LENIENT
+  identity read gating the own-comment affordances (writes stay loud
+  through the services).
+- **`/react` — `CommentThread` (+ `CommentComposer`, `buildCommentTree`,
+  `formatRelativeTime`)** — the canonical face: threaded list
+  (oldest→newest, replies nested by `parentId`, orphaned replies promoted
+  to roots — never dropped), composer (Cmd/Ctrl+Enter submits; a failed
+  post keeps the text beside the inline error — input is never lost),
+  per-item reply, edit-own inline, delete-own as a TWO-STEP that names the
+  consequence ("Deletes this comment for everyone.") before the
+  destructive click exists, relative timestamps via
+  `Intl.RelativeTimeFormat` (+ absolute on hover, "(edited)" marker),
+  author names through the `entityDoors.EntityRef` door when bound (token
+  `user`), avatars/names through `authorDisplay`. Chrome from
+  design-system (`Button`/`Skeleton`/`cn`, peer >=0.3.0 unchanged); glyphs
+  inlined (C19 — `RefreshIcon`/`SpinnerIcon`/`CornerDownRightIcon`
+  reused, zero new icon deps).
+- 30 new behavioral tests (11 /core service+slice, 12 jsdom face tests +
+  tree/relative-time units) → **177 total**; full gate green (`typecheck`,
+  `test`, `check:package` incl. the packed-tarball canary).
+
 ## 0.4.0 — 2026-08-29 (unreleased; W4 completion)
 
 The three faces STOPPED at the W3+W4 build for missing design-system

package/README.md

@@ -18,7 +18,7 @@ import {
   isEntityTypeToken,           // runtime guard, narrows to the union
   type AssociationEdge,        // one assoc_for_entity row (both directions)
   type AssociationsRpcResult,  // the never-throw result envelope
-  type DemandedRpcName,        // the 23-function demanded RPC surface
+  type DemandedRpcName,        // the 27-function demanded RPC surface
   type AssociationsConfig,     // the seven ports a host binds
 } from "@ai-matrx/associations";
 ```
@@ -92,9 +92,9 @@ and probed (`assertDemandedSchema` in `/core`). Every violation
    `(source_type, source_id, target_type, target_id, role)` `NULLS NOT DISTINCT`.
    Type columns are FK-validated against `platform.entity_types.token`.
 2. **RPC-only.** The client holds **no grant** on the table. Every operation goes
-   through the 23 SECURITY DEFINER functions in `DEMANDED_RPC_NAMES` (`assoc_*`
+   through the 27 SECURITY DEFINER functions in `DEMANDED_RPC_NAMES` (`assoc_*`
    ×8, `conversation_file*` ×3, `agent_resource_*` ×2, `cat_*` ×5, `ues_*` ×4,
-   `reference_search_candidates`). Those readers consume the live-only
+   `reference_search_candidates`, and the W6 comments family `cmt_*` ×4). Those readers consume the live-only
    `associations_live` view, so tombstone semantics (a trashed entity
    soft-removes its edges; restore revives them) hold by construction — this
    package never writes a `.is("deleted_at", null)` filter. The DB's legacy

package/dist/core/index.cjs

@@ -33,6 +33,7 @@ __export(core_exports, {
   createAssociationsStore: () => createAssociationsStore,
   createCandidatesService: () => createCandidatesService,
   createCategoriesService: () => createCategoriesService,
+  createCommentsService: () => createCommentsService,
   createEntityRegistry: () => createEntityRegistry,
   createEntityRowsService: () => createEntityRowsService,
   createFavoritesService: () => createFavoritesService,
@@ -2714,6 +2715,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}`;
@@ -2730,6 +2847,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(
@@ -2763,12 +2886,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();
@@ -2785,6 +2912,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;
@@ -2874,6 +3009,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) {
@@ -2944,6 +3122,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) {
@@ -3018,6 +3199,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,
@@ -3025,7 +3252,7 @@ function createAssociationsStore(config) {
     entityRows,
     helpers,
     registry,
-    services: { associations, categories },
+    services: { associations, categories, comments },
     registerEntityOverlay: registry.registerEntityOverlay,
     errorSink,
     identity: config.identity
@@ -3056,7 +3283,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
@@ -3121,7 +3352,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;