@ai-matrx/associations 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,122 @@
+# Changelog — @ai-matrx/associations
+
+## 0.2.0 — 2026-08-29 (unreleased; W2 of the extraction)
+
+Wave 2: the headless owns-persistence `/core` subpath — the service
+chokepoint, guards, the loud result funnel, the registry merge engine, the
+subscribable cache store, titles/favorites/categories/candidates/entity-rows,
+and the falsifiable `assertDemandedSchema` probe. Behavior ported VERBATIM
+from the matrx-frontend originals (census appendix, re-read in full
+2026-08-29); only the measured seams inverted onto the W1 ports.
+
+- **`createAssociationsStore(cfg)`** (`src/core/store.ts`) — the one runtime
+  object a host constructs. Required ports (dataSource/identity/errorSink)
+  throw at construction, each with a named message. Replaces matrx-frontend's
+  ~530 lines of Redux fragments with verbatim cache behavior: per-key
+  in-flight dedup, ready short-circuit unless `force`, pending retains prior
+  edges AND the visible error, add/remove reload BOTH endpoints, setTargets
+  reloads the source only, category echo-insert then authoritative reload,
+  stable idle defaults (`useSyncExternalStore` contract), `subscribe`/
+  `subscribeCategories`/`invalidate`/`invalidateAll`. The "never dispatch
+  appContextSlice" law is now STRUCTURAL (no host-store import path exists)
+  and proven by test: a write notifies only the two endpoint keys.
+- **Services** as sink-bound factories over the `dataSource` port, each
+  method returning the never-throw envelope: `associationsService` (incl. the
+  stricter file→conversation `conversation_file_*` routing and the
+  `agent_resource_*` pair), `categoriesService`, `favoritesService`,
+  `candidates` (generic `reference_search_candidates` read + overlay
+  override + universal cross-token search), `titles` (chunked batch resolve,
+  prime, fallback), `entityRows` (registry-convention create/rename),
+  `helpers` (linkEdges/linkOneToMany/linkManyToOne/replaceTargets/
+  linkCreated/unlinkEdges), and the pure edge classifier
+  (`isContentSourceEdge` exclusion-list law).
+- **`rpcResult`**: `createRpcResultHelpers(errorSink)` — the original mapper
+  verbatim PLUS the new PGRST202 → `demanded_schema_violation` branch that
+  ALWAYS reaches the errorSink and names the demanded-schema contract.
+- **`assertDemandedSchema(dataSource, { selfTest })`**: probes all 23
+  demanded RPCs with ZERO side effects (every uuid arg is an unparseable
+  sentinel, so PostgREST resolves the function but Postgres fails the cast
+  before any body executes — verified against the live SECURITY DEFINER
+  sources 2026-08-29). `selfTest: true` probes a fabricated name that MUST
+  come back PGRST202, so a dataSource that cannot fail is refused
+  (falsifiability rule).
+- **Registry merge engine** (`src/core/registry.ts`): generated metadata +
+  host `entityOverlay` port, convention owner/org columns, reads-tolerant
+  alias resolution (`cld_file` → `file`), curated/listable token sets with
+  the pickable-but-unlistable scream.
+- **Seam inversions (deliberate, per the packaging standard)**: supabase
+  singleton → `dataSource`; `requireUserId` store read → `identity`; every
+  `console.warn`/`console.error` scream → `errorSink` events (plain
+  PostgREST result errors still do NOT double-report — hosts capture those
+  at the dataSource layer — except PGRST202, which always screams);
+  `isTransportFailure` re-implemented in-package (the `@ai-matrx/data/net`
+  original's NetError-class branches cannot occur here; the plain-object/
+  TypeError/navigator branches ported verbatim) to keep `/core` at zero
+  runtime dependencies; lucide `DEFAULT_ICON` → `Icon: null` (C19 — the
+  consumer renders its default); the module-level entity-title Map →
+  store-instance state (no module-level mutable state exists anywhere in
+  `/core`, so there is nothing for dual-loaded graphs to split and no
+  globalThis slot is needed); `favoritesService` + `favoritesCore` (two host
+  files split only by the singleton coupling) collapse back into ONE
+  implementation.
+- **Port addition (additive)**: `AssociationsDataSource` gains OPTIONAL
+  structural `from`/`schema` members — entity-row create/rename write TABLES
+  (verbatim original behavior), not RPCs. An rpc-only dataSource still
+  satisfies everything else; entity-row calls against it return a screamed
+  error naming the missing capability.
+- **Defects found in the originals**: none requiring a behavior change; two
+  latent strictness holes hardened in the port (unchecked `failures[0]` in
+  the helper combiner and unchecked `list[cursor]` in the search worker —
+  both unreachable in practice, both now guarded under
+  `noUncheckedIndexedAccess`).
+- Tests: 97 (from 26) — every rpcResult mapping branch incl. PGRST202,
+  guards + alias recovery, every service branch (file→conversation boundary,
+  id-echo checks, dedupe/empty short-circuits), registry merge/degrade,
+  candidates/titles/entity-rows incl. chunking and capability screams, the
+  full store behavior suite incl. the never-touches-context invariant, and
+  the probe proven falsifiable both ways.
+- Gate: `pnpm typecheck && pnpm test && pnpm check:package` green; the
+  tarball canary now imports AND requires `/core`, constructs a store
+  against fake ports, proves required-port throw, and bans "use client" in
+  all four dist files.
+
+## 0.1.0 — 2026-08-29 (unreleased; W1 of the extraction)
+
+Wave 1 of the associations extraction
+(`common-docs/projects/npm-package-extraction/ASSOCIATIONS-PACKAGE-DESIGN.md`,
+ratified C18): the types root.
+
+- **Entity-type vocabulary in-package**: `src/entity-types.generated.ts`
+  (651 tokens, generated live from `platform.entity_types` on 2026-08-29) plus
+  the generator (`scripts/generate-entity-types.ts`, ported from matrx-frontend
+  `scripts/generate-entity-types.ts`). The app-side ENTITY_OVERLAY duplication
+  guard stays in matrx-frontend's `check:entity-types` until the W5 elimination
+  pass (the overlay is host code). Skew policy per C18: writes strict, reads
+  tolerant; registry changes ship as patch releases.
+- **Demanded RPC contract**: `src/demanded-rpcs.generated.ts` — the 23-function
+  surface (`DemandedRpcSignatures` / `DemandedRpcName` / `DEMANDED_RPC_NAMES`),
+  sliced from the live-generated platform DB contract by
+  `scripts/extract-demanded-rpcs.ts`. The legacy `assoc_link`/`assoc_list`/
+  `assoc_unlink` trio is deliberately not demanded (zero client callers;
+  flagged for server-side retirement).
+- **Edge/result types** ported verbatim from matrx-frontend
+  `features/scopes/types.ts` (`AssociationEdge`, `AssociationTargetEdge`,
+  `AssociationSourceEdge`, `AssociationsEntry`, `UserEntityState`,
+  `PlatformCategory`, `CategoriesEntry`, `ASSOCIATION_TARGET_TYPES`) with two
+  deliberate seam inversions, per the packaging standard:
+  - the host contract's `Json` type became `unknown` (JSON-boundary rule);
+  - `ScopesRpcError`/`ScopesRpcResult` became `AssociationsRpcError`/
+    `AssociationsRpcResult`, and the error-code union gained
+    `demanded_schema_violation` (the PGRST202 → demanded-schema scream that
+    `/core`'s `rpcResult` will map in W2; `template_missing`, a scopes-only
+    code, was not carried over).
+- **The seven ports** (`src/ports.ts`): `AssociationsDataSource`,
+  `AssociationsIdentity`, `ErrorSink` (required) + `EntityOverlayEntry`,
+  `AssociationsNotifier`, `WindowShellPort`, `CapturePort`,
+  `PickerOverrideMap`, `EntityDoorsPort` (optional, defined degradations),
+  combined in `AssociationsConfig`. Shapes distilled from the measured
+  matrx-frontend call sites (census 2026-08-29), nothing speculative.
+- Gate: `pnpm typecheck && pnpm test && pnpm check:package` (build, publint,
+  attw on the packed tarball, empty-project ESM import + CJS require canary,
+  pure-root "use client" ban) — all green; `check:entity-types` drift gate
+  proven falsifiable against the live registry.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Matrix Engine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# @ai-matrx/associations
+
+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.2 ships the types root and the headless `/core`** — the service
+chokepoint, guards, the never-throw result funnel, the registry merge engine,
+and the subscribable cache store. The React faces (`/react`: hooks, cards,
+list, pickers, capture toolbar) arrive in the next waves. 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
+  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)
+  type AssociationsRpcResult,  // the never-throw result envelope
+  type DemandedRpcName,        // the 23-function demanded RPC surface
+  type AssociationsConfig,     // the seven ports a host binds
+} from "@ai-matrx/associations";
+```
+
+```ts
+import {
+  createAssociationsStore, // the ONE runtime object a host constructs
+  assertDemandedSchema,    // boot probe: every demanded RPC must answer
+} from "@ai-matrx/associations/core";
+
+const store = createAssociationsStore({
+  dataSource: supabase,                       // structural subset of SupabaseClient
+  identity: { requireUserId },                // throws when unauthenticated
+  errorSink: (e) => report(e),                // recovery layers scream here
+  entityOverlay: { file: { hrefFor: (id) => `/files/f/${id}` } }, // optional
+});
+
+await store.load("task", taskId);             // lazy, deduped, subscribable
+store.getEdges("task", taskId);               // sync, stable idle default
+await store.add({ sourceType: "note", sourceId, targetType: "task", targetId });
+store.titles.prime("task", taskId, "Renamed");
+await store.favorites.setFavorite("note", noteId, true);
+
+// Dev/CI boot check for any new environment (zero side effects; selfTest
+// proves the probe can fail before you trust its green):
+await assertDemandedSchema(supabase, { selfTest: true });
+```
+
+## The demanded schema — read this first
+
+This package is **opinionated like the Python `matrx-*` packages**: it does not
+adapt to your database — it DEMANDS ours. A consumer who won't run our schema is
+not this package's consumer. It ships no DDL (the platform DB owns that; managed
+consumers run on our infrastructure); it ships the demand three ways —
+documented (here), typed (`DemandedRpcSignatures`, generated from the live DB),
+and probed (`assertDemandedSchema` in `/core`). Every violation
+**screams, never degrades**.
+
+1. **The edge.** `platform.associations(source_type, source_id, target_type,
+   target_id, organization_id, label, metadata, role, position, created_by,
+   created_at, deleted_at, …)` — one polymorphic table, unique on the 5-tuple
+   `(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_*`
+   ×8, `conversation_file*` ×3, `agent_resource_*` ×2, `cat_*` ×5, `ues_*` ×4,
+   `reference_search_candidates`). 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
+   `assoc_link`/`assoc_list`/`assoc_unlink` trio is deliberately NOT demanded.
+3. **Direction is registry-owned: little→big.** The resource is the SOURCE, the
+   container the TARGET (`task → organization`, `file → scope`). The DB trigger
+   `trg_associations_auto_orient` rejects reversed writes — this package
+   surfaces that error verbatim and never flips an edge for you.
+4. **A link is never a grant.** Access lives in `iam.permissions` /
+   `iam.memberships`. The ONLY sanctioned association→access bridge is DB-side
+   conveyance (`platform.association_types.conveys_max` → reachability). This
+   package makes **zero access decisions**.
+5. **A missing function screams.** A PostgREST PGRST202 on any demanded RPC maps
+   to the `demanded_schema_violation` result code and always reaches your
+   errorSink: a database without our schema produces one unambiguous scream, not
+   a mystery toast.
+
+## The token vocabulary — writes strict, reads tolerant
+
+`EntityTypeToken` mirrors `platform.entity_types` 1:1 (651 active tokens),
+regenerated by `pnpm gen:entity-types` inside this package. Skew policy:
+
+- **Writes are STRICT** against the installed vocabulary: a token this version
+  doesn't know fails at the guard, in code, before Postgres — exactly like a
+  missing DB type. The fix is `pnpm up @ai-matrx/associations` (registry changes
+  ship as **patch releases**), never a raw-string widening.
+- **Reads are TOLERANT**: an edge arriving with a token this version doesn't
+  know renders through the fallback (default icon, raw label, no door) instead
+  of crashing.
+
+## The seven ports
+
+One `AssociationsConfig`, bound once per host. `dataSource` (a structural subset
+of `SupabaseClient` answering the demanded RPCs), `identity`, and `errorSink`
+are **required** — construction throws without them. `entityOverlay` (icons /
+routes / candidate overrides per token), `notifier`, `windowShell`, `capture`,
+`pickerOverrides`, and `entityDoors` are optional, each with a defined
+degradation — never a dead button, never a silent failure.
+
+## Versioning
+
+Consumed by Matrx repos as `latest` (`workspace:*` inside the aidream monorepo)
+per THE LATEST LAW — never pinned. Registry token changes → regenerate → patch.
+Contract changes → minor/major per semver.
+
+## License
+
+MIT