automate.ax 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zach Sents
+
+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/README.md

@@ -0,0 +1,119 @@
+# `automate.ax`
+
+Happy-path Automate.ax package for automation authors. It provides the `automate` CLI plus the public helpers used in `automate.config.ts` and automation files.
+
+## Install
+
+```bash
+bun add automate.ax
+bun add @automate.ax/components-core
+```
+
+## CLI
+
+```bash
+bunx automate.ax --help
+bunx automate.ax login
+bunx automate.ax deploy --dir ./my-app
+bunx automate.ax org apikey create --org <organization>
+bunx automate.ax org apikey list --org <organization>
+```
+
+The published CLI defaults to `https://automate.ax`. From this repo, use
+`bun run cli:local -- <command>` to run against `http://localhost:3000`.
+Organization API key commands also support `rename` and `delete`; created
+secrets are shown once.
+
+## Config
+
+```ts
+import { defineConfig } from "automate.ax"
+
+export default defineConfig({
+  projectId: "project_...",
+})
+```
+
+`automate deploy` resolves the Automate.ax directory from `--dir`, the current directory,
+the nearest parent config, or a bounded downward config search.
+It writes local build artifacts to `.automate/build` and uploads bundled
+JavaScript artifacts to Automate.ax. Deployment fails when no `*.automation.ts`
+files are found. The CLI then polls the Graphile-backed snapshot, planning,
+configuration, and cleanup stages every two seconds. If account bindings are
+missing, interactive deployments prompt for eligible connected accounts; JSON
+output returns the authorization state. Ctrl-C detaches without cancelling the
+deployment.
+
+## Automation
+
+```ts
+import { log, onHttpRequest } from "@automate.ax/components-core"
+import { automation, transform } from "automate.ax"
+
+export default automation("When a request is received", () => {
+  const request = onHttpRequest({ scope: "automation" })
+  const method = request.method
+  const path = request.path
+  const message = transform(
+    [method, path],
+    (resolvedMethod, resolvedPath) =>
+      `${resolvedMethod} request to ${resolvedPath}`,
+  )
+
+  log({ value: message })
+})
+```
+
+`automation()` attaches a `.description` metadata field and runs the same bundle
+in planning, orchestration, and execution phases.
+
+`transform(signals, fn)` records its signal inputs as graph edges. Orchestration walks
+those inputs to durable event and action leaves without calling `fn`; execution
+materializes the inputs and then calls it. Transform results stay in memory and
+may be any value. `signal.transform(fn)` is the unary convenience form, and
+`signal.property` is shorthand for
+`signal.transform((value) => value.property)`. Property access composes across
+objects and primitives, so `request.path.length` is a `Signal<number>`.
+
+Declare custom actions at the top level, then call them inside an automation:
+
+```ts
+import { defineAction } from "automate.ax"
+import { z } from "zod"
+
+const notify = defineAction("Notify")
+  .describe("Sends a notification")
+  .input(
+    z.object({
+      message: z.string(),
+    }),
+  )
+  .output(z.void())
+  .handler(({ input }) => {
+    console.log(input.message)
+  })
+```
+
+Omitting `input` uses an empty-object schema, and omitting `output` uses a void
+schema. `describe`, `input`, and `output` can be called in any order or repeated
+before `handler`; the latest value for each replaces the previous one. The
+resulting action exposes its display metadata through `.meta`. Orchestration
+snapshots that metadata onto each action invocation for display and debugging.
+During execution, handlers receive a `runtime` object containing the platform
+capabilities available to action code. Orchestration and invocation transport
+methods are internal to the SDK. The current capabilities are
+`runtime.sendOutput({ type, data })` and `runtime.sendEmail(input)`.
+
+`runtime.sendOutput({ type, data })` requires a string discriminator and
+encodable data. It durably emits the output without ending the automation. A
+handler may emit multiple ordered outputs; call positions make retries
+idempotent. Outputs do not enter the trigger event bus.
+
+## Package Role
+
+Use `automate.ax` for app projects, automation and component authoring,
+deploy-time subscriptions, and the `automate` CLI. Install component packages
+such as `@automate.ax/components-core` for platform-provided actions and triggers.
+HTTP triggers return `202` immediately unless configured with
+`waitForResponse: true`; responding automations use the platform-provided
+`respondToHttpRequest` action.

