@ai-matrx/associations 0.4.0 → 0.5.1

package/dist/core/index.d.cts

@@ -1,4 +1,4 @@
-import { EntityOverlayMap, EntityTypeToken, EntityOverlayEntry, ErrorSink, AssociationsRpcError, AssociationsDataSource, AssociationsIdentity, AssociationTargetType, AssociationsRpcResult, AssociationEdge, AssociationTargetEdge, AssociationSourceEdge, CategoryDimension, PlatformCategory, UserStateKind, UserEntityState, AssociationsEntry, CategoriesEntry, AssociationsConfig } from '../index.cjs';
+import { EntityOverlayMap, EntityTypeToken, EntityOverlayEntry, ErrorSink, AssociationsRpcError, AssociationsDataSource, AssociationsIdentity, AssociationTargetType, AssociationsRpcResult, AssociationEdge, AssociationTargetEdge, AssociationSourceEdge, CategoryDimension, PlatformCategory, UserStateKind, UserEntityState, PlatformComment, AssociationsEntry, CategoriesEntry, CommentsEntry, AssociationsConfig } from '../index.cjs';
 import 'react';
 
 /** The universal ownership column post-2026-reorg. */
@@ -474,6 +474,28 @@ interface AssociationHelpersApi {
 }
 declare function createAssociationHelpers(service: AssociationsServiceApi): AssociationHelpersApi;
 
