@manifesto-ai/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Manifesto AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,182 @@
+# @manifesto-ai/sdk
+
+> **SDK** is the public developer API layer for Manifesto applications. It presents ergonomic factory functions, lifecycle management, and hook systems while delegating all execution to the Runtime.
+
+> **Phase 1 Notice:** During the current phase, most users should install `@manifesto-ai/app`, which re-exports all SDK APIs. See [ADR-007](../../docs/internals/adr/007-sdk-runtime-split-kickoff.md) for details.
+
+---
+
+## What is SDK?
+
+SDK owns the public contract shape that developers interact with. It provides `createApp()`, the `App` interface, and the hook system — but delegates all orchestration to `@manifesto-ai/runtime`.
+
+```
+Application Code
+      |
+      v
+    SDK (createApp, App, Hooks)       <-- you are here
+      |
+      v
+    Runtime (orchestration, execution)
+      |
+      v
+    Core / Host / World
+```
+
+---
+
+## What SDK Does
+
+| Responsibility | Description |
+|----------------|-------------|
+| App factory | `createApp(config)` — single entry point for creating apps |
+| App interface | `ManifestoApp` — thin facade over Runtime |
+| Lifecycle | `ready()` / `dispose()` with status tracking |
+| Hook system | Observable lifecycle with re-entrancy guards |
+| AppRef | Read-only facade for safe hook access |
+| Job queue | Deferred execution for hook-triggered actions |
+| Test helper | `createTestApp()` — minimal app for testing |
+
+---
+
+## What SDK Does NOT Do
+
+| NOT Responsible For | Who Is |
+|--------------------|--------|
+| Execution orchestration | Runtime |
+| Effect execution | Host (via Runtime) |
+| Pure state computation | Core (via Runtime) |
+| Governance and lineage | World (via Runtime) |
+| Type/error definitions | Runtime |
+
+---
+
+## Installation
+
+During **Phase 1**, use `@manifesto-ai/app` as the canonical entry point:
+
+```bash
+pnpm add @manifesto-ai/app
+```
+
+For direct SDK access (preview):
+
+```bash
+pnpm add @manifesto-ai/sdk
+```
+
+---
+
+## Quick Example
+
+```typescript
+import { createApp } from "@manifesto-ai/sdk";
+
+const app = createApp({
+  schema: counterSchema,
+  effects: {
+    "api.save": async (params, ctx) => [
+      { op: "set", path: "data.savedAt", value: params.timestamp },
+    ],
+  },
+});
+
+await app.ready();
+
+const handle = app.act("increment");
+await handle.completed();
+
+console.log(app.getState().data.count); // 1
+```
+
+---
+
+## Core API
+
+### Factory Functions
+
+```typescript
+function createApp(config: AppConfig): App;
+function createTestApp(domain: DomainSchema | string, opts?: Partial<AppConfig>): App;
+```
+
+### App Interface
+
+```typescript
+interface App {
+  // Lifecycle
+  ready(): Promise<void>;
+  dispose(opts?): Promise<void>;
+  readonly status: AppStatus;
+  readonly hooks: Hookable<AppHooks>;
+
+  // Schema
+  getDomainSchema(): DomainSchema;
+
+  // Actions
+  act(type: string, input?: unknown, opts?): ActionHandle;
+  submitProposal(proposal): Promise<ProposalResult>;
+
+  // State
+  getState<T>(): AppState<T>;
+  subscribe(selector, listener, opts?): () => void;
+  getSnapshot(): Snapshot;
+
+  // Session
+  session(actorId: string, opts?): Session;
+
+  // Branch
+  currentBranch(): Branch;
+  listBranches(): Branch[];
+  switchBranch(branchId): Promise<void>;
+  fork(opts?): Promise<Branch>;
+
+  // World Query
+  getCurrentHead(): WorldId;
+  getWorld(worldId?): World;
+}
+```
+
+> See [sdk-SPEC-v0.1.0.md](docs/sdk-SPEC-v0.1.0.md) for the complete specification.
+
+---
+
+## Relationship with Other Packages
+
+```
+App (facade) -> SDK -> Runtime -> Core / Host / World
+```
+
+| Relationship | Package | How |
+|--------------|---------|-----|
+| Re-exported by | `@manifesto-ai/app` | App re-exports createApp, createTestApp, hooks |
+| Delegates to | `@manifesto-ai/runtime` | All orchestration via AppRuntime |
+| Depends on | `@manifesto-ai/core` | Schema types |
+| Depends on | `@manifesto-ai/world` | World types |
+
+---
+
+## When to Use SDK Directly
+
+**Most users should use `@manifesto-ai/app` during Phase 1.**
+
+Use SDK directly when:
+- Building custom integrations that need only the public API surface
+- Creating framework-specific wrappers (React, Vue, etc.)
+- After Phase 2 transition when SDK becomes the primary entry point
+
+---
+
+## Documentation
+
+| Document | Purpose |
+|----------|---------|
+| [sdk-SPEC-v0.1.0.md](docs/sdk-SPEC-v0.1.0.md) | Complete specification |
+| [VERSION-INDEX.md](docs/VERSION-INDEX.md) | Version history and reading guide |
+| [ADR-007](../../docs/internals/adr/007-sdk-runtime-split-kickoff.md) | Split rationale |
+
+---
+
+## License
+
+[MIT](../../LICENSE)

