@asaidimu/utils-workspace 7.0.1 → 7.0.3

package/index.d.ts

@@ -3,6 +3,132 @@ import { IndexDefinition, SchemaDefinition, SchemaChange, DataTransform, Predica
 import { QueryFilter, PaginationOptions } from '@asaidimu/query';
 import { GoogleGenAI, GenerateContentParameters } from '@google/genai';
 
+/**
+ * Severity levels for structured issues and errors.
+ */
+type Severity = "error" | "warning" | "info";
+/**
+ * Represents a detailed validation or operational problem.
+ * Designed to be machine-readable while remaining human-friendly.
+ */
+interface Issue {
+    /** Machine-readable identifier (e.g., "REQUIRED_FIELD_MISSING"). */
+    readonly code: string;
+    /** Human-readable description of the problem. */
+    readonly message: string;
+    /** Field path in a document or state (e.g., "users.0.email"). */
+    readonly path?: string;
+    /** Optional array index when the issue relates to a specific element. */
+    readonly index?: number;
+    /** Seriousness of the issue. Defaults to "error". */
+    readonly severity?: Severity;
+    /** Optional detailed explanation, can be multi-line. */
+    readonly description?: string;
+    /** Nested issues that caused this one. */
+    readonly cause?: readonly Issue[];
+}
+/**
+ * Standardized error code format: CATEGORY-XXX[-SUFFIX]
+ * Examples:
+ * - VAL-001 (Validation: required field missing)
+ * - DB-002-NF (Database: not found)
+ * - AUTH-003-DENIED (Auth: permission denied)
+ */
+interface ErrorCodeMetadata {
+    /** The formal error code (e.g., "VAL-001") */
+    readonly code: string;
+    /** Human-readable name for the error type */
+    readonly name: string;
+    /** Detailed description of when this error occurs */
+    readonly description: string;
+    /** Suggested action for handling or resolving the error */
+    readonly action?: string;
+    /** HTTP status code mapping (if applicable) */
+    readonly httpStatus?: number;
+    /** Category of the error */
+    readonly category: ErrorCategory;
+    /** Whether this error should be logged as warning vs error */
+    readonly logLevel?: "debug" | "info" | "warn" | "error";
+}
+type ErrorCategory = "validation" | "database" | "auth" | "business" | "system" | "network" | "concurrency" | "custom";
+/**
+ * SystemError is the primary error type for all operational and validation errors.
+ * Supports both predefined and custom error codes with full metadata.
+ */
+declare class SystemError extends Error {
+    readonly code: string;
+    readonly codeMetadata: ErrorCodeMetadata;
+    readonly severity: Severity;
+    readonly path?: string;
+    readonly operation?: string;
+    readonly issues: readonly Issue[];
+    readonly cause?: unknown;
+    constructor(params: {
+        code: string;
+        message?: string;
+        severity?: Severity;
+        path?: string;
+        operation?: string;
+        issues?: readonly Issue[];
+        cause?: unknown;
+        metadata?: Partial<Omit<ErrorCodeMetadata, "code">>;
+    });
+    /**
+     * Returns a new SystemError with the specified path.
+     */
+    withPath(path: string): SystemError;
+    /**
+     * Returns a new SystemError with the specified operation name.
+     */
+    withOperation(operation: string): SystemError;
+    /**
+     * Returns a new SystemError with the specified issue appended.
+     */
+    withIssue(issue: Issue): SystemError;
+    /**
+     * Returns a new SystemError with multiple issues appended.
+     */
+    withIssues(issues: readonly Issue[]): SystemError;
+    /**
+     * Returns a new SystemError wrapping the specified cause.
+     */
+    withCause(cause: unknown): SystemError;
+    /**
+     * Returns the HTTP status code for this error (if applicable).
+     */
+    getHttpStatus(): number | undefined;
+    /**
+     * Formats the error for logging with structured metadata.
+     */
+    toLogEntry(): Record<string, unknown>;
+    /**
+     * Produces a human-readable representation suitable for logging.
+     */
+    toString(): string;
+}
+/**
+ * Factory for creating a new SystemError with automatic metadata.
+ */
+declare function createError(code: string, message?: string): SystemError;
+/**
+ * A functional wrapper for operations that can fail.
+ * Encourages explicit error handling over try/catch blocks.
+ */
+type Result$1<T, E = SystemError> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: E;
+};
+/**
+ * Type-safe helpers for creating Results.
+ */
+declare const Result$1: {
+    ok: <T>(value: T) => Result$1<T, never>;
+    fail: <E>(error: E) => Result$1<never, E>;
+};
+
 type SerializerResult<T> = {
     value: T | null;
     error?: unknown;
@@ -66,7 +192,7 @@ declare class Serializer<T = void> {
 /**
  * Utility type for representing partial updates to the state, allowing deep nesting.
  * It makes all properties optional and applies the same transformation recursively
- * to nested objects and array elements, allowing for selective updates while
+ * to nested objects, allowing for selective updates while
  * preserving the original structure. It also includes the original type T and
  * undefined as possibilities for the top level and nested values.
  */
@@ -122,97 +248,19 @@ declare const Branded: {
 };
 
 /**
- * Severity levels for structured issues and errors.
- */
-type Severity = "error" | "warning" | "info";
-/**
- * Represents a detailed validation or operational problem.
- * Designed to be machine-readable while remaining human-friendly.
- */
-interface Issue {
-    /** Machine-readable identifier (e.g., "REQUIRED_FIELD_MISSING"). */
-    readonly code: string;
-    /** Human-readable description of the problem. */
-    readonly message: string;
-    /** Field path in a document or state (e.g., "users.0.email"). */
-    readonly path?: string;
-    /** Optional array index when the issue relates to a specific element. */
-    readonly index?: number;
-    /** Seriousness of the issue. Defaults to "error". */
-    readonly severity?: Severity;
-    /** Optional detailed explanation, can be multi-line. */
-    readonly description?: string;
-    /** Nested issues that caused this one. */
-    readonly cause?: readonly Issue[];
-}
-/**
- * SystemError is the primary error type for all operational and validation errors.
- * It provides rich contextual information and supports immutable composition
- * through a fluent API.
- */
-declare class SystemError extends Error {
-    readonly code: string;
-    readonly severity: Severity;
-    readonly path?: string;
-    readonly operation?: string;
-    readonly issues: readonly Issue[];
-    readonly cause?: unknown;
-    constructor(params: {
-        code: string;
-        message: string;
-        severity?: Severity;
-        path?: string;
-        operation?: string;
-        issues?: readonly Issue[];
-        cause?: unknown;
-    });
-    /**
-     * Returns a new SystemError with the specified path.
-     * Path typically indicates the location in a data structure where the error occurred.
-     */
-    withPath(path: string): SystemError;
-    /**
-     * Returns a new SystemError with the specified operation name.
-     * Describes what was being attempted when the error occurred.
-     */
-    withOperation(operation: string): SystemError;
-    /**
-     * Returns a new SystemError with the specified issue appended.
-     */
-    withIssue(issue: Issue): SystemError;
-    /**
-     * Returns a new SystemError with multiple issues appended.
-     */
-    withIssues(issues: readonly Issue[]): SystemError;
-    /**
-     * Returns a new SystemError wrapping the specified cause.
-     */
-    withCause(cause: unknown): SystemError;
-    /**
-     * Produces a human-readable representation suitable for logging.
-     */
-    toString(): string;
-}
-/**
- * Factory for creating a new SystemError.
- */
-declare function createError(code: string, message: string): SystemError;
-/**
- * Predefined common error codes.
+ * Predefined common error codes, mapped to the standard ErrorCodes registry.
  */
 declare const CommonErrors: {
-    readonly NOT_FOUND: "NOT_FOUND";
-    readonly DUPLICATE_KEY: "DUPLICATE_KEY";
-    readonly INVALID_COMMAND: "INVALID_COMMAND";
-    readonly PERMISSION_DENIED: "PERMISSION_DENIED";
-    readonly BACKEND_ERROR: "BACKEND_ERROR";
-    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
-    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
-    readonly CONCURRENCY_ERROR: "CONCURRENCY_ERROR";
-    /** Returned when an operation cannot proceed because a resource is locked. */
-    readonly RESOURCE_LOCKED: "RESOURCE_LOCKED";
-    /** Returned when an operation was explicitly aborted or the system is shutting down. */
-    readonly OPERATION_ABORTED: "OPERATION_ABORTED";
+    readonly NOT_FOUND: "DB-001-NF";
+    readonly DUPLICATE_KEY: "DB-002-DUP";
+    readonly INVALID_COMMAND: "BUS-001";
+    readonly PERMISSION_DENIED: "AUTH-001-DENIED";
+    readonly BACKEND_ERROR: "SYS-002";
+    readonly INTERNAL_ERROR: "SYS-001";
+    readonly VALIDATION_FAILED: "VAL-001";
+    readonly CONCURRENCY_ERROR: "CON-001";
+    readonly RESOURCE_LOCKED: "DB-003-LOCK";
+    readonly OPERATION_ABORTED: "BUS-002-ABORT";
 };
 
 /**
@@ -335,14 +383,25 @@ interface Event<T extends string = string, P = any, M extends Metadata = {}> {
     readonly meta: M;
 }
 /**
- * A pure function that calculates a state patch based on a command.
- * Reducers are the primary mechanism for state mutation in the CQRS loop.
+ * Represents the structured outcome of an Action.
+ * Allows an action to specify both a state patch and a computational result.
+ */
+interface ActionOutcome<S extends Record<string, any>, I extends Index, R = any> {
+    /** The speculative state patch to be applied to the system. */
+    patch?: DeepPartial<State<S, I>>;
+    /** The computational return value for the caller. */
+    result?: R;
+}
+/**
+ * A pure-ish function that calculates a state patch and/or a result based on a command.
+ * Actions are the primary mechanism for logic execution in the CQRS loop.
  *
  * @template S - The Domain State type.
  * @template I - The Index type.
  * @template C - The specific Command type being handled.
+ * @template R - The result type.
  */
-type Action<S extends Record<string, any>, I extends Index, C extends Command<any, any, any>> = (state: State<S, I>, command: C) => DeepPartial<State<S, I>> | Promise<DeepPartial<State<S, I>>>;
+type Action<S extends Record<string, any>, I extends Index, C extends Command<any, any, any>, R = any> = (state: State<S, I>, command: C) => Result<DeepPartial<State<S, I>> | ActionOutcome<S, I, R>, SystemError> | Promise<Result<DeepPartial<State<S, I>> | ActionOutcome<S, I, R>, SystemError>>;
 type ActionEntry<S extends Record<string, any>, I extends Index, C extends Command<any, any, any>> = {
     action: Action<S, I, C>;
     namespace: string;
@@ -362,8 +421,8 @@ type Middleware<S extends Record<string, any>, I extends Index> = (api: {
     /** Returns the current consistent snapshot of the state. */
     state: () => State<S, I>;
     /** Re-dispatches a command through the full pipeline. */
-    dispatch: <C extends Command<any, any, any>>(command: C) => Promise<Result<void, SystemError>>;
-}) => (next: (command: Command<any, any, any>) => Promise<Result<DeepPartial<State<S, I>>, SystemError>>) => (command: Command<any, any, any>) => Promise<Result<DeepPartial<State<S, I>>, SystemError>>;
+    dispatch: <C extends Command<any, any, any>, R = any>(command: C) => Promise<Result<R, SystemError>>;
+}) => (next: (command: Command<any, any, any>) => Promise<Result<ActionOutcome<S, I>, SystemError>>) => (command: Command<any, any, any>) => Promise<Result<ActionOutcome<S, I>, SystemError>>;
 /**
  * A collection of named registries that collectively know how to produce
  * a materialized index projection.
@@ -1047,13 +1106,13 @@ interface CommandRegistry<S extends Record<string, any>, I extends Index = {}> {
 interface CommandCoordinator<T extends string> {
     /**
      * Dispatches a single command through the auth → middleware → reducer
-     * → state pipeline.
+     * pipeline and commits the resulting state patch.
      *
      * @param ctx     - The verified identity and permissions of the actor.
      * @param command - The command carrying intent and payload.
-     * @returns       - A Result indicating success or a structured failure.
+     * @returns       - A Result containing the computational return value or a SystemError.
      */
-    dispatch<C extends Command<any, any, any>>(ctx: AuthContext<T>, command: C): Promise<Result<void, SystemError>>;
+    dispatch<C extends Command<any, any, any>, R = any>(ctx: AuthContext<T>, command: C): Promise<Result<R, SystemError>>;
     /**
      * Executes a sequence of steps as an atomic saga.
      *
@@ -1102,7 +1161,10 @@ interface IRegistry<T> {
     clear(): void;
     /** Creates a deep clone of the registry. */
     clone(): IRegistry<T>;
+    /** Returns a record of entrys keyed by a string key */
     entries(): Record<string, T>;
+    /** Returns number of items in registry */
+    count(): number;
 }
 /** The read/write contract for a registry. */
 type IRegistryReader<T> = Pick<IRegistry<T>, "get" | "list" | "entries" | "has">;
