@w6w/embed 0.2.1 → 0.2.19

package/dist/lib/import-bindings.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Pure row logic behind `ImportSpecModal`'s configure step (T2.1.1, IF-1 / D-B8 / D-B9).
+ *
+ * Turns the server's `POST /spec/preview` dependencies into editable rows and back into the
+ * `selections` map the import body carries. The client NEVER ranks: a row's initial selection is
+ * exactly the server's `suggested`. Every dependency yields exactly one selection on the way out —
+ * `{mode:"unconfigured"}` included, never omitted and never upgraded to a suggestion the user
+ * cleared.
+ *
+ * `node --test` throws `ERR_UNKNOWN_FILE_EXTENSION` on anything reaching the `@w6w/ui` import graph
+ * (see `lib/import-paste.ts`), so this module takes no value import at all.
+ */
+export type DependencyKind = "connection" | "var" | "secret" | "const" | "store";
+export type Selection = {
+    mode: "bind";
+    target: string;
+} | {
+    mode: "create";
+    name: string;
+} | {
+    mode: "unconfigured";
+};
+export type SelectionMode = Selection["mode"];
+export interface DependencyOption {
+    id: string;
+    label: string;
+    source: "connection" | "built-in" | "var" | "secret" | "const" | "store";
+    authKey?: string;
+    compatible?: boolean;
+    reason?: string;
+}
+export interface SpecDependency {
+    key: string;
+    kind: DependencyKind;
+    name: string;
+    app?: string;
+    authHint?: {
+        method: "built-in";
+    } | {
+        method: "authKey";
+        authKey: string;
+    };
+    usages: {
+        nodeId: string | null;
+        path: string;
+        access?: "read" | "write" | "delete";
+    }[];
+    store?: {
+        kind: "kv" | "doc" | "table" | null;
+        schema: unknown | null;
+        access: {
+            read: boolean;
+            write: boolean;
+            delete: boolean;
+        };
+    };
+    dynamic?: true;
+}
+export interface PreviewDependency extends SpecDependency {
+    options: DependencyOption[];
+    suggested: Selection;
+    canCreate: boolean;
+}
+export interface ImportRow {
+    key: string;
+    dep: PreviewDependency;
+    /** Options offered to the row (the server's, plus any connection created in-modal). */
+    options: DependencyOption[];
+    selection: Selection;
+    /** Remembered name for `create`, so toggling modes does not lose an edit. */
+    createName: string;
+}
+/** IF-1 "Allowed modes". */
+export declare function allowedModes(dep: PreviewDependency): SelectionMode[];
+/** One row per dependency; the initial selection is `suggested` verbatim (D-B9). */
+export declare function buildRows(deps: readonly PreviewDependency[]): ImportRow[];
+/** Bind a row to an option. Refused (row unchanged) for an unknown / incompatible option or a disallowed mode. */
+export declare function setBind(rows: readonly ImportRow[], key: string, target: string): ImportRow[];
+/** Switch a store row to `create` / edit its name. Refused unless `create` is allowed. */
+export declare function setCreateName(rows: readonly ImportRow[], key: string, name: string): ImportRow[];
+/** Leave the dependency unconfigured (always allowed). */
+export declare function setUnconfigured(rows: readonly ImportRow[], key: string): ImportRow[];
+/** A connection was just created via "Add connection": offer it and bind the row to it. */
+export declare function withCreatedConnection(rows: readonly ImportRow[], key: string, id: string, label: string): ImportRow[];
+/** Whether a row can be submitted: a `create` needs a non-blank name. */
+export declare function rowReady(row: ImportRow): boolean;
+export declare function rowsReady(rows: readonly ImportRow[]): boolean;
+/** The import body's `selections`: ONE entry per dependency key, `unconfigured` included. */
+export declare function toSelections(rows: readonly ImportRow[]): Record<string, Selection>;

package/dist/lib/index.d.ts

