@stndrds/schema 1.0.0-alpha.192 → 1.0.0-alpha.194

package/dist/attributes-DP08iPCh.d.mts

@@ -0,0 +1,889 @@
+import { IconName, CountryIso3, CurrencyCode, ColorId, MimeType } from '@stndrds/constants';
+import { Uuid } from './utils.mjs';
+
+type ComputedReturnType = "text" | "number" | "boolean" | "date" | "select" | "multiselect";
+type ComputedFieldKind = "formula" | "rollup";
+type ComputedValueType = {
+    kind: "scalar";
+    type: Exclude<ComputedReturnType, "multiselect">;
+} | {
+    kind: "collection";
+    itemType: "text" | "number" | "boolean" | "date" | "select";
+};
+type ComputedStateStatus = "pending" | "fresh" | "stale" | "failed";
+interface ComputedOptionsSource {
+    objectName: string;
+    attributeName: string;
+    attributeId?: string;
+}
+interface ComputedAttributeState {
+    attributeName: string;
+    status: ComputedStateStatus;
+    computedAt: Date | null;
+    staleSince: Date | null;
+    dependenciesHash: string | null;
+    jobId: string | null;
+    error: string | null;
+    updatedAt: Date;
+}
+type ComputedDependency = {
+    kind: "local";
+    attributeName: string;
+} | {
+    kind: "relation";
+    relationName: string;
+    targetAttributeName?: string;
+    cardinality?: "one" | "many";
+} | {
+    kind: "computed";
+    attributeName: string;
+} | {
+    kind: "options";
+    source: ComputedOptionsSource;
+};
+interface ComputedPlan {
+    kind: ComputedFieldKind;
+    attributeName: string;
+    expression: string;
+    returnType: ComputedReturnType;
+    valueType: ComputedValueType;
+    dependencies: ComputedDependency[];
+    optionsSource?: ComputedOptionsSource;
+    targetAttributeType?: AttributeType;
+    dependenciesHash: string;
+}
+
+interface DocumentLayout {
+    /** Named sub-folders auto-created at the top of the record's drive when first used via attach --variant. */
+    variants?: Record<string, DocumentLayoutVariant>;
+    /** Dev-declared folder structures the user can instantiate via the UI inside a record's drive. */
+    presets?: FolderPreset[];
+}
+interface DocumentLayoutVariant {
+    /** Display title for the auto-created sub-folder. */
+    title: string;
+    description?: string;
+}
+interface FolderPreset {
+    id: string;
+    label: string;
+    icon?: IconName;
+    description?: string;
+    structure: PresetNode[];
+}
+interface PresetNode {
+    title: string;
+    description?: string;
+    children?: PresetNode[];
+}
+/** Max depth allowed for preset.structure to keep instantiation predictable. */
+declare const MAX_PRESET_DEPTH = 5;
+
+type BuiltInTransform = "toString" | "toNumber" | "toDate" | "toBoolean" | "toISOString";
+type SchemaOperation = {
+    type: "add_attribute";
+    attribute: Attribute;
+} | {
+    type: "remove_attribute";
+    name: string;
+    backup_config: Attribute;
+} | {
+    type: "rename_attribute";
+    from: string;
+    to: string;
+} | {
+    type: "change_type";
+    name: string;
+    from: AttributeType;
+    to: AttributeType;
+    transform?: BuiltInTransform;
+} | {
+    type: "update_config";
+    name: string;
+    from: Partial<Record<string, unknown>>;
+    to: Partial<Record<string, unknown>>;
+} | {
+    type: "remove_object";
+    backup: Record<string, unknown>;
+} | {
+    type: "rename_object";
+    from: string;
+    to: string;
+};
+interface MigrationDefinition {
+    version: number;
+    operations: SchemaOperation[];
+}
+
+/**
+ * Timestamps for tracking creation and updates
+ */
+interface Timestamps {
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Object definition - Represents a database table/entity
+ */
+interface ObjectDefinition {
+    id?: Uuid;
+    name: string;
+    label: string;
+    pluralLabel?: string;
+    description?: string;
+    icon?: IconName;
+    /**
+     * Template expression used to compute the object's display label.
+     * Supports variable interpolation and pipes for formatting.
+     *
+     * @example
+     * ```typescript
+     * // Simple attribute reference
+     * labelExpression: "{{ name }}"
+     *
+     * // Multiple attributes
+     * labelExpression: "{{ firstName }} {{ lastName }}"
+     *
+     * // With pipes for formatting
+     * labelExpression: "{{ code | UPPER }} - {{ name | capitalize }}"
+     * ```
+     *
+     * Available pipes: UPPER, LOWER, capitalize, trim
+     */
+    labelExpression: string;
+    attributes: Attribute[];
+    system?: boolean;
+    /**
+     * If true, no custom (user-created) attributes are allowed on this object.
+     * `standards diff` will report an error if any custom attribute is found.
+     * Use .sealed() on the ObjectBuilder to set this.
+     */
+    sealed?: boolean;
+    /**
+     * List of custom attribute names explicitly acknowledged by the developer.
+     * On a sealed object, these names will NOT trigger a CI failure.
+     * On an extensible object, this is purely documentary.
+     * Use .tolerate(["name"]) on the ObjectBuilder to set this.
+     */
+    toleratedAttributes?: string[];
+    metadata?: Record<string, unknown>;
+    /** Current schema version (incremented with each migration) */
+    schema_version: number;
+    /** Ordered list of migrations applied to this object's schema */
+    migrations: MigrationDefinition[];
+    /** Smart-folder layout convention for documents attached to records of this object. */
+    documentLayout?: DocumentLayout;
+}
+/**
+ * Links an attribute to an object
+ */
+interface ObjectAttribute {
+    objectId: Uuid;
+    attributeId: Uuid;
+    order?: number;
+    required?: boolean;
+}
+/**
+ * Completion status of a record based on data completeness.
+ *
+ * - `draft`: Record is missing one or more required attribute values.
+ *   Can be saved but is considered incomplete.
+ * - `complete`: All required attribute values are present and valid.
+ *   Record is ready for use.
+ *
+ * This is different from workflow status (e.g., "pending", "approved").
+ * Completion status is computed dynamically based on the object schema.
+ */
+type CompletionStatus = "draft" | "complete";
+/**
+ * Record - Instance of an Object (a row in the database)
+ */
+interface ObjectRecord extends Timestamps {
+    id: Uuid;
+    objectId: Uuid;
+    /**
+     * Display label computed from the object's labelExpression.
+     * Computed dynamically based on record values.
+     *
+     * @example "John Doe" (from "{{ firstName }} {{ lastName }}")
+     */
+    label: string;
+    /**
+     * Completion status of the record.
+     * - `draft`: Missing required values, record is incomplete
+     * - `complete`: All required values present and valid
+     *
+     * Computed dynamically based on the object's schema.
+     */
+    completionStatus: CompletionStatus;
+    values: Record<string, unknown>;
+    /** Per-computed-attribute state keyed by attribute name. */
+    computedStates?: Record<string, ComputedAttributeState>;
+    /**
+     * Custom metadata for the record.
+     * Use this for UI/UX state, feature flags, or any application-specific data.
+     * Unlike system fields (id, createdAt, updatedAt), metadata can be updated.
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Soft delete timestamp.
+     * If set, the record is considered deleted but can be restored.
+     * Queries exclude soft-deleted records by default.
+     */
+    deletedAt?: Date | null;
+    /**
+     * Actor ID who soft-deleted this record.
+     * Set alongside deletedAt when a record is soft-deleted.
+     */
+    deletedBy?: string | null;
+    /**
+     * Actor ID who created this record.
+     * Automatically set by RecordService when actorId is configured.
+     * Optional for backward compatibility with existing records.
+     */
+    createdBy?: string;
+    /**
+     * Actor ID who last updated this record.
+     * Automatically set by RecordService when actorId is configured.
+     * Optional for backward compatibility with existing records.
+     */
+    lastUpdatedBy?: string;
+    /** Schema version at the time this record was last migrated */
+    schemaVersion: number;
+}
+/**
+ * System-managed field names on ObjectRecord.
+ * These are stored as SQL columns (not in JSONB `values`).
+ *
+ * Use this in adapters to determine if a filter/sort attribute is a table column
+ * vs. a JSONB value field.
+ *
+ * @example
+ * ```typescript
+ * if (SYSTEM_FIELD_NAMES.includes(filter.attribute)) {
+ *   // Filter on SQL column (e.g., WHERE created_at > ...)
+ * } else {
+ *   // Filter on JSONB field (e.g., WHERE values->>'name' = ...)
+ * }
+ * ```
+ */
+declare const SYSTEM_FIELD_NAMES: readonly ["id", "createdAt", "updatedAt", "createdBy", "lastUpdatedBy"];
+/**
+ * Type for system field names
+ */
+type SystemFieldName = (typeof SYSTEM_FIELD_NAMES)[number];
+/**
+ * Reserved attribute names that cannot be used for custom attributes.
+ * These names conflict with ObjectRecord properties.
+ *
+ * Includes:
+ * - System fields (id, createdAt, updatedAt, createdBy, lastUpdatedBy)
+ * - Other ObjectRecord properties (objectId, label, completionStatus, values, metadata, deletedAt)
+ *
+ * @example
+ * ```typescript
+ * if (RESERVED_ATTRIBUTE_NAMES.includes(attributeName)) {
+ *   throw new Error(`"${attributeName}" is a reserved name`);
+ * }
+ * ```
+ */
+declare const RESERVED_ATTRIBUTE_NAMES: readonly ["id", "createdAt", "updatedAt", "createdBy", "lastUpdatedBy", "objectId", "label", "completionStatus", "values", "metadata", "deletedAt", "deletedBy", "schemaVersion"];
+/**
+ * Type for reserved attribute names
+ */
+type ReservedAttributeName = (typeof RESERVED_ATTRIBUTE_NAMES)[number];
+
+type DocumentKind = "file" | "folder";
+interface Document extends Timestamps {
+    id: Uuid;
+    tenantId: Uuid;
+    title: string;
+    kind: DocumentKind;
+    parentId?: Uuid | null;
+    description?: string;
+    contentHash?: string;
+    createdBy?: Uuid;
+    updatedBy?: Uuid;
+    deletedAt?: Date | null;
+    /**
+     * Fractional ordering position within `(tenantId, parentId)`. Lower values
+     * sort first. New rows default to `max(siblings) + 1024` so reorderings can
+     * insert between neighbours without renumbering. The server may rebalance
+     * positions in the background to keep the spacing bounded.
+     */
+    position: number;
+}
+interface DocumentWithSubCount extends Document {
+    subCount: number | null;
+}
+/**
+ * Configuration for a single named slot on a DocumentAttribute.
+ * Slots are placeholders for files within a Document; declared at design-time
+ * on the attribute and validated at attach time.
+ */
+interface DocumentSlotConfig {
+    /** Stable identifier referenced in DB. */
+    name: string;
+    /** Display label in UI. Falls back to `name` if absent. */
+    label?: string;
+    /** Description shown to users and to the AI in tool context. */
+    description?: string;
+    /** Surfaced to UI/AI but not enforced by the system. */
+    required?: boolean;
+    /** MIME prefixes or globs (e.g. "image/*", "application/pdf"). */
+    acceptedMimeTypes?: string[];
+    /** Hard ceiling enforced by the service before upload. */
+    maxSizeBytes?: number;
+}
+/** Default applied by the document() builder when no slots are configured. */
+declare const DEFAULT_DOCUMENT_SLOT: DocumentSlotConfig;
+interface DocumentSlot extends Timestamps {
+    id: Uuid;
+    tenantId: Uuid;
+    documentId: Uuid;
+    slotName: string;
+    isAdditional: boolean;
+    fileId: Uuid;
+    status: SlotStatus;
+    ocrText?: string;
+    ocrConfidence?: number;
+    processedAt?: Date;
+}
+type SlotStatus = "uploaded" | "processing" | "completed" | "failed";
+interface CreateDocument {
+    title: string;
+    kind?: DocumentKind;
+    parentId?: Uuid | null;
+    description?: string;
+    position?: number;
+}
+/**
+ * Reference to a record attribute that should atomically attach a freshly
+ * created Document. Passed alongside `CreateDocument` to make creation
+ * link-aware end-to-end (client → REST → service → repo).
+ *
+ * The server requires this — orphan Documents are not creatable through the
+ * REST API.
+ */
+interface CreateDocumentLink {
+    objectName: string;
+    sourceRecordId: string;
+    attributeName: string;
+    /**
+     * Optional qualifyWith properties on the record→Document edge. Currently
+     * accepted by the controller DTO but silently ignored by the service (see
+     * `DocumentService.createDocument` — there's a TODO to support this).
+     */
+    properties?: Record<string, unknown>;
+}
+interface UpdateDocument {
+    title?: string;
+    parentId?: Uuid | null;
+    position?: number;
+}
+interface CreateDocumentSlot {
+    documentId: Uuid;
+    slotName: string;
+    fileId: Uuid;
+    isAdditional?: boolean;
+}
+interface UpdateDocumentSlot {
+    status?: SlotStatus;
+    ocrText?: string;
+    ocrConfidence?: number;
+}
+interface DocumentListOptions {
+    limit?: number;
+    offset?: number;
+}
+interface DocumentWithSlots extends Document {
+    slots: DocumentSlot[];
+}
+interface RecordDocuments {
+    /** Documents grouped by attribute name (includes system 'attachments' attribute) */
+    byAttribute: Record<string, DocumentWithSlots[]>;
+}
+
+/**
+ * Allowed attribute types in .qualifyWith()
+ *
+ * IMPORTANT: Complex types (formula, rollup, relation, file, user, document, richtext)
+ * are NOT supported to avoid duplicating backend behavior.
+ */
+type PropertyType = "text" | "number" | "checkbox" | "date" | "phone" | "currency" | "status" | "select" | "multiselect" | "location";
+/**
+ * Union of attribute types allowed as qualified relation properties.
+ *
+ * These are the same Attribute types used for object attributes,
+ * restricted to simple types that don't require complex backend duplication.
+ */
+type PropertyAttribute = TextAttribute | NumberAttribute | CheckboxAttribute | DateAttribute | PhoneAttribute | CurrencyAttribute | StatusAttribute | SelectAttribute | MultiselectAttribute | LocationAttribute;
+/**
+ * Schema defining properties for a qualified relation.
+ *
+ * Uses the same Attribute types as object attributes, enabling DRY builders:
+ *
+ * @example
+ * ```typescript
+ * relation({ name: "companies", label: "Companies" })
+ *   .to("companies").many()
+ *   .qualifyWith(
+ *     select({ name: "role", label: "Role" }).options([...]).required(),
+ *     number({ name: "shares", label: "Shares" }).min(0),
+ *   )
+ * ```
+ */
+interface PropertySchema {
+    definitions: PropertyAttribute[];
+}
+/**
+ * Property attribute types that have an `options` array.
+ */
+type OptionPropertyAttribute = SelectAttribute | StatusAttribute | MultiselectAttribute;
+/**
+ * Type guard to check if a property attribute has options.
+ *
+ * @param attr - The property attribute to check
+ * @returns true if the attribute is a select, status, or multiselect type with options
+ *
+ * @example
+ * ```typescript
+ * for (const def of definitions) {
+ *   if (hasOptions(def)) {
+ *     // TypeScript knows def.options exists and is Option[]
+ *     for (const option of def.options) {
+ *       console.log(option.value);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function hasOptions(attr: PropertyAttribute): attr is OptionPropertyAttribute;
+
+type AttributeType = "text" | "richtext" | "number" | "checkbox" | "date" | "phone" | "currency" | "status" | "location" | "select" | "multiselect" | "file" | "user" | "relation" | "formula" | "rollup" | "document";
+/**
+ * Status group categorization
+ */
+type StatusGroup = "idle" | "in_progress" | "finished";
+/**
+ * Unified option type for select-like fields
+ */
+interface Option {
+    value: string;
+    label: string;
+    color?: ColorId;
+    description?: string;
+    group?: StatusGroup;
+    /** Value of the inverse option for bilateral relations (e.g. "parent" → "child") */
+    inverse?: string;
+    archived?: boolean;
+}
+/**
+ * Attribute grouping for UI organization
+ */
+interface AttributeGroup {
+    id: string;
+    label: string;
+    description?: string;
+    attributeIds: string[];
+    collapsible?: boolean;
+    collapsed?: boolean;
+    order?: number;
+}
+interface BaseAttribute<DefaultValueType = unknown> {
+    id?: Uuid;
+    objectId?: Uuid;
+    name: string;
+    label: string;
+    type: AttributeType;
+    required?: boolean;
+    placeholder?: string;
+    description?: string;
+    defaultValue?: DefaultValueType;
+    icon?: IconName;
+    order?: number;
+    hidden?: boolean;
+    archived?: boolean;
+    deprecated?: boolean;
+    system?: boolean;
+    unique?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface TextAttribute extends BaseAttribute<string> {
+    type: "text";
+    multiline?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: "email" | "url" | "slug";
+}
+type NumberUnit = "integer" | "decimal" | "percentage";
+interface NumberAttribute extends BaseAttribute<number> {
+    type: "number";
+    min?: number;
+    max?: number;
+    unit?: NumberUnit;
+    decimals?: number;
+    renderAs?: "number" | "rating";
+}
+interface CheckboxAttribute extends BaseAttribute<boolean> {
+    type: "checkbox";
+}
+type DateFormat = "short" | "long" | "full" | "relative";
+type DateValue = string | "today";
+interface DateAttribute extends BaseAttribute<string> {
+    type: "date";
+    dateFormat?: DateFormat;
+    minDate?: DateValue;
+    maxDate?: DateValue;
+}
+interface Phone {
+    countryCode: CountryIso3;
+    phoneNumber: string;
+}
+interface PhoneAttribute extends BaseAttribute<Phone> {
+    type: "phone";
+    defaultCountryCode?: CountryIso3;
+}
+interface Currency {
+    code: CurrencyCode;
+    value: number;
+}
+interface CurrencyAttribute extends BaseAttribute<Currency> {
+    type: "currency";
+    defaultCurrency?: CurrencyCode;
+    allowedCurrencies?: CurrencyCode[];
+    /** Allow negative currency values (e.g. refunds, credits). Defaults to false. */
+    allowNegative?: boolean;
+}
+/**
+ * StatusAttribute - For workflow states with semantic grouping (idle/in_progress/finished)
+ * Use this for: Task status, Order status, Project phases, Process states
+ * Use SelectAttribute for: Categories, Types, simple choices without workflow
+ */
+interface StatusAttribute extends BaseAttribute<string> {
+    type: "status";
+    options: Option[];
+}
+interface Location {
+    address?: string;
+    address2?: string;
+    city?: string;
+    state?: string;
+    postalCode?: string;
+    country?: CountryIso3;
+    latitude?: number;
+    longitude?: number;
+}
+type LocationGranularity = "full" | "address" | "city" | "state" | "country" | "coordinates";
+interface LocationAttribute extends BaseAttribute<Location> {
+    type: "location";
+    granularity?: LocationGranularity;
+    defaultCountry?: CountryIso3;
+    allowedCountries?: CountryIso3[];
+}
+/**
+ * SelectAttribute - For simple single-choice selection
+ * Use this for: Categories, Document types, Departments, Priorities
+ * Options can be grouped (e.g., countries by continent) but no workflow logic
+ */
+interface SelectAttribute extends BaseAttribute<string> {
+    type: "select";
+    options: Option[];
+}
+interface MultiselectAttribute extends BaseAttribute<string[]> {
+    type: "multiselect";
+    options: Option[];
+}
+interface FileAttribute extends BaseAttribute<string> {
+    type: "file";
+    maxFiles?: number;
+    maxSize?: number;
+    allowedTypes?: MimeType[] | readonly MimeType[];
+    multiple?: boolean;
+}
+type UserReferenceType = "user" | "agent";
+interface UserAttribute extends BaseAttribute<string | string[]> {
+    type: "user";
+    types?: UserReferenceType[];
+    multiple?: boolean;
+}
+/**
+ * Wildcard marker for universal relations (can link to any object)
+ * Use with `.toAny()` builder method
+ */
+declare const RELATION_TARGET_ANY: "*";
+/**
+ * Configuration for bilateral synchronization (bidirectional relations)
+ */
+interface BilateralConfig {
+    /** Target object containing the inverse attribute */
+    object: string;
+    /** Name of the inverse attribute */
+    attribute: string;
+    /** Optional cardinality override (inferred by default) */
+    cardinality?: "one" | "many";
+    /** When true, this side owns the storage direction for qualified properties.
+     *  Set to false on the inverse side (enriched at read time). */
+    storageOwner?: boolean;
+}
+/**
+ * Target object for a relation - defines which objects can be linked
+ */
+interface RelationTarget {
+    /** Object name (e.g., "companies", "contacts") or "*" for any object */
+    object: string;
+    /**
+     * Display template for the label using mustache-like syntax
+     * @example "{name}" or "{firstName} {lastName} — {email}"
+     */
+    displayTemplate?: string;
+    /**
+     * Optional filter to restrict available records
+     * @example { status: "active" }
+     */
+    filter?: Record<string, unknown>;
+}
+/**
+ * Base properties shared by both single and multi relation attributes
+ *
+ * Note: Deletion behavior is always "restrict" - if a record is referenced
+ * by other records, it cannot be deleted until those references are removed.
+ * This is enforced by RecordService.deleteRecord() which throws
+ * RecordReferencedError when attempting to delete a referenced record.
+ */
+interface RelationAttributeBase extends Omit<BaseAttribute<unknown>, "defaultValue"> {
+    type: "relation";
+    /** Target objects that can be linked */
+    targets: RelationTarget[];
+    /** Optional properties schema for qualified relations */
+    properties?: PropertySchema;
+    /** Configuration for bilateral synchronization (opt-in) */
+    bilateral?: BilateralConfig;
+}
+/**
+ * Single relation attribute (one-to-one or many-to-one)
+ * Stores a single record ID or null
+ */
+interface SingleRelationAttribute extends RelationAttributeBase {
+    cardinality: "one";
+    defaultValue?: string | null;
+}
+/**
+ * Multi relation attribute (one-to-many or many-to-many)
+ * Stores an array of record IDs
+ */
+interface MultiRelationAttribute extends RelationAttributeBase {
+    cardinality: "many";
+    defaultValue?: string[];
+    /** Maximum number of relations allowed */
+    maxItems?: number;
+}
+/**
+ * RelationAttribute links to other objects/records
+ * Discriminated union by cardinality for type-safe value handling
+ *
+ * @example Single relation (many-to-one)
+ * ```typescript
+ * relation({ name: "company", label: "Company" })
+ *   .to("companies")
+ *   .required()
+ * // → Value: "rec-uuid-123" | null
+ * ```
+ *
+ * @example Multi relation (many-to-many)
+ * ```typescript
+ * relation({ name: "contacts", label: "Contacts" })
+ *   .to("contacts", { displayTemplate: "{firstName} {lastName}" })
+ *   .many()
+ *   .maxItems(5)
+ * // → Value: ["rec-1", "rec-2", ...]
+ * ```
+ *
+ * @example Polymorphic relation (multiple target objects)
+ * ```typescript
+ * relation({ name: "linked", label: "Linked Items" })
+ *   .to("companies")
+ *   .to("contacts")
+ *   .to("deals")
+ *   .many()
+ * // → Can link to records from any of these objects
+ * ```
+ */
+type RelationAttribute = SingleRelationAttribute | MultiRelationAttribute;
+/**
+ * Check if a relation attribute is universal (can link to any object)
+ * Universal relations have `targets: [{ object: "*" }]`
+ */
+declare function isUniversalRelation(attr: RelationAttribute): boolean;
+/**
+ * Check if a relation attribute has bilateral synchronization enabled
+ */
+declare function isBilateralRelation(attr: RelationAttribute): attr is RelationAttribute & {
+    bilateral: BilateralConfig;
+};
+/**
+ * Infer the cardinality of the inverse relation
+ * - one → many (contact.company ↔ company.contacts)
+ * - many → many (contact.tags ↔ tag.contacts)
+ */
+declare function inferInverseCardinality(cardinality: "one" | "many"): "one" | "many";
+/**
+ * RichtextAttribute - Rich text content using semantic markdown
+ *
+ * Stores content as semantic markdown string (with directives like :::callout).
+ * Parsed at runtime to Tiptap JSON for editing.
+ * Use this for: Notes, articles, descriptions, long-form content.
+ *
+ * @example
+ * ```typescript
+ * richtext({ name: "content", label: "Content" }).required()
+ * ```
+ */
+interface RichtextAttribute extends BaseAttribute<string> {
+    type: "richtext";
+}
+type RichTextAttribute = RichtextAttribute;
+/**
+ * Return type for formula expressions
+ */
+type FormulaReturnType = ComputedReturnType;
+/**
+ * FormulaAttribute - Computed value based on other attributes
+ *
+ * Formulas are calculated at read-time and are always read-only.
+ * Users cannot directly edit formula values.
+ *
+ * @example Simple calculation
+ * ```typescript
+ * formula({ name: "total", label: "Total" })
+ *   .expression("price * quantity")
+ *   .returns("number")
+ *   .decimals(2)
+ * ```
+ *
+ * @example With functions
+ * ```typescript
+ * formula({ name: "fullName", label: "Full Name" })
+ *   .expression("CONCAT(firstName, ' ', lastName)")
+ *   .returns("text")
+ * ```
+ */
+interface FormulaAttribute extends Omit<BaseAttribute<never>, "defaultValue" | "required"> {
+    type: "formula";
+    /** Expression to evaluate (e.g., "price * quantity") */
+    expression: string;
+    /** Expected return type for formatting */
+    returnType: FormulaReturnType;
+    /** Decimal places for number results */
+    decimals?: number;
+    /** Source attribute for select-like computed options */
+    optionsSource?: ComputedOptionsSource;
+    /** Whether to allow relation references in the expression (e.g., "company.name") */
+    allowRelations?: boolean;
+    /** Formula is always not required (read-only) */
+    required: false;
+}
+/**
+ * Aggregation functions for rollup attributes
+ *
+ * Categories:
+ * - Numeric (sum, avg): Only for number and currency types
+ * - Date (earliest, latest): Only for date type
+ * - Count (count, countValues, countUniqueValues, countEmpty): Universal
+ * - Percent (percentEmpty, percentNotEmpty): Universal
+ * - Lookup (original): Returns all values as array, rendered as target type
+ */
+type RollupFunction = "sum" | "avg" | "earliest" | "latest" | "count" | "countValues" | "countUniqueValues" | "countEmpty" | "percentEmpty" | "percentNotEmpty" | "original";
+/**
+ * RollupAttribute - Aggregates values from related records
+ *
+ * Rollups are calculated and stored (denormalized) for performance.
+ * They are automatically recalculated when related records change.
+ * Users cannot directly edit rollup values.
+ *
+ * @example Sum of related amounts
+ * ```typescript
+ * rollup({ name: "totalOrders", label: "Total Orders" })
+ *   .from("orders")           // relation attribute name
+ *   .aggregate("amount")      // target attribute to sum
+ *   .using("sum")
+ *   .decimals(2)
+ * ```
+ *
+ * @example Count of related records
+ * ```typescript
+ * rollup({ name: "orderCount", label: "Number of Orders" })
+ *   .from("orders")
+ *   .using("count")
+ * ```
+ */
+interface RollupAttribute extends Omit<BaseAttribute<never>, "defaultValue" | "required"> {
+    type: "rollup";
+    /** Name of the relation attribute on this object */
+    relationAttribute: string;
+    /**
+     * Dot notation path for multi-level traversal (Phase 4+)
+     * @example "orders.items" - traverse through orders to items
+     */
+    relationPath?: string;
+    /** Attribute name on the target object to aggregate */
+    targetAttribute: string;
+    /** Aggregation function to apply */
+    function: RollupFunction;
+    /** Decimal places for numeric results */
+    decimals?: number;
+    /** Rollup is always not required (read-only) */
+    required: false;
+    /**
+     * Cached type of the target attribute for display purposes
+     * Used when function="original" to render values as the target type
+     */
+    targetAttributeType?: AttributeType;
+    /**
+     * Cached options from target attribute (for select/status/multiselect display)
+     * Required when function="original" and target is a select-like type
+     */
+    targetAttributeOptions?: Option[];
+    /** Source attribute for select-like computed options */
+    optionsSource?: ComputedOptionsSource;
+}
+/**
+ * DocumentAttribute - References structured documents.
+ *
+ * Unlike FileAttribute which stores raw file references, DocumentAttribute
+ * provides structured document handling with typed edge properties.
+ *
+ * Every document attribute is multi by construction — the underlying
+ * storage (documents + document_slots + files) supports 1 Doc → N slot
+ * files uniformly. Single-value file fields use `file()` instead.
+ *
+ * @example
+ * ```typescript
+ * document({ name: "contracts", label: "Contrats" })
+ *   .slots([{ name: "signed" }])
+ * ```
+ */
+interface DocumentAttribute extends BaseAttribute<string[]> {
+    type: "document";
+    /**
+     * Schema for typed properties on the record→document edge.
+     * Symmetric with `RelationAttribute.properties`; populated by `.qualifyWith(...)`.
+     * Stored on `record_reference_edges.properties`, not on the document itself.
+     */
+    properties?: PropertySchema;
+    /**
+     * File slots declared on this attribute. Builder injects
+     * [DEFAULT_DOCUMENT_SLOT] when omitted. Always non-empty in practice.
+     */
+    slots?: DocumentSlotConfig[];
+}
+type Attribute = TextAttribute | RichtextAttribute | NumberAttribute | CheckboxAttribute | DateAttribute | PhoneAttribute | CurrencyAttribute | StatusAttribute | LocationAttribute | SelectAttribute | MultiselectAttribute | FileAttribute | UserAttribute | RelationAttribute | FormulaAttribute | RollupAttribute | DocumentAttribute;
+/**
+ * Check if an attribute supports sorting based on its type.
+ */
+declare function isAttributeSortable(attr: {
+    type: AttributeType;
+}): boolean;
+
+export { DEFAULT_DOCUMENT_SLOT as $, type Attribute as A, type BilateralConfig as B, type CurrencyAttribute as C, type DateAttribute as D, type RelationTarget as E, type FileAttribute as F, type RollupFunction as G, type UserReferenceType as H, type MigrationDefinition as I, type AttributeGroup as J, type BaseAttribute as K, type LocationAttribute as L, type MultiRelationAttribute as M, type NumberAttribute as N, type ObjectDefinition as O, type PhoneAttribute as P, type BuiltInTransform as Q, type RelationAttribute as R, type SingleRelationAttribute as S, type TextAttribute as T, type UserAttribute as U, type ComputedAttributeState as V, type ComputedFieldKind as W, type ComputedStateStatus as X, type CreateDocument as Y, type CreateDocumentLink as Z, type CreateDocumentSlot as _, type RichtextAttribute as a, type DateFormat as a0, type DateValue as a1, type Document as a2, type DocumentKind as a3, type DocumentLayoutVariant as a4, type DocumentListOptions as a5, type DocumentSlot as a6, type DocumentWithSlots as a7, type DocumentWithSubCount as a8, type FolderPreset as a9, MAX_PRESET_DEPTH as aa, type NumberUnit as ab, type ObjectAttribute as ac, type ObjectRecord as ad, type OptionPropertyAttribute as ae, type PresetNode as af, type PropertyAttribute as ag, type PropertyType as ah, RELATION_TARGET_ANY as ai, RESERVED_ATTRIBUTE_NAMES as aj, type RecordDocuments as ak, type ReservedAttributeName as al, type RichTextAttribute as am, SYSTEM_FIELD_NAMES as an, type SlotStatus as ao, type StatusGroup as ap, type SystemFieldName as aq, type UpdateDocument as ar, type UpdateDocumentSlot as as, hasOptions as at, inferInverseCardinality as au, isAttributeSortable as av, isBilateralRelation as aw, isUniversalRelation as ax, type MultiselectAttribute as b, type SelectAttribute as c, type StatusAttribute as d, type FormulaAttribute as e, type RollupAttribute as f, type CheckboxAttribute as g, type CompletionStatus as h, type ComputedValueType as i, type ComputedReturnType as j, type AttributeType as k, type ComputedOptionsSource as l, type ComputedDependency as m, type ComputedPlan as n, type Timestamps as o, type DocumentLayout as p, type SchemaOperation as q, type LocationGranularity as r, type Location as s, type DocumentAttribute as t, type Phone as u, type Currency as v, type DocumentSlotConfig as w, type PropertySchema as x, type Option as y, type FormulaReturnType as z };