@manifesto-ai/core 0.2.0 → 1.0.0

package/README.md

@@ -1,434 +1,196 @@
 # @manifesto-ai/core
 
-> AI Native Semantic Layer for SaaS Business Logic
+> **Core** is the pure semantic calculator of Manifesto. It computes state transitions deterministically with no side effects.
 
-The core package provides domain definition, runtime execution, expression evaluation, and effect system for Manifesto AI.
+---
 
-## Installation
+## What is Core?
 
-```bash
-pnpm add @manifesto-ai/core
-# or
-npm install @manifesto-ai/core
-```
+Core is responsible for evaluating domain semantics. Given a schema, snapshot, and intent, it computes what patches and effects should result—but never executes them.
 
-## Quick Start
+In the Manifesto architecture:
 
-```typescript
-import {
-  defineDomain,
-  createRuntime,
-  defineDerived,
-  defineAction,
-  sequence,
-  setState,
-  apiCall,
-  z
-} from '@manifesto-ai/core';
-
-// Define a domain
-const todosDomain = defineDomain('todos', {
-  dataSchema: z.object({
-    items: z.array(z.object({
-      id: z.string(),
-      title: z.string(),
-      completed: z.boolean()
-    }))
-  }),
-
-  stateSchema: z.object({
-    filter: z.enum(['all', 'active', 'completed']).default('all'),
-    isLoading: z.boolean().default(false)
-  }),
-
-  derived: {
-    'derived.activeCount': defineDerived(
-      { $size: { $filter: ['data.items', { $eq: ['$item.completed', false] }] } },
-      z.number()
-    ),
-    'derived.filteredItems': defineDerived(
-      {
-        $if: [
-          { $eq: [{ $get: 'state.filter' }, 'all'] },
-          { $get: 'data.items' },
-          { $filter: ['data.items', {
-            $eq: ['$item.completed', { $eq: [{ $get: 'state.filter' }, 'completed'] }]
-          }] }
-        ]
-      },
-      z.array(z.object({ id: z.string(), title: z.string(), completed: z.boolean() }))
-    )
-  },
-
-  actions: {
-    addTodo: defineAction({
-      precondition: { $gt: [{ $size: { $get: 'input.title' } }, 0] },
-      effect: setValue('data.items', {
-        $concat: [
-          { $get: 'data.items' },
-          [{ id: { $get: 'input.id' }, title: { $get: 'input.title' }, completed: false }]
-        ]
-      })
-    })
-  }
-});
-
-// Create runtime
-const runtime = createRuntime(todosDomain);
-
-// Use the runtime
-runtime.set('data.items', [
-  { id: '1', title: 'Learn Manifesto', completed: false }
-]);
-
-console.log(runtime.get('derived.activeCount')); // 1
 ```
-
-## API Reference
-
-### Domain Definition
-
-#### `defineDomain(name, config)`
-
-Creates a domain definition.
-
-```typescript
-const domain = defineDomain('myDomain', {
-  dataSchema: z.object({ ... }),      // Required: Source data schema
-  stateSchema: z.object({ ... }),     // Optional: UI state schema
-  derived: { ... },                    // Optional: Computed values
-  async: { ... },                      // Optional: Async data sources
-  actions: { ... }                     // Optional: Domain actions
-});
+Host ──→ CORE ──→ ComputeResult
+           │
+    Computes patches & effects
+    (pure, no IO, deterministic)
 ```
 
-#### `defineSource(schema, meta?)`
+---
 
-Defines a source field with optional metadata.
+## What Core Does
 
-```typescript
-const sources = {
-  'data.user': defineSource(
-    z.object({ name: z.string(), email: z.string() }),
-    { description: 'Current user information' }
-  )
-};
-```
+| Responsibility | Description |
+|----------------|-------------|
+| Compute state transitions | Given (schema, snapshot, intent), produce patches and effects |
+| Apply patches | Transform snapshots by applying patch operations |
+| Validate schemas | Check DomainSchema structure for correctness |
+| Explain values | Trace why a computed value has its current result |
 
-#### `defineDerived(expression, schema, meta?)`
+---
 
-Defines a computed value.
+## What Core Does NOT Do
 
