@manifesto-ai/compiler 3.9.0 → 5.0.1

package/README.md

@@ -1,16 +1,22 @@
 # @manifesto-ai/compiler
 
-> **Compiler** translates MEL (Manifesto Expression Language) into DomainSchema for Manifesto Core.
+> **Compiler** lets apps import MEL domains and can emit generated SDK domain facades.
 
 ---
 
 ## What is the Compiler?
 
-The compiler is the MEL frontend for Manifesto. It tokenizes, parses, validates, and lowers MEL source into a DomainSchema that Core can evaluate deterministically.
+The compiler is the MEL frontend for Manifesto. For app developers, it lets a
+bundler import `.mel` files and optionally emit the generated
+`<source>.domain.ts` facade used by `createManifesto<TDomain>()`.
 
+```text
+.mel source -> compiler plugin -> createManifesto()
+                              -> optional generated <source>.domain.ts facade
 ```
-MEL source -> Compiler -> DomainSchema -> Core
-```
+
+Internally, the compiler tokenizes, parses, validates, and lowers MEL source
+into the runtime schema consumed behind the SDK app path.
 
 ---
 
@@ -19,9 +25,10 @@ MEL source -> Compiler -> DomainSchema -> Core
 | Responsibility | Description |
 | --- | --- |
 | Parse MEL | Tokenize and parse MEL into an AST |
-| Validate | Scope, typing, and semantic checks aligned to the current compiler contract |
-| Generate IR | Produce DomainSchema for Core |
-| Lower system values | Optional lowering of $system.* into explicit effects |
+| Validate | Scope, typing, and domain-rule checks aligned to the current compiler contract |
+| Emit runtime schema | Produce the schema imported by `createManifesto()` |
+| Emit optional TypeScript facade | Write generated domain types for larger SDK apps |
+| Lower runtime/context expressions | Lower `$runtime.*` and `$context.*` references for deterministic runtime evaluation |
 
 ---
 
@@ -29,15 +36,15 @@ MEL source -> Compiler -> DomainSchema -> Core
 
 | NOT Responsible For | Who Is |
 | --- | --- |
-| Execute effects | Host |
-| Apply patches | Core |
-| Govern authority or seal history | `@manifesto-ai/governance` + `@manifesto-ai/lineage` |
+| Execute external work | Runtime effect handlers |
+| Apply domain transitions | Manifesto runtime |
+| Add optional approval/history protocols | `@manifesto-ai/governance` + `@manifesto-ai/lineage` |
 | Bind UI or caller integrations | SDK / application layer |
 
 Current MEL/compiler highlights:
 
 - `available when` remains the coarse action gate.
-- `dispatchable when` is the fine bound-intent legality gate.
+- `dispatchable when` is the fine input-specific legality gate.
 - Expression-level collection builtins include `filter`, `map`, `find`, `every`, and `some`.
 - Bounded parser-free sugar includes `absDiff`, `clamp`, `idiv`, `streak`, `match`, `argmax`, and `argmin`.
 - Current schema-position lowering supports `Record<string, T>` and `T | null`.
@@ -122,31 +129,32 @@ import { createCompilerCodegen } from "@manifesto-ai/codegen";
 
 melPlugin({
   include: /\.mel$/,           // File filter (default: /\.mel$/)
-  codegen: {
-    emit: createCompilerCodegen(),
-    timing: "transform",       // default: run during dev/build transforms
-  },
+  codegen: createCompilerCodegen(),
 });
 ```
 
-`codegen` is an explicit emitter hook. `@manifesto-ai/compiler` does not import `@manifesto-ai/codegen` for you; install it only if you want MEL artifacts written during dev or build and inject the emitter yourself.
+`codegen` is an explicit emitter hook. `@manifesto-ai/compiler` does not import
+`@manifesto-ai/codegen` for you; install it only if you want MEL artifacts
+written during dev or build and inject the emitter yourself.
 
-`createCompilerCodegen()` can be called with no options. In that default mode it uses the canonical domain plugin and writes `<source>.domain.ts` next to the compiled `.mel` file during transform. If you prefer build-end emission, set `timing: "build"` or `timing: "both"`. You can still customize the pipeline:
+`createCompilerCodegen()` can be called with no options. In that default mode
+it writes `<source>.domain.ts` next to the compiled `.mel` file during
+transform. You can still customize the generated facade:
 
 ```typescript
 import { createCompilerCodegen, createDomainPlugin } from "@manifesto-ai/codegen";
 
 melPlugin({
-  codegen: {
-    emit: createCompilerCodegen({
-      outDir: "src/generated",
-      plugins: [createDomainPlugin({ interfaceName: "CounterDomain" })],
-    }),
-    timing: "build",
-  },
+  codegen: createCompilerCodegen({
+    outDir: "src/generated",
+    plugins: [createDomainPlugin({ interfaceName: "TodoDomain" })],
+  }),
 });
 ```
 
