@manifesto-ai/core 2.8.0 → 2.10.0

package/README.md

@@ -37,7 +37,7 @@ Host -> CORE -> ComputeResult
 | Execute effects | Host |
 | Perform IO (network, filesystem) | Host |
 | Persist snapshots | Host |
-| Govern authority/proposals | World |
+| Govern authority/proposals | `@manifesto-ai/governance` + `@manifesto-ai/lineage` |
 | Handle UI/event bindings | SDK |
 
 ---
@@ -140,7 +140,7 @@ type Patch = { op: "set" | "unset" | "merge", path, value? };
 type ComputeResult = { status, snapshot, requirements, trace };
 ```
 
-> See [SPEC-v2.0.0.md](docs/SPEC-v2.0.0.md) for complete API reference.
+> See [core-SPEC.md](docs/core-SPEC.md) for the current living specification.
 
 ---
 
@@ -186,7 +186,7 @@ Use Core directly when:
 - Testing domain logic in isolation
 - Building developer tools (debuggers, visualizers)
 
-For typical usage, see [`@manifesto-ai/sdk`](../sdk/) — the recommended entry point. For explicit governance, see [`@manifesto-ai/world`](../world/).
+For typical usage, see [`@manifesto-ai/sdk`](../sdk/) — the recommended entry point. For explicit governance, see [`@manifesto-ai/lineage`](../lineage/) and [`@manifesto-ai/governance`](../governance/).
 
 ---
 
@@ -195,8 +195,9 @@ For typical usage, see [`@manifesto-ai/sdk`](../sdk/) — the recommended entry
 | Document | Purpose |
 |----------|---------|
 | [GUIDE.md](docs/GUIDE.md) | Step-by-step usage guide |
-| [SPEC-v2.0.0.md](docs/SPEC-v2.0.0.md) | Complete specification |
-| [FDR-v2.0.0.md](docs/FDR-v2.0.0.md) | Design rationale |
+| [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

@@ -0,0 +1,27 @@
+import type { DomainSchema } from "../schema/domain.js";
+import type { Snapshot } from "../schema/snapshot.js";
+type ActionAvailabilityErrorCode = "UNKNOWN_ACTION" | "INTERNAL_ERROR" | "TYPE_MISMATCH";
+export type ActionAvailabilityEvaluation = {
+    kind: "ok";
+    available: boolean;
+} | {
+    kind: "error";
+    code: ActionAvailabilityErrorCode;
+    message: string;
+};
+/**
+ * Evaluate an action's availability expression without re-entry semantics.
+ *
+ * This is the shared evaluator used by compute() initial invocation checks and
+ * the public availability query API.
+ */
+export declare function evaluateActionAvailability(schema: DomainSchema, snapshot: Snapshot, actionName: string, timestamp?: number): ActionAvailabilityEvaluation;
+/**
+ * Check whether an action is available for a new invocation.
+ */
+export declare function isActionAvailable(schema: DomainSchema, snapshot: Snapshot, actionName: string): boolean;
+/**
+ * Return all currently dispatchable actions in schema key order.
+ */
+export declare function getAvailableActions(schema: DomainSchema, snapshot: Snapshot): readonly string[];
+export {};

package/dist/core/apply.d.ts

@@ -0,0 +1,11 @@
+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";
+/**
+ * Apply patches to snapshot.data and recompute computed values.
+ *
+ * Patch targets are rooted at snapshot.data only.
+ * System transitions are handled by applySystemDelta().
+ */
+export declare function apply(schema: DomainSchema, snapshot: Snapshot, patches: readonly Patch[], context: HostContext): Snapshot;

package/dist/core/compute.d.ts

@@ -0,0 +1,16 @@
+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";
+/**
+ * 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;
+/**
+ * Compute the result of dispatching an intent (async wrapper).
+ */
+export declare function compute(schema: DomainSchema, snapshot: Snapshot, intent: Intent, context: HostContext): Promise<ComputeResult>;

package/dist/core/explain.d.ts

@@ -0,0 +1,13 @@
+import type { DomainSchema } from "../schema/domain.js";
+import type { Snapshot } from "../schema/snapshot.js";
+import type { SemanticPath } from "../schema/common.js";
+import type { ExplainResult } from "../schema/result.js";
+/**
+ * Explain why a value is what it is
+ *
+ * @param schema - The domain schema
+ * @param snapshot - Current snapshot state
+ * @param path - The path to explain
+ * @returns ExplainResult with value, trace, and dependencies
+ */
+export declare function explain(schema: DomainSchema, snapshot: Snapshot, path: SemanticPath): ExplainResult;

package/dist/core/index.d.ts

@@ -0,0 +1,4 @@
+export { validate } from "./validate.js";
+export { apply } from "./apply.js";
+export { compute, computeSync } from "./compute.js";
+export { explain } from "./explain.js";

package/dist/core/system-delta.d.ts

@@ -0,0 +1,8 @@
+import type { Snapshot } from "../schema/snapshot.js";
+import type { SystemDelta } from "../schema/result.js";
+/**
+ * Apply a declarative system transition to a snapshot.
+ *
+ * This function is pure, deterministic, and total.
+ */
+export declare function applySystemDelta(snapshot: Snapshot, delta: SystemDelta): Snapshot;

package/dist/core/validate.d.ts

@@ -0,0 +1,15 @@
+import type { ValidationResult } from "../schema/result.js";
+/**
+ * Validate a domain schema
+ *
+ * Validation rules:
+ * - V-001: All paths in ComputedSpec.deps MUST exist
+ * - V-002: ComputedSpec dependency graph MUST be acyclic
+ * - V-003: All paths in ExprNode.get MUST exist
+ * - V-004: All `call` references in FlowSpec MUST exist
+ * - V-005: FlowSpec `call` graph MUST be acyclic
+ * - V-006: ActionSpec.available expression MUST return boolean (runtime check)
+ * - V-007: ActionSpec.input MUST be valid FieldSpec (Zod handles this)
+ * - V-008: Schema hash MUST match canonical hash
+ */
+export declare function validate(schema: unknown): ValidationResult;

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

@@ -0,0 +1,22 @@
+import type { ExprNode } from "../schema/expr.js";
+import type { FlowNode } from "../schema/flow.js";
+import type { FieldSpec, StateSpec } from "../schema/field.js";
+import type { ComputedSpec } from "../schema/computed.js";
+import type { PatchSegment } from "../schema/patch.js";
+export declare function isValidSchemaId(id: string): boolean;
+export declare function isValidSemver(version: string): boolean;
+export declare function collectGetPathsFromExpr(expr: ExprNode): string[];
+export declare function collectGetPathsFromFlow(flow: FlowNode): string[];
+export declare function pathExistsInStateSpec(state: StateSpec, path: string): boolean;
+export declare function pathExistsInComputedSpec(computed: ComputedSpec, path: string): boolean;
+export declare function pathExistsInFieldSpec(spec: FieldSpec, path: string): boolean;
+export declare function pathExistsInFieldSpecSegments(spec: FieldSpec, segments: readonly PatchSegment[]): boolean;
+export declare function validateValueAgainstFieldSpec(value: unknown, spec: FieldSpec, options?: {
+    allowPartial?: boolean;
+    allowUndefined?: boolean;
+}): {
+    ok: boolean;
+    message?: string;
+};
+export declare function getFieldSpecAtPath(spec: FieldSpec, path: string): FieldSpec | null;
+export declare function getFieldSpecAtSegments(spec: FieldSpec, segments: readonly PatchSegment[]): FieldSpec | null;

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { ErrorValue } from "./schema/snapshot.js";
+/**
+ * Core error codes
+ */
+export declare const CoreErrorCode: z.ZodEnum<{
+    VALIDATION_ERROR: "VALIDATION_ERROR";
+    PATH_NOT_FOUND: "PATH_NOT_FOUND";
+    TYPE_MISMATCH: "TYPE_MISMATCH";
+    DIVISION_BY_ZERO: "DIVISION_BY_ZERO";
+    INDEX_OUT_OF_BOUNDS: "INDEX_OUT_OF_BOUNDS";
+    UNKNOWN_ACTION: "UNKNOWN_ACTION";
+    ACTION_UNAVAILABLE: "ACTION_UNAVAILABLE";
+    INVALID_INPUT: "INVALID_INPUT";
+    CYCLIC_DEPENDENCY: "CYCLIC_DEPENDENCY";
+    UNKNOWN_FLOW: "UNKNOWN_FLOW";
+    CYCLIC_CALL: "CYCLIC_CALL";
+    UNKNOWN_EFFECT: "UNKNOWN_EFFECT";
+    INTERNAL_ERROR: "INTERNAL_ERROR";
+}>;
+export type CoreErrorCode = z.infer<typeof CoreErrorCode>;
+/**
+ * Create an error value (errors are values, not exceptions)
+ */
+export declare function createError(code: CoreErrorCode, message: string, actionId: string, nodePath: string, timestamp: number, context?: Record<string, unknown>): ErrorValue;
+/**
+ * Check if a value is an ErrorValue
+ */
+export declare function isErrorValue(value: unknown): value is ErrorValue;

package/dist/evaluator/computed.d.ts

@@ -0,0 +1,13 @@
+import type { DomainSchema } from "../schema/domain.js";
+import type { Snapshot } from "../schema/snapshot.js";
+import type { SemanticPath, Result } from "../schema/common.js";
+import type { ErrorValue } from "../schema/snapshot.js";
+/**
+ * Evaluate all computed values for a snapshot
+ * Returns the computed values record or an error
+ */
+export declare function evaluateComputed(schema: DomainSchema, snapshot: Snapshot): Result<Record<SemanticPath, unknown>, ErrorValue>;
+/**
+ * Evaluate a single computed value
+ */
+export declare function evaluateSingleComputed(schema: DomainSchema, snapshot: Snapshot, path: SemanticPath): Result<unknown, ErrorValue>;

package/dist/evaluator/context.d.ts

@@ -0,0 +1,61 @@
+import type { Snapshot } from "../schema/snapshot.js";
+import type { DomainSchema } from "../schema/domain.js";
+import { type TraceContext } from "../schema/trace.js";
+/**
+ * Evaluation context for expressions and flows
+ */
+export type EvalContext = {
+    /**
+     * Current snapshot state
+     */
+    readonly snapshot: Snapshot;
+    /**
+     * Domain schema
+     */
+    readonly schema: DomainSchema;
+    /**
+     * Current action being processed (if any)
+     */
+    readonly currentAction: string | null;
+    /**
+     * Current node path in the flow (for tracing)
+     */
+    readonly nodePath: string;
+    /**
+     * Intent ID for the current intent (for re-entry safety)
+     */
+    readonly intentId?: string;
+    /**
+     * UUID generator counter (for deterministic UUID generation)
+     */
+    uuidCounter?: number;
+    /**
+     * Trace context for deterministic trace ID generation
+     */
+    readonly trace: TraceContext;
+    /**
+     * Collection context variables (for filter, map, find, etc.)
+     */
+    readonly $item?: unknown;
+    readonly $index?: number;
+    readonly $array?: unknown[];
+};
+/**
+ * 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;
+/**
+ * Create context with collection variables for filter/map/find/etc.
+ */
+export declare function withCollectionContext(ctx: EvalContext, item: unknown, index: number, array: unknown[]): EvalContext;
+/**
+ * Update context with new snapshot
+ */
+export declare function withSnapshot(ctx: EvalContext, snapshot: Snapshot): EvalContext;
+/**
+ * Update context with new node path
+ */
+export declare function withNodePath(ctx: EvalContext, nodePath: string): EvalContext;

package/dist/evaluator/dag.d.ts

@@ -0,0 +1,29 @@
+import type { ComputedSpec } from "../schema/computed.js";
+import type { SemanticPath } from "../schema/common.js";
+import type { Result } from "../schema/common.js";
+import type { ValidationError } from "../schema/result.js";
+/**
+ * Dependency graph for computed values
+ */
+export type DependencyGraph = {
+    readonly nodes: readonly SemanticPath[];
+    readonly edges: ReadonlyMap<SemanticPath, readonly SemanticPath[]>;
+};
+/**
+ * Build a dependency graph from ComputedSpec
+ */
+export declare function buildDependencyGraph(computed: ComputedSpec): DependencyGraph;
+/**
+ * Topological sort using Kahn's algorithm
+ * Returns sorted order or error if cycles detected
+ */
+export declare function topologicalSort(graph: DependencyGraph): Result<SemanticPath[], ValidationError>;
+/**
+ * Detect cycles in the dependency graph
+ * Returns array of cycle paths or null if no cycles
+ */
+export declare function detectCycles(graph: DependencyGraph): SemanticPath[][] | null;
+/**
+ * Get all dependencies (transitive) for a given node
+ */
+export declare function getTransitiveDeps(graph: DependencyGraph, node: SemanticPath): Set<SemanticPath>;

package/dist/evaluator/expr.d.ts

@@ -0,0 +1,10 @@
+import type { ExprNode } from "../schema/expr.js";
+import type { ErrorValue } from "../schema/snapshot.js";
+import type { Result } from "../schema/common.js";
+import { type EvalContext } from "./context.js";
+export type ExprResult = Result<unknown, ErrorValue>;
+/**
+ * Evaluate an expression node
+ * All expressions are pure and total (always return a value or error)
+ */
+export declare function evaluateExpr(expr: ExprNode, ctx: EvalContext): ExprResult;

package/dist/evaluator/flow.d.ts

@@ -0,0 +1,35 @@
+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 { TraceNode } from "../schema/trace.js";
+import { type EvalContext } from "./context.js";
+/**
+ * Flow execution status
+ */
+export type FlowStatus = "running" | "complete" | "pending" | "halted" | "error";
+/**
+ * Flow execution state
+ */
+export type FlowState = {
+    readonly snapshot: Snapshot;
+    readonly status: FlowStatus;
+    readonly patches: readonly Patch[];
+    readonly requirements: readonly Requirement[];
+    readonly error: ErrorValue | null;
+};
+/**
+ * Flow evaluation result
+ */
+export type FlowResult = {
+    readonly state: FlowState;
+    readonly trace: TraceNode;
+};
+/**
+ * Create initial flow state
+ */
+export declare function createFlowState(snapshot: Snapshot): FlowState;
+/**
+ * Evaluate a flow node
+ */
+export declare function evaluateFlowSync(flow: FlowNode, ctx: EvalContext, state: FlowState, nodePath: string): FlowResult;
+export declare function evaluateFlow(flow: FlowNode, ctx: EvalContext, state: FlowState, nodePath: string): Promise<FlowResult>;

package/dist/evaluator/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./context.js";
+export * from "./expr.js";
+export * from "./flow.js";
+export * from "./dag.js";
+export * from "./computed.js";

package/dist/factories.d.ts

@@ -0,0 +1,21 @@
+import type { Snapshot } from "./schema/snapshot.js";
+import type { Intent } from "./schema/patch.js";
+import type { HostContext } from "./schema/host-context.js";
+/**
+ * Create a new snapshot with initial data
+ *
+ * @param data - Initial domain data
+ * @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;
+/**
+ * Create an intent
+ *
+ * @param type - Action type
+ * @param input - Action input (optional)
+ * @param intentId - Unique identifier for this processing attempt (optional, auto-generated if not provided)
+ * @returns Intent
+ */
+export declare function createIntent(type: string, intentId: string): Intent;
+export declare function createIntent(type: string, input: unknown, intentId: string): Intent;