@hatua/model 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Gomes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/authoring.d.ts

@@ -0,0 +1,47 @@
+import { Step } from '@hatua/schema';
+/**
+ * What the verb decides about a Step that does not exist yet.
+ *
+ * `regionsOf` reads the keys and never the verb, and that is load-bearing: a
+ * `handler:` on a `core.fork` is meaningless and has no runner, but refusing to
+ * draw it would make it undeletable rather than absent (`docs/handoff.md` §
+ * Flow map geometry). That rule answers "what does this Step nest". It cannot
+ * answer "what should a new one nest", because a Step written with neither key
+ * nests nothing at all — and the verb is the only thing that knows a `core.try`
+ * protects a body and falls back to a handler.
+ *
+ * The two questions are asked by different callers at different moments, which
+ * is why they are two functions and this one sits downstream of both the region
+ * vocabulary and the verbs.
+ */
+/**
+ * The regions a Step of this verb is born carrying.
+ *
+ * Empty and present, never populated. An empty region is a Band on the map with
+ * a word over it and an insert point inside — `banded` in @hatua/layout draws
+ * one for exactly that reason — and that is the whole of what makes it somewhere
+ * a Step can be dropped. Without the key there is no region, so there is no
+ * frame, no `+`, and no way to put anything inside the container: a card that
+ * can never be filled in.
+ *
+ * `TRY_HAS_NO_BODY` and `LOOP_HAS_NO_BODY` still report against the result. That
+ * is the point — the Step is unfinished, and these are the frames it gets
+ * finished in.
+ *
+ * `core.fork` is the one verb whose regions are not empty lists, because a
+ * Branch carries a label and a condition of its own. It is still born with two
+ * of them: CONTEXT.md defines a Fork as holding two or more, one Branch is the
+ * same path with a condition on it, and a Fork with none is a card with nothing
+ * inside it and no way to put anything there.
+ *
+ * Two, and a **condition** fork rather than a parallel one — `when: ''` on the
+ * first Branch is a condition nobody has written yet, and its absence on the
+ * second is what makes that one the fallback. A parallel fork is the shape that
+ * cannot be reached by editing one field, so the reachable shape is the one to
+ * be born in.
+ *
+ * The labels are rendered copy and reach an end user's screen, so they are
+ * written in the words on the screen rather than in this repository's
+ * (`.agents/rules/rendered-copy-is-written-for-the-hosts-users.md`).
+ */
+export declare function bornRegionsOf(use: string): Pick<Step, 'steps' | 'handler' | 'branches'>;

package/dist/blocks.d.ts