package/dist/__tests__/bootstrap.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bootstrap.test.d.ts.map

package/dist/__tests__/bootstrap.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/bootstrap.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/bootstrap.test.js

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+describe('@manifesto-ai/sdk bootstrap', () => {
+    it('SdkManifest type is importable and structurally correct', () => {
+        // Type-level verification: the manifest type constrains to expected shape
+        const manifest = {
+            name: '@manifesto-ai/sdk',
+            specVersion: '0.1.0',
+            phase: 'bootstrap',
+        };
+        expect(manifest.name).toBe('@manifesto-ai/sdk');
+        expect(manifest.specVersion).toBe('0.1.0');
+        expect(manifest.phase).toBe('bootstrap');
+    });
+    it('package entry point resolves without error', async () => {
+        const mod = await import('../index.js');
+        expect(mod).toBeDefined();
+    });
+    it('exports SDK components', async () => {
+        const mod = await import('../index.js');
+        // App Factory
+        expect(mod.createApp).toBeDefined();
+        expect(mod.createTestApp).toBeDefined();
+        // ManifestoApp
+        expect(mod.ManifestoApp).toBeDefined();
+        // Hooks
+        expect(mod.AppRefImpl).toBeDefined();
+        expect(mod.createAppRef).toBeDefined();
+        expect(mod.HookableImpl).toBeDefined();
+        expect(mod.JobQueue).toBeDefined();
+        expect(mod.HookContextImpl).toBeDefined();
+        expect(mod.createHookContext).toBeDefined();
+    });
+});
+//# sourceMappingURL=bootstrap.test.js.map

