taskflow-core 0.1.8 → 0.2.0

package/dist/flowir/canonical-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-hash.d.ts","sourceRoot":"","sources":["../../src/flowir/canonical-hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA8EtD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAoBrD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAEzD;AAMD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAG7C;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAGjD"}

package/dist/flowir/canonical-hash.js

@@ -0,0 +1,219 @@
+/**
+ * # Genuine content-addressed hash over canonical FlowIR
+ *
+ * This is pi-taskflow's **own** content-addressed hash (Q5=own) over the
+ * canonical {@link FlowIR} type contract defined in `./schema.ts`. Unlike
+ * `./hash.ts`'s `flowDefHash` — which fingerprints the *DSL Taskflow
+ * definition* (vendored from overstory, async Web Crypto, truncated to 16
+ * bytes / 32 hex) — this module hashes the *compiled IR* synchronously with
+ * `node:crypto` SHA-256 (full 64-hex-char digest). The two answer different
+ * questions:
+ *
+ * - `flowDefHash(def)`  — "did the *flow definition* change?" (DSL-level)
+ * - `hashFlowIR(ir)`    — "is this *compiled IR* the same IR?" (IR-level)
+ *
+ * Wired into `compileTaskflowToIR` via `hashFlowIR` (`ir:<64-hex>`).
+ * The IR-level hash is the content-addressed key the event-sourced kernel
+ * (batch 2, `flowir/compile.ts`) will use to deduplicate compiled graphs and
+ * to key per-phase fingerprints (`hashNode`) independent of surface formatting.
+ *
+ * ## Canonicalization guarantees
+ *
+ * {@link canonicalizeFlowIR} produces a DETERMINISTIC serialization that is
+ * invariant under the cosmetic differences two logically-equivalent IRs may
+ * differ by:
+ *
+ * - **Object key order** — all object keys are stable-sorted (UTF-16 code
+ *   units), so reordering fields on a node or on the IR object does not
+ *   change the canonical form.
+ * - **Node array order** — `nodes` is re-sorted by `id` (stable), so two IRs
+ *   that list the same nodes in different order canonicalize identically.
+ *   Other arrays (`inject`, `emits`, `deps`, `edges`) keep their order —
+ *   their ordering is semantically meaningful (declared-read order, edge
+ *   declaration order) and must be preserved.
+ * - **Condition spelling** — a node's `when` guard is canonicalized via
+ *   {@link normalizeCond} (`./cond.ts`), which collapses whitespace, operator
+ *   spacing, and redundant enclosing parens while preserving string-literal
+ *   contents. Equivalent conditions canonicalize identically.
+ * - **Insignificant formatting** — `undefined` optional fields are dropped,
+ *   so their presence/absence does not change the hash.
+ *
+ * Two logically-equivalent FlowIRs (key reorder, whitespace, equivalent
+ * condition spelling) MUST canonicalize to the same string.
+ *
+ * ## Domain-separated digests
+ *
+ * Return values are prefixed:
+ * - `hashFlowIR` → `ir:<64-hex>`
+ * - `hashNode`   → `node:<64-hex>`
+ *
+ * so IR-level and node-level digests never collide in a shared cache key
+ * namespace.
+ *
+ * ## Purity
+ *
+ * Zero runtime deps besides `node:crypto`. No IO, no `Date`, no randomness,
+ * never throws. The hash is synchronous (unlike `flowDefHash`).
+ *
+ * Exported from the FlowIR barrel (`./index.ts`) for consumers; **not yet
+ * wired** into runtime/cache — `usedFallbackHash` is untouched. Wiring
+ * happens in batch 2.
+ *
+ * @see ./schema.ts for the canonical FlowIR type contract.
+ * @see ./cond.ts for condition normalization (`normalizeCond`).
+ * @see ./hash.ts for the DSL-level `flowDefHash` (vendored from overstory).
+ */
+import { createHash } from "node:crypto";
+import { normalizeCond } from "./cond.js";
+// ---------------------------------------------------------------------------
+// Canonical serializer (key-sorted, undefined-dropped, array-order-preserving)
+// ---------------------------------------------------------------------------
+/**
+ * Deterministic serialization of a plain-JSON-compatible value: recursively
+ * key-sorts objects (UTF-16 code units), drops `undefined` values, preserves
+ * array order, and uses `JSON.stringify` for primitives/null. This mirrors
+ * the canonical-JSON convention used by `./hash.ts`'s `canonicalJson` (itself
+ * vendored from overstory) so the two hashes share the same primitive
+ * encoding — but this serializer is local to the IR hash so the IR-level
+ * contract can evolve independently of the overstory-vendored DSL hash.
+ *
+ * The value passed in MUST be pre-canonicalized (nodes sorted by id, `when`
+ * normalized) — this function does not know about FlowIR semantics, it only
+ * guarantees key-order independence and `undefined`-dropping.
+ */
+function canonicalSerialize(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return JSON.stringify(value);
+    if (typeof value === "number")
+        return JSON.stringify(value);
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalSerialize(item)).join(",")}]`;
+    }
+    if (typeof value === "object") {
+        const record = value;
+        const keys = Object.keys(record)
+            .filter((key) => record[key] !== undefined)
+            .sort();
+        const body = keys.map((key) => `${JSON.stringify(key)}:${canonicalSerialize(record[key])}`);
+        return `{${body.join(",")}}`;
+    }
+    // undefined / function / symbol / bigint at this layer — not representable.
+    return "null";
+}
+// ---------------------------------------------------------------------------
+// Canonical node object (drops undefined, normalizes `when`)
+// ---------------------------------------------------------------------------
+/**
+ * Project a {@link FlowIRNode} into a plain canonical object form: fields are
+ * emitted in a fixed order (order is irrelevant — `canonicalSerialize`
+ * re-sorts keys, but emitting canonically makes the intermediate form
+ * human-inspectable), `when` is normalized via {@link normalizeCond} so
+ * equivalent condition spellings collapse, and `undefined` optionals are
+ * omitted so their presence/absence does not affect the hash.
+ *
+ * `inject`/`emits`/`deps` arrays are preserved verbatim (order is semantic —
+ * declared-read order matters for fingerprinting).
+ */
+function canonicalNodeObject(node) {
+    const obj = {
+        id: node.id,
+        kind: node.kind,
+        inject: node.inject,
+        emits: node.emits,
+    };
+    if (node.when !== undefined) {
+        obj.when = normalizeCond(node.when).canonical;
+    }
+    if (node.task !== undefined)
+        obj.task = node.task;
+    if (node.condRef !== undefined)
+        obj.condRef = node.condRef;
+    if (node.deps !== undefined)
+        obj.deps = node.deps;
+    if (node.join !== undefined)
+        obj.join = node.join;
+    if (node.timeout !== undefined)
+        obj.timeout = node.timeout;
+    if (node.payload !== undefined)
+        obj.payload = node.payload;
+    return obj;
+}
+// ---------------------------------------------------------------------------
+// Public canonicalization
+// ---------------------------------------------------------------------------
+/**
+ * Deterministic, order- and whitespace-independent canonical serialization of
+ * a {@link FlowIR}.
+ *
+ * - `nodes` is re-sorted by `id` (stable) so node-list order does not affect
+ *   the result.
+ * - Each node's `when` guard is canonicalized via {@link normalizeCond}.
+ * - All object keys are stable-sorted; `undefined` optionals are dropped.
+ * - `inject`/`emits`/`deps`/`edges` arrays keep their order (semantic).
+ *
+ * Two logically-equivalent FlowIRs MUST canonicalize to the same string.
+ * Never throws.
+ */
+export function canonicalizeFlowIR(ir) {
+    // Stable sort by node id — node-list order is not semantic.
+    const sortedNodes = [...ir.nodes].sort((a, b) => {
+        if (a.id < b.id)
+            return -1;
+        if (a.id > b.id)
+            return 1;
+        return 0;
+    });
+    const obj = {
+        name: ir.name,
+        nodes: sortedNodes.map((n) => canonicalNodeObject(n)),
+    };
+    if (ir.version !== undefined)
+        obj.version = ir.version;
+    if (ir.edges !== undefined)
+        obj.edges = ir.edges;
+    if (ir.args !== undefined)
+        obj.args = ir.args;
+    if (ir.budget !== undefined)
+        obj.budget = ir.budget;
+    if (ir.concurrency !== undefined)
+        obj.concurrency = ir.concurrency;
+    if (ir.meta !== undefined)
+        obj.meta = ir.meta;
+    return canonicalSerialize(obj);
+}
+/**
+ * Deterministic canonical serialization of a single {@link FlowIRNode}, for
+ * per-node content addressing. Same canonicalization rules as
+ * {@link canonicalizeFlowIR} applied to one node (`when` normalized, keys
+ * sorted, `undefined` optionals dropped, `inject`/`emits`/`deps` order
+ * preserved). Never throws.
+ */
+export function canonicalizeNode(node) {
+    return canonicalSerialize(canonicalNodeObject(node));
+}
+// ---------------------------------------------------------------------------
+// Content-addressed hashing (node:crypto SHA-256, domain-prefixed)
+// ---------------------------------------------------------------------------
+/**
+ * Domain-separated content hash of a compiled FlowIR.
+ * Returns `ir:<64 lowercase hex SHA-256 chars>` over {@link canonicalizeFlowIR}.
+ * Synchronous. Never throws.
+ */
+export function hashFlowIR(ir) {
+    const hex = createHash("sha256").update(canonicalizeFlowIR(ir), "utf8").digest("hex");
+    return `ir:${hex}`;
+}
+/**
+ * Domain-separated per-node content hash.
+ * Returns `node:<64 lowercase hex SHA-256 chars>` over {@link canonicalizeNode}.
+ * Synchronous. Never throws.
+ */
+export function hashNode(node) {
+    const hex = createHash("sha256").update(canonicalizeNode(node), "utf8").digest("hex");
+    return `node:${hex}`;
+}
+//# sourceMappingURL=canonical-hash.js.map

package/dist/flowir/canonical-hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-hash.js","sourceRoot":"","sources":["../../src/flowir/canonical-hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C,8EAA8E;AAC9E,+EAA+E;AAC/E,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,SAAS,kBAAkB,CAAC,KAAc;IACzC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC7D,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC5D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACvE,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,KAAgC,CAAC;QAChD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;aAC9B,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;aAC1C,IAAI,EAAE,CAAC;QACT,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,kBAAkB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;QAC5F,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAC9B,CAAC;IACD,4EAA4E;IAC5E,OAAO,MAAM,CAAC;AACf,CAAC;AAED,8EAA8E;AAC9E,6DAA6D;AAC7D,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,SAAS,mBAAmB,CAAC,IAAgB;IAC5C,MAAM,GAAG,GAA4B;QACpC,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,KAAK,EAAE,IAAI,CAAC,KAAK;KACjB,CAAC;IACF,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,GAAG,CAAC,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC;IAC/C,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;QAAE,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IAClD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;QAAE,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAC3D,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;QAAE,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IAClD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;QAAE,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IAClD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;QAAE,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAC3D,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;QAAE,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAC3D,OAAO,GAAG,CAAC;AACZ,CAAC;AAED,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAU;IAC5C,4DAA4D;IAC5D,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAC/C,IAAI,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE;YAAE,OAAO,CAAC,CAAC,CAAC;QAC3B,IAAI,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE;YAAE,OAAO,CAAC,CAAC;QAC1B,OAAO,CAAC,CAAC;IACV,CAAC,CAAC,CAAC;IAEH,MAAM,GAAG,GAA4B;QACpC,IAAI,EAAE,EAAE,CAAC,IAAI;QACb,KAAK,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;KACrD,CAAC;IACF,IAAI,EAAE,CAAC,OAAO,KAAK,SAAS;QAAE,GAAG,CAAC,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC;IACvD,IAAI,EAAE,CAAC,KAAK,KAAK,SAAS;QAAE,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC;IACjD,IAAI,EAAE,CAAC,IAAI,KAAK,SAAS;QAAE,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC;IAC9C,IAAI,EAAE,CAAC,MAAM,KAAK,SAAS;QAAE,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC;IACpD,IAAI,EAAE,CAAC,WAAW,KAAK,SAAS;QAAE,GAAG,CAAC,WAAW,GAAG,EAAE,CAAC,WAAW,CAAC;IACnE,IAAI,EAAE,CAAC,IAAI,KAAK,SAAS;QAAE,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC;IAE9C,OAAO,kBAAkB,CAAC,GAAG,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAgB;IAChD,OAAO,kBAAkB,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,8EAA8E;AAC9E,mEAAmE;AACnE,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,EAAU;IACpC,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,kBAAkB,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACtF,OAAO,MAAM,GAAG,EAAE,CAAC;AACpB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAgB;IACxC,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACtF,OAAO,QAAQ,GAAG,EAAE,CAAC;AACtB,CAAC"}

package/dist/flowir/compile.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Genuine Taskflow → FlowIR compiler (RFC §5.2, S0).
+ *
+ * This graduates the stub `translateTaskflow` into a **canonical** IR emitter:
+ * 1:1 phase→node projection (native multi-node lowering deferred per §12),
+ * declared inject/emits, explicit edges, normalized `when` via {@link normalizeCond},
+ * and richer optional node fields (`task`, `deps`, `join`, `timeout`, `condRef`).
+ *
+ * Pure, synchronous, never throws — diagnostics live in the return value so
+ * `/tf ir` on a broken flow still yields a structured report.
+ *
+ * @see docs/rfc-0.2.0-architecture.md §5
+ * @see ./translate.ts (stub; still used for sidecar field list parity)
+ */
+import { type Taskflow } from "../schema.ts";
+import type { FlowIR as CanonicalFlowIR } from "./schema.ts";
+import type { CompileError, CompileWarning, FlowIR, TaskflowIRMeta } from "./meta.ts";
+/**
+ * Result of {@link compileTaskflowToFlowIR}: canonical IR + declared meta + diagnostics.
+ * `usedFallbackHash` is **false** when the IR is well-formed enough to content-address
+ * (always, unless hard errors prevent IR emission).
+ *
+ * Named separately from Mermaid `compileTaskflow` in `../compile.ts` (diagram).
+ */
+export interface CompileTaskflowToFlowIRResult {
+    /** Canonical FlowIR (superset of the stub projection). */
+    canonical: CanonicalFlowIR;
+    /** Stub-compatible IR projection (same nodes without requiring consumers to import schema.ts). */
+    ir: FlowIR;
+    meta: TaskflowIRMeta;
+    warnings: CompileWarning[];
+    errors: CompileError[];
+    /** False once the genuine compiler owns the hash (S0). */
+    usedFallbackHash: boolean;
+}
+/**
+ * Compile a (desugared) Taskflow into canonical FlowIR.
+ *
+ * - One node per phase (1:1).
+ * - `inject` = `{steps.*}` refs ∪ `dependsOn` (minus self).
+ * - `emits` = `[phase.id]`.
+ * - `edges` synthesized from inject for graph consumers.
+ * - `when` kept as source text; `condRef` = normalizeCond(canonical) when present.
+ * - Optional fields: task, deps, join, timeout copied when set.
+ *
+ * Never throws.
+ */
+export declare function compileTaskflowToFlowIR(def: Taskflow): CompileTaskflowToFlowIRResult;
+//# sourceMappingURL=compile.d.ts.map

package/dist/flowir/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/flowir/compile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAwD,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAEnG,OAAO,KAAK,EACX,MAAM,IAAI,eAAe,EAIzB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACX,YAAY,EACZ,cAAc,EAEd,MAAM,EAEN,cAAc,EACd,MAAM,WAAW,CAAC;AA4EnB;;;;;;GAMG;AACH,MAAM,WAAW,6BAA6B;IAC7C,0DAA0D;IAC1D,SAAS,EAAE,eAAe,CAAC;IAC3B,kGAAkG;IAClG,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,0DAA0D;IAC1D,gBAAgB,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,QAAQ,GAAG,6BAA6B,CA+HpF"}

package/dist/flowir/compile.js

@@ -0,0 +1,219 @@
+/**
+ * Genuine Taskflow → FlowIR compiler (RFC §5.2, S0).
+ *
+ * This graduates the stub `translateTaskflow` into a **canonical** IR emitter:
+ * 1:1 phase→node projection (native multi-node lowering deferred per §12),
+ * declared inject/emits, explicit edges, normalized `when` via {@link normalizeCond},
+ * and richer optional node fields (`task`, `deps`, `join`, `timeout`, `condRef`).
+ *
+ * Pure, synchronous, never throws — diagnostics live in the return value so
+ * `/tf ir` on a broken flow still yields a structured report.
+ *
+ * @see docs/rfc-0.2.0-architecture.md §5
+ * @see ./translate.ts (stub; still used for sidecar field list parity)
+ */
+import { collectRefs, PHASE_TYPES } from "../schema.js";
+import { normalizeCond } from "./cond.js";
+// Keep in sync with translate.ts SIDECAR_PHASE_FIELDS (round-trip lossless).
+const SIDECAR_PHASE_FIELDS = [
+    "agent",
+    "task",
+    "over",
+    "as",
+    "branches",
+    "from",
+    "use",
+    "def",
+    "with",
+    "run",
+    "input",
+    "timeout",
+    "until",
+    "maxIterations",
+    "convergence",
+    "reflexion",
+    "variants",
+    "judge",
+    "judgeAgent",
+    "mode",
+    "dependsOn",
+    "join",
+    "when",
+    "retry",
+    "output",
+    "expect",
+    "model",
+    "thinking",
+    "tools",
+    "cwd",
+    "final",
+    "optional",
+    "idempotent",
+    "concurrency",
+    "context",
+    "contextLimit",
+    "onBlock",
+    "eval",
+    "score",
+    "cache",
+    "shareContext",
+    "cancelLosers",
+    "expandMode",
+    "maxNodes",
+];
+const NODE_FIELD_KEYS = new Set(["task", "dependsOn", "join", "when", "timeout"]);
+const VALID_KINDS = new Set(PHASE_TYPES);
+function sidecarForPhase(phase) {
+    const out = {};
+    const rec = phase;
+    for (const k of SIDECAR_PHASE_FIELDS) {
+        if (k in rec && rec[k] !== undefined)
+            out[k] = rec[k];
+    }
+    return out;
+}
+function payloadForPhase(phase) {
+    const sidecar = sidecarForPhase(phase);
+    for (const key of NODE_FIELD_KEYS)
+        delete sidecar[key];
+    return Object.keys(sidecar).length > 0 ? sidecar : undefined;
+}
+function asKind(type) {
+    const k = (type ?? "agent");
+    if (VALID_KINDS.has(k))
+        return k;
+    // Unknown kinds still project as agent for IR shape; validation is source of truth.
+    return "agent";
+}
+/**
+ * Compile a (desugared) Taskflow into canonical FlowIR.
+ *
+ * - One node per phase (1:1).
+ * - `inject` = `{steps.*}` refs ∪ `dependsOn` (minus self).
+ * - `emits` = `[phase.id]`.
+ * - `edges` synthesized from inject for graph consumers.
+ * - `when` kept as source text; `condRef` = normalizeCond(canonical) when present.
+ * - Optional fields: task, deps, join, timeout copied when set.
+ *
+ * Never throws.
+ */
+export function compileTaskflowToFlowIR(def) {
+    const warnings = [];
+    const errors = [];
+    const declaredDeps = {};
+    const sidecarPhases = {};
+    const knownIds = new Set((def.phases ?? []).map((p) => p.id));
+    if (!def.name || typeof def.name !== "string") {
+        errors.push({ code: "missing-name", message: "Taskflow.name is required" });
+    }
+    if (!Array.isArray(def.phases) || def.phases.length === 0) {
+        errors.push({ code: "empty-phases", message: "Taskflow.phases must be a non-empty array" });
+    }
+    const nodes = [];
+    const edges = [];
+    for (const phase of def.phases ?? []) {
+        if (!phase?.id) {
+            errors.push({ code: "missing-phase-id", message: "Phase missing id" });
+            continue;
+        }
+        const refs = collectRefs(phase);
+        const reads = new Set(refs.steps.filter((id) => id !== phase.id));
+        for (const d of phase.dependsOn ?? []) {
+            if (d !== phase.id)
+                reads.add(d);
+        }
+        for (const d of phase.from ?? []) {
+            if (d !== phase.id)
+                reads.add(d);
+        }
+        const inject = Array.from(reads);
+        declaredDeps[phase.id] = { reads: inject, writes: [phase.id] };
+        for (const r of refs.steps) {
+            if (r !== phase.id && !knownIds.has(r)) {
+                warnings.push({
+                    phaseId: phase.id,
+                    message: `references {steps.${r}.*} but no phase '${r}' exists`,
+                });
+            }
+        }
+        const kind = asKind(phase.type);
+        if (phase.type && !VALID_KINDS.has(phase.type)) {
+            warnings.push({
+                phaseId: phase.id,
+                message: `unknown phase type '${phase.type}' — projected as kind 'agent'`,
+            });
+        }
+        const node = {
+            id: phase.id,
+            kind,
+            inject,
+            emits: [phase.id],
+        };
+        if (phase.when !== undefined) {
+            node.when = phase.when;
+            const n = normalizeCond(phase.when);
+            // condRef is a stable, hashable form of the guard (not a storage key).
+            node.condRef = n.canonical || undefined;
+        }
+        if (typeof phase.task === "string")
+            node.task = phase.task;
+        if (phase.dependsOn && phase.dependsOn.length > 0)
+            node.deps = [...phase.dependsOn];
+        if (phase.join === "all" || phase.join === "any")
+            node.join = phase.join;
+        if (typeof phase.timeout === "number")
+            node.timeout = phase.timeout;
+        const payload = payloadForPhase(phase);
+        if (payload)
+            node.payload = payload;
+        for (const from of inject) {
+            edges.push({ from, to: phase.id });
+        }
+        sidecarPhases[phase.id] = sidecarForPhase(phase);
+        nodes.push(node);
+    }
+    const canonical = {
+        name: def.name || "unnamed",
+        version: typeof def.version === "number" ? def.version : 1,
+        nodes,
+        edges: edges.length > 0 ? edges : undefined,
+        args: def.args,
+        budget: def.budget,
+        concurrency: def.concurrency,
+        meta: {
+            source: "taskflow-core",
+            irVersion: 1,
+            // These flow-level switches change agent discovery / runtime inputs and
+            // therefore MUST participate in the content-addressed cache identity.
+            // Keeping them in canonical meta preserves the 1:1 node projection while
+            // preventing two semantically different flows from sharing an IR hash.
+            annotations: {
+                agentScope: def.agentScope ?? "user",
+                contextSharing: def.contextSharing ?? false,
+            },
+        },
+    };
+    // Stub-compatible projection: strip fields meta.FlowIR doesn't declare but keep inject/emits/when/kind.
+    const ir = {
+        name: canonical.name,
+        nodes: nodes.map((n) => ({
+            id: n.id,
+            kind: n.kind,
+            inject: n.inject,
+            emits: n.emits,
+            when: n.when,
+        })),
+        args: def.args,
+        budget: def.budget,
+        concurrency: def.concurrency,
+    };
+    const meta = {
+        sourceFlowName: def.name || "unnamed",
+        declaredDeps,
+        sidecar: { phases: sidecarPhases },
+    };
+    // Genuine compiler owns the IR hash when we produced nodes.
+    const usedFallbackHash = nodes.length === 0 || errors.some((e) => e.code === "empty-phases");
+    return { canonical, ir, meta, warnings, errors, usedFallbackHash };
+}
+//# sourceMappingURL=compile.js.map

package/dist/flowir/compile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.js","sourceRoot":"","sources":["../../src/flowir/compile.ts"],"names":[],"mappings":"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"}

package/dist/flowir/cond.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Canonical normalization of `when` / `until` / `eval` condition expressions.
+ *
+ * This is the **condition-IR seam** of the overstory-convergence roadmap's
+ * FlowIR compiler: it lifts a raw condition string into a stable
+ * {@link NormalizedCond} descriptor that two future consumers share:
+ *
+ *  - **Hashing** (consumer a): structurally-equivalent conditions MUST
+ *    normalize to the same `canonical` string so they fold identically into
+ *    the FlowIR content hash (whitespace, operator spacing, and redundant
+ *    enclosing parens do not change meaning → must not change the hash).
+ *  - **Deterministic replay** (consumer b): the `when-guard` decision is
+ *    re-evaluated from the recorded expression; `refs` tells replay exactly
+ *    which `steps.*` / `args.*` / `env.*` inputs the guard read so it can
+ *    rebind them from the event log without token spend.
+ *
+ * **Single source of truth — no semantic drift.** The condition grammar
+ * (tokenizer + recursive-descent parser + comparison/truthiness semantics)
+ * lives in {@link ../interpolate.ts}. This module REUSES that parser by
+ * delegating parse-validation (and fail-open semantics) to
+ * {@link tryEvaluateCondition} — it does NOT duplicate or reimplement the
+ * tokenizer/parser. If the parser accepts an expression, it is structurally
+ * valid and we normalize its surface text; if the parser rejects it, we
+ * fail open (see {@link normalizeCond}) so a broken guard never silently
+ * drops a phase — matching the project's fail-open-for-guards invariant.
+ *
+ * The `canonical` form is a surface normalization (whitespace removal +
+ * redundant enclosing-paren stripping with string-literal contents
+ * preserved), not a full AST rewrite: for valid expressions whitespace only
+ * separates tokens, so removing it (after protecting quoted literals) yields
+ * a stable concatenation that is invariant under the cosmetic differences
+ * hashing cares about. Reference extraction runs on the **literal-protected**
+ * surface so `{steps.*}` text inside string literals is never treated as a
+ * real dependency.
+ *
+ * Pure module: no IO, no `Date`, no randomness, never throws.
+ *
+ * @see docs/rfc-0.2.0-architecture.md §5.4 (`flowir/cond.ts` — 条件归一化)
+ * @see ../interpolate.ts for the shared condition parser (tokenize / CondParser / compare / tryEvaluateCondition)
+ */
+/**
+ * A condition expression lifted into a stable, hashable descriptor.
+ *
+ * - `source`  — the original expression text, verbatim (never normalized).
+ * - `canonical` — a stable normalized surface form: whitespace-collapsed,
+ *   operator-spacing-invariant, redundant enclosing parens stripped, with
+ *   quoted-string contents preserved. Structurally-equivalent expressions
+ *   produce byte-identical `canonical` strings.
+ * - `refs` — the `steps.<id>…` / `args.<name>…` / `env.<VAR>…` references
+ *   the expression reads (in first-occurrence order, de-duplicated). Empty
+ *   when the expression failed to parse (fail-open). Placeholders that only
+ *   appear inside string literals are **not** counted as refs.
+ */
+export interface NormalizedCond {
+    source: string;
+    canonical: string;
+    refs: string[];
+}
+/**
+ * Normalize a `when` / `until` / `eval` condition expression.
+ *
+ * The expression is parsed (validated) by reusing the shared condition
+ * parser in {@link ../interpolate.ts} via {@link tryEvaluateCondition}; on a
+ * parse error this **fails open** — returning `{ source, canonical:
+ * source.trim(), refs: [] }` — so a malformed guard is never silently
+ * dropped and never crashes a compile/replay pass. This mirrors the
+ * project's fail-open-for-guards invariant (`when` parse errors → phase
+ * still runs). Never throws.
+ *
+ * On success, `canonical` is the whitespace/paren-normalized surface form
+ * (stable for hashing) and `refs` are the `steps.*` / `args.*` / `env.*`
+ * references the expression reads (for replay rebinding). Placeholders that
+ * only appear inside string literals are excluded from `refs`.
+ */
+export declare function normalizeCond(expr: string): NormalizedCond;
+//# sourceMappingURL=cond.d.ts.map

package/dist/flowir/cond.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cond.d.ts","sourceRoot":"","sources":["../../src/flowir/cond.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAQH;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,EAAE,CAAC;CACf;AA6ID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAsB1D"}