@hatua/model 0.0.0 → 0.1.0

package/dist/loops.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/metadata.d.ts

@@ -0,0 +1,45 @@
+import { Manifest, WorkflowExecution } from '@hatua/schema';
+/**
+ * Run metadata is derived, not reported.
+ *
+ * A component declares each metadata key as a `measure` (summable — tokens,
+ * cost, retries) or a `dimension` (groupable — model, region). Given only
+ * per-step values, that is enough for Hatua to compute run totals and pivots
+ * like "tokens per model" itself.
+ *
+ * The alternative — runners reporting their own run-level summaries with their
+ * own schemas — would mean every runner shapes the Runs view differently, and
+ * Hatua could render none of them generically.
+ */
+export interface MetadataDescriptor {
+    k: string;
+    label: string;
+    role: 'measure' | 'dimension';
+    unit?: string;
+}
+export interface MeasureTotal {
+    key: string;
+    label: string;
+    unit?: string;
+    total: number;
+}
+export interface Pivot {
+    measure: string;
+    measureLabel: string;
+    dimension: string;
+    dimensionLabel: string;
+    unit?: string;
+    rows: {
+        value: string;
+        total: number;
+    }[];
+}
+/** Every metadata key any manifest declares, keyed by component `use`. */
+export declare function descriptorsByUse(manifests: readonly Manifest[]): Map<string, MetadataDescriptor[]>;
+/** Sum every declared measure across the run. */
+export declare function totals(execution: WorkflowExecution, descriptors: Map<string, MetadataDescriptor[]>, useOf: (stepId: string) => string | undefined): MeasureTotal[];
+/**
+ * Sum a measure grouped by a dimension — "tokens per model". Both must be
+ * declared by the same component, since only then do they co-occur on a sample.
+ */
+export declare function pivot(execution: WorkflowExecution, descriptors: Map<string, MetadataDescriptor[]>, useOf: (stepId: string) => string | undefined, measureKey: string, dimensionKey: string): Pivot | null;

package/dist/metadata.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/rules.conformance.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scope.d.ts