package/dist/automation/actions.d.ts

@@ -0,0 +1,200 @@
+import { type Encodable, type ObjectProducingSchema, type ProducingSchema } from "@automate.ax/codec";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { type AccountAuthorizationAction, type IntegrationAccountReference, type IntegrationScopeRequirement, type ResolvedIntegrationAccount } from "./integrations.js";
+import type { Signal } from "./signal.js";
+declare const DEFAULT_ACTION_INPUT_SCHEMA: StandardSchemaV1<Record<string, never>>;
+declare const DEFAULT_ACTION_OUTPUT_SCHEMA: StandardSchemaV1<void>;
+/**
+ * Executor-only platform capabilities available to action handlers.
+ *
+ * These methods perform platform-managed effects without exposing credentials
+ * or execution infrastructure to the action.
+ */
+export interface ActionRuntime {
+    /**
+     * Emits a typed value from the current action execution.
+     *
+     * @param output - Value and application-defined type used to classify it.
+     * @param output.data - Encodable payload to emit.
+     * @param output.type - Application-defined output type.
+     */
+    sendOutput(output: {
+        /** Encodable payload to emit. */
+        data: Encodable;
+        /** Application-defined output type. */
+        type: string;
+    }): Promise<void>;
+    /**
+     * Sends a plain-text email through the platform.
+     *
+     * Resolves with the provider's message ID when one is available.
+     *
+     * @param input - Email fields.
+     * @param input.subject - Email subject line.
+     * @param input.text - Plain-text message body.
+     * @param input.to - Recipient email address.
+     */
+    sendEmail(input: {
+        /** Email subject line. */
+        subject: string;
+        /** Plain-text message body. */
+        text: string;
+        /** Recipient email address. */
+        to: string;
+    }): Promise<{
+        /** Provider message ID, or `null` when the provider supplies none. */
+        id: string | null;
+    }>;
+}
+/**
+ * Implements an action after its input and account selection are materialized.
+ *
+ * The handler receives schema-validated input and, for account-backed actions,
+ * the resolved account secret. Its result is subsequently validated by the
+ * action's output schema.
+ *
+ * @template TInputSchema - Schema used to validate materialized action input.
+ * @template TOutputSchema - Schema used to validate the handler result.
+ * @template TAccountServiceId - Required integration service, or `never` when
+ *   the action does not use an account.
+ */
+export type ActionHandler<TInputSchema extends ObjectProducingSchema<unknown> = ObjectProducingSchema<unknown>, TOutputSchema extends ProducingSchema<Encodable> = ProducingSchema<Encodable>, TAccountServiceId extends string = never> = (options: {
+    /** Parsed input produced by the action's input schema. */
+    input: StandardSchemaV1.InferOutput<TInputSchema>;
+    /** Platform-managed capabilities available during execution. */
+    runtime: ActionRuntime;
+} & ([TAccountServiceId] extends [never] ? object : {
+    /**
+     * Resolved credentials for the integration service required by the
+     * action.
+     */
+    account: ResolvedIntegrationAccount<TAccountServiceId>;
+})) => Promise<StandardSchemaV1.InferInput<TOutputSchema>> | StandardSchemaV1.InferInput<TOutputSchema>;
+/** Display metadata attached to a defined action. */
+export interface ActionMetadata {
+    /** Optional explanation of what the action does. */
+    readonly description?: string;
+    /** Human-readable action name. */
+    readonly name: string;
+}
+/**
+ * Fluent definition state for an action.
+ *
+ * The generic state records the configured schemas and account requirement so
+ * the final handler and callable action remain fully inferred.
+ *
+ * @template TInputSchema - Currently configured input schema.
+ * @template TOutputSchema - Currently configured output schema.
+ * @template TAccountServiceId - Required integration service, or `never` for an
+ *   action without an account requirement.
+ */
+export interface ActionBuilder<TInputSchema extends ObjectProducingSchema<unknown> = typeof DEFAULT_ACTION_INPUT_SCHEMA, TOutputSchema extends ProducingSchema<Encodable> = typeof DEFAULT_ACTION_OUTPUT_SCHEMA, TAccountServiceId extends string = never> {
+    /**
+     * Requires an integration account when planning and executing the action.
+     *
+     * @template TNextAccountServiceId - Integration service required by the
+     *   resulting builder.
+     * @param serviceId - Stable identifier of the required integration service.
+     * @param requiredScopes - Provider scopes the selected account must satisfy.
+     */
+    account<TNextAccountServiceId extends string>(serviceId: TNextAccountServiceId, requiredScopes?: IntegrationScopeRequirement[]): ActionBuilder<TInputSchema, TOutputSchema, TNextAccountServiceId>;
+    /**
+     * Adds a human-readable description to action metadata.
+     *
+     * @param description - Explanation shown to users and planning tools.
+     */
+    describe(description: string): ActionBuilder<TInputSchema, TOutputSchema, TAccountServiceId>;
+    /**
+     * Sets the schema used to validate materialized action input.
+     *
+     * @template TNextInputSchema - Input schema stored by the resulting builder.
+     * @param schema - Standard Schema-compatible schema producing an object.
+     */
+    input<TNextInputSchema extends ObjectProducingSchema<unknown>>(schema: TNextInputSchema): ActionBuilder<TNextInputSchema, TOutputSchema, TAccountServiceId>;
+    /**
+     * Sets the schema used to validate the action handler's result.
+     *
+     * @template TNextOutputSchema - Output schema stored by the resulting
+     *   builder.
+     * @param schema - Standard Schema-compatible output schema.
+     */
+    output<TNextOutputSchema extends ProducingSchema<Encodable>>(schema: TNextOutputSchema): ActionBuilder<TInputSchema, TNextOutputSchema, TAccountServiceId>;
+    /**
+     * Completes the definition with its execution implementation.
+     *
+     * @param handler - Implementation invoked with validated input and runtime
+     *   capabilities.
+     */
+    handler(handler: ActionHandler<TInputSchema, TOutputSchema, TAccountServiceId>): DefinedAction<TInputSchema, TOutputSchema, TAccountServiceId>;
+}
+/**
+ * Object shape accepted from callers before action input is parsed.
+ *
+ * Schemas with an object-shaped declared input preserve that input type so
+ * coercions and transforms remain callable. Schemas whose declared input is
+ * broader use their known object output shape instead.
+ *
+ * @template TInputSchema - Object-producing action input schema.
+ */
+export type ActionSchemaInput<TInputSchema extends ObjectProducingSchema<unknown>> = StandardSchemaV1.InferInput<TInputSchema> extends Record<string, unknown> ? StandardSchemaV1.InferInput<TInputSchema> : StandardSchemaV1.InferOutput<TInputSchema>;
+/**
+ * Per-field inputs accepted when invoking an action.
+ *
+ * Each field may be supplied directly or as a signal that is resolved before
+ * schema validation.
+ *
+ * @template TInputSchema - Object-producing action input schema.
+ */
+export type ActionCallInput<TInputSchema extends ObjectProducingSchema<unknown>> = {
+    [TKey in keyof ActionSchemaInput<TInputSchema>]: ActionSchemaInput<TInputSchema>[TKey] | Signal<ActionSchemaInput<TInputSchema>[TKey]>;
+};
+/**
+ * Optional account selection added to account-backed action calls.
+ *
+ * The selection may be a binding name, a typed account reference, or a signal
+ * resolving to either. Omitting it selects the project's default binding.
+ *
+ * @template TAccountServiceId - Required integration service.
+ */
+type ActionAccountCallInput<TAccountServiceId extends string> = {
+    /** Project account binding to use for this invocation. */
+    account?: string | IntegrationAccountReference<TAccountServiceId> | Signal<string> | Signal<IntegrationAccountReference<TAccountServiceId>> | Signal<string | IntegrationAccountReference<TAccountServiceId>>;
+};
+type ActionInvocationInput<TInputSchema extends ObjectProducingSchema<unknown>, TAccountServiceId extends string> = [TAccountServiceId] extends [never] ? ActionCallInput<TInputSchema> : [TInputSchema] extends [typeof DEFAULT_ACTION_INPUT_SCHEMA] ? ActionAccountCallInput<TAccountServiceId> : ActionCallInput<TInputSchema> & ActionAccountCallInput<TAccountServiceId>;
+/**
+ * Callable action produced by a completed action definition.
+ *
+ * Calling it registers an invocation and returns a signal for the eventual
+ * validated output. Account-backed actions also carry their authorization
+ * requirement for planning.
+ *
+ * @template TInputSchema - Schema governing invocation input.
+ * @template TOutputSchema - Schema governing the resulting signal value.
+ * @template TAccountServiceId - Required integration service, or `never` for
+ *   accountless actions.
+ */
+export type DefinedAction<TInputSchema extends ObjectProducingSchema<unknown> = ObjectProducingSchema<unknown>, TOutputSchema extends ProducingSchema<Encodable> = ProducingSchema<Encodable>, TAccountServiceId extends string = never> = {
+    /**
+     * Registers an invocation and exposes its eventual output.
+     *
+     * @param input - Literal and signal-backed fields supplied to the action.
+     */
+    (input: ActionInvocationInput<TInputSchema, TAccountServiceId>): Signal<StandardSchemaV1.InferOutput<TOutputSchema>>;
+    /** Display metadata configured while defining the action. */
+    readonly meta: ActionMetadata;
+} & ([TAccountServiceId] extends [never] ? object : AccountAuthorizationAction<TAccountServiceId>);
+/**
+ * Starts a fluent action definition.
+ *
+ * @param name - Human-readable action name.
+ */
+export declare function defineAction(name: string): ActionBuilder;
+/**
+ * Creates a string signal by interpolating in-memory values and signals.
+ *
+ * @param strings - Static portions of the tagged template.
+ * @param values - Dynamic values interleaved between static portions.
+ */
+export declare function t(strings: TemplateStringsArray, ...values: unknown[]): Signal<string>;
+export {};
+//# sourceMappingURL=actions.d.ts.map