@@ -1,5 +1,6 @@
 export * from './workflow-validity.ts';
 export * from './workflow-variables.ts';
+export * from './starting-data.ts';
 export * from './workflow-settings.ts';
 export * from './workflow-route.ts';
 export type { RailCallable } from './code-rail.ts';
@@ -22,3 +23,6 @@ export * from './input-seeding.ts';
 export * from './input-coverage.ts';
 export * from './coerce-input.ts';
 export * from './callable-record.ts';
+export * from './binding-problems.ts';
+export * from './setup-incomplete.ts';
+export * from './import-bindings.ts';

package/dist/lib/invoke-error.d.ts

@@ -0,0 +1 @@
+export declare function invokeErrorCopy(e: unknown): string;

package/dist/lib/rail-settings.d.ts

@@ -78,7 +78,7 @@ export declare function hasDelete(kind: RailSettingsKind): boolean;
  * `/endpoints/:id/spec` by a wrong `if`/`else` fallthrough — every one of the four
  * `RailSettingsKind` arms is named explicitly below.
  */
-export declare function specCollectionForKind(kind: RailSettingsKind): "functions" | "endpoints" | null;
+export declare function specCollectionForKind(kind: RailSettingsKind): "functions" | "endpoints" | "workflows" | null;
 /** What A8's `evaluateEdit` needs to know about the row already on screen — deliberately
  *  narrower than a whole `FunctionDef`/`EndpointDef`: the two fields a hand-edit must not
  *  be allowed to change out from under the row it opened on. */

package/dist/lib/sdk-snippets.d.ts

