@ai-matrx/records 0.55.1 → 0.56.0

package/dist/{field-Dr7Ugek4.d.cts → types-RxnWzAWZ.d.cts}

@@ -4259,4 +4259,338 @@ interface FieldPatch {
     expr?: Record<string, unknown>;
 }
 
-export { MERGE_FIELD_MODIFIERS as $, ABSENCE_REASONS as A, CONTEXT_POLICIES as B, type ComputeOn as C, DECLARABLE_FIELD_KINDS as D, DELIVERIES as E, type FieldTypeWord as F, type DeclarableFieldKind as G, type Delivery as H, ENTITY_TOKENS as I, type EntityToken as J, FIELD_SENSITIVITIES as K, FIELD_SOURCES as L, FRESHNESS as M, type NewFieldDeclaration as N, type OnDelete as O, type PgError as P, type FieldBehavior as Q, type RelationFlavor as R, type StorageMode as S, type TableType as T, type Uuid as U, type ForbiddenEnvelopeWord as V, type WriteConflict as W, type Freshness as X, type HiddenFieldNotice as Y, KERNEL_TABLES as Z, type KernelTableName as _, type TableDisplay as a, MERGE_FIELD_SEMANTIC_TYPES as a0, MERGE_FIELD_SOURCES as a1, type MergeFieldModifier as a2, type MergeFieldSemanticType as a3, type MergeFieldSource as a4, ON_DELETE as a5, OVERRIDE_POLICIES as a6, type OverridePolicy as a7, PARITY_FIELD_TYPES as a8, PER_VALUE_ACCESS_WORDS as a9, VALUE_ALTERNATE_KEYS as aA, VALUE_ENVELOPE_KEYS as aB, type ValueAlternate as aC, type ValueAlternateKey as aD, type ValueEnvelope as aE, type ValueEnvelopeKey as aF, type ValueSource as aG, err as aH, isRecordsErr as aI, ok as aJ, type ParityFieldType as aa, type ParityFieldTypeDescriptor as ab, type PerValueAccessWord as ac, type ProvenancePointer as ad, RELATION_BINDINGS as ae, RELATION_CARDINALITIES as af, RELATION_FLAVORS as ag, RETIRED_ACTOR_WORDS as ah, RULE_NODE_KINDS as ai, RULE_USES as aj, type RecordsErrorCode as ak, type RelationBinding as al, type RelationDisplay as am, type RetiredActorWord as an, type RuleNodeKind as ao, type RuleUse as ap, STORAGE_MODES as aq, STORE_DOORS as ar, STORE_KNOBS as as, STORE_REFUSAL_CODES as at, type StoreDoorName as au, type StoreRefusalCode as av, TABLE_DISPLAYS as aw, TABLE_ORIGINS as ax, TABLE_TYPES as ay, type TableOrigin as az, type FieldSource as b, type FieldRule as c, type FieldSensitivity as d, type ContextPolicy as e, type RelationCardinality as f, type Timestamp as g, type RecordDocument as h, type RecordsResult as i, type RecordGraphWritten as j, type RecordRead as k, type ReadRow as l, type Field as m, type StoredRecord as n, type FieldPatch as o, type RecordRevision as p, type ReadValue as q, type FieldProposal as r, type TableProposal as s, type RecordsError as t, type StaleWriteDetail as u, type PredictedRefusal as v, ACTOR_VOCABULARY as w, type AbsenceReason as x, type Actor as y, COMPUTE_ON as z };
+/**
+ * Who the data belongs to. A test organization is created under this name — the
+ * owner's law #4: every organization, table, record, form, portal, dashboard,
+ * document, checklist, booking page, capture sheet, subscription, pipeline and
+ * enrichment created for a test carries the use case's own name. Cleanup finds
+ * a test organization by `cleanupTag` in its settings, NEVER by a junk name.
+ */
+interface BusinessIdentity {
+    /** "Harbor Dental Group" — what goes on the organization, the invoice, the screenshot. */
+    name: string;
+    /** "Harbor Dental Group, PLLC" — used on documents that need the legal entity. */
+    legalName?: string;
+    /** One line a stranger would understand: "A six-chair family dental practice." */
+    describes: string;
+    /** Plausible and synthesized. Never a real business's real address. */
+    address: PostalAddress;
+    /** Synthesized, E.164-shaped or the local convention the document uses. */
+    phone: string;
+    /**
+     * Synthesized. NOT a `.example` domain — those read as fake on a screenshot.
+     * Optional, because the law welcomes personal-life use cases and a household
+     * renovation or a family recipe collection genuinely has no website.
+     */
+    website?: string;
+    /** Synthesized mailbox on the same domain: "frontdesk@harbordentalgroup.com". */
+    email: string;
+    /** IANA zone, so dates in the rows make sense together. */
+    timezone: string;
+}
+interface PostalAddress {
+    line1: string;
+    line2?: string;
+    city: string;
+    /** State, province or region, in the country's own convention. */
+    region: string;
+    postalCode: string;
+    /** ISO 3166-1 alpha-2. */
+    country: string;
+}
+/**
+ * One table of the business, in the words the practitioner uses. `token` is the
+ * slug the store addresses it by; `name` is what a person reads.
+ */
+interface UseCaseTable {
+    /** snake_case, singular, the practitioner's noun: "patient", "work_order". */
+    token: string;
+    /** "Patients", "Work orders". */
+    name: string;
+    labelSingular: string;
+    labelPlural: string;
+    /** REC-32. One of the seven, closed. Most business tables are `entity`. */
+    type: TableType;
+    display: TableDisplay;
+    /** REC-4. `light` is the whole document; `heavy` is indexed on write. */
+    weight: StorageMode;
+    ordered: boolean;
+    /** A lucide icon name, so the screen is not a wall of identical rows. */
+    icon?: string;
+    /** REC-2. The field key whose value titles a record. Must be a declared field. */
+    titleField: string;
+    /** What this table is FOR, in the practitioner's words. */
+    describes: string;
+    fields: UseCaseField[];
+    /** The seed rows. Enough that the screen looks like a working business. */
+    rows: UseCaseRow[];
+}
+/**
+ * One field. `parityType` is the word a person picks in the UI and it must be
+ * one the store resolves — any parity type the store ships, any behaviour they
+ * are made of, or one of the plain synonyms (see `FieldTypeWord`). The set is
+ * `RESOLVABLE_FIELD_TYPE_WORDS`, derived from the registry; never a count or a
+ * list typed out here.
+ */
+interface UseCaseField {
+    /** snake_case, the practitioner's own name for it: "date_of_birth", "po_number". */
+    key: string;
+    /** "Date of birth", "PO number". Sentence case, the way the form reads. */
+    label: string;
+    parityType: FieldTypeWord;
+    /** FLD-2. The shape of the value, never a second behaviour. */
+    multi?: boolean;
+    /** FLD-2. The values carry their own dates. */
+    dated?: boolean;
+    required?: boolean;
+    /** FLD-N-1. The unit CHANGES THE MEANING and lives on the field: "USD", "lb", "mi". */
+    unit?: string | null;
+    /** "currency", "percent", "email", "phone", "url", "date". Never decoration. */
+    format?: string | null;
+    /** FLD-7. Where the values come from. Defaults to `manual`. */
+    source?: FieldSource;
+    /** FLD-9. A formula says whether it computes on read or on write. */
+    computeOn?: ComputeOn;
+    /** FLD-3. Validation rules the store will enforce. */
+    rules?: FieldRule[];
+    /**
+     * For `select` / `multi_select`: the REAL lifecycle words of this business,
+     * in the order they actually happen. "Scheduled, Confirmed, Seen, No-show" —
+     * never "Option A, Option B".
+     */
+    choices?: string[];
+    /** For a relation field: the `token` of the table it points at. */
+    relationTarget?: string;
+    relationMax?: number;
+    /** AGT-7. The ceiling a merge field's delivery can never widen. */
+    sensitivity: FieldSensitivity;
+    /** FLD-12. Whether an agent may see this field's values at all. */
+    contextPolicy: ContextPolicy;
+    /** What the practitioner would be told about this field, if anything. */
+    help?: string;
+}
+/**
+ * One row of seed data.
+ *
+ * `key` is a stable LOCAL id (not a UUID): relationships across tables point at
+ * it, so a template is readable and a seeder can resolve the graph in one pass
+ * without inventing identifiers. Use a meaningful slug — "patient-rivera-m",
+ * not "row-7".
+ */
+interface UseCaseRow {
+    key: string;
+    /**
+     * Keyed by the table's field keys. A relation field's value is the `key` (or
+     * an array of keys) of rows in the target table.
+     */
+    values: Record<string, unknown>;
+}
+/**
+ * REL-1…REL-9. The domain truth, stated once: "an invoice belongs to the job it
+ * bills, and a job belongs to the client who asked for it."
+ *
+ * The field side carries `relationTarget`; this is the declaration a seeder
+ * reads, because it also carries the flavour, the cardinality, what happens to
+ * the far side on delete, and the reverse name.
+ */
+interface UseCaseRelationship {
+    /** One sentence of domain truth. Not "links A to B". */
+    describes: string;
+    /** The table that HOLDS the relation field. */
+    fromTable: string;
+    /** The field key on `fromTable`. Must be declared and must be a relation. */
+    fromField: string;
+    /** The `token` of the table it points at. */
+    toTable: string;
+    /** REL-1. Ownership is one fact, stored once, read from the field's side. */
+    flavor: RelationFlavor;
+    /** REL-7. */
+    cardinality: RelationCardinality;
+    /** REL-2. What happens to the far side, separate from flavour. */
+    onDelete: OnDelete;
+    /** REL-9. The reverse, visible from both ends, and NOT a second field. */
+    inverseKey: string;
+}
+/** Who is allowed to open a form. */
+type FormAudience = "public" | "member" | "staff";
+/**
+ * A form a practitioner in this business would actually put in front of someone
+ * — "the Harbor Dental new-patient intake", never "Test Form 1".
+ */
+interface UseCaseForm {
+    token: string;
+    name: string;
+    /** What it is for, and who fills it in. */
+    describes: string;
+    audience: FormAudience;
+    /** The table a submission becomes a record of. */
+    table: string;
+    fields: UseCaseFormField[];
+    submitLabel: string;
+    /** What the person sees after they submit. Real words, not "Success!". */
+    confirmation: string;
+}
+interface UseCaseFormField {
+    /** A field key on the form's table. */
+    fieldKey: string;
+    /** Override the field's own label when the form asks it differently. */
+    label?: string;
+    required?: boolean;
+    /** The helper line under the input, if a practitioner would want one. */
+    help?: string;
+}
+/**
+ * The real lifecycle a record moves through in this business, in order. A
+ * pipeline's stages are the words the staff say out loud.
+ */
+interface UseCasePipeline {
+    token: string;
+    name: string;
+    describes: string;
+    /** The table whose records move through it. */
+    table: string;
+    /** The `select` field that holds the current stage. */
+    stageField: string;
+    stages: UseCasePipelineStage[];
+}
+interface UseCasePipelineStage {
+    /** Must appear in the stage field's `choices`. */
+    key: string;
+    label: string;
+    /** What is true of a record sitting here, and what moves it on. */
+    describes: string;
+    /** Roughly how long a record sits here, so a board looks believable. */
+    typicalDurationDays?: number;
+}
+/**
+ * The question the owner of this business actually asks a dashboard on Monday
+ * morning — "how much have we invoiced this month that hasn't been paid?" —
+ * plus how it is answered from the tables above.
+ */
+interface UseCaseDashboardQuestion {
+    /** The question in the practitioner's own words, ending in a question mark. */
+    question: string;
+    /** Why they care. What they DO differently depending on the answer. */
+    whyItMatters: string;
+    table: string;
+    aggregate: "count" | "sum" | "avg" | "min" | "max";
+    /** The field aggregated. Omitted only for `count`. */
+    of?: string;
+    groupBy?: string;
+    /** A plain-language filter: "status is Unpaid and due_date is before today". */
+    filter?: string;
+    /** What the number IS: "USD", "days", "appointments". */
+    answerUnit: string;
+}
+/**
+ * A document this business really sends. The body carries merge fields in
+ * `{{double_brace}}` form; every one of them is declared below and resolves to a
+ * field on the document's table (or a stated literal).
+ */
+interface UseCaseDocumentTemplate {
+    token: string;
+    name: string;
+    describes: string;
+    table: string;
+    /** The subject or title line, merge fields allowed. */
+    title: string;
+    /** The body. Real prose this business would send, merge fields inline. */
+    body: string;
+    mergeFields: UseCaseMergeField[];
+}
+interface UseCaseMergeField {
+    /** The token inside `{{ }}` in the body. */
+    key: string;
+    /**
+     * The field key it reads, on the document's table — or, when it is not a
+     * field, the word `business` (from `BusinessIdentity`) or `today`.
+     */
+    from: string;
+    describes: string;
+}
+/** How a notification reaches someone. */
+type NotificationChannel = "email" | "sms" | "in_app";
+/**
+ * The one automatic message this business would genuinely want — the thing a
+ * practitioner sets up on day one and never turns off.
+ */
+interface UseCaseNotificationRule {
+    token: string;
+    name: string;
+    describes: string;
+    when: UseCaseNotificationTrigger;
+    /** Who it goes to, in the business's own words: "the assigned hygienist". */
+    audience: string;
+    channel: NotificationChannel;
+    /** The actual message. Merge fields allowed, same convention as documents. */
+    message: string;
+}
+interface UseCaseNotificationTrigger {
+    table: string;
+    event: "created" | "updated" | "stage_entered" | "due" | "overdue";
+    /** For `stage_entered`: the stage key. */
+    stage?: string;
+    /** For `due` / `overdue`: the date field watched. */
+    field?: string;
+    /** For `due`: how many days ahead it fires. */
+    daysBefore?: number;
+}
+/**
+ * Where the shape and the values came from. `synthesized` means a person wrote
+ * plausible values out of domain knowledge; `public-data` means the numbers or
+ * names were derived from a genuinely public dataset, which is named.
+ *
+ * Either way the law holds: no real person, no real customer, no production row.
+ */
+interface UseCaseProvenance {
+    kind: "synthesized" | "public-data";
+    /** Named when `kind` is `public-data`. */
+    source?: string;
+    /** Who or what wrote this file, and when. */
+    authoredBy: string;
+    authoredOn: string;
+    /**
+     * The affirmation, carried in the data so a reviewer can see it: every person,
+     * address, phone and mailbox here is invented and belongs to nobody.
+     */
+    noRealPeople: true;
+}
+/** One real business, and everything a test, seed, demo or screenshot needs of it. */
+interface UseCase {
+    /** kebab-case and unique: "harbor-dental-new-patient-intake". */
+    id: string;
+    /**
+     * THE SENTENCE. Who the user is, what business they run, and what job this
+     * exact feature does for them — one sentence, at the top, before anything
+     * else. This is the first thing the law asks for and the validator checks it.
+     */
+    useCase: string;
+    /** The industry, for rotation: "Dentistry", "Property management". */
+    industry: string;
+    business: BusinessIdentity;
+    /**
+     * The tag written into a test organization's settings so cleanup can find it.
+     * Cleanup finds test data by THIS, never by a junk name.
+     */
+    cleanupTag: string;
+    tables: UseCaseTable[];
+    relationships: UseCaseRelationship[];
+    form: UseCaseForm;
+    pipeline: UseCasePipeline;
+    dashboardQuestion: UseCaseDashboardQuestion;
+    documentTemplate: UseCaseDocumentTemplate;
+    notificationRule: UseCaseNotificationRule;
+    provenance: UseCaseProvenance;
+}
+/** What the registry lists without loading a use case's rows. */
+interface UseCaseSummary {
+    id: string;
+    useCase: string;
+    industry: string;
+    businessName: string;
+    /** How many tables and rows the file carries, so a caller can pick by size. */
+    tableCount: number;
+    rowCount: number;
+}
+
+export { type EntityToken as $, type TableProposal as A, type BusinessIdentity as B, type RecordsError as C, type PgError as D, type StaleWriteDetail as E, type FormAudience as F, type PredictedRefusal as G, ABSENCE_REASONS as H, ACTOR_VOCABULARY as I, type AbsenceReason as J, type Actor as K, COMPUTE_ON as L, CONTEXT_POLICIES as M, type NotificationChannel as N, type ComputeOn as O, type PostalAddress as P, type ContextPolicy as Q, type RecordDocument as R, type StoredRecord as S, type Timestamp as T, type UseCase as U, DECLARABLE_FIELD_KINDS as V, type WriteConflict as W, DELIVERIES as X, type DeclarableFieldKind as Y, type Delivery as Z, ENTITY_TOKENS as _, type UseCaseSummary as a, err as a$, FIELD_SENSITIVITIES as a0, FIELD_SOURCES as a1, FRESHNESS as a2, type FieldBehavior as a3, type FieldRule as a4, type FieldSensitivity as a5, type FieldSource as a6, type FieldTypeWord as a7, type ForbiddenEnvelopeWord as a8, type Freshness as a9, type RelationBinding as aA, type RelationCardinality as aB, type RelationDisplay as aC, type RelationFlavor as aD, type RetiredActorWord as aE, type RuleNodeKind as aF, type RuleUse as aG, STORAGE_MODES as aH, STORE_DOORS as aI, STORE_KNOBS as aJ, STORE_REFUSAL_CODES as aK, type StorageMode as aL, type StoreDoorName as aM, type StoreRefusalCode as aN, TABLE_DISPLAYS as aO, TABLE_ORIGINS as aP, TABLE_TYPES as aQ, type TableDisplay as aR, type TableOrigin as aS, type TableType as aT, VALUE_ALTERNATE_KEYS as aU, VALUE_ENVELOPE_KEYS as aV, type ValueAlternate as aW, type ValueAlternateKey as aX, type ValueEnvelope as aY, type ValueEnvelopeKey as aZ, type ValueSource as a_, type HiddenFieldNotice as aa, KERNEL_TABLES as ab, type KernelTableName as ac, MERGE_FIELD_MODIFIERS as ad, MERGE_FIELD_SEMANTIC_TYPES as ae, MERGE_FIELD_SOURCES as af, type MergeFieldModifier as ag, type MergeFieldSemanticType as ah, type MergeFieldSource as ai, ON_DELETE as aj, OVERRIDE_POLICIES as ak, type OnDelete as al, type OverridePolicy as am, PARITY_FIELD_TYPES as an, PER_VALUE_ACCESS_WORDS as ao, type ParityFieldType as ap, type ParityFieldTypeDescriptor as aq, type PerValueAccessWord as ar, type ProvenancePointer as as, RELATION_BINDINGS as at, RELATION_CARDINALITIES as au, RELATION_FLAVORS as av, RETIRED_ACTOR_WORDS as aw, RULE_NODE_KINDS as ax, RULE_USES as ay, type RecordsErrorCode as az, type UseCaseDashboardQuestion as b, isRecordsErr as b0, ok as b1, type UseCaseDocumentTemplate as c, type UseCaseField as d, type UseCaseForm as e, type UseCaseFormField as f, type UseCaseMergeField as g, type UseCaseNotificationRule as h, type UseCaseNotificationTrigger as i, type UseCasePipeline as j, type UseCasePipelineStage as k, type UseCaseProvenance as l, type UseCaseRelationship as m, type UseCaseRow as n, type UseCaseTable as o, type Uuid as p, type RecordsResult as q, type RecordGraphWritten as r, type RecordRead as s, type ReadRow as t, type Field as u, type NewFieldDeclaration as v, type FieldPatch as w, type RecordRevision as x, type ReadValue as y, type FieldProposal as z };