@manifesto-ai/core 2.13.0 → 5.1.0

package/README.md

@@ -6,14 +6,33 @@
 
 ## What is 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.
+Core is responsible for evaluating domain semantics. Given a schema, snapshot, intent, and context, it computes what patches and requirements should result—but never executes them.
+
+Most app developers should start with `@manifesto-ai/sdk`, not this package.
+The direct Core examples below are for custom runtime authors, test harnesses,
+and developer tooling that needs the pure compute/apply boundary.
+
+```typescript
+const app = createManifesto<TodoDomain>(TodoMel, effects).activate();
+await app.action.addTodo.submit("Review docs");
+console.log(app.snapshot().state.todos);
+```
+
+If you are deciding where to start:
+
+| Goal | Start Here |
+|------|------------|
+| Build a web app, backend route, script, or trusted agent | `@manifesto-ai/sdk` and the main Guide |
+| Fulfill API/database work from MEL effects | SDK effect handlers |
+| Add approval, audit history, or restore | Lineage/Governance after the base runtime works |
+| Test pure domain computation or build runtime tooling | This Core package |
 
 In the Manifesto architecture:
 
 ```
 Host -> CORE -> ComputeResult
            |
-    Computes patches & effects
+    Computes patches & requirements
     (pure, no IO, deterministic)
 ```
 
@@ -23,7 +42,7 @@ Host -> CORE -> ComputeResult
 
 | Responsibility | Description |
 |----------------|-------------|
-| Compute state transitions | Given (schema, snapshot, intent), produce patches and effects |
+| Compute state transitions | Given (schema, snapshot, intent, context), produce patches and requirements |
 | 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 |
@@ -37,13 +56,17 @@ Host -> CORE -> ComputeResult
 | Execute effects | Host |
 | Perform IO (network, filesystem) | Host |
 | Persist snapshots | Host |
-| Govern authority/proposals | `@manifesto-ai/governance` + `@manifesto-ai/lineage` |
+| Add optional approval/history protocols | `@manifesto-ai/governance` + `@manifesto-ai/lineage` |
 | Handle UI/event bindings | SDK |
 
 ---
 
 ## Installation
 
+Install Core directly only when you need direct compute fixtures, custom
+runtime internals, or low-level tooling. App code gets Core through
+`@manifesto-ai/sdk`.
+
 ```bash
 npm install @manifesto-ai/core
 # or
@@ -52,11 +75,11 @@ pnpm add @manifesto-ai/core
 
 ---
 
-## Quick Example
+## Direct Core Fixture
 
 ```typescript
 import { createCore, createSnapshot, createIntent } from "@manifesto-ai/core";
-import type { DomainSchema } from "@manifesto-ai/core";
+import type { Context, DomainSchema } from "@manifesto-ai/core";
 
 // Create core instance
 const core = createCore();