@@ -0,0 +1,119 @@
+import { Slot } from '@hatua/expressions';
+import { Block, Step, WorkflowDefinition } from '@hatua/schema';
+import { Diagnostic } from './diagnostic';
+import { StepRef } from './tree';
+/**
+ * Blocks: what a call takes, what a return publishes, and which Blocks reach
+ * which.
+ *
+ * A Block is invoked as `use: block.<id>` rather than by a verb of its own —
+ * ADR-0014 gives the verb namespace three roots, and "declared in this document"
+ * is one of them, so calling costs a namespace rather than a fourth structural
+ * verb (ADR-0013).
+ */
+/** The root that says a verb names a Block in this document. */
+export declare const BLOCK_PREFIX = "block.";
+/** The verb that publishes a Block's declared outputs and ends it. */
+export declare const RETURN_VERB = "core.return";
+/** The Block a verb names, or null when it names something else. */
+export declare const blockIdOf: (use: string) => string | null;
+/** One Block by id. */
+export declare const blockOf: (doc: WorkflowDefinition, id: string) => Block | undefined;
+/**
+ * The Slots a call's `with:` map resolves into: one per declared parameter,
+ * typed by the declaration.
+ *
+ * Deliberately NOT routed through a synthesized Component Manifest. A manifest
+ * field carries a rendering `kind` and no type, so
+ * `slotsFor` recovers the expected type from `FIELD_KIND_TYPES` — and that
+ * vocabulary cannot express "a Template that must produce a boolean" at all,
+ * because `bool` holds a literal rather than a Template. Synthesizing a manifest
+ * would therefore have thrown away exactly the half of the contract the call
+ * site exists to check. A declaration's `t` IS the expected type, which is what
+ * a Slot has always been (CONTEXT.md): a Template together with the type it must
+ * produce.
+ *
+ * The rendering kind is a screen's problem and is derived where the screen is.
+ */
+export declare const callSlots: (step: Step, block: Block) => Slot[];
+/**
+ * The Slots a `core.return`'s `with:` map resolves into: one per declared
+ * output of the Block it sits on.
+ *
+ * `core.return` is the mirror of `core.map`. A mapping's *outputs* come from its
+ * own field values because no manifest can declare them; a return's *inputs*
+ * come from the enclosing Block's `outputs:` for the same reason — they are
+ * whatever that Block promised, and no manifest knows which Block a step is on.
+ */
+export declare const returnSlots: (step: Step, block: Block) => Slot[];
+/**
+ * Which Blocks a Block reaches directly, in document order.
+ *
+ * Reads the whole Board rather than its top level: a call nested inside a Fork
+ * branch, a loop body or a `core.try`'s handler still reaches, which is the
+ * entire point of asking. A region missing from this walk is a region recursion
+ * can hide in: the call graph comes out short an edge, the cycle is not found,
+ * and the document publishes.
+ */
+export declare function callsOf(steps: readonly Step[]): string[];
+/**
+ * The Blocks that take part in a cycle, by id.
+ *
+ * ADR-0013 refuses recursion because "unbounded recursion is the jump problem
+ * wearing a contract's clothes" — so this is a design-time answer rather than a
+ * depth limit a runner discovers. Direct and indirect are one question: a Block
+ * that reaches itself through any chain is in a cycle, and a colour-marked
+ * depth-first walk answers both without a second traversal.
+ */
+export declare function cyclicBlocks(doc: WorkflowDefinition): Set<string>;
+/**
+ * Every Step that calls a Block, on every Board including the Block's own.
+ *
+ * The other direction from `callsOf`, and it walks the whole document rather
+ * than one Board: a call sits wherever somebody wrote it, and a count that only
+ * looked at the root would tell a user deleting a Block that nothing calls it
+ * while two other Blocks do.
+ */
+export declare function callSitesOf(doc: WorkflowDefinition, id: string): StepRef[];
+/**
+ * What a Block takes and publishes, in a line: `1 param · 2 outputs`.
+ *
+ * One definition because two surfaces say it — the canvas's root node for the
+ * Board a Block opens, and the card that Board is reached from. Two spellings
+ * of the same count read as two different facts about one Block.
+ *
+ * An absent Block reads as a contract of nothing rather than as an empty
+ * string: a Board resolved against a document that no longer declares it still
+ * draws a node, and a summary that vanishes reads as a Board with no contract
+ * instead of one that is not there.
+ */
+export declare const contractSummary: (block: Block | undefined) => string;
+/**
+ * Every Block that will not run: one with a diagnostic on its own Board, and
+ * one that calls another such Block, however far down.
+ *
+ * A call is a **doorway** (ADR-0013), and a doorway says nothing about what is
+ * behind it. So a Board holding nothing but a clean-looking call can be a Board
+ * that cannot run, and the only way to find out is to walk through — which
+ * nobody does, because there is nothing on screen suggesting they should. That
+ * is the same invisibility a Reference naming nothing had before
+ * `validateDefinition` grew its expression family, one level of nesting up.
+ *
+ * **Derived, and never a diagnostic.** Every problem here is already reported,
+ * on the Board that holds it and by the rule that found it. Raising a second one
+ * at each call site would report one problem twice — so a Publish gate counting
+ * what it found would count the same fault once per doorway, and a Block called
+ * from five places would look five times as broken as one called from one.
+ * This says which Blocks are affected; the surfaces decide what to draw.
+ *
+ * **Transitive**, because the alternative is not honest. A Block whose own
+ * Steps are all fine but which calls a broken one is a Block that does not run,
+ * and marking only the immediate caller leaves every Board above it clean —
+ * with nothing to suggest walking down to the level that says so.
+ *
+ * Terminates on a document whose Blocks call each other, because a caller
+ * already in the set is not queued again. Such a document also has
+ * `BLOCK_RECURSION` against every Block on the cycle, so they are seeded here
+ * in any case.
+ */
+export declare function troubledBlocks(doc: WorkflowDefinition, diagnostics: readonly Diagnostic[]): ReadonlySet<string>;

