@ai-matrx/records 0.87.32 → 0.92.0

package/dist/realtime/index.d.cts

@@ -1,7 +1,7 @@
 import * as _ai_matrx_realtime from '@ai-matrx/realtime';
 import { RealtimeManager, ChannelSpec } from '@ai-matrx/realtime';
-import { R as RecordsRealtimePort } from '../ports-D8-iuY1P.cjs';
-import '../record-DpB2QgAZ.cjs';
+import { R as RecordsRealtimePort } from '../ports-DSU2RsR6.cjs';
+import '../record-BQi92d4-.cjs';
 
 /**
  * The topic is a CONTRACT WITH THE DATABASE (a Postgres trigger writes it, an RLS policy parses it),

package/dist/realtime/index.d.ts

@@ -1,7 +1,7 @@
 import * as _ai_matrx_realtime from '@ai-matrx/realtime';
 import { RealtimeManager, ChannelSpec } from '@ai-matrx/realtime';
-import { R as RecordsRealtimePort } from '../ports-TMWX-t9l.js';
-import '../record-DpB2QgAZ.js';
+import { R as RecordsRealtimePort } from '../ports-BWtxAnXh.js';
+import '../record-BQi92d4-.js';
 
 /**
  * The topic is a CONTRACT WITH THE DATABASE (a Postgres trigger writes it, an RLS policy parses it),

package/dist/{record-DpB2QgAZ.d.cts → record-BQi92d4-.d.cts}

@@ -6180,6 +6180,12 @@ interface RecordRead {
      * was never asked for).
      */
     computedUnavailable?: RecordsError | null;
+    /**
+     * The version this read saw, so a safe edit (`recordUpdate` with `expected_version`) needs no
+     * second call. Read beside the document in the same round of requests; `null` when the store
+     * could not answer it (a write then refuses as "version unread", never as last-write-wins).
+     */
+    version?: number | null;
 }
 