package/dist/__tests__/bootstrap.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.test.js","sourceRoot":"","sources":["../../src/__tests__/bootstrap.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAG9C,QAAQ,CAAC,6BAA6B,EAAE,GAAG,EAAE;IAC3C,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;QACjE,0EAA0E;QAC1E,MAAM,QAAQ,GAAgB;YAC5B,IAAI,EAAE,mBAAmB;YACzB,WAAW,EAAE,OAAO;YACpB,KAAK,EAAE,WAAW;SACnB,CAAC;QAEF,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAChD,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3C,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,KAAK,IAAI,EAAE;QAC1D,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;QACxC,MAAM,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IAC5B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wBAAwB,EAAE,KAAK,IAAI,EAAE;QACtC,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;QAExC,cAAc;QACd,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;QACpC,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,WAAW,EAAE,CAAC;QAExC,eAAe;QACf,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,WAAW,EAAE,CAAC;QAEvC,QAAQ;QACR,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,WAAW,EAAE,CAAC;QACvC,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,WAAW,EAAE,CAAC;QACvC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;QACnC,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,WAAW,EAAE,CAAC;QAC1C,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,WAAW,EAAE,CAAC;IAC9C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/app.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Manifesto App Implementation (Thin Facade)
+ *
+ * Delegates all operations to AppBootstrap (assembly) and AppRuntime (operations).
+ *
+ * @see ADR-004 Phase 4 — FACADE-1~5
+ * @see SPEC §5-6
+ * @module
+ */
+import type { DomainSchema, Snapshot } from "@manifesto-ai/core";
+import type { App, ActionHandle, ActOptions, AppConfig, AppHooks, AppState, AppStatus, Branch, DisposeOptions, ForkOptions, Hookable, MemoryFacade, MigrationLink, Proposal, ProposalResult, Session, SessionOptions, SubscribeOptions, SystemFacade, Unsubscribe, World, WorldStore } from "@manifesto-ai/runtime";
+import type { WorldId, WorldHead } from "@manifesto-ai/world";
+/**
+ * Manifesto App — Thin Facade (FACADE-1~5)
+ *
+ * Only contains lifecycle management and delegation to AppRuntime.
+ *
+ * @see ADR-004 Phase 4
+ */
+export declare class ManifestoApp implements App {
+    private _lifecycleManager;
+    private _bootstrap;
+    private _runtime;
+    constructor(config: AppConfig, worldStore: WorldStore);
+    get status(): AppStatus;
+    get hooks(): Hookable<AppHooks>;
+    ready(): Promise<void>;
+    dispose(opts?: DisposeOptions): Promise<void>;
+    getDomainSchema(): DomainSchema;
+    currentBranch(): Branch;
+    listBranches(): readonly Branch[];
+    switchBranch(branchId: string): Promise<Branch>;
+    fork(opts?: ForkOptions): Promise<Branch>;
+    act(type: string, input?: unknown, opts?: ActOptions): ActionHandle;
+    getActionHandle(proposalId: string): ActionHandle;
+    session(actorId: string, opts?: SessionOptions): Session;
+    getState<T = unknown>(): AppState<T>;
+    subscribe<TSelected>(selector: (state: AppState<unknown>) => TSelected, listener: (selected: TSelected) => void, opts?: SubscribeOptions<TSelected>): Unsubscribe;
+    get system(): SystemFacade;
+    get memory(): MemoryFacade;
+    getMigrationLinks(): readonly MigrationLink[];
+    getCurrentHead(): WorldId;
+    getSnapshot<T = unknown>(): AppState<T>;
+    getSnapshot(worldId: WorldId): Promise<Snapshot>;
+    getWorld(worldId: WorldId): Promise<World>;
+    getHeads(): Promise<WorldHead[]>;
+    getLatestHead(): Promise<WorldHead | null>;
+    submitProposal(proposal: Proposal): Promise<ProposalResult>;
+    private _getRuntime;
+}
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,KAAK,EACV,GAAG,EACH,YAAY,EACZ,UAAU,EACV,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,MAAM,EACN,cAAc,EACd,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,aAAa,EAEb,QAAQ,EACR,cAAc,EACd,OAAO,EACP,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,KAAK,EACL,UAAU,EACX,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAqB9D;;;;;;GAMG;AACH,qBAAa,YAAa,YAAW,GAAG;IACtC,OAAO,CAAC,iBAAiB,CAAmB;IAC5C,OAAO,CAAC,UAAU,CAAe;IACjC,OAAO,CAAC,QAAQ,CAA2B;gBAE/B,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU;IAmCrD,IAAI,MAAM,IAAI,SAAS,CAEtB;IAED,IAAI,KAAK,IAAI,QAAQ,CAAC,QAAQ,CAAC,CAE9B;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAyBtB,OAAO,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BnD,eAAe,IAAI,YAAY;IAa/B,aAAa,IAAI,MAAM;IAIvB,YAAY,IAAI,SAAS,MAAM,EAAE;IAI3B,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI/C,IAAI,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAI/C,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,YAAY;IAInE,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY;IAIjD,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO;IAIxD,QAAQ,CAAC,CAAC,GAAG,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC;IAIpC,SAAS,CAAC,SAAS,EACjB,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,KAAK,SAAS,EACjD,QAAQ,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,IAAI,EACvC,IAAI,CAAC,EAAE,gBAAgB,CAAC,SAAS,CAAC,GACjC,WAAW;IAId,IAAI,MAAM,IAAI,YAAY,CAEzB;IAED,IAAI,MAAM,IAAI,YAAY,CAEzB;IAED,iBAAiB,IAAI,SAAS,aAAa,EAAE;IAI7C,cAAc,IAAI,OAAO;IAIzB,WAAW,CAAC,CAAC,GAAG,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC;IACvC,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;IAQ1C,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC;IAI1C,QAAQ,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAIhC,aAAa,IAAI,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAI1C,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC;IAQjE,OAAO,CAAC,WAAW;CAIpB"}