package/dist/blocks.test.d.ts

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

package/dist/connections.d.ts

@@ -0,0 +1,61 @@
+import { Manifest, WorkflowDefinition } from '@hatua/schema';
+import { Diagnostic } from './diagnostic';
+/**
+ * Connection rules. Two families, and they fail at different moments on purpose.
+ *
+ * The only rules here that cannot be answered from the Workflow Definition. A
+ * Connection stores an opaque `ref` and nothing else (ADR-0007), so what type it
+ * is comes from the Host — which makes absence a third answer these rules have
+ * to hold, distinct from "matches" and "does not match". ADR-0022 is why that
+ * answer is silence rather than a diagnostic.
+ */
+type ManifestIndex = ReadonlyMap<string, Manifest>;
+/** Takes flat manifests. Catalogues are flattened at load time, not here. */
+export declare const indexManifests: (manifests: readonly Manifest[]) => ManifestIndex;
+/**
+ * What the Host says each established Connection is, keyed by the opaque `ref` a
+ * Workflow Definition stores.
+ *
+ * A map rather than a `(ref) => type | undefined` function so that a missing
+ * entry means one thing and one thing only: the Host listed its Connections and
+ * this handle was not among them. A function returning `undefined` cannot say
+ * whether it was asked before the Host answered.
+ *
+ * **An empty map is an answer.** It says the Host has established no Connections
+ * — a fresh environment, and a legitimate one. `undefined` in its place is the
+ * other case entirely: nobody can describe them, because no `ConnectionSource`
+ * is wired or the one that is would not answer.
+ *
+ * The two must not look alike. Collapsed, every Connection in the workflow is
+ * CONNECTION_UNRESOLVABLE on first paint — so a workflow with nothing wrong with
+ * it cannot be published, and every `conn` field carries a sentence saying its
+ * Connection is gone. It clears when the port answers, and for a Host that wires
+ * no port it never clears at all.
+ */
+export type ConnectionTypes = ReadonlyMap<string, string>;
+/**
+ * A connection with no `ref` was never established. That blocks publish but not
+ * editing — you can lay out a whole workflow before wiring up its connections,
+ * and forcing the connection first would make the builder unusable on a fresh
+ * environment.
+ *
+ * Answered from the document alone, so it is reported whether or not anything
+ * can describe a Connection.
+ */
+export declare function unresolvedConnections(doc: WorkflowDefinition): Diagnostic[];
+/**
+ * A `conn` field offers only connections whose Host-reported type matches its
+ * `conn_type` — so a "send email" step is never handed an LLM connection. Both
+ * codes that decide it block editing, because unlike a missing connection
+ * neither is a legitimate intermediate state: each can only arise from a
+ * hand-edit.
+ *
+ * **`types` is optional, and its absence is not an error.** Handed nothing, this
+ * reports only what the document answers on its own — a field naming a
+ * Connection the document does not declare — and says nothing about the two
+ * questions that need a type. Reporting those anyway would say "no longer
+ * resolves" about every Connection in the workflow before the Host has spoken,
+ * which refuses Publish to a workflow with nothing wrong with it. See ADR-0022.
+ */
+export declare function mismatchedConnections(doc: WorkflowDefinition, manifests: ManifestIndex, types?: ConnectionTypes): Diagnostic[];
+export {};

