@stonecrop/stonecrop 0.10.15 → 0.11.0

package/dist/stonecrop.d.ts

@@ -2,12 +2,14 @@ import type { AnyStateNodeConfig } from 'xstate';
 import { Component } from 'vue';
 import { ComputedRef } from 'vue';
 import type { DataClient } from '@stonecrop/schema';
+import type { DoctypeMeta } from '@stonecrop/schema';
+import type { LinkDeclaration } from '@stonecrop/schema';
 import { List } from 'immutable';
 import { Map as Map_2 } from 'immutable';
 import { Plugin as Plugin_2 } from 'vue';
 import { Ref } from 'vue';
 import { Router } from 'vue-router';
-import { SchemaTypes } from '@stonecrop/aform';
+import type { SchemaTypes } from '@stonecrop/aform';
 import { Store } from 'pinia';
 import { StoreDefinition } from 'pinia';
 import type { UnknownMachineConfig } from 'xstate';
@@ -80,28 +82,17 @@ export declare interface BatchOperation {
     reversible: boolean;
 }
 
-/**
- * Recursively collect nested data from HST using pre-resolved schemas
- * @param resolvedSchema - The already-resolved schema (with nested schemas embedded)
- * @param basePath - The base path in HST (e.g., "customer.123.address")
- * @param hstStore - The HST store instance
- * @returns The collected data object
- * @public
- */
-export declare function collectNestedData(resolvedSchema: SchemaTypes[], basePath: string, hstStore: HSTNode): Record<string, any>;
-
 /**
  * Factory function for HST creation
  * Creates a new HSTNode proxy for hierarchical state tree navigation.
  *
  * @param target - The target object to wrap with HST functionality
  * @param doctype - The document type identifier
- * @param parentDoctype - Optional parent document type identifier
  * @returns A new HSTNode proxy instance
  *
  * @public
  */
-export declare function createHST(target: any, doctype: string, parentDoctype?: string): HSTNode;
+export declare function createHST(target: any, doctype: string): HSTNode;
 
 /**
  * Creates a validator with the given registry
@@ -176,6 +167,12 @@ export declare class Doctype {
      * @readonly
      */
     readonly component?: Component;
+    /**
+     * Relationship links to other doctypes
+     * @public
+     * @readonly
+     */
+    readonly links?: Record<string, LinkDeclaration>;
     /**
      * Creates a new Doctype instance
      * @param doctype - The doctype name
@@ -183,8 +180,9 @@ export declare class Doctype {
      * @param workflow - The doctype workflow configuration (XState machine)
      * @param actions - The doctype actions and field triggers
      * @param component - Optional Vue component for rendering the doctype
+     * @param links - Optional relationship links to other doctypes
      */
-    constructor(doctype: string, schema: ImmutableDoctype['schema'], workflow: ImmutableDoctype['workflow'], actions: ImmutableDoctype['actions'], component?: Component);
+    constructor(doctype: string, schema: ImmutableDoctype['schema'], workflow: ImmutableDoctype['workflow'], actions: ImmutableDoctype['actions'], component?: Component, links?: Record<string, LinkDeclaration>);
     /**
      * Creates a Doctype instance from a plain configuration object.
      * Handles conversion of arrays to Immutable.js collections internally.
@@ -322,18 +320,16 @@ export declare type DoctypeConfig = {
     slug?: string;
     /** Database table name */
     tableName?: string;
-    /** Field definitions */
+    /** Field definitions (including link fields with fieldtype: 'Link') */
     fields?: SchemaTypes[];
+    /** Relationship links to other doctypes */
+    links?: Record<string, LinkDeclaration>;
     /** Workflow configuration (XState format or simple WorkflowMeta) */
     workflow?: UnknownMachineConfig | WorkflowMeta;
     /** Actions and their field triggers */
     actions?: Record<string, string[]>;
-    /** Parent doctype for inheritance */
+    /** Ancestor doctype for inheritance */
     inherits?: string;
-    /** Doctype to use for list views */
-    listDoctype?: string;
-    /** Parent doctype for child tables */
-    parentDoctype?: string;
 };
 
 /**
@@ -425,6 +421,12 @@ export declare class FieldTriggerEngine {
      * @param fn - The action function
      */
     registerAction(name: string, fn: FieldActionFunction): void;