package/dist/app.js

@@ -0,0 +1,170 @@
+/**
+ * Manifesto App Implementation (Thin Facade)
+ *
+ * Delegates all operations to AppBootstrap (assembly) and AppRuntime (operations).
+ *
+ * @see ADR-004 Phase 4 — FACADE-1~5
+ * @see SPEC §5-6
+ * @module
+ */
+import { AppDisposedError, AppBootstrap, createActionQueue, createLivenessGuard, createProposalManager, createLifecycleManager, createSchemaManager, createWorldHeadTracker, SubscriptionStore, createDefaultPolicyService, createSilentPolicyService, } from "@manifesto-ai/runtime";
+// =============================================================================
+// ManifestoApp Implementation (Thin Facade)
+// =============================================================================
+/**
+ * Manifesto App — Thin Facade (FACADE-1~5)
+ *
+ * Only contains lifecycle management and delegation to AppRuntime.
+ *
+ * @see ADR-004 Phase 4
+ */
+export class ManifestoApp {
+    _lifecycleManager;
+    _bootstrap;
+    _runtime = null;
+    constructor(config, worldStore) {
+        this._lifecycleManager = createLifecycleManager();
+        // PolicyService: use provided or create default
+        let policyService;
+        if (config.policyService) {
+            policyService = config.policyService;
+        }
+        else {
+            const isTest = typeof globalThis !== "undefined" &&
+                globalThis.process?.env?.NODE_ENV === "test";
+            policyService = isTest
+                ? createSilentPolicyService(config.executionKeyPolicy)
+                : createDefaultPolicyService({ executionKeyPolicy: config.executionKeyPolicy });
+        }
+        this._bootstrap = new AppBootstrap({
+            config,
+            worldStore,
+            policyService,
+            lifecycleManager: this._lifecycleManager,
+            schemaManager: createSchemaManager(config.schema),
+            proposalManager: createProposalManager(),
+            actionQueue: createActionQueue(),
+            livenessGuard: createLivenessGuard(),
+            worldHeadTracker: createWorldHeadTracker(),
+            subscriptionStore: new SubscriptionStore(),
+            effects: config.effects,
+        });
+    }
+    // ===========================================================================
+    // Lifecycle
+    // ===========================================================================
+    get status() {
+        return this._lifecycleManager.status;
+    }
+    get hooks() {
+        return this._lifecycleManager.hooks;
+    }
+    async ready() {
+        if (this._lifecycleManager.status === "ready") {
+            return;
+        }
+        if (this._lifecycleManager.isDisposed()) {
+            throw new AppDisposedError("ready");
+        }
+        // Bootstrap assembles all components (steps 1-10)
+        this._runtime = await this._bootstrap.assemble(this);
+        // Initialize plugins (after _runtime is set so plugins can access app APIs)
+        await this._bootstrap.initializePlugins(this);
+        // Mark as ready
+        this._lifecycleManager.transitionTo("ready");
+        // Emit app:ready
+        await this._lifecycleManager.emitHook("app:ready", this._lifecycleManager.createHookContext());
+    }
+    async dispose(opts) {
+        if (this._lifecycleManager.status === "disposed") {
+            return;
+        }
+        if (this._lifecycleManager.status === "disposing") {
+            return;
+        }
+        this._lifecycleManager.transitionTo("disposing");
+        await this._lifecycleManager.emitHook("app:dispose:before", this._lifecycleManager.createHookContext());
+        this._lifecycleManager.transitionTo("disposed");
+        await this._lifecycleManager.emitHook("app:dispose", this._lifecycleManager.createHookContext());
+    }
+    // ===========================================================================
+    // Public API — all delegation to _getRuntime()
+    // ===========================================================================
+    getDomainSchema() {
+        if (this._lifecycleManager.isDisposed()) {
+            throw new AppDisposedError("getDomainSchema");
+        }
+        // Special case: getDomainSchema is accessible during plugin initialization
+        // (status is "created" but _runtime is already assembled).
+        // Original code checked schemaManager.isResolved instead of ensureReady().
+        if (this._runtime) {
+            return this._runtime.getDomainSchema();
+        }
+        return this._getRuntime("getDomainSchema").getDomainSchema();
+    }
+    currentBranch() {
+        return this._getRuntime("currentBranch").currentBranch();
+    }
+    listBranches() {
+        return this._getRuntime("listBranches").listBranches();
+    }
+    async switchBranch(branchId) {
+        return this._getRuntime("switchBranch").switchBranch(branchId);
+    }
+    async fork(opts) {
+        return this._getRuntime("fork").fork(opts);
+    }
+    act(type, input, opts) {
+        return this._getRuntime("act").act(type, input, opts);
+    }
+    getActionHandle(proposalId) {
+        return this._getRuntime("getActionHandle").getActionHandle(proposalId);
+    }
+    session(actorId, opts) {
+        return this._getRuntime("session").session(actorId, opts);
+    }
+    getState() {
+        return this._getRuntime("getState").getState();
+    }
+    subscribe(selector, listener, opts) {
+        return this._getRuntime("subscribe").subscribe(selector, listener, opts);
+    }
+    get system() {
+        return this._getRuntime("system").system;
+    }
+    get memory() {
+        return this._getRuntime("memory").memory;
+    }
+    getMigrationLinks() {
+        return this._getRuntime("getMigrationLinks").getMigrationLinks();
+    }
+    getCurrentHead() {
+        return this._getRuntime("getCurrentHead").getCurrentHead();
+    }
+    getSnapshot(worldId) {
+        if (worldId !== undefined) {
+            return this._getRuntime("getSnapshot").getSnapshot(worldId);
+        }
+        return this._getRuntime("getSnapshot").getState();
+    }
+    async getWorld(worldId) {
+        return this._getRuntime("getWorld").getWorld(worldId);
+    }
+    async getHeads() {
+        return this._getRuntime("getHeads").getHeads();
+    }
+    async getLatestHead() {
+        return this._getRuntime("getLatestHead").getLatestHead();
+    }
+    async submitProposal(proposal) {
+        return this._getRuntime("submitProposal").submitProposal(proposal);
+    }
+    // ===========================================================================
+    // Private: Runtime Guard (FACADE-5)
+    // ===========================================================================
+    _getRuntime(apiName) {
+        this._lifecycleManager.ensureReady(apiName);
+        return this._runtime;
+    }
+}
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/create-app.d.ts

