@manifesto-ai/sdk 1.2.0 → 2.0.0

package/README.md

@@ -1,27 +1,27 @@
 # @manifesto-ai/sdk
 
-> **SDK** is the canonical public developer API for Manifesto applications.
+> Thin public composition layer for the Manifesto protocol stack.
 
 ---
 
 ## Overview
 
-SDK owns the public contract for app creation and interaction.
-It provides `createApp()`, `createTestApp()`, `ManifestoApp`, and the hook primitives while delegating orchestration to Runtime.
+`@manifesto-ai/sdk` is the canonical entry point for new Manifesto integrations.
 
 ```text
 Application Code
       |
       v
-SDK (createApp, App, Hooks)
+SDK (createManifesto, defineOps, re-exports)
       |
       v
-Runtime (orchestration)
-      |
-      v
-Core / Host / World
+Compiler / Host / Core
+      +
+optional World integration
 ```
 
+The SDK owns exactly one concept: `createManifesto()`. Everything else is either a small SDK utility (`defineOps`) or a re-export from protocol packages. Legacy app-package facade APIs are retired in v1.0.0. Governance and lineage remain explicit integrations through `@manifesto-ai/world`.
+
 ---
 
 ## Installation
@@ -35,42 +35,61 @@ pnpm add @manifesto-ai/sdk
 ## Quick Example
 
 ```typescript
-import { createApp } from "@manifesto-ai/sdk";
+import { createManifesto, createIntent } from "@manifesto-ai/sdk";
 
-const app = createApp({
+const manifesto = createManifesto({
   schema: counterSchema,
-  effects: {
-    "api.save": async (params) => [
-      { op: "set", path: "data.savedAt", value: params.timestamp },
-    ],
-  },
+  effects: {},
 });
 
-await app.ready();
-await app.act("increment").done();
-console.log(app.getState().data.count);
+manifesto.on("dispatch:completed", ({ snapshot }) => {
+  console.log(snapshot?.data.count);
+});
+
+manifesto.dispatch(createIntent("increment", "intent-1"));
 ```
 
 ---
 
 ## Main Exports
 
-### Factory
+### SDK-Owned
+
+```typescript
+function createManifesto(config: ManifestoConfig): ManifestoInstance;
+function defineOps<TData>(): TypedOps<TData>;
+```
+
+### ManifestoInstance
 
 ```typescript
-function createApp(config: AppConfig): App;
-function createTestApp(domain: DomainSchema | string, opts?: Partial<AppConfig>): App;
+interface ManifestoInstance {
+  dispatch(intent: Intent): void;
+  subscribe(selector, listener): Unsubscribe;
+  on(event, handler): Unsubscribe;
+  getSnapshot(): Snapshot;
+  dispose(): void;
+}
 ```
 
-### Class
+### Event Channel
 
 ```typescript
-class ManifestoApp implements App { /* ... */ }
+type ManifestoEvent =
+  | "dispatch:completed"
+  | "dispatch:rejected"
+  | "dispatch:failed";
 ```
 
-### Runtime-Reexported Public Types/Errors
+`dispatch()` is enqueue-only. Observe results through `subscribe()` for state changes or `on()` for per-intent telemetry.
 
-SDK re-exports public contract types and errors (for example `AppConfig`, `AppState`, `ActionHandle`, `AppNotReadyError`).
+### Re-Exported Protocol Surface
+
+SDK re-exports selected protocol types and factories from:
+
+- `@manifesto-ai/core`
+- `@manifesto-ai/world`
+- `@manifesto-ai/host` (types)
 
 ---
 