-export { KERNEL_TABLES as $, type Actor as A, ABSENCE_REASONS as B, type ComputeOn as C, type DeclarableFieldKind as D, ACTOR_VOCABULARY as E, type FieldSource as F, type AbsenceReason as G, type HiddenFieldNotice as H, COMPUTE_ON as I, CONTEXT_POLICIES as J, DECLARABLE_FIELD_KINDS as K, DELIVERIES as L, type Delivery as M, ENTITY_TOKENS as N, type OnDelete as O, type PgError as P, type EntityToken as Q, type RecordsError as R, type StorageMode as S, type TableType as T, type Uuid as U, FIELD_SENSITIVITIES as V, type WriteConflict as W, FIELD_SOURCES as X, FRESHNESS as Y, type ForbiddenEnvelopeWord as Z, type Freshness as _, type TableDisplay as a, type KernelTableName as a0, type KeysetRow as a1, MERGE_FIELD_MODIFIERS as a2, MERGE_FIELD_SEMANTIC_TYPES as a3, MERGE_FIELD_SOURCES as a4, type MergeFieldModifier as a5, type MergeFieldSemanticType as a6, type MergeFieldSource as a7, ON_DELETE as a8, OVERRIDE_POLICIES as a9, type ValueAlternateKey as aA, type ValueEnvelope as aB, type ValueEnvelopeKey as aC, type ValueSource as aD, err as aE, isLockedStub as aF, isRecordsErr as aG, ok as aH, splitLockedRows as aI, type OverridePolicy as aa, PARITY_FIELD_TYPES as ab, PER_VALUE_ACCESS_WORDS as ac, type PerValueAccessWord as ad, type ProvenancePointer as ae, RELATION_BINDINGS as af, RELATION_CARDINALITIES as ag, RELATION_FLAVORS as ah, RETIRED_ACTOR_WORDS as ai, RULE_NODE_KINDS as aj, RULE_USES as ak, type RelationBinding as al, type RetiredActorWord as am, STORAGE_MODES as an, STORE_DOORS as ao, STORE_KNOBS as ap, STORE_REFUSAL_CODES as aq, type StoreDoorName as ar, type StoreRefusalCode as as, TABLE_DISPLAYS as at, TABLE_ORIGINS as au, TABLE_TYPES as av, type TableOrigin as aw, VALUE_ALTERNATE_KEYS as ax, VALUE_ENVELOPE_KEYS as ay, type ValueAlternate as az, type FieldSensitivity as b, type ContextPolicy as c, type RelationFlavor as d, type RelationCardinality as e, type Timestamp as f, type RecordsErrorCode as g, type RecordDocument as h, type RecordsResult as i, type RecordChange as j, type RecordChangeResult as k, type RecordGraphWritten as l, type RecordRead as m, type ReadRow as n, type RecordPageSort as o, type RecordPage as p, type RecordKeysetPage as q, type StoredRecord as r, type RecordRevision as s, type ReadValue as t, type RuleNodeKind as u, type RuleUse as v, type FieldBehavior as w, type ParityFieldType as x, type StaleWriteDetail as y, type PredictedRefusal as z };
+export { type Freshness as $, type Actor as A, type PredictedRefusal as B, type ComputeOn as C, type DeclarableFieldKind as D, ABSENCE_REASONS as E, type FieldSource as F, ACTOR_VOCABULARY as G, type HiddenFieldNotice as H, type AbsenceReason as I, COMPUTE_ON as J, CONTEXT_POLICIES as K, DECLARABLE_FIELD_KINDS as L, DELIVERIES as M, type Delivery as N, type OnDelete as O, type PgError as P, ENTITY_TOKENS as Q, type RecordsResult as R, type StorageMode as S, type Timestamp as T, type Uuid as U, type EntityToken as V, type WriteConflict as W, FIELD_SENSITIVITIES as X, FIELD_SOURCES as Y, FRESHNESS as Z, type ForbiddenEnvelopeWord as _, type RecordsError as a, KERNEL_TABLES as a0, type KernelTableName as a1, type KeysetRow as a2, MERGE_FIELD_MODIFIERS as a3, MERGE_FIELD_SEMANTIC_TYPES as a4, MERGE_FIELD_SOURCES as a5, type MergeFieldModifier as a6, type MergeFieldSemanticType as a7, type MergeFieldSource as a8, ON_DELETE as a9, type ValueAlternateKey as aA, type ValueEnvelope as aB, type ValueEnvelopeKey as aC, type ValueSource as aD, err as aE, isLockedStub as aF, isRecordsErr as aG, ok as aH, splitLockedRows as aI, OVERRIDE_POLICIES as aa, type OverridePolicy as ab, PARITY_FIELD_TYPES as ac, PER_VALUE_ACCESS_WORDS as ad, type PerValueAccessWord as ae, type ProvenancePointer as af, RELATION_BINDINGS as ag, RELATION_CARDINALITIES as ah, RELATION_FLAVORS as ai, RETIRED_ACTOR_WORDS as aj, RULE_NODE_KINDS as ak, RULE_USES as al, type RetiredActorWord as am, STORAGE_MODES as an, STORE_DOORS as ao, STORE_KNOBS as ap, STORE_REFUSAL_CODES as aq, type StoreDoorName as ar, type StoreRefusalCode as as, TABLE_DISPLAYS as at, TABLE_ORIGINS as au, TABLE_TYPES as av, type TableOrigin as aw, VALUE_ALTERNATE_KEYS as ax, VALUE_ENVELOPE_KEYS as ay, type ValueAlternate as az, type RelationFlavor as b, type RelationBinding as c, type RelationCardinality as d, type RuleNodeKind as e, type RuleUse as f, type TableType as g, type TableDisplay as h, type FieldSensitivity as i, type ContextPolicy as j, type RecordsErrorCode as k, type RecordDocument as l, type RecordChange as m, type RecordChangeResult as n, type RecordGraphWritten as o, type RecordRead as p, type ReadRow as q, type RecordPageSort as r, type RecordPage as s, type RecordKeysetPage as t, type StoredRecord as u, type RecordRevision as v, type ReadValue as w, type FieldBehavior as x, type ParityFieldType as y, type StaleWriteDetail as z };

package/dist/{record-DpB2QgAZ.d.ts → record-BQi92d4-.d.ts}

@@ -6180,6 +6180,12 @@ interface RecordRead {
      * was never asked for).
      */
     computedUnavailable?: RecordsError | null;
+    /**
+     * The version this read saw, so a safe edit (`recordUpdate` with `expected_version`) needs no
+     * second call. Read beside the document in the same round of requests; `null` when the store
+     * could not answer it (a write then refuses as "version unread", never as last-write-wins).
+     */
+    version?: number | null;
 }
 
