@melite/engine-contract 0.1.4-alpha → 0.1.5-pre-alpha

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,55 @@
1
+ ---
2
+ description: The engine Service Definition — the engines seat, engine-agnostic stage types, and the pinned engine-id vocabulary every engine adapter and the runs lane share.
3
+ kind: package-library
4
+ ---
5
+
6
+ # @melite/engine-contract
7
+
8
+ `@melite/engine-contract` declares the one contract every run-path engine
9
+ implements: the `engines` seat registry, the stage-row and executor types,
10
+ and the engine-id grammar. It calls nothing — it is the typed seam the
11
+ ComfyUI, craft, agent, and MCP adapters register into and the runs lane
12
+ resolves through. The estate bundle mounts `enginesContract` before every
13
+ engine adapter row.
14
+
15
+ ## Contract
16
+
17
+ - Engine ids: `comfyui`, `craft`, `agent`, or `mcp:<server>` with the server
18
+ name matching dsh-mcp-client's `[A-Za-z0-9_-]{1,32}`. `register` refuses
19
+ ungrammatical ids and duplicates loud; `resolve` refuses unknown ids loud,
20
+ naming every registered id.
21
+ - One registered engine is `{ executor, probe? }` — the control arm
22
+ `executeStages(rows, runDir, inputNames, options, initials?)` plus an
23
+ optional reachability probe. Connection lifecycle stays with each engine's
24
+ own owner; the probe only reports.
25
+ - Registrations are effects: `register` returns the disposer; providers wrap
26
+ it in `ctx.effect`.
27
+ - Declared exports: `.` (barrel), `./engines` (EnginesService + provider +
28
+ id grammar), `./types` (EngineStageRow, EngineStageOutcome,
29
+ EngineExecutor), `./vocabulary` (the engine-agnostic ParamSpec grammar),
30
+ `./package.json`.
31
+
32
+ ## Model Experience
33
+
34
+ ### Request context and condition
35
+
36
+ #### What the model sees
37
+
38
+ None — the package contributes no model-visible input.
39
+
40
+ #### Token effect
41
+
42
+ Zero-direct token effect.
43
+
44
+ #### KV Cache effect
45
+
46
+ Independent — the seat holds no conversation state.
47
+
48
+ ## Known Limitations and Deferred Work
49
+
50
+ - **No capability-listing face** — the seat resolves ids; it does not
51
+ enumerate per-engine params. Served forms come from each engine's own doc
52
+ module.
53
+ - **initials is optional and dialect-bound** — engines whose param dialect
54
+ has no `$spells` ignore run initials; nothing enforces a uniform
55
+ treatment.
package/lib/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  export type { EngineParamValue, EngineStageRow, EngineStageOutcome, EngineRunOutcome, EngineRunOptions, EngineExecutor, EngineRecord, } from "./types.js";
2
2
  export type { PortSpec, ParamSpec, ActionSpec } from "./vocabulary.js";
3
- export { EnginesService, engineIdOk, enginesContract } from "./engines.js";
3
+ export { AGENT_ENGINE_ID, COMFYUI_ENGINE_ID, CRAFT_ENGINE_ID, EnginesService, engineIdOk, enginesContract, } from "./engines.js";
4
4
  export { enginesContract as default } from "./engines.js";
5
5
  //# sourceMappingURL=index.d.ts.map
package/lib/index.js CHANGED
@@ -1,3 +1,3 @@
1
- export { EnginesService, engineIdOk, enginesContract } from "./engines.js";
1
+ export { AGENT_ENGINE_ID, COMFYUI_ENGINE_ID, CRAFT_ENGINE_ID, EnginesService, engineIdOk, enginesContract, } from "./engines.js";
2
2
  export { enginesContract as default } from "./engines.js";
3
3
  //# sourceMappingURL=index.js.map
package/lib/types.d.ts CHANGED
@@ -36,6 +36,11 @@ export interface EngineStageOutcome {
36
36
  export interface EngineRunOutcome {
37
37
  readonly stages: readonly EngineStageOutcome[];
38
38
  readonly engineRef?: string;
39
+ /** THE REPLAY VERDICT (D11): true when the executor's seated tap
40
+ * folded zero engine events before settlement — the engine served
41
+ * memo'd outputs without executing. Optional so existing
42
+ * executors stay assignable (absent = unknown, never clean). */
43
+ readonly replaySuspect?: boolean;
39
44
  }
40
45
  /** The run-path's signals into the executor: the stop flag (the
41
46
  * user's stop press) and the progress tap (stage activity /
@@ -44,6 +49,11 @@ export interface EngineRunOutcome {
44
49
  export interface EngineRunOptions {
45
50
  shouldStop(): boolean;
46
51
  report(updates: Record<string, unknown>): void;
52
+ /** §23 cross-roots manifest extras (J12: config-named by the
53
+ * queue seat — the trees a chained-input estate URL may
54
+ * resolve under beyond the run's own output root; optional so
55
+ * existing executors stay assignable). */
56
+ readonly stateRoots?: readonly string[];
47
57
  }
48
58
  /** The control arm: execute stages of one run. The ComfyUI
49
59
  * executor keeps the MERGED single-graph law internally (rows
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@melite/engine-contract",
3
- "version": "0.1.4-alpha",
3
+ "version": "0.1.5-pre-alpha",
4
4
  "license": "SSPL-1.0",
5
5
  "type": "module",
6
6
  "description": "The engine Service Definition (stroke 53, the engine-generics seam): one registry seat every engine provider registers into and every run-path consumer resolves through — ComfyUI today, MCP servers (blender/unity/godot) next. Stage rows are engine-agnostic; graph surgery (spliceWorkflow) stays inside the owning engine's executor. Source-plane TS (erasable syntax, no build step).",