+    /**
+     * Look up a registered action function by name.
+     * Returns `undefined` if the action has not been registered.
+     * @param name - The action name
+     */
+    getAction(name: string): FieldActionFunction | undefined;
     /**
      * Register a global XState transition action function
      * @param name - The name of the transition action
@@ -573,6 +575,18 @@ export declare interface FieldTriggerOptions {
  */
 export declare function getGlobalTriggerEngine(options?: FieldTriggerOptions): FieldTriggerEngine;
 
+/**
+ * Returns the global Stonecrop singleton instance, or `undefined` if no
+ * instance has been created yet.
+ *
+ * Use this when you need the Stonecrop instance outside a Vue component
+ * context (e.g., in workflow action handlers, plugin setup code, or
+ * non-component utilities). Inside a component, prefer `useStonecrop()`.
+ *
+ * @public
+ */
+export declare function getStonecrop(): Stonecrop | undefined;
+
 /**
  * Global HST Manager (Singleton)
  * Manages hierarchical state trees and provides access to the global registry.
@@ -641,10 +655,10 @@ export declare interface HSTNode {
      */
     has(path: string): boolean;
     /**
-     * Gets the parent node in the tree hierarchy
-     * @returns The parent HSTNode or null if this is the root
+     * Gets the ancestor node in the tree hierarchy (immediate predecessor)
+     * @returns The ancestor HSTNode or null if this is the root
      */
-    getParent(): HSTNode | null;
+    getAncestor(): HSTNode | null;
     /**
      * Gets the root node of the tree
      * @returns The root HSTNode
@@ -732,10 +746,10 @@ export declare interface HSTOperation {
     userId?: string;
     /** Additional metadata for custom use cases */
     metadata?: Record<string, any>;
-    /** Parent operation ID for batch operations */
-    parentOperationId?: string;
-    /** Child operation IDs for batch operations */
-    childOperationIds?: string[];
+    /** Ancestor operation ID for batch operations */
+    ancestorOperationId?: string;
+    /** Descendant operation IDs for batch operations */
+    descendantOperationIds?: string[];
 }
 
 /**
@@ -788,14 +802,24 @@ export declare type HSTStonecropReturn = BaseStonecropReturn & {
      */
     resolvedSchema: Ref<SchemaTypes[]>;
     /**
-     * Loads or initializes nested doctype data.
-     * Use this when rendering a nested form component. Checks HST first, then initializes defaults.
-     * @param parentPath - The HST path to check for existing data
-     * @param childDoctype - The nested doctype metadata
-     * @param recordId - Optional record ID (reserved for future API fetch)
-     * @returns The loaded or initialized data object
+     * Scaffold empty descendant records from defaults for all descendant links.
+     * @param path - The HST path where initialized data should be stored
+     * @param doctype - The doctype to initialize
+     */
+    initializeNestedData: (path: string, doctype: Doctype) => void;
+    /**
+     * Fetch a record and its nested data from the server.
+     * Stores each field at its own HST path per the field-level convention.
+     * @param path - The HST path (e.g., "recipe.r1")
+     * @param doctype - The doctype to fetch
+     * @param recordId - Record ID to fetch
+     * @param options - Query options (includeNested to control which links are fetched)
+     * @throws Error with code "CLIENT_REQUIRED" if no data client is configured
+     * @throws Error with code "RECORD_NOT_FOUND" if the server returns null
      */
-    loadNestedData: (parentPath: string, childDoctype: Doctype, recordId?: string) => Record<string, any>;
+    fetchNestedData: (path: string, doctype: Doctype, recordId: string, options?: {
+        includeNested?: boolean | string[];
+    }) => Promise<void>;
     /**
      * Collects a complete record payload with all nested data from HST.
      * Use this before submitting to an API. Recursively includes 1:1 and 1:many nested records.
@@ -805,13 +829,13 @@ export declare type HSTStonecropReturn = BaseStonecropReturn & {
      */
     collectRecordPayload: (doctype: Doctype, recordId: string) => Record<string, any>;
     /**
-     * Creates a nested context for a child doctype component.
+     * Creates a nested context for a descendant doctype component.
      * Use this in parent components to pass scoped handlers to child components.
      * @param basePath - The parent HST path prefix
-     * @param childDoctype - The child doctype metadata
+     * @param descendantDoctype - The descendant doctype metadata
      * @returns Scoped provideHSTPath and handleHSTChange functions
      */