-```typescript
-const derived = {
-  'derived.fullName': defineDerived(
-    { $concat: [{ $get: 'data.firstName' }, ' ', { $get: 'data.lastName' }] },
-    z.string(),
-    { description: 'User full name' }
-  )
-};
-```
-
-#### `defineAsync(config, schema, meta?)`
+| NOT Responsible For | Who Is |
+|--------------------|--------|
+| Execute effects | Host |
+| Perform IO (network, filesystem) | Host |
+| Persist snapshots | Host |
+| Govern authority/proposals | World |
+| Handle UI bindings | Bridge / React |
 
-Defines an async data source.
+---
 
-```typescript
-const async = {
-  'async.userData': defineAsync(
-    {
-      fetch: { method: 'GET', url: '/api/user' },
-      dependencies: ['data.userId']
-    },
-    z.object({ name: z.string() })
-  )
-};
-```
-
-#### `defineAction(config)`
-
-Defines a domain action with preconditions and effects.
+## Installation
 
-```typescript
-const actions = {
-  submit: defineAction({
-    precondition: { $and: [
-      { $gt: [{ $get: 'derived.total' }, 0] },
-      { $not: { $get: 'state.isSubmitting' } }
-    ]},
-    effect: sequence([
-      setState('state.isSubmitting', true),
-      apiCall({ method: 'POST', url: '/api/submit' }),
-      setState('state.isSubmitting', false)
-    ])
-  })
-};
+```bash
+npm install @manifesto-ai/core
+# or
+pnpm add @manifesto-ai/core
 ```
 
-### Runtime
-
-#### `createRuntime(domain, options?)`
+---
 
-Creates a runtime instance for a domain.
+## Quick Example
 
 ```typescript
-const runtime = createRuntime(domain, {
-  initialData: { count: 0 },
-  initialState: { isLoading: false }
-});
-```
-
-#### Runtime Methods
-
-```typescript
-// Get a value by path
-runtime.get('data.user.name');        // Returns the value
-runtime.get('derived.fullName');      // Computes and returns
-
-// Set a value
-runtime.set('data.count', 10);
-runtime.set('state.isLoading', true);
+import { createCore, createSnapshot, createIntent } from "@manifesto-ai/core";
+import type { DomainSchema } from "@manifesto-ai/core";
 
-// Subscribe to changes
-const unsubscribe = runtime.subscribe('data.count', (value) => {
-  console.log('Count:', value);
-});
+// Create core instance
+const core = createCore();
 
-// Subscribe to all changes
-runtime.subscribeAll((snapshot) => {
-  console.log('Snapshot changed:', snapshot);
-});
-
-// Get current snapshot
-const snapshot = runtime.getSnapshot();
-
-// Check action availability
-const canSubmit = runtime.checkAction('submit');
-// { available: true, reason: null }
-
-// Execute an action
-await runtime.executeAction('submit', { orderId: '123' });
-
-// Explain why a value is what it is
-const explanation = runtime.explain('derived.total');
-```
-
-### Expression DSL
-
-Manifesto uses a JSON-based DSL for declarative expressions.
+// Define a simple schema (usually from @manifesto-ai/builder)
+const schema: DomainSchema = {
+  version: "1.0.0",
+  state: {
+    count: { type: "number", default: 0 },
+  },
+  actions: {
+    increment: {
+      flow: {
+        kind: "patch",
+        op: "set",
+        path: "/data/count",
+        value: { kind: "add", left: { kind: "get", path: "/data/count" }, right: 1 },
+      },
+    },
+  },
+};
 
-#### Comparison Operators
+// Create initial snapshot
+const snapshot = createSnapshot(schema);
 
-```typescript
-{ $eq: [a, b] }       // a === b
-{ $ne: [a, b] }       // a !== b
-{ $gt: [a, b] }       // a > b
-{ $gte: [a, b] }      // a >= b
-{ $lt: [a, b] }       // a < b
-{ $lte: [a, b] }      // a <= b
-```
+// Create intent
+const intent = createIntent("increment");
 
-#### Logical Operators
+// Compute result (pure, deterministic)
+const result = await core.compute(schema, snapshot, intent);
 
-```typescript
-{ $and: [expr1, expr2, ...] }   // All true
-{ $or: [expr1, expr2, ...] }    // Any true
-{ $not: expr }                   // Negation
+console.log(result.status); // → "completed"
+console.log(result.snapshot.data.count); // → 1
 ```
 
-#### Arithmetic Operators
+> See [GUIDE.md](../../docs/packages/core/GUIDE.md) for the full tutorial.
 
-```typescript
-{ $add: [a, b] }        // a + b
-{ $subtract: [a, b] }   // a - b
-{ $multiply: [a, b] }   // a * b
-{ $divide: [a, b] }     // a / b
-{ $modulo: [a, b] }     // a % b
-```
-
-#### String Functions
+---
 
-```typescript
-{ $concat: [str1, str2, ...] }  // Concatenate strings
-{ $upper: str }                  // Uppercase
-{ $lower: str }                  // Lowercase
-{ $trim: str }                   // Trim whitespace
-{ $split: [str, delimiter] }     // Split string
-{ $includes: [str, search] }     // Contains substring
-```
+## Core API
 
-#### Array Functions
+### Main Exports
 
 ```typescript