-export { KERNEL_TABLES as $, type Actor as A, ABSENCE_REASONS as B, type ComputeOn as C, type DeclarableFieldKind as D, ACTOR_VOCABULARY as E, type FieldSource as F, type AbsenceReason as G, type HiddenFieldNotice as H, COMPUTE_ON as I, CONTEXT_POLICIES as J, DECLARABLE_FIELD_KINDS as K, DELIVERIES as L, type Delivery as M, ENTITY_TOKENS as N, type OnDelete as O, type PgError as P, type EntityToken as Q, type RecordsError as R, type StorageMode as S, type TableType as T, type Uuid as U, FIELD_SENSITIVITIES as V, type WriteConflict as W, FIELD_SOURCES as X, FRESHNESS as Y, type ForbiddenEnvelopeWord as Z, type Freshness as _, type TableDisplay as a, type KernelTableName as a0, type KeysetRow as a1, MERGE_FIELD_MODIFIERS as a2, MERGE_FIELD_SEMANTIC_TYPES as a3, MERGE_FIELD_SOURCES as a4, type MergeFieldModifier as a5, type MergeFieldSemanticType as a6, type MergeFieldSource as a7, ON_DELETE as a8, OVERRIDE_POLICIES as a9, type ValueAlternateKey as aA, type ValueEnvelope as aB, type ValueEnvelopeKey as aC, type ValueSource as aD, err as aE, isLockedStub as aF, isRecordsErr as aG, ok as aH, splitLockedRows as aI, type OverridePolicy as aa, PARITY_FIELD_TYPES as ab, PER_VALUE_ACCESS_WORDS as ac, type PerValueAccessWord as ad, type ProvenancePointer as ae, RELATION_BINDINGS as af, RELATION_CARDINALITIES as ag, RELATION_FLAVORS as ah, RETIRED_ACTOR_WORDS as ai, RULE_NODE_KINDS as aj, RULE_USES as ak, type RelationBinding as al, type RetiredActorWord as am, STORAGE_MODES as an, STORE_DOORS as ao, STORE_KNOBS as ap, STORE_REFUSAL_CODES as aq, type StoreDoorName as ar, type StoreRefusalCode as as, TABLE_DISPLAYS as at, TABLE_ORIGINS as au, TABLE_TYPES as av, type TableOrigin as aw, VALUE_ALTERNATE_KEYS as ax, VALUE_ENVELOPE_KEYS as ay, type ValueAlternate as az, type FieldSensitivity as b, type ContextPolicy as c, type RelationFlavor as d, type RelationCardinality as e, type Timestamp as f, type RecordsErrorCode as g, type RecordDocument as h, type RecordsResult as i, type RecordChange as j, type RecordChangeResult as k, type RecordGraphWritten as l, type RecordRead as m, type ReadRow as n, type RecordPageSort as o, type RecordPage as p, type RecordKeysetPage as q, type StoredRecord as r, type RecordRevision as s, type ReadValue as t, type RuleNodeKind as u, type RuleUse as v, type FieldBehavior as w, type ParityFieldType as x, type StaleWriteDetail as y, type PredictedRefusal as z };
+export { type Freshness as $, type Actor as A, type PredictedRefusal as B, type ComputeOn as C, type DeclarableFieldKind as D, ABSENCE_REASONS as E, type FieldSource as F, ACTOR_VOCABULARY as G, type HiddenFieldNotice as H, type AbsenceReason as I, COMPUTE_ON as J, CONTEXT_POLICIES as K, DECLARABLE_FIELD_KINDS as L, DELIVERIES as M, type Delivery as N, type OnDelete as O, type PgError as P, ENTITY_TOKENS as Q, type RecordsResult as R, type StorageMode as S, type Timestamp as T, type Uuid as U, type EntityToken as V, type WriteConflict as W, FIELD_SENSITIVITIES as X, FIELD_SOURCES as Y, FRESHNESS as Z, type ForbiddenEnvelopeWord as _, type RecordsError as a, KERNEL_TABLES as a0, type KernelTableName as a1, type KeysetRow as a2, MERGE_FIELD_MODIFIERS as a3, MERGE_FIELD_SEMANTIC_TYPES as a4, MERGE_FIELD_SOURCES as a5, type MergeFieldModifier as a6, type MergeFieldSemanticType as a7, type MergeFieldSource as a8, ON_DELETE as a9, type ValueAlternateKey as aA, type ValueEnvelope as aB, type ValueEnvelopeKey as aC, type ValueSource as aD, err as aE, isLockedStub as aF, isRecordsErr as aG, ok as aH, splitLockedRows as aI, OVERRIDE_POLICIES as aa, type OverridePolicy as ab, PARITY_FIELD_TYPES as ac, PER_VALUE_ACCESS_WORDS as ad, type PerValueAccessWord as ae, type ProvenancePointer as af, RELATION_BINDINGS as ag, RELATION_CARDINALITIES as ah, RELATION_FLAVORS as ai, RETIRED_ACTOR_WORDS as aj, RULE_NODE_KINDS as ak, RULE_USES as al, type RetiredActorWord as am, STORAGE_MODES as an, STORE_DOORS as ao, STORE_KNOBS as ap, STORE_REFUSAL_CODES as aq, type StoreDoorName as ar, type StoreRefusalCode as as, TABLE_DISPLAYS as at, TABLE_ORIGINS as au, TABLE_TYPES as av, type TableOrigin as aw, VALUE_ALTERNATE_KEYS as ax, VALUE_ENVELOPE_KEYS as ay, type ValueAlternate as az, type RelationFlavor as b, type RelationBinding as c, type RelationCardinality as d, type RuleNodeKind as e, type RuleUse as f, type TableType as g, type TableDisplay as h, type FieldSensitivity as i, type ContextPolicy as j, type RecordsErrorCode as k, type RecordDocument as l, type RecordChange as m, type RecordChangeResult as n, type RecordGraphWritten as o, type RecordRead as p, type ReadRow as q, type RecordPageSort as r, type RecordPage as s, type RecordKeysetPage as t, type StoredRecord as u, type RecordRevision as v, type ReadValue as w, type FieldBehavior as x, type ParityFieldType as y, type StaleWriteDetail as z };