package/dist/automation/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../src/automation/actions.ts"],"names":[],"mappings":"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"}

package/dist/automation/actions.js

@@ -0,0 +1,286 @@
+import { mapValues } from "@zachsents/zippy";
+import { omit, pick } from "remeda";
+import { z } from "zod";
+import { actionAccountRequirementDefinition, DEFAULT_ACCOUNT_BINDING, isIntegrationAccountReference, serializedIntegrationAccountDefinition, } from "./integrations.js";
+import { actionProvenance, createActionSignal, isSignal, signalTransform, subscriptionProvenance, transform, } from "./signal.js";
+import { consumeHookSlot } from "./runtime.js";
+const DEFAULT_ACTION_INPUT_SCHEMA = z.record(z.string(), z.never());
+const DEFAULT_ACTION_OUTPUT_SCHEMA = z.void();
+/**
+ * Starts a fluent action definition.
+ *
+ * @param name - Human-readable action name.
+ */
+export function defineAction(name) {
+    return createActionBuilder({
+        input: DEFAULT_ACTION_INPUT_SCHEMA,
+        meta: { name },
+        output: DEFAULT_ACTION_OUTPUT_SCHEMA,
+    });
+}
+/**
+ * Creates a builder carrying the action metadata and latest configured schemas.
+ *
+ * @param definition - Metadata and schemas configured by prior builder calls.
+ * @param definition.account - Optional integration account requirement.
+ * @param definition.account.requiredScopes - Required provider scopes.
+ * @param definition.account.serviceId - Required integration service.
+ * @param definition.input - Current input schema.
+ * @param definition.meta - Display metadata for the action.
+ * @param definition.output - Current output schema.
+ */
+function createActionBuilder(definition) {
+    return {
+        account(serviceId, requiredScopes = []) {
+            return createActionBuilder({
+                ...definition,
+                account: { requiredScopes, serviceId },
+            });
+        },
+        describe(description) {
+            return createActionBuilder({
+                ...definition,
+                meta: { ...definition.meta, description },
+            });
+        },
+        input(input) {
+            return createActionBuilder({ ...definition, input });
+        },
+        output(output) {
+            return createActionBuilder({ ...definition, output });
+        },
+        handler(handler) {
+            return Object.assign((input) => invokeAction({
+                ...pick(definition, ["account", "meta"]),
+                handler,
+                input: definition.input,
+                output: definition.output,
+            }, input), { meta: definition.meta }, definition.account && {
+                [actionAccountRequirementDefinition]: definition.account,
+            });
+        },
+    };
+}
+/**
+ * Registers an action invocation and returns a signal for its eventual output.
+ *
+ * @param options - Schemas and handler that define the action.
+ * @param input - Literal and signal-backed values supplied by the caller.
+ */
+function invokeAction(options, input) {
+    const slot = consumeHookSlot();
+    const accountInput = options.account && "account" in input ? input.account : undefined;
+    const schemaInput = options.account ? omit(input, ["account"]) : input;
+    const planningContext = globalThis.__AUTOMATION_PLANNING_CONTEXT__;
+    if (planningContext && options.account) {
+        planningContext.accountUses.push({
+            ...getPlannedAccountSelection(accountInput, options.account.serviceId),
+            requiredScopes: options.account.requiredScopes,
+            serviceId: options.account.serviceId,
+        });
+    }
+    const state = globalThis.__AUTOMATION_RUNTIME_STATE__;
+    if (state?.phase === "orchestrate") {
+        // This action has not already completed in this automation context
+        if (!state.context.actionOutputs.some((output) => output.slot === slot)) {
+            const actionDependencyIds = new Set();
+            const eventDependencyIds = new Set();
+            if (Object.values(input).every((value) => !isSignal(value) ||
+                collectSignalDependencies(value, state.context, actionDependencyIds, eventDependencyIds))) {
+                state.actionInvocations.push({
+                    actionDependencyIds: [...actionDependencyIds],
+                    eventDependencyIds: [...eventDependencyIds],
+                    name: options.meta.name,
+                    description: options.meta.description ?? null,
+                    slot,
+                });
+            }
+        }
+    }
+    else if (state?.phase === "execute" && state.invocation.slot === slot) {
+        const materialized = mapValues(schemaInput, (v) => isSignal(v) ? resolveSignal(v, state.invocation.context) : v);
+        const materializedAccount = isSignal(accountInput)
+            ? resolveSignal(accountInput, state.invocation.context)
+            : accountInput;
+        state.executed = true;
+        state.effects.push((async () => {
+            const account = options.account === undefined
+                ? undefined
+                : await resolveActionAccount(materializedAccount, options.account, state.resolveAccountInput);
+            await state.completeInvocation({
+                output: await validateStandardSchema(options.output, 
+                // REVIEW: Account presence follows the builder's conditional handler type.
+                // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Runtime branch and builder type share the same account declaration.
+                await options.handler({
+                    ...(account && { account }),
+                    input: await validateStandardSchema(options.input, materialized, "Action input"),
+                    runtime: state.runtime,
+                }), "Action output"),
+            });
+        })());
+    }
+    return createActionSignal(slot);
+}
+/**
+ * Resolves a materialized account selection through its current project
+ * binding.
+ *
+ * @param value - Literal or signal-produced account selection.
+ * @param requirement - Service declared by the action.
+ * @param requirement.serviceId - Integration service required by the action.
+ * @param resolveAccountInput - Private runtime transport for credential
+ *   loading.
+ * @throws When the value is not a compatible bound account for the action.
+ */
+async function resolveActionAccount(value, requirement, resolveAccountInput) {
+    if (value !== undefined &&
+        typeof value !== "string" &&
+        !isIntegrationAccountReference(value)) {
+        throw new Error("Action account input is not a named integration account binding.");
+    }
+    const accountDefinition = isIntegrationAccountReference(value)
+        ? value[serializedIntegrationAccountDefinition]
+        : undefined;
+    if (accountDefinition &&
+        accountDefinition.serviceId !== requirement.serviceId) {
+        throw new Error(`Action requires a ${requirement.serviceId} account, but received a ${accountDefinition.serviceId} account.`);
+    }
+    return await resolveAccountInput({
+        binding: typeof value === "string"
+            ? value
+            : accountDefinition?.binding === undefined
+                ? DEFAULT_ACCOUNT_BINDING
+                : accountDefinition.binding,
+        serviceId: requirement.serviceId,
+    });
+}
+/**
+ * Classifies an action account input without evaluating signal transforms.
+ *
+ * @param value - Account selection supplied to the action.
+ * @param serviceId - Integration service required by the action.
+ * @throws When the input is not a compatible account selection.
+ */
+function getPlannedAccountSelection(value, serviceId) {
+    if (isSignal(value)) {
+        return { dynamic: true };
+    }
+    if (value === undefined || typeof value === "string") {
+        return {
+            binding: value ?? DEFAULT_ACCOUNT_BINDING,
+            dynamic: false,
+        };
+    }
+    if (!isIntegrationAccountReference(value)) {
+        throw new Error("Action account input is not a named integration account binding.");
+    }
+    const definition = value[serializedIntegrationAccountDefinition];
+    if (definition.serviceId !== serviceId) {
+        throw new Error(`Action requires a ${serviceId} account, but received a ${definition.serviceId} account.`);
+    }
+    return {
+        binding: definition.binding,
+        dynamic: false,
+    };
+}
+/**
+ * Creates a string signal by interpolating in-memory values and signals.
+ *
+ * @param strings - Static portions of the tagged template.
+ * @param values - Dynamic values interleaved between static portions.
+ */
+export function t(strings, ...values) {
+    return transform(values.filter(isSignal), (...resolvedSignals) => {
+        let signalIndex = 0;
+        return (values.reduce((result, value, index) => result +
+            (strings[index] ?? "") +
+            String(isSignal(value) ? resolvedSignals[signalIndex++] : value), "") + (strings[strings.length - 1] ?? ""));
+    });
+}
+/**
+ * Resolves a signal against executor-loaded dependency values.
+ *
+ * @param signal - Signal to resolve.
+ * @param context - Dependency values loaded for the action executor.
+ * @throws When an expected execution dependency is missing.
+ */
+function resolveSignal(signal, context) {
+    const subscription = signal[subscriptionProvenance];
+    if (subscription) {
+        const match = context.events.find((event) => event.slot === subscription.slot);
+        if (!match) {
+            throw new Error(`Missing subscription dependency for slot ${subscription.slot}.`);
+        }
+        return match.payload;
+    }
+    const action = signal[actionProvenance];
+    if (action) {
+        const match = context.actionOutputs.find((output) => output.slot === action.slot);
+        if (!match) {
+            throw new Error(`Missing action dependency for slot ${action.slot}.`);
+        }
+        return match.output;
+    }
+    const transformation = signal[signalTransform];
+    if (!transformation) {
+        throw new Error("Signal has no runtime provenance or transform.");
+    }
+    return transformation.transform(...transformation.inputs.map((input) => resolveSignal(input, context)));
+}
+/**
+ * Adds a signal's boundary dependencies without evaluating its transforms.
+ *
+ * @param signal - Signal whose durable inputs should be collected.
+ * @param context - Available dependency metadata for the current context.
+ * @param actionDependencyIds - Prior action invocation IDs collected so far.
+ * @param eventDependencyIds - Automation event IDs collected so far.
+ * @throws When the signal has no runtime provenance or transform.
+ */
+function collectSignalDependencies(signal, context, actionDependencyIds, eventDependencyIds) {
+    const subscription = signal[subscriptionProvenance];
+    if (subscription) {
+        const match = context.events.find((event) => event.slot === subscription.slot);
+        if (!match)
+            return false;
+        eventDependencyIds.add(match.automationEventId);
+        return true;
+    }
+    const action = signal[actionProvenance];
+    if (action) {
+        const match = context.actionOutputs.find((output) => output.slot === action.slot);
+        if (!match)
+            return false;
+        actionDependencyIds.add(match.actionInvocationId);
+        return true;
+    }
+    const transformation = signal[signalTransform];
+    if (!transformation) {
+        throw new Error("Signal has no runtime provenance or transform.");
+    }
+    return transformation.inputs.every((input) => collectSignalDependencies(input, context, actionDependencyIds, eventDependencyIds));
+}
+/**
+ * Validates a value through a Standard Schema implementation.
+ *
+ * @param schema - Standard Schema validator to invoke.
+ * @param value - Unknown value to validate.
+ * @param label - Label included in validation errors.
+ * @throws When validation reports one or more issues.
+ */
+async function validateStandardSchema(schema, value, label) {
+    const result = await schema["~standard"].validate(value);
+    if (result.issues) {
+        const details = result.issues
+            .map((issue) => {
+            const path = issue.path
+                ?.map((segment) => typeof segment === "object" ? String(segment.key) : String(segment))
+                .join(".");
+            return path ? `${path}: ${issue.message}` : issue.message;
+        })
+            .join("; ");
+        throw new Error(details.length > 0
+            ? `${label} validation failed: ${details}`
+            : `${label} validation failed.`);
+    }
+    return result.value;
+}

