@ai-matrx/associations 0.6.2 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog — @ai-matrx/associations
 
+## 0.7.0 — 2026-08-31 (role-safe pin and detach)
+
+- `useContainerLinks` now exposes `setPinned`, which updates the exact
+  role-qualified edge, preserves every sibling metadata field, and refreshes
+  both endpoint caches through the canonical `assoc_add` chokepoint.
+- `AssociationCard` attached-item windows now expose pin/unpin and pass the
+  edge role through both pin and detach. Previously, a role-bearing row was
+  visible but its detach control targeted only the role-less edge and could
+  silently leave the displayed row attached.
+- The default `AssociationList` adapter now derives pin state from edge
+  metadata and supplies the same role-safe pin operation. Failed pin writes
+  announce themselves through the notifier instead of disappearing.
+- Hook and face regressions prove metadata preservation and exact-role routing
+  for both pin and detach. Full package suite: 189 tests.
+
 ## 0.6.2 — 2026-08-31 (vocabulary catch-up: commerce_certified_printer)
 
 Regenerated `src/entity-types.generated.ts` from live `platform.entity_types`:

package/README.md

@@ -4,16 +4,16 @@ THE one way to relate two entities on the AI Matrx platform: association edges,
 categories, favorites/recents, and the generated entity-type vocabulary — shipped
 as one package a Matrx client or enterprise app installs.
 
-**v0.3 ships the types root, the headless `/core`, and the React binding
-`/react`** — the service chokepoint, guards, the never-throw result funnel,
-the registry merge engine, the subscribable cache store, the seven hooks, and
-the association faces (cards, list, pickers, attached-items sheet, capture
-toolbar). Everything below about the schema is binding — it is the package's
-product.
+The package ships the types root, the headless `/core`, the React binding
+`/react`, and the package-owned lazy React entry `/react/lazy`: the service
+chokepoint, guards, never-throw result funnel, registry merge engine,
+subscribable cache store, hooks, and the association faces (cards, list,
+pickers, attached-items sheet, capture toolbar). Everything below about the
+schema is binding — it is the package's product.
 
 ```ts
 import {
-  type EntityTypeToken,        // 651-token union generated from platform.entity_types
+  type EntityTypeToken,        // generated from platform.entity_types
   ENTITY_TYPE_METADATA,        // per-token schema/table/label/titleColumn/contentRole
   isEntityTypeToken,           // runtime guard, narrows to the union
   type AssociationEdge,        // one assoc_for_entity row (both directions)
@@ -48,6 +48,12 @@ await store.favorites.setFavorite("note", noteId, true);
 await assertDemandedSchema(supabase, { selfTest: true });
 ```
 