package/dist/connections.test.d.ts

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

package/dist/diagnostic.d.ts

@@ -0,0 +1,60 @@
+import { DefinitionCode } from './generated/diagnostics';
+/**
+ * One thing wrong with a Workflow Definition, and the vocabulary every rule
+ * family raises it in.
+ *
+ * Its own module because it belongs to no one family. A rule about a Fork's
+ * branches, a Reference naming nothing and a Connection whose type does not fit
+ * are all this shape, and putting the shape inside whichever file happened to
+ * need it first makes every other family import from that one.
+ */
+export interface Diagnostic {
+    code: string;
+    message: string;
+    /** Where it surfaces: an unconnected connection must not block editing. */
+    blocks: 'edit' | 'publish';
+    stepId?: string;
+    /**
+     * Set instead of `stepId` when the subject is a Trigger.
+     *
+     * Separate because a Trigger is not a Step and the two are rendered by
+     * different regions: the Flow tab looks a Step's id up in `byStep`, and a
+     * Trigger's id filed there is either drawn by nobody or — if a hand-edited
+     * Trigger id happens to match a Step's — painted on that Step's row.
+     */
+    triggerId?: string;
+    /**
+     * Which Board the subject sits on: a Block's id, or absent for the root.
+     *
+     * Set ALONGSIDE `stepId`, not instead of it: a step id alone does not name one
+     * Step, because ids are Board-local — two Blocks may each hold a `ret`.
+     * Set on its own when the subject is the Block itself: "a path through this
+     * block can finish without returning" belongs to no Step in it.
+     */
+    blockId?: string;
+    /**
+     * Which Connection the diagnostic is about.
+     *
+     * Set ALONGSIDE `stepId` when a field's Connection is the thing at fault, so
+     * the diagnostic still files under the Step whose field the user can act on.
+     * Set on its own when the subject is the Connection itself — "this was never
+     * connected" belongs to no Step, because a declared Connection nothing uses
+     * is still unfinished.
+     */
+    connectionId?: string;
+    fieldKey?: string;
+}
+/**
+ * Fill a declared message's `{name}` holes from the fields a diagnostic carries.
+ *
+ * Exported because the generated table carries templates, and a Host reading
+ * `DEFINITION_DIAGNOSTICS[code].message` itself would get the literal braces.
+ * The Go SDK's `FormatDefinitionMessage` is the same function.
+ *
+ * A hole with no field keeps its braces rather than becoming empty: a sentence
+ * missing a word reads as a bug in Hatua, and one still holding `{label}` reads
+ * as a diagnostic raised without the field it names — which is what it is.
+ */
+export declare const formatDefinitionMessage: (code: DefinitionCode, fields?: Record<string, string>) => string;
+/** One diagnostic, taking `blocks` from the declaration rather than restating it. */
+export declare const raise: (code: DefinitionCode, subject: Partial<Diagnostic>, fields?: Record<string, string>) => Diagnostic;

package/dist/execution.d.ts

