@ai-matrx/records 0.96.14 → 0.97.1

package/dist/{declareTable-VoNRi_j_.d.cts → declareTable-Bekj6UwK.d.cts}

@@ -1,4 +1,4 @@
-import { R as RecordsClient } from './client-DKgbZUNt.cjs';
+import { R as RecordsClient } from './client-pFV_8AhM.cjs';
 import { a as FieldTypeWord, N as NewFieldDeclaration } from './field-DjS7iId2.cjs';
 import { U as Uuid, a as RecordsError } from './record-zwSBU5PQ.cjs';
 import { F as FieldDrift } from './table-kind-CMXvN5Kb.cjs';

package/dist/{declareTable-D_CiMnXM.d.ts → declareTable-C7zVyyLA.d.ts}

@@ -1,4 +1,4 @@
-import { R as RecordsClient } from './client-D7bvxEZW.js';
+import { R as RecordsClient } from './client-MVuEbxKl.js';
 import { a as FieldTypeWord, N as NewFieldDeclaration } from './field-D-1OKy5r.js';
 import { U as Uuid, a as RecordsError } from './record-zwSBU5PQ.js';
 import { F as FieldDrift } from './table-kind-CjTL6PyT.js';

package/dist/doors-C43_5HjC.d.ts

@@ -0,0 +1,487 @@
+import { U as Uuid, R as RecordsResult } from './record-zwSBU5PQ.js';
+
+/**
+ * What a context field holds, as a person thinks of it — derived from the Field's behaviour, `multi`,
+ * `format`, display format and `config.kind` (`contextFieldKind`). The value is always `value`; the
+ * kind says how to read and edit it.
+ */
+type ContextFieldKind = "string" | "markdown" | "email" | "url" | "phone" | "color" | "number" | "percent" | "currency" | "boolean" | "date" | "datetime" | "time" | "object" | "array" | "reference" | "document";
+declare const CONTEXT_FIELD_KINDS: readonly ContextFieldKind[];
+/** The store's context policy on a Field: whether an agent receives it every turn, on request, or never. */
+type ContextPolicy = "include" | "on_request" | "exclude";
+/** The store's sensitivity words on a Field. */
+type ContextSensitivity = "public" | "internal" | "confidential" | "restricted";
+/** A scope type: a Table kept for context. */
+interface ScopeType {
+    id: Uuid;
+    organization_id: Uuid;
+    label_singular: string;
+    label_plural: string;
+    icon: string;
+    color: string;
+    /** The Table's slug in the store's grammar (`practice_areas`). */
+    slug: string | null;
+    description: string;
+    sort_order: number;
+    max_assignments_per_entity: number | null;
+    default_variable_keys: string[];
+    /** Who made the type: with the organization's owners and admins, they shape it (`canShapeScopeType`). */
+    created_by: Uuid | null;
+    created_at: string;
+    updated_at: string;
+}
+/** A scope type with its live scopes, as the tree doors answer it. */
+interface ScopeTypeWithScopes extends ScopeType {
+    scopes: Scope[];
+}
+/** A scope: a Record of its type's Table. */
+interface Scope {
+    id: Uuid;
+    scope_type_id: Uuid;
+    organization_id: Uuid;
+    name: string;
+    description: string;
+    slug: string | null;
+    sort_order: number;
+    parent_scope_id: Uuid | null;
+    /** Free settings keys of the scope (each a Field of its Table the scope door derived). */
+    settings: Record<string, unknown>;
+    created_by: Uuid | null;
+    created_at: string;
+    updated_at: string;
+}
+/** A scope with its type's presentation (`custom.context_scopes`). */
+interface ScopeWithType extends Scope {
+    scope_type: ScopeTypeLabel | null;
+}
+/** The presentation of a scope type: what a chip or a breadcrumb shows. */
+interface ScopeTypeLabel {
+    id: Uuid;
+    label_singular: string;
+    label_plural: string;
+    icon: string | null;
+    color: string | null;
+}
+/** A scope type that was archived, with how many scopes went with it. */
+interface ArchivedScopeType {
+    id: Uuid;
+    organization_id: Uuid;
+    label_singular: string;
+    label_plural: string;
+    icon: string;
+    color: string;
+    archived_at: string;
+    created_by: Uuid | null;
+    archived_scope_count: number;
+}
+/** A scope that was archived (a Record in the archive of its type's Table). */
+interface ArchivedScope {
+    id: Uuid;
+    name: string | null;
+    slug: string | null;
+    archived_at: string | null;
+}
+/** A context field: a Field (column) of a scope type's Table. */
+interface ContextField {
+    id: Uuid;
+    scope_type_id: Uuid;
+    organization_id: Uuid;
+    key: string;
+    label: string;
+    description: string;
+    kind: ContextFieldKind;
+    /** The Field's own words, for a caller that needs them (`type` is the store's behaviour word). */
+    type: string;
+    multi: boolean;
+    format: string | null;
+    config: Record<string, unknown>;
+    relation_target: Uuid | null;
+    /** Its place among the type's context fields, from 0. */
+    sort: number;
+    context_policy: ContextPolicy;
+    sensitivity: ContextSensitivity;
+    source: string;
+    status: string;
+    status_note: string | null;
+    category: string | null;
+    tags: string[];
+    max_items: number;
+    custom_component: unknown;
+    reference_source: unknown;
+    allowed_scope_type_ids: Uuid[] | null;
+    allowed_reference_types: string[] | null;
+    review_interval_days: number | null;
+    depends_on: string[];
+    /** The store's clock on this Field. */
+    version: number;
+    created_by: Uuid | null;
+    created_at: string;
+    updated_at: string;
+}
+/** One thing a reference cell points at. */
+interface ContextReference {
+    /** The record id (for a file: the File record's id). */
+    id: Uuid;
+    /** What it is: `scope`, `file`, `table`, or another entity token. */
+    type: string;
+    /** Its name, where the door named it to this caller. */
+    label?: string;
+    /** For a file: the `files.files` id a viewer opens. */
+    file_id?: Uuid;
+}
+/** The cell holds only the first words of a text kept as a file, and the whole could not be read. */
+interface IncompleteValue {
+    /** The cell's own first words. */
+    head: string;
+    /** The whole text's length in characters, when known. */
+    chars: number | null;
+    /** The file holding the whole text, when it has one yet. */
+    file_id: Uuid | null;
+    /** Why the whole text is not here, in one sentence. */
+    why: string;
+}
+/** A context value: one cell of a scope's Record. */
+interface ContextValue {
+    scope_id: Uuid;
+    field_id: Uuid;
+    key: string;
+    kind: ContextFieldKind;
+    /**
+     * THE CELL, as the store holds it (a text, a number, a boolean, an ISO date, a list, an object).
+     * A reference or document cell is its `references` (ids here). A text kept as a file is its whole
+     * text when the read could open the file (`completeWholeValues`), else the first words and `incomplete`.
+     */
+    value: unknown;
+    /** A reference / document cell, decoded: what it points at, with names the caller may see. */
+    references: ContextReference[];
+    /** The version a PERSON made (system rewrites never move it). */
+    version: number;
+    set_at: string | null;
+    source_type: string | null;
+    authored_by: Uuid | null;
+    /** The pointer to the file holding a text too big for one cell, when the cell holds only its start. */
+    whole_value: StoreWholeValue | null;
+    /** Present only when `value` is not the whole text — never save it back as the value. */
+    incomplete: IncompleteValue | null;
+}
+/** The file fields of a whole-value pointer, as `custom.context_values` answers them. */
+interface StoreWholeValue {
+    kind: string;
+    file_id?: Uuid | null;
+    file_record?: Uuid | null;
+    bytes?: number | null;
+    chars?: number | null;
+    sha256?: string | null;
+    shown_chars?: number | null;
+    mime?: string | null;
+    pending?: boolean | null;
+    in_value?: boolean | null;
+}
+/** The scope types of some organizations, without their scopes, and how many each holds. */
+interface ScopeTypeSkeleton {
+    types: ScopeType[];
+    /** type id → how many scopes the caller sees in it; null when asked without counts. */
+    counts: Record<Uuid, number> | null;
+}
+/** One page of one type's scopes. */
+interface ScopePage {
+    scopes: Scope[];
+    total: number;
+    next_offset: number | null;
+}
+/** A System Context item (`context.system_context_item`), as `custom.context_system_items` answers it. */
+interface SystemContextItem {
+    [key: string]: unknown;
+}
+/** One scope template of the gallery, as `custom.context_templates` answers it. */
+interface ScopeTemplate {
+    [key: string]: unknown;
+}
+/** A new scope type, or the parts of one to change (`undefined` = leave as it is). */
+interface ScopeTypeSpec {
+    label_singular?: string;
+    label_plural?: string;
+    icon?: string;
+    color?: string;
+    description?: string;
+    sort_order?: number;
+    max_assignments_per_entity?: number | null;
+    default_variable_keys?: string[];
+    /** Any spelling; the package writes it in the store's grammar. Absent on create = from the label. */
+    slug?: string;
+}
+/** A new scope, or the parts of one to change. */
+interface ScopeSpec {
+    name?: string;
+    description?: string;
+    settings?: Record<string, unknown>;
+    parent_scope_id?: Uuid | null;
+    slug?: string;
+    sort_order?: number;
+}
+/** A new context field, or the parts of one to change (`null` clears). */
+interface ContextFieldSpec {
+    key?: string;
+    label?: string;
+    kind?: ContextFieldKind;
+    description?: string;
+    category?: string | null;
+    context_policy?: ContextPolicy;
+    sensitivity?: ContextSensitivity;
+    tags?: string[];
+    sort?: number;
+    status?: string;
+    status_note?: string | null;
+    custom_component?: unknown;
+    review_interval_days?: number | null;
+    allowed_reference_types?: string[] | null;
+    max_items?: number | null;
+    allowed_scope_type_ids?: Uuid[] | null;
+    reference_source?: unknown;
+}
+/** One cell to write. `value` is the cell as `ContextValue.value` reads it; a reference cell takes `references`. */
+interface ContextValueWrite {
+    scope_id: Uuid;
+    field_id: Uuid;
+    kind: ContextFieldKind;
+    value?: unknown;
+    /** A reference / document cell: the things it points at (replaces the cell). */
+    references?: ContextReference[];
+    /** Who wrote it: `manual` from a person's own edit (the store's default is `ai_enriched`). */
+    source_type?: string;
+    change_summary?: string;
+}
+/** What a written cell answers. */
+interface ContextValueWritten {
+    scope_id: Uuid;
+    field_id: Uuid;
+    version: number;
+    source_type: string;
+}
+
+/** A scope type as the tree doors answer it. */
+interface StoreTypeRow {
+    id: string;
+    organization_id: string;
+    label_singular?: string | null;
+    label_plural?: string | null;
+    name?: string | null;
+    icon?: string | null;
+    color?: string | null;
+    slug?: string | null;
+    description?: string | null;
+    sort_order?: number | null;
+    max_assignments_per_entity?: number | null;
+    default_variable_keys?: string[] | null;
+    created_by?: string | null;
+    created_at?: string | null;
+    updated_at?: string | null;
+    scope_count?: number | null;
+}
+/** A scope as the tree and scope doors answer it. */
+interface StoreScopeRow {
+    id: string;
+    scope_type_id: string;
+    organization_id: string;
+    name?: string | null;
+    description?: string | null;
+    slug?: string | null;
+    sort_order?: number | string | null;
+    parent_scope_id?: string | null;
+    settings?: Record<string, unknown> | null;
+    created_by?: string | null;
+    created_at?: string | null;
+    updated_at?: string | null;
+    scope_type?: (Partial<StoreTypeRow> & {
+        id: string;
+    }) | null;
+}
+/** A Field document, as `custom.context_items` / `custom.context_values` answer it. */
+interface StoreFieldDoc {
+    key?: string;
+    label?: string;
+    type?: string;
+    multi?: boolean | null;
+    format?: string | null;
+    display_format?: {
+        id?: string;
+    } | null;
+    config?: ({
+        kind?: string;
+    } & Record<string, unknown>) | null;
+    relation_target?: string | null;
+    sort?: number | string | null;
+    description?: string | null;
+    sensitivity?: string | null;
+    context_policy?: string | null;
+    source?: string | null;
+    status?: string | null;
+    status_note?: string | null;
+    category?: string | null;
+    tags?: string[] | null;
+    max_items?: number | null;
+    custom_component?: unknown;
+    reference_source?: unknown;
+    allowed_scope_type_ids?: string[] | null;
+    allowed_reference_types?: string[] | null;
+    review_interval_days?: number | null;
+    depends_on?: string[] | null;
+    [extra: string]: unknown;
+}
+/** What the store remembers about a field it moved from the old tables and could not type. */
+interface StoreCarried {
+    value_type?: string;
+    as_text?: boolean;
+    is_active?: boolean;
+}
+/** A context field as `custom.context_items` answers it. */
+interface StoreItemRow {
+    id: string;
+    scope_type_id: string;
+    organization_id: string;
+    data: StoreFieldDoc;
+    carried?: StoreCarried | null;
+    created_by?: string | null;
+    created_at?: string | null;
+    updated_at?: string | null;
+    version?: number | null;
+}
+/** A cell as `custom.context_values` answers it. */
+interface StoreValueRow {
+    scope_id: string;
+    context_item_id: string;
+    key: string;
+    value: unknown;
+    field?: (Pick<StoreFieldDoc, "type" | "multi" | "format" | "display_format" | "config" | "relation_target"> & {
+        carried?: StoreCarried | null;
+    }) | null;
+    version?: number | null;
+    store_version?: number | null;
+    set_at?: string | null;
+    source_type?: string | null;
+    value_id?: string | null;
+    authored_by?: string | null;
+    labels?: Record<string, string> | null;
+    files?: Record<string, string> | null;
+    whole_value?: StoreWholeValue | null;
+}
+declare function scopeTypeFromStore(row: StoreTypeRow): ScopeType;
+/**
+ * A settings value as it was written. The scope door keeps a list-of-objects setting (a class's exam
+ * dates) as a list of their JSON texts (`custom._ctx_words`); read back, each is the object again.
+ */
+declare function settingFromStore(value: unknown): unknown;
+declare function scopeFromStore(row: StoreScopeRow): Scope;
+declare function scopeWithTypeFromStore(row: StoreScopeRow): ScopeWithType;
+/** The file kernel: a relation at it is a document (a file), never a reference to a row. */
+declare const FILE_KERNEL_ID = "11111111-0000-4000-8000-000000000006";
+/** What a Field holds, as a person thinks of it. */
+declare function contextFieldKind(doc: Pick<StoreFieldDoc, "type" | "multi" | "format" | "display_format" | "config" | "relation_target">, carried?: StoreCarried | null): ContextFieldKind;
+declare function contextFieldFromStore(row: StoreItemRow): ContextField;
+/** A reference / document cell's targets, with the names and files the door gave this caller. */
+declare function referencesOf(row: Pick<StoreValueRow, "value" | "field" | "labels" | "files">): ContextReference[];
+/** One cell, as a `ContextValue` (its whole text not yet read — see `completeWholeValues`). */
+declare function contextValueFromStore(row: StoreValueRow): ContextValue;
+/** Reads a file's whole text as the person (the host's one file reader). */
+type ReadContextFileText = (fileId: Uuid) => Promise<string>;
+/**
+ * A CELL THAT HOLDS ONLY THE FIRST WORDS OF A TEXT KEPT AS A FILE GETS ITS WHOLE TEXT.
+ *
+ * The store keeps a value over its one-cell ceiling as a file and the cell holds its first words;
+ * `custom.context_values` names the file (`whole_value`). Each such value is given the file's whole
+ * text — read once per file through the host's reader, checked against the size and SHA-256 the
+ * pointer names. A file that cannot be read, or does not match, leaves the first words AND sets
+ * `incomplete` (with why) — never the first words passed off as the value. Mutates `values`.
+ */
+declare function completeWholeValues(values: ContextValue[], read: ReadContextFileText | null): Promise<void>;
+/** The refusal a person sees when saving would cut a value that was not read whole. */
+declare const INCOMPLETE_SAVE_REFUSAL = "Only the start of this value loaded. Paste the whole text to replace it.";
+/**
+ * The refusal sentence when saving `draft` over a cell that was not read whole would cut the real
+ * value — else `null`. Refused: the first words unchanged, and a draft built on them that is shorter
+ * than the whole. Allowed: a draft that replaces the text, an explicit clear.
+ */
+declare function incompleteSaveRefusal(cell: Pick<ContextValue, "incomplete"> | undefined, draft: unknown): string | null;
+/** The canonical reference fence (the same grammar `@ai-matrx/agents/envelope` builds). */
+declare function referenceFence(references: readonly ContextReference[]): string;
+
+/** The client's one door call (`callDoor` in core/client.ts). */
+type ScopeDoorCall = <T>(door: string, args: Record<string, unknown>, where: string) => Promise<RecordsResult<T>>;
+/** How many ids one call of each batched door takes. */
+declare const SCOPES_PER_CALL = 500;
+declare const SCOPE_TYPES_PER_FIELDS_CALL = 100;
+/** `custom.context_values` refuses more than this many scopes in one call. */
+declare const SCOPES_PER_VALUES_CALL = 200;
+/** One page of a type's scopes (the door's default; it answers at most 1000). */
+declare const TYPE_SCOPES_PAGE = 200;
+/** The archive answers at most this many rows a call (`custom.page_size` ceiling). */
+declare const ARCHIVED_SCOPES_PAGE = 200;
+interface ScopeDoors {
+    /** Every live scope type of these organizations, each with its live scopes. */
+    tree(organizationIds: readonly Uuid[]): Promise<RecordsResult<ScopeTypeWithScopes[]>>;
+    /** The scope types of these organizations without their scopes (the first paint), with or without counts. */
+    types(organizationIds: readonly Uuid[], options?: {
+        withCounts?: boolean;
+    }): Promise<RecordsResult<ScopeTypeSkeleton>>;
+    /** One page of one type's scopes, in the tree's order. */
+    typeScopesPage(scopeTypeId: Uuid, offset?: number, limit?: number): Promise<RecordsResult<ScopePage>>;
+    /** The scopes whose name holds `query` (case-insensitive), across these organizations. */
+    search(organizationIds: readonly Uuid[], query: string, limit?: number): Promise<RecordsResult<{
+        scopes: Scope[];
+        total: number;
+    }>>;
+    /** Scopes by id, each with its type's label, in whichever organization each lives. */
+    scopes(ids: readonly Uuid[]): Promise<RecordsResult<ScopeWithType[]>>;
+    /** The context fields (columns) of these scope types. */
+    fields(scopeTypeIds: readonly Uuid[]): Promise<RecordsResult<ContextField[]>>;
+    /**
+     * The cells of these scopes. A text kept as a file is read whole through `readFileText`; without
+     * one (or when the file cannot be read) the cell keeps its first words and says so (`incomplete`).
+     */
+    values(scopeIds: readonly Uuid[], options?: {
+        readFileText?: ReadContextFileText | null;
+    }): Promise<RecordsResult<ContextValue[]>>;
+    /** The archived scope types of one organization. */
+    archivedTypes(organizationId: Uuid): Promise<RecordsResult<ArchivedScopeType[]>>;
+    /** Of these scope ids, the ones that are ARCHIVED scopes of this type. */
+    archivedScopesOfType(organizationId: Uuid, scopeTypeId: Uuid, wanted: ReadonlySet<Uuid>): Promise<RecordsResult<ArchivedScope[]>>;
+    /** The System Context items (not scopes: the platform's own ambient context). */
+    systemItems(): Promise<RecordsResult<SystemContextItem[]>>;
+    /** The scope templates of the gallery. */
+    templates(): Promise<RecordsResult<ScopeTemplate[]>>;
+    /** A new scope type in `organizationId`. */
+    createType(organizationId: Uuid, spec: ScopeTypeSpec): Promise<RecordsResult<ScopeType>>;
+    /** Change a scope type (only the keys given). */
+    updateType(typeId: Uuid, spec: ScopeTypeSpec): Promise<RecordsResult<ScopeType>>;
+    /** Archive a scope type; its scopes and fields come back with a restore. */
+    archiveType(typeId: Uuid): Promise<RecordsResult<{
+        id: Uuid;
+    }>>;
+    restoreType(typeId: Uuid): Promise<RecordsResult<{
+        id: Uuid;
+    }>>;
+    /** A new scope of `typeId` in `organizationId`. */
+    createScope(organizationId: Uuid, typeId: Uuid, spec: ScopeSpec): Promise<RecordsResult<Scope>>;
+    updateScope(scopeId: Uuid, spec: ScopeSpec): Promise<RecordsResult<Scope>>;
+    archiveScope(scopeId: Uuid): Promise<RecordsResult<{
+        id: Uuid;
+    }>>;
+    restoreScope(scopeId: Uuid): Promise<RecordsResult<{
+        id: Uuid;
+    }>>;
+    /** A new context field (column) on a scope type. Answers the field as the read door does. */
+    createField(scopeTypeId: Uuid, spec: ContextFieldSpec): Promise<RecordsResult<ContextField>>;
+    /** Change a context field (`null` clears a key). Answers the field as the read door does. */
+    updateField(fieldId: Uuid, scopeTypeId: Uuid, spec: ContextFieldSpec): Promise<RecordsResult<ContextField>>;
+    archiveField(fieldId: Uuid): Promise<RecordsResult<{
+        id: Uuid;
+    }>>;
+    restoreField(fieldId: Uuid): Promise<RecordsResult<{
+        id: Uuid;
+    }>>;
+    /** Write one cell. */
+    writeValue(write: ContextValueWrite): Promise<RecordsResult<ContextValueWritten>>;
+}
+declare function createScopeDoors(call: ScopeDoorCall): ScopeDoors;
+
+export { ARCHIVED_SCOPES_PAGE as A, type StoreWholeValue as B, CONTEXT_FIELD_KINDS as C, type SystemContextItem as D, completeWholeValues as E, FILE_KERNEL_ID as F, contextFieldFromStore as G, contextFieldKind as H, INCOMPLETE_SAVE_REFUSAL as I, contextValueFromStore as J, createScopeDoors as K, incompleteSaveRefusal as L, referenceFence as M, referencesOf as N, scopeFromStore as O, scopeTypeFromStore as P, scopeWithTypeFromStore as Q, type ReadContextFileText as R, SCOPES_PER_CALL as S, TYPE_SCOPES_PAGE as T, settingFromStore as U, type ArchivedScope as a, type ArchivedScopeType as b, type ContextField as c, type ContextFieldKind as d, type ContextFieldSpec as e, type ContextPolicy as f, type ContextReference as g, type ContextSensitivity as h, type ContextValue as i, type ContextValueWrite as j, type ContextValueWritten as k, type IncompleteValue as l, SCOPES_PER_VALUES_CALL as m, SCOPE_TYPES_PER_FIELDS_CALL as n, type Scope as o, type ScopeDoorCall as p, type ScopeDoors as q, type ScopePage as r, type ScopeSpec as s, type ScopeTemplate as t, type ScopeType as u, type ScopeTypeLabel as v, type ScopeTypeSkeleton as w, type ScopeTypeSpec as x, type ScopeTypeWithScopes as y, type ScopeWithType as z };