package/dist/automation/automation.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Describes an automation — the function that the orchestrator will execute in
+ * various contexts (plan, execute, deploy, authz).
+ */
+export interface AutomationDescriptor {
+    (): Promise<void> | void;
+    description: string;
+}
+/**
+ * Defines a top-level automation for the runtime to invoke.
+ *
+ * @param description - Human-readable summary of the automation.
+ * @param fn - Automation body to run in the active runtime phase.
+ */
+export declare function automation(description: AutomationDescriptor["description"], fn: () => void): AutomationDescriptor;
+//# sourceMappingURL=automation.d.ts.map

package/dist/automation/automation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"automation.d.ts","sourceRoot":"","sources":["../../src/automation/automation.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACxB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,WAAW,EAAE,oBAAoB,CAAC,aAAa,CAAC,EAChD,EAAE,EAAE,MAAM,IAAI,GACb,oBAAoB,CAEtB"}

package/dist/automation/automation.js

@@ -0,0 +1,10 @@
+import { runAutomationFunction } from "./runtime.js";
+/**
+ * Defines a top-level automation for the runtime to invoke.
+ *
+ * @param description - Human-readable summary of the automation.
+ * @param fn - Automation body to run in the active runtime phase.
+ */
+export function automation(description, fn) {
+    return Object.assign(() => runAutomationFunction(fn), { description });
+}