@manifesto-ai/sdk 2.3.0 → 3.1.1

package/dist/index.d.ts

@@ -1,426 +1,16 @@
-import { DomainSchema, Snapshot as Snapshot$1, Patch, Intent, SetPatch, UnsetPatch, MergePatch } from '@manifesto-ai/core';
-export { ComputeResult, Snapshot as CoreSnapshot, DomainSchema, ErrorValue, Intent, MergePatch, Patch, Requirement, SetPatch, TraceGraph, UnsetPatch, createCore, createIntent, createSnapshot } from '@manifesto-ai/core';
-export { HostOptions, HostResult } from '@manifesto-ai/host';
-export { CoordinatorSealGenesisParams, CoordinatorSealNextParams, ExecuteApprovedProposalInput, GovernanceEventDispatcher, GovernedWorldStore, RecoveredWorldRuntimeCompletion, ResumeExecutingProposalInput, SealResult, SealedWorldRuntimeCompletion, WorldConfig, WorldCoordinator, WorldExecutionOptions, WorldExecutionResult, WorldExecutor, WorldInstance, WorldRuntime, WorldRuntimeCompletion, WorldStoreTransaction, createWorld } from '@manifesto-ai/world';
-
 /**
- * SDK package identity and SPEC version metadata.
- * Used for phase tracking and compatibility verification.
- */
-type SdkManifest = {
-    readonly name: '@manifesto-ai/sdk';
-    readonly specVersion: '2.0.0';
-    readonly phase: 'released';
-};
-
-/**
- * SDK Public Types
- *
- * Defines ManifestoInstance, ManifestoConfig, event types, and supporting types.
- *
- * @see SDK SPEC
- * @module
- */
-
-/**
- * Typed Snapshot with generic data shape.
- *
- * Core's Snapshot uses `data: unknown`. This overlay provides type-safe
- * access to domain data via the generic parameter T.
- *
- * The SDK does not add compatibility fields here; it transparently follows the
- * current Core Snapshot surface.
- */
-type Snapshot<T = unknown> = Omit<Snapshot$1, "data"> & {
-    data: T;
-};
-/**
- * Context provided to effect handlers.
- *
- * Simplified from Host's EffectContext (2-param contract).
- */
-type EffectContext<T = unknown> = {
-    /** Current snapshot (read-only). */
-    readonly snapshot: Readonly<Snapshot<T>>;
-};
-/**
- * SDK-level effect handler.
- *
- * Users provide this simplified 2-param handler; SDK adapts it
- * to Host's 3-param EffectHandler internally.
- */
-type EffectHandler = (params: unknown, ctx: EffectContext) => Promise<readonly Patch[]>;
-/**
- * Configuration for createManifesto().
- *
- * @see SDK SPEC v2.0.0
- */
-interface ManifestoConfig<T = unknown> {
-    /**
-     * Required: Domain schema defining state, computed, actions.
-     * Accepts either a compiled DomainSchema or MEL text string.
-     *
-     * @see SDK-CONFIG-1
-     */
-    schema: DomainSchema | string;
-    /**
-     * Required: Effect handlers keyed by effect type.
-     *
-     * @see SDK-CONFIG-2
-     */
-    effects: Record<string, EffectHandler>;
-    /**
-     * Optional: Guard function for intent validation.
-     */
-    guard?: (intent: Intent, snapshot: Snapshot<T>) => boolean;
-    /**
-     * Optional: Restore from persisted snapshot.
-     */
-    snapshot?: Snapshot<T>;
-}
-/**
- * Selector function — projects a value from the typed snapshot.
- */
-type Selector<T, R> = (snapshot: Snapshot<T>) => R;
-/**
- * Unsubscribe function returned by subscribe() and on().
- */
-type Unsubscribe = () => void;
-/**
- * ManifestoInstance — the sole runtime handle returned by createManifesto().
- *
- * 7 methods, no more.
- *
- * @see SDK SPEC v2.0.0
- */
-interface ManifestoInstance<T = unknown> {
-    /**
-     * Fire-and-forget intent dispatch.
-     *
-     * Enqueues the intent for serial processing. Returns immediately.
-     *
-     * @throws DisposedError if instance is disposed (SDK-DISPATCH-4)
-     * @see SDK-DISPATCH-1, SDK-DISPATCH-2, SDK-DISPATCH-3
-     */
-    dispatch(intent: Intent): void;
-    /**
-     * Subscribe to state changes via selector.
-     *
-     * Fires only at terminal snapshot, at most once per intent.
-     *
-     * @see SDK-SUB-1, SDK-SUB-2, SDK-SUB-3, SDK-SUB-4
-     */
-    subscribe<R>(selector: Selector<T, R>, listener: (value: R) => void): Unsubscribe;
-    /**
-     * Listen to intent lifecycle events (telemetry channel).
-     *
-     * Payload type is narrowed by event name.
-     *
-     * @see SDK-EVENT-1, SDK-EVENT-2, SDK-EVENT-3
-     */
-    on<K extends ManifestoEvent>(event: K, handler: (payload: ManifestoEventMap<T>[K]) => void): Unsubscribe;
-    /**
-     * Check whether an action is currently dispatchable against the current snapshot.
-     */
-    isActionAvailable(actionName: string): boolean;
-    /**
-     * Return all action names that are currently dispatchable.
-     */
-    getAvailableActions(): readonly string[];
-    /**
-     * Get the current snapshot synchronously.
-     *
-     * @see SDK-SNAP-1
-     */
-    getSnapshot(): Snapshot<T>;
-    /**
-     * Dispose the instance and release resources.
-     *
-     * @see SDK-DISPOSE-1, SDK-DISPOSE-2, SDK-DISPOSE-3
-     */
-    dispose(): void;
-}
-/**
- * Typed event map — payload narrowed by event name.
- *
- * @see SDK SPEC v1.0.0 §8
- */
-interface ManifestoEventMap<T = unknown> {
-    "dispatch:completed": {
-        intentId: string;
-        intent: Intent;
-        snapshot: Snapshot<T>;
-    };
-    "dispatch:rejected": {
-        intentId: string;
-        intent: Intent;
-        reason: string;
-    };
-    "dispatch:failed": {
-        intentId: string;
-        intent: Intent;
-        error: Error;
-    };
-}
-/**
- * Telemetry event types for the `on()` channel.
- *
- * @see SDK SPEC v1.0.0 §8
- */
-type ManifestoEvent = keyof ManifestoEventMap;
-/**
- * Union of all event payloads (for backward compatibility).
- *
- * Prefer using `ManifestoEventMap<T>[K]` with typed `on()` instead.
- *
- * @see SDK-INV-6 — intentId is always present
- */
-type ManifestoEventPayload<T = unknown> = ManifestoEventMap<T>[ManifestoEvent];
-
-/**
- * createManifesto() Factory
- *
- * The sole SDK-owned concept. Creates a ManifestoInstance for the default
- * direct-dispatch path by composing schema compilation and Host execution into
- * a single handle. Governed World composition remains explicit outside this
- * factory.
- *
- * @see SDK SPEC v1.0.0 §5
- * @see ADR-010
- * @module
- */
-
-/**
- * Create a ManifestoInstance.
- *
- * This is the sole entry point for SDK consumers. It composes the protocol
- * axes required for the default direct-dispatch runtime into a single handle with
- * 7 methods: dispatch, subscribe, on, isActionAvailable,
- * getAvailableActions, getSnapshot, dispose.
- *
- * @see SDK-FACTORY-1 through SDK-FACTORY-5
- * @see SDK-INV-1 through SDK-INV-6
- */
-declare function createManifesto<T = unknown>(config: ManifestoConfig<T>): ManifestoInstance<T>;
-
-/**
- * dispatchAsync() — Non-normative convenience utility
- *
- * Promise-based wrapper around dispatch() + on().
- * Resolves when the intent reaches a terminal state.
- *
- * @see SDK SPEC v1.0.0 §14.3
- * @module
- */
-
-/**
- * Error thrown when an intent is rejected by a guard.
- */
-declare class DispatchRejectedError extends Error {
-    readonly code = "DISPATCH_REJECTED";
-    readonly intentId: string;
-    constructor(intentId: string, reason?: string);
-}
-/**
- * Dispatch an intent and wait for it to complete.
- *
- * - Resolves with the terminal Snapshot on `dispatch:completed`
- * - Rejects with the error on `dispatch:failed`
- * - Rejects with DispatchRejectedError on `dispatch:rejected`
- *
- * This is a convenience utility derived entirely from `dispatch` + `on`.
- * It does NOT violate the "one owned concept" rule.
- *
- * @see SDK SPEC v1.0.0 §14.3
- */
-declare function dispatchAsync<T = unknown>(instance: ManifestoInstance<T>, intent: Intent): Promise<Snapshot<T>>;
-
-/**
- * SDK v1.0.0 Error Types
- *
- * @see SDK SPEC v1.0.0 §12
- * @see SDK-ERR-1, SDK-ERR-2, SDK-ERR-3
- * @module
- */
-/**
- * Base error for all SDK errors.
- *
- * @see SDK-ERR-1
- */
-declare class ManifestoError extends Error {
-    readonly code: string;
-    constructor(code: string, message: string, options?: ErrorOptions);
-}
-/**
- * Thrown when user effects attempt to override reserved effect types (e.g. system.get).
- *
- * @see SDK-ERR-2, SDK-INV-4
- */
-declare class ReservedEffectError extends ManifestoError {
-    readonly effectType: string;
-    constructor(effectType: string);
-}
-/**
- * Thrown when MEL compilation fails. Exposes full diagnostic info.
- *
- * @see SDK-ERR-4
- */
-declare class CompileError extends ManifestoError {
-    readonly diagnostics: readonly CompileDiagnostic[];
-    constructor(diagnostics: readonly CompileDiagnostic[], formattedMessage: string);
-}
-/**
- * Minimal diagnostic shape exposed by SDK.
- * Matches @manifesto-ai/compiler Diagnostic but avoids hard dependency.
- */
-interface CompileDiagnostic {
-    readonly severity: "error" | "warning" | "info";
-    readonly code: string;
-    readonly message: string;
-    readonly location: {
-        readonly start: {
-            readonly line: number;
-            readonly column: number;
-            readonly offset: number;
-        };
-        readonly end: {
-            readonly line: number;
-            readonly column: number;
-            readonly offset: number;
-        };
-    };
-    readonly source?: string;
-    readonly suggestion?: string;
-}
-/**
- * Thrown when dispatch is called on a disposed instance.
- *
- * @see SDK-ERR-3, SDK-DISPATCH-4
- */
-declare class DisposedError extends ManifestoError {
-    constructor();
-}
-
-/**
- * Depth counter for recursive type operations.
- * Prevents infinite recursion in TypeScript's type system.
- *
- * Usage: Prev[4] = 3, Prev[3] = 2, ... Prev[0] = never
- */
-type Prev = [never, 0, 1, 2, 3, 4];
-/**
- * Extract all valid dot-separated paths from a data type.
- *
- * - Object keys become path segments
- * - Nested objects generate dot-separated paths (e.g. "user.name")
- * - Arrays, primitives, and Record<string, T> are leaf nodes
- *   (Record sub-paths are not supported by Core's path resolution)
- * - Limited to 3 levels of nesting to avoid TS recursion limits
- *   (root key + 3 nested levels = max 4 path segments)
- *
- * @example
- * type State = { user: { name: string; age: number }; count: number };
- * type P = DataPaths<State>;
- * // "user" | "user.name" | "user.age" | "count"
- */
-type DataPaths<T, D extends number = 3> = [D] extends [never] ? never : T extends Record<string, unknown> ? T extends unknown[] ? never : {
-    [K in keyof T & string]: K | (NonNullable<T[K]> extends Record<string, unknown> ? NonNullable<T[K]> extends unknown[] ? never : string extends keyof NonNullable<T[K]> ? never : `${K}.${DataPaths<NonNullable<T[K]>, Prev[D]>}` : never);
-}[keyof T & string] : never;
-/**
- * Resolve the value type at a dot-separated path.
- *
- * @example
- * type State = { user: { name: string } };
- * type V = ValueAt<State, "user.name">; // string
- * type U = ValueAt<State, "user">;      // { name: string }
- */
-type ValueAt<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? ValueAt<NonNullable<T[K]>, Rest> : never : P extends keyof T ? T[P] : never;
-/**
- * Paths that resolve to plain object types (valid targets for merge).
- * Arrays and primitives are excluded since merge performs shallow object merge.
- *
- * @example
- * type State = { user: { name: string }; tags: string[]; count: number };
- * type M = ObjectPaths<State>;
- * // "user" (tags and count excluded - not plain objects)
- */
-type ObjectPaths<T, D extends number = 3> = [D] extends [never] ? never : T extends Record<string, unknown> ? T extends unknown[] ? never : {
-    [K in keyof T & string]: (NonNullable<T[K]> extends Record<string, unknown> ? NonNullable<T[K]> extends unknown[] ? never : K : never) | (NonNullable<T[K]> extends Record<string, unknown> ? NonNullable<T[K]> extends unknown[] ? never : string extends keyof NonNullable<T[K]> ? never : `${K}.${ObjectPaths<NonNullable<T[K]>, Prev[D]>}` : never);
-}[keyof T & string] : never;
-/**
- * Type-safe patch operations builder.
- *
- * Provides IDE autocomplete for state paths and compile-time type checking
- * for patch values. All methods return standard Patch objects compatible
- * with Core's apply() function.
- * System mutation convenience APIs are intentionally excluded.
- *
- * @typeParam TData - The shape of domain state (snapshot.data)
- */
-interface TypedOps<TData extends Record<string, unknown>> {
-    /**
-     * Create a set patch — replace value at path (create if missing).
-     *
-     * @example
-     * ops.set('count', 5);
-     * ops.set('user.name', 'Alice');
-     */
-    set<P extends DataPaths<TData>>(path: P, value: Exclude<ValueAt<TData, P>, undefined>): SetPatch;
-    /**
-     * Create an unset patch — remove property at path.
-     *
-     * @example
-     * ops.unset('temporaryField');
-     */
-    unset<P extends DataPaths<TData>>(path: P): UnsetPatch;
-    /**
-     * Create a merge patch — shallow merge at object path.
-     * Only valid for paths that resolve to plain object types.
-     *
-     * @example
-     * ops.merge('user', { name: 'Bob' });
-     */
-    merge<P extends ObjectPaths<TData>>(path: P, value: {
-        [K in keyof ValueAt<TData, P>]?: Exclude<ValueAt<TData, P>[K], undefined>;
-    }): MergePatch;
-    /**
-     * Raw (untyped) patch creation — escape hatch for dynamic paths
-     * or platform namespace ($*) targets.
-     */
-    raw: {
-        set(path: string, value: unknown): SetPatch;
-        unset(path: string): UnsetPatch;
-        merge(path: string, value: Record<string, unknown>): MergePatch;
-    };
-}
-/**
- * Create a type-safe patch operations builder.
- *
- * Injects the domain state type to enable:
- * - IDE autocomplete on all valid state paths
- * - Compile-time type checking of patch values
- * - Merge restricted to object-typed paths
- *
- * @typeParam TData - The shape of domain state (snapshot.data)
- *
- * @example
- * type State = {
- *   count: number;
- *   user: { name: string; age: number };
- *   tags: string[];
- * };
- *
- * const ops = defineOps<State>();
+ * @manifesto-ai/sdk v3.0.0
  *
- * ops.set('count', 5);              // OK — value: number
- * ops.set('user.name', 'Alice');    // OK — value: string
- * ops.set('count', 'hello');        // TS error — expected number
- * ops.merge('user', { name: 'B' }); // OK — partial object merge
- * ops.unset('tags');                // OK
+ * SDK hard cut around the activation boundary.
  *
- * // Escape hatch for dynamic / platform paths
- * ops.raw.set('$host.custom', { key: 'value' });
+ * @see sdk-SPEC-v3.0.0-draft.md
+ * @see ADR-017
+ * @packageDocumentation
  */
