@kindgi/flow 0.0.0-bootstrap.0 → 0.1.1

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/** The set of operator names recognized by the DSL, exported for tooling. */
+export const OPERATORS = [
+    'eq',
+    'ne',
+    'lt',
+    'lte',
+    'gt',
+    'gte',
+    'in',
+    'notIn',
+    'exists',
+    'notExists',
+    'truthy',
+    'falsy',
+    'and',
+    'or',
+    'not',
+];
+/**
+ * The set of convergence-mode names recognized by the runtime, exported for
+ * tooling that needs the closed enum without repeating literals.
+ */
+export const CONVERGENCE_MODES = ['all-succeed', 'any-succeed', 'settle-all'];
+/**
+ * The set of subgraph convergence-mode names recognized by the runtime,
+ * exported for tooling that needs the closed enum without duplicating
+ * literals.
+ */
+export const SUBGRAPH_CONVERGENCE_MODES = ['success-only', 'settle-all'];
+/**
+ * Minimum + maximum values for `EdgePolicy.priority`. Kept as exported
+ * constants so downstream tooling (linters, UI editors, docs) can share
+ * the same bounds without duplicating literals.
+ */
+export const EDGE_POLICY_PRIORITY_MIN = -100;
+export const EDGE_POLICY_PRIORITY_MAX = 100;
+/** The `EdgePolicy.priority` default when the field is unset. */
+export const EDGE_POLICY_PRIORITY_DEFAULT = 0;
+/**
+ * Sentinel node ids used by flow edges. `$start` / `$end` are the outer
+ * flow's entry/exit. `$loop-start` / `$loop-end` are the body-scope
+ * entry/exit inside a loop node.
+ *
+ * These sentinels are never present in `flow.nodes` or `LoopBody.nodes` —
+ * they're virtual, and no handler executes at them.
+ */
+export const START_NODE = '$start';
+export const END_NODE = '$end';
+export const LOOP_START_NODE = '$loop-start';
+export const LOOP_END_NODE = '$loop-end';
+/** All sentinel ids. Useful for validators that need to reject them as node ids. */
+export const SENTINEL_IDS = [START_NODE, END_NODE, LOOP_START_NODE, LOOP_END_NODE];
+/** Type guard: is this node a loop node? */
+export function isLoopNode(node) {
+    return node.kind === 'loop';
+}
+/** Type guard: is this node a fanout node? */
+export function isFanoutNode(node) {
+    return node.kind === 'fanout';
+}
+/** Type guard: is this node a subgraph-invocation node? */
+export function isSubflowNode(node) {
+    return node.kind === 'subgraph';
+}
+/** Type guard: is this node a leaf? */
+export function isLeafNode(node) {
+    return node.kind !== 'loop' && node.kind !== 'fanout' && node.kind !== 'subgraph';
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAiGjC,6EAA6E;AAC7E,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,OAAO;IACP,QAAQ;IACR,WAAW;IACX,QAAQ;IACR,OAAO;IACP,KAAK;IACL,IAAI;IACJ,KAAK;CACG,CAAC;AA+MX;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,aAAa,EAAE,aAAa,EAAE,YAAY,CAAU,CAAC;AA2FvF;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,cAAc,EAAE,YAAY,CAAU,CAAC;AAuQlF;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,GAAY,CAAC;AACtD,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAY,CAAC;AACrD,iEAAiE;AACjE,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAU,CAAC;AA6HvD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,QAAiB,CAAC;AAC5C,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAe,CAAC;AACxC,MAAM,CAAC,MAAM,eAAe,GAAG,aAAsB,CAAC;AACtD,MAAM,CAAC,MAAM,aAAa,GAAG,WAAoB,CAAC;AAElD,oFAAoF;AACpF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,eAAe,EAAE,aAAa,CAAU,CAAC;AAE5F,4CAA4C;AAC5C,MAAM,UAAU,UAAU,CAAC,IAAc;IACvC,OAAO,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC;AAC9B,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,YAAY,CAAC,IAAc;IACzC,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC;AAChC,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,aAAa,CAAC,IAAc;IAC1C,OAAO,IAAI,CAAC,IAAI,KAAK,UAAU,CAAC;AAClC,CAAC;AAED,uCAAuC;AACvC,MAAM,UAAU,UAAU,CAAC,IAAc;IACvC,OAAO,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,CAAC;AACpF,CAAC"}

package/package.json

@@ -1,7 +1,54 @@
 {
   "name": "@kindgi/flow",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder so a trusted publisher can be attached. Releases are published from https://github.com/kindgi/kindgi-sdk with provenance; use 0.1.0 or later.",
+  "version": "0.1.1",
+  "description": "Flow model + predicate DSL for Kindgi™. Defines the task-flow shape (nodes, edges, conditional edges, data-flow mappings) executed by the kernel. Pure — no I/O, no database, no runtime. Ships types, a JSON-schema-validated loader (loadFlow / defineFlow), a predicate evaluator and mapping resolver (evaluateExpr / resolveMapping), and the scheduler tick (schedulerTick) the kernel uses to pick the nodes ready for concurrent execution.",
   "license": "Apache-2.0",
-  "repository": { "type": "git", "url": "git+https://github.com/kindgi/kindgi-sdk.git" }
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kindgi/kindgi-sdk.git",
+    "directory": "packages/flow"
+  },
+  "homepage": "https://github.com/kindgi/kindgi-sdk/tree/main/packages/flow#readme",
+  "bugs": {
+    "url": "https://github.com/kindgi/kindgi-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "SPEC.md",
+    "type-manifest.json"
+  ],
+  "dependencies": {
+    "@kindgi/schema": "0.1.1",
+    "@kindgi/types": "0.1.1"
+  },
+  "devDependencies": {
+    "@kindgi/specs": "0.1.1",
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}

package/src/define.ts

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Result, Unbranded } from '@kindgi/types';
+
+import type { FlowError } from './errors.js';
+import { loadFlow } from './loader.js';
+import type { Flow } from './types.js';
+
+/**
+ * The author-facing spec accepted by `defineFlow`: the shape of the runtime
+ * `Flow` — an object literal conforming to `flow.schema.json` — with its
+ * ids as plain strings. An author writes `id: 'acme.review'`, a node
+ * `id: 'parse'`, an edge `from: 'parse'`, with no `as FlowId` / `as NodeId`
+ * / `as EdgeId` casts; branded ids still fit. `defineFlow` returns the
+ * validated `Flow`, branded, ready for the kernel or a registry.
+ */
+export type FlowSpec = Unbranded<Flow>;
+
+/**
+ * Build a validated `Flow` from a user-supplied definition.
+ *
+ * Thin wrapper over `loadFlow` — same validation gauntlet, same error
+ * surface, same `Result<Flow, FlowError>` envelope. The distinction is
+ * ergonomic: `defineFlow` is the author-facing primitive that mirrors
+ * `defineTool` / `defineCheck` / `defineAgent`, so pack authors reach for
+ * one consistent shape when declaring workspace primitives. `loadFlow`
+ * remains the wire-form entry point for JSON coming off disk / network.
+ *
+ * Validates (fail-fast, in `loadFlow` order):
+ *   1. JSON-schema conformance against `flow.schema.json`.
+ *   2. Reserved-id / duplicate-id / unknown-node-reference checks.
+ *   3. Predicate + edge-policy + loop / fanout / subgraph well-formedness,
+ *      data-flow mappings and the flow `output.schema`.
+ *   4. Start-edge check and cycle detection (outer + every loop body at
+ *      every nesting level).
+ *
+ * The returned `Flow` is byte-identical to `loadFlow(spec).value` on
+ * success; consumers can treat the two entry points as interchangeable
+ * modulo authoring intent.
+ */
+export function defineFlow(spec: FlowSpec): Result<Flow, FlowError> {
+  return loadFlow(spec);
+}