+`useContainerLinks({ containerType, containerId, orgId })` is the canonical
+container-side React API. Its `attach`, `detach`, and `setPinned` operations all
+target the exact role-qualified edge; `setPinned` preserves the edge's other
+metadata fields. `AssociationCardGrid` and the default `AssociationList`
+adapter expose those same operations without host wiring.
+
 ```tsx
 // /react — the banner'd React binding (peer: react >=18;
 // @ai-matrx/design-system is a real dependency — the faces' chrome

package/dist/{CommentThread-CqZHMTsH.d.cts → CommentThread-HW4hLdsd.d.cts}

@@ -1483,6 +1483,11 @@ interface UseContainerLinksReturn {
     }) => Promise<AssociationWriteResult>;
     /** Detach a resource from this container. */
     detach: (token: EntityTypeToken, resourceId: string, role?: string) => Promise<AssociationWriteResult>;
+    /**
+     * Toggle the edge's agent-context pin while preserving every other metadata
+     * field and the exact semantic role.
+     */
+    setPinned: (token: EntityTypeToken, resourceId: string, pinned: boolean, role?: string) => Promise<AssociationWriteResult>;
 }
 declare function useContainerLinks(args: UseContainerLinksArgs): UseContainerLinksReturn;
 
@@ -1604,7 +1609,12 @@ interface AttachedItemsSheetProps {
     links: ContainerLink[];
     /** Opens the attach picker. Omitted when the token cannot list candidates. */
     onAdd?: () => void;
-    onDetach: (resourceId: string) => Promise<{
+    onDetach: (resourceId: string, role?: string | null) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** Toggle metadata.pinned on this exact role-qualified edge. */
+    onSetPinned?: (resourceId: string, pinned: boolean, role?: string | null) => Promise<{
         ok: boolean;
         error?: string;
     }>;
@@ -1675,7 +1685,7 @@ interface ContainerResourcesAdapter {
      * Optional pin capability (edge `metadata.pinned`) — pinned resources stay
      * inline in agent context at every tier. Rows show a pin toggle when set.
      */
-    setPinned?: (token: EntityTypeToken, resourceId: string, pinned: boolean) => Promise<{
+    setPinned?: (token: EntityTypeToken, resourceId: string, pinned: boolean, role?: string) => Promise<{
         ok: boolean;
         error?: string;
     }>;

package/dist/{CommentThread-CqZHMTsH.d.ts → CommentThread-HW4hLdsd.d.ts}

@@ -1483,6 +1483,11 @@ interface UseContainerLinksReturn {
     }) => Promise<AssociationWriteResult>;
     /** Detach a resource from this container. */
     detach: (token: EntityTypeToken, resourceId: string, role?: string) => Promise<AssociationWriteResult>;
+    /**
+     * Toggle the edge's agent-context pin while preserving every other metadata
+     * field and the exact semantic role.
+     */
+    setPinned: (token: EntityTypeToken, resourceId: string, pinned: boolean, role?: string) => Promise<AssociationWriteResult>;
 }
 declare function useContainerLinks(args: UseContainerLinksArgs): UseContainerLinksReturn;
 
@@ -1604,7 +1609,12 @@ interface AttachedItemsSheetProps {
     links: ContainerLink[];
     /** Opens the attach picker. Omitted when the token cannot list candidates. */
     onAdd?: () => void;
-    onDetach: (resourceId: string) => Promise<{
+    onDetach: (resourceId: string, role?: string | null) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** Toggle metadata.pinned on this exact role-qualified edge. */
+    onSetPinned?: (resourceId: string, pinned: boolean, role?: string | null) => Promise<{
         ok: boolean;
         error?: string;
     }>;
@@ -1675,7 +1685,7 @@ interface ContainerResourcesAdapter {
      * Optional pin capability (edge `metadata.pinned`) — pinned resources stay
      * inline in agent context at every tier. Rows show a pin toggle when set.
      */
-    setPinned?: (token: EntityTypeToken, resourceId: string, pinned: boolean) => Promise<{
+    setPinned?: (token: EntityTypeToken, resourceId: string, pinned: boolean, role?: string) => Promise<{
         ok: boolean;
         error?: string;
     }>;

package/dist/react/index.cjs

@@ -1109,6 +1109,12 @@ var useEntityRelationships = useAssociations;
 
 // src/react/hooks/useContainerLinks.ts
 var import_react3 = require("react");
+function metadataRecord(metadata) {
+  if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) {
+    return metadata == null ? {} : null;
+  }
+  return Object.fromEntries(Object.entries(metadata));
+}
 function useContainerLinks(args) {
   const { containerType, containerId, orgId } = args;
   const store = useAssociationsStore();
@@ -1230,6 +1236,31 @@ function useContainerLinks(args) {
     }
     return result;
   };
+  const setPinned = async (token, resourceId, pinned, role) => {
+    if (!containerId) return { ok: false, error: "Missing container id" };
+    const exactRole = role ?? null;
+    const link = incoming.find(
+      (candidate) => candidate.token === token && candidate.resourceId === resourceId && candidate.role === exactRole
+    );
+    if (!link) return { ok: false, error: "Association edge not found" };
+    const currentMetadata = metadataRecord(link.metadata);
+    if (!currentMetadata) {
+      return {
+        ok: false,
+        error: "Association metadata is not an object and cannot be updated safely"
+      };
+    }
+    return store.add({
+      sourceType: token,
+      sourceId: resourceId,
+      targetType: containerType,
+      targetId: containerId,
+      ...orgId != null ? { orgId } : {},
+      ...link.label != null ? { label: link.label } : {},
+      ...role !== void 0 ? { role } : {},
+      metadata: { ...currentMetadata, pinned }
+    });
+  };
   const reload = async () => {
     await Promise.all([
       reloadGeneric(),
@@ -1247,7 +1278,8 @@ function useContainerLinks(args) {
     attachedIdsFor,
     linksFor,
     attach,
-    detach
+    detach,
+    setPinned
   };
 }
 
@@ -2628,6 +2660,9 @@ function UniversalAssociationPicker(props) {
 var import_react15 = require("react");
 var import_design_system5 = require("@ai-matrx/design-system");
 var import_jsx_runtime9 = require("react/jsx-runtime");
+function metadataIsPinned(metadata) {
+  return metadata !== null && typeof metadata === "object" && !Array.isArray(metadata) && Reflect.get(metadata, "pinned") === true;
+}
 function AttachedItemsSheet(props) {
   const store = useAssociationsStore();
   const info = store.registry.getEntityInfo(props.token);
@@ -2663,7 +2698,8 @@ function AttachedItemsSheet(props) {
           enabled: props.open,
           links: props.links,
           ...props.onAdd ? { onAdd: props.onAdd } : {},
-          onDetach: props.onDetach
+          onDetach: props.onDetach,
+          ...props.onSetPinned ? { onSetPinned: props.onSetPinned } : {}
         }
       )
     }
@@ -2674,7 +2710,8 @@ function AttachedItemsBody({
   enabled,
   links,
   onAdd,
-  onDetach
+  onDetach,
+  onSetPinned
 }) {
   const store = useAssociationsStore();
   const notifier = useNotifier();
@@ -2716,11 +2753,12 @@ function AttachedItemsBody({
       cancelled = true;
     };
   }, [token, idKey, enabled, store]);
-  const detach = async (resourceId) => {
+  const detach = async (link) => {
+    const resourceId = link.resourceId;
     if (busyId) return;
     setBusyId(resourceId);
     try {
-      const res = await onDetach(resourceId);
+      const res = await onDetach(resourceId, link.role);
       if (!res.ok) {
         notifier.error(`Couldn't detach${res.error ? `: ${res.error}` : ""}`);
       }