-    createNestedContext: (basePath: string, childDoctype: Doctype) => {
+    createNestedContext: (basePath: string, descendantDoctype: Doctype) => {
         provideHSTPath: (fieldname: string) => string;
         handleHSTChange: (changeData: HSTChangeData) => void;
     };
@@ -830,6 +854,17 @@ export declare type HSTStonecropReturn = BaseStonecropReturn & {
      * Available immediately if Doctype instance passed, after async resolution if slug string passed.
      */
     resolvedDoctype: Ref<Doctype | undefined>;
+    /**
+     * Computed ref indicating whether workflow actions are ready to run.
+     * True when all links with blockWorkflows are loaded in HST.
+     * Use with v-bind:disabled="!isWorkflowReady" on action buttons.
+     */
+    isWorkflowReady: ComputedRef<boolean>;
+    /**
+     * List of link fieldnames that are blocking workflow execution.
+     * Empty array when isWorkflowReady is true.
+     */
+    blockedLinks: ComputedRef<string[]>;
 };
 
 /**
@@ -840,6 +875,7 @@ export declare type ImmutableDoctype = {
     readonly schema?: List<SchemaTypes>;
     readonly workflow?: UnknownMachineConfig | AnyStateNodeConfig | WorkflowMeta;
     readonly actions?: Map_2<string, string[]>;
+    readonly links?: Record<string, LinkDeclaration>;
 };
 
 /**
@@ -872,6 +908,24 @@ export declare type InstallOptions = {
     onRouterInitialized?: (registry: Registry, stonecrop: Stonecrop) => void | Promise<void>;
 };
 
+/**
+ * Lazy link state for a single link field.
+ * Provides reactive state and reload capability for lazy-loaded links.
+ * @public
+ */
+export declare type LazyLink = {
+    /** True while fetching data */
+    loading: Ref<boolean>;
+    /** True after successful fetch (permanent until reload) */
+    loaded: Ref<boolean>;
+    /** Error state, if any */
+    error: Ref<Error | null>;
+    /** Explicitly trigger a fetch for this link */
+    reload: () => Promise<void>;
+    /** The loaded data from HST, or undefined if not loaded */
+    data: ComputedRef<any>;
+};
+
 /**
  * Mark a specific operation as irreversible.
  * Used to prevent undo of critical operations like publishing or deletion.
@@ -1133,9 +1187,27 @@ export declare class Registry {
     readonly name: string;
     /**
      * The registry property contains a collection of doctypes
+     *
+     * @defaultValue `{}`
      * @see {@link Doctype}
      */
     readonly registry: Record<string, Doctype>;
+    /**
+     * Reverse index: backlink fieldname → list of \{ doctype slug, link fieldname \}.
+     * Multiple doctypes can declare a link with the same backlink name, so each key
+     * maps to an array. Built at schema load time for O(1) ancestor lookups.
+     *
+     * @defaultValue `new Map()`
+     * @internal
+     */
+    private _ancestorIndex;
+    /**
+     * Whether the ancestor index needs rebuilding
+     *
+     * @defaultValue `true`
+     * @internal
+     */
+    private _ancestorIndexDirty;
     /**
      * The Vue router instance
      * @see {@link https://router.vuejs.org/}
@@ -1162,35 +1234,32 @@ export declare class Registry {
     /**
      * Resolve nested Doctype fields in a schema by embedding child schemas inline.
      *
-     * @remarks
-     * Walks the schema array and for each field with `fieldtype: 'Doctype'` and a string
-     * `options` value, looks up the referenced doctype in the registry and:
+     * Accepts a Doctype and extracts `fields` and `links` internally.
+     * Fields array contains both scalar fields and link fields (with fieldtype: 'Link').
+     * Render order is determined by the order of fields in the fields array.
      *
-     * - If `cardinality: 'many'`: auto-derives `columns` from the child doctype's schema,
-     *   sets `component: 'ATable'`, `config: { view: 'list' }`, and initializes `rows: []`.
-     * - Otherwise (default/`cardinality: 'one'`): embeds the child schema as the field's
-     *   `schema` property for 1:1 nested forms.
+     * For each link field:
+     * - Looks up the corresponding link declaration in `links` by fieldname
+     * - `cardinality: 'noneOrMany'` or `'atLeastOne'`: auto-derives `columns` from the target's schema,
+     *   sets `component` to `link.component ?? 'ATable'`, `config: { view: 'list' }`, `rows: []`.
+     * - `cardinality: 'one'` or `'atMostOne'`: embeds the target schema as the entry's
+     *   `schema` property, sets `component` to `link.component ?? 'AForm'`.
      *
      * Recurses for deeply nested doctypes. Circular references are protected against.
+     * Returns a new array — does not mutate the original.
      *
-     * Returns a new array — does not mutate the original schema.
-     *
-     * @param schema - The schema array to resolve
-     * @returns A new schema array with nested Doctype fields resolved
-     *
-     * @example
-     * ```ts
-     * registry.addDoctype(addressDoctype)
-     * registry.addDoctype(customerDoctype)
-     *
-     * // Before: customer schema has { fieldname: 'address', fieldtype: 'Doctype', options: 'address' }
-     * const resolved = registry.resolveSchema(customerSchema)
-     * // After: address field now has schema: [...address fields...]
-     * ```
+     * @param doctype - The doctype to resolve
+     * @param visited - Internal — set of already-visited doctype slugs for cycle detection
+     * @returns A new schema array with nested links resolved
      *
      * @public
      */
-    resolveSchema(schema: SchemaTypes[], visited?: Set<string>): SchemaTypes[];
+    resolveSchema(doctype: Doctype, visited?: Set<string>): SchemaTypes[];
+    /**
+     * Build an ATable configuration from a field and child schema
+     * @internal
+     */
+    private buildTableConfig;
     /**
      * Initialize a new record with default values based on a schema.
      *
@@ -1201,7 +1270,7 @@ export declare class Registry {
      * - Check → `false`
      * - Int, Float, Decimal, Currency, Quantity → `0`
      * - JSON → `{}`
-     * - Doctype with `cardinality: 'many'` → `[]`
+     * - Doctype with `cardinality: 'noneOrMany'` or `'atLeastOne'` → `[]`
      * - Doctype without `cardinality` or `cardinality: 'one'` → recursively initializes nested record
      * - All others → `null`
      *
@@ -1227,6 +1296,69 @@ export declare class Registry {
      * @public
      */
     getDoctype(slug: string): Doctype | undefined;
+    /**
+     * Get all links declared on a doctype.
+     *
+     * @param doctypeSlug - The doctype slug to get links for
+     * @returns Array of link declarations with fieldname, or empty array if none
+     *
+     * @example
+     * ```ts
+     * const links = registry.getDescendantLinks('recipe')
+     * // [{ fieldname: 'tasks', target: 'recipe-task', cardinality: 'noneOrMany', backlink: 'recipe' }]
+     * ```
+     *
+     * @public
+     */
+    getDescendantLinks(doctypeSlug: string): Array<LinkDeclaration & {
+        fieldname: string;
+    }>;
+    /**
+     * Get links on other doctypes that target the given doctype.
+     *
+     * @param doctypeSlug - The doctype slug to find ancestor links for
+     * @returns Array of link declarations with fieldname and declaring doctype slug, or empty array
+     *
+     * @example
+     * ```ts
+     * const ancestors = registry.getAncestorLinks('recipe-task')
+     * // [{ fieldname: 'tasks', target: 'recipe-task', cardinality: 'noneOrMany', backlink: 'recipe', doctype: 'recipe' }]
+     * ```
+     *
+     * @public
+     */
+    getAncestorLinks(doctypeSlug: string): Array<LinkDeclaration & {
+        fieldname: string;
+        doctype: string;
+    }>;
+    /**
+     * Ensure the ancestor index is up to date
+     * @internal
+     */
+    private _ensureAncestorIndex;
+    /**
+     * Convert the registry to a Map of DoctypeMeta objects for use with StonecropClient.
+     *
+     * This allows passing a Registry instance to StonecropClient by deriving the
+     * Map\<string, DoctypeMeta\> that StonecropClient needs for building nested GraphQL queries.
+     *
+     * @returns Map of doctype metadata keyed by doctype name
+     *
+     * @example
+     * ```typescript
+     * const registry = new Registry()
+     * registry.addDoctype(Doctype.fromObject(customerSchema))
+     * registry.addDoctype(Doctype.fromObject(orderSchema))
+     *
+     * const client = new StonecropClient({
+     *   endpoint: '/graphql',
+     *   registry: registry.toMetaMap(),  // Convert once, use with client
+     * })
+     * ```
+     *
+     * @public
+     */
+    toMetaMap(): Map<string, DoctypeMeta>;
 }
 
 /**
@@ -1266,9 +1398,10 @@ export declare class SchemaValidator {
      * @param schema - Schema fields (List or Array)
      * @param workflow - Optional workflow configuration
      * @param actions - Optional actions map
+     * @param links - Optional links object
      * @returns Validation result
      */