@@ -49,7 +49,7 @@ export type SnippetCallable = {
     kind: "connection";
     id: string;
     action: string;
-    params?: string[];
+    params?: readonly SnippetInput[];
 } | {
     kind: "var";
     name: string;

package/dist/lib/setup-incomplete.d.ts

@@ -0,0 +1,22 @@
+/** A name list for one category; `ready:false` (loading/errored) means that category is never flagged. */
+export interface SetupNameList {
+    names: string[];
+    ready: boolean;
+}
+export interface SetupIncompleteInput {
+    /** The parsed saved workflow (nodes, connections, variables, …). */
+    workflow: unknown;
+    lists: {
+        vars: SetupNameList;
+        secrets: SetupNameList;
+        constants: SetupNameList;
+        stores: SetupNameList;
+    };
+}
+/** Node id -> human labels of what is missing at that node (e.g. `connection "gmail"`, `var.x`). */
+export type SetupIncompleteResult = Record<string, string[]>;
+/**
+ * Derive what is unconfigured in a saved workflow (plan IF-1 shape), keyed by node id.
+ * A category whose list is not `ready` is never flagged.
+ */
+export declare function findSetupIncomplete(input: SetupIncompleteInput): SetupIncompleteResult;

package/dist/lib/starting-data.d.ts

@@ -0,0 +1,31 @@
+import { WorkflowVariableRow } from './workflow-variables.ts';
+/** Why a Starting data draft cannot be saved. */
+export type StartingDataProblem = "invalid_json" | "not_object" | "too_large";
+/** The outcome of reading a Starting data draft for save. `value: undefined` drops the key. */
+export type StartingDataForSave = {
+    ok: true;
+    value: Record<string, unknown> | undefined;
+} | {
+    ok: false;
+    reason: StartingDataProblem;
+};
+/**
+ * Read a definition's `initialState` field. Takes `unknown` because the source is
+ * `JSON.parse`d and the `</>` editor lets an author type anything: only a plain
+ * object counts; anything else reads as "no starting data".
+ */
+export declare function readStartingData(raw: unknown): Record<string, unknown> | undefined;
+/**
+ * Turn the tab's JSON text into the value `patchMeta({ initialState })` saves.
+ * Blank text and `{}` both mean "no starting data" (`value: undefined`, so the
+ * key is dropped from the definition). Anything but a plain object is refused,
+ * as is an object whose serialised form exceeds `STATE_LIMITS.initialChars`
+ * (measured exactly as the server measures it: `JSON.stringify(v).length`).
+ */
+export declare function startingDataForSave(text: string): StartingDataForSave;
+/**
+ * The declared variable keys that are also top-level keys of the starting data —
+ * on those keys the variable's value wins (R2'). Variable declaration order, no
+ * duplicates, no empty keys.
+ */
+export declare function startingDataCollisions(initial: Record<string, unknown> | undefined, variables: readonly WorkflowVariableRow[]): string[];

package/dist/lib/state-panel.d.ts

@@ -0,0 +1,29 @@
+import { StateLogRow } from '@w6w/expr';
+/**
+ * The run's state tree: the snapshot `GET /runs/:id` serves when one was persisted, else the
+ * state-write log folded by `@w6w/expr`'s `foldStateLog` (the same fold the run log's "state
+ * after this step" uses). `undefined` when neither has anything.
+ */
+export declare function runStateTree(snapshot: unknown, writes: readonly StateLogRow[] | undefined): Record<string, unknown> | undefined;
+/**
+ * Who last wrote each top-level state key, from the run's state-write log: the node id of the
+ * last write under that key, or `null` for a key that came from the starting state (the seed row,
+ * `seq 0` with no node). A warning row wrote nothing; a delete (`new` absent or `null`) forgets the
+ * key; a whole-tree write (`path []`) hands every key it sets to its node. Read in `seq` order
+ * whatever order the rows arrive in.
+ */
+export declare function stateKeyWriters(writes: readonly StateLogRow[]): Map<string, string | null>;
+/** One line of the starting state preview: a leaf's dotted path and how it reads. */
+export interface StartingStateRow {
+    path: string;
+    /** `reference`: a string carrying a `{{ }}` reference, resolved when a run starts. */
+    kind: "literal" | "reference";
+    /** The reference text verbatim, or the literal as JSON. */
+    text: string;
+}
+/**
+ * The starting state flattened to one row per leaf, in key order: nested objects descend
+ * (`a.b`), arrays and empty objects stay one literal row. A string with a `{{ }}` reference is a
+ * `reference` row shown as typed, never as a value: it only resolves when a run starts.
+ */
+export declare function startingStateRows(initial: Record<string, unknown> | undefined): StartingStateRow[];

package/dist/lib/target-fields.d.ts

@@ -1,18 +1,4 @@
-/**
- * Pure helpers shared by `TargetSelector`'s three arms (rfcs/endpoint.md
- * :339-347 — `EndpointTarget = CallableRef | ActionTarget`) and by
- * `EndpointsPage`'s save gate.
- *
- * Pure and testable by design, mirroring `workflow-validity.ts`'s shape:
- * `@w6w/ui`'s `package.json` `exports["."]` resolves to raw `./src/index.ts`,
- * which re-exports `.tsx` files, so `node --test` throws
- * `ERR_UNKNOWN_FILE_EXTENSION` the moment anything here imports `@w6w/ui` or
- * `@w6w/ui/flow` — even type-only. So this module declares its own local
- * structural (`*Like`) types instead of importing the real ones from
- * `../api/types.ts`, and `isTriggerApp`/`asFieldDefs` (the workflow arm's only
- * dependency on `@w6w/ui/flow`) are **caller-injected** — `TargetSelector.tsx`
- * (unaffected by the JSX constraint) imports the real ones and passes them in.
- */
+import { ParamWhen } from '@w6w/expr';
 /** The four arms `EndpointTarget` can take; a Function's `impl` takes the
  *  first three (D-8) — `"endpoint"` is alias-only, never legal for `Fn.impl`. */
 export type TargetKind = "action" | "function" | "workflow" | "endpoint";
@@ -79,6 +65,7 @@ export interface ParamLike {
     required?: boolean;
     default?: unknown;
     showIf?: ShowIfPredicate;
+    when?: ParamWhen[];
 }
 /** Visibility predicate — mirroring ActionParam.showIf from @w6w/ui. */
 export interface ShowIfPredicate {
@@ -104,6 +91,7 @@ export interface WorkflowStepLike {
 }
 /** A workflow definition, just enough of it for the trigger-field union. */
 export interface WorkflowLike {
+    nodes?: unknown;
     steps?: unknown;
 }
 /** Everything `fieldsFromWorkflow` needs from `@w6w/ui/flow` but cannot import itself. */
@@ -121,6 +109,7 @@ export interface TargetField {
     required?: boolean;
     default?: unknown;
     showIf?: ShowIfPredicate;
+    when?: ParamWhen[];
 }
 /** One row of an input-contract list (`FunctionInput`/`EndpointInput`'s common shape). */
 export interface InputRowLike {
@@ -153,6 +142,13 @@ export declare function implToTarget(impl: FunctionImplLike | undefined): Action
  * `{}`, not absent, on a CallableRef impl too.
  */
 export declare function targetToImpl(target: ActionTargetLike | CallableTargetLike): FunctionImplLike;
+/**
+ * The `impl` a re-pick produces. `outputMap` adapts ONE binding's vendor response, so it survives
+ * only while the binding identity is unchanged: the same `uses.app` + `uses.action` (action arm),
+ * or the same callable kind + id (ref arm). Connection and `with` edits keep it; a different
+ * action or callee drops it (rfcs/function.md: switching provider replaces `impl` wholesale).
+ */
+export declare function implAfterRebind(prev: FunctionImplLike | undefined, target: ActionTargetLike | CallableTargetLike): FunctionImplLike;
 /** Project a list of action/function params into the normalized `TargetField[]` (A5). */
 export declare function paramsToFields(params: ParamLike[]): TargetField[];
 /**

package/dist/lib/trigger-preview.d.ts

@@ -44,6 +44,7 @@ export interface WorkflowStepLike {
 }
 /** A workflow definition, just enough of it for this preview. */
 export interface WorkflowLike {
+    nodes?: WorkflowStepLike[];
     steps?: WorkflowStepLike[];
 }
 /**

package/dist/lib/workflow-live-run.d.ts

@@ -1,3 +1,4 @@
+import { StateLogRow } from '@w6w/expr';
 import { RunStatus } from '@w6w/sdk';
 export type { RunStatus };
 /**
@@ -23,16 +24,25 @@ export type StepMetaLike = {
  *  `ExecutionLogPanel` row. */
 export interface StepExecutionLike {
     status: StepStatus;
+    /** Why a `skipped` step did not run (`NodeExecution.skipReason`); read as `unknown` (opaque
+     *  wire) and carried only when it is one of the four known reasons. */
+    skipReason?: unknown;
     startedAt?: string;
     finishedAt?: string;
     input?: unknown;
     output?: unknown;
+    logs?: string[];
     /** `StepExecution.error` — a `StepError` on `failed` per rfcs/workflow.md
      *  §StepExecution, but read as `unknown` because `RunState.steps` is opaque
      *  on the wire; {@link toLogError} normalises whatever actually arrives. */
     error?: unknown;
     /** Recorded metadata; absent (or null) for steps that recorded none. */
     meta?: StepMetaLike | null;
+    /** For each only (I3): per-iteration body records, read as `unknown` (opaque wire). */
+    iterations?: unknown;
+    iterationsTotal?: unknown;
+    iterationsFailed?: unknown;
+    iterationsTruncated?: unknown;
 }
 /** A step or run error, as the run log panel renders it — field-for-field
  *  `@w6w/ui`'s `ExecutionLogError` (rfcs/workflow.md §StepError's
@@ -56,17 +66,24 @@ export interface RunErrorSourceLike {
     status?: string;
     error?: unknown;
     stepErrors?: ReadonlyArray<{
-        stepId: string;
+        nodeId?: string;
+        stepId?: string;
         error: unknown;
     }>;
 }
+/** The per-node execution map of a run record, in either shape — `nodes`
+ *  preferred, else the legacy `steps`. */
+export declare function runNodeMap(run: {
+    nodes?: unknown;
+    steps?: unknown;
+} | undefined | null): Record<string, StepExecutionLike> | undefined;
 /** The slice of a saved step-test fixture (`StepTest`) {@link latestFixtureInput}
  *  reads — `with` is what the trigger's Test tab invokes it with. */
 export interface StepTestFixtureLike {
     with?: unknown;
 }
 /** The row-level fallback for a `failed` step that carries no `error` at all. */
-export declare const STEP_FAILED_NO_REASON = "Step failed without reporting a reason.";
+export declare const STEP_FAILED_NO_REASON = "Node failed without reporting a reason.";
 /** The run-level fallback for a `failed` run where nothing carries a reason. */
 export declare const RUN_FAILED_NO_REASON = "Run failed without reporting a reason.";
 /** One `ExecutionLogPanel` row — field-for-field `@w6w/ui`'s
@@ -76,12 +93,39 @@ export declare const RUN_FAILED_NO_REASON = "Run failed without reporting a reas
 export interface ExecutionLogStepLike {
     id: string;
     status: StepStatus;
+    skipReason?: SkipReasonLike;
     startedAt?: string;
     finishedAt?: string;
     input?: unknown;
     output?: unknown;
+    logs?: string[];
     error?: LogErrorLike;
     meta?: StepMetaLike;
+    /** For each only (I4) — field-for-field `@w6w/ui`'s `ExecutionLogStep`. */
+    iterations?: ExecutionLogIterationLike[];
+    iterationsTotal?: number;
+    iterationsFailed?: number;
+    iterationsTruncated?: boolean;
+    /** This node's state writes (`GET /runs/:id/state-writes` rows, in `seq` order) —
+     *  field-for-field `@w6w/ui`'s `ExecutionLogStep.stateWrites` (plan §2.7). Absent → no State block. */
+    stateWrites?: StateWriteEntryLike[] | null;
+    /** The state tree right after this node's last write (`foldStateLog`). */
+    stateAfter?: Record<string, unknown> | null;
+}
+/** One state-write entry on a run-log row — `@w6w/ui`'s `ExecutionLogStep.stateWrites[number]`. */
+export type StateWriteEntryLike = {
+    path: string[];
+    item?: number;
+    old?: unknown;
+    new?: unknown;
+    warning?: string;
+};
+/** One For each iteration row (I4) — mirrors `@w6w/ui`'s `ExecutionLogIteration`. */
+export interface ExecutionLogIterationLike {
+    index: number;
+    status: "succeeded" | "failed" | "running";
+    failedNodeId?: string;
+    steps: ExecutionLogStepLike[];
 }
 /** How a cancel-request failure should be handled (A6). */
 export type CancelErrorOutcome = "reconcile" | "surface";
@@ -103,6 +147,21 @@ export declare function shouldContinuePolling(status: RunStatus | undefined): bo
  * each other.
  */
 export declare function isRunInFlight(status: RunStatus | undefined, pollFailed: boolean): boolean;
+/**
+ * When a run turns terminal, how long after (ms) the editor re-reads the workflow's saved step
+ * tests. The server books every step that succeeded in an editor run as its passing saved test
+ * (`step-passes.ts`) — the record the publish gate reads — but only AFTER the engine has
+ * checkpointed the run's terminal state, so the poll can see `succeeded` a few milliseconds before
+ * the pass lands. The immediate read covers the usual case; the later one covers that window.
+ */
+export declare const STEP_PASS_REFRESH_DELAYS_MS: readonly number[];
+/**
+ * Should the editor re-read this workflow's saved step tests now? Only once the run it polls is
+ * terminal and belongs to the open workflow — a run's passes are booked as it finishes, and the
+ * step-tests cache never refetches on its own (`refetchOnWindowFocus: false`), so without this
+ * the publish gate keeps the pre-run list and a step that just passed still blocks Publish.
+ */
+export declare function stepPassRefreshDue(status: RunStatus | undefined, runWorkflowId: string | undefined, workflowId: string): boolean;
 /** A1/A6 — what the Run button should read right now. */
 export declare function runButtonLabel(status: RunStatus | undefined, pollFailed: boolean): string;
 /**
@@ -115,12 +174,13 @@ export declare function runButtonLabel(status: RunStatus | undefined, pollFailed
 export declare function classifyCancelError(code: string): CancelErrorOutcome;
 /**
  * G5 — map a `RunState`'s opaque `steps` record onto `ExecutionLogPanel`'s
- * row shape, in the record's own key order (the order the server checkpoints
- * steps in, so it already reads as execution order). `ExecutionLogPanel`'s
- * own contract is "never re-sorted" (`ExecutionLogPanel.tsx`'s header), so
- * this function must not reorder either.
+ * row shape, preserving its keys and timestamps. Record key order is not
+ * execution order; `ExecutionLogPanel` sorts the rows chronologically for
+ * both live runs and saved history.
  */
-export declare function mapRunStateToLogSteps(steps: Record<string, StepExecutionLike> | undefined): ExecutionLogStepLike[];
+export declare function mapRunStateToLogSteps(steps: Record<string, StepExecutionLike> | undefined, stateLog?: readonly StateLogRow[]): ExecutionLogStepLike[];
+/** `@w6w/ui`'s `SkipReason`, restated locally (see {@link ExecutionLogStepLike}). */
+export type SkipReasonLike = "not_on_path" | "condition" | "stopped" | "disabled";
 /**
  * Normalise whatever a step or run reported as its error into the panel's
  * {@link LogErrorLike}. `null`/`undefined` mean "no error". A non-empty string
@@ -162,4 +222,29 @@ export declare function latestFixtureInput(tests: ReadonlyArray<StepTestFixtureL
  * click time on purpose — a cached `stepTestsKey` query can be stale, since
  * saving a fixture does not invalidate it.
  */
-export declare function resolveHeaderRunInput(triggerStepId: string | undefined, list: (stepId: string) => Promise<ReadonlyArray<StepTestFixtureLike> | undefined>): Promise<Record<string, unknown> | undefined>;
+export declare function resolveHeaderRunInput(triggerStepId: string | undefined, list: (stepId: string) => Promise<ReadonlyArray<StepTestFixtureLike> | undefined>, remembered?: () => Promise<ReadonlyArray<{
+    nodeId: string;
+    input: unknown;
+}> | undefined>): Promise<Record<string, unknown> | undefined>;
+/** The trigger the header Run starts at, and whether it is the Manual trigger. */
+export interface HeaderRunEntry {
+    id: string;
+    manual: boolean;
+}
+/**
+ * The trigger the header Run starts at, and so whose remembered sample payload it runs with: the
+ * FIRST Manual trigger (a run's own default entry), else the first other entry trigger — a
+ * webhook, a schedule or an app trigger. Before, only a Manual trigger was looked up, so a
+ * webhook-started workflow's header Run sent no payload at all. `undefined` when nothing in
+ * `steps` is a trigger. The predicates are injected (`@w6w/ui/flow`), as in `trigger-preview.ts`.
+ */
+export declare function headerRunEntry(steps: ReadonlyArray<{
+    id: string;
+    uses?: {
+        app?: string;
+        trigger?: unknown;
+    };
+}>, isManualTrigger: (app: string) => boolean, isEntryTrigger: (uses: {
+    app: string;
+    trigger?: true;
+}) => boolean): HeaderRunEntry | undefined;

package/dist/lib/workflow-nodes.d.ts

@@ -0,0 +1,5 @@
+/** The vertex array of a workflow definition, in either shape — `nodes` wins, `steps` is the legacy name. */
+export declare function workflowNodes<T = unknown>(def: {
+    nodes?: T[];
+    steps?: T[];
+} | null | undefined): T[];

package/dist/lib/workflow-validity.d.ts

@@ -8,6 +8,22 @@
  * > and every step is valid. Graph well-formedness (orphaned/unreachable
  * > nodes, dangling edges) is explicitly OUT of scope for this project.
  *
+ * **Amended 2026-10-29: no trigger NODE is required.** A workflow without one is
+ * a manual workflow (`rfcs/workflow.md:114`): it already runs from the editor's
+ * Run button and from code, and the server publishes it, so gating Publish on a
+ * trigger node only blocked a workflow that works. The workflow is now valid iff
+ * it has at least one step and every step is valid.
+ *
+ * **Amended 2026-11-01: an app trigger node is never test-gated.** A node with
+ * `uses.trigger: true` runs when its app reports the event; its Test tab has
+ * nothing to run by hand ("Publish the workflow to start listening",
+ * `AppTriggerTestNote` in `@w6w/ui`), so it can never hold a saved passing
+ * test. Gating it on one made every app-triggered workflow unpublishable.
+ *
+ * **Amended 2026-11-02: tests never gate publishing.** Successful runs and saved
+ * test records can disagree, and users may publish without testing. Only the
+ * target and required configuration are checked; test history is advisory.
+ *
  * Pure and testable by design: `WorkflowsPage.tsx` is JSX, which Node 24's
  * type-stripping cannot parse, so nothing in it can be loaded by `node --test`
  * (same shape as `src/lib/workflow-save.ts` + its `.test.ts`). This module
@@ -18,11 +34,7 @@
  * the two functions the pinned predicate reuses
  * (`requiredParamsFilled`/`isTestRequired`) are **caller-injected** on
  * `ValidityContext` — `WorkflowsPage.tsx` (unaffected by the JSX constraint)
- * imports the real ones from `@w6w/ui` and passes them in. Same for "a
- * trigger exists": that reads a graph STEP whose `INTERNAL_NODES` entry has
- * `group === "trigger"` (`@w6w/ui/flow`), never the workflow's top-level
- * `trigger` field (`rfcs/workflow.md:114`, "Absent means manual-only" — always
- * present, so it can't gate anything) — so `hasTrigger` is caller-computed too.
+ * imports the real ones from `@w6w/ui` and passes them in.
  *
  * `ActionParamLike`/`WorkflowStepLike`/`WorkflowLike` below are this file's
  * own minimal local types (see `rfcs/workflow.md` §"Step" for the real shape,
@@ -42,13 +54,18 @@ export interface WorkflowStepLike {
     uses?: {
         app?: string;
         action?: string;
+        connection?: string | null;
+        connectionRef?: string;
         /** The "or a function id" arm (`rfcs/function.md:49,260`) — `Step.uses.function`. */
         function?: string;
+        /** An app trigger node (`uses.trigger: true`): never gated on a saved test. */
+        trigger?: boolean;
     };
     with?: Record<string, unknown>;
 }
 /** A workflow definition, just enough of it for this gate. */
 export interface WorkflowLike {
+    nodes?: WorkflowStepLike[];
     steps?: WorkflowStepLike[];
     /**
      * Present on real definitions, never read here — graph well-formedness
@@ -63,30 +80,62 @@ export interface WorkflowLike {
  * each field is caller-built rather than derived in here.
  */
 export interface ValidityContext {
-    /** Does the graph contain a step whose (app, action) is a trigger node? */
-    hasTrigger: boolean;
     /** Declared params for a step's target, keyed `` `${app}::${action}` ``. */
     actionParamsByKey: Record<string, ActionParamLike[]>;
-    /** The fetched apps list, keyed by app id — only a key present here is test-gated. */
+    /** @deprecated Kept for caller compatibility; app test policy does not gate publishing. */
     appsById: Record<string, unknown>;
-    /** Whether the given step id has a saved test that last ran successfully. */
+    /** @deprecated Kept for caller compatibility; test results do not gate publishing. */
     testStatus: Record<string, boolean>;
     /** `@w6w/ui`'s `requiredParamsFilled`, injected (see module docstring). */
     requiredParamsFilled: (params: ActionParamLike[], values: Record<string, unknown>) => boolean;
-    /** `@w6w/ui`'s `isTestRequired`, injected (see module docstring). */
+    /** @deprecated Kept for caller compatibility; never consulted for publishing. */
     isTestRequired: (app: unknown) => boolean;
 }
+/** Which of the pinned predicate's checks a step fails, or `null` when it's valid. */
+type StepFailure = "target missing" | "required params";
 /** Is this one step valid, per the pinned predicate? */
 export declare function stepValid(step: WorkflowStepLike, ctx: ValidityContext): boolean;
 /**
- * Is the whole workflow valid? A trigger step must exist and every step must
- * be individually valid — nothing about graph well-formedness (this never
- * reads `workflow.edges`, even when present).
+ * Is the whole workflow valid? It must have at least one step and every step
+ * must be individually valid — a trigger node is not required, and nothing
+ * about graph well-formedness is checked (this never reads `workflow.edges`).
  */
 export declare function workflowValid(workflow: WorkflowLike, ctx: ValidityContext): boolean;
 /**
- * `null` when the workflow is valid; otherwise names the cause — `"no trigger
- * step"`, or the id of the first invalid step in declared order plus which
- * check it fails.
+ * `null` when the workflow is valid; otherwise names the cause — `"no steps"`,
+ * or the id of the first invalid step in declared order plus which check it
+ * fails.
  */
 export declare function invalidReason(workflow: WorkflowLike, ctx: ValidityContext): string | null;
+/** One reason the workflow cannot be published: the node it is about and how to fix it. */
+export interface PublishProblem {
+    /** The node's id, or `null` for a workflow-wide problem (`"no steps"`). */
+    stepId: string | null;
+    check: StepFailure | "no steps";
+    /** Names the node and says how to fix it — shown verbatim in the tooltip and the list. */
+    message: string;
+}
+/**
+ * Every publish problem, in declared node order — the full list `invalidReason`
+ * stops at the first of. Empty iff `workflowValid`.
+ */
+export declare function publishProblems(workflow: WorkflowLike, ctx: ValidityContext): PublishProblem[];
+/** What the header Publish button's `disabled` reads, each cause kept apart for its reason. */
+export interface PublishGate {
+    /** No project to publish into. */
+    projectMissing: boolean;
+    /** The draft has not loaded, is saving, or is switching context. */
+    loading: boolean;
+    /** The draft refuses to save (and so to publish): its reason, verbatim. */
+    saveBlockedReason: string | null;
+    /** The node catalog the validity gate needs has not arrived yet. */
+    catalogLoading: boolean;
+    problems: readonly PublishProblem[];
+    publishing: boolean;
+}
+/**
+ * Why Publish is disabled, or `null` when it is enabled. Every disabled state
+ * has a reason, so the button never greys out silently.
+ */
+export declare function publishDisabledReason(g: PublishGate): string | null;
+export {};

package/dist/lib/workflow-variables.d.ts

@@ -66,7 +66,7 @@ export declare function variablesForSave(rows: WorkflowVariableRow[]): WorkflowV
  */
 export declare function duplicateKeyIndexes(rows: WorkflowVariableRow[]): number[];
 /**
- * The `vars.*` names to offer row `index`'s expression rail: the keys of
+ * The `var.*` names to offer row `index`'s expression rail: the keys of
  * rows **strictly above** it, then `projectVars`, deduped, with blanks
  * dropped. Declaration order is resolution order (D-5), so a row can only
  * reference a variable declared earlier than itself — offering a row at or

package/dist/lib/workflow-version.d.ts

@@ -0,0 +1,2 @@
+/** Compare JSON definitions independent of object property order. Array order is meaningful. */
+export declare function sameWorkflowDefinition(a: unknown, b: unknown): boolean;