+Advanced build setups can still pass `{ emit, timing }` when they need build-end
+or dual transform/build emission.
+
 ### Subpath Exports
 
 | Export | Bundler |
@@ -181,12 +189,12 @@ const source = `
 domain Counter {
   state { count: number = 0 }
   action increment() {
-    when true { patch count = add(count, 1) }
+    onceIntent { patch count = count + 1 }
   }
 }
 `;
 
-const result = compile(source, { lowerSystemValues: true });
+const result = compile(source);
 
 if (!result.success) {
   console.error(result.errors);
@@ -202,10 +210,13 @@ const errors = check(source);
 ```typescript
 type CompileOptions = {
   skipSemanticAnalysis?: boolean;
-  lowerSystemValues?: boolean;
 };
 ```
 
+Legacy compatibility options may still exist for older call sites, but they are
+not current v5 integration seams. Runtime facts are represented through
+`$runtime.*` and explicit Core `Context`, not compiler-lowered system values.
+
 ---
 
 ## Documentation
@@ -216,7 +227,7 @@ type CompileOptions = {
 | [MEL Syntax](../../docs/mel/SYNTAX.md) | Grammar and syntax |
 | [MEL Examples](../../docs/mel/EXAMPLES.md) | Example library |
 | [MEL Error Guide](../../docs/mel/ERROR-GUIDE.md) | Error codes and fixes |
-| [Compiler Spec](docs/SPEC-v1.1.0.md) | Current full compiler and MEL spec |
+| [Compiler Spec](docs/SPEC-v1.2.0.md) | Current full compiler and MEL spec |
 | [Compiler FDR](docs/FDR-v0.5.0.md) | Design rationale |
 | [Compiler Compliance Suite](docs/compiler-SPEC-compilance-test-suite.md) | CCTS structure, rule modes, and execution guide |
 

package/dist/analyzer/expr-type-surface.d.ts

@@ -6,6 +6,7 @@ export type TypeEnv = Map<string, TypeExprNode>;
 export type ComparableSurfaceClass = "primitive" | "nonprimitive" | "unknown";
 export interface DomainTypeSymbols {
     stateTypes: Map<string, TypeExprNode>;
+    contextTypes: Map<string, TypeExprNode>;
     computedDecls: Map<string, ComputedNode>;
     typeDefs: Map<string, TypeDeclNode>;
     computedTypeCache: Map<string, TypeExprNode | null>;

package/dist/analyzer/validator.d.ts

@@ -31,6 +31,7 @@ export declare class SemanticValidator {
      * v0.3.3: Validate state field - check for anonymous object types (W012)
      */
     private validateStateField;
+    private validateContext;
     private validateStateInitializer;
     /**
      * v0.3.3: Check if a type expression contains anonymous object types
@@ -39,13 +40,13 @@ export declare class SemanticValidator {
     private checkAnonymousObjectType;
     private validateAction;
     /**
-     * v0.3.3: Validate available expression is pure (E005)
-     * No $system.*, no effects, no $input.*
+     * v0.3.3: Validate available expression is pure (E005).
+     * No dollar namespace reads or action parameters.
      */
     private validateAvailableExpr;
     /**
-     * v0.9.0: Validate dispatchable expression is pure (E047)
-     * Allows state/computed/action params, but forbids direct $input.*, $meta.*, and $system.*.
+     * v0.9.0: Validate dispatchable expression is pure (E047).
+     * Allows state/computed/action params, but forbids direct dollar namespace reads.
      */
     private validateDispatchableExpr;
     private validateGuardedStmt;
@@ -58,6 +59,8 @@ export declare class SemanticValidator {
     private validateStop;
     private validateCondition;
     private validateExpr;
+    private validateDollarIdent;
+    private validateContextPath;
     private validateFunctionCall;
     private validatePrimitiveEquality;
     private inferType;
@@ -69,7 +72,6 @@ export declare class SemanticValidator {
     private validateMatchCall;
     private validateArgSelectionCall;
     private error;
-    private warn;
 }
 /**
  * Validate a MEL program semantically

package/dist/api/compile-mel-patch-collector.d.ts

@@ -4,11 +4,9 @@ import type { MelIRPatchPath } from "../lowering/lower-runtime-patch.js";
 import type { GuardedStmtNode, InnerStmtNode, PatchStmtNode } from "../parser/ast.js";
 import { toMelExpr } from "./compile-mel-patch-expr.js";
 export interface PatchCollectContext {
-    actionName: string;
-    onceCounter: number;
-    onceIntentCounter: number;
-    whenCounter: number;
+    readonly actionName: string;
 }
+type AllowedSysPrefix = "input" | "runtime" | "context";
 export type ConditionedPatchStatement = {
     patch: PatchStmtNode;
     condition?: MelExprNode;
@@ -19,11 +17,11 @@ export interface PatchCollectorDeps {
 }
 export declare class PatchStatementCollector {
     private readonly deps;
-    private readonly conditionComposer;
     private readonly exprValidator;
-    constructor(deps: PatchCollectorDeps);
+    constructor(deps: PatchCollectorDeps, allowSysPrefixes?: readonly AllowedSysPrefix[]);
     collect(stmts: GuardedStmtNode[] | InnerStmtNode[], errors: Diagnostic[], context: PatchCollectContext, parentCondition: MelExprNode | undefined): ConditionedPatchStatement[];
     private collectPatchStatements;
+    private pushUnsupportedControlError;
 }
 export declare function compilePatchStmtToMelRuntime(patchStatement: ConditionedPatchStatement): {
     op: "set" | "unset" | "merge";
@@ -31,3 +29,4 @@ export declare function compilePatchStmtToMelRuntime(patchStatement: Conditioned
     value?: MelExprNode;
     condition?: MelExprNode;
 };
+export {};

package/dist/api/compile-mel.d.ts

@@ -81,11 +81,11 @@ export interface CompileMelPatchOptions {
      */
     actionName: string;
     /**
-     * Allowed system path prefixes.
-     * Default: ["meta", "input"] (system is forbidden per §20.3).
+     * Allowed dollar namespace prefixes.
+     * Default: ["input", "runtime", "context"].
      */
     allowSysPaths?: {
-        prefixes: ("meta" | "input")[];
+        prefixes: ("input" | "runtime" | "context")[];
     };
     /**
      * Function table version.
@@ -140,7 +140,7 @@ export declare function compileMelModule(melText: string, options?: CompileMelMo
  * by evaluateRuntimePatches() to get concrete values.
  *
  * Constraints:
- * - §20.3: $system.* is forbidden in Translator path
+ * - ADR-027: `$system.*` and `$meta.*` are retired in current v5 MEL.
  *
  * @param melText - MEL patch source text
  * @param options - Compilation options

package/dist/api/index.d.ts

@@ -5,7 +5,7 @@
  *
  * @see SPEC v0.4.0 §19
  */
-export type { Annotation, AnnotationIndex, CompileTrace, CompileMelDomainOptions, CompileMelDomainResult, CompileMelModuleOptions, CompileMelModuleResult, CompileMelPatchOptions, CompileMelPatchResult, DomainModule, JsonLiteral, LocalTargetKey, SourceMapEmissionContext, SourceMapEntry, SourceMapIndex, SourceMapPath, SourcePoint, SourceSpan, } from "./compile-mel.js";
+export type { Annotation, AnnotationIndex, CompileTrace, CompileMelDomainOptions, CompileMelDomainResult, CompileMelModuleOptions, CompileMelModuleResult, DomainModule, JsonLiteral, LocalTargetKey, SourceMapEmissionContext, SourceMapEntry, SourceMapIndex, SourceMapPath, SourcePoint, SourceSpan, } from "./compile-mel.js";
 export type { CompileFragmentInContextOptions, MelEditAddActionOp, MelEditAddAvailableOp, MelEditAddComputedOp, MelEditAddDispatchableOp, MelEditAddStateFieldOp, MelEditAddTypeOp, MelEditOp, MelEditRemoveDeclarationOp, MelEditRenameDeclarationOp, MelEditReplaceActionBodyOp, MelEditReplaceAvailableOp, MelEditReplaceComputedExprOp, MelEditReplaceDispatchableOp, MelEditReplaceStateDefaultOp, MelEditReplaceTypeFieldOp, MelEditResult, MelParamSource, MelTextEdit, SchemaDiff, SchemaModifiedTarget, } from "./compile-fragment-in-context.js";
-export { compileMelDomain, compileMelModule, compileMelPatch } from "./compile-mel.js";
+export { compileMelDomain, compileMelModule } from "./compile-mel.js";
 export { compileFragmentInContext } from "./compile-fragment-in-context.js";