-{ $size: array }                            // Array length
-{ $first: array }                           // First element
-{ $last: array }                            // Last element
-{ $filter: [array, predicate] }             // Filter elements
-{ $map: [array, transform] }                // Transform elements
-{ $find: [array, predicate] }               // Find first match
-{ $some: [array, predicate] }               // Any match
-{ $every: [array, predicate] }              // All match
-{ $sum: array }                             // Sum numbers
-{ $reduce: [array, reducer, initial] }      // Reduce array
-```
+// Factory
+function createCore(): ManifestoCore;
 
-#### Conditional
+// Core interface
+interface ManifestoCore {
+  compute(schema, snapshot, intent): Promise<ComputeResult>;
+  apply(schema, snapshot, patches): Snapshot;
+  validate(schema): ValidationResult;
+  explain(schema, snapshot, path): ExplainResult;
+}
 
-```typescript
-{ $if: [condition, thenValue, elseValue] }
+// Key types
+type DomainSchema = { version, state, computed?, actions?, flows?, meta? };
+type Snapshot = { data, computed, system, input, meta };
+type Intent = { type, input?, intentId };
+type Patch = { op: "set" | "unset" | "merge", path, value? };
+type ComputeResult = { status, snapshot, patches, requirements, trace };
 ```
 
-#### Path Reference
+> See [SPEC.md](../../docs/packages/core/SPEC.md) for complete API reference.
 
-```typescript
-{ $get: 'data.user.name' }    // Get value at path
-'$item.price'                  // Current item in iteration
-'$index'                       // Current index in iteration
-```
+---
 
-### Effect System
+## Core Concepts
 
-Effects describe side effects as data.
+### Snapshot as Sole Medium
 
-#### Effect Types
+All communication between Core and Host happens through Snapshot. There is no hidden state, no suspended context, no continuation.
 
-```typescript
-// Set a value
-setValue('data.count', 10)
-setValue('data.count', { $add: [{ $get: 'data.count' }, 1] })
+### Deterministic Computation
 
-// Set state
-setState('state.isLoading', true)
+Given the same (schema, snapshot, intent), Core always produces the same result. This enables:
+- Reliable testing without mocks
+- Time-travel debugging
+- Reproducible bug reports
 
-// API call
-apiCall({
-  method: 'POST',
-  url: '/api/orders',
-  body: { $get: 'data.order' },
-  headers: { 'Content-Type': 'application/json' }
-})
+### Effects as Declarations
 
-// Navigation
-navigate('/success')
+When an action needs IO (API call, timer, etc.), Core doesn't execute it. Instead, it records an Effect as a Requirement in the snapshot. Host reads these and executes them.
 
-// Delay
-delay(1000)  // milliseconds
+---
 
