/**
 * Copyright (c) 2025 Elara AI Pty Ltd
 * Licensed under BSL 1.1. See LICENSE for details.
 */
/**
 * Low-level tree and dataset operations for e3 repositories.
 *
 * Trees are persistent data structures with structural sharing (like git trees).
 * Each tree node contains DataRefs pointing to either other trees or dataset values.
 *
 * Tree operations require a Structure parameter which describes the shape of the
 * tree node. This enables proper encoding/decoding with the correct StructType
 * and supports future tree types (array, variant, etc.).
 *
 * Workspace operations use per-dataset ref files (DatasetRef) instead of tree
 * traversal. This enables concurrent writes without serialization.
 *
 * Low-level tree read/write operations remain for computing root hashes and
 * for package operations.
 */
import { type EastType, type EastTypeValue } from '@elaraai/east';
import { type DataRef, type Structure, type TreePath, type VersionVector } from '@elaraai/e3-types';
import type { StorageBackend, LockHandle } from './storage/interfaces.js';
/**
 * A tree object: mapping of field names to data references.
 *
 * This is a plain object (not a Map) because tree objects are encoded as
 * StructTypes with known field names derived from the Structure.
 */
export type TreeObject = Record<string, DataRef>;
/**
 * Read and decode a tree object from the object store.
 *
 * @param storage - Storage backend
 * @param repo - Repository identifier
 * @param hash - Hash of the tree object
 * @param structure - The structure describing this tree node's shape
 * @returns The decoded tree object (field name -> DataRef)
 * @throws If object not found, structure is not a tree, or decoding fails
 */
export declare function treeRead(storage: StorageBackend, repo: string, hash: string, structure: Structure): Promise<TreeObject>;
/**
 * Encode and write a tree object to the object store.
 *
 * @param storage - Storage backend
 * @param repo - Repository identifier
 * @param fields - Object mapping field names to DataRefs
 * @param structure - The structure describing this tree node's shape
 * @returns Hash of the written tree object
 * @throws If structure is not a tree or encoding fails
 */
export declare function treeWrite(storage: StorageBackend, repo: string, fields: TreeObject, structure: Structure): Promise<string>;
/**
 * Read and decode a dataset value from the object store.
 *
 * The .beast2 format includes type information in the header, so values
 * can be decoded without knowing the schema in advance.
 *
 * @param storage - Storage backend
 * @param repo - Repository identifier
 * @param hash - Hash of the dataset value
 * @returns The decoded value and its type
 * @throws If object not found or not a valid beast2 object
 */
export declare function datasetRead(storage: StorageBackend, repo: string, hash: string): Promise<{
    type: EastType;
    value: unknown;
}>;
/**
 * Encode and write a dataset value to the object store.
 *
 * @param storage - Storage backend
 * @param repo - Repository identifier
 * @param value - The value to encode
 * @param type - The East type for encoding (EastType or EastTypeValue)
 * @returns Hash of the written dataset value
 */
export declare function datasetWrite(storage: StorageBackend, repo: string, value: unknown, type: EastType | EastTypeValue): Promise<string>;
/**
 * Options for setting a workspace dataset.
 */
export interface WorkspaceSetDatasetOptions {
    /**
     * External workspace lock to use. If provided, the caller is responsible
     * for releasing the lock after the operation. If not provided, workspaceSetDataset
     * will acquire and release a lock internally.
     */
    lock?: LockHandle;
}
/**
 * Update a dataset at a path within a workspace.
 *
 * Writes the value to the object store and updates the per-dataset ref file.
 * Uses shared structure lock to allow concurrent writes.
 *
 * @param storage - Storage backend
 * @param repo - Repository identifier
 * @param ws - Workspace name
 * @param treePath - Path to the dataset
 * @param value - The new value to write
 * @param type - The East type for encoding the value (EastType or EastTypeValue)
 * @param options - Optional settings including external lock
 * @throws {WorkspaceLockError} If workspace is locked by another process
 * @throws If workspace not deployed, path invalid, or path points to a tree
 */
export declare function workspaceSetDataset(storage: StorageBackend, repo: string, ws: string, treePath: TreePath, value: unknown, type: EastType | EastTypeValue, options?: WorkspaceSetDatasetOptions): Promise<void>;
/**
 * List field names at a tree path within a workspace's data tree.
 *
 * Uses the structure to determine available fields (no tree traversal needed).
 *
 * @param storage - Storage backend
 * @param repo - Repository identifier
 * @param ws - Workspace name
 * @param treePath - Path to the tree node
 * @returns Array of field names at the path
 * @throws If workspace not deployed, path invalid, or path points to a dataset
 */
export declare function workspaceListTree(storage: StorageBackend, repo: string, ws: string, treePath: TreePath): Promise<string[]>;
/**
 * Read and decode a dataset value at a path within a workspace's data tree.
 *
 * Reads the per-dataset ref file to get the value hash, then decodes the value.
 *
 * @param storage - Storage backend
 * @param repo - Repository identifier
 * @param ws - Workspace name
 * @param treePath - Path to the dataset
 * @returns The decoded dataset value
 * @throws If workspace not deployed, path invalid, or path points to a tree
 */