@@ -1254,12 +1316,13 @@ declare class Registry<T> implements IRegistry<T> {
      * Creates a deep clone of the registry.
      * @returns A new Registry instance with deeply cloned items
      */
-    clone(): Registry<T>;
+    clone(): IRegistry<T>;
     /**
      * Returns all registry entries as a plain object.
      * @returns Object with all registry key-value pairs
      */
     entries(): Record<string, T>;
+    count(): number;
 }
 
 /**
@@ -1288,7 +1351,7 @@ declare class ExecutionEngine<T extends string, S extends Record<string, any>, I
     get authorizer(): Authorizer<T, S, I>;
     register<C extends Command<any, any, any>>(namespace: string, type: C["type"], reducer: Action<S, I, C>): Result<void, SystemError>;
     use(middleware: Middleware<S, I>): void;
-    dispatch<C extends Command<any, any, any>>(ctx: AuthContext<T>, command: C): Promise<Result<void, SystemError>>;
+    dispatch<C extends Command<any, any, any>, R = any>(ctx: AuthContext<T>, command: C): Promise<Result<R, SystemError>>;
     transact(ctx: AuthContext<T>, steps: TransactionStep[]): Promise<Result<void, SystemError>>;
     /**
      * Core dispatch pipeline: auth → middleware chain → reducer → state.
@@ -1338,7 +1401,7 @@ declare class ExecutionEngine<T extends string, S extends Record<string, any>, I
 declare class KernelCoordinator<T extends string, S extends Record<string, any>, I extends Index = {}> implements CommandCoordinator<T>, AuthorizationProvider<T, S, I> {
     private readonly engine;
     private readonly serializer;
-    constructor(engine: ExecutionEngine<T, S, I>, serializer: Serializer<Result<void, SystemError>>);
+    constructor(engine: ExecutionEngine<T, S, I>, serializer: Serializer<Result<any, SystemError>>);
     get authorizer(): Authorizer<T, S, I>;
     /**
      * Dispatches a single command through the serialized execution pipeline.
@@ -1349,7 +1412,7 @@ declare class KernelCoordinator<T extends string, S extends Record<string, any>,
      * @param ctx     - The verified identity and permissions of the actor.
      * @param command - The command carrying intent and payload.
      */
