@melite/engine-contract 0.1.4-alpha → 0.2.0-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/LICENSE +561 -457
- package/README.md +55 -0
- package/lib/index.d.ts +2 -2
- package/lib/index.js +1 -1
- package/lib/types.d.ts +26 -2
- package/lib/vocabulary.d.ts +6 -2
- package/package.json +4 -4
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
|
-
export type { EngineParamValue, EngineStageRow, EngineStageOutcome, EngineRunOutcome, EngineRunOptions, EngineExecutor, EngineRecord, } from "./types.js";
|
|
1
|
+
export type { EngineParamValue, EngineStageRow, EngineStageOutcome, EngineRunOutcome, EngineRunOptions, EngineExecutor, EngineRecord, EngineRef, } 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
|
@@ -30,12 +30,30 @@ export interface EngineStageOutcome {
|
|
|
30
30
|
readonly outputs: Readonly<Record<string, EngineParamValue>>;
|
|
31
31
|
readonly artifacts: readonly string[];
|
|
32
32
|
}
|
|
33
|
+
declare const BRAND: unique symbol;
|
|
34
|
+
/** A string carrying a compile-time-only brand B (the
|
|
35
|
+
* @deepseek-ai/dsh-brand mechanics, declared local — see the block
|
|
36
|
+
* comment above). */
|
|
37
|
+
type Branded<B extends string> = string & {
|
|
38
|
+
readonly [BRAND]: B;
|
|
39
|
+
};
|
|
40
|
+
/** The engine's own handle for one submitted run (ComfyUI's
|
|
41
|
+
* promptId). Minted ONCE at the transport that pulled it off the
|
|
42
|
+
* wire (comfyui-cordis's /prompt POST), de-branded by nothing —
|
|
43
|
+
* the ledger stores the string it already is. */
|
|
44
|
+
export type EngineRef = Branded<"EngineRef">;
|
|
33
45
|
/** A whole submit's outcome. `engineRef` is the engine's own
|
|
34
46
|
* handle for the submitted work (ComfyUI's promptId) — opaque to
|
|
35
|
-
* the consumer, carried for the ledger
|
|
47
|
+
* the consumer, carried for the ledger; branded at its producer
|
|
48
|
+
* (the dsh-brand convention), never a bare string. */
|
|
36
49
|
export interface EngineRunOutcome {
|
|
37
50
|
readonly stages: readonly EngineStageOutcome[];
|
|
38
|
-
readonly engineRef?:
|
|
51
|
+
readonly engineRef?: EngineRef;
|
|
52
|
+
/** THE REPLAY VERDICT (D11): true when the executor's seated tap
|
|
53
|
+
* folded zero engine events before settlement — the engine served
|
|
54
|
+
* memo'd outputs without executing. Optional so existing
|
|
55
|
+
* executors stay assignable (absent = unknown, never clean). */
|
|
56
|
+
readonly replaySuspect?: boolean;
|
|
39
57
|
}
|
|
40
58
|
/** The run-path's signals into the executor: the stop flag (the
|
|
41
59
|
* user's stop press) and the progress tap (stage activity /
|
|
@@ -44,6 +62,11 @@ export interface EngineRunOutcome {
|
|
|
44
62
|
export interface EngineRunOptions {
|
|
45
63
|
shouldStop(): boolean;
|
|
46
64
|
report(updates: Record<string, unknown>): void;
|
|
65
|
+
/** §23 cross-roots manifest extras (J12: config-named by the
|
|
66
|
+
* queue seat — the trees a chained-input estate URL may
|
|
67
|
+
* resolve under beyond the run's own output root; optional so
|
|
68
|
+
* existing executors stay assignable). */
|
|
69
|
+
readonly stateRoots?: readonly string[];
|
|
47
70
|
}
|
|
48
71
|
/** The control arm: execute stages of one run. The ComfyUI
|
|
49
72
|
* executor keeps the MERGED single-graph law internally (rows
|
|
@@ -70,4 +93,5 @@ export interface EngineRecord {
|
|
|
70
93
|
readonly executor: EngineExecutor;
|
|
71
94
|
readonly probe?: () => Promise<void>;
|
|
72
95
|
}
|
|
96
|
+
export {};
|
|
73
97
|
//# sourceMappingURL=types.d.ts.map
|
package/lib/vocabulary.d.ts
CHANGED
|
@@ -14,10 +14,14 @@ export interface PortSpec<K extends string = string> {
|
|
|
14
14
|
* random, and the one minter resolves it so every node sharing the
|
|
15
15
|
* seed shares the minted value. A variant preset pinning a param
|
|
16
16
|
* the surface does not offer, or a value outside the envelope,
|
|
17
|
-
* refuses at the family door.
|
|
17
|
+
* refuses at the family door. `"image"` is the SCALAR media seat —
|
|
18
|
+
* the value is a media path (a string at the wire), the form face
|
|
19
|
+
* is the picker + upload square, never freehand text (the NO-DROP
|
|
20
|
+
* law's write half: run-899a8448 typed a stage name into a media
|
|
21
|
+
* seat that declared as plain string). */
|
|
18
22
|
export interface ParamSpec {
|
|
19
23
|
readonly name: string;
|
|
20
|
-
readonly type: "number" | "string" | "boolean" | "enum" | "image_list";
|
|
24
|
+
readonly type: "number" | "string" | "boolean" | "enum" | "image" | "image_list";
|
|
21
25
|
readonly bounds?: readonly [number, number];
|
|
22
26
|
readonly options?: readonly string[];
|
|
23
27
|
readonly rule?: "seed-sentinel";
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@melite/engine-contract",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"license": "
|
|
3
|
+
"version": "0.2.0-alpha",
|
|
4
|
+
"license": "AGPL-3.0-or-later",
|
|
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).",
|
|
7
7
|
"exports": {
|
|
@@ -26,7 +26,7 @@
|
|
|
26
26
|
"devDependencies": {
|
|
27
27
|
"@types/node": "^22.20.0",
|
|
28
28
|
"typescript": "^5.9.3",
|
|
29
|
-
"@deepseek-ai/cordis": "^4.0.
|
|
29
|
+
"@deepseek-ai/cordis": "^4.0.5"
|
|
30
30
|
},
|
|
31
31
|
"files": [
|
|
32
32
|
"lib/index.js",
|
|
@@ -34,7 +34,7 @@
|
|
|
34
34
|
"lib/**/*.d.ts"
|
|
35
35
|
],
|
|
36
36
|
"peerDependencies": {
|
|
37
|
-
"@deepseek-ai/cordis": "^4.0.
|
|
37
|
+
"@deepseek-ai/cordis": "^4.0.5"
|
|
38
38
|
},
|
|
39
39
|
"scripts": {
|
|
40
40
|
"build": "tsc -p tsconfig.build.json",
|