@ai-matrx/records 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog — @ai-matrx/records
+
+## 0.3.0
+
+**The anonymous lane, wired to the doors that actually exist.** This package
+named a door `custom.anon_record_write`, which the store never had — so
+`FormRunner` told every person that a public form's link was "pending" for a
+lane that had already shipped. W4-ANON landed as SEVEN doors, and they are all
+here now: `anonTokenIssue` / `anonTokenVerify` / `anonTokenRevoke` (an embed
+token carries ONE decision, read or write, and an exact origin list), `anonWrite`
+(the stranger's write — the TOKEN supplies the organization, and what it makes is
+a quarantined submission, never a record), `anonCapture` (the SIGNED-IN offline
+path, deduplicated on a key the client mints) and `anonPublish`. A screen calling
+a live feature pending is the same silent failure as one calling a missing
+feature live.
+
+**Work.** `workStates`, `workTemplateRefusal` / `workTemplateDeclare` /
+`workTemplateInstantiate` / `workTemplateShape` / `workInstantiationShape`,
+`workWhoseTurn`, `workHasAssignment`, `workAssignmentFields`,
+`workTakeAssignment`, `workTransitionRefusal`, and the slots:
+`workSlotsDeclare`, `workSlotHold`, `workSlotRelease`, `workSlotHolds`,
+`workSlotExpire`. One hold per slot is a UNIQUE INDEX in the database, so a
+second hold comes back as `already_exists` carrying the index that refused it.
+
+**The trust doors, and they are `iam`'s, not the store's.** `isExternalPrincipal`,
+`externalPrincipalCard`, `externalPrincipalReach`, `publishBindingCreate`,
+`publishBindingRevoke`, `resolvePublishBinding`, `worldPublishGapNotice`,
+`publishToWorld`. They are named by hand in `core/doors.ts` rather than
+generated, because `pnpm records:generate` reads `custom` and only `custom` — a
+census of it says nothing true about `iam`. `RecordsDataSource.rpc` gained an
+optional third argument, `{ schema }`, which a supabase-js host routes to
+`client.schema(schema).rpc(...)`; every existing call is unchanged.
+
+New types: `WorkState`, `WorkGraph`, `WorkInstantiation`, `WorkTurn`,
+`WorkSlotHold`, `WorkAssignmentField`, `AnonTokenBinding`,
+`ExternalPrincipalCard`, `PublishBinding`, `ResolvedPublishBinding`.
+
+**Two vocabularies this package had wrong, found by writing a Field the store
+refused.** `FIELD_SENSITIVITIES` read `standard · sensitive · secret`; the store
+has always wanted `public · internal · confidential · restricted`, which is also
+what the knob `custom/field_sensitivity_levels` keys off — so the two could
+never have agreed. And `Field.context_policy` was typed as `Delivery`
+(`inline · on_demand · auto`), which is a different question: delivery is how
+much of a merge field's value rides into a turn, while FLD-12's context policy
+is whether an agent may see a Field's values at all, in the store's own words
+`include · summarize · exclude · on_request`. Both are corrected, and
+`ContextPolicy` is now its own exported type. Neither was generated, which is
+why neither was caught by `pnpm check:store-registry`.
+
+`src/store.generated.ts` regenerated from the live store.
+
+## 0.2.0
+
+**Reads go through the read door.** `recordRead` calls `custom.read_record` and
+`list` calls `custom.read_records` instead of selecting `custom.record`, so the
+store decides which rows a reader may see and which fields of them: a masked
+field comes back present-and-null with the store's own reason in `hidden`
+(`_hidden`, unfolded for you). `query` materialises through the same doors, and
+its as-of reads now call `custom.query_record_as_of` / `custom.query_table_as_of`
+— both clocks — instead of filtering `updated_at` itself and refusing the world
+clock by name.
+
+Shapes that changed with it: `list` and `query` answer `ReadRow[]`
+(`{ id, document, level, hidden }`) rather than raw store rows, `RecordRead` is
+`{ record_id, document, hidden, computed }`, and `useRecords` lost
+`includeDeleted` — the read door reads live records only, and there is no door
+that answers otherwise.
+
+New refusal class: `stale_read` (`40001`), which is `custom.has_visibility_at`
+refusing to answer from a snapshot older than a write the reader has already
+observed. It is the one refusal worth retrying.
+
+**A store defect this found and fixed** (`db/migrations/campaign/vis25_the_owner_arm_on_the_read_door.sql`,
+applied to the main database): `custom.has_visibility` had no VIS-25 owner arm,
+so the record you had just written was yours to `custom.read_records` and not
+yours to `custom.read_record` — the list offered the row and the door slammed.
+
+## 0.1.1
+
+First working release: the types root, the headless `/core` client over the
+store's doors, the `/react` binding, the generated store registry
+(`pnpm records:generate` / `check:store-registry`) and the real-door suite that
+runs against the live rehearsal branch inside an always-rolled-back transaction.
+
+Two defects the suite found in the mirror and fixed:
+
+- The document-size prediction measured `JSON.stringify` bytes; the store
+  measures the JSONB text, which puts a space after every `:` and every `,`. On
+  an 18-key document the two sentences disagreed by 35 bytes. The mirror now
+  renders the way Postgres does.
+- The mirror predicted refusals for `ver`, `actor`, `on_behalf_of` and `at`.
+  The store never raises them: `custom.stamp_value_envelopes` and
+  `custom.value_versions` overwrite all four with the truth BEFORE
+  `custom.value_envelope_refusal` looks. Those four predictions are gone —
+  a sentence the store never says is a defect in the mirror.

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,118 @@
+# @ai-matrx/records
+
+THE headless client of the AI Matrx record store: the Table / Field / Rule /
+Record / Relation / Home types, the closed vocabularies and refusal codes read
+from the store ITSELF, the typed calls over the store's doors and nothing else,
+the merge-field declaration, a validation mirror that predicts only what the
+store's own triggers refuse, and a result envelope that never throws.
+
+The package ships the types root, the headless `/core` and the React binding
+`/react`. `@ai-matrx/records-ui` renders it; nothing else talks to the store.
+
+**The one rule this package lives by:** the client mirrors the store's contract
+and never re-implements a rule the store enforces. Where the store refuses, this
+package surfaces the store's own sentence — never a translation of it.
+
+```ts
+import {
+  type Table, type Field, type StoredRecord, // the shapes
+  type ValueEnvelope,                        // ver · src · actor · on_behalf_of · at · absent · alternates · dated
+  PARITY_FIELD_TYPES,                        // the 13 field types, read from custom.parity_field_types()
+  ACTOR_VOCABULARY,                          // exactly: user, agent, system
+  ABSENCE_REASONS,                           // exactly: never asked, none, refused, conflicting
+  STORE_DOORS, STORE_REFUSAL_CODES,          // GENERATED from pg_proc on the live store
+} from "@ai-matrx/records";
+```
+
+## /core — the typed client over the doors
+
+```ts
+import { createRecordsClient } from "@ai-matrx/records/core";
+
+const records = createRecordsClient({
+  dataSource: supabase,                  // structural subset of SupabaseClient
+  organizationId: orgId,                 // the store is keyed (organization_id, id)
+  onError: (e) => report(e),             // OPTIONAL — the default screams to console
+});
+
+const written = await records.recordWrite({ table_id, data: { title: "Acme", owner: personId } });
+const rows    = await records.list({ table_id, limit: 50 });
+const one     = await records.recordRead({ record_id, withComputed: true });
+const moved   = await records.recordUpdate({ record_id, patch: { title: "Acme Inc" }, expectedVersion: 3 });
+
+if (!moved.ok && moved.error.code === "stale_write") {
+  // The store's own words, plus the conflict field by field.
+  moved.error.message;  // "Someone else changed this record while you were working on it. …"
+  staleWriteDetail(moved.error); // { expected_version, current_version, contested_fields }
+}
+```
+
+Nothing here throws, and nothing here invents an answer. A door the store does
+not have yet is answered `door_absent`, naming the door AND the lane that owes
+it — `metadataSearch`, `fieldPropose`, `tablePropose` and `mergeFieldResolve`
+refuse today rather than returning an empty list that would read like "there is
+nothing".
+
+## The mirror — what the store is about to say, said half a second earlier
+
+```ts
+import { predictWriteRefusals } from "@ai-matrx/records/core";
+
+const problems = predictWriteRefusals({ fields, document, recordType });
+// [{ field_key: "amount", sqlstate: "23514", predicted_by: "custom.validate_values",
+//    message: "Amount has to be at least 1" }]
+```
+
+This is NOT validation — the store validates, inside the write door, and cannot
+be bypassed. The mirror only says what the store is about to say, in the store's
+exact sentence, and it says NOTHING where it cannot see (option membership,
+relation targets, anything needing a query). Silence means "ask the store".
+
+## /react — bind once, then hooks
+
+```tsx
+import {
+  RecordsProvider, useTables, useFields, useRecords, useRecord, useRecordMutation,
+} from "@ai-matrx/records/react";
+
+<RecordsProvider client={records}>{children}</RecordsProvider>;
+
+const { tables } = useTables();
+const { fields } = useFields(table_id);
+const { rows, total, live, liveOffReason } = useRecords({ table_id, pageSize: 50 });
+const { write, update, remove, conflict } = useRecordMutation();
+```
+
+`live` is never quietly false: when realtime is not bound, `liveOffReason` says
+why in a sentence a screen can show.
+
+## The generated half
+
+`src/store.generated.ts` is written by `pnpm records:generate` from the live
+store's own catalogue — the vocabularies from the store's vocabulary functions,
+the field types from `custom.parity_field_types()`, the doors from `pg_proc`,
+the kernel ids from the kernel rows, the tokens from `platform.entity_types`.
+`pnpm check:store-registry` exits non-zero the moment this package and the store
+disagree, which is how a door another lane added shows up as a red check rather
+than as a runtime surprise.
+
+## The suite
+
+`pnpm test` runs against the live rehearsal branch. Every case is one
+transaction that always ends in `rollback`: inside it the suite opens the
+product switch, grants only what its own half needs, and sets
+`request.jwt.claims` to the campaign's test identity (`test@test.com`) — so every
+call goes through the real doors, the real triggers and the real guards, as a
+real identity, and the branch is byte-identical afterwards (the last test
+re-reads it from a fresh connection and proves it). The red half is the same
+calls without that standing, asserted by the store's message text.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `pnpm records:generate` | Rewrite `src/store.generated.ts` from the live store |
+| `pnpm check:store-registry` | Fail when this package and the store disagree |
+| `pnpm test` | The real-door suite |
+| `pnpm build` | tsup → `dist` (esm + cjs + d.ts), then the client boundary stamp |
+| `pnpm check:package` | build · exports agreement · publint · tarball canary |