@@ -0,0 +1,43 @@
+import { WorkflowExecution } from '@hatua/schema';
+/**
+ * Reading a **Workflow Execution** against the definition it references.
+ *
+ * Here rather than in a region for the reason `regionsOf` is here: the card on
+ * the map, the pane beside it and any viewer a **Host** writes all ask the same
+ * two questions — which records belong to a Step, and what one status stands for
+ * them — and three answers to that is a card reading `failed` beside a pane
+ * reading `succeeded`.
+ */
+/** One Step's record, as the schema shapes it. */
+export type StepRecord = WorkflowExecution['steps'][number];
+export type RunStatus = StepRecord['status'];
+/**
+ * Every record a Step has in one execution.
+ *
+ * More than one when it sits inside a loop: `core.for_each` runs its children
+ * once per item, so a flat `stepId -> status` list cannot say "succeeded 23
+ * times and failed once", and the schema gives each pass its own record with its
+ * own nested results.
+ *
+ * The walk descends into iterations and nowhere else, because that is the only
+ * nesting an execution has — a **Fork**'s branches are nesting in the
+ * definition rather than in the record, and the Steps that ran inside one are
+ * reported flat.
+ */
+export declare function recordsFor(execution: WorkflowExecution, stepId: string): StepRecord[];
+/**
+ * The one status a Step's card shows, or null when the Step has no record at
+ * all.
+ *
+ * Null is a real answer and not a missing one: a Step inside a **Branch** that
+ * was not taken never ran, and the version the run is drawn against still holds
+ * it. An unmarked card is what says so.
+ */
+export declare function statusOf(records: readonly StepRecord[]): RunStatus | null;
+/** The log entries belonging to one Step, in the order the Host reported them. */
+export declare function logFor(execution: WorkflowExecution, stepId: string): {
+    at: string;
+    message: string;
+    step?: string | undefined;
+    channel?: string | undefined;
+}[];

package/dist/fixtures.d.ts

@@ -0,0 +1,10 @@
+import { Manifest, WorkflowDefinition } from '@hatua/schema';
+import { ConnectionTypes } from './connections';
+/** Mirrors the worked example in the plan, so tests and docs cannot drift apart. */
+export declare const DOC: WorkflowDefinition;
+export declare const MANIFESTS: Manifest[];
+/**
+ * What the Host reports each established Connection is, keyed by the opaque ref
+ * a Workflow Definition stores — `ConnectionSource.listConnections` as a map.
+ */
+export declare const CONNECTION_TYPES: ConnectionTypes;

package/dist/generated/diagnostics.d.ts

@@ -0,0 +1,18 @@
+/**
+ * What a diagnostic stops. `publish` never blocks editing (ADR-0009);
+ * `edit` is reserved for what ordinary building cannot produce.
+ */
+export type Blocks = 'edit' | 'publish';
+export type DefinitionCode = 'FIELD_REQUIRED' | 'COMPONENT_UNKNOWN' | 'FORK_HAS_NO_BRANCHES' | 'FORK_NEEDS_TWO_BRANCHES' | 'BRANCH_UNREACHABLE_AFTER' | 'LOOP_HAS_NO_BODY' | 'TRY_HAS_NO_BODY' | 'TRY_HAS_NO_HANDLER' | 'LOOP_LIST_NOT_A_LIST' | 'REPEAT_HAS_NO_CONDITION' | 'VAR_UNKNOWN' | 'BLOCK_UNKNOWN' | 'BLOCK_RECURSION' | 'RETURN_OUTSIDE_BLOCK' | 'BLOCK_PATH_WITHOUT_RETURN' | 'STEP_AFTER_RETURN' | 'BLOCK_ID_DUPLICATE' | 'DECLARATION_KEY_DUPLICATE' | 'STEP_ID_DUPLICATE' | 'CONNECTION_NOT_ESTABLISHED' | 'CONNECTION_UNKNOWN' | 'CONNECTION_UNRESOLVABLE' | 'CONNECTION_TYPE_MISMATCH';
+export interface DefinitionDiagnosticSpec {
+    readonly code: DefinitionCode;
+    readonly blocks: Blocks;
+    /** Template. `{name}` holes are filled by `formatDefinitionMessage`. */
+    readonly message: string;
+}
+/**
+ * `blocks` is part of the shared contract. A code that stopped Publish here
+ * and merely informed in Go would let a workflow publish from one builder
+ * and not another.
+ */
+export declare const DEFINITION_DIAGNOSTICS: Record<DefinitionCode, DefinitionDiagnosticSpec>;

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from './authoring';
+export * from './blocks';
+export * from './connections';
+export * from './diagnostic';
+export * from './execution';
+export * from './metadata';
+export * from './scope';
+export * from './segment';
+export * from './slots';
+export * from './tree';
+export * from './validity';