@smthrs/flow 0.0.0-stage → 1.0.0-rc.3

package/dist/cjs/Graph.d.ts

@@ -0,0 +1,325 @@
+/**
+ * Graph building: a flow declaration plus a real payload, walked once into the
+ * drafts a plan is compiled from.
+ *
+ * This is the plan phase of `docs/concepts/bodies-and-plans.md` and nothing
+ * else — no I/O, no execution, no elaboration. {@link build} evaluates the
+ * body with the REAL payload, because a body's own payload is data
+ * (`docs/concepts/flows-and-actions.md`), and evaluates every
+ * continuation and branch arm exactly once against a STRICT
+ * {@link module:Planned.Planned} placeholder, because a step result does not
+ * exist yet. A body that computes on a placeholder therefore fails here,
+ * naming the node, rather than baking `NaN` into a plan.
+ *
+ * Fatal refusals stay fatal. Computing on a planned value throws its
+ * `GraphBuildError` immediately, as does recursively expanding an inline
+ * `.call()`, because either case makes the requested graph invalid. Recoverable
+ * topology loss, such as a missing or invalid continuation, is reported in
+ * {@link Graph.diagnostics} so the remaining graph can still be inspected.
+ *
+ * The walk is stack-safe by construction: topology and payloads are traversed
+ * with explicit stacks, never native recursion, and each carries a nesting
+ * bound. Topology past the bound is a typed `graph_too_deep` refusal, a
+ * payload past it is `payload_too_deep`, and a payload containing itself is
+ * `cyclic_payload` — all three fail loudly where unbounded recursion would
+ * overflow the native stack without a typed error.
+ *
+ * Composition follows the same note: `Other.call(payload)` splices the
+ * callee's body into this graph with the capabilities of the two declarations
+ * intersected, and a flow that calls itself inline throws with the trampoline
+ * (`docs/concepts/trampoline-rounds.md`) and the child boundary as the two
+ * ways out. A callee whose declared placement the enclosing flow does not carry
+ * throws for the same reason and names the same way out, because inline
+ * expansion is the claim that these steps run in the caller's execution.
+ * `Other.child(payload)` is that boundary: one leaf node here, its own
+ * execution when the graph is driven. A branch expands BOTH arms, so the
+ * exit condition and the handoff site are visible topology before anything
+ * runs, and the predicate rides the branch's key material as a digest.
+ *
+ * What comes out is `@smthrs/plan` shaped: {@link Graph.drafts} feeds
+ * `Plan.compile` and `Plan.append` unchanged, and the `Ref`/`Pending` inputs a
+ * node's key material names are what the compiler turns into dependency
+ * digests and the plan turns into edges. Structural node ids are derived only
+ * from traversal positions and do not enter a plan draft's hashed value, so
+ * editing a mapper re-keys exactly what reads it. The interpreter does use an
+ * `ActionCall` id as durable dispatch-site material: it is the replay-stable
+ * discriminator that keeps identical declarations at distinct graph
+ * positions out of one arrival-ordered ordinal scope.
+ *
+ * Adapted from the agent repo's `@smthrs/core` `Graph.ts`. The lenient
+ * placeholder, the model-shaped `Dynamic` node, the lane-merge elaboration,
+ * and the conflict pass do not come across: the placeholder is strict here,
+ * a model call is an ordinary action, and write overlap is resolved by
+ * `Plan.compile`, which owns that verdict.
+ *
+ * @since 0.1.0
+ */
+import { GraphBuildError } from "@smthrs/plan/GraphBuildError";
+import * as Node from "@smthrs/plan/Node";
+import type * as Plan from "@smthrs/plan/Plan";
+import * as Annotations from "./Flow/Annotations.ts";
+import type * as Flow from "./Flow/Flow.ts";
+import * as DeclarationSite from "./internal/DeclarationSite.ts";
+/**
+ * Why one node depends on another: `value` consumes a result, `continuation`
+ * is the sequencing edge a builder or a branch arm records against the
+ * upstream node it was evaluated with.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type EdgeReason = "value" | "continuation" | "failure";
+/**
+ * A dependency edge, pointing from the node that produces to the node that
+ * consumes.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Edge {
+    readonly from: string;
+    readonly to: string;
+    readonly reason: EdgeReason;
+}
+/**
+ * One observed node: its structural address, the AST variant it came from, and
+ * the {@link module:Plan.NodeDraft} the plan is compiled from.
+ *
+ * `kind` is the authoring variant, not the plan's node kind — every draft a
+ * graph produces is a plan `step`.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface GraphNode {
+    readonly id: string;
+    readonly kind: Node.Ast["_tag"];
+    readonly dependencies: ReadonlyArray<string>;
+    readonly capabilities: ReadonlyArray<string>;
+    readonly capabilityCeilings: ReadonlyArray<ReadonlyArray<string>>;
+    readonly placement: unknown;
+    readonly draft: Plan.NodeDraft;
+    /**
+     * The authoring node this graph node was observed at.
+     *
+     * Key material digests a mapper, a predicate, and a callee's schemas; it
+     * cannot carry them, because a digest is not a function. A driver that has
+     * the real values in hand needs the functions themselves, so the AST rides
+     * along: {@link module:Node.mapper}, {@link module:Node.predicate}, and the
+     * member names of an `All` are read off it. The entry node a flow is entered
+     * as is the call the graph synthesized, carrying the real payload rather than
+     * the inert form an authored call records.
+     */
+    readonly ast: Node.Ast;
+    /**
+     * What this node passes on, hydrated: real data where the author wrote data,
+     * and a {@link module:Planned.Planned} placeholder where a step result goes.
+     * It is the call payload of an `ActionCall` or a `FlowCall`, the value of a
+     * `Succeed`, the error of a `Fail`, and `undefined` for every other variant,
+     * which passes nothing of its own.
+     */
+    readonly payload: unknown;
+    /**
+     * Where the declaration this node was observed at was written, when the
+     * runtime's stack format says so.
+     *
+     * Provenance, never identity: it is carried on the declaration as a
+     * non-enumerable property, so it is outside key material and a node keyed
+     * with it is byte-identical to the same node keyed without it. A node with
+     * no declaration to read — a map, a combination, an untagged succeed — has
+     * none, and so does a declaration made inside the framework itself.
+     */
+    readonly declaredAt?: DeclarationSite.DeclaredAt | undefined;
+}
+/**
+ * What a pure per-node layer resolver is told. It is the identity of the
+ * implementation a node would run against — hosts, services, permission
+ * implementations — never a layer value or a runtime handle.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface LayerRequest {
+    readonly nodeId: string;
+    readonly kind: Node.Ast["_tag"];
+    readonly capabilities: ReadonlyArray<string>;
+    readonly effects: Annotations.Effects | undefined;
+    readonly placement: unknown;
+}
+/**
+ * The knobs {@link build} takes. `resolveLayers` is invoked once per node and
+ * must be pure: planning performs no I/O, and a resolver that read the world
+ * would make a plan a function of more than its declarations.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface BuildOptions {
+    readonly resolveLayers?: ((request: LayerRequest) => Iterable<string>) | undefined;
+    /**
+     * `stable` refuses process-local flow bodies, mappers, predicates, and
+     * continuation builders before drafts can be compiled or actions driven.
+     * Declare every semantic capture with `Node.capture`; include an explicit
+     * implementation version for imported behavior not represented by the
+     * callback source. The default, `process-local`, supports inspection and
+     * experimentation but does not promise reproducible plan identity.
+     *
+     * This validates callback identity only. Action implementations and resolved
+     * layers still need their own semantic identity contract.
+     */
+    readonly callbackIdentity?: "stable" | "process-local" | undefined;
+    /**
+     * The address the entry node is recorded under, `root` by default. A plan
+     * grows by appending, and `Plan.append` refuses an id it already holds, so an
+     * elaboration built for an existing plan names its own root.
+     */
+    readonly root?: string | undefined;
+}
+/**
+ * A built graph: the nodes in dependency order, the edges between them, and the
+ * refusals that were recoverable enough to report rather than throw.
+ *
+ * DECIDED: the drafts are NOT a field here. They
+ * are derived from `nodes`, and the derivation carries a refusal — a graph with
+ * diagnostics is inspectable but not compilable — so {@link drafts} is the only
+ * way to ask for them. A field beside the accessor was a second, silent answer
+ * to the same question: reading `graph.drafts` handed back the truncated drafts
+ * of an incomplete graph while `Graph.drafts(graph)` threw on it. Effect keeps
+ * data interfaces plain and puts the policy in the accessor, so the field goes
+ * rather than growing a getter that throws from inside a `readonly` record.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Graph {
+    readonly nodes: ReadonlyArray<GraphNode>;
+    readonly edges: ReadonlyArray<Edge>;
+    readonly diagnostics: ReadonlyArray<GraphBuildError>;
+}
+/**
+ * The nesting bound the build enforces on authored topology. The walk itself
+ * is iterative and cannot overflow the native stack, so the bound is policy:
+ * topology a thousand combinators deep is a generated artifact, and refusing
+ * it with a typed `graph_too_deep` names the fix — `.child()` boundaries or
+ * trampoline handoffs — where unbounded acceptance would only defer the
+ * failure to whatever walks the plan next.
+ *
+ * It is EXPORTED so a composition that unrolls its own topology, as
+ * `@smthrs/patterns` does for a bounded loop, refuses at the same number the
+ * build enforces instead of restating it and drifting.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export declare const maximumGraphDepth = 1000;
+/**
+ * Builds the graph of a flow declaration, or of a bare node, by walking the
+ * AST once.
+ *
+ * A flow is entered as a call to itself: the returned graph's `root` node is
+ * that call, carrying the flow's declared effects, placement, and
+ * capabilities, and its body spliced beneath it. Every flow has a body, so the
+ * only inline call this leaves as a leaf is one whose declaration did not
+ * survive serialization beside its AST.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const build: (flowOrNode: Flow.Any | Node.Any, payload?: unknown, options?: BuildOptions) => Graph;
+/**
+ * The observed nodes, children before the parents that consume them.
+ *
+ * @since 0.1.0
+ * @category accessors
+ */
+export declare const nodes: (graph: Graph) => ReadonlyArray<GraphNode>;
+/**
+ * The dependency edges, in the order they were observed.
+ *
+ * @since 0.1.0
+ * @category accessors
+ */
+export declare const edges: (graph: Graph) => ReadonlyArray<Edge>;
+/**
+ * States that a file this runtime is about to evaluate holds bytes read from
+ * another, so the declarations inside it are reported at the file an author
+ * can open.
+ *
+ * A host that verifies a flow's source evaluates THE BYTES IT MEASURED, and
+ * the only way to evaluate bytes here is to write them somewhere and import
+ * that path: `@smthrs/registry` `Executable` writes them as a scratch sibling
+ * of the entry and removes it when the load is over. Without this, every node
+ * of an agent-authored flow names that scratch file, and a reader offered its
+ * path is offered a file nothing holds (D-068).
+ *
+ * The loader states this BEFORE it imports, because a declaration captures its
+ * site while the module is evaluated and never rewrites it. Both sides hold
+ * the same module: a loaded flow is recognized by this package's own type id,
+ * so a graph file resolving a second copy of `@smthrs/flow` is refused as not
+ * a flow at all rather than registered with a site nothing corrected.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const evaluatedFrom: (evaluated: string, entry: string) => void;
+/**
+ * The drafts, in node order, ready for `Plan.compile` or `Plan.append`
+ * unchanged.
+ *
+ * A graph with a FATAL diagnostic is inspectable but intentionally not
+ * compilable: returning its partial drafts would turn missing topology into a
+ * valid plan. This accessor therefore throws the first fatal build refusal, and
+ * it is the ONLY way to reach the drafts. The built graph holds nodes, and a
+ * draft is the node's own {@link GraphNode.draft}.
+ *
+ * An advisory refusal does not withhold the drafts. The one advisory code is
+ * `capability_outside_grant`, where the callee runs with LESS authority than it
+ * asked for: the author needs to see it, and the graph it describes is exactly
+ * the graph that will run.
+ *
+ * @since 0.1.0
+ * @category accessors
+ */
+export declare const drafts: (graph: Graph) => ReadonlyArray<Plan.NodeDraft>;
+/**
+ * Recoverable topology issues recorded during the build, such as a missing
+ * continuation builder or a continuation that did not produce a node. Fatal
+ * refusals, including computing on a planned value and recursive inline
+ * `.call()`, throw from {@link build} and never appear here.
+ *
+ * @since 0.1.0
+ * @category accessors
+ */
+export declare const diagnostics: (graph: Graph) => ReadonlyArray<GraphBuildError>;
+/** Serializable declaration inspection. No action or prompt renderer runs.
+ * Payload-dependent JavaScript can refuse symbolic inspection; that is a
+ * diagnostic, not evidence that the flow itself cannot execute.
+ * @category models
+ * @since 1.0.0
+ */
+export interface Inspection {
+    readonly nodes: ReadonlyArray<Pick<GraphNode, "id" | "kind" | "dependencies"> & {
+        readonly label?: string;
+    }>;
+    readonly edges: ReadonlyArray<Edge>;
+    readonly steps: ReadonlyArray<{
+        readonly id: string;
+        readonly label: string;
+    }>;
+    readonly diagnostics: ReadonlyArray<{
+        readonly code: string;
+        readonly message: string;
+    }>;
+    /** The renderer's source, never rendered with an invented input. */
+    readonly prompt?: string;
+}
+/** Inspect the existing graph model with an unresolved input reference.
+ * Run this only in the same guest that loads the declaration: plan-time body
+ * code is repository code too. An input-dependent body is reported explicitly
+ * without choosing a sample payload. As with Planned values in bodies, use
+ * node combinators for branching; JavaScript truthiness is not inspectable.
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const inspect: (flow: Flow.Any) => Inspection;
+//# sourceMappingURL=Graph.d.ts.map

package/dist/cjs/Graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Graph.d.ts","sourceRoot":"","sources":["../../src/Graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAIH,OAAO,EAAE,eAAe,EAAqB,MAAM,8BAA8B,CAAA;AAEjF,OAAO,KAAK,IAAI,MAAM,mBAAmB,CAAA;AACzC,OAAO,KAAK,KAAK,IAAI,MAAM,mBAAmB,CAAA;AAQ9C,OAAO,KAAK,WAAW,MAAM,uBAAuB,CAAA;AAEpD,OAAO,KAAK,KAAK,IAAI,MAAM,gBAAgB,CAAA;AAE3C,OAAO,KAAK,eAAe,MAAM,+BAA+B,CAAA;AAKhE;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,cAAc,GAAG,SAAS,CAAA;AAE7D;;;;;;GAMG;AACH,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAC5B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAC/B,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC5C,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC5C,QAAQ,CAAC,kBAAkB,EAAE,aAAa,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;IACjE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAA;IAC9B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAA;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB;;;;;;;;;OASG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC,UAAU,GAAG,SAAS,CAAA;CAC7D;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAC/B,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC5C,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,OAAO,GAAG,SAAS,CAAA;IACjD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,YAAY,KAAK,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAA;IAClF;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,QAAQ,GAAG,eAAe,GAAG,SAAS,CAAA;IAClE;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACnC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;IACxC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,CAAA;IACnC,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,eAAe,CAAC,CAAA;CACrD;AAiKD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,OAAQ,CAAA;AA4ftC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,KAAK,GAChB,YAAY,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,EAC/B,UAAU,OAAO,EACjB,UAAS,YAAiB,KACzB,KAwxBF,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAAI,OAAO,KAAK,KAAG,aAAa,CAAC,SAAS,CAAgB,CAAA;AAE5E;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAAI,OAAO,KAAK,KAAG,aAAa,CAAC,IAAI,CAAgB,CAAA;AAEvE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,aAAa,GAAI,WAAW,MAAM,EAAE,OAAO,MAAM,KAAG,IAAuD,CAAA;AAExH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,KAAK,KAAG,aAAa,CAAC,IAAI,CAAC,SAAS,CAIjE,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,KAAK,KAAG,aAAa,CAAC,eAAe,CAAsB,CAAA;AAE9F;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,cAAc,CAAC,GAAG;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC5G,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,CAAA;IACnC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC9E,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACxF,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,IAAI,CAAC,GAAG,KAAG,UAgDxC,CAAA"}