@@ -0,0 +1,162 @@
+import { TypeNode } from '@hatua/expressions';
+import { Block, ContextKey, Manifest, Step, WorkflowDefinition } from '@hatua/schema';
+import { BoardId, StepRef } from './tree';
+/**
+ * What a step may reference. The reference tree is built from this, which is
+ * what makes a broken mapping unexpressible rather than merely discouraged.
+ */
+export interface ScopeEntry {
+    /**
+     * The whole addressable path, e.g. `steps.s2`, `triggers.nightly`,
+     * `var.digest_to`, `params.entry`, `run.tenant`, `TRIGGER`.
+     *
+     * Always below a root, never at one — which is what lets a Step be called
+     * `run` and a parameter be called `steps` (ADR-0014).
+     */
+    path: string;
+    /**
+     * Where the value comes from, which is what the reference tree groups by and
+     * what decides a row's icon.
+     *
+     * `context` is the Host's Run Context — ambient values it supplies to every
+     * execution. It sits beside `trigger` and `var` rather than under them
+     * because it is neither: nothing in the document declares it, and unlike a
+     * variable it cannot be edited from the builder at all.
+     */
+    kind: 'step' | 'trigger' | 'param' | 'var' | 'context' | 'builtin';
+    label: string;
+    /**
+     * One sentence about the value, shown under the focused row in the completion
+     * list. Only the Host's Run Context declares one today — a manifest output
+     * has nowhere to put a sentence — so absent is the ordinary case and a row
+     * without one simply shows nothing rather than a placeholder.
+     */
+    description?: string;
+    /**
+     * The shape of what it yields.
+     *
+     * This is what makes an entry usable by `@hatua/expressions`' type checker,
+     * which takes `ScopeEntry[]` as an argument precisely so it can stay ignorant
+     * of manifests and of this package. One scope, two readers: the reference
+     * tree reads `label` and `kind`, the checker reads `path` and `type`.
+     */
+    type: TypeNode;
+}
+/**
+ * The steps a given step may reference: its ancestors and the earlier siblings
+ * of every ancestor. Sibling branches are deliberately out of scope, so a user
+ * cannot express a mapping that could not resolve at run time.
+ *
+ * The walk is rooted at the Step's own Board and never leaves it. A Block's
+ * steps do not see the call site's ancestry, which is the whole reason a call is
+ * a cross-link with a contract and a jump is not (ADR-0013).
+ */
+export declare function upstreamOf(doc: WorkflowDefinition, ref: StepRef): Step[];
+/**
+ * Everything a Board offers with no position in its tree.
+ *
+ * **Never a Step's output.** A variable's value has no position — it is not
+ * reached by running anything — so no Step is guaranteed to have run by the
+ * time it is evaluated, and offering one would express a mapping that cannot
+ * resolve. Everything here is available unconditionally for the mirror-image
+ * reason: a workflow cannot run without a Trigger firing, the Host supplies Run
+ * Context to every execution, a parameter is filled by the caller before the
+ * Block starts, and a variable is Board-scoped rather than positional.
+ *
+ * The two Boards offer different things, and the difference IS the contract:
+ *
+ * | | root Board | a Block's |
+ * | --- | --- | --- |
+ * | `run.*` | Run Context | the same — the one thing that crosses |
+ * | `triggers.*`, `TRIGGER` | the parameter contract | absent |
+ * | `params.*` | absent | the parameter contract |
+ * | `var.*` | the workflow's | the Block's, rebuilt per call |
+ *
+ * A Block cannot read the workflow's variables or ask which Trigger fired.
+ * Run Context is the single exception because nothing in the document declares
+ * it: the Host supplies it to every execution, so it is exact on every path of
+ * every Board with no intersection to compute (ADR-0013).
+ *
+ * It exists as its own function because the Board panel needs scope without a
+ * Step to ask about. `scopeFor` is this plus the upstream Steps, so the two
+ * readers share one definition of the unpositioned half rather than drifting.
+ */
+export declare function boardScope(doc: WorkflowDefinition, board?: BoardId, manifests?: readonly Manifest[], context?: readonly ContextKey[]): ScopeEntry[];
+/**
+ * Everything addressable from a step: the unpositioned scope above, plus the
+ * upstream steps.
+ *
+ * Only steps are constrained by tree position, because only a step can fail to
+ * have run.
+ */
+export declare function scopeFor(doc: WorkflowDefinition, ref: StepRef, manifests?: readonly Manifest[], context?: readonly ContextKey[], memo?: ScopeMemo): ScopeEntry[];
+/**
+ * What one walk has already worked out, so a second walk over the same document
+ * does not work it out again.
+ *
+ * A scope is *positional*, so asking for every Step's is asking n times — and
+ * each answer names every Step upstream of it, so the answers together hold
+ * n²/2 entries. Recomputing each one costs a fresh type tree per upstream Step
+ * per Step, which is what makes a whole-document pass superlinear: a thousand
+ * Steps take a second, and `validateDefinition` runs on every keystroke.
+ *
+ * Shared by passing one of these to every `scopeFor` in the pass. Created per
+ * pass and never held in the module: the document is an argument, and a cache
+ * outliving the call would be answering about a document that has since been
+ * edited.
+ */
+export interface ScopeMemo {
+    /** One loop's element type, which is what makes nested loops linear. */
+    readonly elements: ElementMemo;
+    /** One upstream Step's entry, keyed by `stepKey`. */
+    readonly entries: Map<string, ScopeEntry>;
+    /** One Board's unpositioned scope: its Triggers, its contract, its variables. */
+    readonly boards: Map<string, ScopeEntry[]>;
+}
+export declare const newScopeMemo: () => ScopeMemo;
+/**
+ * The type one path names, read out of a scope, or null when nothing declares
+ * it.
+ *
+ * Longest prefix first, because a scope path is dotted and is one entry rather
+ * than two: `steps.s2` is an entry and `steps` is not, so `steps.s2.messages`
+ * has to try three segments before two. That is the same rule `validate.ts`
+ * walks a Member chain by, restated here for a caller that has a path and no
+ * expression — reading a *declared* type is not checking one, and reaching for
+ * the checker would mean manufacturing diagnostics nobody asked for in order to
+ * throw them away.
+ */
+export declare function typeAtPath(scope: readonly ScopeEntry[], path: string): TypeNode | null;
+/**
+ * What one element of a `core.for_each`'s list is, or null when the document
+ * does not say.
+ *
+ * This is the whole of `t: item`. The loop's `list` is a `ref` field, so its
+ * declared type is `unknown` and the ordinary Slot check learns nothing from
+ * it; the shape is one level below whatever it points at, which is exactly the
+ * `of:` the source output declared. Null when `list` is missing, is not a plain
+ * Reference, names nothing, or names something that is not a list — and null
+ * means `item` stays `item`, which the checker treats as matching anything.
+ * Guessing `object` instead would be a shape nothing declared.
+ */
+export declare function loopElementType(doc: WorkflowDefinition, board: BoardId, step: Step, manifests?: readonly Manifest[], context?: readonly ContextKey[], resolving?: ReadonlySet<string>, elements?: ElementMemo): TypeNode | null;
+/**
+ * What one loop's element resolves to, for the length of one top-level walk.
+ *
+ * A Step's element type is a property of the document, so one walk asking for
+ * the same loop twice is asking the same question twice — and the walk asks for
+ * it once per path that reaches it, which is what makes the cost exponential
+ * without this. The map is created per `scopeFor` rather than held in the
+ * module: the document is an argument, and a cache outliving the call would be
+ * answering about a document that has since been edited.
+ */
+type ElementMemo = Map<string, TypeNode | null>;
+/**
+ * What a Block's outputs are, as a scope entry's type at the call site.
+ *
+ * Read where the Block is declared rather than from a manifest, which is what
+ * makes a call type-check before its body is written: the declaration is the
+ * contract, and `core.return` only binds values to it.
+ */
+export declare function blockOutputType(block: Block | undefined): TypeNode;
+export {};