@@ -85,7 +108,7 @@ const schema: DomainSchema = {
       flow: {
         kind: "patch",
         op: "set",
-        path: "count",
+        path: [{ kind: "prop", name: "count" }],
         value: {
           kind: "add",
           left: { kind: "get", path: "count" },
@@ -96,8 +119,11 @@ const schema: DomainSchema = {
   },
 };
 
-// Create host context (deterministic inputs)
-const context = { now: 0, randomSeed: "seed" };
+// Create owner-neutral ADR-027 context (deterministic inputs)
+const context: Context = {
+  runtime: { time: { timestamp: 0 }, random: { seed: "seed" } },
+  external: {},
+};
 
 // Create initial snapshot
 const snapshot = createSnapshot({ count: 0 }, schema.hash, context);
@@ -107,9 +133,12 @@ const intent = createIntent("increment", "intent-1");
 
 // Compute result (pure, deterministic)
 const result = await core.compute(schema, snapshot, intent, context);
+const patched = core.apply(schema, snapshot, result.patches);
+const namespaced = core.applyNamespaceDeltas(patched, result.namespaceDelta ?? []);
+const next = core.applySystemDelta(namespaced, result.systemDelta);
 
 console.log(result.status); // -> "complete"
-console.log(result.snapshot.data.count); // -> 1
+console.log(next.state.count); // -> 1
 ```
 
 > See [GUIDE.md](docs/GUIDE.md) for the full tutorial.
@@ -127,17 +156,17 @@ function createCore(): ManifestoCore;
 // Core interface
 interface ManifestoCore {
   compute(schema, snapshot, intent, context): Promise<ComputeResult>;
-  apply(schema, snapshot, patches, context): Snapshot;
+  apply(schema, snapshot, patches): Snapshot;
   validate(schema): ValidationResult;
   explain(schema, snapshot, path): ExplainResult;
 }
 
 // Key types
-type DomainSchema = { id, version, hash, types, state, computed, actions, meta? };
-type Snapshot = { data, computed, system, input, meta };
+type DomainSchema = { id, version, hash, types, state, context?, computed, actions, meta? };
+type Snapshot = { state, computed, system, input, meta, namespaces };
 type Intent = { type, input?, intentId };
 type Patch = { op: "set" | "unset" | "merge", path, value? };
-type ComputeResult = { status, snapshot, requirements, trace };
+type ComputeResult = { status, patches, namespaceDelta?, systemDelta, trace };
 ```
 
 > See [core-SPEC.md](docs/core-SPEC.md) for the current living specification.
@@ -152,7 +181,7 @@ All communication between Core and Host happens through Snapshot. There is no hi
 
 ### Deterministic Computation
 
-Given the same (schema, snapshot, intent), Core always produces the same result. This enables:
+Given the same (schema, snapshot, intent, context), Core always produces the same result. This enables:
 - Reliable testing without mocks
 - Time-travel debugging
 - Reproducible bug reports
@@ -194,7 +223,7 @@ For typical usage, see [`@manifesto-ai/sdk`](../sdk/) — the recommended entry
 
 | Document | Purpose |
 |----------|---------|
-| [GUIDE.md](docs/GUIDE.md) | Step-by-step usage guide |
+| [GUIDE.md](docs/GUIDE.md) | Direct Core fixture guide for tests, custom runtimes, and tooling |
 | [core-SPEC.md](docs/core-SPEC.md) | Current living specification |
 | [VERSION-INDEX.md](docs/VERSION-INDEX.md) | Current and historical document map |
 | [FDR-v1.0.0.md](docs/FDR-v1.0.0.md) | Historical design rationale |

package/dist/core/action-availability.d.ts

@@ -1,8 +1,8 @@
 import type { DomainSchema } from "../schema/domain.js";
 import type { Snapshot } from "../schema/snapshot.js";
 import type { Intent } from "../schema/patch.js";
-type ActionAvailabilityErrorCode = "UNKNOWN_ACTION" | "INTERNAL_ERROR" | "TYPE_MISMATCH";
-type ActionDispatchabilityErrorCode = "UNKNOWN_ACTION" | "INTERNAL_ERROR" | "TYPE_MISMATCH";
+export type ActionAvailabilityErrorCode = "UNKNOWN_ACTION" | "INTERNAL_ERROR" | "TYPE_MISMATCH";
+export type ActionDispatchabilityErrorCode = "UNKNOWN_ACTION" | "INTERNAL_ERROR" | "TYPE_MISMATCH";
 export type ActionAvailabilityEvaluation = {
     kind: "ok";
     available: boolean;
@@ -28,6 +28,10 @@ export type ActionDispatchabilityEvaluation = {
 export declare function evaluateActionAvailability(schema: DomainSchema, snapshot: Snapshot, actionName: string, timestamp?: number): ActionAvailabilityEvaluation;
 /**
  * Check whether an action is available for a new invocation.
+ *
+ * @deprecated Use {@link evaluateActionAvailability}: this wrapper throws on
+ * evaluation errors, violating the errors-are-values contract. It will be
+ * removed in the next major release.
  */
 export declare function isActionAvailable(schema: DomainSchema, snapshot: Snapshot, actionName: string): boolean;
 /**
@@ -36,10 +40,46 @@ export declare function isActionAvailable(schema: DomainSchema, snapshot: Snapsh
 export declare function evaluateIntentDispatchability(schema: DomainSchema, snapshot: Snapshot, intent: Intent, timestamp?: number): ActionDispatchabilityEvaluation;
 /**
  * Check whether a specific bound intent is dispatchable.
+ *
+ * @deprecated Use {@link evaluateIntentDispatchability}: this wrapper throws
+ * on evaluation errors, violating the errors-are-values contract. It will be
+ * removed in the next major release.
  */
 export declare function isIntentDispatchable(schema: DomainSchema, snapshot: Snapshot, intent: Intent): boolean;
+export type AvailableActionError = {
+    readonly actionName: string;
+    readonly code: ActionAvailabilityErrorCode;
+    readonly message: string;
+};
+export type AvailableActionsEvaluation = {
+    kind: "ok";
+    /** Action names whose availability evaluated to true, in schema key order. */
+    actions: readonly string[];
+    /**
+     * Actions whose availability expression failed to evaluate. They are
+     * excluded from `actions` (an action whose legality cannot be evaluated
+     * is not available), but the failure stays observable as a value so one
+     * broken expression cannot poison the whole legality query.
+     */
+    errors: readonly AvailableActionError[];
+} | {
+    kind: "error";
+    code: "INTERNAL_ERROR";
+    message: string;
+};
+/**
+ * Evaluate availability for every action without re-entry semantics.
+ *
+ * Per-action evaluation failures are reported as values alongside the
+ * available list; only a snapshot-level preparation failure (computed
+ * evaluation) makes the whole query fail.
+ */
+export declare function evaluateAvailableActions(schema: DomainSchema, snapshot: Snapshot): AvailableActionsEvaluation;
 /**
  * Return all currently available actions in schema key order.
+ *
+ * @deprecated Use {@link evaluateAvailableActions}: this wrapper throws on
+ * evaluation errors, violating the errors-are-values contract. It will be
+ * removed in the next major release.
  */
 export declare function getAvailableActions(schema: DomainSchema, snapshot: Snapshot): readonly string[];
-export {};

package/dist/core/apply.d.ts

@@ -1,11 +1,17 @@
 import type { DomainSchema } from "../schema/domain.js";
 import type { Snapshot } from "../schema/snapshot.js";
 import type { Patch } from "../schema/patch.js";
-import type { HostContext } from "../schema/host-context.js";
+import type { NamespaceDelta } from "../schema/result.js";
 /**
- * Apply patches to snapshot.data and recompute computed values.
+ * Apply domain patches to snapshot.state and recompute computed values.
  *
- * Patch targets are rooted at snapshot.data only.
+ * Patch targets are rooted at snapshot.state only.
  * System transitions are handled by applySystemDelta().
  */
-export declare function apply(schema: DomainSchema, snapshot: Snapshot, patches: readonly Patch[], context: HostContext): Snapshot;
+export declare function apply(schema: DomainSchema, snapshot: Snapshot, patches: readonly Patch[]): Snapshot;
+/**
+ * Apply namespace transitions to snapshot.namespaces.
+ *
+ * Patch targets are rooted at snapshot.namespaces[namespace].
+ */
+export declare function applyNamespaceDeltas(snapshot: Snapshot, deltas: readonly NamespaceDelta[]): Snapshot;

package/dist/core/compute.d.ts

@@ -2,18 +2,18 @@ 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";
-import type { HostContext } from "../schema/host-context.js";
+import { type Context as CoreContext } from "../schema/context.js";
 /**
  * Compute the result of dispatching an intent (synchronous).
  *
  * This is the canonical computation path. Each call is independent -
  * there is no suspended context.
  */
-export declare function computeSync(schema: DomainSchema, snapshot: Snapshot, intent: Intent, context: HostContext): ComputeResult;
+export declare function computeSync(schema: DomainSchema, snapshot: Snapshot, intent: Intent, context: CoreContext): ComputeResult;
 /**
  * Compute the result of dispatching an intent (async wrapper).
  */
-export declare function compute(schema: DomainSchema, snapshot: Snapshot, intent: Intent, context: HostContext): Promise<ComputeResult>;
+export declare function compute(schema: DomainSchema, snapshot: Snapshot, intent: Intent, context: CoreContext): Promise<ComputeResult>;
 /**
  * Validate only the caller-provided input portion of an intent.
  * Returns an error message when the intent is malformed, or null when valid.

package/dist/core/context-validation.d.ts

@@ -0,0 +1,11 @@
+import type { DomainSchema } from "../schema/domain.js";
+import type { ValidationResult } from "../schema/result.js";
+import type { JsonValue } from "../schema/context.js";
+/**
+ * Validate a materialized ADR-027 external context value against a schema.
+ *
+ * This helper validates only the user-owned `Context.external` partition.
+ * Manifesto-owned `Context.runtime` is validated by the canonical `Context`
+ * schema at the compute boundary.
+ */
+export declare function validateExternalContext(schema: DomainSchema, external: Record<string, JsonValue>): ValidationResult;

package/dist/core/index.d.ts

@@ -1,4 +1,5 @@
 export { validate } from "./validate.js";
-export { apply } from "./apply.js";
+export { validateExternalContext } from "./context-validation.js";
+export { apply, applyNamespaceDeltas } from "./apply.js";
 export { compute, computeSync } from "./compute.js";
 export { explain } from "./explain.js";

package/dist/errors.d.ts

@@ -5,6 +5,7 @@ import type { ErrorValue } from "./schema/snapshot.js";
  */
 export declare const CoreErrorCode: z.ZodEnum<{
     VALIDATION_ERROR: "VALIDATION_ERROR";
+    INVALID_PATCH_PATH: "INVALID_PATCH_PATH";
     PATH_NOT_FOUND: "PATH_NOT_FOUND";
     TYPE_MISMATCH: "TYPE_MISMATCH";
     DIVISION_BY_ZERO: "DIVISION_BY_ZERO";
@@ -12,6 +13,8 @@ export declare const CoreErrorCode: z.ZodEnum<{
     UNKNOWN_ACTION: "UNKNOWN_ACTION";
     ACTION_UNAVAILABLE: "ACTION_UNAVAILABLE";
     INVALID_INPUT: "INVALID_INPUT";
+    INVALID_VALUE: "INVALID_VALUE";
+    INVALID_CONTEXT: "INVALID_CONTEXT";
     CYCLIC_DEPENDENCY: "CYCLIC_DEPENDENCY";
     UNKNOWN_FLOW: "UNKNOWN_FLOW";
     CYCLIC_CALL: "CYCLIC_CALL";

package/dist/evaluator/context.d.ts

@@ -1,6 +1,11 @@
 import type { Snapshot } from "../schema/snapshot.js";
 import type { DomainSchema } from "../schema/domain.js";
+import type { Context } from "../schema/context.js";
 import { type TraceContext } from "../schema/trace.js";
+export type EvalPhase = "flow" | "computed" | "availability" | "dispatchability" | "snapshot";
+type RuntimeAllocationState = {
+    ordinal: number;
+};
 /**
  * Evaluation context for expressions and flows
  */
@@ -26,9 +31,25 @@ export type EvalContext = {
      */
     readonly intentId?: string;
     /**
-     * UUID generator counter (for deterministic UUID generation)
+     * Runtime context for bound action flow evaluation.
+     */
+    readonly context?: Context;
+    /**
+     * Current evaluation phase. Runtime/context reads are legal only in flow.
+     */
+    readonly phase: EvalPhase;
+    /**
+     * Context-local occurrence ordinal for deterministic runtime allocation.
+     */
+    runtimeOrdinal?: number;
+    /**
+     * Shared deterministic runtime allocator for cloned nested evaluation contexts.
+     */
+    runtimeAllocator?: RuntimeAllocationState;
+    /**
+     * Current expression allocation path for deterministic runtime values.
      */
-    uuidCounter?: number;
+    expressionPath?: string;
     /**
      * Trace context for deterministic trace ID generation
      */
@@ -39,14 +60,17 @@ export type EvalContext = {
     readonly $item?: unknown;
     readonly $index?: number;
     readonly $array?: unknown[];
+    readonly collectionStack?: readonly number[];
 };
 /**
  * Create a new evaluation context
  *
  * @param timestampOrTrace - Required timestamp or TraceContext for deterministic tracing.
- *                           MUST be provided by Host via HostContext.now to ensure determinism.
  */
-export declare function createContext(snapshot: Snapshot, schema: DomainSchema, currentAction: string | null, nodePath: string, intentId: string | undefined, timestampOrTrace: number | TraceContext): EvalContext;
+export declare function createContext(snapshot: Snapshot, schema: DomainSchema, currentAction: string | null, nodePath: string, intentId: string | undefined, timestampOrTrace: number | TraceContext, options?: {
+    readonly context?: Context;
+    readonly phase?: EvalPhase;
+}): EvalContext;
 /**
  * Create context with collection variables for filter/map/find/etc.
  */
@@ -59,3 +83,4 @@ export declare function withSnapshot(ctx: EvalContext, snapshot: Snapshot): Eval
  * Update context with new node path
  */
 export declare function withNodePath(ctx: EvalContext, nodePath: string): EvalContext;
+export {};

package/dist/evaluator/flow.d.ts

@@ -1,6 +1,7 @@
 import type { FlowNode } from "../schema/flow.js";
 import type { Snapshot, Requirement, ErrorValue } from "../schema/snapshot.js";
 import type { Patch } from "../schema/patch.js";
+import type { NamespaceDelta } from "../schema/result.js";
 import type { TraceNode } from "../schema/trace.js";
 import { type EvalContext } from "./context.js";
 /**
@@ -14,6 +15,7 @@ export type FlowState = {
     readonly snapshot: Snapshot;
     readonly status: FlowStatus;
     readonly patches: readonly Patch[];
+    readonly namespaceDelta: readonly NamespaceDelta[];
     readonly requirements: readonly Requirement[];
     readonly error: ErrorValue | null;
 };

package/dist/factories.d.ts

@@ -1,14 +1,14 @@
 import type { Snapshot } from "./schema/snapshot.js";
 import type { Intent } from "./schema/patch.js";
-import type { HostContext } from "./schema/host-context.js";
+import type { Context } from "./schema/context.js";
 /**
- * Create a new snapshot with initial data
+ * Create a new snapshot with initial state
  *
- * @param data - Initial domain data
+ * @param state - Initial domain state
  * @param schemaHash - Hash of the schema this snapshot conforms to
  * @returns New snapshot
  */
-export declare function createSnapshot<T>(data: T, schemaHash: string, context: HostContext): Snapshot;
+export declare function createSnapshot<T>(state: T, schemaHash: string, context: Context): Snapshot;
 /**
  * Create an intent
  *

package/dist/index.d.ts

@@ -9,14 +9,17 @@ import type { DomainSchema } from "./schema/domain.js";
 import type { Snapshot } from "./schema/snapshot.js";
 import type { Intent, Patch } from "./schema/patch.js";
 import type { SemanticPath } from "./schema/common.js";
-import type { ComputeResult, ValidationResult, ExplainResult, SystemDelta } from "./schema/result.js";
-import type { HostContext } from "./schema/host-context.js";
+import type { ComputeResult, ValidationResult, ExplainResult, NamespaceDelta, SystemDelta } from "./schema/result.js";
+import type { Context, JsonValue } from "./schema/context.js";
 import { compute, computeSync, validateIntentInput } from "./core/compute.js";
-import { apply } from "./core/apply.js";
+import { apply, applyNamespaceDeltas } from "./core/apply.js";
 import { applySystemDelta } from "./core/system-delta.js";
 import { validate } from "./core/validate.js";
 import { explain } from "./core/explain.js";
+import { validateExternalContext } from "./core/context-validation.js";
 import { getAvailableActions, isActionAvailable, isIntentDispatchable } from "./core/action-availability.js";
+export { evaluateActionAvailability, evaluateAvailableActions, evaluateIntentDispatchability, } from "./core/action-availability.js";
+export type { ActionAvailabilityErrorCode, ActionAvailabilityEvaluation, ActionDispatchabilityErrorCode, ActionDispatchabilityEvaluation, AvailableActionError, AvailableActionsEvaluation, } from "./core/action-availability.js";
 /**
  * ManifestoCore interface
  */
@@ -27,16 +30,20 @@ export interface ManifestoCore {
      * This is the ONLY entry point for computation.
      * Each call is independent - there is no suspended context.
      */
-    compute(schema: DomainSchema, snapshot: Snapshot, intent: Intent, context: HostContext): Promise<ComputeResult>;
+    compute(schema: DomainSchema, snapshot: Snapshot, intent: Intent, context: Context): Promise<ComputeResult>;
     /**
      * Compute the result of dispatching an intent (synchronous).
      */
-    computeSync(schema: DomainSchema, snapshot: Snapshot, intent: Intent, context: HostContext): ComputeResult;
+    computeSync(schema: DomainSchema, snapshot: Snapshot, intent: Intent, context: Context): ComputeResult;
     /**
      * Apply patches to a snapshot.
      * Returns new snapshot with recomputed values.
      */
-    apply(schema: DomainSchema, snapshot: Snapshot, patches: readonly Patch[], context: HostContext): Snapshot;
+    apply(schema: DomainSchema, snapshot: Snapshot, patches: readonly Patch[]): Snapshot;
+    /**
+     * Apply namespace transitions to a snapshot.
+     */
+    applyNamespaceDeltas(snapshot: Snapshot, deltas: readonly NamespaceDelta[]): Snapshot;
     /**
      * Apply a system transition emitted by compute().
      */
@@ -61,6 +68,10 @@ export interface ManifestoCore {
      * Check whether a specific bound intent is dispatchable against the current snapshot.
      */
     isIntentDispatchable(schema: DomainSchema, snapshot: Snapshot, intent: Intent): boolean;
+    /**
+     * Validate a materialized ADR-027 external context value against the schema.
+     */
+    validateExternalContext(schema: DomainSchema, external: Record<string, JsonValue>): ValidationResult;
 }
 /**
  * Create a ManifestoCore instance
@@ -71,4 +82,4 @@ export * from "./utils/index.js";
 export * from "./evaluator/index.js";
 export * from "./errors.js";
 export * from "./factories.js";
-export { compute, computeSync, validateIntentInput, apply, applySystemDelta, validate, explain, isActionAvailable, getAvailableActions, isIntentDispatchable, };
+export { compute, computeSync, validateIntentInput, apply, applyNamespaceDeltas, applySystemDelta, validate, validateExternalContext, explain, isActionAvailable, getAvailableActions, isIntentDispatchable, };