@relayflows/sdk 2.0.24 → 2.0.26

package/src/cloud-run.ts

@@ -9,6 +9,7 @@ import { CompileError, compileSpec, kernelToAuthoring, toKernelSpec } from './co
 import type { FlowSpec } from './spec.js';
 import { snapshotJsonValue, type JsonValue } from './json-value.js';
 import { loadAuthoredFlow, type SurfaceModuleAuthority } from './authored-flow-loader.js';
+import { assertNoUseDependencies, collectExtensionSubmissions, type FlowExtensionSubmission } from './flow-extension-submit.js';
 import {
   CloudFlowError, cloudConnection, cloudFetch, cloudRequest, cloudRunId, isCloudRecord,
   type CloudConnectionOptions,
@@ -61,6 +62,7 @@ export function cloudSubmissionBody(submission: CloudSubmission): Record<string,
     relayflowVersion: 'v2',
     ...(submission.authoredAuthority === undefined ? {} : { authoredAuthority: submission.authoredAuthority }),
     ...(submission.inputPresent ? { inputs: submission.inputs } : {}),
+    ...(submission.extensions === undefined || submission.extensions.length === 0 ? {} : { extensions: submission.extensions }),
   };
 }
 
@@ -90,6 +92,7 @@ export interface CloudSubmission {
   readonly name: string;
   /** Authored `schedule.*` handlers, for `flows schedule` to pick up. */
   readonly schedules: readonly ScheduleTriggerSource[];
+  readonly extensions?: readonly FlowExtensionSubmission[];
 }
 
 export async function prepareCloudSubmission(
@@ -97,7 +100,7 @@ export async function prepareCloudSubmission(
   options: { input?: JsonValue; signal?: AbortSignal } = {},
 ): Promise<CloudSubmission> {
   let spec: FlowSpec | undefined;
-  let authored: { source: string; authority: CloudAuthoredAuthority; name: string; schedules: ScheduleTriggerSource[] } | undefined;
+  let authored: { source: string; authority: CloudAuthoredAuthority; name: string; schedules: ScheduleTriggerSource[]; extensions: readonly FlowExtensionSubmission[] } | undefined;
   const inputPresent = Object.prototype.hasOwnProperty.call(options, 'input');
   let authoredInput: JsonValue | undefined;
   try {
@@ -122,14 +125,13 @@ export async function prepareCloudSubmission(
             `${flow.path} is not a loadable authored flow: ${error instanceof Error ? error.message : String(error)}. `
             + 'Run `flows check` on it from the same directory.');
         }
-        if (loaded.graph.length !== 1) {
-          throw new CloudFlowError('unsupported_source',
-            'Cloud authored submission currently accepts one self-contained .flow.ts source without use dependencies.');
-        }
+        assertNoUseDependencies(loaded);
+        const extensions = await collectExtensionSubmissions(loaded);
         authored = {
           source,
           name: definition.name,
           schedules: definition.handlers.flatMap(h => h.trigger.kind === 'schedule' ? [h.trigger] : []),
+          extensions,
           authority: Object.freeze({
             schemaVersion: 1,
             sourceSha256: createHash('sha256').update(bytes).digest('hex'),
@@ -182,7 +184,15 @@ export async function prepareCloudSubmission(
   return {
     workflow: authored.source, fileType: 'ts', authoredAuthority: authored.authority,
     inputs: authoredInput, inputPresent: true, name: authored.name, schedules: authored.schedules,
-    specHash: createHash('sha256').update(canonicalize({ authority: authored.authority, input: authoredInput })).digest('hex'),
+    ...(authored.extensions.length === 0 ? {} : { extensions: authored.extensions }),
+    specHash: createHash('sha256').update(canonicalize({
+      authority: authored.authority, input: authoredInput,
+      ...(authored.extensions.length === 0 ? {} : {
+        extensions: authored.extensions.map(extension => ({
+          name: extension.name, digest: extension.digest, ref: extension.ref,
+        })),
+      }),
+    })).digest('hex'),
   };
 }
 

package/src/flow-extension-compat.ts

@@ -0,0 +1,35 @@
+import { readFileSync } from 'node:fs';
+import type { FlowExtensionManifest } from './flow-extension-manifest.js';
+import { PluginError } from './plugin-manifest.js';
+import { satisfiesRange } from './semver-range.js';
+
+export interface RuntimeVersions { readonly sdk: string; readonly surface: string }
+
+/** The versions a plugin's `compat` is checked against: this SDK and the surface it pins. */
+export function runtimeVersions(): RuntimeVersions {
+  const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version: string; dependencies: Record<string, string> };
+  return { sdk: pkg.version, surface: pkg.dependencies['@relayflows/surface']! };
+}
+
+/** `compat.surface` / `compat.sdk` against the runtime: a miss is a refusal, never a warning. */
+export function assertCompatible(manifest: FlowExtensionManifest, versions: RuntimeVersions): void {
+  for (const [what, range, actual] of [['surface', manifest.compat.surface, versions.surface], ['sdk', manifest.compat.sdk, versions.sdk]] as const) {
+    if (!satisfiesRange(actual, range)) throw new PluginError('plugin_incompatible', `${manifest.name} requires ${what} ${range}; this runtime has ${actual}.`);
+  }
+}
+
+/**
+ * `compat.base` against the flow being extended. `FlowHeader.version` is
+ * optional: a base without it matches only `"*"`.
+ */
+export function assertBaseCompatible(manifest: FlowExtensionManifest, base: { readonly name: string; readonly version?: string }): void {
+  const entry = manifest.compat.base.find(b => b.name === base.name);
+  if (entry === undefined) {
+    throw new PluginError('plugin_incompatible', `${manifest.name} extends ${manifest.compat.base.map(b => b.name).join(', ')}, not "${base.name}".`);
+  }
+  if (base.version === undefined) {
+    if (entry.version !== '*') throw new PluginError('plugin_incompatible', `${manifest.name} requires ${base.name} ${entry.version}, but the base flow declares no version; only "*" can be satisfied.`);
+    return;
+  }
+  if (!satisfiesRange(base.version, entry.version)) throw new PluginError('plugin_incompatible', `${manifest.name} requires ${base.name} ${entry.version}; the base flow is ${base.version}.`);
+}

package/src/flow-extension-loader.ts

@@ -0,0 +1,304 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { Ctx } from '@relayflows/surface';
+import type { AuthoredFlowDefinition, FlowHandle } from './authored-flow.js';
+import { sha256 } from './bundle.js';
+import { assertBaseCompatible, assertCompatible, runtimeVersions, type RuntimeVersions } from './flow-extension-compat.js';
+import { validateFlowExtensionManifest, type FlowExtensionManifest } from './flow-extension-manifest.js';
+import { findPluginProject } from './plugin-loader.js';
+import { reconcileDeclaredExtensions, type PluginLockEntry } from './plugin-lock.js';
+import { PluginError } from './plugin-manifest.js';
+import { pluginStoreDirectory, verifyStoredPlugin } from './plugin-store.js';
+
+/**
+ * Compose schema-2 flow extensions onto a base authored flow.
+ *
+ * Order of operations is the security argument, so it is fixed:
+ *   1. `flows.json.plugins` and `flows.lock.json` must agree (declaration ⇔
+ *      provenance, same order);
+ *   2. the materialized store is re-hashed against the lock's digest and the
+ *      manifest bytes against the lock's manifest hash — nothing under
+ *      `.flows/plugins` is read as code before this passes;
+ *   3. the manifest is validated, its compat checked against the runtime and
+ *      the base flow, and anything this slice does not compose (hooks, `use`,
+ *      schedule triggers, non-provider webhooks, gates) is refused;
+ *   4. only then is the entry imported, and its handlers are checked against
+ *      the manifest's declared triggers — an entry cannot subscribe to more
+ *      than it declared.
+ * Extensions compose after the base, in lock order; nothing replaces,
+ * reorders, or widens a base handler.
+ */
+type TriggerHandler = AuthoredFlowDefinition['handlers'][number];
+
+export type FlowHook = (f: Ctx, input: unknown) => Promise<boolean>;
+
+export interface LoadedFlowExtension {
+  readonly name: string;
+  readonly version: string;
+  readonly ref: string;
+  readonly digest: string;
+  readonly directory: string;
+  readonly entryPath: string;
+  readonly manifest: FlowExtensionManifest;
+  readonly handle: FlowHandle;
+  /** Bound to the surface copy the entry itself imported; the base's accessor cannot see this handle's WeakMap entry. */
+  readonly getDefinition: ImportedFlow<unknown>['getDefinition'];
+  readonly handlers: readonly TriggerHandler[];
+  readonly hooks: Readonly<Record<string, FlowHook>>;
+}
+
+export interface ImportedFlow<Authority> {
+  readonly handle: FlowHandle;
+  readonly getDefinition: <Input = unknown>(handle: FlowHandle) => AuthoredFlowDefinition<Input>;
+  readonly surfaceAuthority: Authority;
+  readonly hooks: Readonly<Record<string, FlowHook>>;
+}
+
+export interface LoadFlowExtensionsOptions<Authority> {
+  readonly importFlow: (path: string) => Promise<ImportedFlow<Authority>>;
+  readonly sameAuthority: (a: Authority, b: Authority) => boolean;
+  readonly versions?: RuntimeVersions;
+}
+
+const EXTENSION_HEADER_FIELDS = new Set(['budget', 'tools']);
+const WALLCLOCK_MS = { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 } as const;
+
+function wallclockMs(value: string): number | undefined {
+  const match = /^(\d+)(ms|s|m|h|d)$/.exec(value);
+  if (!match) return undefined;
+  const unit = match[2] as keyof typeof WALLCLOCK_MS;
+  return Number(match[1]) * WALLCLOCK_MS[unit];
+}
+
+/** Credentials and servers declared on a flow-extension, probed before the base body starts. */
+export async function probeFlowExtension(manifest: FlowExtensionManifest, env: NodeJS.ProcessEnv = process.env): Promise<void> {
+  for (const credential of manifest.preflight.credentials) {
+    if (!env[credential]?.trim()) throw new PluginError('plugin_credential_missing', `${manifest.name} requires ${credential}.`);
+  }
+  for (const server of manifest.preflight.servers) {
+    try {
+      const response = await fetch(server, { method: 'HEAD', signal: AbortSignal.timeout(5000) });
+      await response.body?.cancel();
+      if (!response.ok) throw new Error('unsuccessful response');
+    } catch { throw new PluginError('plugin_server_unreachable', `${manifest.name} cannot reach ${server}.`); }
+  }
+}
+
+function unsupported(name: string, what: string): never {
+  throw new PluginError('plugin_unsupported', `${name}: ${what} is not composed by this release.`);
+}
+
+/** The `{provider, event, action?}` a provider subscription lowers to, or undefined for anything else. */
+function subscriptionOf(handler: TriggerHandler): { provider: string; event: string; action?: string } | undefined {
+  const trigger = handler.trigger;
+  if (trigger.kind !== 'webhook' || trigger.filter === undefined) return undefined;
+  const { provider, type, payload } = trigger.filter as { provider?: unknown; type?: unknown; payload?: unknown };
+  if (typeof provider !== 'string' || provider !== trigger.name || typeof type !== 'string') return undefined;
+  const action = typeof payload === 'object' && payload !== null && !Array.isArray(payload) ? (payload as { action?: unknown }).action : undefined;
+  if (action !== undefined && typeof action !== 'string') return undefined;
+  return action === undefined ? { provider, event: type } : { provider, event: type, action };
+}
+
+/**
+ * Server-authenticated integration delivery metadata. This is executor
+ * authority, not authored input: a caller must derive it from its verified
+ * delivery record and pass it out of band. User-controlled `input.event`
+ * objects never become this value.
+ */
+const HOSTED_EXTENSION_DISPATCH_AUTHORITY = Symbol('hosted-extension-dispatch-authority');
+
+export type HostedExtensionDispatch = {
+  readonly [HOSTED_EXTENSION_DISPATCH_AUTHORITY]: true;
+  readonly provenance: 'integration-watch';
+  readonly provider: string;
+  readonly eventType: string;
+  readonly deliveryId: string;
+};
+
+type HostedEventIdentity = { readonly provider: string; readonly event: string; readonly action?: string };
+const DISPATCH_PROVIDER = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const DISPATCH_EVENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const DISPATCH_DELIVERY = /^[A-Za-z0-9_.:-]{1,200}$/;
+
+function hostedEventIdentity(dispatch: unknown): HostedEventIdentity {
+  if (typeof dispatch !== 'object' || dispatch === null || Array.isArray(dispatch)) {
+    throw new PluginError('plugin_event_unroutable', 'Hosted extension dispatch authority is malformed.');
+  }
+  const { provenance, provider, eventType, deliveryId } = dispatch as Partial<HostedExtensionDispatch>;
+  if ((dispatch as Partial<HostedExtensionDispatch>)[HOSTED_EXTENSION_DISPATCH_AUTHORITY] !== true
+    || provenance !== 'integration-watch'
+    || typeof provider !== 'string' || !DISPATCH_PROVIDER.test(provider)
+    || typeof deliveryId !== 'string' || !DISPATCH_DELIVERY.test(deliveryId)
+    || typeof eventType !== 'string') {
+    throw new PluginError('plugin_event_unroutable', 'Hosted extension dispatch authority is malformed.');
+  }
+  const parts = eventType.split('.');
+  if ((parts.length !== 1 && parts.length !== 2) || parts.some(part => !DISPATCH_EVENT.test(part))) {
+    throw new PluginError('plugin_event_unroutable', `Hosted extension event ${JSON.stringify(eventType)} is malformed.`);
+  }
+  return parts.length === 1
+    ? { provider, event: parts[0]! }
+    : { provider, event: parts[0]!, action: parts[1]! };
+}
+
+/**
+ * Brand metadata only after the host has authenticated the integration
+ * delivery. The symbol is deliberately not serializable, so copying a direct
+ * run's JSON into executor options cannot mint dispatch authority.
+ */
+export function hostedExtensionDispatchFromVerifiedDelivery(
+  delivery: Omit<HostedExtensionDispatch, typeof HOSTED_EXTENSION_DISPATCH_AUTHORITY | 'provenance'>,
+): HostedExtensionDispatch {
+  const dispatch = Object.freeze({
+    [HOSTED_EXTENSION_DISPATCH_AUTHORITY]: true as const,
+    provenance: 'integration-watch' as const,
+    ...delivery,
+  });
+  hostedEventIdentity(dispatch);
+  return dispatch;
+}
+
+/**
+ * Resolve a server-authenticated delivery to one extension handler. Authored
+ * input is deliberately absent from this API: direct runs may contain any
+ * JSON shape and cannot opt themselves into extension execution. Overlapping
+ * subscriptions fail closed, including a generic event handler overlapping
+ * an action-specific handler.
+ */
+export function extensionHandlerForHostedDispatch(
+  dispatch: unknown,
+  extensions: readonly Pick<LoadedFlowExtension, 'name' | 'handlers'>[],
+): { readonly extension: Pick<LoadedFlowExtension, 'name' | 'handlers'>; readonly handler: TriggerHandler } | undefined {
+  if (dispatch === undefined) return undefined;
+  const identity = hostedEventIdentity(dispatch);
+  const matches = extensions.flatMap(extension => extension.handlers.flatMap(handler => {
+    const subscription = subscriptionOf(handler);
+    if (subscription === undefined || subscription.provider !== identity.provider || subscription.event !== identity.event) return [];
+    if (subscription.action !== undefined && subscription.action !== identity.action) return [];
+    return [{ extension, handler }];
+  }));
+  if (matches.length > 1) {
+    throw new PluginError(
+      'plugin_event_ambiguous',
+      `Hosted event ${identity.provider}.${identity.event}${identity.action === undefined ? '' : `.${identity.action}`} matches multiple extension handlers (${matches.map(match => match.extension.name).join(', ')}).`,
+    );
+  }
+  return matches[0];
+}
+
+function assertDeclaredSubscription(name: string, manifest: FlowExtensionManifest, handler: TriggerHandler, index: number): void {
+  const subscription = subscriptionOf(handler);
+  if (handler.trigger.kind === 'schedule') unsupported(name, `handler ${index} (a schedule trigger)`);
+  if (subscription === undefined) {
+    throw new PluginError('plugin_manifest_invalid', `${name}: handler ${index} is not a provider subscription; extension handlers must be provider triggers declared in flows-plugin.json.`);
+  }
+  const declared = manifest.triggers.find(t => t.provider === subscription.provider && t.event === subscription.event);
+  const covered = declared !== undefined && (subscription.action === undefined ? declared.actions.length === 0 : declared.actions.includes(subscription.action));
+  if (!covered) {
+    const spelled = `${subscription.provider} ${subscription.event}${subscription.action === undefined ? '' : `.${subscription.action}`}`;
+    throw new PluginError('plugin_manifest_invalid', `${name}: handler ${index} subscribes to ${spelled}, which flows-plugin.json does not declare in triggers.`);
+  }
+}
+
+async function loadOne<Authority>(
+  root: string, lock: PluginLockEntry, ref: string,
+  base: { readonly definition: AuthoredFlowDefinition; readonly surfaceAuthority: Authority },
+  options: LoadFlowExtensionsOptions<Authority>,
+): Promise<LoadedFlowExtension> {
+  const directory = pluginStoreDirectory(root, lock.name, lock.digest);
+  await verifyStoredPlugin(directory, lock.digest);
+  const manifestBytes = readFileSync(join(directory, 'flows-plugin.json'));
+  if (sha256(manifestBytes) !== lock.manifestSha256) throw new PluginError('plugin_source_drift', `${ref}: flows-plugin.json differs from the lockfile's manifest hash.`);
+  let input: unknown;
+  try { input = JSON.parse(manifestBytes.toString('utf8')); }
+  catch { throw new PluginError('plugin_manifest_invalid', `${ref}: flows-plugin.json is not valid JSON.`); }
+  const manifest = validateFlowExtensionManifest(input);
+  if (manifest.name !== lock.name || manifest.version !== lock.version) throw new PluginError('plugin_source_drift', `${ref}: manifest names ${manifest.name}@${manifest.version}, lockfile has ${lock.name}@${lock.version}.`);
+  assertCompatible(manifest, options.versions ?? runtimeVersions());
+  assertBaseCompatible(manifest, { name: base.definition.name, version: base.definition.header.version });
+  const baseBudget = base.definition.header.budget;
+  const ceiling = manifest.permissions.budget;
+  if (ceiling?.dollars !== undefined && typeof baseBudget === 'object' && baseBudget.dollars !== undefined && ceiling.dollars > baseBudget.dollars) {
+    throw new PluginError('plugin_incompatible', `${manifest.name} declares a $${ceiling.dollars} budget ceiling above the base flow's $${baseBudget.dollars}.`);
+  }
+  if (ceiling?.wallclock !== undefined && typeof baseBudget === 'object' && baseBudget.wallclock !== undefined) {
+    const pluginMs = wallclockMs(ceiling.wallclock);
+    const baseMs = wallclockMs(baseBudget.wallclock);
+    if (pluginMs !== undefined && baseMs !== undefined && pluginMs > baseMs) {
+      throw new PluginError('plugin_incompatible', `${manifest.name} declares a ${ceiling.wallclock} wallclock ceiling above the base flow's ${baseBudget.wallclock}.`);
+    }
+  }
+  const entryPath = join(directory, manifest.entry);
+  let imported: ImportedFlow<Authority>;
+  try { imported = await options.importFlow(entryPath); }
+  catch (error) { throw new PluginError('plugin_manifest_invalid', `${ref}: entry ${manifest.entry} did not load: ${error instanceof Error ? error.message : String(error)}`); }
+  if (!options.sameAuthority(imported.surfaceAuthority, base.surfaceAuthority)) {
+    throw new PluginError('plugin_incompatible', `${manifest.name}: entry resolves a different @relayflows/surface than the base flow.`);
+  }
+  const definition = imported.getDefinition(imported.handle);
+  const foreign = Object.keys(definition.header).filter(key => !EXTENSION_HEADER_FIELDS.has(key));
+  if (foreign.length > 0) unsupported(manifest.name, `entry header ${foreign.join(', ')}`);
+  if (manifest.extends.handlers && definition.handlers.length === 0) {
+    throw new PluginError('plugin_manifest_invalid', `${manifest.name}: extends.handlers is true but ${manifest.entry} declares no .on() handlers.`);
+  }
+  if (!manifest.extends.handlers && definition.handlers.length > 0) {
+    throw new PluginError('plugin_manifest_invalid', `${manifest.name}: ${manifest.entry} declares handlers but extends.handlers is false.`);
+  }
+  definition.handlers.forEach((handler, index) => assertDeclaredSubscription(manifest.name, manifest, handler, index));
+  const hooks = imported.hooks;
+  const exported = Object.keys(hooks).sort();
+  const declared = [...manifest.extends.hooks].sort();
+  if (exported.join('\0') !== declared.join('\0')) {
+    throw new PluginError('plugin_manifest_invalid', `${manifest.name}: extends.hooks [${manifest.extends.hooks.join(', ')}] does not match exported hooks [${exported.join(', ')}].`);
+  }
+  const baseHooks = base.definition.header.hooks ?? [];
+  for (const hook of manifest.extends.hooks) {
+    if (!baseHooks.includes(hook)) {
+      throw new PluginError('plugin_incompatible', `${manifest.name}: hook ${hook} is not declared by the base flow.`);
+    }
+  }
+  return Object.freeze({
+    name: manifest.name, version: manifest.version, ref, digest: lock.digest, directory, entryPath, manifest,
+    handle: imported.handle, getDefinition: imported.getDefinition, handlers: Object.freeze([...definition.handlers]),
+    hooks,
+  });
+}
+
+export function parseHooksExport(module: Record<string, unknown>, name: string): Readonly<Record<string, FlowHook>> {
+  const exported = module['hooks'];
+  if (exported === undefined) return Object.freeze({});
+  if (typeof exported !== 'object' || exported === null || Array.isArray(exported)) {
+    throw new PluginError('plugin_manifest_invalid', `${name}: hooks export must be a record of functions.`);
+  }
+  const hooks: Record<string, FlowHook> = {};
+  for (const [key, value] of Object.entries(exported)) {
+    if (typeof value !== 'function') {
+      throw new PluginError('plugin_manifest_invalid', `${name}: hooks.${key} is not a function.`);
+    }
+    hooks[key] = value as FlowHook;
+  }
+  return Object.freeze(hooks);
+}
+
+/** Extensions declared by the project that owns `flowPath`, verified and loaded in lock order; empty when none are declared. */
+export async function loadFlowExtensions<Authority>(
+  flowPath: string,
+  base: { readonly definition: AuthoredFlowDefinition; readonly surfaceAuthority: Authority },
+  options: LoadFlowExtensionsOptions<Authority>,
+): Promise<readonly LoadedFlowExtension[]> {
+  const root = findPluginProject(dirname(flowPath));
+  if (root === undefined) return Object.freeze([]);
+  const declared = reconcileDeclaredExtensions(root);
+  const loaded: LoadedFlowExtension[] = [];
+  for (const { ref, entry } of declared) loaded.push(await loadOne(root, entry, ref, base, options));
+  return Object.freeze(loaded);
+}
+
+/** The base definition with extension handlers appended in lock order; the base's own fields are untouched. */
+export function composeDefinition<Input>(base: AuthoredFlowDefinition<Input>, extensions: readonly LoadedFlowExtension[]): AuthoredFlowDefinition<Input> {
+  if (extensions.length === 0) return base;
+  return Object.freeze({
+    ...base,
+    handlers: Object.freeze([...base.handlers, ...extensions.flatMap(extension => extension.handlers)]),
+  });
+}

package/src/flow-extension-manifest.ts

@@ -0,0 +1,190 @@
+import { Ajv } from 'ajv';
+import { providerEventTypes } from '@relayflows/surface';
+import { FLOW_HARNESSES } from './flow-requirements.js';
+import { snapshotJsonValue } from './json-value.js';
+import { PluginError, pluginKindOf } from './plugin-manifest.js';
+import { safePath } from './bundle.js';
+import { SHA, parsePluginSource, type PluginSourceInput } from './plugin-source.js';
+import { isVersionRange, parseVersion } from './semver-range.js';
+
+/**
+ * Schema 2, `kind: "flow-extension"`: a plugin whose `entry` default-exports
+ * `flow()` and contributes handlers, hooks, and gates to a base flow. It is the
+ * same `flows-plugin.json` file and the same preflight covenant as a helper
+ * plugin (RFC-0001 decision 13); only the kind decides which validator reads it.
+ * Helper manifests (`kind` absent) never reach this module.
+ *
+ * This slice validates and records the declaration. Runtime composition is
+ * refused with `plugin_unsupported` (plugin-loader.ts) until the handlers slice.
+ */
+export interface FlowExtensionTrigger { readonly provider: string; readonly event: string; readonly actions: readonly string[] }
+export interface FlowExtensionCompat {
+  readonly surface: string;
+  readonly sdk: string;
+  readonly base: readonly { readonly name: string; readonly version: string }[];
+}
+export interface FlowExtensionPermissions {
+  readonly integrations: readonly string[];
+  readonly harnesses: readonly string[];
+  readonly mcp: readonly string[];
+  /** Declared effect classes, shown for review; not enforced by this runtime (gate 8 / #442). */
+  readonly writes: readonly string[];
+  readonly budget?: { readonly dollars?: number; readonly wallclock?: string };
+}
+export interface FlowExtensionManifest {
+  readonly schema: 2;
+  readonly kind: 'flow-extension';
+  readonly name: string;
+  readonly version: string;
+  readonly description?: string;
+  /** Authoring copies may omit it; `flows add` records the resolved origin in the lockfile regardless. */
+  readonly source?: PluginSourceInput & { readonly sha?: string };
+  readonly compat: FlowExtensionCompat;
+  readonly entry: string;
+  readonly extends: { readonly handlers: boolean; readonly hooks: readonly string[] };
+  readonly triggers: readonly FlowExtensionTrigger[];
+  readonly permissions: FlowExtensionPermissions;
+  readonly preflight: { readonly credentials: readonly string[]; readonly servers: readonly string[] };
+  readonly config?: Record<string, unknown>;
+}
+
+const TOP_LEVEL = new Set(['schema', 'kind', 'name', 'version', 'description', 'source', 'compat', 'entry', 'extends', 'triggers', 'gates', 'verbs', 'permissions', 'preflight', 'config']);
+const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const PROVIDER = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const WRITE_CLASS = /^[a-z0-9-]+(?::[a-z0-9_-]+)+$/;
+const WALLCLOCK = /^\d+(?:ms|s|m|h|d)$/;
+const MAX_DESCRIPTION = 500;
+const MAX_LIST = 64;
+
+const object = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const invalid = (message: string): never => { throw new PluginError('plugin_manifest_invalid', message); };
+
+function stringList(value: unknown, what: string, pattern: RegExp): readonly string[] {
+  if (!Array.isArray(value) || value.length > MAX_LIST) return invalid(`${what} must be a list of at most ${MAX_LIST} strings.`);
+  const out: string[] = [];
+  for (const entry of value) {
+    if (typeof entry !== 'string' || !pattern.test(entry)) return invalid(`${what} has an invalid entry ${JSON.stringify(entry)}.`);
+    if (out.includes(entry)) return invalid(`${what} lists ${entry} twice.`);
+    out.push(entry);
+  }
+  return Object.freeze(out);
+}
+
+function compat(value: unknown): FlowExtensionCompat {
+  if (!object(value) || Object.keys(value).some(k => !['surface', 'sdk', 'base'].includes(k))) return invalid('compat expects surface, sdk, and base.');
+  for (const key of ['surface', 'sdk'] as const) {
+    if (typeof value[key] !== 'string' || !isVersionRange(value[key])) return invalid(`compat.${key} must be a version range (*, x.y.z, ^x.y.z, ~x.y.z, >=x.y.z [<a.b.c]).`);
+  }
+  if (!Array.isArray(value.base) || value.base.length === 0 || value.base.length > MAX_LIST) return invalid('compat.base must name at least one base flow.');
+  const base = value.base.map(entry => {
+    if (!object(entry) || Object.keys(entry).some(k => !['name', 'version'].includes(k))
+      || typeof entry.name !== 'string' || entry.name.trim().length === 0 || entry.name.length > 100
+      || typeof entry.version !== 'string' || !isVersionRange(entry.version)) return invalid('compat.base entries are { name, version range }.');
+    return Object.freeze({ name: entry.name, version: entry.version });
+  });
+  if (new Set(base.map(b => b.name)).size !== base.length) return invalid('compat.base names a base flow twice.');
+  return Object.freeze({ surface: value.surface as string, sdk: value.sdk as string, base: Object.freeze(base) });
+}
+
+function triggers(value: unknown): readonly FlowExtensionTrigger[] {
+  if (!Array.isArray(value) || value.length > MAX_LIST) return invalid('triggers must be a list.');
+  const registry = providerEventTypes as Readonly<Record<string, readonly string[]>>;
+  const seen = new Set<string>();
+  return Object.freeze(value.map(entry => {
+    if (!object(entry) || Object.keys(entry).some(k => !['provider', 'event', 'actions'].includes(k))
+      || typeof entry.provider !== 'string' || !PROVIDER.test(entry.provider)
+      || typeof entry.event !== 'string' || !IDENTIFIER.test(entry.event)) return invalid('triggers entries are { provider, event, actions }.');
+    const actions = stringList(entry.actions, `triggers ${entry.provider}.${entry.event} actions`, IDENTIFIER);
+    const known = registry[entry.provider];
+    // Fail where ingress would: an event the surface registry cannot lower is
+    // refused now, not after deployment on the first real delivery.
+    if (known === undefined) throw new PluginError('plugin_event_unroutable', `Trigger provider ${entry.provider} is not in the surface event registry.`);
+    const unroutable = (actions.length === 0 ? [entry.event] : actions.map(a => `${entry.event}.${a}`)).filter(type => !known.includes(type));
+    if (unroutable.length > 0) throw new PluginError('plugin_event_unroutable', `Trigger ${entry.provider} ${unroutable.join(', ')} is not in the surface event registry.`);
+    const key = `${entry.provider}:${entry.event}`;
+    if (seen.has(key)) return invalid(`Trigger ${key} is declared twice.`);
+    seen.add(key);
+    return Object.freeze({ provider: entry.provider, event: entry.event, actions });
+  }));
+}
+
+function permissions(value: unknown): FlowExtensionPermissions {
+  if (!object(value) || Object.keys(value).some(k => !['integrations', 'harnesses', 'mcp', 'writes', 'budget'].includes(k))) {
+    return invalid('permissions expects integrations, harnesses, mcp, writes, and optional budget.');
+  }
+  const harnesses = stringList(value.harnesses, 'permissions.harnesses', /^[a-z]+$/);
+  for (const harness of harnesses) if (!(FLOW_HARNESSES as readonly string[]).includes(harness)) return invalid(`permissions.harnesses: unknown harness ${harness}.`);
+  let budget: FlowExtensionPermissions['budget'];
+  if (value.budget !== undefined) {
+    if (!object(value.budget) || Object.keys(value.budget).some(k => !['dollars', 'wallclock'].includes(k))) return invalid('permissions.budget expects dollars and/or wallclock.');
+    if (value.budget.dollars !== undefined && (typeof value.budget.dollars !== 'number' || !(value.budget.dollars > 0) || !Number.isFinite(value.budget.dollars))) return invalid('permissions.budget.dollars must be a positive number.');
+    if (value.budget.wallclock !== undefined && (typeof value.budget.wallclock !== 'string' || !WALLCLOCK.test(value.budget.wallclock))) return invalid('permissions.budget.wallclock must be a duration such as 45m.');
+    budget = Object.freeze({ ...(value.budget.dollars === undefined ? {} : { dollars: value.budget.dollars }), ...(value.budget.wallclock === undefined ? {} : { wallclock: value.budget.wallclock }) });
+  }
+  return Object.freeze({
+    integrations: stringList(value.integrations, 'permissions.integrations', PROVIDER),
+    harnesses,
+    mcp: stringList(value.mcp, 'permissions.mcp', /^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/),
+    writes: stringList(value.writes, 'permissions.writes', WRITE_CLASS),
+    ...(budget === undefined ? {} : { budget }),
+  });
+}
+
+function source(value: unknown): FlowExtensionManifest['source'] {
+  if (!object(value) || Object.keys(value).some(k => !['host', 'owner', 'repo', 'sha', 'path'].includes(k))
+    || value.host !== 'github' || typeof value.owner !== 'string' || typeof value.repo !== 'string'
+    || (value.path !== undefined && typeof value.path !== 'string')
+    || (value.sha !== undefined && (typeof value.sha !== 'string' || !SHA.test(value.sha)))) {
+    return invalid('source expects { host: "github", owner, repo, path, sha? }.');
+  }
+  const path = (value.path as string | undefined) ?? '';
+  const parsed = parsePluginSource(`github:${value.owner}/${value.repo}@${(value.sha as string | undefined) ?? 'HEAD'}${path === '' ? '' : `#${path}`}`);
+  return Object.freeze({ ...parsed, ...(value.sha === undefined ? {} : { sha: value.sha as string }) });
+}
+
+export function validateFlowExtensionManifest(input: unknown): FlowExtensionManifest {
+  let v: unknown;
+  try { v = snapshotJsonValue(input, 'plugin manifest'); }
+  catch { return invalid('Plugin manifest must be JSON data.'); }
+  if (!object(v)) return invalid('Expected a plugin manifest object.');
+  if (pluginKindOf(v) !== 'flow-extension') throw new PluginError('plugin_kind_invalid', 'Expected kind "flow-extension".');
+  if (v.schema !== 2) return invalid('A flow-extension manifest is schema 2.');
+  const unknown = Object.keys(v).filter(k => !TOP_LEVEL.has(k));
+  if (unknown.length > 0) return invalid(`Unknown manifest fields: ${unknown.join(', ')}.`);
+  if (!Object.hasOwn(v, 'preflight')) throw new PluginError('plugin_preflight_missing', 'Plugin must declare preflight.');
+  if (typeof v.name !== 'string' || !NAME.test(v.name) || v.name.startsWith('helper-')) return invalid('name must be lowercase kebab-case and must not start with helper-.');
+  if (typeof v.version !== 'string' || parseVersion(v.version) === undefined) return invalid('version must be semver x.y.z.');
+  if (v.description !== undefined && (typeof v.description !== 'string' || v.description.length > MAX_DESCRIPTION)) return invalid(`description must be a string of at most ${MAX_DESCRIPTION} characters.`);
+  if (typeof v.entry !== 'string' || !v.entry.endsWith('.flow.ts') || !safePath(v.entry)) return invalid('entry must be a plugin-relative .flow.ts path.');
+  if (!object(v.extends) || Object.keys(v.extends).some(k => !['handlers', 'hooks', 'verbs', 'gates'].includes(k)) || typeof v.extends.handlers !== 'boolean') return invalid('extends expects { handlers: boolean, hooks: [] }.');
+  const hooks = stringList(v.extends.hooks ?? [], 'extends.hooks', NAME);
+  for (const [field, at] of [['verbs', v.extends.verbs], ['gates', v.extends.gates], ['verbs', v.verbs], ['gates', v.gates]] as const) {
+    if (at !== undefined && (!Array.isArray(at) || at.length > 0)) return invalid(`A flow extension declares no ${field}; ship a helper plugin beside it.`);
+  }
+  if (!v.extends.handlers && hooks.length === 0) return invalid('A flow extension must contribute handlers or at least one hook.');
+  if (!object(v.preflight) || Object.keys(v.preflight).some(k => !['credentials', 'servers'].includes(k))) return invalid('Preflight requires credentials and servers arrays.');
+  const credentials = stringList(v.preflight.credentials, 'preflight.credentials', IDENTIFIER);
+  const servers = stringList(v.preflight.servers, 'preflight.servers', /^https?:\/\/\S+$/);
+  for (const server of servers) {
+    try { if (!['http:', 'https:'].includes(new URL(server).protocol)) return invalid('Servers must be HTTP(S) URLs.'); }
+    catch { return invalid('Servers must be HTTP(S) URLs.'); }
+  }
+  let config: Record<string, unknown> | undefined;
+  if (v.config !== undefined) {
+    if (!object(v.config)) return invalid('config must be a JSON Schema object.');
+    try { new Ajv({ strict: false }).compile(v.config); } catch { return invalid('config is not a valid JSON Schema.'); }
+    config = v.config;
+  }
+  return Object.freeze({
+    schema: 2, kind: 'flow-extension', name: v.name, version: v.version,
+    ...(v.description === undefined ? {} : { description: v.description }),
+    ...(v.source === undefined ? {} : { source: source(v.source) }),
+    compat: compat(v.compat), entry: v.entry,
+    extends: Object.freeze({ handlers: v.extends.handlers, hooks }),
+    triggers: triggers(v.triggers ?? []),
+    permissions: permissions(v.permissions),
+    preflight: Object.freeze({ credentials, servers }),
+    ...(config === undefined ? {} : { config }),
+  });
+}