package/dist/scope.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/segment.d.ts

@@ -0,0 +1,107 @@
+import { Step, WorkflowDefinition } from '@hatua/schema';
+import { Board, BoardId, StepRef } from './tree';
+/**
+ * A contiguous stretch of sibling **Steps** in one region of one **Board**.
+ *
+ * The shape a selection takes and the shape extraction consumes (ADR-0018,
+ * ADR-0020). A Segment of one is a Segment: a single container together with
+ * its whole body is the flattening case a Block exists for.
+ *
+ * ## Named by Steps, never by positions
+ *
+ * `{ board, steps }` and not a start index and a length. A Segment is held
+ * across edits, and an index range means a Step added above it silently changes
+ * which Steps are in it — the argument `RegionRef` makes about `branchIndex`,
+ * which it accepts only because a Branch has no id and a Step has one.
+ *
+ * So contiguity is *derived* rather than stored, by `segmentSteps` against the
+ * Board being drawn. What the shape does carry structurally is the **one
+ * Board**: a `readonly StepRef[]` can express a selection spanning two Boards,
+ * which is not a Segment and never can be, and hoisting the Board out makes
+ * that unrepresentable rather than something every reader has to filter for.
+ */
+export interface Segment {
+    readonly board: BoardId;
+    /** The Steps, by id, in document order. Never empty. */
+    readonly steps: readonly string[];
+}
+/** One Step's place among its siblings: the list it sits in, and where. */
+export interface Siblings {
+    readonly steps: readonly Step[];
+    readonly index: number;
+}
+/**
+ * The sibling list holding one Step, and its position in it.
+ *
+ * The whole of "are these two Steps siblings": two ids resolve to the same
+ * `steps` array or they do not. Identity of the array is the test rather than a
+ * path, because `regionsOf` hands the region's own list over and a Board holds
+ * exactly one array per region.
+ */
+export declare function siblingsOf(board: Board, id: string): Siblings | undefined;
+/**
+ * The Segment reaching from one Step to another, or `undefined` when the two
+ * are not siblings.
+ *
+ * The *only* way a Segment of more than one Step is built, which is what makes
+ * "a selection is always extractable" true by construction rather than by a
+ * check somebody has to remember to run (ADR-0020). Order of the arguments does
+ * not matter: a user may extend a selection upwards, and the Steps come back in
+ * document order either way.
+ */
+export declare function segmentBetween(board: Board, anchorId: string, headId: string): Segment | undefined;
+/** A Segment holding one Step. */
+export declare const segmentOf: ({ board, id }: StepRef) => Segment;
+/**
+ * The Steps a Segment actually names on a Board, in document order.
+ *
+ * Every consumer's way in, and the place a Segment held across an edit is
+ * reconciled with the document as it is now: a Step that has been removed drops
+ * out, and what is left is still contiguous because removal closes the gap.
+ *
+ * Empty means the Segment names nothing on this Board — a Board that is gone, a
+ * Block that was deleted, or a Segment whose every Step has been removed. A
+ * caller showing a selection draws nothing for it; a caller acting on one has
+ * nothing to act on.
+ */
+export declare function segmentSteps(doc: WorkflowDefinition, segment: Segment): readonly Step[];
+/**
+ * Whether a Segment names this Step, for a surface deciding whether to draw a
+ * card as selected.
+ *
+ * A Board comparison and not only an id: ids are Board-local, so two Blocks may
+ * each hold a Step called `ret` and a bare id highlights both (ADR-0013).
+ */
+export declare const segmentHolds: (segment: Segment | undefined, ref: StepRef) => boolean;
+/**
+ * The Step one place from the Segment's head, in the direction given, or
+ * `undefined` at the end of the sibling list.
+ *
+ * What `Shift`+`↑`/`↓` moves. The *head* moves and the anchor stays, so the
+ * same keystroke grows a Segment and shrinks it from the other end.
+ */
+export declare function siblingFrom(board: Board, id: string, step: 1 | -1): string | undefined;
+/**
+ * Whether a Segment holds a `core.return`, anywhere inside it.
+ *
+ * What extraction refuses (ADR-0018). Moved onto a new Board, a return binds to
+ * the *new* Block's `outputs:` and ends a Block the author did not mean it to
+ * end — behaviour the move silently changes, with nothing malformed for a rule
+ * to report. So the gesture is not offered rather than repaired.
+ *
+ * Nested and not only the Segment's own Steps: a return inside a Fork branch
+ * inside the Segment moves with it and binds exactly the same way.
+ *
+ * Takes the Steps a Segment resolves to rather than the Segment, so a caller
+ * that has already asked `segmentSteps` — which is every caller, because the
+ * count beside the action comes from the same answer — does not resolve twice.
+ *
+ * **`extractBlock` cannot call this, and asks the same question its own way.**
+ * A command runs against a document that does not project (ADR-0001), so it has
+ * no `Step[]` to hand over and walks the YAML AST instead. The two agree because
+ * `regionsOf` here and `stepEntriesIn` there enumerate the same regions — a
+ * Branch's steps, a body, a handler — which is a coupling neither file states on
+ * its own. A region kind added to one and not the other makes the canvas offer
+ * an enabled action on the one selection the command refuses.
+ */
+export declare const segmentReturns: (steps: readonly Step[]) => boolean;

