@ai-matrx/associations 0.6.2 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog — @ai-matrx/associations
 
+## 0.7.1 — 2026-09-01 (reference-pickable universal search)
+
+- Universal search and attach defaults now use `registry.listableTokens()`.
+  Display-only content types remain visible when already attached, but no
+  longer generate candidate RPC calls or picker chips.
+- Explicit token lists remain supported for specialized host adapters.
+- A regression proves the default RPC sweep exactly matches the registry's
+  reference-pickable, listable set. Full package suite: 190 tests.
+
+## 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/core/index.cjs

@@ -2427,7 +2427,7 @@ function createCandidatesService(deps) {
   }
   async function searchCandidatesAcrossTokens(args) {
     const { tokens, search, ownerId, perTokenLimit = 5, concurrency = 6 } = args;
-    const list = tokens ?? registry.curatedTokens();
+    const list = tokens ?? registry.listableTokens();
     if (list.length === 0) return [];
     const out = [];
     let cursor = 0;