-// Emit event
-emitEvent('orderCreated', { orderId: '123' })
-```
-
-#### Effect Composition
+## Relationship with Other Packages
 
-```typescript
-// Sequential execution
-sequence([
-  setState('state.isLoading', true),
-  apiCall({ method: 'GET', url: '/api/data' }),
-  setState('state.isLoading', false)
-])
-
-// Parallel execution
-parallel([
-  apiCall({ method: 'GET', url: '/api/user' }),
-  apiCall({ method: 'GET', url: '/api/settings' })
-])
-
-// Conditional execution
-conditional(
-  { $get: 'state.isPremium' },
-  apiCall({ method: 'GET', url: '/api/premium' }),
-  apiCall({ method: 'GET', url: '/api/basic' })
-)
-
-// Error handling
-catchEffect(
-  apiCall({ method: 'POST', url: '/api/submit' }),
-  setState('state.error', { $get: 'error.message' })
-)
 ```
-
-#### Running Effects
-
-```typescript
-import { runEffect } from '@manifesto-ai/core';
-
-const result = await runEffect(effect, runtime, {
-  apiHandler: async (config) => {
-    const response = await fetch(config.url, {
-      method: config.method,
-      body: JSON.stringify(config.body)
-    });
-    return response.json();
-  }
-});
-
-if (isOk(result)) {
-  console.log('Success:', result.value);
-} else {
-  console.log('Error:', result.error);
-}
+┌─────────────┐
+│    Host     │ ← Uses Core to compute
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│    CORE     │
+└─────────────┘
+       ▲
+       │
+┌─────────────┐
+│   Builder   │ ← Produces DomainSchema for Core
+└─────────────┘
 ```
 
-### Result Type
-
-A functional error handling type.
-
-```typescript
-import { ok, err, isOk, isErr, map, flatMap, unwrapOr } from '@manifesto-ai/core';
+| Relationship | Package | How |
+|--------------|---------|-----|
+| Used by | `@manifesto-ai/host` | Host calls compute() and apply() |
+| Schema from | `@manifesto-ai/builder` | Builder produces DomainSchema |
 
-// Create results
-const success = ok(42);
-const failure = err({ code: 'NOT_FOUND', message: 'Item not found' });
+---
 
-// Check type
-if (isOk(success)) {
-  console.log(success.value);  // 42
-}
+## When to Use Core Directly
 
-// Transform
-const doubled = map(success, (x) => x * 2);  // ok(84)
+**Most users don't need to use Core directly.**
 
-// Chain operations
-const result = flatMap(success, (x) =>
-  x > 0 ? ok(x) : err({ code: 'INVALID', message: 'Must be positive' })
-);
+Use Core directly when:
+- Building a custom Host implementation
+- Testing domain logic in isolation
+- Building developer tools (debuggers, visualizers)
 