-    validate(doctype: string, schema: List<SchemaTypes> | SchemaTypes[] | undefined, workflow?: AnyStateNodeConfig, actions?: Map_2<string, string[]> | Map<string, string[]>): ValidationResult;
+    validate(doctype: string, schema: List<SchemaTypes> | SchemaTypes[] | undefined, workflow?: AnyStateNodeConfig, actions?: Map_2<string, string[]> | Map<string, string[]>, links?: Record<string, LinkDeclaration>): ValidationResult;
     /**
      * Validates that required schema properties are present
      * @internal
@@ -1279,6 +1412,11 @@ export declare class SchemaValidator {
      * @internal
      */
     private validateLinkFields;
+    /**
+     * Validates link declarations: target resolution, backlink consistency, Link field correspondence
+     * @internal
+     */
+    private validateLinkDeclarations;
     /**
      * Validates workflow state machine configuration
      * @internal
@@ -1312,6 +1450,7 @@ export declare class Stonecrop {
      * @internal
      */
     static _root: Stonecrop;
+    /** The HST store instance for reactive state management */
     private hstStore;
     private _operationLogStore?;
     private _operationLogConfig?;
@@ -1371,8 +1510,8 @@ export declare class Stonecrop {
     actionError?: string | undefined;
     userId?: string | undefined;
     metadata?: Record<string, any> | undefined;
-    parentOperationId?: string | undefined;
-    childOperationIds?: string[] | undefined;
+    ancestorOperationId?: string | undefined;
+    descendantOperationIds?: string[] | undefined;
     }[], HSTOperation[] | {
     id: string;
     type: HSTOperationType;
@@ -1395,8 +1534,8 @@ export declare class Stonecrop {
     actionError?: string | undefined;
     userId?: string | undefined;
     metadata?: Record<string, any> | undefined;
-    parentOperationId?: string | undefined;
-    childOperationIds?: string[] | undefined;
+    ancestorOperationId?: string | undefined;
+    descendantOperationIds?: string[] | undefined;
     }[]>;
     currentIndex: Ref<number, number>;
     config: Ref<    {
@@ -1434,7 +1573,7 @@ export declare class Stonecrop {
     getSnapshot: () => OperationLogSnapshot;
     markIrreversible: (operationId: string, reason: string) => void;
     logAction: (doctype: string, actionName: string, recordIds?: string[], result?: "success" | "failure" | "pending", error?: string) => string;
-    }, "operations" | "clientId" | "currentIndex" | "config">, Pick<{
+    }, "operations" | "currentIndex" | "config" | "clientId">, Pick<{
     operations: Ref<    {
     id: string;
     type: HSTOperationType;
@@ -1457,8 +1596,8 @@ export declare class Stonecrop {
     actionError?: string | undefined;
     userId?: string | undefined;
     metadata?: Record<string, any> | undefined;
-    parentOperationId?: string | undefined;
-    childOperationIds?: string[] | undefined;
+    ancestorOperationId?: string | undefined;
+    descendantOperationIds?: string[] | undefined;
     }[], HSTOperation[] | {
     id: string;
     type: HSTOperationType;
@@ -1481,8 +1620,8 @@ export declare class Stonecrop {
     actionError?: string | undefined;
     userId?: string | undefined;
     metadata?: Record<string, any> | undefined;
-    parentOperationId?: string | undefined;
-    childOperationIds?: string[] | undefined;
+    ancestorOperationId?: string | undefined;
+    descendantOperationIds?: string[] | undefined;
     }[]>;
     currentIndex: Ref<number, number>;
     config: Ref<    {
@@ -1543,8 +1682,8 @@ export declare class Stonecrop {
     actionError?: string | undefined;
     userId?: string | undefined;
     metadata?: Record<string, any> | undefined;
-    parentOperationId?: string | undefined;
-    childOperationIds?: string[] | undefined;
+    ancestorOperationId?: string | undefined;
+    descendantOperationIds?: string[] | undefined;
     }[], HSTOperation[] | {
     id: string;
     type: HSTOperationType;
@@ -1567,8 +1706,8 @@ export declare class Stonecrop {
     actionError?: string | undefined;
     userId?: string | undefined;
     metadata?: Record<string, any> | undefined;
-    parentOperationId?: string | undefined;
-    childOperationIds?: string[] | undefined;
+    ancestorOperationId?: string | undefined;
+    descendantOperationIds?: string[] | undefined;
     }[]>;
     currentIndex: Ref<number, number>;
     config: Ref<    {
@@ -1664,7 +1803,25 @@ export declare class Stonecrop {
      * @param action - The action to run
      * @param args - Action arguments (typically record IDs)
      */
-    runAction(doctype: Doctype, action: string, args?: any[]): void;
+    runAction(doctype: Doctype, action: string, args?: string[]): void;
+    /**
+     * Get the effective blockWorkflows value for a link.
+     * Returns true if blockWorkflows is explicitly true, or if it's absent and fetch method is 'sync'.
+     * @param link - The link declaration
+     * @returns Whether workflows should be blocked until this link is loaded
+     */
+    private getEffectiveBlockWorkflows;
+    /**
+     * Check if workflow actions are ready to run (all required link data is loaded).
+     * A link's data is considered loaded if it exists in HST at `slug.recordId.linkname`.
+     * @param doctype - The doctype to check
+     * @param recordId - The record ID
+     * @returns Object with `ready: true` if all blocked links are loaded, or `ready: false` with `blockedLinks` array
+     */
+    isWorkflowReady(doctype: Doctype, recordId: string): {
+        ready: boolean;
+        blockedLinks?: string[];
+    };
     /**
      * Get records from server using the configured data client.
      * @param doctype - The doctype
@@ -1732,14 +1889,40 @@ export declare class Stonecrop {
      */
     collectRecordPayload(doctype: Doctype, recordId: string): Record<string, any>;
     /**
-     * Load nested data from HST or initialize with defaults
-     * @param parentPath - The HST path to check for existing data
-     * @param childDoctype - The child doctype metadata
-     * @param _recordId - Optional record ID to load
-     * @returns The loaded or initialized data
+     * Scaffold empty descendant records from defaults for all descendant links.
+     *
+     * Initializes all scalar and link fields at their HST paths with default values.
+     * For new records, call this after setting up the doctype to ensure all paths exist.
+     *
+     * @param path - HST path (e.g., "customer.new")
+     * @param doctype - The doctype to initialize
      * @public
      */
-    loadNestedData(parentPath: string, childDoctype: Doctype, _recordId?: string): Record<string, any>;
+    initializeNestedData(path: string, doctype: Doctype): void;
+    /**
+     * Fetch a record and its nested data from the server.
+     *
+     * Calls `_client.getRecord()` with nested sub-selections and stores each scalar field at its own HST path
+     * (`slug.recordId.fieldname`), descendants at the link-level path (`slug.recordId.linkname`).
+     *
+     * @param path - HST path (e.g., "recipe.r1")
+     * @param doctype - The doctype to fetch
+     * @param recordId - Record ID to fetch
+     * @param options - Query options (includeNested to control which links are fetched)
+     * @throws Error with code `"CLIENT_REQUIRED"` if no data client is configured
+     * @throws Error with code `"RECORD_NOT_FOUND"` if the server returns null
+     * @public
+     */
+    fetchNestedData(path: string, doctype: Doctype, recordId: string, options?: {
+        includeNested?: boolean | string[];
+    }): Promise<void>;
+    /**
+     * Recursively collect nested data from HST
+     * @param basePath - The base path in HST (e.g., "customer.123.address")
+     * @param doctype - The doctype whose links drive the recursive traversal
+     * @returns The collected data object
+     */
+    private collectNestedData;
 }
 
 /**
@@ -1838,6 +2021,29 @@ export declare interface UndoRedoState {
     currentIndex: number;
 }
 
+/**
+ * Get the lazy link state for a specific link field on a doctype record.
+ *
+ * This composable provides reactive state for lazy-loaded links:
+ * - `loading`: true while fetching
+ * - `loaded`: true after successful fetch (permanent until reload)
+ * - `error`: error state if any
+ * - `reload()`: explicitly trigger a fetch
+ * - `data`: computed from HST, or undefined if not loaded
+ *
+ * The reload() function respects the link's fetch strategy:
+ * - `sync`: fetches via GraphQL query through fetchNestedData
+ * - `lazy`: fetches via GraphQL query through fetchNestedData
+ * - `custom`: invokes the serialized handler function directly
+ *
+ * @param doctype - The doctype instance
+ * @param recordId - The record ID
+ * @param linkFieldname - The link fieldname to load
+ * @returns LazyLink with loading, loaded, error, reload, and data
+ * @public
+ */
+export declare function useLazyLink(doctype: Doctype, recordId: string, linkFieldname: string): LazyLink;
+
 /**
  * Composable for operation log management
  * Provides easy access to undo/redo functionality and operation history
@@ -1886,8 +2092,8 @@ export declare function useOperationLog(config?: Partial<OperationLogConfig>): {
     actionError?: string | undefined;
     userId?: string | undefined;
     metadata?: Record<string, any> | undefined;
-    parentOperationId?: string | undefined;
-    childOperationIds?: string[] | undefined;
+    ancestorOperationId?: string | undefined;
+    descendantOperationIds?: string[] | undefined;
     }[], HSTOperation[] | {
     id: string;
     type: HSTOperationType;
@@ -1910,8 +2116,8 @@ export declare function useOperationLog(config?: Partial<OperationLogConfig>): {
     actionError?: string | undefined;
     userId?: string | undefined;
     metadata?: Record<string, any> | undefined;
-    parentOperationId?: string | undefined;
-    childOperationIds?: string[] | undefined;
+    ancestorOperationId?: string | undefined;
+    descendantOperationIds?: string[] | undefined;
     }[]>;
     currentIndex: Ref<number, number>;
     undoRedoState: ComputedRef<UndoRedoState>;
@@ -1961,8 +2167,8 @@ actionResult?: "success" | "failure" | "pending" | undefined;
 actionError?: string | undefined;
 userId?: string | undefined;
 metadata?: Record<string, any> | undefined;
-parentOperationId?: string | undefined;
-childOperationIds?: string[] | undefined;
+ancestorOperationId?: string | undefined;
+descendantOperationIds?: string[] | undefined;
 }[], HSTOperation[] | {
 id: string;
 type: HSTOperationType;
@@ -1985,8 +2191,8 @@ actionResult?: "success" | "failure" | "pending" | undefined;
 actionError?: string | undefined;
 userId?: string | undefined;
 metadata?: Record<string, any> | undefined;
-parentOperationId?: string | undefined;
-childOperationIds?: string[] | undefined;
+ancestorOperationId?: string | undefined;
+descendantOperationIds?: string[] | undefined;
 }[]>;
 currentIndex: Ref<number, number>;
 config: Ref<    {
@@ -2024,7 +2230,7 @@ getOperationsFor: (doctype: string, recordId?: string) => HSTOperation[];
 getSnapshot: () => OperationLogSnapshot;
 markIrreversible: (operationId: string, reason: string) => void;
 logAction: (doctype: string, actionName: string, recordIds?: string[], result?: "success" | "failure" | "pending", error?: string) => string;
-}, "operations" | "clientId" | "currentIndex" | "config">, Pick<{
+}, "operations" | "currentIndex" | "config" | "clientId">, Pick<{
 operations: Ref<    {
 id: string;
 type: HSTOperationType;
@@ -2047,8 +2253,8 @@ actionResult?: "success" | "failure" | "pending" | undefined;
 actionError?: string | undefined;
 userId?: string | undefined;
 metadata?: Record<string, any> | undefined;
-parentOperationId?: string | undefined;
-childOperationIds?: string[] | undefined;
+ancestorOperationId?: string | undefined;
+descendantOperationIds?: string[] | undefined;
 }[], HSTOperation[] | {
 id: string;
 type: HSTOperationType;
@@ -2071,8 +2277,8 @@ actionResult?: "success" | "failure" | "pending" | undefined;
 actionError?: string | undefined;
 userId?: string | undefined;
 metadata?: Record<string, any> | undefined;
-parentOperationId?: string | undefined;
-childOperationIds?: string[] | undefined;
+ancestorOperationId?: string | undefined;
+descendantOperationIds?: string[] | undefined;
 }[]>;
 currentIndex: Ref<number, number>;
 config: Ref<    {
@@ -2133,8 +2339,8 @@ actionResult?: "success" | "failure" | "pending" | undefined;
 actionError?: string | undefined;
 userId?: string | undefined;
 metadata?: Record<string, any> | undefined;
-parentOperationId?: string | undefined;
-childOperationIds?: string[] | undefined;
+ancestorOperationId?: string | undefined;
+descendantOperationIds?: string[] | undefined;
 }[], HSTOperation[] | {
 id: string;
 type: HSTOperationType;
@@ -2157,8 +2363,8 @@ actionResult?: "success" | "failure" | "pending" | undefined;
 actionError?: string | undefined;
 userId?: string | undefined;
 metadata?: Record<string, any> | undefined;
-parentOperationId?: string | undefined;
-childOperationIds?: string[] | undefined;
+ancestorOperationId?: string | undefined;
+descendantOperationIds?: string[] | undefined;
 }[]>;
 currentIndex: Ref<number, number>;
 config: Ref<    {
@@ -2208,7 +2414,17 @@ logAction: (doctype: string, actionName: string, recordIds?: string[], result?:
 export declare function useStonecrop(): BaseStonecropReturn | HSTStonecropReturn;
 
 /**
- * Unified Stonecrop composable with HST integration for a specific doctype and record
+ * Unified Stonecrop composable with HST integration for a specific doctype and record.
+ *
+ * When a `Doctype` instance is passed, all synchronous initialisation (`hstStore`,
+ * `resolvedSchema`, `formData`, `handleHSTChange`, operation-log wiring) is performed
+ * during `setup()` — before the first render and without awaiting any lifecycle hook.
+ * Callers can read `hstStore.value`, `resolvedSchema.value`, and `formData.value`
+ * immediately after calling this composable; no `nextTick`, `flushPromises`, or
+ * `setTimeout` is required.
+ *
+ * The only remaining async work in `onMounted` is fetching an existing record from the
+ * server when `recordId` is not `'new'`, and lazy-loading a doctype by slug string.
  *
  * @param options - Configuration with doctype (string slug or Doctype instance) and optional recordId
  * @returns Stonecrop instance with full HST integration utilities
@@ -2309,6 +2525,8 @@ export declare interface ValidatorOptions {
     registry?: Registry;
     /** Whether to validate Link field targets */
     validateLinkTargets?: boolean;
+    /** Whether to validate links object (target resolution, backlink consistency, Link field correspondence) */
+    validateLinks?: boolean;
     /** Whether to validate workflow reachability */
     validateWorkflows?: boolean;
     /** Whether to validate action registration */