@@ -0,0 +1,52 @@
+/**
+ * App Factory
+ *
+ * @see SPEC v2.3.0 §6
+ * @module
+ */
+import type { DomainSchema } from "@manifesto-ai/core";
+import type { App, AppConfig, Effects, MelText } from "@manifesto-ai/runtime";
+/**
+ * Create a new Manifesto App instance (v2.3.0).
+ *
+ * The `createApp()` function:
+ * 1. Returns synchronously with an App instance
+ * 2. Does NOT perform runtime initialization during this call
+ * 3. Creates Host internally (users provide effects, not Host)
+ * 4. Creates World internally if not provided (per ADR-003)
+ *
+ * ## v2.3.0 API (Recommended)
+ *
+ * Uses AppConfig with effects-first design. Host and World are created internally.
+ *
+ * ```typescript
+ * const app = createApp({
+ *   schema: domainSchema,
+ *   effects: {
+ *     'api.fetch': async (params, ctx) => [...],
+ *     'api.save': async (params, ctx) => [...],
+ *   },
+ *   // world is optional (defaults to internal World with InMemoryWorldStore)
+ * });
+ *
+ * await app.ready();
+ * ```
+ *
+ * @see SPEC v2.3.0 §6.1
+ * @see ADR-APP-002
+ * @see ADR-003
+ */
+export declare function createApp(config: AppConfig): App;
+/**
+ * Create a minimal App for testing.
+ *
+ * Uses in-memory implementations for WorldStore and empty effects.
+ * For v2.3.0, this creates an effects-first app.
+ *
+ * @param domain - Domain schema or MEL text
+ * @param opts - Additional options
+ */
+export declare function createTestApp(domain: MelText | DomainSchema, opts?: Partial<Omit<AppConfig, "schema" | "effects">> & {
+    effects?: Effects;
+}): App;
+//# sourceMappingURL=create-app.d.ts.map