-    dispatch<C extends Command<any, any, any>>(ctx: AuthContext<T>, command: C): Promise<Result<void, SystemError>>;
+    dispatch<C extends Command<any, any, any>, R = any>(ctx: AuthContext<T>, command: C): Promise<Result<R, SystemError>>;
     /**
      * Executes a multi-step transaction through the serialized pipeline.
      *
@@ -1547,6 +1610,133 @@ declare function createAnonymousContext(): AuthContext<"anonymous">;
  */
 declare function createUserContext(userId: UUID, scopes?: string[], metadata?: UUID): AuthContext<"user">;
 
+/**
+ * A ultra-compact, runtime-scoped tracking registry.
+ * Translates multi-segment semantic components or dynamic types
+ * into 1-token safe base36 structural short-hashes.
+ */
+declare class ShortKeyRegistry<T extends string = string> {
+    private readonly counters;
+    private readonly runtimeSalt;
+    constructor();
+    /**
+     * Generates a compact, non-colliding short token key.
+     * Compresses the target scope tracking increment into a deterministic signature.
+     */
+    next(scope: T): string;
+    /**
+     * Reset local execution indices for context window boundary updates.
+     */
+    clear(): void;
+}
+
+/**
+ * Utility class for common blob and binary data operations.
+ * Optimized for environments supporting Node.js, Browsers, and Edge runtimes.
+ */
+declare class BlobUtilities {
+    /**
+     * Computes the SHA-256 hash of a given Uint8Array.
+     * @param data The Uint8Array to hash.
+     * @returns A Promise that resolves to the SHA-256 hash as a hexadecimal string.
+     */
+    static computeSHA256(data: Uint8Array): Promise<string>;
+    /**
+     * Computes a CRC32 checksum of a given Uint8Array for fast data integrity verification.
+     * @param data The Uint8Array to checksum.
+     * @returns The CRC32 checksum as a hexadecimal string.
+     */
+    static computeCRC32(data: Uint8Array): string;
+    /**
+     * Converts a Uint8Array to a Base64 string.
+     * Uses native Buffer in Node.js/Deno, and falls back to a chunked btoa()
+     * implementation for Browsers and Edge environments to avoid stack overflows.
+     * @param buffer The Uint8Array to convert.
+     * @returns The Base64 encoded string.
+     */
+    static bufferToBase64(buffer: Uint8Array): string;
+    /**
+     * Converts a Base64 string back to a Uint8Array.
+     * @param base64 The Base64 encoded string.
+     * @returns The decoded Uint8Array.
+     */
+    static base64ToBuffer(base64: string): Uint8Array;
+    /**
+     * Generates a short, deterministic hash of a string.
+     * Returns a uniformly distributed, fixed-length base36 string.
+     * @param s The string to hash.
+     * @param length The desired length of base36 hash. Defaults to 4.
+     * @returns The short base36 hash string.
+     */
+    static shortHash(s: string, length?: number): string;
+    /**
+     * Converts a Blob to a Uint8Array.
+     * @param blob The Blob to convert.
+     * @returns A Promise that resolves to the Uint8Array.
+     */
+    static blobToUint8Array(blob: Blob): Promise<Uint8Array>;
+    /**
+     * Creates a Blob from a Uint8Array.
+     * @param data The Uint8Array to create the blob from.
+     * @param mimeType The MIME type of the blob (e.g., 'application/octet-stream').
+     * @returns The resulting Blob.
+     */
+    static uint8ArrayToBlob(data: Uint8Array, mimeType?: string): Blob;
+    /**
+     * Encodes a string into a Uint8Array using UTF-8.
+     * @param text The string to encode.
+     * @returns The encoded Uint8Array.
+     */
+    static textToUint8Array(text: string): Uint8Array;
+    /**
+     * Decodes a Uint8Array into a string using UTF-8.
+     * @param data The Uint8Array to decode.
+     * @returns The decoded string.
+     */
+    static uint8ArrayToText(data: Uint8Array): string;
+    /**
+     * Converts a Uint8Array to a URL-safe Base64 string.
+     * Replaces '+' with '-', '/' with '_', and removes trailing '=' padding.
+     * @param buffer The Uint8Array to convert.
+     * @returns The URL-safe Base64 encoded string.
+     */
+    static bufferToUrlSafeBase64(buffer: Uint8Array): string;
+    /**
+     * Converts a URL-safe Base64 string back to a Uint8Array.
+     * Restores padding and replaces characters back to standard Base64.
+     * @param base64 The URL-safe Base64 encoded string.
+     * @returns The decoded Uint8Array.
+     */
+    static urlSafeBase64ToBuffer(base64: string): Uint8Array;
+    /**
+     * Slices a Blob into chunks of a specified size.
+     * This is useful for uploading large files in parts or feeding data into LLM context windows.
+     * @param blob The Blob to slice.
+     * @param chunkSize The size of each chunk in bytes.
+     * @param options An optional configuration for the chunking process.
+     * @returns An async generator that yields Uint8Arrays of the binary data.
+     */
+    static chunkBlob(blob: Blob, chunkSize?: number): AsyncGenerator<Uint8Array>;
+    /**
+     * Wraps a Uint8Array with metadata providing business context for ERP systems.
+     * The metadata is stored as a JSON string at the start of the Blob, followed by the length of the length of the metadata length.
+     * @param buffer The binary data to wrap.
+     * @param metadata own a single object containing metadata keys/values.
+     * @returns A Uint8Array containing metadata and binary data.
+     */
+    static wrapBlobMetadata(buffer: Uint8Array, metadata: Record<string, any>): Uint8Array;
+    /**
+     * Unwraps a Uint8Array containing metadata wrapped by wrapBlobMetadata.
+     * @param wrappedBuffer own a Uint8Array containing metadata and metadata length.
+     * @returns An object containing the original binary data and the metadata object.
+     * @throws Error if the buffer is too small or contains invalid metadata length.
+     */
+    static unwrapBlobMetadata(wrappedBuffer: Uint8Array): {
+        data: Uint8Array;
+        metadata: Record<string, any>;
+    };
+}
+
 type DatabaseConfig = {
     factory: StoreFactory;
     database: string;
@@ -1815,7 +2005,7 @@ declare class ModuleAggregator<T extends string, S extends Record<string, any>,
 }
 
 type ContentCoreState = any;