package/dist/relation-DMwkmzgN.d.cts

@@ -0,0 +1,230 @@
+import { U as Uuid, b as RelationFlavor, O as OnDelete, c as RelationBinding, d as RelationCardinality, T as Timestamp, R as RecordsResult } from './record-BQi92d4-.cjs';
+import { c as RecordsDataSource } from './ports-DSU2RsR6.cjs';
+
+/**
+ * REL-6. Whether Visibility flows along this relation and the MAXIMUM access
+ * level it carries. Default off on `referenced`, on for `owned`.
+ */
+interface RelationCarries {
+    carries: boolean;
+    /** The ceiling — a relation never carries more access than this. */
+    max_access: string | null;
+}
+/** The seven properties, each its own question. */
+interface RelationProperties {
+    /** REL-1. Stored once on the contained table, read from the field's side. */
+    flavor: RelationFlavor;
+    /** REL-2. Separate from flavour. */
+    on_delete: OnDelete;
+    /** REL-3. A snapshot is a frozen copy in the relation's payload — never a pointer into History. */
+    binding: RelationBinding;
+    /** REL-4. */
+    ordered: boolean;
+    /** REL-5. */
+    loops: "allowed" | "refused";
+    /** REL-6. */
+    carries: RelationCarries;
+    /** REL-7. */
+    cardinality: RelationCardinality;
+}
+/**
+ * REL-8 / REL-N-1. A target is a REFERENCE, written that way from the first
+ * line of code, because it may name a row outside our database. One Table,
+ * several, or any — polymorphic without restriction. External targets are
+ * read-only in v1.
+ */
+type RelationTarget = {
+    kind: "ours";
+    entity_token: string;
+    row_id: Uuid;
+} | {
+    kind: "external";
+    connection_token: string;
+    external_table: string;
+    external_key: string;
+} | {
+    kind: "any";
+};
+/** One edge, as the store holds it in `platform.associations`. */
+interface Relation {
+    id: Uuid;
+    organization_id: Uuid;
+    /** REL-10. The field key, which is what `role` holds. */
+    role: string;
+    source: RelationTarget;
+    target: RelationTarget;
+    properties: RelationProperties;
+    /** REL-4. Meaningful only when `ordered`. */
+    position: number | null;
+    /** REL-3. The frozen copy, when `binding` is `snapshot`. */
+    payload: Record<string, unknown> | null;
+    /** REL-14. Hydrated from the target's title field AT READ — never stored. */
+    label: string | null;
+    created_at: Timestamp;
+    updated_at: Timestamp;
+    /** REL-13 / REL-16. Associations are versioned, so relation history exists. */
+    version: number;
+}
+/**
+ * DOOR-6. A query coordinate: "related to THIS, along THAT role, in that
+ * direction". Any combination, and any subset of them.
+ */
+interface RelationCoordinate {
+    /** The record at the other end. */
+    record_id: Uuid;
+    /** The field key the edge carries as its role. Omit to mean any role. */
+    role?: string;
+    /** Which way to walk. `out` is this record's own relation fields. */
+    direction?: "out" | "in" | "either";
+}
+/**
+ * The arguments of the ONE relation-words resolver: the FIELD, because that is where its display
+ * spec is declared and judged (`custom._display_of_field` reads it server-side; the caller never
+ * carries it), and the ids of a page of cells.
+ */
+/** A linked record's icon, and its table's icon for a record that has none (`relationWordsMany`). */
+interface RelationIcons {
+    icon: string | null;
+    tableIcon: string | null;
+}
+interface RelationWordsManyArgs {
+    field_id: Uuid;
+    record_ids: Uuid[];
+}
+/** One reference as the store keeps it. */
+interface EntityRef {
+    /** The `platform.entity_types` token: `note`, `web_site`, `agent` … */
+    token: string;
+    id: Uuid;
+}
+/** One reference as a read door answers it. */
+interface EntityRefWithWords extends EntityRef {
+    /**
+     * The thing's own title — or the store's withheld sentence when the reader
+     * may not open it; `null` when the kind names no title.
+     */
+    label: string | null;
+}
+/** One kind of platform thing a record may point at (`custom.entity_reference_kinds`). */
+interface EntityReferenceKind {
+    token: string;
+    /** What a person reads: "Note", "Site", "Agent". */
+    label: string;
+    /** The picker's grouping: the admin-assigned reference category, else the schema. */
+    category: string;
+}
+/**
+ * The references a cell holds, whichever shape it arrived in — one object, a
+ * list, or what a read door rendered (with labels). Anything that is not a
+ * reference is left out, never guessed at.
+ */
+declare function entityRefsOf(value: unknown): EntityRefWithWords[];
+/**
+ * What to WRITE for an entity-reference cell: `{token, id}` only, each thing
+ * once, first mention first — the label a read door added is dropped, because
+ * the store reads it and never keeps it (REL-14). A single-valued column gets
+ * the one object (or `null`), a multi-valued one the list.
+ */
+declare function entityRefsToWrite(value: unknown, multi: boolean): EntityRef | EntityRef[] | null;
+/**
+ * The kinds of platform thing a record may point at — what the field editor's
+ * kind picker lists. `custom.entity_reference_kinds()`.
+ */
+declare function entityReferenceKinds(source: RecordsDataSource): Promise<RecordsResult<EntityReferenceKind[]>>;
+/**
+ * THE SEARCH DOOR (lane REFERENCE-CARRY). The platform things of these kinds whose words hold
+ * `search`, that THIS person may point a record at — each one a thing the store's own write check
+ * (`custom._entity_reference_target_ok`) would accept, so a picked reference is never refused on
+ * save. `custom.entity_reference_search`. An empty search lists the first things by name.
+ */
+declare function entityReferenceSearch(source: RecordsDataSource, organizationId: Uuid | null, tokens: readonly string[], search: string, limit?: number): Promise<RecordsResult<EntityRefWithWords[]>>;
+/**
+ * THE WORDS HELPER. The words of each `{token, id}` for a picker or a chip
+ * before anything is saved — each label read by the store for THIS person and
+ * withheld when they may not open the thing. `custom.entity_reference_words`.
+ * A saved cell needs no call: every read door already answers its labels.
+ */
+declare function entityReferenceWords(source: RecordsDataSource, organizationId: Uuid | null, refs: readonly EntityRef[]): Promise<RecordsResult<EntityRefWithWords[]>>;
+/** One reverse column of a Table, as `custom.reverse_columns` answers it. */
+interface ReverseColumn {
+    /** Stable key: the linking Field's `inverse_key`, else `linked_<field id>`. Never a Field key of B. */
+    key: string;
+    /** What the column is called on B: the linking table's name (plus the column's when ambiguous). */
+    label: string;
+    /** The relation Field on the linking table. */
+    source_field_id: Uuid;
+    source_field_key: string;
+    source_field_label: string;
+    /** The linking table. */
+    source_table_id: Uuid;
+    source_table_name: string;
+    /** Always `many`: any number of records may link to one. */
+    cardinality: "many";
+    /**
+     * True for a virtual back-link (written only from the linking table's side). False for a TWO-WAY
+     * LINK (NOTION-PROPS): the reverse end is a real Field on this table — `key` is its key, `label`
+     * its label — and `relationReverseSet` writes its links from here.
+     */
+    read_only: boolean;
+}
+/**
+ * NOTION-PROPS. A two-way link's reverse Field: a relation whose `config.reverse_of` names the
+ * forward relation it mirrors. It holds no value of its own — its links are the forward Field's.
+ */
+declare function isReverseField(field: {
+    type?: unknown;
+    config?: unknown;
+} | null | undefined): boolean;
+/** One linking record, as a chip shows it. */
+interface ReverseLink {
+    id: Uuid;
+    /** The linking record's name, read by the store for this reader. */
+    words: string;
+}
+/** The links of one record through one reverse column: how many the reader may see, and one page. */
+interface ReverseLinks {
+    total: number;
+    links: ReverseLink[];
+}
+interface ReverseLinksManyArgs {
+    /** The Table whose records are being shown (B). */
+    table_id: Uuid;
+    /** `ReverseColumn.source_field_id`. */
+    source_field_id: Uuid;
+    /** A page of B's record ids — up to 200 a call; more are sent in groups by the client. */
+    record_ids: readonly Uuid[];
+    /** Links per record, 1–50 (the store holds it there). Default 10. */
+    limit?: number;
+    /** Skip this many links of each record — the next page of one hub record. Default 0. */
+    offset?: number;
+}
+/** `reverseLinksFields`: the links of a page through several reverse columns, in one call. */
+interface ReverseLinksFieldsArgs {
+    table_id: Uuid;
+    /** Each `ReverseColumn.source_field_id` — at most 20. */
+    source_field_ids: readonly Uuid[];
+    record_ids: readonly Uuid[];
+    limit?: number;
+    offset?: number;
+}
+/** The store's per-call ceiling on records for `custom.reverse_links_many`. */
+declare const REVERSE_LINKS_RECORDS_PER_CALL = 200;
+/** The store's ceiling on links a record per call. */
+declare const REVERSE_LINKS_PAGE_MAX = 50;
+/** The store's typed "source archived" answer for a lookup or roll-up. */
+interface SourceArchived {
+    __unavailable: "source_archived";
+    /** `link`: the relation it reads through is archived; `column`: the far column it reads is. */
+    reads: "link" | "column";
+    /** The archived Field. Absent when the reader may not know its Table. */
+    field_id?: Uuid;
+    /** Its label. Absent when the reader may not know its Table. */
+    label?: string;
+    table_id?: Uuid;
+    /** Its Table's name. Absent when the reader may not know that Table. */
+    table?: string;
+}
+/** The typed "source archived" answer, when `value` is one; null for any other value. */
+declare function sourceArchivedOf(value: unknown): SourceArchived | null;
+
+export { type EntityRefWithWords as E, type RelationCoordinate as R, type SourceArchived as S, type RelationWordsManyArgs as a, type RelationIcons as b, type ReverseColumn as c, type ReverseLinksManyArgs as d, type ReverseLinks as e, type ReverseLinksFieldsArgs as f, type EntityRef as g, type EntityReferenceKind as h, REVERSE_LINKS_PAGE_MAX as i, REVERSE_LINKS_RECORDS_PER_CALL as j, type Relation as k, type RelationCarries as l, type RelationProperties as m, type RelationTarget as n, type ReverseLink as o, entityReferenceKinds as p, entityReferenceSearch as q, entityReferenceWords as r, entityRefsOf as s, entityRefsToWrite as t, isReverseField as u, sourceArchivedOf as v };