@@ -78,27 +97,34 @@ SDK re-exports public contract types and errors (for example `AppConfig`, `AppSt
 
 | Relationship | Package | How |
 |--------------|---------|-----|
-| Delegates to | `@manifesto-ai/runtime` | All orchestration via runtime pipeline |
 | Uses | `@manifesto-ai/core` | Schema and expression types |
-| Uses | `@manifesto-ai/world` | World protocol types |
-| Legacy predecessor | App facade package | Removed in R2 (see API retirement record) |
+| Uses | `@manifesto-ai/host` | Effect execution and compute loop |
+| Re-exports | `@manifesto-ai/world` | World protocol types and store factory for explicit governance integration |
+| Uses | `@manifesto-ai/compiler` | MEL → DomainSchema compilation |
+| Retired predecessor | `@manifesto-ai/runtime` | Absorbed into `createManifesto()` per ADR-010 |
 
 ---
 
-## Migration from Legacy App Facade
+## Migration Notes
+
+Older app-package code usually maps to three current patterns:
 
-Legacy app-facade imports should be replaced with `@manifesto-ai/sdk`.
+- use `createManifesto({ schema, effects })` as the public entry point
+- create intents explicitly with `createIntent(...)`
+- treat `dispatch()` as enqueue-only and observe completion through `dispatch:*` events or a small `dispatchAsync()` helper
 
-For automated rewrite guidance, see:
-- [docs/guides/migrate-app-to-sdk.md](../../docs/guides/migrate-app-to-sdk.md)
+For migration details, see:
+- [Migrate App to SDK](../../docs/guides/migrate-app-to-sdk.md)
+- [sdk-SPEC-v1.0.0.md](docs/sdk-SPEC-v1.0.0.md)
+- [ADR-010](../../docs/internals/adr/010-major-hard-cut.md)
 
 ---
 
 ## Documentation
 
-- [sdk-SPEC-v0.1.0.md](docs/sdk-SPEC-v0.1.0.md)
+- [sdk-SPEC-v1.0.0.md](docs/sdk-SPEC-v1.0.0.md)
 - [VERSION-INDEX.md](docs/VERSION-INDEX.md)
-- [ADR-008](../../docs/internals/adr/008-sdk-first-transition-and-app-retirement.md)
+- [ADR-010](../../docs/internals/adr/010-major-hard-cut.md)
 
 ---
 

package/dist/index.d.ts

@@ -1,21 +1,414 @@
+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 { WorldStore, createMemoryWorldStore } from '@manifesto-ai/world';
+
 /**
- * @manifesto-ai/sdk v1.0.0
- *
- * Public developer API layer for the Manifesto protocol stack.
- * Canonical entry point since Phase 2 (ADR-008).
- *
- * @see sdk-SPEC-v0.1.0.md
- * @packageDocumentation
- */
-export type { SdkManifest } from './manifest.js';
-export type { AppStatus, RuntimeKind, Unsubscribe, ActionPhase, ActionResult, CompletedActionResult, RejectedActionResult, FailedActionResult, PreparationFailedActionResult, ExecutionStats, ActionUpdate, ActionUpdateDetail, ActorPolicyConfig, SystemActionsConfig, DisposeOptions, DoneOptions, ActOptions, ForkOptions, SessionOptions, SubscribeOptions, LineageOptions, AppState, SystemState, SnapshotMeta, MemoryHubConfig, BackfillConfig, RecallRequest, RecallResult, MemoryMaintenanceOptions, MigrationLink, MigrationContext, MigrationFn, App, ActionHandle, Branch, Session, MemoryFacade, SystemFacade, SystemMemoryFacade, Hookable, HookContext, EnqueueOptions, AppPlugin, AppHooks, MemoryProvider, MemoryVerifier, MemoryIngestEntry, MemorySelectionView, ProveResult, Requirement, AppConfig, AppRef, Proposal, ProposalResult, ExecutionKey, ExecutionKeyPolicy, ProposalId, ActorId, BranchId, ApprovedScope, AuthorityDecision, PolicyService, ArtifactRef, Intent, SchemaCompatibilityResult, MemoryStore, StoredMemoryRecord, MemoryRecordInput, MemoryFilter, World, WorldId, Snapshot, Patch, WorldHead, Effects, AppEffectContext, EffectHandler, ErrorValue, MelText, } from '@manifesto-ai/runtime';
-export { ManifestoAppError, AppNotReadyError, AppDisposedError, ActionRejectedError, ActionFailedError, ActionPreparationError, ActionTimeoutError, ActionNotFoundError, HandleDetachedError, HookMutationError, ReservedEffectTypeError, SystemActionDisabledError, SystemActionRoutingError, MemoryDisabledError, BranchNotFoundError, WorldNotFoundError, WorldSchemaHashMismatchError, WorldNotInLineageError, ReservedNamespaceError, MissingDefaultActorError, DomainCompileError, PluginInitError, SchemaMismatchOnResumeError, BranchHeadNotFoundError, } from '@manifesto-ai/runtime';
-export { createApp, createTestApp } from './create-app.js';
-export { ManifestoApp } from './app.js';
-export { AppRefImpl, createAppRef } from './hooks/index.js';
-export type { AppRefCallbacks } from './hooks/index.js';
-export { HookableImpl } from './hooks/index.js';
-export type { HookState } from './hooks/index.js';
-export { JobQueue } from './hooks/index.js';
-export { HookContextImpl, createHookContext } from './hooks/index.js';
-//# sourceMappingURL=index.d.ts.map
+ * SDK package identity and SPEC version metadata.
+ * Used for phase tracking and compatibility verification.
+ */
+type SdkManifest = {
+    readonly name: '@manifesto-ai/sdk';
+    readonly specVersion: '1.0.0';
+    readonly phase: 'released';
+};
+
+/**
+ * SDK v1.0.0 Public Types
+ *
+ * Defines ManifestoInstance, ManifestoConfig, event types, and supporting types.
+ *
+ * @see SDK SPEC v1.0.0 §6–8
+ * @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.
+ *
+ * @see SDK SPEC v1.0.0 §6.1
+ */
+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 v1.0.0 §7
+ */
+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().
+ *
+ * 5 methods, no more.
+ *
+ * @see SDK SPEC v1.0.0 §6
+ */
+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;
+    /**
+     * 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 that composes
+ * the four protocol axes (Core, Host, World, Compiler) into a single handle.
+ *
+ * @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 (Core via Host, Host, World, Compiler) into a single handle with
+ * 5 methods: dispatch, subscribe, on, 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>();
+ *
+ * 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
+ *
+ * // Escape hatch for dynamic / platform paths
+ * ops.raw.set('$host.custom', { key: 'value' });
+ */
+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 };