+interface AddCommentArgs {
+    /** Registered entity-type token the comment hangs on (writes-strict, C18). */
+    entityType: string;
+    entityId: string;
+    body: string;
+    /** Reply target — an existing comment's id. Top-level when omitted. */
+    parentId?: string | null;
+    /** Org override; the RPC resolves task-org/personal-org when omitted. */
+    orgId?: string | null;
+}
+interface CommentsServiceApi {
+    listForEntity(entityType: string, entityId: string): Promise<AssociationsRpcResult<{
+        comments: PlatformComment[];
+    }>>;
+    add(args: AddCommentArgs): Promise<AssociationsRpcResult<{
+        id: string;
+    }>>;
+    edit(id: string, body: string): Promise<AssociationsRpcResult<null>>;
+    remove(id: string): Promise<AssociationsRpcResult<null>>;
+}
+declare function createCommentsService(deps: CoreDeps): CommentsServiceApi;
+
 /** Cache key for one association endpoint. */
 declare function associationsKey(type: string, id: string): string;
 interface AssociationWriteResult {
@@ -488,6 +510,12 @@ interface CategoryMutationResult {
     id?: string;
     error?: string;
 }
+interface CommentMutationResult {
+    ok: boolean;
+    /** Set on a successful `addComment`. */
+    id?: string;
+    error?: string;
+}
 interface AssociationsStore {
     /** Stable, sync read of one endpoint's entry (idle default when uncached). */
     getEdges(type: string, id: string): AssociationsEntry;
@@ -531,7 +559,7 @@ interface AssociationsStore {
     }): Promise<AssociationWriteResult>;
     /** Reset one endpoint to idle and notify its subscribers. */
     invalidate(type: string, id: string): void;
-    /** Reset every association endpoint AND every category facet. */
+    /** Reset every association endpoint, category facet, and comment thread. */
     invalidateAll(): void;
     getCategories(dimension: CategoryDimension): CategoriesEntry;
     loadCategories(dimension: CategoryDimension, opts?: {
@@ -566,6 +594,41 @@ interface AssociationsStore {
         dimension: CategoryDimension;
         id: string;
     }): Promise<CategoryMutationResult>;
+    /** Stable, sync read of one entity's comment thread (idle when uncached). */
+    getComments(type: string, id: string): CommentsEntry;
+    /**
+     * Lazy load of every comment on `${type}:${id}` (oldest→newest; thread by
+     * `parentId`). Deduped per key; `status === "ready"` short-circuits unless
+     * `force`.
+     */
+    loadComments(type: string, id: string, opts?: {
+        force?: boolean;
+    }): Promise<void>;
+    /** External-store contract for one entity's comment thread. */
+    subscribeComments(key: string, cb: () => void): () => void;
+    /** Post a comment (or a reply); on success force-reloads the thread. */
+    addComment(args: {
+        entityType: string;
+        entityId: string;
+        body: string;
+        parentId?: string | null;
+        orgId?: string | null;
+    }): Promise<CommentMutationResult>;
+    /** Edit a comment body (author-only in the RPC); reloads the thread. */
+    editComment(args: {
+        entityType: string;
+        entityId: string;
+        id: string;
+        body: string;
+    }): Promise<CommentMutationResult>;
+    /** Soft-delete a comment (author/org member in the RPC); reloads the thread. */
+    deleteComment(args: {
+        entityType: string;
+        entityId: string;
+        id: string;
+    }): Promise<CommentMutationResult>;
+    /** Reset one entity's comment thread to idle and notify its subscribers. */
+    invalidateComments(type: string, id: string): void;
     /** Batched title resolution + the session cache + prime. */
     titles: TitlesServiceApi;
     /** Per-user favorite/pinned/hidden state (`ues_*`). */
@@ -586,6 +649,7 @@ interface AssociationsStore {
     services: {
         associations: AssociationsServiceApi;
         categories: CategoriesServiceApi;
+        comments: CommentsServiceApi;
     };
     /** Merge more host overlay entries in (icons/routes/candidate loaders). */
     registerEntityOverlay: EntityRegistry["registerEntityOverlay"];
@@ -676,4 +740,4 @@ interface CategoryHierarchy {
  */
 declare function buildCategoryHierarchy(categories: PlatformCategory[]): CategoryHierarchy;
 
-export { type AddAssociationArgs, type AssertDemandedSchemaOptions, type AssociationGuards, type AssociationHelpersApi, type AssociationWriteResult, type AssociationsServiceApi, type AssociationsStore, type CandidateRecord, type CandidatesResult, type CandidatesServiceApi, type CategoriesServiceApi, type CategoryHierarchy, type CategoryHierarchyItem, type CategoryMutationResult, type ContainerRef, type ContentRole, type ConversationFileLink, type CoreDeps, type CreateEntityRowArgs, DEFAULT_ORG_COLUMN, DEFAULT_OWNER_COLUMN, type DemandedSchemaReport, type EdgeAttrs, type EdgeSpec, type EntityInfo, type EntityRef, type EntityRegistry, type EntityRowResult, type EntityRowsServiceApi, type FavoritesServiceApi, type ListCandidatesArgs, NON_CONTENT_SOURCE_TYPES, type PgErrorMapper, type RpcResultHelpers, SELF_TEST_MISSING_RPC, type SearchAcrossTokensArgs, type TitlesServiceApi, type UniversalCandidate, assertDemandedSchema, associationsKey, buildCategoryHierarchy, createAssociationGuards, createAssociationHelpers, createAssociationsService, createAssociationsStore, createCandidatesService, createCategoriesService, createEntityRegistry, createEntityRowsService, createFavoritesService, createRpcResultHelpers, createTitlesService, entityTitleCacheKey, err, firstError, isContentRole, isContentSourceEdge, isMembershipMetadata, isTransportFailure, isUuid, ok, resolveEntityToken };
+export { type AddAssociationArgs, type AddCommentArgs, type AssertDemandedSchemaOptions, type AssociationGuards, type AssociationHelpersApi, type AssociationWriteResult, type AssociationsServiceApi, type AssociationsStore, type CandidateRecord, type CandidatesResult, type CandidatesServiceApi, type CategoriesServiceApi, type CategoryHierarchy, type CategoryHierarchyItem, type CategoryMutationResult, type CommentMutationResult, type CommentsServiceApi, type ContainerRef, type ContentRole, type ConversationFileLink, type CoreDeps, type CreateEntityRowArgs, DEFAULT_ORG_COLUMN, DEFAULT_OWNER_COLUMN, type DemandedSchemaReport, type EdgeAttrs, type EdgeSpec, type EntityInfo, type EntityRef, type EntityRegistry, type EntityRowResult, type EntityRowsServiceApi, type FavoritesServiceApi, type ListCandidatesArgs, NON_CONTENT_SOURCE_TYPES, type PgErrorMapper, type RpcResultHelpers, SELF_TEST_MISSING_RPC, type SearchAcrossTokensArgs, type TitlesServiceApi, type UniversalCandidate, assertDemandedSchema, associationsKey, buildCategoryHierarchy, createAssociationGuards, createAssociationHelpers, createAssociationsService, createAssociationsStore, createCandidatesService, createCategoriesService, createCommentsService, createEntityRegistry, createEntityRowsService, createFavoritesService, createRpcResultHelpers, createTitlesService, entityTitleCacheKey, err, firstError, isContentRole, isContentSourceEdge, isMembershipMetadata, isTransportFailure, isUuid, ok, resolveEntityToken };

package/dist/core/index.d.ts

@@ -1,4 +1,4 @@
-import { EntityOverlayMap, EntityTypeToken, EntityOverlayEntry, ErrorSink, AssociationsRpcError, AssociationsDataSource, AssociationsIdentity, AssociationTargetType, AssociationsRpcResult, AssociationEdge, AssociationTargetEdge, AssociationSourceEdge, CategoryDimension, PlatformCategory, UserStateKind, UserEntityState, AssociationsEntry, CategoriesEntry, AssociationsConfig } from '../index.js';
+import { EntityOverlayMap, EntityTypeToken, EntityOverlayEntry, ErrorSink, AssociationsRpcError, AssociationsDataSource, AssociationsIdentity, AssociationTargetType, AssociationsRpcResult, AssociationEdge, AssociationTargetEdge, AssociationSourceEdge, CategoryDimension, PlatformCategory, UserStateKind, UserEntityState, PlatformComment, AssociationsEntry, CategoriesEntry, CommentsEntry, AssociationsConfig } from '../index.js';
 import 'react';
 
 /** The universal ownership column post-2026-reorg. */
@@ -474,6 +474,28 @@ interface AssociationHelpersApi {
 }
 declare function createAssociationHelpers(service: AssociationsServiceApi): AssociationHelpersApi;
 
+interface AddCommentArgs {
+    /** Registered entity-type token the comment hangs on (writes-strict, C18). */
+    entityType: string;
+    entityId: string;
+    body: string;
+    /** Reply target — an existing comment's id. Top-level when omitted. */
+    parentId?: string | null;
+    /** Org override; the RPC resolves task-org/personal-org when omitted. */
+    orgId?: string | null;
+}
+interface CommentsServiceApi {
+    listForEntity(entityType: string, entityId: string): Promise<AssociationsRpcResult<{
+        comments: PlatformComment[];
+    }>>;
+    add(args: AddCommentArgs): Promise<AssociationsRpcResult<{
+        id: string;
+    }>>;
+    edit(id: string, body: string): Promise<AssociationsRpcResult<null>>;
+    remove(id: string): Promise<AssociationsRpcResult<null>>;
+}
+declare function createCommentsService(deps: CoreDeps): CommentsServiceApi;
+
 /** Cache key for one association endpoint. */
 declare function associationsKey(type: string, id: string): string;
 interface AssociationWriteResult {
@@ -488,6 +510,12 @@ interface CategoryMutationResult {
     id?: string;
     error?: string;
 }
+interface CommentMutationResult {
+    ok: boolean;
+    /** Set on a successful `addComment`. */
+    id?: string;
+    error?: string;
+}
 interface AssociationsStore {
     /** Stable, sync read of one endpoint's entry (idle default when uncached). */
     getEdges(type: string, id: string): AssociationsEntry;
@@ -531,7 +559,7 @@ interface AssociationsStore {
     }): Promise<AssociationWriteResult>;
     /** Reset one endpoint to idle and notify its subscribers. */
     invalidate(type: string, id: string): void;
-    /** Reset every association endpoint AND every category facet. */
+    /** Reset every association endpoint, category facet, and comment thread. */
     invalidateAll(): void;
     getCategories(dimension: CategoryDimension): CategoriesEntry;
     loadCategories(dimension: CategoryDimension, opts?: {
@@ -566,6 +594,41 @@ interface AssociationsStore {
         dimension: CategoryDimension;
         id: string;
     }): Promise<CategoryMutationResult>;
+    /** Stable, sync read of one entity's comment thread (idle when uncached). */
+    getComments(type: string, id: string): CommentsEntry;
+    /**
+     * Lazy load of every comment on `${type}:${id}` (oldest→newest; thread by
+     * `parentId`). Deduped per key; `status === "ready"` short-circuits unless
+     * `force`.
+     */
+    loadComments(type: string, id: string, opts?: {
+        force?: boolean;
+    }): Promise<void>;
+    /** External-store contract for one entity's comment thread. */
+    subscribeComments(key: string, cb: () => void): () => void;
+    /** Post a comment (or a reply); on success force-reloads the thread. */
+    addComment(args: {
+        entityType: string;
+        entityId: string;
+        body: string;
+        parentId?: string | null;
+        orgId?: string | null;
+    }): Promise<CommentMutationResult>;
+    /** Edit a comment body (author-only in the RPC); reloads the thread. */
+    editComment(args: {
+        entityType: string;
+        entityId: string;
+        id: string;
+        body: string;
+    }): Promise<CommentMutationResult>;
+    /** Soft-delete a comment (author/org member in the RPC); reloads the thread. */
+    deleteComment(args: {
+        entityType: string;
+        entityId: string;
+        id: string;
+    }): Promise<CommentMutationResult>;
+    /** Reset one entity's comment thread to idle and notify its subscribers. */
+    invalidateComments(type: string, id: string): void;
     /** Batched title resolution + the session cache + prime. */
     titles: TitlesServiceApi;
     /** Per-user favorite/pinned/hidden state (`ues_*`). */
@@ -586,6 +649,7 @@ interface AssociationsStore {
     services: {
         associations: AssociationsServiceApi;
         categories: CategoriesServiceApi;
+        comments: CommentsServiceApi;
     };
     /** Merge more host overlay entries in (icons/routes/candidate loaders). */
     registerEntityOverlay: EntityRegistry["registerEntityOverlay"];
@@ -676,4 +740,4 @@ interface CategoryHierarchy {
  */
 declare function buildCategoryHierarchy(categories: PlatformCategory[]): CategoryHierarchy;
 
-export { type AddAssociationArgs, type AssertDemandedSchemaOptions, type AssociationGuards, type AssociationHelpersApi, type AssociationWriteResult, type AssociationsServiceApi, type AssociationsStore, type CandidateRecord, type CandidatesResult, type CandidatesServiceApi, type CategoriesServiceApi, type CategoryHierarchy, type CategoryHierarchyItem, type CategoryMutationResult, type ContainerRef, type ContentRole, type ConversationFileLink, type CoreDeps, type CreateEntityRowArgs, DEFAULT_ORG_COLUMN, DEFAULT_OWNER_COLUMN, type DemandedSchemaReport, type EdgeAttrs, type EdgeSpec, type EntityInfo, type EntityRef, type EntityRegistry, type EntityRowResult, type EntityRowsServiceApi, type FavoritesServiceApi, type ListCandidatesArgs, NON_CONTENT_SOURCE_TYPES, type PgErrorMapper, type RpcResultHelpers, SELF_TEST_MISSING_RPC, type SearchAcrossTokensArgs, type TitlesServiceApi, type UniversalCandidate, assertDemandedSchema, associationsKey, buildCategoryHierarchy, createAssociationGuards, createAssociationHelpers, createAssociationsService, createAssociationsStore, createCandidatesService, createCategoriesService, createEntityRegistry, createEntityRowsService, createFavoritesService, createRpcResultHelpers, createTitlesService, entityTitleCacheKey, err, firstError, isContentRole, isContentSourceEdge, isMembershipMetadata, isTransportFailure, isUuid, ok, resolveEntityToken };
+export { type AddAssociationArgs, type AddCommentArgs, type AssertDemandedSchemaOptions, type AssociationGuards, type AssociationHelpersApi, type AssociationWriteResult, type AssociationsServiceApi, type AssociationsStore, type CandidateRecord, type CandidatesResult, type CandidatesServiceApi, type CategoriesServiceApi, type CategoryHierarchy, type CategoryHierarchyItem, type CategoryMutationResult, type CommentMutationResult, type CommentsServiceApi, type ContainerRef, type ContentRole, type ConversationFileLink, type CoreDeps, type CreateEntityRowArgs, DEFAULT_ORG_COLUMN, DEFAULT_OWNER_COLUMN, type DemandedSchemaReport, type EdgeAttrs, type EdgeSpec, type EntityInfo, type EntityRef, type EntityRegistry, type EntityRowResult, type EntityRowsServiceApi, type FavoritesServiceApi, type ListCandidatesArgs, NON_CONTENT_SOURCE_TYPES, type PgErrorMapper, type RpcResultHelpers, SELF_TEST_MISSING_RPC, type SearchAcrossTokensArgs, type TitlesServiceApi, type UniversalCandidate, assertDemandedSchema, associationsKey, buildCategoryHierarchy, createAssociationGuards, createAssociationHelpers, createAssociationsService, createAssociationsStore, createCandidatesService, createCategoriesService, createCommentsService, createEntityRegistry, createEntityRowsService, createFavoritesService, createRpcResultHelpers, createTitlesService, entityTitleCacheKey, err, firstError, isContentRole, isContentSourceEdge, isMembershipMetadata, isTransportFailure, isUuid, ok, resolveEntityToken };

package/dist/core/index.js

@@ -641,6 +641,7 @@ var ENTITY_TYPE_METADATA = {
   "workflow": { token: "workflow", schema: "workflow", table: "definition", label: "Workflow", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: true, titleColumn: "name", contentRole: "utility", referenceCategory: null },
   "workflow_card": { token: "workflow_card", schema: "workflow", table: "card", label: "Workflow Card", baseTier: 1, isComponent: true, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "workflow_checkpoint": { token: "workflow_checkpoint", schema: "workflow", table: "checkpoint", label: "Workflow Checkpoint", baseTier: 1, isComponent: true, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
+  "workflow_comparison": { token: "workflow_comparison", schema: "workflow", table: "comparison", label: "Workflow Comparison", baseTier: 1, isComponent: false, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "workflow_definition_version": { token: "workflow_definition_version", schema: "workflow", table: "definition_version", label: "Workflow Definition Version", baseTier: 1, isComponent: true, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: "name", contentRole: null, referenceCategory: null },
   "workflow_idempotency": { token: "workflow_idempotency", schema: "workflow", table: "idempotency", label: "Workflow Idempotency", baseTier: 1, isComponent: true, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
   "workflow_job": { token: "workflow_job", schema: "workflow", table: "job", label: "Workflow Job", baseTier: 1, isComponent: true, isModule: false, isListed: false, scopeable: true, category: null, referencePickable: false, titleColumn: null, contentRole: null, referenceCategory: null },
@@ -1297,6 +1298,7 @@ var ENTITY_TYPE_TOKENS = [
   "workflow",
   "workflow_card",
   "workflow_checkpoint",
+  "workflow_comparison",
   "workflow_definition_version",
   "workflow_idempotency",
   "workflow_job",
@@ -2661,6 +2663,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}`;
@@ -2677,6 +2795,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(
@@ -2710,12 +2834,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();
@@ -2732,6 +2860,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;
@@ -2821,6 +2957,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) {
@@ -2891,6 +3070,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) {
@@ -2965,6 +3147,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,
@@ -2972,7 +3200,7 @@ function createAssociationsStore(config) {
     entityRows,
     helpers,
     registry,
-    services: { associations, categories },
+    services: { associations, categories, comments },
     registerEntityOverlay: registry.registerEntityOverlay,
     errorSink,
     identity: config.identity
@@ -3003,7 +3231,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
@@ -3068,7 +3300,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;
@@ -3222,6 +3464,7 @@ export {
   createAssociationsStore,
   createCandidatesService,
   createCategoriesService,
+  createCommentsService,
   createEntityRegistry,
   createEntityRowsService,
   createFavoritesService,