package/src/errors.ts

@@ -0,0 +1,306 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { EdgeId, FlowId, NodeId } from '@kindgi/types';
+
+/**
+ * Every flow error carries a discriminating `code` so callers can pattern
+ * match without inspecting messages. Messages are intended for logs and are
+ * not part of the API contract.
+ */
+export type FlowError =
+  | SchemaValidationError
+  | DuplicateNodeError
+  | DuplicateEdgeError
+  | UnknownNodeReferenceError
+  | ReservedIdError
+  | CycleError
+  | InvalidPredicateError
+  | InvalidEdgePolicyError
+  | MissingStartEdgeError
+  | LoopBodyMissingStartError
+  | LoopBodyCycleError
+  | LoopBodyEdgeReferenceError
+  | LoopMaxIterationsError
+  | LoopOutputSchemaError
+  | LoopVariantMismatchError
+  | LoopConcurrencyError
+  | InvalidFanoutNodeError
+  | InvalidSubflowNodeError
+  | InvalidMappingError
+  | InvalidFlowOutputError;
+
+export interface SchemaValidationError {
+  readonly code: 'schema-validation-failed';
+  readonly message: string;
+  readonly flowId?: FlowId;
+  /** Ajv-style path list — one per validation failure. */
+  readonly issues: readonly { readonly path: string; readonly message: string }[];
+}
+
+export interface DuplicateNodeError {
+  readonly code: 'duplicate-node-id';
+  readonly message: string;
+  readonly flowId: FlowId;
+  readonly nodeId: NodeId;
+}
+
+export interface DuplicateEdgeError {
+  readonly code: 'duplicate-edge-id';
+  readonly message: string;
+  readonly flowId: FlowId;
+  readonly edgeId: EdgeId;
+}
+
+export interface UnknownNodeReferenceError {
+  readonly code: 'unknown-node-reference';
+  readonly message: string;
+  readonly flowId: FlowId;
+  readonly edgeId: EdgeId;
+  readonly endpoint: 'from' | 'to';
+  readonly referencedId: string;
+}
+
+export interface ReservedIdError {
+  readonly code: 'reserved-id';
+  readonly message: string;
+  readonly flowId: FlowId;
+  readonly nodeId: NodeId;
+}
+
+export interface CycleError {
+  readonly code: 'cycle-detected';
+  readonly message: string;
+  readonly flowId: FlowId;
+  /** Node ids in the cycle, in traversal order. */
+  readonly cycle: readonly NodeId[];
+}
+
+export interface InvalidPredicateError {
+  readonly code: 'invalid-predicate';
+  readonly message: string;
+  readonly flowId: FlowId;
+  readonly edgeId: EdgeId;
+  readonly reason: string;
+}
+
+/**
+ * A `FlowEdge.policy` field is structurally valid JSON-schema-wise but
+ * violates one of the semantic rules `loadFlow` enforces — e.g.
+ * `retry.maxAttempts` out of the `[1, 10]` band, negative `delayMs`, or
+ * `backoff: 'exponential'` without a `maxDelayMs` ceiling.
+ *
+ * The schema layer catches shape errors (wrong types, unknown fields);
+ * this error surfaces the semantic ones the schema can't express.
+ */
+export interface InvalidEdgePolicyError {
+  readonly code: 'invalid-edge-policy';
+  readonly message: string;
+  readonly flowId: FlowId;
+  readonly edgeId: EdgeId;
+  readonly field:
+    | 'retry.maxAttempts'
+    | 'retry.delayMs'
+    | 'retry.backoff'
+    | 'retry.maxDelayMs'
+    | 'timeoutMs'
+    | 'concurrencyKey'
+    | 'priority';
+  readonly reason: string;
+}
+
+export interface MissingStartEdgeError {
+  readonly code: 'missing-start-edge';
+  readonly message: string;
+  readonly flowId: FlowId;
+}
+
+/**
+ * A loop node's body has no edge originating at `$loop-start`. Analogous to
+ * `MissingStartEdgeError` but scoped to a specific loop body.
+ */
+export interface LoopBodyMissingStartError {
+  readonly code: 'loop-body-missing-start-edge';
+  readonly message: string;
+  readonly flowId: FlowId;
+  readonly loopNodeId: NodeId;
+}
+
+/** A cycle was detected inside a loop node's body sub-flow. */
+export interface LoopBodyCycleError {
+  readonly code: 'loop-body-cycle-detected';
+  readonly message: string;
+  readonly flowId: FlowId;
+  readonly loopNodeId: NodeId;
+  readonly cycle: readonly NodeId[];
+}
+
+/**
+ * An edge inside a loop body references an endpoint that isn't a known
+ * body node or a `$loop-start` / `$loop-end` sentinel.
+ */
+export interface LoopBodyEdgeReferenceError {
+  readonly code: 'loop-body-unknown-node-reference';
+  readonly message: string;
+  readonly flowId: FlowId;
+  readonly loopNodeId: NodeId;
+  readonly edgeId: EdgeId;
+  readonly endpoint: 'from' | 'to';
+  readonly referencedId: string;
+}
+
+/**
+ * A loop node's `maxIterations` is out of the allowed range. Checked by
+ * `loadFlow` in addition to the schema-level bounds.
+ */
+export interface LoopMaxIterationsError {
+  readonly code: 'loop-invalid-max-iterations';
+  readonly message: string;
+  readonly flowId: FlowId;
+  readonly loopNodeId: NodeId;
+  readonly value: number;
+}
+
+/**
+ * A loop node's `outputSchema` is missing or is not a valid JSON Schema
+ * (draft 2020-12). Every loop declares a typed escape contract; a
+ * malformed schema is caught at load time so no execution-time surprise
+ * ever surfaces to the caller.
+ */
+export interface LoopOutputSchemaError {
+  readonly code: 'loop-invalid-output-schema';
+  readonly message: string;
+  readonly flowId: FlowId;
+  readonly loopNodeId: NodeId;
+  /** Meta-schema validation issues (Ajv-style path + message). */
+  readonly issues: readonly { readonly path: string; readonly message: string }[];
+}
+
+/**
+ * A loop node declares fields that belong to the wrong variant. Examples:
+ *   - `loopKind: 'foreach'` with an `exitCondition` present.
+ *   - `loopKind: 'while'` with an `iterateOver` present.
+ *   - `loopKind: 'foreach'` missing `iterateOver`.
+ *   - `loopKind: 'while'` missing `exitCondition`.
+ *
+ * Enforced at load time so the executor can trust the discriminated union.
+ */
+export interface LoopVariantMismatchError {
+  readonly code: 'loop-variant-mismatch';
+  readonly message: string;
+  readonly flowId: FlowId;
+  readonly loopNodeId: NodeId;
+  readonly loopKind: 'while' | 'foreach';
+  readonly problem:
+    | 'while-missing-exit-condition'
+    | 'while-has-iterate-over'
+    | 'while-has-invalid-evaluation-timing'
+    | 'while-has-concurrency'
+    | 'foreach-missing-iterate-over'
+    | 'foreach-has-exit-condition'
+    | 'foreach-has-evaluation-timing';
+}
+
+/**
+ * A foreach loop's `concurrency` field is out of the allowed band. Bounds:
+ *   - Must be a positive integer.
+ *   - `1 ≤ concurrency ≤ 32` — the upper cap is a safety limit.
+ *   - `concurrency ≤ maxIterations` — otherwise pointless.
+ *
+ * The 32 cap prevents accidents (a stray `concurrency: 1000` spawning a
+ * thousand simultaneous handlers). The cap is fixed; adaptive or
+ * rate-aware concurrency is not part of this primitive.
+ */
+export interface LoopConcurrencyError {
+  readonly code: 'loop-invalid-concurrency';
+  readonly message: string;
+  readonly flowId: FlowId;
+  readonly loopNodeId: NodeId;
+  readonly value: number;
+  readonly reason: 'not-integer' | 'below-minimum' | 'exceeds-max-iterations' | 'exceeds-cap';
+}
+
+/**
+ * A `subgraph` node is structurally valid JSON-schema-wise but violates
+ * one of the semantic rules `loadFlow` enforces — e.g. malformed `flowRef`,
+ * non-exact semver, an `inputMapping` value that isn't a valid Operand,
+ * an `outputSchema` that fails to compile against the draft-2020-12
+ * meta-schema, or an unknown `convergence` mode.
+ *
+ * `field` narrows the location of the failure so callers can attribute
+ * without matching on the message.
+ */
+export interface InvalidSubflowNodeError {
+  readonly code: 'invalid-subgraph-node';
+  readonly message: string;
+  readonly flowId: FlowId;
+  readonly subgraphNodeId: NodeId;
+  readonly field:
+    | 'flowRef'
+    | 'flowRef.flowId'
+    | 'flowRef.version'
+    | 'inputMapping'
+    | 'output-schema'
+    | 'convergence';
+  readonly reason: string;
+  /** Meta-schema issues, when `field === 'output-schema'`. */
+  readonly issues?: readonly { readonly path: string; readonly message: string }[];
+}
+
+/**
+ * A `fanout` node is structurally valid JSON-schema-wise but violates one
+ * of the semantic rules `loadFlow` enforces — e.g. duplicate `branchId`,
+ * concurrency out of `[1, branches.length]`, an unknown convergence mode,
+ * or a per-branch `outputSchema` that fails to compile against the
+ * draft-2020-12 meta-schema.
+ *
+ * `field` narrows the location of the failure so callers can attribute
+ * without matching on the message.
+ */
+export interface InvalidFanoutNodeError {
+  readonly code: 'invalid-fanout-node';
+  readonly message: string;
+  readonly flowId: FlowId;
+  readonly fanoutNodeId: NodeId;
+  readonly field:
+    | 'branches'
+    | 'branch-id'
+    | 'branch-handler'
+    | 'branch-output-schema'
+    | 'concurrency'
+    | 'convergence';
+  readonly reason: string;
+  /** Branch id at fault, when the failure attribution is per-branch. */
+  readonly branchId?: string;
+  /** Meta-schema issues, when `field === 'branch-output-schema'`. */
+  readonly issues?: readonly { readonly path: string; readonly message: string }[];
+}
+
+/**
+ * A leaf `inputMapping` or the flow `output.mapping` entry can't be
+ * resolved as written (schema-version 1.8.0+): its path names a node the
+ * flow doesn't have, maps the node's own output, or uses a loop-only root
+ * (`iterationIndex` / `iterationOutput`). A path with an unknown root
+ * fails the schema step instead (`schema-validation-failed`).
+ */
+export interface InvalidMappingError {
+  readonly code: 'invalid-mapping';
+  readonly message: string;
+  readonly flowId: FlowId;
+  /** The leaf node whose `inputMapping` is invalid; absent for the flow's `output`. */
+  readonly nodeId?: NodeId;
+  /** The mapping key whose operand is invalid. */
+  readonly key: string;
+  readonly reason: string;
+}
+
+/**
+ * A flow's `output.schema` is not a valid JSON Schema (draft 2020-12).
+ */
+export interface InvalidFlowOutputError {
+  readonly code: 'invalid-flow-output';
+  readonly message: string;
+  readonly flowId: FlowId;
+  /** Meta-schema validation issues (Ajv-style path + message). */
+  readonly issues: readonly { readonly path: string; readonly message: string }[];
+}