-declare function defineOps<TData extends Record<string, unknown>>(): TypedOps<TData>;
-
-export { type CompileDiagnostic, CompileError, type DataPaths, DispatchRejectedError, DisposedError, type EffectContext, type EffectHandler, type ManifestoConfig, ManifestoError, type ManifestoEvent, type ManifestoEventMap, type ManifestoEventPayload, type ManifestoInstance, type ObjectPaths, ReservedEffectError, type SdkManifest, type Selector, type Snapshot, type TypedOps, type Unsubscribe, type ValueAt, createManifesto, defineOps, dispatchAsync };
+export type { SdkManifest } from "./manifest.js";
+export { createManifesto } from "./create-manifesto.js";
+export type { ActivatedInstance, ActionArgs, BaseLaws, BaseComposableLaws, ComposableManifesto, ComputedRef, EffectContext, EffectHandler, FieldRef, GovernedComposableLaws, GovernanceLaws, LineageComposableLaws, LineageLaws, ManifestoBaseInstance, ManifestoDecoratedRuntimeByLaws, ManifestoDomainShape, ManifestoEvent, ManifestoEventMap, ManifestoEventPayload, ManifestoRuntimeByLaws, Selector, Snapshot, TypedActionRef, TypedCommitAsync, TypedCreateIntent, TypedDispatchAsync, TypedMEL, TypedOn, TypedSubscribe, Unsubscribe, } from "./types.js";
+export { AlreadyActivatedError, CompileError, DisposedError, ManifestoError, ReservedEffectError, } from "./errors.js";
+export type { CompileDiagnostic } from "./errors.js";
+export type { DomainSchema, Intent, Patch, Snapshot as CoreSnapshot, } from "@manifesto-ai/core";
+export { createSnapshot } from "@manifesto-ai/core";