package/dist/create-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-app.d.ts","sourceRoot":"","sources":["../src/create-app.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAQ9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,GAAG,CAEhD;AA2BD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,OAAO,GAAG,YAAY,EAC9B,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,GAAG,SAAS,CAAC,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5E,GAAG,CAmBL"}

package/dist/create-app.js

@@ -0,0 +1,94 @@
+/**
+ * App Factory
+ *
+ * @see SPEC v2.3.0 §6
+ * @module
+ */
+import { ManifestoApp } from "./app.js";
+import { createInMemoryWorldStore, ReservedEffectTypeError, RESERVED_EFFECT_TYPE } from "@manifesto-ai/runtime";
+// =============================================================================
+// v2.2.0 API
+// =============================================================================
+/**
+ * Create a new Manifesto App instance (v2.3.0).
+ *
+ * The `createApp()` function:
+ * 1. Returns synchronously with an App instance
+ * 2. Does NOT perform runtime initialization during this call
+ * 3. Creates Host internally (users provide effects, not Host)
+ * 4. Creates World internally if not provided (per ADR-003)
+ *
+ * ## v2.3.0 API (Recommended)
+ *
+ * Uses AppConfig with effects-first design. Host and World are created internally.
+ *
+ * ```typescript
+ * const app = createApp({
+ *   schema: domainSchema,
+ *   effects: {
+ *     'api.fetch': async (params, ctx) => [...],
+ *     'api.save': async (params, ctx) => [...],
+ *   },
+ *   // world is optional (defaults to internal World with InMemoryWorldStore)
+ * });
+ *
+ * await app.ready();
+ * ```
+ *
+ * @see SPEC v2.3.0 §6.1
+ * @see ADR-APP-002
+ * @see ADR-003
+ */
+export function createApp(config) {
+    return createAppFromConfig(config);
+}
+/**
+ * Create App with v2.3.0 AppConfig (effects-first, World owns persistence).
+ *
+ * @internal
+ */
+function createAppFromConfig(config) {
+    // Extract domain from config
+    const domain = config.schema;
+    // Validate reserved effect types - users cannot override system.get
+    if (RESERVED_EFFECT_TYPE in config.effects) {
+        throw new ReservedEffectTypeError(RESERVED_EFFECT_TYPE);
+    }
+    // ADR-003: World owns persistence
+    // If world is not provided, create a default WorldStore
+    const worldStore = config.world?.store ?? createInMemoryWorldStore();
+    return new ManifestoApp(config, worldStore);
+}
+// =============================================================================
+// Helper Factories
+// =============================================================================
+/**
+ * Create a minimal App for testing.
+ *
+ * Uses in-memory implementations for WorldStore and empty effects.
+ * For v2.3.0, this creates an effects-first app.
+ *
+ * @param domain - Domain schema or MEL text
+ * @param opts - Additional options
+ */
+export function createTestApp(domain, opts) {
+    return createApp({
+        schema: domain,
+        effects: opts?.effects ?? {},
+        initialData: opts?.initialData,
+        hooks: opts?.hooks,
+        actorPolicy: opts?.actorPolicy,
+        scheduler: opts?.scheduler,
+        systemActions: opts?.systemActions,
+        devtools: opts?.devtools,
+        plugins: opts?.plugins,
+        validation: opts?.validation,
+        memory: opts?.memory,
+        memoryStore: opts?.memoryStore,
+        memoryProvider: opts?.memoryProvider,
+        policyService: opts?.policyService,
+        executionKeyPolicy: opts?.executionKeyPolicy,
+        world: opts?.world,
+    });
+}
+//# sourceMappingURL=create-app.js.map