-interface Blob extends Identifiable, Timestamped, Versioned {
+interface Blob$1 extends Identifiable, Timestamped, Versioned {
     readonly checksum: SHA256;
     readonly size: number;
     readonly mime: string;
@@ -1835,7 +2025,7 @@ interface Blob extends Identifiable, Timestamped, Versioned {
  * A lightweight reference to a blob.
  * Used in content blocks to avoid passing heavy metadata or binary data across boundaries.
  */
-type BlobRef = Pick<Blob, "id" | "checksum" | "mime" | "size">;
+type BlobRef = Pick<Blob$1, "id" | "checksum" | "mime" | "size">;
 type ResolvedBlob = {
     /** Indicates the blob data is available in the local memory space. */
     kind: "inline";
@@ -1977,7 +2167,7 @@ interface ContentDefinition<ContentType extends string, Data extends Record<stri
      * Scans a content block of this type for actionable side effects.
      * Returns a list of Commands to be dispatched against the workspace.
      */
-    parse?: (value: Data) => Command<any>[];
+    parse?: (block: Content<ContentType, Data>) => Command<any>[];
 }
 
 /**
@@ -1999,7 +2189,7 @@ interface ToolResultData {
     /** The output returned by the tool (any JSON-serializable value) */
     result: unknown;
     /** Identifier that links this result to the original tool-call */
-    callId: string;
+    key: string;
     /** Optional error message if the tool execution failed */
     error?: string;
 }
@@ -2146,14 +2336,23 @@ interface AgentIndex extends Index {
 }
 /**
  * A tool that can be called by an agent.
+ * Descriptions and parameter structures serve both human engineers (for debugging/registry)
+ * and LLMs (for precise function execution routing).
  */
 interface ToolDefinition<Name extends string = string, Params extends Record<string, any> = any> {
     /** The unique name of the tool. Used in the model response to identify which tool to call. */
     name: Name;
-    /** Human-readable description of what the tool does. */
+    /** Human-readable description explaining what the tool does, its side effects, and when to use it. */
     description: string;
     /** JSON Schema fragment defining the tool's parameters. */
-    parameters: Record<string, unknown>;
+    parameters?: Record<string, unknown>;
+    /** * Explicit execution arguments showcasing expected input profiles.
+     * Directly utilized to ground structured model inferences and guide developers.
+     */
+    example: {
+        input?: Params;
+        explanation: string;
+    };
     /**
      * The actual implementation function.
      * This is executed by the system when the model requests this tool.
@@ -2407,11 +2606,6 @@ type SnapshotTarget = {
     kind: "turn";
     turn: Turn;
 };
-type SnapshotErrorKind = "session-not-found" | "role-not-found";
-declare class SnapshotError extends Error {
-    readonly kind: SnapshotErrorKind;
-    constructor(kind: SnapshotErrorKind, message: string);
-}
 /**
  * Wraps each effect dispatch outcome so callers can inspect per-effect
  * failures without the sequence being aborted by a throw.
@@ -2549,7 +2743,7 @@ declare class Session {
      * @param target - Optional discriminated target to build the snapshot
      *   against. Omit to use the current head of the active chain.
      */
-    snapshot(target?: SnapshotTarget): Promise<Result<SessionSnapshot, SnapshotError>>;
+    snapshot(target?: SnapshotTarget): Promise<Result<SessionSnapshot, SystemError>>;
     /**
      * Throws if the session has been closed, giving mutations a consistent
      * early-exit rather than propagating odd errors from the coordinator.
@@ -2650,6 +2844,7 @@ type DeleteRoleCommand = Command<"role:delete", {
 type ExecuteToolCommand = Command<"tool:execute", {
     name: string;
     parameters: Record<string, any>;
+    key: string;
 }>;
 /**
  * Union of all Agent commands.
@@ -2662,9 +2857,15 @@ type AgentCommand = AddRoleCommand | UpdateRoleCommand | DeleteRoleCommand | Exe
  */
 declare class ToolRegistry extends Registry<ToolDefinition<any>> {
     /**
-     * Returns a system-prompt section describing all available tools.
+     * Returns a token-optimized system-prompt section describing available tools
+     * using a neutral, standardized example tool block blueprint.
      */
     description(): string;
+    /**
+     * Generates the strict structured array blocks for your response schema.
+     * This is where the aggregation happens effortlessly!
+     */
+    schema(): any[];
     /**
      * Returns a JSON Schema array of all tool definitions.
      * Useful for providers that support native tool-calling (like OpenAI/Gemini).
@@ -2701,32 +2902,36 @@ declare class AgentModule implements Module<"user" | "system", Record<string, an
         roles: RoleStore;
     }>;
     actions: {
-        "role:add": (_state: State<any, AgentIndex>, command: AddRoleCommand) => Promise<{
+        "role:add": (_state: State<any, AgentIndex>, command: AddRoleCommand) => Promise<Result<{
             index: {
                 roles: {
                     [x: string]: RoleSummary | undefined;
                 };
             };
-        }>;
+        }, never>>;
         "role:update": (state: State<any, AgentIndex>, command: UpdateRoleCommand) => Promise<{
-            index?: undefined;
+            readonly ok: false;
+            readonly error: never;
         } | {
-            index: {
-                roles: {
-                    [name]: RoleSummary | undefined;
-                };
-            };
+            readonly ok: true;
+            readonly value: {};
         }>;
         "role:delete": (state: State<any, AgentIndex>, command: DeleteRoleCommand) => Promise<{
-            index?: undefined;
+            readonly ok: false;
+            readonly error: never;
         } | {
-            index: {
-                roles: {
-                    [name]: any;
-                };
+            readonly ok: true;
+            readonly value: {};
+        }>;
+        "tool:execute": (_state: State<any, AgentIndex>, command: ExecuteToolCommand) => Promise<{
+            readonly ok: false;
+            readonly error: SystemError;
+        } | {
+            readonly ok: true;
+            readonly value: {
+                result: any;
             };
         }>;
-        "tool:execute": (_state: State<any, AgentIndex>, command: ExecuteToolCommand) => Promise<any>;
     };
     /**
      * Rebuilds the AgentIndex from durable storage.
@@ -2741,17 +2946,17 @@ declare class AgentModule implements Module<"user" | "system", Record<string, an
  * This implementation addresses the constraint that Anansi should
  * not store large binary payloads directly.
  */
-declare class BlobStore extends BaseStore<Blob, "id", Blob> {
+declare class BlobStore extends BaseStore<Blob$1, "id", Blob$1> {
     private readonly storage;
-    constructor(collection: Collection<Blob>, storage: BlobStorage);
+    constructor(collection: Collection<Blob$1>, storage: BlobStorage);
     /**
      * Overridden to hydrate the binary data from specialized storage.
      */
-    get(id: UUID): Promise<Blob | null>;
+    get(id: UUID): Promise<Blob$1 | null>;
     /**
      * Overridden to separate metadata and binary data during creation.
      */
-    add(entity: Blob): Promise<void>;
+    add(entity: Blob$1): Promise<void>;
     /**
      * Overridden to ensure bytes are purged when the record is deleted.
      */
@@ -2759,7 +2964,7 @@ declare class BlobStore extends BaseStore<Blob, "id", Blob> {
     /**
      * Finds a blob by its content checksum.
      */
-    findByChecksum(checksum: SHA256): Promise<Blob | null>;
+    findByChecksum(checksum: SHA256): Promise<Blob$1 | null>;
     /**
      * Resolves a BlobRef to a ResolvedBlob (inline or remote) or null.
      *
@@ -2844,7 +3049,7 @@ declare class ContentModule implements Module<"user" | "system", ContentCoreStat
         blobs: BlobStore;
     }>;
     actions: {
-        "content:add": (_: State<ContentCoreState, ContentIndex>, command: AddContentCommand) => Promise<{
+        "content:add": (_: State<ContentCoreState, ContentIndex>, command: AddContentCommand) => Promise<Result<{
             index: {
                 content: {
                     items: {
@@ -2855,52 +3060,38 @@ declare class ContentModule implements Module<"user" | "system", ContentCoreStat
                     };
                 };
             };
-        }>;
+        }, never>>;
         "content:update": (state: State<ContentCoreState, ContentIndex>, command: UpdateContentCommand) => Promise<{
-            index?: undefined;
+            readonly ok: false;
+            readonly error: never;
         } | {
-            index: {
-                content: {
-                    items: {
-                        [x: string]: ContentSummary<any>;
-                    };
-                    keys: {};
-                };
-            };
+            readonly ok: true;
+            readonly value: {};
         }>;
         "content:delete": (state: State<ContentCoreState, ContentIndex>, command: DeleteContentCommand) => Promise<{
-            index?: undefined;
+            readonly ok: false;
+            readonly error: never;
         } | {
-            index: {
-                content: {
-                    items: {
-                        [x: string]: any;
-                    };
-                    keys: {
-                        [x: number]: any;
-                    };
-                };
-            };
+            readonly ok: true;
+            readonly value: {};
         }>;
-        "blob:register": (state: State<ContentCoreState, ContentIndex>, command: RegisterBlobCommand) => Promise<{
+        "blob:register": (state: State<ContentCoreState, ContentIndex>, command: RegisterBlobCommand) => Promise<Result<{
             index: {
                 content: {
                     blobs: any;
                 };
             };
-        }>;
-        "blob:retain": (_state: State<ContentCoreState, ContentIndex>, command: RetainBlobCommand) => Promise<{}>;
-        "blob:release": (_state: State<ContentCoreState, ContentIndex>, command: ReleaseBlobCommand) => Promise<{}>;
+        }, never>>;
+        "blob:retain": (_state: State<ContentCoreState, ContentIndex>, command: RetainBlobCommand) => Promise<Result<{}, never>>;
+        "blob:release": (_state: State<ContentCoreState, ContentIndex>, command: ReleaseBlobCommand) => Promise<Result<{}, never>>;
         "blob:purge": (state: State<ContentCoreState, ContentIndex>, command: PurgeBlobCommand) => Promise<{
-            index?: undefined;
+            readonly ok: false;
+            readonly error: never;
         } | {
-            index: {
-                content: {
-                    blobs: any;
-                };
-            };
+            readonly ok: true;
+            readonly value: {};
         }>;
-        "blob:record_remote_id": (_state: State<ContentCoreState, ContentIndex>, command: RecordBlobRemoteIdCommand) => Promise<{}>;
+        "blob:record_remote_id": (_state: State<ContentCoreState, ContentIndex>, command: RecordBlobRemoteIdCommand) => Promise<Result<{}, never>>;
     };
     /**
      * Rebuilds the ContentIndex from durable storage.
@@ -2990,84 +3181,68 @@ declare class SessionModule implements Module<"user" | "system", Record<string,
         turns: TurnStore;
     }>;
     actions: {
-        "session:create": (_: State<any, SessionIndex>, command: CreateSessionCommand) => Promise<{
+        "session:create": (_: State<any, SessionIndex>, command: CreateSessionCommand) => Promise<Result<{
             index: {
                 sessions: {
                     [x: string]: SessionSummary;
                 };
             };
-        }>;
+        }, never>>;
         "session:update": (state: State<any, SessionIndex>, command: UpdateSessionCommand) => Promise<{
-            index?: undefined;
+            readonly ok: false;
+            readonly error: never;
         } | {
-            index: {
-                sessions: {
-                    [x: string]: SessionSummary;
-                };
-            };
+            readonly ok: true;
+            readonly value: {};
         }>;
         "session:fork": (state: State<any, SessionIndex>, command: ForkSessionCommand) => Promise<{
-            index?: undefined;
+            readonly ok: false;
+            readonly error: never;
         } | {
-            index: {
-                sessions: {
-                    [x: string]: SessionSummary;
-                };
-            };
+            readonly ok: true;
+            readonly value: {};
         }>;
         "session:delete": (state: State<any, SessionIndex>, command: DeleteSessionCommand) => Promise<{
-            index?: undefined;
+            readonly ok: false;
+            readonly error: never;
         } | {
-            index: {
-                sessions: {
-                    [x: string]: any;
-                };
-            };
+            readonly ok: true;
+            readonly value: {};
         }>;
         "turn:add": (state: State<any, SessionIndex>, command: AddTurnCommand) => Promise<{
-            index?: undefined;
+            readonly ok: false;
+            readonly error: never;
         } | {
-            index: {
-                sessions: {
-                    [x: string]: SessionSummary;
-                };
-            };
+            readonly ok: true;
+            readonly value: {};
         }>;
         "turn:update": (state: State<any, SessionIndex>, command: UpdateTurnCommand) => Promise<{
-            index?: undefined;
+            readonly ok: false;
+            readonly error: never;
         } | {
-            index: {
-                sessions: {
-                    [x: string]: SessionSummary;
-                };
-            };
+            readonly ok: true;
+            readonly value: {};
         }>;
         "turn:edit": (state: State<any, SessionIndex>, command: EditTurnCommand) => Promise<{
-            index?: undefined;
+            readonly ok: false;
+            readonly error: never;
         } | {
-            index: {
-                sessions: {
-                    [x: string]: any;
-                };
-            };
+            readonly ok: true;
+            readonly value: {};
         }>;
         "turn:branch": (state: State<any, SessionIndex>, command: BranchTurnCommand) => Promise<{
-            index?: undefined;
+            readonly ok: false;
+            readonly error: never;
         } | {
-            index: {
-                sessions: {
-                    [x: string]: SessionSummary;
-                };
-            };
+            readonly ok: true;
+            readonly value: {};
         }>;
         "turn:delete": (state: State<any, SessionIndex>, command: DeleteTurnCommand) => Promise<{
-            index?: undefined;
+            readonly ok: false;
+            readonly error: never;
         } | {
-            index: {
-                sessions: {
-                    [x: string]: SessionSummary;
-                };
-            };
+            readonly ok: true;
+            readonly value: {};
         }>;
     };
     /**
@@ -3109,14 +3284,23 @@ declare function createWorkspace<T extends string, S extends Record<string, any>
     aggregator: ModuleAggregator<string, S, I>;
 }>;
 
+declare const ToolCallRegex: RegExp;
 /**
  * Registry for managing ContentDefinitions.
  * Enables the Kernel to delegate type-specific logic to registered handlers.
  */
 declare class ContentRegistry extends Registry<ContentDefinition<any>> {
+    private readonly shortKeys;
     constructor(opts: {
         logger: Logger$1;
+        empty?: boolean;
     });
+    /**
+     * Gets an item by its key.
+     * @param key - The key of the item to retrieve
+     * @returns The item if found, undefined otherwise
+     */
+    get(key: string): ContentDefinition<any> | undefined;
     /**
      * Returns the system-prompt section describing all emittable block types.
      */
@@ -3124,12 +3308,12 @@ declare class ContentRegistry extends Registry<ContentDefinition<any>> {
     /**
      * Returns a plain JSON Schema object scoped to emittable block definitions.
      */
-    schema(filter?: ContentFilter): Record<string, unknown>;
+    schema(filter?: ContentFilter, extra?: Record<string, unknown>[]): Record<string, unknown>;
     /**
-     * Returns the default mode for a registered content type.
-     * @param type - The content type string (e.g., "text", "thinking")
-     * @returns The ContentMode if the type is registered, undefined otherwise.
+     * Updates an existing item with new properties.
+     * Special handling for 'mappings' to ensure provider mappings are merged rather than overwritten.
      */
+    update(key: string, updates: Partial<ContentDefinition<any>>): Result$1<void, SystemError>;
     mode(type: string): ContentMode | undefined;
     /**
      * Converts a raw JSON object from a model response into a workspace content block.
@@ -3219,7 +3403,7 @@ interface Prompt {
      * (i.e., the tool has already been executed).
      * Empty object if the last assistant turn has no tool calls or no results yet.
      */
-    tools: Array<ToolResultContent>;
+    results: Array<ToolResultContent>;
     /**
      * Non-fatal warnings generated during the build phase.
      */
@@ -3254,7 +3438,7 @@ interface AssemblerExtension extends PromptSection {
  * Provider-agnostic system prompt assembler.
  */
 interface SystemPromptAssembler {
-    readonly registry: ContentRegistry;
+    readonly content: ContentRegistry;
     build<P, C>(provider: string, prompt: Prompt, mapTurn: (args: {
         turn: Turn;
         parts: P[];
@@ -3262,6 +3446,7 @@ interface SystemPromptAssembler {
         system: string;
         transcript: C[];
         sections: PromptSection[];
+        schema: any;
     }>;
     join(sections: PromptSection[]): string;
 }
@@ -3324,6 +3509,8 @@ interface InferenceContext {
         /** Tokens remaining in the context window after this prompt. */
         remaining?: number;
     };
+    /** the schema of the response structure */
+    schema: Record<string, any>;
     /**
      * Sends this prompt to the model.
      * @returns The parsed assistant Turn plus any execution side-effects.
@@ -3459,10 +3646,11 @@ interface Logger {
     info?: (message: string, ...args: unknown[]) => void;
 }
 declare class PromptAssembler implements SystemPromptAssembler {
+    readonly content: ContentRegistry;
+    private readonly tools;
     private resolver;
-    readonly registry: ContentRegistry;
     private readonly logger;
-    constructor(registry: ContentRegistry, resolver: BlobResolver, logger?: Logger);
+    constructor(content: ContentRegistry, tools: ToolRegistry, resolver: BlobResolver, logger?: Logger);
     build<P, C>(provider: string, prompt: Prompt, mapTurn: (args: {
         turn: Turn;
         parts: P[];
@@ -3470,7 +3658,9 @@ declare class PromptAssembler implements SystemPromptAssembler {
         system: string;
         sections: PromptSection[];
         transcript: C[];
+        schema: any;
     }>;
+    private buildSchema;
     private buildSections;
     join(sections: PromptSection[]): string;
 }
@@ -3593,15 +3783,27 @@ declare class TurnBuilder {
     }): TurnBuilder;
     addToolCall(name: string, parameters: Record<string, unknown>, options?: {
         key?: string;
-        callId?: string;
         label?: string;
         topics?: string[];
     }): TurnBuilder;
-    addToolResult(callId: string, name: string, result: unknown, error?: string, options?: {
+    addToolResult(key: string, name: string, result: unknown, error?: string, options?: {
         key?: string;
         label?: string;
         topics?: string[];
     }): TurnBuilder;
+    /**
+     * Adds a historical tool report block (read‑only archival record).
+     * @param key - Unique key linking to the original tool call.
+     * @param name - Name of the tool that was invoked.
+     * @param parameters - Arguments passed to the tool.
+     * @param result - The result value (if successful). Provide only when `error` is omitted.
+     * @param error - The error message (if failed). Provide only when `result` is omitted.
+     * @param options - Optional block metadata (`label`, `topics`).
+     */
+    addToolReport(key: string, name: string, parameters: Record<string, unknown>, result?: unknown, error?: string, options?: {
+        label?: string;
+        topics?: string[];
+    }): TurnBuilder;
     addBlock(block: Content<any, any>): TurnBuilder;
     deleteBlock(blockId: UUID): TurnBuilder;
     withId(id: UUID): TurnBuilder;
@@ -3690,6 +3892,7 @@ declare class Bootstrapper {
         turns: TurnBuilderFactory;
     }>;
 }
+type BootstrappedWorkspace = Awaited<ReturnType<typeof Bootstrapper.workspace>>;
 
 declare const GOOGLE_MODELS: Array<ModelProfile>;
 /** Everyday workhorse models: Flash variants + larger Gemma 4s. */
@@ -3704,10 +3907,10 @@ declare class GoogleGenAIAdapter implements LLMAdapter {
     private readonly assembler;
     private readonly turns;
     private readonly registry;
-    private readonly tools?;
     private readonly model;
     private readonly _models;
-    constructor(client: GoogleGenAI, assembler: SystemPromptAssembler, turns: TurnBuilderFactory, registry: ContentRegistry, tools?: ToolRegistry | undefined, options?: {
+    private readonly logger;
+    constructor(client: GoogleGenAI, assembler: SystemPromptAssembler, turns: TurnBuilderFactory, registry: ContentRegistry, logger: Logger$1, options?: {
         model: string;
         models: Array<ModelProfile>;
     });
@@ -3776,4 +3979,4 @@ declare class MemoryBlobStorage implements BlobStorage {
     exportAllBytes(): Promise<Array<[SHA256, Uint8Array]>>;
 }
 
-export { type Action, type ActionEntry, type AgentIndex, AgentModule, type AssemblerExtension, type AuthContext, AuthContextBuilder, type AuthorizationProvider, type Authorizer, BaseStore, type Blob, type BlobRef, type BlobResolver, type BlobStorage, type BootstrapParams, Bootstrapper, type BranchInfo, Branded, type Command, type CommandCoordinator, type CommandRegistry, CommonErrors, ConsoleLogger, type Content, type ContentCoreState, type ContentDefinition, type ContentFilter, type ContentIndex, type ContentMapper, type ContentMode, ContentModule, ContentRegistry, type ContentRetriever, type ContentSummary, type CreateWorkspaceCommand, type CreateWorkspaceParams, DELETE_SYMBOL, type DatabaseConfig, type DeepPartial, type DomainRegistry, type EffectResult, type Entity, type Event, index as GoogleAdapter, type IKernel, type IRegistry, type IRegistryReader, type IWorkspaceDatabase, type Identifiable, type Index, type IndexedDBBlobConfig, IndexedDBBlobStorage, type InferenceContext, type InferenceResults, type Issue, Kernel, type KernelConfig, LLM, type LLMAdapter, type LLMAdapterStatic, type LogEntry, type LogLevel, type Logger$1 as Logger, MemoryBlobStorage, type Metadata, type Middleware, type ModelConstraint, type ModelConstraints, type ModelName, type ModelProfile, type ModelStatus, type Module, ModuleAggregator, type ProjectMetadata, type Prompt, PromptAssembler, type PromptBuilder, type PromptBuilderOptions, type PromptSection, Registry, type ResolvedBlob, Result, type Role, type RoleSummary, type SHA256, type Selector, Session, type SessionIndex, SessionManager, SessionModule, type SessionSnapshot, type SessionSummary, type Severity, SnapshotError, type SnapshotErrorKind, type SnapshotTarget, type State, type StateManager, type StateReader, type Store, type StoreKey, type SyncWorkspaceCommand, SystemAuth, SystemError, type SystemPromptAssembler, type Taggable, type Timestamp, type Timestamped, type ToolDefinition, type TransactionStep, type Turn, TurnBuilderFactory, type TurnNode, type TurnProcessor, TurnTree, type URI, type UUID, type Versioned, type WorkspaceCommand, WorkspaceDatabase, type WorkspaceIndex, WorkspaceModule, type WorkspaceSettings, type WorkspaceState, createAnonymousContext, createAuthContext, createError, createLogger, createUserContext, createWorkspace, deepClone, del, logger, merge };
+export { type Action, type ActionEntry, type ActionOutcome, type AgentIndex, AgentModule, type AssemblerExtension, type AuthContext, AuthContextBuilder, type AuthorizationProvider, type Authorizer, BaseStore, type Blob$1 as Blob, type BlobRef, type BlobResolver, type BlobStorage, BlobUtilities, type BootstrapParams, type BootstrappedWorkspace, Bootstrapper, type BranchInfo, Branded, type Command, type CommandCoordinator, type CommandRegistry, CommonErrors, ConsoleLogger, type Content, type ContentCoreState, type ContentDefinition, type ContentFilter, type ContentIndex, type ContentMapper, type ContentMode, ContentModule, ContentRegistry, type ContentRetriever, type ContentSummary, type CreateWorkspaceCommand, type CreateWorkspaceParams, DELETE_SYMBOL, type DatabaseConfig, type DeepPartial, type DomainRegistry, type EffectResult, type Entity, type Event, index as GoogleAdapter, type IKernel, type IRegistry, type IRegistryReader, type IWorkspaceDatabase, type Identifiable, type Index, type IndexedDBBlobConfig, IndexedDBBlobStorage, type InferenceContext, type InferenceResults, type Issue, Kernel, type KernelConfig, LLM, type LLMAdapter, type LLMAdapterStatic, type LogEntry, type LogLevel, type Logger$1 as Logger, MemoryBlobStorage, type Metadata, type Middleware, type ModelConstraint, type ModelConstraints, type ModelName, type ModelProfile, type ModelStatus, type Module, ModuleAggregator, type ProjectMetadata, type Prompt, PromptAssembler, type PromptBuilder, type PromptBuilderOptions, type PromptSection, Registry, type ResolvedBlob, Result, type Role, type RoleSummary, type SHA256, type Selector, Session, type SessionIndex, SessionManager, SessionModule, type SessionSnapshot, type SessionSummary, type Severity, ShortKeyRegistry, type SnapshotTarget, type State, type StateManager, type StateReader, type Store, type StoreKey, type SyncWorkspaceCommand, SystemAuth, SystemError, type SystemPromptAssembler, type Taggable, type Timestamp, type Timestamped, ToolCallRegex, type ToolDefinition, type TransactionStep, type Turn, TurnBuilderFactory, type TurnNode, type TurnProcessor, TurnTree, type URI, type UUID, type Versioned, type WorkspaceCommand, WorkspaceDatabase, type WorkspaceIndex, WorkspaceModule, type WorkspaceSettings, type WorkspaceState, createAnonymousContext, createAuthContext, createError, createLogger, createUserContext, createWorkspace, deepClone, del, logger, merge };