-// Get with default
-const value = unwrapOr(failure, 0);  // 0
-```
+For typical usage, see [`@manifesto-ai/react`](../react/) or [`@manifesto-ai/host`](../host/).
 
-### Schema Utilities
+---
 
-```typescript
-import {
-  schemaToSource,
-  validateValue,
-  zodErrorToValidationResult,
-  CommonSchemas
-} from '@manifesto-ai/core';
-
-// Common schemas
-CommonSchemas.email    // z.string().email()
-CommonSchemas.phone    // Phone number pattern
-CommonSchemas.money    // Positive number with 2 decimals
-
-// Validate values
-const result = validateValue(userSchema, inputData);
-if (!result.valid) {
-  console.log(result.issues);
-}
-```
+## Documentation
 
-## Related Packages
+| Document | Purpose |
+|----------|---------|
+| [GUIDE.md](../../docs/packages/core/GUIDE.md) | Step-by-step usage guide |
+| [SPEC.md](../../docs/packages/core/SPEC.md) | Complete specification |
+| [FDR.md](../../docs/packages/core/FDR.md) | Design rationale |
 
-- [@manifesto-ai/bridge](../bridge) - Framework adapters
-- [@manifesto-ai/bridge-zustand](../bridge-zustand) - Zustand integration
-- [@manifesto-ai/bridge-react-hook-form](../bridge-react-hook-form) - React Hook Form integration
-- [@manifesto-ai/projection-ui](../projection-ui) - UI state projection
-- [@manifesto-ai/projection-agent](../projection-agent) - AI agent context
-- [@manifesto-ai/projection-graphql](../projection-graphql) - GraphQL schema generation
+---
 
 ## License
 
-MIT
+[MIT](../../LICENSE)

package/dist/core/apply.d.ts

@@ -0,0 +1,16 @@
+import type { DomainSchema } from "../schema/domain.js";
+import type { Snapshot } from "../schema/snapshot.js";
+import type { Patch } from "../schema/patch.js";
+/**
+ * Apply patches to a snapshot
+ *
+ * This function:
+ * 1. Applies all patches to the data
+ * 2. Recomputes all computed values
+ * 3. Increments the version number
+ * 4. Updates the timestamp
+ *
+ * Note: Version and timestamp are Core-owned - Host MUST NOT modify these directly.
+ */
+export declare function apply(schema: DomainSchema, snapshot: Snapshot, patches: readonly Patch[]): Snapshot;
+//# sourceMappingURL=apply.d.ts.map

package/dist/core/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/core/apply.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAKhD;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CACnB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,SAAS,KAAK,EAAE,GACxB,QAAQ,CAwCV"}

package/dist/core/apply.js

@@ -0,0 +1,52 @@
+import { setByPath, unsetByPath, mergeAtPath } from "../utils/path.js";
+import { evaluateComputed } from "../evaluator/computed.js";
+import { isOk } from "../schema/common.js";
+/**
+ * Apply patches to a snapshot
+ *
+ * This function:
+ * 1. Applies all patches to the data
+ * 2. Recomputes all computed values
+ * 3. Increments the version number
+ * 4. Updates the timestamp
+ *
+ * Note: Version and timestamp are Core-owned - Host MUST NOT modify these directly.
+ */
+export function apply(schema, snapshot, patches) {
+    // 1. Apply patches to data
+    let newData = snapshot.data;
+    for (const patch of patches) {
+        switch (patch.op) {
+            case "set":
+                newData = setByPath(newData, patch.path, patch.value);
+                break;
+            case "unset":
+                newData = unsetByPath(newData, patch.path);
+                break;
+            case "merge":
+                newData = mergeAtPath(newData, patch.path, patch.value);
+                break;
+        }
+    }
+    // 2. Create intermediate snapshot with new data
+    const intermediateSnapshot = {
+        ...snapshot,
+        data: newData,
+    };
+    // 3. Recompute all computed values
+    const computedResult = evaluateComputed(schema, intermediateSnapshot);
+    const computed = isOk(computedResult) ? computedResult.value : snapshot.computed;
+    // 4. Return new snapshot with updated metadata
+    return {
+        data: newData,
+        computed,
+        system: snapshot.system,
+        input: snapshot.input,
+        meta: {
+            ...snapshot.meta,
+            version: snapshot.meta.version + 1,
+            timestamp: Date.now(),
+        },
+    };
+}
+//# sourceMappingURL=apply.js.map

package/dist/core/apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../src/core/apply.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAE3C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,KAAK,CACnB,MAAoB,EACpB,QAAkB,EAClB,OAAyB;IAEzB,2BAA2B;IAC3B,IAAI,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC;IAE5B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,QAAQ,KAAK,CAAC,EAAE,EAAE,CAAC;YACjB,KAAK,KAAK;gBACR,OAAO,GAAG,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;gBACtD,MAAM;YACR,KAAK,OAAO;gBACV,OAAO,GAAG,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;gBAC3C,MAAM;YACR,KAAK,OAAO;gBACV,OAAO,GAAG,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;gBACxD,MAAM;QACV,CAAC;IACH,CAAC;IAED,gDAAgD;IAChD,MAAM,oBAAoB,GAAa;QACrC,GAAG,QAAQ;QACX,IAAI,EAAE,OAAO;KACd,CAAC;IAEF,mCAAmC;IACnC,MAAM,cAAc,GAAG,gBAAgB,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IACtE,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAEjF,+CAA+C;IAC/C,OAAO;QACL,IAAI,EAAE,OAAO;QACb,QAAQ;QACR,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,IAAI,EAAE;YACJ,GAAG,QAAQ,CAAC,IAAI;YAChB,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC;YAClC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB;KACF,CAAC;AACJ,CAAC"}

package/dist/core/compute.d.ts

@@ -0,0 +1,17 @@
+import type { DomainSchema } from "../schema/domain.js";
+import type { Snapshot } from "../schema/snapshot.js";
+import type { Intent } from "../schema/patch.js";
+import type { ComputeResult } from "../schema/result.js";
+/**
+ * Compute the result of dispatching an intent
+ *
+ * This is the ONLY entry point for computation.
+ * Each call is independent - there is no suspended context.
+ *
+ * @param schema - The domain schema
+ * @param snapshot - Current snapshot state
+ * @param intent - The intent to process
+ * @returns ComputeResult with new snapshot, trace, and status
+ */
+export declare function compute(schema: DomainSchema, snapshot: Snapshot, intent: Intent): Promise<ComputeResult>;
+//# sourceMappingURL=compute.d.ts.map

package/dist/core/compute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute.d.ts","sourceRoot":"","sources":["../../src/core/compute.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAe,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,qBAAqB,CAAC;AASxE;;;;;;;;;;GAUG;AACH,wBAAsB,OAAO,CAC3B,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,aAAa,CAAC,CA6HxB"}