package/dist/create-app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-app.js","sourceRoot":"","sources":["../src/create-app.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAEhH,gFAAgF;AAChF,aAAa;AACb,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,MAAM,UAAU,SAAS,CAAC,MAAiB;IACzC,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC;AACrC,CAAC;AAED;;;;GAIG;AACH,SAAS,mBAAmB,CAAC,MAAiB;IAC5C,6BAA6B;IAC7B,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAE7B,oEAAoE;IACpE,IAAI,oBAAoB,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QAC3C,MAAM,IAAI,uBAAuB,CAAC,oBAAoB,CAAC,CAAC;IAC1D,CAAC;IAED,kCAAkC;IAClC,wDAAwD;IACxD,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,IAAI,wBAAwB,EAAE,CAAC;IAErE,OAAO,IAAI,YAAY,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAC9C,CAAC;AAED,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAC3B,MAA8B,EAC9B,IAA6E;IAE7E,OAAO,SAAS,CAAC;QACf,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,IAAI,EAAE,OAAO,IAAI,EAAE;QAC5B,WAAW,EAAE,IAAI,EAAE,WAAW;QAC9B,KAAK,EAAE,IAAI,EAAE,KAAK;QAClB,WAAW,EAAE,IAAI,EAAE,WAAW;QAC9B,SAAS,EAAE,IAAI,EAAE,SAAS;QAC1B,aAAa,EAAE,IAAI,EAAE,aAAa;QAClC,QAAQ,EAAE,IAAI,EAAE,QAAQ;QACxB,OAAO,EAAE,IAAI,EAAE,OAAO;QACtB,UAAU,EAAE,IAAI,EAAE,UAAU;QAC5B,MAAM,EAAE,IAAI,EAAE,MAAM;QACpB,WAAW,EAAE,IAAI,EAAE,WAAW;QAC9B,cAAc,EAAE,IAAI,EAAE,cAAc;QACpC,aAAa,EAAE,IAAI,EAAE,aAAa;QAClC,kBAAkB,EAAE,IAAI,EAAE,kBAAkB;QAC5C,KAAK,EAAE,IAAI,EAAE,KAAK;KACnB,CAAC,CAAC;AACL,CAAC"}