export declare function workspaceGetDataset(storage: StorageBackend, repo: string, ws: string, treePath: TreePath): Promise<unknown>;
/**
 * Get the hash of a dataset at a path within a workspace's data tree.
 *
 * Reads the per-dataset ref file directly. No tree traversal needed.
 *
 * @param storage - Storage backend
 * @param repo - Repository identifier
 * @param ws - Workspace name
 * @param treePath - Path to the dataset
 * @returns Object with ref type and hash (null for unassigned/null refs)
 * @throws If workspace not deployed, path invalid, or path points to a tree
 */
export declare function workspaceGetDatasetHash(storage: StorageBackend, repo: string, ws: string, treePath: TreePath): Promise<{
    refType: DataRef['type'];
    hash: string | null;
}>;
/**
 * Set a dataset at a path within a workspace using a pre-computed hash.
 *
 * Writes a DatasetRef file directly. No tree path-copy needed.
 *
 * IMPORTANT: This function does NOT acquire a workspace lock. The caller must
 * hold a lock on the workspace before calling this function. This
 * is typically used by dataflowExecute which holds the lock for the entire
 * execution.
 *
 * @param storage - Storage backend
 * @param repo - Repository identifier
 * @param ws - Workspace name
 * @param treePath - Path to the dataset
 * @param valueHash - Hash of the dataset value already in the object store
 * @throws If workspace not deployed, path invalid, or path points to a tree
 */
export declare function workspaceSetDatasetByHash(storage: StorageBackend, repo: string, ws: string, treePath: TreePath, valueHash: string, versions: VersionVector): Promise<void>;
/**
 * Result of querying a single dataset's status.
 */
export interface DatasetStatusResult {
    /** Ref type: 'unassigned' | 'null' | 'value' */
    refType: DataRef['type'];
    /** Object hash (null for unassigned/null refs) */
    hash: string | null;
    /** East type of the dataset */
    datasetType: EastTypeValue;
    /** Size in bytes (null for unassigned) */
    size: number | null;
}
/**
 * Get the status of a single dataset at a path within a workspace.
 *
 * Returns the ref type, hash, East type, and size without downloading the value.
 *
 * @param storage - Storage backend
 * @param repo - Repository identifier
 * @param ws - Workspace name
 * @param treePath - Path to the dataset
 * @returns Dataset status including ref type, hash, type, and size
 * @throws If workspace not deployed, path invalid, or path points to a tree
 */
export declare function workspaceGetDatasetStatus(storage: StorageBackend, repo: string, ws: string, treePath: TreePath): Promise<DatasetStatusResult>;
/**
 * A tree branch node (contains children).
 */
export interface TreeBranchNode {
    /** Field name */
    name: string;
    /** Discriminator */
    kind: 'tree';
    /** Child nodes */
    children: TreeNode[];
}
/**
 * A dataset leaf node (contains a value).
 */
export interface TreeLeafNode {
    /** Field name */
    name: string;
    /** Discriminator */
    kind: 'dataset';
    /** East type value (only present if includeTypes option was true) */
    datasetType?: EastTypeValue;
    /** Object hash (only present if includeStatus option was true and ref is 'value') */
    hash?: string;
    /** Ref type: 'unassigned' | 'null' | 'value' (only present if includeStatus option was true) */
    refType?: string;
    /** Size in bytes (only present if includeStatus option was true and ref is 'null' or 'value') */
    size?: number;
}
/**
 * A node in the tree structure for display purposes.
 */
export type TreeNode = TreeBranchNode | TreeLeafNode;
/**
 * Options for workspaceGetTree.
 */
export interface WorkspaceGetTreeOptions {
    /** Maximum depth to recurse (undefined = unlimited) */
    maxDepth?: number;
    /** Include East types for dataset nodes */
    includeTypes?: boolean;
    /** Include hash, refType, and size for dataset nodes */
    includeStatus?: boolean;
}
/**
 * Get the full tree structure at a path within a workspace.
 *
 * Recursively walks the structure and ref files to build a hierarchical
 * structure suitable for display. Tasks are shown as leaves with their output type.
 *
 * @param storage - Storage backend
 * @param repo - Repository identifier
 * @param ws - Workspace name
 * @param treePath - Path to start from (empty for root)
 * @param options - Optional settings for depth limit and type inclusion
 * @returns Array of tree nodes at the path
 * @throws If workspace not deployed or path invalid
 */
export declare function workspaceGetTree(storage: StorageBackend, repo: string, ws: string, treePath: TreePath, options?: WorkspaceGetTreeOptions): Promise<TreeNode[]>;
/**
 * List field names at a tree path within a package's data tree.
 *
 * Note: In the new format, packages store per-dataset refs in data/ dir
 * rather than tree objects. This function uses the structure directly.
 *
 * @param storage - Storage backend
 * @param repo - Repository identifier
 * @param name - Package name
 * @param version - Package version
 * @param path - Path to the tree node
 * @returns Array of field names at the path
 * @throws If package not found, path invalid, or path points to a dataset
 */
export declare function packageListTree(storage: StorageBackend, repo: string, name: string, version: string, path: TreePath): Promise<string[]>;
//# sourceMappingURL=trees.d.ts.map