package/dist/segment.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/slots.d.ts

@@ -0,0 +1,161 @@
+import { Slot, ValueType } from '@hatua/expressions';
+import { Manifest, Step, Variable, WorkflowDefinition, MAPPABLE_FIELD_KINDS } from '@hatua/schema';
+import { BoardId } from './tree';
+/**
+ * The bridge between a Component Manifest and the expression language.
+ *
+ * `@hatua/expressions` deliberately knows nothing about manifests: it takes a
+ * `Slot` and a `ScopeEntry[]` as arguments, which is what keeps it depending on
+ * `@hatua/schema` alone and stops a cycle forming with this package. The cost is
+ * that *something* has to turn a step and its manifest into those arguments, and
+ * this is it — once per language, so a runner never restates the field-kind to
+ * type mapping and cannot get it subtly different from the builder.
+ */
+/** The kinds whose value is a Template. Everything else holds a literal. */
+export type MappableFieldKind = (typeof MAPPABLE_FIELD_KINDS)[number];
+/**
+ * What each mappable field kind's value must produce.
+ *
+ * Keyed by `MappableFieldKind` rather than by `string`, so the compiler refuses
+ * both a missing kind and an invented one. A loose `Record<string, ValueType>`
+ * accepts entries for `bool`, `enum`, `secret` and `conn` — kinds `isMappable`
+ * rejects before this is ever read, so they are unreachable — while silently
+ * tolerating the omission of `map`, which is mappable. That is the same "two
+ * definitions of one thing" failure a Reference regex would be, and the key
+ * type is what stops it.
+ *
+ * `mono` and `textarea` are text that renders differently. `ref` is `unknown` on
+ * purpose: a ref field holds whatever it points at, and the check belongs at the
+ * far end. `map` has no single type at all — each of its entries declares its
+ * own, which is why `slotsFor` never reads this for one.
+ */
+export declare const FIELD_KIND_TYPES: Readonly<Record<MappableFieldKind, ValueType>>;
+/** One entry of a `map` field: a name, a Template, and the type it must produce. */
+export interface MapEntry {
+    key: string;
+    value: string;
+    type: ValueType;
+}
+/**
+ * The Slots a step's `with:` map resolves into.
+ *
+ * A `map` field contributes one Slot per entry, named `<field>.<key>`, because
+ * each entry is separately typed and separately wrong.
+ */
+export declare function slotsFor(step: Step, manifest: Manifest): Slot[];
+/**
+ * The Slot a branch's `when` resolves into.
+ *
+ * Separate from `slotsFor` because a branch is not a step and has no manifest —
+ * and because its type is not declared anywhere: a condition is a boolean, and
+ * that is the whole reason `when: "{{steps.s2.count}} > 0"` can be refused at design
+ * time rather than misread at run time.
+ */
+export declare const whenSlot: (when: string) => Slot;
+/** The verb whose outputs come from its own configuration. */
+export declare const MAPPING_VERB = "core.map";
+/** The verb that iterates a collection. */
+export declare const FOR_EACH_VERB = "core.for_each";
+/** The verb that branches. */
+export declare const FORK_VERB = "core.fork";
+/** The verb that writes one of its Board's variables. */
+export declare const SET_VAR_VERB = "core.set_var";
+/**
+ * The field a `core.for_each` iterates, and the one `item` is resolved through.
+ *
+ * A constant rather than a literal at three call sites, because it is a name two
+ * languages and one manifest have to agree on: `item` means "one element of
+ * whatever THIS key points at", so a reader looking under a different key
+ * resolves `item` to nothing and reports no type at all.
+ */
+export declare const FOR_EACH_LIST_FIELD = "list";
+/**
+ * The output key a container binds for the children it owns.
+ *
+ * Both are ordinary manifest outputs of the container Step, read as
+ * `{{steps.<container id>.<key>}}`. That is the whole binding mechanism, and it
+ * is one mechanism rather than two: ADR-0014 closed the path roots so that a
+ * structural idea could not take a bare word away from users, and a Step id is
+ * already one segment below `steps.`. Two nested loops cannot shadow each other,
+ * because two Steps cannot share an id on one Board.
+ */
+export declare const ITEM_BINDING = "item";
+/**
+ * The Slot a `core.repeat`'s `until` resolves into.
+ *
+ * The mirror of `whenSlot`, and for the same reason: a condition is a boolean,
+ * and no manifest field can say so — `FIELD_KIND_TYPES` has no mappable boolean
+ * at all, because `bool` holds a literal rather than a Template. That is why
+ * `until` is a structural key beside `steps:` rather than a field under `with:`.
+ * Under `with:` it would type-check as text, so `{{ steps.s2.count }}` would
+ * pass as a termination condition.
+ *
+ * A repeat tests this AFTER its body, so the body always runs at least once.
+ */
+export declare const repeatSlot: (until: string) => Slot;
+/**
+ * The type a variable's `{{ var.<key> }}`, its initial `value` and every
+ * `core.set_var` writing it are all checked against.
+ *
+ * Declared rather than read off the value. A var is the one addressable thing
+ * whose content changes while the document does not, so inferring its type from
+ * the literal in the file would make the marking a lie the moment a
+ * `core.set_var` wrote something else — and every downstream check was answered
+ * against it (ADR-0013).
+ *
+ * `unknown` for a var carrying no `t` at all — absent or empty alike, matching
+ * the Go SDK, because a hand-edit is exactly what reaches here and `t: ""` is as
+ * plausible a one as a missing key. The schema requires a type, so refusing to
+ * check is the honest answer where guessing `text` would refuse a document over
+ * a type nothing declared.
+ */
+export declare const variableType: (variable: Variable) => ValueType;
+/**
+ * The Slot a `core.set_var`'s `value` resolves into, typed by the variable it
+ * names.
+ *
+ * The third verb a manifest cannot describe, alongside a call and a
+ * `core.return`, and for the same reason: what its field must produce is
+ * declared elsewhere in the document. Here it is the Board's `vars`, which is
+ * also why a `core.set_var` inside a Block can only ever name that Block's —
+ * `vars` is read from the Board the Step sits on, so there is no reaching out.
+ *
+ * Takes the Board rather than a list of variables, so the caller cannot supply
+ * the wrong one: the Go SDK's `SetVarSlot` has the same signature, and a runner
+ * handed a list would be the one deciding whether a Block falls back to the
+ * workflow's variables — which is the rule this verb exists inside.
+ *
+ * Null when the step names no variable, or names one the Board does not
+ * declare: both have their own diagnostic, and resolving a Template against a
+ * type nothing declared would report a mismatch the user cannot act on.
+ */
+export declare function setVarSlot(doc: WorkflowDefinition, board: BoardId, step: Step): Slot | null;
+/**
+ * The Slot a variable's initial value resolves into.
+ *
+ * A var's `value` may hold `{{ … }}`, and until `t` was declared there was
+ * nothing to check it against. Null for a literal: only a Template is a Slot.
+ */
+export declare function variableSlot(variable: Variable): Slot | null;
+/** The `{key, value, type}` entries of a `map` field, ignoring anything malformed. */
+export declare function mapEntries(value: unknown): MapEntry[];
+/**
+ * The Slots a Step's `with:` map resolves into, whichever kind of Step it is.
+ *
+ * One entry point, so a caller never has to know that a call, a `core.return`
+ * and a `core.set_var` are the three verbs a Component Manifest cannot
+ * describe: what each of their fields must produce is declared elsewhere in the
+ * document — in a Block's `params`, in a Block's `outputs`, in the Board's
+ * `vars` — and a caller that only asked `slotsFor` would check nothing at a
+ * call site at all. `sdk/go`'s `SlotsForStep` is the same dispatch.
+ *
+ * Empty where the document does not say: a call naming a Block that is not
+ * declared, a return on the root Board, a `core.set_var` naming no variable.
+ * Each of those has its own diagnostic, and resolving a Template against a
+ * contract nothing declares would report a second problem about the first one.
+ *
+ * A branch's `when:` and a `core.repeat`'s `until:` are NOT here. They are
+ * structural keys beside `steps:` rather than fields under `with:`, which is
+ * exactly what lets them be boolean — `whenSlot` and `repeatSlot` are theirs.
+ */
+export declare function slotsForStep(doc: WorkflowDefinition, board: BoardId, step: Step, manifest: Manifest | undefined): Slot[];

package/dist/slots.test.d.ts

@@ -0,0 +1 @@
+export {};