@ai-matrx/records 0.87.32 → 0.92.1

package/CHANGELOG.md

@@ -1,5 +1,105 @@
 # Changelog — @ai-matrx/records
 
+## 0.92.1
+
+**`recordRead`'s version is opt-in: `recordRead({ record_id, withVersion: true })`.** 0.92.0 read the header on
+every call, so a screen that draws first and versions later (the record form) waited for the slower of the two.
+
+**Consumer action:** none for screens; a host that wants the version with the read passes `withVersion: true`.
+
+## 0.92.0
+
+**A member of an archived organization is told so.** Every store door used to refuse an archived organization with
+"You are not a member of that organization", even to its members. The store now says "This organization is archived"
+(same refusal code `door`, the store's sentence and restore hint carried verbatim) with DETAIL
+`organization_archived:<organization id>`. New `archivedOrganizationId(error)` (from `@ai-matrx/records` and
+`@ai-matrx/records/core`) reads that organization out so a screen can offer "Restore" (the owner's
+`iam.organization_restore` door). A non-member still gets the old sentence and `null` from it.
+
+**The withheld note is said once.** For a reader who may not see a confidential measure, `custom.record_aggregate`
+used to repeat the same `_withheld` explanation on every group row; the store now says it once (first row) and
+`liftWithheld` puts it on every row's `row.withheld`, so totals and charts read exactly what they read before.
+
+**Consumer action:** none. Hosts that read `measures._withheld` off the raw door (not through the client) must read it
+from the first row.
+
+## 0.92.0
+
+**New section `@ai-matrx/records/versions`** — the version rule for any screen a company builds, moved whole
+from `@ai-matrx/records-ui`: `useRecordVersions` / `useTableVersion`, the write doors that carry the version
+the person saw (`updateRecordAt`, `changeRecordsAt`, `movePipelineCardAt(s)`, `restoreAt`,
+`updateOnTheWinningVersion`), `askOnce` (one question in flight per client) and `refusal` (a refusal shaped
+like the store's own). React is the only peer it needs.
+
+**`recordRead({ record_id, withVersion: true })` answers `version`.** The read asks the record's header in the
+same round of requests, so a safe edit (`recordUpdate` with `expected_version`) needs no second call. `null`
+when the version could not be read (the record still comes back). Off by default, so a screen that draws
+before its version lands is never held back.
+
+**Consumer action:** none. Hosts that read a record and then asked `recordHeaders` for its version can use
+`read.data.version` instead.
+
+## 0.91.0
+
+**`typedAnswersFor(fields, values)` in `@ai-matrx/records/forms`** — what a stranger typed on a public form or
+booking page, turned into values against the Fields that page published, with one refusal sentence in question
+order (moved whole from the website's `features/unified-data/typedAnswers.ts`). Every public door a company builds
+coerces the same way the grid, the import and our own pages do.
+
+**Consumer action:** hosts with their own copy (the website's `typedAnswers.ts`) import
+`typedAnswersFor` from `@ai-matrx/records/forms` and delete the copy.
+
+## 0.90.0
+
+**New section `@ai-matrx/records/setup`** — `createRecords({ auth: sessionAuth(supabase), organizationId })`:
+one call that composes the typed client, live changes (one realtime manager over the session), search
+across tables, platform records and a slot for the host's associations store. Signing in is a port
+(`RecordsAuthPort`); an organization API key will plug in as a second mode without changing anything else.
+The README opens with a quick start a company follows to list, create, edit, archive and watch records.
+
+**Consumer action:** none.
+
+## 0.89.0
+
+**New section `@ai-matrx/records/forms`** — the form document (flows, looks, endings, jumps, embeds,
+the form doors' arguments) and which read a public address does, moved whole from `@ai-matrx/records-ui`
+(`forms.ts`, `publicBinding.ts`), so a company's own screens can build and run forms without ours.
+
+**New section `@ai-matrx/records/search`** — `searchRecords(dataSource, { search, tableIds?, organizationIds? })`
+and `listStoreRecordCandidates(dataSource, { search })`: search across every table the person can see
+through `custom.records_search` (never narrowed by the active organization), moved from the website.
+
+**Consumer action:** `@ai-matrx/records-ui` users need none. Hosts with their own copy of record search
+(the website's `storeRecordCandidates.ts`) call `listStoreRecordCandidates(supabase, args)` instead.
+
+## 0.88.1
+
+**One data engine instance across sections.** `records/react` carried its own private copy of
+`records/data/react` (its `DataPortContext` and host-event bus) because the build copies every module
+into each entry that reaches it. It now imports the published `records/data/react`, as `records/entity/react`
+does, so a `DataPortProvider` mounted from either section is the one every hook reads. The shared-state
+gate gained a census: each module that holds React context or page-local state (data-engine provider,
+seed provider, shape revisions) must live in exactly one section's dist files — proven red on a planted copy.
+
+**Consumer action:** none.
+
+## 0.88.0
+
+**New sections `@ai-matrx/records/entity` and `@ai-matrx/records/entity/react`** — the former
+`@ai-matrx/entity-data` package, moved in whole (same API, same behaviour): platform records (contacts,
+projects, tasks) through the entity doors, the entity `DataPort`, entity live notices, and the
+token-first hooks (`EntityDataProvider`, `useEntityList`, `useEntityWrite`, …). `records/entity/react`
+imports the published `records/react` and `records/data/react` instead of carrying a private copy, so
+the providers a host mounted are the ones it reads.
+
+The shared-state gate (`scripts/check-shared-state.mjs`, run on the packed tarball) now also proves an
+entity write's op id lands in the one op ledger (ESM and CJS) and that `entity/react` holds no private
+copy of the data-engine or seed providers.
+
+**Consumer action:** replace `@ai-matrx/entity-data`, `@ai-matrx/entity-data/core` and
+`@ai-matrx/entity-data/port` with `@ai-matrx/records/entity`, and `@ai-matrx/entity-data/react` with
+`@ai-matrx/records/entity/react`; then drop the `@ai-matrx/entity-data` dependency.
+
 ## 0.87.32
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

package/README.md

@@ -24,6 +24,69 @@ import {
 } from "@ai-matrx/records";
 ```
 
+## Quick start — our record store inside your own system
+
+Everything a company needs to list, create, edit, archive and watch records from its own screens or
+scripts, with none of ours. One package; each section loads only when imported.
+
+```sh
+npm install @ai-matrx/records @supabase/supabase-js
+```
+
+```ts
+import { createClient } from "@supabase/supabase-js";
+import { createRecords, sessionAuth } from "@ai-matrx/records/setup";
+import { ensureTable } from "@ai-matrx/records/core";
+
+// 1. Sign in. The database address is https://db.matrxserver.com; the publishable key is on your
+//    AI Matrx account page. Any supabase-js sign-in works (password, magic link, SSO, server cookies).
+const supabase = createClient("https://db.matrxserver.com", PUBLISHABLE_KEY);
+await supabase.auth.signInWithPassword({ email, password });
+
+// 2. One call. You choose the organization new records are saved in; reads span all of yours.
+const matrx = await createRecords({ auth: sessionAuth(supabase), organizationId: (orgs) => orgs[0] ?? null });
+
+// 3. A table (found by its slug, or made the first time), then records.
+const table = await ensureTable(matrx.records, { name: "Service callbacks", slug: "service_callbacks",
+  fields: [{ key: "caller", label: "Caller", type: "text" }, { key: "phone", label: "Phone", type: "phone" }] });
+if (!table.ok) throw new Error(table.error.message);
+const tableId = table.data;                 // the table id
+
+const created = await matrx.records.recordWrite({ table_id: tableId, data: { caller: "Marcus Delgado", phone: "+14155550178" } });
+const page    = await matrx.records.list({ table_id: tableId, limit: 50 });                  // { rows, total }
+const record_id = created.ok ? created.data : "";
+const read    = await matrx.records.recordRead({ record_id });                               // .data.document
+const heads   = await matrx.records.recordHeaders({ ids: [record_id] });                     // .data[0].version
+const expectedVersion = heads.ok ? heads.data[0]?.version : undefined;
+const edited  = await matrx.records.recordUpdate({ record_id, patch: { phone: "+14155550199" }, expectedVersion }); // answers the new version
+// Always send expectedVersion: a colleague's newer edit is then refused (`stale_write`, field by field), never overwritten.
+const archived = await matrx.records.recordDelete({ record_id });                            // soft: recordRestore brings it back
+
+// 4. Live: other people's changes to this table (this setup's own writes are not echoed back).
+const stop = matrx.watch(tableId, { records: (ids) => console.log("changed", ids) });
+
+// 5. Search across every table you can see; platform records (contacts…) through matrx.entities.
+const hits = await matrx.search({ search: "Delgado" });
+
+stop(); matrx.close(); // a script closes the live socket before it exits
+```
+
+Every call answers `{ ok: true, data } | { ok: false, error }` — the store's own sentence, never a
+throw. React hosts add `@ai-matrx/records/react` or `@ai-matrx/records/data/react` hooks on the same
+client; `@ai-matrx/records-ui` is our optional set of screens. Organization API keys plug into `auth`
+as a second mode (planned); today `auth` is a signed-in session.
+
+| Section | What |
+|---|---|
+| `records/setup` | `createRecords`, `sessionAuth` — the one call above |
+| `records/core` | the typed client over every door (tables, records, versions, views, forms, totals) |
+| `records/realtime` | the live-changes port setup uses |
+| `records/search` | `searchRecords`, `listStoreRecordCandidates` |
+| `records/forms` | the form document, embeds and which read a public address does |
+| `records/entity`, `records/entity/react` | platform records (contacts, projects, tasks) |
+| `records/data`, `records/data/react` | one data port and TanStack hooks over custom tables and entities |
+| `records/react` | provider + hooks over the client |
+
 ## /core — the typed client over the doors
 
 ```ts
@@ -278,6 +341,58 @@ 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.
 
+## /entity — platform records (contacts, projects, tasks) through the same port
+Platform records (contacts, projects, tasks…) through the same `DataPort` an Applet reads a custom
+table with. A thin typed client over the store's entity doors, and a host `DataPort` for entity
+aliases, and token-first React hooks over records' one data engine (`@ai-matrx/records/data/react`).
+
+**Reads and writes.** `create` saves into the active organization the host names (none → refused
+`organization_required`), `update` sends the version the person saw (a stale one is refused with the
+store's sentence), `archive` / `restore` move a row to the trash and back. **Lists are live** when the host passes `realtime: createEntityRealtime({ manager })`
+(and `organization`, the active one): other people's changes arrive as `rows:<alias>` events naming the ids.
+
+```ts
+import { createEntityDataPort } from "@ai-matrx/records/entity";
+import { DataPortProvider, hostEvents, useDataRows } from "@ai-matrx/records/data/react";
+
+const port = createEntityDataPort({
+  dataSource: supabase, // the signed-in person's supabase-js client
+  aliases: { contacts: { kind: "entity", token: "party", organizationId } },
+});
+
+// in React:
+// <DataPortProvider port={port} events={hostEvents(port)} portKey="applet-1" queryClient={qc}>
+//   const { rows, hasMore, loadMore, error } = useDataRows("contacts", { org: organizationId, sort: [{ column: "display_name" }] });
+```
+
+In a React app, name the type and let the engine do the rest:
+
+```tsx
+import { EntityDataProvider, useEntityList, useEntityWrite } from "@ai-matrx/records/entity/react";
+
+// once, high: <EntityDataProvider dataSource={supabase} activeOrganizationId={activeOrg}>…
+const contacts = useEntityList("party", { where: [{ column: "last_name", op: "eq", value: "Ellis" }] });
+const write = useEntityWrite("party");
+await write.update(contacts.rows[0]._id, { first_name: "Ada" }); // drawn at once, rolled back on refusal
+```
+
+### Entries
+
+| Entry | What |
+|---|---|
+| `@ai-matrx/records/entity` | `createEntityClient({ dataSource })` → `list`, `get`, `columns`, `insert`, `update`, `archive`, `unarchive`; `toWire`; `mapEntityError`; `createEntityDataPort({ client \| dataSource, aliases, activeOrganizationId })` → `HostDataPort` + `describe`; `createEntityRealtime` |
+| `@ai-matrx/records/entity/react` | `EntityDataProvider`, `useEntityList`, `useEntityColumns`, `useEntityType`, `useEntityRow`, `useEntityWrite` |
+
+### Behaviour worth knowing
+
+- The lane defaults to the type's own landing lane, decided by the store; `org` is a filter and never a lock.
+- Paging is keyset: the cursor is the store's `next_after`.
+- A filter or sort the store does not offer yet is refused by name with the store's sentence, never emulated in the browser.
+- Custom fields read from `row._custom` and filter as `_custom.<key>`; a field the person may not read arrives `null`.
+- A total that stopped at the store's count cap is reported as `null` (unknown), never as a wrong number.
+
+Local mechanics: `src/entity/FEATURE.md`. Formerly the package `@ai-matrx/entity-data` (deprecated; same API, renamed imports: `/core` and `/port` → `records/entity`, `/react` → `records/entity/react`).
+
 ## Drill-down — declared definitions
 
 A server drill (`platform.drill_describe` / `platform.drill_ask`) answers a standard table from

package/dist/{client-E0VQ0NPO.d.ts → client-Cn3odIIB.d.cts}

@@ -1,8 +1,11 @@
-import { R as RelationCoordinate, C as ChoiceNudge, T as TableArchiveProgress, a as TableRestoreProgress, b as TableDuplicateProgress, c as TableDuplicated, d as TableCopyInProgress, A as ArchiveLane, e as ArchivedRow, f as Table, g as TableHome, h as TableMoved, i as ChoiceUsage, j as ChoiceRehome, k as ChoiceCellBack, l as ChoicesRehomed, m as TableCapacity, F as FieldDrift, n as FieldRetyped, o as RecordsMerged, M as MigrationUndone, p as RelationWordsManyArgs, q as RelationIcons, r as ReverseColumn, s as ReverseLinksManyArgs, t as ReverseLinks, u as ReverseLinksFieldsArgs, S as SourceArchived, v as TableKindFacts, w as TableLevelFacts, x as TableReaderRule, y as TableLevelSet, E as EntityTableFacts, z as EntityFieldsAcross, N as NewEntityFieldDeclaration, B as EntityFieldRights, D as EntityRecordRead, G as EntityBackLinks, H as EntityRowWritten, I as EntityRecordsFound, P as Pipeline, J as PipelineColumn, K as PipelineVerdict, L as PipelineMoveResult, O as PipelineMoveManyItem, Q as PipelineMoveMany, U as PipelineSpec, V as PipelineDeclared, W as StageRuleOnFail, X as StageRuleEnforcement, Y as StagePending, Z as StagePendingOnBoard, _ as PipelineGate, $ as PipelineGatePreview, a0 as FormLookOptions, a1 as ImportPlan, a2 as ImportPolicy, a3 as ImportOpened, a4 as ImportColumnsDeclared, a5 as ImportBatchResult, a6 as ImportFinished, a7 as ImportReport, a8 as ImportRun, a9 as InboundDeclared, aa as InboundAddress, ab as PortalSummary, ac as PortalArchiveFilter, ad as PortalArchiveAnswer, ae as FormArchiveAnswer, af as ArchivedForm, ag as ArchivedChecklistTemplate, ah as TableRowDefaults, ai as TableRowDefaultsPatch, aj as RowDefaultsApplied, ak as RecordRowControls, al as PortalTableRef, am as PortalCard, an as PortalConfigInput, ao as PortalFormSpec, ap as PortalFormAnswer, aq as PortalInvitation, ar as PortalRevocation, as as PortalPreviewRow, at as CaptureSheetSummary, au as CaptureSheetFace, av as CaptureFileRef, aw as CaptureOutcome, ax as EnrichmentSummary, ay as EnrichDeclared, az as EnrichDueRow, aA as EnrichCell, aB as EnrichRun, aC as DrillSource, aD as DrillDefinition, aE as DrillQuestion, aF as DrillAnswer, aG as DrillRowsPage, aH as DocToken, aI as DocUnresolvedToken, aJ as DocTemplateRow, aK as DocRenderRow, aL as DocSignatureRow, aM as RecordHistoryEntry, aN as RecordScopeContext, aO as ConversationScope, aP as ConversationScopeContext, aQ as FieldHistoryEntry, aR as RestorePreview, aS as RestoreResult, aT as CommentThreadRead, aU as CommentWritten, aV as AnonTokenBinding, aW as ChecklistSpec, aX as ChecklistDeclared, aY as ChecklistTemplateSummary, aZ as ChecklistTemplateShape, a_ as ChecklistRunStarted, a$ as ChecklistRunStep, b0 as ChecklistRunSummary, b1 as ChecklistStepCompleted, b2 as WorkState, b3 as WorkGraph, b4 as WorkInstantiation, b5 as WorkTurn, b6 as WorkAssignmentField, b7 as WorkSlotHold, b8 as WorkInboxView, b9 as WorkInboxItem, ba as InboxStateChange, bb as InboxCounts, bc as WorkListFlavour, bd as WorkListItem, be as WorkAssignment, bf as WorkRecordState, bg as WorkApprover, bh as WorkChange, bi as WorkApprovalFiled, bj as WorkApprovalDecision, bk as WorkDecideManyItem, bl as WorkDecideMany, bm as ExternalPrincipalCard, bn as PublishBinding, bo as ResolvedPublishBinding, bp as ResolvedPublishBindingKind, bq as MyLevel, br as DecorationPath, bs as TableDecorations, bt as GridLayout, bu as FormulaParse, bv as FormulaPreview, bw as RowAction, bx as ActionRunResult, by as AutomationSpec, bz as AutomationDeclared, bA as AutomationList, bB as AutomationFlipped, bC as AutomationRuns, bD as RecordEvent, bE as TableWebhookDeclared, bF as TableWebhook, bG as IoExportPage, bH as TableListEntry, bI as DataHomeTable, bJ as TableSyncSpec, bK as TableSyncResult, bL as TableRowCount, bM as RecordHeader, bN as OutsideShareAnswer, bO as ViewOrderSet } from './table-kind-xKxTHtrV.js';
-import { d as StoreFilter, F as FormSummary, B as BookingSummary, e as BookingAvailability, f as BookingDeclared, g as FormRoute, h as FormResults, i as DashboardSummary, j as DashboardBlock, R as RecordFilter, k as AggregateCompare, c as AggregateBucket, l as DashboardRunResult, m as StuckRow, b as AggregateMeasure, n as AggregateRow, o as Subscription, M as MySubscription, p as SubscriptionSpec, q as DigestPreview, r as SavedViewRow, s as SavedViewSpecIn, t as RowTemplateRow } from './subscription-D7KQBHXN.js';
-import { b as Field, c as FieldPatch, N as NewFieldDeclaration, R as RelationNamesAnswer, d as FieldDuplicated, e as FieldProposal, T as TableProposal, B as ButtonPressed } from './field-BPABOJ2Y.js';
-import { f as Timestamp, U as Uuid, g as RecordsErrorCode, h as RecordDocument, i as RecordsResult, j as RecordChange, k as RecordChangeResult, l as RecordGraphWritten, m as RecordRead, n as ReadRow, o as RecordPageSort, p as RecordPage, q as RecordKeysetPage, r as StoredRecord, s as RecordRevision, t as ReadValue, R as RecordsError, W as WriteConflict } from './record-DpB2QgAZ.js';
-import { a as RecordsConfig } from './ports-TMWX-t9l.js';
+import { C as ChoiceNudge, T as TableArchiveProgress, a as TableRestoreProgress, b as TableDuplicateProgress, c as TableDuplicated, d as TableCopyInProgress, A as ArchiveLane, e as ArchivedRow, f as Table, g as TableHome, h as TableMoved, i as ChoiceUsage, j as ChoiceRehome, k as ChoiceCellBack, l as ChoicesRehomed, m as TableCapacity, F as FieldDrift, n as FieldRetyped, R as RecordsMerged, M as MigrationUndone, o as TableKindFacts, p as TableLevelFacts, q as TableReaderRule, r as TableLevelSet, E as EntityTableFacts, s as EntityFieldsAcross, N as NewEntityFieldDeclaration, t as EntityFieldRights, u as EntityRecordRead, v as EntityBackLinks, w as EntityRowWritten, x as EntityRecordsFound, P as Pipeline, y as PipelineColumn, z as PipelineVerdict, B as PipelineMoveResult, D as PipelineMoveManyItem, G as PipelineMoveMany, H as PipelineSpec, I as PipelineDeclared, S as StageRuleOnFail, J as StageRuleEnforcement, K as StagePending, L as StagePendingOnBoard, O as PipelineGate, Q as PipelineGatePreview, U as ImportPlan, V as ImportPolicy, W as ImportOpened, X as ImportColumnsDeclared, Y as ImportBatchResult, Z as ImportFinished, _ as ImportReport, $ as ImportRun, a0 as InboundDeclared, a1 as InboundAddress, a2 as FormArchiveAnswer, a3 as ArchivedForm, a4 as ArchivedChecklistTemplate, a5 as TableRowDefaults, a6 as TableRowDefaultsPatch, a7 as RowDefaultsApplied, a8 as RecordRowControls, a9 as CaptureSheetSummary, aa as CaptureSheetFace, ab as CaptureFileRef, ac as CaptureOutcome, ad as EnrichmentSummary, ae as EnrichDeclared, af as EnrichDueRow, ag as EnrichCell, ah as EnrichRun, ai as DrillSource, aj as DrillDefinition, ak as DrillQuestion, al as DrillAnswer, am as DrillRowsPage, an as DocToken, ao as DocUnresolvedToken, ap as DocTemplateRow, aq as DocRenderRow, ar as DocSignatureRow, as as RecordHistoryEntry, at as RecordScopeContext, au as ConversationScope, av as ConversationScopeContext, aw as FieldHistoryEntry, ax as RestorePreview, ay as RestoreResult, az as CommentThreadRead, aA as CommentWritten, aB as AnonTokenBinding, aC as ChecklistSpec, aD as ChecklistDeclared, aE as ChecklistTemplateSummary, aF as ChecklistTemplateShape, aG as ChecklistRunStarted, aH as ChecklistRunStep, aI as ChecklistRunSummary, aJ as ChecklistStepCompleted, aK as WorkState, aL as WorkGraph, aM as WorkInstantiation, aN as WorkTurn, aO as WorkAssignmentField, aP as WorkSlotHold, aQ as WorkInboxView, aR as WorkInboxItem, aS as InboxStateChange, aT as InboxCounts, aU as WorkListFlavour, aV as WorkListItem, aW as WorkAssignment, aX as WorkRecordState, aY as WorkApprover, aZ as WorkChange, a_ as WorkApprovalFiled, a$ as WorkApprovalDecision, b0 as WorkDecideManyItem, b1 as WorkDecideMany, b2 as ExternalPrincipalCard, b3 as PublishBinding, b4 as ResolvedPublishBinding, b5 as ResolvedPublishBindingKind, b6 as MyLevel, b7 as DecorationPath, b8 as TableDecorations, b9 as GridLayout, ba as FormulaParse, bb as FormulaPreview, bc as RowAction, bd as ActionRunResult, be as AutomationSpec, bf as AutomationDeclared, bg as AutomationList, bh as AutomationFlipped, bi as AutomationRuns, bj as RecordEvent, bk as TableWebhookDeclared, bl as TableWebhook, bm as IoExportPage, bn as TableListEntry, bo as DataHomeTable, bp as TableSyncSpec, bq as TableSyncResult, br as TableRowCount, bs as RecordHeader, bt as OutsideShareAnswer, bu as ViewOrderSet } from './table-kind-DzctQ7dO.cjs';
+import { d as StoreFilter, e as DashboardSummary, f as DashboardBlock, R as RecordFilter, g as AggregateCompare, c as AggregateBucket, h as DashboardRunResult, i as StuckRow, b as AggregateMeasure, j as AggregateRow, k as Subscription, M as MySubscription, l as SubscriptionSpec, m as DigestPreview, n as SavedViewRow, o as SavedViewSpecIn, p as RowTemplateRow } from './subscription-CdoI-UaB.cjs';
+import { R as RelationCoordinate, a as RelationWordsManyArgs, b as RelationIcons, c as ReverseColumn, d as ReverseLinksManyArgs, e as ReverseLinks, f as ReverseLinksFieldsArgs, S as SourceArchived } from './relation-8vAWCa67.cjs';
+import { b as Field, c as FieldPatch, N as NewFieldDeclaration, R as RelationNamesAnswer, d as FieldDuplicated, e as FieldProposal, T as TableProposal, B as ButtonPressed } from './field-CCY1rG9l.cjs';
+import { F as FormSummary, B as BookingSummary, a as BookingAvailability, b as BookingDeclared, c as FormRoute, d as FormResults } from './rule-wHI5B0Ka.cjs';
+import { F as FormLookOptions, P as PortalSummary, a as PortalArchiveFilter, b as PortalArchiveAnswer, c as PortalTableRef, d as PortalCard, e as PortalConfigInput, f as PortalFormSpec, g as PortalFormAnswer, h as PortalInvitation, i as PortalRevocation, j as PortalPreviewRow } from './portal-DRdmZ-xv.cjs';
+import { T as Timestamp, U as Uuid, k as RecordsErrorCode, l as RecordDocument, R as RecordsResult, m as RecordChange, n as RecordChangeResult, o as RecordGraphWritten, p as RecordRead, q as ReadRow, r as RecordPageSort, s as RecordPage, t as RecordKeysetPage, u as StoredRecord, v as RecordRevision, w as ReadValue, a as RecordsError, W as WriteConflict } from './record-BwCf9wKW.cjs';
+import { a as RecordsConfig } from './ports-s0D2jvqn.cjs';
 
 /**
  * DOOR-8. As-of on EITHER clock, and they are different questions:
@@ -372,6 +375,8 @@ interface RecordsClient {
     recordRead(args: {
         record_id: Uuid;
         withComputed?: boolean;
+        /** Also answer `version` (read in the same round, so the read takes as long as the slower of the two). */
+        withVersion?: boolean;
         organization_id?: Uuid | null;
     }): Promise<RecordsResult<RecordRead>>;
     /**

package/dist/{client-C3ZZNfGH.d.cts → client-Dzd8gtAo.d.ts}

@@ -1,8 +1,11 @@
-import { R as RelationCoordinate, C as ChoiceNudge, T as TableArchiveProgress, a as TableRestoreProgress, b as TableDuplicateProgress, c as TableDuplicated, d as TableCopyInProgress, A as ArchiveLane, e as ArchivedRow, f as Table, g as TableHome, h as TableMoved, i as ChoiceUsage, j as ChoiceRehome, k as ChoiceCellBack, l as ChoicesRehomed, m as TableCapacity, F as FieldDrift, n as FieldRetyped, o as RecordsMerged, M as MigrationUndone, p as RelationWordsManyArgs, q as RelationIcons, r as ReverseColumn, s as ReverseLinksManyArgs, t as ReverseLinks, u as ReverseLinksFieldsArgs, S as SourceArchived, v as TableKindFacts, w as TableLevelFacts, x as TableReaderRule, y as TableLevelSet, E as EntityTableFacts, z as EntityFieldsAcross, N as NewEntityFieldDeclaration, B as EntityFieldRights, D as EntityRecordRead, G as EntityBackLinks, H as EntityRowWritten, I as EntityRecordsFound, P as Pipeline, J as PipelineColumn, K as PipelineVerdict, L as PipelineMoveResult, O as PipelineMoveManyItem, Q as PipelineMoveMany, U as PipelineSpec, V as PipelineDeclared, W as StageRuleOnFail, X as StageRuleEnforcement, Y as StagePending, Z as StagePendingOnBoard, _ as PipelineGate, $ as PipelineGatePreview, a0 as FormLookOptions, a1 as ImportPlan, a2 as ImportPolicy, a3 as ImportOpened, a4 as ImportColumnsDeclared, a5 as ImportBatchResult, a6 as ImportFinished, a7 as ImportReport, a8 as ImportRun, a9 as InboundDeclared, aa as InboundAddress, ab as PortalSummary, ac as PortalArchiveFilter, ad as PortalArchiveAnswer, ae as FormArchiveAnswer, af as ArchivedForm, ag as ArchivedChecklistTemplate, ah as TableRowDefaults, ai as TableRowDefaultsPatch, aj as RowDefaultsApplied, ak as RecordRowControls, al as PortalTableRef, am as PortalCard, an as PortalConfigInput, ao as PortalFormSpec, ap as PortalFormAnswer, aq as PortalInvitation, ar as PortalRevocation, as as PortalPreviewRow, at as CaptureSheetSummary, au as CaptureSheetFace, av as CaptureFileRef, aw as CaptureOutcome, ax as EnrichmentSummary, ay as EnrichDeclared, az as EnrichDueRow, aA as EnrichCell, aB as EnrichRun, aC as DrillSource, aD as DrillDefinition, aE as DrillQuestion, aF as DrillAnswer, aG as DrillRowsPage, aH as DocToken, aI as DocUnresolvedToken, aJ as DocTemplateRow, aK as DocRenderRow, aL as DocSignatureRow, aM as RecordHistoryEntry, aN as RecordScopeContext, aO as ConversationScope, aP as ConversationScopeContext, aQ as FieldHistoryEntry, aR as RestorePreview, aS as RestoreResult, aT as CommentThreadRead, aU as CommentWritten, aV as AnonTokenBinding, aW as ChecklistSpec, aX as ChecklistDeclared, aY as ChecklistTemplateSummary, aZ as ChecklistTemplateShape, a_ as ChecklistRunStarted, a$ as ChecklistRunStep, b0 as ChecklistRunSummary, b1 as ChecklistStepCompleted, b2 as WorkState, b3 as WorkGraph, b4 as WorkInstantiation, b5 as WorkTurn, b6 as WorkAssignmentField, b7 as WorkSlotHold, b8 as WorkInboxView, b9 as WorkInboxItem, ba as InboxStateChange, bb as InboxCounts, bc as WorkListFlavour, bd as WorkListItem, be as WorkAssignment, bf as WorkRecordState, bg as WorkApprover, bh as WorkChange, bi as WorkApprovalFiled, bj as WorkApprovalDecision, bk as WorkDecideManyItem, bl as WorkDecideMany, bm as ExternalPrincipalCard, bn as PublishBinding, bo as ResolvedPublishBinding, bp as ResolvedPublishBindingKind, bq as MyLevel, br as DecorationPath, bs as TableDecorations, bt as GridLayout, bu as FormulaParse, bv as FormulaPreview, bw as RowAction, bx as ActionRunResult, by as AutomationSpec, bz as AutomationDeclared, bA as AutomationList, bB as AutomationFlipped, bC as AutomationRuns, bD as RecordEvent, bE as TableWebhookDeclared, bF as TableWebhook, bG as IoExportPage, bH as TableListEntry, bI as DataHomeTable, bJ as TableSyncSpec, bK as TableSyncResult, bL as TableRowCount, bM as RecordHeader, bN as OutsideShareAnswer, bO as ViewOrderSet } from './table-kind-BZu8mtND.cjs';
-import { d as StoreFilter, F as FormSummary, B as BookingSummary, e as BookingAvailability, f as BookingDeclared, g as FormRoute, h as FormResults, i as DashboardSummary, j as DashboardBlock, R as RecordFilter, k as AggregateCompare, c as AggregateBucket, l as DashboardRunResult, m as StuckRow, b as AggregateMeasure, n as AggregateRow, o as Subscription, M as MySubscription, p as SubscriptionSpec, q as DigestPreview, r as SavedViewRow, s as SavedViewSpecIn, t as RowTemplateRow } from './subscription-BD9DnJxX.cjs';
-import { b as Field, c as FieldPatch, N as NewFieldDeclaration, R as RelationNamesAnswer, d as FieldDuplicated, e as FieldProposal, T as TableProposal, B as ButtonPressed } from './field-BanTVGK2.cjs';
-import { f as Timestamp, U as Uuid, g as RecordsErrorCode, h as RecordDocument, i as RecordsResult, j as RecordChange, k as RecordChangeResult, l as RecordGraphWritten, m as RecordRead, n as ReadRow, o as RecordPageSort, p as RecordPage, q as RecordKeysetPage, r as StoredRecord, s as RecordRevision, t as ReadValue, R as RecordsError, W as WriteConflict } from './record-DpB2QgAZ.cjs';
-import { a as RecordsConfig } from './ports-D8-iuY1P.cjs';
+import { C as ChoiceNudge, T as TableArchiveProgress, a as TableRestoreProgress, b as TableDuplicateProgress, c as TableDuplicated, d as TableCopyInProgress, A as ArchiveLane, e as ArchivedRow, f as Table, g as TableHome, h as TableMoved, i as ChoiceUsage, j as ChoiceRehome, k as ChoiceCellBack, l as ChoicesRehomed, m as TableCapacity, F as FieldDrift, n as FieldRetyped, R as RecordsMerged, M as MigrationUndone, o as TableKindFacts, p as TableLevelFacts, q as TableReaderRule, r as TableLevelSet, E as EntityTableFacts, s as EntityFieldsAcross, N as NewEntityFieldDeclaration, t as EntityFieldRights, u as EntityRecordRead, v as EntityBackLinks, w as EntityRowWritten, x as EntityRecordsFound, P as Pipeline, y as PipelineColumn, z as PipelineVerdict, B as PipelineMoveResult, D as PipelineMoveManyItem, G as PipelineMoveMany, H as PipelineSpec, I as PipelineDeclared, S as StageRuleOnFail, J as StageRuleEnforcement, K as StagePending, L as StagePendingOnBoard, O as PipelineGate, Q as PipelineGatePreview, U as ImportPlan, V as ImportPolicy, W as ImportOpened, X as ImportColumnsDeclared, Y as ImportBatchResult, Z as ImportFinished, _ as ImportReport, $ as ImportRun, a0 as InboundDeclared, a1 as InboundAddress, a2 as FormArchiveAnswer, a3 as ArchivedForm, a4 as ArchivedChecklistTemplate, a5 as TableRowDefaults, a6 as TableRowDefaultsPatch, a7 as RowDefaultsApplied, a8 as RecordRowControls, a9 as CaptureSheetSummary, aa as CaptureSheetFace, ab as CaptureFileRef, ac as CaptureOutcome, ad as EnrichmentSummary, ae as EnrichDeclared, af as EnrichDueRow, ag as EnrichCell, ah as EnrichRun, ai as DrillSource, aj as DrillDefinition, ak as DrillQuestion, al as DrillAnswer, am as DrillRowsPage, an as DocToken, ao as DocUnresolvedToken, ap as DocTemplateRow, aq as DocRenderRow, ar as DocSignatureRow, as as RecordHistoryEntry, at as RecordScopeContext, au as ConversationScope, av as ConversationScopeContext, aw as FieldHistoryEntry, ax as RestorePreview, ay as RestoreResult, az as CommentThreadRead, aA as CommentWritten, aB as AnonTokenBinding, aC as ChecklistSpec, aD as ChecklistDeclared, aE as ChecklistTemplateSummary, aF as ChecklistTemplateShape, aG as ChecklistRunStarted, aH as ChecklistRunStep, aI as ChecklistRunSummary, aJ as ChecklistStepCompleted, aK as WorkState, aL as WorkGraph, aM as WorkInstantiation, aN as WorkTurn, aO as WorkAssignmentField, aP as WorkSlotHold, aQ as WorkInboxView, aR as WorkInboxItem, aS as InboxStateChange, aT as InboxCounts, aU as WorkListFlavour, aV as WorkListItem, aW as WorkAssignment, aX as WorkRecordState, aY as WorkApprover, aZ as WorkChange, a_ as WorkApprovalFiled, a$ as WorkApprovalDecision, b0 as WorkDecideManyItem, b1 as WorkDecideMany, b2 as ExternalPrincipalCard, b3 as PublishBinding, b4 as ResolvedPublishBinding, b5 as ResolvedPublishBindingKind, b6 as MyLevel, b7 as DecorationPath, b8 as TableDecorations, b9 as GridLayout, ba as FormulaParse, bb as FormulaPreview, bc as RowAction, bd as ActionRunResult, be as AutomationSpec, bf as AutomationDeclared, bg as AutomationList, bh as AutomationFlipped, bi as AutomationRuns, bj as RecordEvent, bk as TableWebhookDeclared, bl as TableWebhook, bm as IoExportPage, bn as TableListEntry, bo as DataHomeTable, bp as TableSyncSpec, bq as TableSyncResult, br as TableRowCount, bs as RecordHeader, bt as OutsideShareAnswer, bu as ViewOrderSet } from './table-kind-i3lZJa3f.js';
+import { d as StoreFilter, e as DashboardSummary, f as DashboardBlock, R as RecordFilter, g as AggregateCompare, c as AggregateBucket, h as DashboardRunResult, i as StuckRow, b as AggregateMeasure, j as AggregateRow, k as Subscription, M as MySubscription, l as SubscriptionSpec, m as DigestPreview, n as SavedViewRow, o as SavedViewSpecIn, p as RowTemplateRow } from './subscription-BynsG1K6.js';
+import { R as RelationCoordinate, a as RelationWordsManyArgs, b as RelationIcons, c as ReverseColumn, d as ReverseLinksManyArgs, e as ReverseLinks, f as ReverseLinksFieldsArgs, S as SourceArchived } from './relation-eLMgv_dV.js';
+import { b as Field, c as FieldPatch, N as NewFieldDeclaration, R as RelationNamesAnswer, d as FieldDuplicated, e as FieldProposal, T as TableProposal, B as ButtonPressed } from './field-enufS5ry.js';
+import { F as FormSummary, B as BookingSummary, a as BookingAvailability, b as BookingDeclared, c as FormRoute, d as FormResults } from './rule-D9yNiorf.js';
+import { F as FormLookOptions, P as PortalSummary, a as PortalArchiveFilter, b as PortalArchiveAnswer, c as PortalTableRef, d as PortalCard, e as PortalConfigInput, f as PortalFormSpec, g as PortalFormAnswer, h as PortalInvitation, i as PortalRevocation, j as PortalPreviewRow } from './portal-or_f7BkT.js';
+import { T as Timestamp, U as Uuid, k as RecordsErrorCode, l as RecordDocument, R as RecordsResult, m as RecordChange, n as RecordChangeResult, o as RecordGraphWritten, p as RecordRead, q as ReadRow, r as RecordPageSort, s as RecordPage, t as RecordKeysetPage, u as StoredRecord, v as RecordRevision, w as ReadValue, a as RecordsError, W as WriteConflict } from './record-BwCf9wKW.js';
+import { a as RecordsConfig } from './ports-BeOgjwYl.js';
 
 /**
  * DOOR-8. As-of on EITHER clock, and they are different questions:
@@ -372,6 +375,8 @@ interface RecordsClient {
     recordRead(args: {
         record_id: Uuid;
         withComputed?: boolean;
+        /** Also answer `version` (read in the same round, so the read takes as long as the slower of the two). */
+        withVersion?: boolean;
         organization_id?: Uuid | null;
     }): Promise<RecordsResult<RecordRead>>;
     /**

package/dist/core/index.cjs

@@ -120,6 +120,7 @@ __export(core_exports, {
   announceRecordChanged: () => announceRecordChanged,
   announceTableStructureChanged: () => announceTableStructureChanged,
   archivedByLine: () => archivedByLine,
+  archivedOrganizationId: () => archivedOrganizationId,
   archivedWhen: () => archivedWhen,
   asChoiceNudge: () => asChoiceNudge,
   asPermissionLevel: () => asPermissionLevel,
@@ -1627,9 +1628,18 @@ function stableFilterKey(filter) {
   return `{${parts.join(",")}}`;
 }
 function liftWithheld(rows2) {
+  let shared;
+  for (const row of rows2) {
+    const m = (row.measures ?? {})["_withheld"];
+    if (m !== void 0 && m !== null && typeof m === "object") {
+      shared = m;
+      break;
+    }
+  }
   return rows2.map((row) => {
     const measures = row.measures ?? {};
-    const marker = measures["_withheld"];
+    const own = measures["_withheld"];
+    const marker = own !== void 0 && own !== null && typeof own === "object" ? own : shared;
     const rowCount = row.row_count ?? 0;
     if (marker === void 0 || marker === null || typeof marker !== "object") {
       return rowCount === row.row_count ? row : { ...row, row_count: rowCount };
@@ -2472,6 +2482,11 @@ function staleWriteDetail(error) {
     contested_fields: detail.contested_fields ?? {}
   };
 }
+function archivedOrganizationId(error) {
+  if (error.code !== "door" || typeof error.detail !== "string") return null;
+  const m = /^organization_archived:([0-9a-f-]{36})$/i.exec(error.detail.trim());
+  return m ? m[1] : null;
+}
 
 // src/relation.ts
 var import_uuid4 = require("@ai-matrx/kit/uuid");
@@ -6883,24 +6898,27 @@ function createRecordsClient(given) {
       if (!pass.ok) return pass;
       return carryOnCopy(pass.data, onProgress);
     },
-    async recordRead({ record_id, withComputed = false, organization_id }) {
+    async recordRead({ record_id, withComputed = false, withVersion = false, organization_id }) {
       if (organization_id && organization_id !== org) {
-        return clientFor(organization_id).recordRead({ record_id, withComputed, organization_id });
+        return clientFor(organization_id).recordRead({ record_id, withComputed, withVersion, organization_id });
       }
       if (readOrgs(organization_id).length > 1) {
         return openInOwnOrg(
           record_id,
           organization_id,
-          (sub) => sub.recordRead({ record_id, withComputed, organization_id: sub.config.organizationId }),
+          (sub) => sub.recordRead({ record_id, withComputed, withVersion, organization_id: sub.config.organizationId }),
           () => true
         );
       }
-      const door = await callDoor(
-        DOORS.readRecord,
-        { p_organization_id: org, p_record_id: record_id },
-        "recordRead"
-      );
+      const [door, header] = await Promise.all([
+        callDoor(DOORS.readRecord, { p_organization_id: org, p_record_id: record_id }, "recordRead"),
+        // A version that cannot be read never takes the record away: it comes back as null.
+        withVersion ? callDoor(DOORS.recordHeaders, { p_organization_id: org, p_ids: [record_id] }, "recordRead.version").catch(
+          () => null
+        ) : Promise.resolve(null)
+      ]);
       if (!door.ok) return err(door.error);
+      const version = header && header.ok ? header.data?.find((h) => h.id === record_id)?.version ?? null : null;
       const { document, hidden } = unfold(door.data);
       let computed = [];
       let computedUnavailable = null;
@@ -6913,7 +6931,7 @@ function createRecordsClient(given) {
         if (provenance.ok) computed = provenance.data ?? [];
         else computedUnavailable = provenance.error;
       }
-      return ok({ record_id, document, hidden, computed, computedUnavailable });
+      return ok({ record_id, document, hidden, computed, computedUnavailable, ...withVersion ? { version } : {} });
     },
     async listByIds({ table_id, ids }) {
       if (ids.length === 0) return ok([]);