package/dist/relation-DlcqV_W5.d.ts

@@ -0,0 +1,230 @@
+import { U as Uuid, b as RelationFlavor, O as OnDelete, c as RelationBinding, d as RelationCardinality, T as Timestamp, R as RecordsResult } from './record-BQi92d4-.js';
+import { c as RecordsDataSource } from './ports-BWtxAnXh.js';
+
+/**
+ * REL-6. Whether Visibility flows along this relation and the MAXIMUM access
+ * level it carries. Default off on `referenced`, on for `owned`.
+ */
+interface RelationCarries {
+    carries: boolean;
+    /** The ceiling — a relation never carries more access than this. */
+    max_access: string | null;
+}
+/** The seven properties, each its own question. */
+interface RelationProperties {
+    /** REL-1. Stored once on the contained table, read from the field's side. */
+    flavor: RelationFlavor;
+    /** REL-2. Separate from flavour. */
+    on_delete: OnDelete;
+    /** REL-3. A snapshot is a frozen copy in the relation's payload — never a pointer into History. */
+    binding: RelationBinding;
+    /** REL-4. */
+    ordered: boolean;
+    /** REL-5. */
+    loops: "allowed" | "refused";
+    /** REL-6. */
+    carries: RelationCarries;
+    /** REL-7. */
+    cardinality: RelationCardinality;
+}
+/**
+ * REL-8 / REL-N-1. A target is a REFERENCE, written that way from the first
+ * line of code, because it may name a row outside our database. One Table,
+ * several, or any — polymorphic without restriction. External targets are
+ * read-only in v1.
+ */
+type RelationTarget = {
+    kind: "ours";
+    entity_token: string;
+    row_id: Uuid;
+} | {
+    kind: "external";
+    connection_token: string;
+    external_table: string;
+    external_key: string;
+} | {
+    kind: "any";
+};
+/** One edge, as the store holds it in `platform.associations`. */
+interface Relation {
+    id: Uuid;
+    organization_id: Uuid;
+    /** REL-10. The field key, which is what `role` holds. */
+    role: string;
+    source: RelationTarget;
+    target: RelationTarget;
+    properties: RelationProperties;
+    /** REL-4. Meaningful only when `ordered`. */
+    position: number | null;
+    /** REL-3. The frozen copy, when `binding` is `snapshot`. */
+    payload: Record<string, unknown> | null;
+    /** REL-14. Hydrated from the target's title field AT READ — never stored. */
+    label: string | null;
+    created_at: Timestamp;
+    updated_at: Timestamp;
+    /** REL-13 / REL-16. Associations are versioned, so relation history exists. */
+    version: number;
+}
+/**
+ * DOOR-6. A query coordinate: "related to THIS, along THAT role, in that
+ * direction". Any combination, and any subset of them.
+ */
+interface RelationCoordinate {
+    /** The record at the other end. */
+    record_id: Uuid;
+    /** The field key the edge carries as its role. Omit to mean any role. */
+    role?: string;
+    /** Which way to walk. `out` is this record's own relation fields. */
+    direction?: "out" | "in" | "either";
+}
+/**
+ * The arguments of the ONE relation-words resolver: the FIELD, because that is where its display
+ * spec is declared and judged (`custom._display_of_field` reads it server-side; the caller never
+ * carries it), and the ids of a page of cells.
+ */
+/** A linked record's icon, and its table's icon for a record that has none (`relationWordsMany`). */
+interface RelationIcons {
+    icon: string | null;
+    tableIcon: string | null;
+}
+interface RelationWordsManyArgs {
+    field_id: Uuid;
+    record_ids: Uuid[];
+}
+/** One reference as the store keeps it. */
+interface EntityRef {
+    /** The `platform.entity_types` token: `note`, `web_site`, `agent` … */
+    token: string;
+    id: Uuid;
+}
+/** One reference as a read door answers it. */
+interface EntityRefWithWords extends EntityRef {
+    /**
+     * The thing's own title — or the store's withheld sentence when the reader
+     * may not open it; `null` when the kind names no title.
+     */
+    label: string | null;
+}
+/** One kind of platform thing a record may point at (`custom.entity_reference_kinds`). */
+interface EntityReferenceKind {
+    token: string;
+    /** What a person reads: "Note", "Site", "Agent". */
+    label: string;
+    /** The picker's grouping: the admin-assigned reference category, else the schema. */
+    category: string;
+}
+/**
+ * The references a cell holds, whichever shape it arrived in — one object, a
+ * list, or what a read door rendered (with labels). Anything that is not a
+ * reference is left out, never guessed at.
+ */
+declare function entityRefsOf(value: unknown): EntityRefWithWords[];
+/**
+ * What to WRITE for an entity-reference cell: `{token, id}` only, each thing
+ * once, first mention first — the label a read door added is dropped, because
+ * the store reads it and never keeps it (REL-14). A single-valued column gets
+ * the one object (or `null`), a multi-valued one the list.
+ */
+declare function entityRefsToWrite(value: unknown, multi: boolean): EntityRef | EntityRef[] | null;
+/**
+ * The kinds of platform thing a record may point at — what the field editor's
+ * kind picker lists. `custom.entity_reference_kinds()`.
+ */
+declare function entityReferenceKinds(source: RecordsDataSource): Promise<RecordsResult<EntityReferenceKind[]>>;
+/**
+ * THE SEARCH DOOR (lane REFERENCE-CARRY). The platform things of these kinds whose words hold
+ * `search`, that THIS person may point a record at — each one a thing the store's own write check
+ * (`custom._entity_reference_target_ok`) would accept, so a picked reference is never refused on
+ * save. `custom.entity_reference_search`. An empty search lists the first things by name.
+ */
+declare function entityReferenceSearch(source: RecordsDataSource, organizationId: Uuid | null, tokens: readonly string[], search: string, limit?: number): Promise<RecordsResult<EntityRefWithWords[]>>;
+/**
+ * THE WORDS HELPER. The words of each `{token, id}` for a picker or a chip
+ * before anything is saved — each label read by the store for THIS person and
+ * withheld when they may not open the thing. `custom.entity_reference_words`.
+ * A saved cell needs no call: every read door already answers its labels.
+ */
+declare function entityReferenceWords(source: RecordsDataSource, organizationId: Uuid | null, refs: readonly EntityRef[]): Promise<RecordsResult<EntityRefWithWords[]>>;
+/** One reverse column of a Table, as `custom.reverse_columns` answers it. */
+interface ReverseColumn {
+    /** Stable key: the linking Field's `inverse_key`, else `linked_<field id>`. Never a Field key of B. */
+    key: string;
+    /** What the column is called on B: the linking table's name (plus the column's when ambiguous). */
+    label: string;
+    /** The relation Field on the linking table. */
+    source_field_id: Uuid;
+    source_field_key: string;
+    source_field_label: string;
+    /** The linking table. */
+    source_table_id: Uuid;
+    source_table_name: string;
+    /** Always `many`: any number of records may link to one. */
+    cardinality: "many";
+    /**
+     * True for a virtual back-link (written only from the linking table's side). False for a TWO-WAY
+     * LINK (NOTION-PROPS): the reverse end is a real Field on this table — `key` is its key, `label`
+     * its label — and `relationReverseSet` writes its links from here.
+     */
+    read_only: boolean;
+}
+/**
+ * NOTION-PROPS. A two-way link's reverse Field: a relation whose `config.reverse_of` names the
+ * forward relation it mirrors. It holds no value of its own — its links are the forward Field's.
+ */
+declare function isReverseField(field: {
+    type?: unknown;
+    config?: unknown;
+} | null | undefined): boolean;
+/** One linking record, as a chip shows it. */
+interface ReverseLink {
+    id: Uuid;
+    /** The linking record's name, read by the store for this reader. */
+    words: string;
+}
+/** The links of one record through one reverse column: how many the reader may see, and one page. */
+interface ReverseLinks {
+    total: number;
+    links: ReverseLink[];
+}
+interface ReverseLinksManyArgs {
+    /** The Table whose records are being shown (B). */
+    table_id: Uuid;
+    /** `ReverseColumn.source_field_id`. */
+    source_field_id: Uuid;
+    /** A page of B's record ids — up to 200 a call; more are sent in groups by the client. */
+    record_ids: readonly Uuid[];
+    /** Links per record, 1–50 (the store holds it there). Default 10. */
+    limit?: number;
+    /** Skip this many links of each record — the next page of one hub record. Default 0. */
+    offset?: number;
+}
+/** `reverseLinksFields`: the links of a page through several reverse columns, in one call. */
+interface ReverseLinksFieldsArgs {
+    table_id: Uuid;
+    /** Each `ReverseColumn.source_field_id` — at most 20. */
+    source_field_ids: readonly Uuid[];
+    record_ids: readonly Uuid[];
+    limit?: number;
+    offset?: number;
+}
+/** The store's per-call ceiling on records for `custom.reverse_links_many`. */
+declare const REVERSE_LINKS_RECORDS_PER_CALL = 200;
+/** The store's ceiling on links a record per call. */
+declare const REVERSE_LINKS_PAGE_MAX = 50;
+/** The store's typed "source archived" answer for a lookup or roll-up. */
+interface SourceArchived {
+    __unavailable: "source_archived";
+    /** `link`: the relation it reads through is archived; `column`: the far column it reads is. */
+    reads: "link" | "column";
+    /** The archived Field. Absent when the reader may not know its Table. */
+    field_id?: Uuid;
+    /** Its label. Absent when the reader may not know its Table. */
+    label?: string;
+    table_id?: Uuid;
+    /** Its Table's name. Absent when the reader may not know that Table. */
+    table?: string;
+}
+/** The typed "source archived" answer, when `value` is one; null for any other value. */
+declare function sourceArchivedOf(value: unknown): SourceArchived | null;
+
+export { type EntityRefWithWords as E, type RelationCoordinate as R, type SourceArchived as S, type RelationWordsManyArgs as a, type RelationIcons as b, type ReverseColumn as c, type ReverseLinksManyArgs as d, type ReverseLinks as e, type ReverseLinksFieldsArgs as f, type EntityRef as g, type EntityReferenceKind as h, REVERSE_LINKS_PAGE_MAX as i, REVERSE_LINKS_RECORDS_PER_CALL as j, type Relation as k, type RelationCarries as l, type RelationProperties as m, type RelationTarget as n, type ReverseLink as o, entityReferenceKinds as p, entityReferenceSearch as q, entityReferenceWords as r, entityRefsOf as s, entityRefsToWrite as t, isReverseField as u, sourceArchivedOf as v };