@makaio/framework 1.0.0-dev-1781729807808 → 1.0.0-dev-1781884053376

package/dist/transition-CCflZ6JS.d.mts

@@ -0,0 +1,454 @@
+import { mt as ArtifactRevision$1 } from "./index--diIlm1t.mjs";
+import { i as JsonValue$1 } from "./json-value-DtIkQN7g.mjs";
+import { z } from "zod";
+import * as _$_makaio_contracts0 from "@makaio/framework/contracts";
+
+//#region core/contracts/src/workflow/blocks.d.ts
+/**
+ * JSON Schema document used for `outputSchema` fields on step block run mappings.
+ *
+ * A JSON Schema document is a JSON object (`Record<string, JsonValue>`). Using
+ * the inferred type from {@link JsonSchemaRecordSchema} keeps this type consistent
+ * with the schema validator used in persisted workflow node definitions.
+ */
+type JsonSchemaRecord = Record<string, JsonValue$1>;
+/**
+ * Step block run mapping that compiles into a `station` primitive node.
+ *
+ * A station node is an atomic work unit executed by an AI agent or registered
+ * runtime handler. The `prompt` is a template evaluated against the builder
+ * form values; the optional `role` selects the executor role.
+ */
+interface StationNodeBlockRun {
+  /** Run mapping discriminant. */
+  readonly type: 'station';
+  /**
+   * Task prompt template compiled into the station node.
+   * Supports `{{ config.<field> }}` and `{{ input.<field> }}` interpolation.
+   */
+  readonly prompt: string;
+  /**
+   * Named role reference forwarded to the compiled station node.
+   * Resolved via the bus `resolveRole` RPC before execution.
+   */
+  readonly role?: string;
+  /**
+   * JSON Schema for the expected station output.
+   * Forwarded verbatim to the compiled station node's `outputSchema` field.
+   */
+  readonly outputSchema?: JsonSchemaRecord;
+  /**
+   * Positive timeout in milliseconds forwarded to the compiled station node.
+   * Defaults to 300 000 ms at execution time when omitted.
+   */
+  readonly timeoutMs?: number;
+}
+/**
+ * Step block run mapping that compiles into a `delegate-agent` primitive node.
+ *
+ * The `agentId` references a registered agent definition. The block builder
+ * resolves `inputExpression` against the configured form values when compiling
+ * the node.
+ */
+interface DelegateAgentNodeBlockRun {
+  /** Run mapping discriminant. */
+  readonly type: 'delegate-agent';
+  /**
+   * Identifier of the registered agent definition to invoke.
+   */
+  readonly agentId: string;
+  /**
+   * jexl expression template resolving to the agent input payload.
+   * Supports `{{ config.<field> }}` and `{{ input.<field> }}` interpolation
+   * that the builder resolves when compiling into a concrete node.
+   */
+  readonly inputExpression?: string;
+  /**
+   * JSON Schema for the expected agent output.
+   * Forwarded verbatim to the compiled node's `outputSchema` field.
+   */
+  readonly outputSchema?: JsonSchemaRecord;
+}
+/**
+ * Step block run mapping that compiles into a `delegate-role` primitive node.
+ *
+ * The `role` is a product-resolved named executor. The `prompt` template is
+ * evaluated against the builder form values when compiling the node.
+ */
+interface DelegateRoleNodeBlockRun {
+  /** Run mapping discriminant. */
+  readonly type: 'delegate-role';
+  /**
+   * Named role reference resolved via the bus `resolveRole` RPC at execution time.
+   */
+  readonly role: string;
+  /**
+   * Task prompt template forwarded to the compiled node.
+   * Supports `{{ config.<field> }}` and `{{ input.<field> }}` interpolation.
+   */
+  readonly prompt: string;
+  /**
+   * JSON Schema for the expected delegation output.
+   * Forwarded verbatim to the compiled node's `outputSchema` field.
+   */
+  readonly outputSchema?: JsonSchemaRecord;
+  /**
+   * Positive timeout in milliseconds forwarded to the compiled node.
+   * Defaults to 300 000 ms at execution time when omitted.
+   */
+  readonly timeoutMs?: number;
+}
+/**
+ * Discriminated union of all supported workflow step block run mappings.
+ *
+ * Each variant maps a declared step block to a concrete primitive node type.
+ * The builder compiles the selected variant into the workflow definition as the
+ * corresponding {@link WorkflowNode} subtype when the block is placed in the canvas.
+ *
+ * Extend this union when new primitive node types require builder support.
+ */
+type WorkflowStepBlockRun = StationNodeBlockRun | DelegateAgentNodeBlockRun | DelegateRoleNodeBlockRun;
+/**
+ * Metadata shared by all workflow blocks.
+ */
+interface WorkflowBlockMetadata {
+  /** Stable identifier, namespaced by extension (e.g., 'coderabbit.review-posted'). */
+  name: string;
+  /** Human-readable label for the builder UI. */
+  label: string;
+  /** Short description for tooltips and catalog. */
+  description: string;
+  /** Grouping tags for the builder palette. Uncategorized blocks appear in "Other". */
+  categories?: string[];
+}
+/**
+ * A trigger block declaration — determines WHEN a workflow starts.
+ * @typeParam TConfig - Zod shape for the builder configuration form.
+ * @typeParam TOutput - Zod type for the payload passed into the workflow as input.
+ */
+interface WorkflowTriggerBlock<TConfig extends z.ZodRawShape = z.ZodRawShape, TOutput extends z.ZodType = z.ZodType> {
+  /** Shared metadata used in the builder palette and catalog. */
+  metadata: WorkflowBlockMetadata;
+  /** Drives the configuration form in the builder UI. */
+  configSchema: z.ZodObject<TConfig>;
+  /** The payload shape passed into the workflow when this trigger fires. */
+  outputSchema: TOutput;
+}
+/**
+ * A step block declaration — determines WHAT happens inside a workflow.
+ *
+ * The `runs` field specifies which primitive node type this block compiles to
+ * when placed in the workflow canvas. The builder reads `runs` to construct a
+ * concrete {@link WorkflowNode} (station, delegate-agent, or delegate-role) for
+ * the persisted workflow definition.
+ * @typeParam TConfig - Zod shape for the builder configuration form.
+ * @typeParam TInput - Zod type for what this step expects from upstream.
+ * @typeParam TOutput - Zod type for what downstream steps can reference.
+ */
+interface WorkflowStepBlock<TConfig extends z.ZodRawShape = z.ZodRawShape, TInput extends z.ZodType = z.ZodType, TOutput extends z.ZodType = z.ZodType> {
+  /** Shared metadata used in the builder palette and catalog. */
+  metadata: WorkflowBlockMetadata;
+  /** Drives the configuration form in the builder UI. */
+  configSchema: z.ZodObject<TConfig>;
+  /** What this step expects from upstream (expressions/config). */
+  inputSchema: TInput;
+  /** What downstream steps can reference via steps.<id>.result. */
+  outputSchema: TOutput;
+  /**
+   * Primitive node compilation target for this step block.
+   *
+   * The builder reads this field and constructs the corresponding primitive
+   * node ({@link WorkflowStationNode}, {@link WorkflowDelegateAgentNode}, or
+   * {@link WorkflowDelegateRoleNode}) when the block is placed on the canvas.
+   */
+  runs: WorkflowStepBlockRun;
+}
+/**
+ * Collection of workflow blocks contributed by an extension.
+ */
+interface WorkflowBlockCollection$1 {
+  /** Trigger block declarations — each determines WHEN a workflow starts. */
+  readonly triggers?: readonly WorkflowTriggerBlock[];
+  /** Step block declarations — each determines WHAT happens inside a workflow. */
+  readonly steps?: readonly WorkflowStepBlock[];
+}
+/**
+ * Serialized trigger block as stored in the registry and served via bus.
+ *
+ * Schema fields are stored as JSON Schema objects for transport and builder
+ * catalog rendering.
+ */
+interface RegisteredTriggerBlock$1 {
+  /** Trigger metadata combined with the owning extension name. */
+  metadata: WorkflowBlockMetadata & {
+    extensionName: string;
+  };
+  /** JSON Schema representation of the builder configuration form. */
+  configSchema: Record<string, unknown>;
+  /** JSON Schema representation of the trigger output payload. */
+  outputSchema: Record<string, unknown>;
+}
+/**
+ * Serialized step block as stored in the registry and served via bus.
+ *
+ * Schema fields are stored as JSON Schema objects for transport and builder
+ * catalog rendering. The `runs` field is preserved verbatim from the block
+ * declaration so the builder can construct the target primitive node directly.
+ */
+interface RegisteredStepBlock$1 {
+  /** Step metadata combined with the owning extension name. */
+  metadata: WorkflowBlockMetadata & {
+    extensionName: string;
+  };
+  /** JSON Schema representation of the builder configuration form. */
+  configSchema: Record<string, unknown>;
+  /** JSON Schema representation of the expected upstream input. */
+  inputSchema: Record<string, unknown>;
+  /** JSON Schema representation of what downstream steps can reference. */
+  outputSchema: Record<string, unknown>;
+  /**
+   * Primitive node compilation target preserved verbatim from the block declaration.
+   * The builder uses this to construct the appropriate primitive node when
+   * placing the block on the canvas.
+   */
+  runs: WorkflowStepBlockRun;
+}
+//#endregion
+//#region core/contracts/src/workflow/transition.d.ts
+/**
+ * The set of artifact bus events that can trigger a transition rule.
+ *
+ * - `artifact.created` — fires when a new artifact is created
+ * - `artifact.revised` — fires when an existing artifact receives a new revision
+ * - `artifact.status.changed` — fires when a tracked status field changes
+ */
+declare const TransitionEventTypeSchema: z.ZodEnum<{
+  "artifact.created": "artifact.created";
+  "artifact.revised": "artifact.revised";
+  "artifact.status.changed": "artifact.status.changed";
+}>;
+type TransitionEventType$1 = z.infer<typeof TransitionEventTypeSchema>;
+/**
+ * Serializable condition evaluated against an artifact event payload.
+ *
+ * Stored as an opaque JSON record in the contracts layer. The pipeline
+ * service interprets this using `@makaio/rules` at evaluation time,
+ * supporting field comparisons, `$and`/`$or`/`$not` combinators, and
+ * `$expr` jexl expression strings.
+ *
+ * Evaluation context shape:
+ * - `artifact` — the `ArtifactRevision` involved in the event
+ * - `previous` — the previous `ArtifactRef` for `artifact.revised` events
+ * - `previousArtifact` — the resolved previous `ArtifactRevision` for
+ *   `artifact.revised` events when the artifact store can provide it
+ * - `path` — the status path for `artifact.status.changed` events
+ * - `current` — the new status value for `artifact.status.changed` events
+ */
+declare const TransitionConditionSchema: z.ZodRecord<z.ZodString, z.ZodType<_$_makaio_contracts0.JsonValue, unknown, z.core.$ZodTypeInternals<_$_makaio_contracts0.JsonValue, unknown>>>;
+type TransitionCondition = z.infer<typeof TransitionConditionSchema>;
+/**
+ * Invocation descriptor for the action to execute when a transition rule fires.
+ *
+ * `type` selects the registered action handler; `input` supplies the
+ * action-specific payload; `executionHints` threads optional infrastructure
+ * hints to the execution host.
+ *
+ * Built-in action type:
+ * - `'workflow.start'` — start a workflow execution via the bus
+ */
+declare const TransitionActionInvocationSchema: z.ZodObject<{
+  type: z.ZodString;
+  input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<_$_makaio_contracts0.JsonValue, unknown, z.core.$ZodTypeInternals<_$_makaio_contracts0.JsonValue, unknown>>>>;
+  executionHints: z.ZodOptional<z.ZodObject<{
+    source: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+      kind: z.ZodLiteral<"path">;
+      path: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      kind: z.ZodLiteral<"source">;
+      filename: z.ZodString;
+      source: z.ZodString;
+    }, z.core.$strict>], "kind">>;
+    requirements: z.ZodOptional<z.ZodObject<{
+      isolation: z.ZodOptional<z.ZodEnum<{
+        local: "local";
+        remote: "remote";
+        container: "container";
+      }>>;
+      capabilities: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$catchall<z.ZodType<_$_makaio_contracts0.JsonValue, unknown, z.core.$ZodTypeInternals<_$_makaio_contracts0.JsonValue, unknown>>>>>;
+    providers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<_$_makaio_contracts0.JsonValue, unknown, z.core.$ZodTypeInternals<_$_makaio_contracts0.JsonValue, unknown>>>>;
+  }, z.core.$catchall<z.ZodType<_$_makaio_contracts0.JsonValue, unknown, z.core.$ZodTypeInternals<_$_makaio_contracts0.JsonValue, unknown>>>>>;
+}, z.core.$strip>;
+type TransitionActionInvocation$1 = z.infer<typeof TransitionActionInvocationSchema>;
+/**
+ * Declarative rule that watches artifact events and triggers workflow actions.
+ *
+ * Transition rules are purely serializable — no functions. The pipeline service
+ * evaluates the `when` condition against the incoming artifact event payload and
+ * dispatches the `action` through the `TransitionActionRegistry` when the
+ * condition matches.
+ *
+ * ID namespacing:
+ * - Bundle-contributed rules: `'<bundleId>.<localId>'`
+ * - Extension-contributed rules: `'<extensionName>.<localId>'`
+ *
+ * Duplicate IDs across all sources hard-fail activation.
+ */
+declare const TransitionRuleDefinitionSchema$1: z.ZodObject<{
+  id: z.ZodString;
+  description: z.ZodOptional<z.ZodString>;
+  on: z.ZodEnum<{
+    "artifact.created": "artifact.created";
+    "artifact.revised": "artifact.revised";
+    "artifact.status.changed": "artifact.status.changed";
+  }>;
+  when: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<_$_makaio_contracts0.JsonValue, unknown, z.core.$ZodTypeInternals<_$_makaio_contracts0.JsonValue, unknown>>>>;
+  action: z.ZodObject<{
+    type: z.ZodString;
+    input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<_$_makaio_contracts0.JsonValue, unknown, z.core.$ZodTypeInternals<_$_makaio_contracts0.JsonValue, unknown>>>>;
+    executionHints: z.ZodOptional<z.ZodObject<{
+      source: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"path">;
+        path: z.ZodString;
+      }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"source">;
+        filename: z.ZodString;
+        source: z.ZodString;
+      }, z.core.$strict>], "kind">>;
+      requirements: z.ZodOptional<z.ZodObject<{
+        isolation: z.ZodOptional<z.ZodEnum<{
+          local: "local";
+          remote: "remote";
+          container: "container";
+        }>>;
+        capabilities: z.ZodOptional<z.ZodArray<z.ZodString>>;
+      }, z.core.$catchall<z.ZodType<_$_makaio_contracts0.JsonValue, unknown, z.core.$ZodTypeInternals<_$_makaio_contracts0.JsonValue, unknown>>>>>;
+      providers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<_$_makaio_contracts0.JsonValue, unknown, z.core.$ZodTypeInternals<_$_makaio_contracts0.JsonValue, unknown>>>>;
+    }, z.core.$catchall<z.ZodType<_$_makaio_contracts0.JsonValue, unknown, z.core.$ZodTypeInternals<_$_makaio_contracts0.JsonValue, unknown>>>>>;
+  }, z.core.$strip>;
+  enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+type TransitionRuleDefinition$1 = z.infer<typeof TransitionRuleDefinitionSchema$1>;
+/**
+ * Transition rule contribution surface for extension packages.
+ *
+ * Declarative static rules contributed by an extension. Processed by
+ * `TransitionContributionProcessor` during extension activation.
+ */
+interface ExtensionTransitionRulesContribution {
+  /**
+   * Transition rule definitions contributed by this extension.
+   *
+   * All IDs must be prefixed with `'<extensionName>.'` (enforced by the
+   * contribution processor). Duplicate IDs hard-fail activation.
+   */
+  readonly rules: readonly TransitionRuleDefinition$1[];
+}
+/**
+ * Callable transition action handler.
+ *
+ * Invoked by the pipeline when a matching rule fires. Receives the resolved
+ * invocation and the artifact event context so it can read artifact data when
+ * building downstream bus requests.
+ */
+interface TransitionActionHandler {
+  /**
+   * Execute the action.
+   * @param invocation - Resolved action invocation descriptor.
+   * @param context - Evaluation context built from the triggering artifact event.
+   * @returns Promise that resolves when the action dispatch completes.
+   */
+  readonly execute: (invocation: TransitionActionInvocation$1, context: TransitionEvaluationContext$1) => Promise<void>;
+}
+/**
+ * Factory that creates a {@link TransitionActionHandler} for a given action type.
+ *
+ * Factories are registered at contribution time and instantiated lazily by the
+ * pipeline service.
+ */
+type TransitionActionFactory$1 = () => TransitionActionHandler;
+/**
+ * Transition action factory contribution surface for extension packages.
+ *
+ * Extensions that need custom action semantics beyond the built-in
+ * `workflow.start` action register their handler factories here.
+ */
+interface ExtensionTransitionActionsContribution {
+  /**
+   * Map of action type strings to action handler factories.
+   *
+   * Each key is a registered action `type` string as declared in
+   * {@link TransitionActionInvocationSchema}. Values are factories
+   * called once per rule dispatch to produce a fresh handler.
+   *
+   * All keys must be prefixed with `'<extensionName>.'`.
+   */
+  readonly actions: Readonly<Record<string, TransitionActionFactory$1>>;
+}
+/**
+ * Context object passed to condition evaluation and action dispatch.
+ *
+ * The pipeline builds this from the incoming artifact event payload so
+ * that rules can reference `artifact`, `previous`, `path`, and `current`
+ * fields using dot-notation in their `when` conditions.
+ */
+interface TransitionEvaluationContext$1 {
+  /**
+   * The artifact revision involved in the event.
+   *
+   * The transition pipeline resolves ref-oriented artifact events, such as
+   * `artifact.status.changed`, before evaluating rules so authoring sees a
+   * consistent full-revision context.
+   */
+  readonly artifact: ArtifactRevision$1;
+  /**
+   * Previous value from the artifact event. For `artifact.revised` this is the
+   * previous artifact ref; for `artifact.status.changed` this is the previous
+   * status value.
+   */
+  readonly previous?: unknown;
+  /**
+   * Resolved previous artifact revision for `artifact.revised` events.
+   *
+   * This preserves `previous` as the original event value while giving rules a
+   * full before/after snapshot when they need to detect semantic deltas.
+   */
+  readonly previousArtifact?: ArtifactRevision$1;
+  /**
+   * JSON Pointer path to the status field that changed.
+   * Present only for `artifact.status.changed` events.
+   */
+  readonly path?: string;
+  /**
+   * Current status value after the change.
+   * Present only for `artifact.status.changed` events.
+   */
+  readonly current?: unknown;
+  /**
+   * Loop-protection metadata injected by the pipeline.
+   *
+   * Downstream actions can inspect this to detect and break
+   * artifact-triggered → workflow → artifact cycles.
+   */
+  readonly _transition: {
+    /**
+     * The transition rule ID that fired this action.
+     */
+    readonly ruleId: string;
+    /**
+     * The artifact event type that matched the rule.
+     */
+    readonly eventType: TransitionEventType$1;
+    /**
+     * Depth counter tracking recursive transition invocations.
+     *
+     * The pipeline increments this on each nested trigger level.
+     * Action handlers that re-emit artifact events must propagate this
+     * metadata so the pipeline can reject invocations that exceed the
+     * configured maximum depth.
+     */
+    readonly depth: number;
+  };
+}
+//#endregion
+export { WorkflowTriggerBlock as C, WorkflowStepBlockRun as S, RegisteredTriggerBlock$1 as _, TransitionActionInvocation$1 as a, WorkflowBlockMetadata as b, TransitionConditionSchema as c, TransitionEventTypeSchema as d, TransitionRuleDefinition$1 as f, RegisteredStepBlock$1 as g, DelegateRoleNodeBlockRun as h, TransitionActionHandler as i, TransitionEvaluationContext$1 as l, DelegateAgentNodeBlockRun as m, ExtensionTransitionRulesContribution as n, TransitionActionInvocationSchema as o, TransitionRuleDefinitionSchema$1 as p, TransitionActionFactory$1 as r, TransitionCondition as s, ExtensionTransitionActionsContribution as t, TransitionEventType$1 as u, StationNodeBlockRun as v, WorkflowStepBlock as x, WorkflowBlockCollection$1 as y };