@ai-matrx/associations 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,121 @@
 # 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
+primitives, now built against `@ai-matrx/design-system` 0.3.0 (Command
+family incl. CommandDialog, the Select family, the CreatablePicker
+composite) — the optional peer floor moves to **`>=0.3.0`**. Behavior ported
+VERBATIM from the matrx-frontend originals (each re-read in full
+2026-08-29); only the measured seams inverted, chrome never vendored.
+
+- **`AssociationEntitySelect` (`src/react/components/AssociationEntitySelect.tsx`)**
+  — the canonical "name dropdown" (display / inline rename / switch / add new
+  / unlink), adapter-driven via the already-shipping
+  `AssociationEntitySelectAdapter` contract + default adapter hook. Seams:
+  `getEntityInfo` → the store's registry merge engine (`Icon: null` →
+  `DefaultEntityIcon`); `@/lib/toast` → the notifier port;
+  `EntityDoorControls` → the entityDoors port's `DoorControls` (absent → the
+  name and rows render without doors, matching the picker precedent); lucide
+  → inlined glyphs (C19).
+- **`CategorySelect` (`src/react/components/CategorySelect.tsx`)** — THE
+  single-value picker over one `platform.categories` dimension, the
+  CreatablePicker composite with the hierarchy parent-select in
+  `createExtra`. Seams: the Redux active-organization read
+  (`selectOrganizationId`) → the identity port's optional `ensureOrgId()`
+  (`orgId` prop wins; with neither, create refuses LOUDLY — notifier + no
+  RPC); toasts → notifier. NOTE: the origin's two-part success toast
+  (message + description) is joined into the notifier's single success
+  message (the port's `success(msg)` carries no description); content
+  preserved.
+- **`CategoryTagPicker` (`src/react/components/CategoryTagPicker.tsx`)** —
+  THE multi-select tagger over the canonical `entity → category` edge
+  (full-role `setTargets` semantics verbatim, one write at a time). Seams:
+  the host-shaped `ensureOrgId` (`@/lib/organizations/personalOrg`) →
+  `identity.ensureOrgId` per the design's seam table, with the loud
+  `ensure_org_missing` refusal when neither the `orgId` prop nor the port
+  can answer; `console.error` → errorSink
+  (`category_tag_set_targets_failed` / `category_tag_create_failed`);
+  toasts → notifier; the `icon` prop's `LucideIcon` type → the structural
+  `TagPickerIcon`.
+- **`buildCategoryHierarchy` → `/core`
+  (`src/core/categoryHierarchy.ts`)** — the two-level display-order util
+  both category faces consume, ported verbatim from
+  `features/scopes/utils/categoryHierarchy.ts` (pure, React-free), exported
+  from `/core`.
+- **Four new inlined glyphs (C19)**: `ChevronDownIcon`,
+  `ChevronsUpDownIcon`, `CornerDownRightIcon`, `TagIcon`.
+- **Token vocabulary regenerated from the live registry: 651 → 654 tokens**
+  (`platform_continued_access`, `route_manifest_entry`, `short_link` landed
+  after the 0.3.0 generation; caught by the W5 swap agent's token-parity
+  gate). `check:entity-types` green against live.
+- 16 new jsdom behavioral tests (render + interaction + degradations against
+  fake ports) → 147 total; full gate green (`typecheck`, `test`,
+  `check:package` incl. the packed-tarball canary).
+
+
 ## 0.3.0 — 2026-08-29 (unreleased; W3 + W4 of the extraction)
 
 Waves 3 and 4: the `/react` subpath — the seven hooks riding the /core store

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

@@ -26,12 +26,14 @@ __export(core_exports, {
   SELF_TEST_MISSING_RPC: () => SELF_TEST_MISSING_RPC,
   assertDemandedSchema: () => assertDemandedSchema,
   associationsKey: () => associationsKey,
+  buildCategoryHierarchy: () => buildCategoryHierarchy,
   createAssociationGuards: () => createAssociationGuards,
   createAssociationHelpers: () => createAssociationHelpers,
   createAssociationsService: () => createAssociationsService,
   createAssociationsStore: () => createAssociationsStore,
   createCandidatesService: () => createCandidatesService,
   createCategoriesService: () => createCategoriesService,
+  createCommentsService: () => createCommentsService,
   createEntityRegistry: () => createEntityRegistry,
   createEntityRowsService: () => createEntityRowsService,
   createFavoritesService: () => createFavoritesService,
@@ -475,6 +477,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 },
@@ -503,6 +506,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 },
@@ -581,6 +585,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 },
@@ -1128,6 +1133,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",
@@ -1156,6 +1162,7 @@ var ENTITY_TYPE_TOKENS = [
   "research_tag",
   "research_template",
   "research_topic",
+  "route_manifest_entry",
   "rulebook",
   "sandbox_instance",
   "sch_agent_task",
@@ -1234,6 +1241,7 @@ var ENTITY_TYPE_TOKENS = [
   "seo_topic",
   "seo_web_analytics_daily",
   "shared_canvas_item",
+  "short_link",
   "skill",
   "skill_render_definition",
   "sms_consent",
@@ -2707,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}`;
@@ -2723,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(
@@ -2756,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();
@@ -2778,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;
@@ -2867,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) {
@@ -2937,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) {
@@ -3011,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,
@@ -3018,7 +3252,7 @@ function createAssociationsStore(config) {
     entityRows,
     helpers,
     registry,
-    services: { associations, categories },
+    services: { associations, categories, comments },
     registerEntityOverlay: registry.registerEntityOverlay,
     errorSink,
     identity: config.identity
@@ -3049,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
@@ -3114,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;
@@ -3190,4 +3438,68 @@ 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
+  };
+}
 //# sourceMappingURL=index.cjs.map