@@ -2728,6 +2766,20 @@ function AttachedItemsBody({
       setBusyId(null);
     }
   };
+  const setPinned = async (link, pinned) => {
+    if (!onSetPinned || busyId) return;
+    setBusyId(link.resourceId);
+    try {
+      const res = await onSetPinned(link.resourceId, pinned, link.role);
+      if (!res.ok) {
+        notifier.error(
+          `Couldn't ${pinned ? "pin" : "unpin"}${res.error ? `: ${res.error}` : ""}`
+        );
+      }
+    } finally {
+      setBusyId(null);
+    }
+  };
   return /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)(import_jsx_runtime9.Fragment, { children: [
     titleError ? /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)("div", { className: "mb-2 rounded-md border border-destructive/40 bg-destructive/10 px-3 py-2 text-[12px] text-destructive", children: [
       "Showing names recorded at attach time \u2014 they may be out of date.",
@@ -2742,6 +2794,7 @@ function AttachedItemsBody({
       const missing = !titles.has(link.resourceId);
       const name = resolved ?? link.label ?? (missing ? null : "Untitled");
       const busy = busyId === link.resourceId;
+      const pinned = metadataIsPinned(link.metadata);
       return /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)(
         "li",
         {
@@ -2761,12 +2814,35 @@ function AttachedItemsBody({
                 className: "text-foreground"
               }
             ) }),
+            onSetPinned ? /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(
+              "button",
+              {
+                type: "button",
+                disabled: busy,
+                onClick: () => void setPinned(link, !pinned),
+                title: pinned ? "Unpin (stops staying in agent context)" : "Pin \u2014 always in agent context",
+                "aria-label": pinned ? "Unpin" : "Pin",
+                className: (0, import_design_system5.cn)(
+                  "flex h-6 w-6 shrink-0 items-center justify-center rounded-md transition-colors hover:bg-accent hover:text-foreground disabled:opacity-50",
+                  pinned ? "text-primary" : "text-muted-foreground"
+                ),
+                children: /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(
+                  PinIcon,
+                  {
+                    className: (0, import_design_system5.cn)(
+                      "h-3.5 w-3.5",
+                      pinned && "fill-primary/20"
+                    )
+                  }
+                )
+              }
+            ) : null,
             /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(
               "button",
               {
                 type: "button",
                 disabled: busy,
-                onClick: () => void detach(link.resourceId),
+                onClick: () => void detach(link),
                 title: "Detach",
                 className: (0, import_design_system5.cn)(
                   "flex h-6 w-6 shrink-0 items-center justify-center rounded-md text-muted-foreground transition-colors",
@@ -2862,7 +2938,15 @@ function AssociationCard({
   const role = getContentRoleMeta(info.contentRole);
   const Icon = info.Icon ?? DefaultEntityIcon;
   const [listOpen, setListOpen] = (0, import_react16.useState)(false);
-  const { status, countFor, attachedIdsFor, linksFor, attach, detach } = useContainerLinks({
+  const {
+    status,
+    countFor,
+    attachedIdsFor,
+    linksFor,
+    attach,
+    detach,
+    setPinned
+  } = useContainerLinks({
     containerType: container?.type ?? "organization",
     containerId: container?.id ?? null,
     orgId: container?.orgId ?? null
@@ -2959,7 +3043,8 @@ function AssociationCard({
             setOpen(true);
           }
         } : {},
-        onDetach: (resourceId) => detach(token, resourceId)
+        onDetach: (resourceId, role2) => detach(token, resourceId, role2 ?? void 0),
+        onSetPinned: (resourceId, pinned, role2) => setPinned(token, resourceId, pinned, role2 ?? void 0)
       }
     ),
     canAttach && /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
@@ -3018,6 +3103,9 @@ function AssociationCardGrid({
 var import_react17 = require("react");
 var import_design_system8 = require("@ai-matrx/design-system");
 var import_jsx_runtime12 = require("react/jsx-runtime");
+function metadataIsPinned2(metadata) {
+  return metadata !== null && typeof metadata === "object" && !Array.isArray(metadata) && Reflect.get(metadata, "pinned") === true;
+}
 function useContainerLinksAdapter(container, tokens) {
   const store = useAssociationsStore();
   const links = useContainerLinks({
@@ -3032,6 +3120,7 @@ function useContainerLinksAdapter(container, tokens) {
       resourceId: l.resourceId,
       label: l.label,
       role: l.role,
+      pinned: metadataIsPinned2(l.metadata),
       removable: true
     }))
   ) : [];
@@ -3041,11 +3130,13 @@ function useContainerLinksAdapter(container, tokens) {
     reload: links.reload,
     rows,
     attach: async (token, id, title) => links.attach(token, id, title),
-    detach: async (token, id, role) => links.detach(token, id, role)
+    detach: async (token, id, role) => links.detach(token, id, role),
+    setPinned: async (token, id, pinned, role) => links.setPinned(token, id, pinned, role)
   };
 }
 function AssociationList(props) {
   const store = useAssociationsStore();
+  const notifier = useNotifier();
   const ctxEntity = usePrimaryEntity();
   const container = props.container ?? ctxEntity ?? null;
   const defaultAdapter = useContainerLinksAdapter(
@@ -3058,6 +3149,7 @@ function AssociationList(props) {
   const [pickerToken, setPickerToken] = (0, import_react17.useState)(null);
   const [showUniversal, setShowUniversal] = (0, import_react17.useState)(false);
   const [removingKeys, setRemovingKeys] = (0, import_react17.useState)(/* @__PURE__ */ new Set());
+  const [pinningKeys, setPinningKeys] = (0, import_react17.useState)(/* @__PURE__ */ new Set());
   const rows = tokenFilter ? adapter.rows.filter((r) => tokenFilter.includes(r.token)) : adapter.rows;
   const visibleRows = rows.filter((r) => !removingKeys.has(r.key));
   const { titleFor } = useEntityTitles(
@@ -3081,6 +3173,31 @@ function AssociationList(props) {
     });
     return res;
   };
+  const handlePin = async (row, pinned) => {
+    if (!adapter.setPinned) return;
+    const info = store.registry.tryGetEntityInfo(row.token);
+    if (!info) return;
+    setPinningKeys((prev) => new Set(prev).add(row.key));
+    try {
+      const res = await adapter.setPinned(
+        info.token,
+        row.resourceId,
+        pinned,
+        row.role ?? void 0
+      );
+      if (!res.ok) {
+        notifier.error(
+          `Couldn't ${pinned ? "pin" : "unpin"} resource${res.error ? `: ${res.error}` : ""}`
+        );
+      }
+    } finally {
+      setPinningKeys((prev) => {
+        const next = new Set(prev);
+        next.delete(row.key);
+        return next;
+      });
+    }
+  };
   const openRow = (row) => {
     if (props.openEntity) {
       props.openEntity(row.token, row.resourceId);
@@ -3271,18 +3388,15 @@ function AssociationList(props) {
                       "button",
                       {
                         type: "button",
-                        onClick: () => void adapter.setPinned?.(
-                          info.token,
-                          row.resourceId,
-                          !(row.pinned ?? false)
-                        ),
+                        disabled: pinningKeys.has(row.key),
+                        onClick: () => void handlePin(row, !(row.pinned ?? false)),
                         title: row.pinned ? "Unpin (stops staying in agent context)" : "Pin \u2014 always in agent context",
                         "aria-label": row.pinned ? "Unpin" : "Pin",
                         className: (0, import_design_system8.cn)(
                           "shrink-0 rounded p-0.5 transition-colors hover:!text-foreground",
                           row.pinned ? "text-primary" : "text-muted-foreground/0 group-hover:text-muted-foreground"
                         ),
-                        children: /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(
+                        children: pinningKeys.has(row.key) ? /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(SpinnerIcon, { className: "h-3 w-3 animate-spin" }) : /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(
                           PinIcon,
                           {
                             className: (0, import_design_system8.cn)(