@relayflows/sdk 2.0.23 → 2.0.25

package/dist/semver-range.d.ts

@@ -0,0 +1,10 @@
+interface Parsed {
+    readonly triple: readonly [number, number, number];
+    readonly pre?: string;
+}
+export declare function parseVersion(value: string): Parsed | undefined;
+export declare function isVersionRange(value: string): boolean;
+/** Whether `version` satisfies `range`; false for malformed input rather than a throw. */
+export declare function satisfiesRange(version: string, range: string): boolean;
+export {};
+//# sourceMappingURL=semver-range.d.ts.map

package/dist/semver-range.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semver-range.d.ts","sourceRoot":"","sources":["../src/semver-range.ts"],"names":[],"mappings":"AAYA,UAAU,MAAM;IAAG,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE;AAE9F,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAM9D;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAErD;AAgCD,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAgBtE"}

package/dist/semver-range.js

@@ -0,0 +1,88 @@
+/**
+ * The small semver subset plugin `compat` ranges may use. Deliberately not a
+ * dependency on `semver`: a plugin's compatibility claim has to be checkable by
+ * every reader — Cloud, the CLI, a catalog — from one short, obvious rule.
+ *
+ * Accepted: `*`, `x.y.z`, `^x.y.z`, `~x.y.z`, `>=x.y.z`, `>=x.y.z <a.b.c`.
+ * Prerelease tags are ordered lexically after the numeric triple and only
+ * compare against a range whose bounds name the same triple.
+ */
+const VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+const RANGE = /^(\*|(?:[\^~]|>=)?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?: <\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)?)$/;
+export function parseVersion(value) {
+    const m = VERSION.exec(value);
+    if (!m)
+        return undefined;
+    const triple = [Number(m[1]), Number(m[2]), Number(m[3])];
+    if (triple.some(n => !Number.isSafeInteger(n)))
+        return undefined;
+    return m[4] === undefined ? { triple } : { triple, pre: m[4] };
+}
+export function isVersionRange(value) {
+    return RANGE.test(value);
+}
+function compare(a, b) {
+    for (let i = 0; i < 3; i++)
+        if (a.triple[i] !== b.triple[i])
+            return a.triple[i] - b.triple[i];
+    if (a.pre === b.pre)
+        return 0;
+    if (a.pre === undefined)
+        return 1;
+    if (b.pre === undefined)
+        return -1;
+    return comparePrerelease(a.pre, b.pre);
+}
+function comparePrerelease(a, b) {
+    const as = a.split('.');
+    const bs = b.split('.');
+    const n = Math.max(as.length, bs.length);
+    for (let i = 0; i < n; i++) {
+        const left = as[i];
+        const right = bs[i];
+        if (left === undefined)
+            return -1;
+        if (right === undefined)
+            return 1;
+        const leftNum = /^\d+$/.test(left) ? Number(left) : undefined;
+        const rightNum = /^\d+$/.test(right) ? Number(right) : undefined;
+        if (leftNum !== undefined && rightNum !== undefined) {
+            if (leftNum !== rightNum)
+                return leftNum - rightNum;
+            continue;
+        }
+        if (leftNum !== undefined)
+            return -1;
+        if (rightNum !== undefined)
+            return 1;
+        if (left !== right)
+            return left < right ? -1 : 1;
+    }
+    return 0;
+}
+/** Whether `version` satisfies `range`; false for malformed input rather than a throw. */
+export function satisfiesRange(version, range) {
+    const v = parseVersion(version);
+    if (v === undefined || !isVersionRange(range))
+        return false;
+    if (range === '*')
+        return true;
+    const [lowerText, upperText] = range.split(' ');
+    const operator = /^[\^~]|^>=/.exec(lowerText)?.[0] ?? '';
+    const lower = parseVersion(lowerText.slice(operator.length));
+    if (compare(v, lower) < 0)
+        return false;
+    if (operator === '')
+        return compare(v, lower) === 0;
+    let upper;
+    if (upperText !== undefined)
+        upper = parseVersion(upperText.slice(1));
+    else if (operator === '^') {
+        const [major, minor] = lower.triple;
+        upper = major > 0 ? { triple: [major + 1, 0, 0] } : minor > 0 ? { triple: [0, minor + 1, 0] } : { triple: [0, 0, lower.triple[2] + 1] };
+    }
+    else if (operator === '~')
+        upper = { triple: [lower.triple[0], lower.triple[1] + 1, 0] };
+    return upper === undefined || compare(v, upper) < 0;
+}
+//# sourceMappingURL=semver-range.js.map

package/dist/semver-range.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayflows/sdk",
-  "version": "2.0.23",
+  "version": "2.0.25",
   "description": "TypeScript-first authoring SDK for Relayflows. Compiles specs; speaks the journal protocol.",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,7 +49,7 @@
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@relayfile/adapter-core": "0.5.26",
     "@relayfile/relay-helpers": "0.4.11",
-    "@relayflows/surface": "2.0.23",
+    "@relayflows/surface": "2.0.25",
     "@types/js-yaml": "^4.0.9",
     "ai-hist": "0.4.1",
     "ajv": "^8.17.1",

package/src/authored-flow-executor.ts

@@ -44,6 +44,8 @@ import {
 } from './authored-flow-operation.js';
 import { AuthoredFlowLifecycle } from './authored-flow-lifecycle.js';
 import { JournalClient } from './journal-client.js';
+import { createHookEvaluator } from './authored-hooks.js';
+import { probeFlowExtension, type LoadedFlowExtension } from './flow-extension-loader.js';
 import type {
   CompletionReason as ProtocolCompletionReason,
   RunCompletionReason as ProtocolRunCompletionReason,
@@ -148,6 +150,8 @@ export interface ExecuteAuthoredFlowOptions {
   readonly localAgentStream?: string;
   /** Durable kernel root that owns this body's child admission identities. */
   readonly rootRunId?: string;
+  /** Installed flow-extension plugins, in lock order, so `f.hook` can AND-compose them. */
+  readonly extensions?: readonly LoadedFlowExtension[];
 }
 
 export async function executeAuthoredFlow<Input = undefined>(
@@ -171,7 +175,7 @@ export async function executeAuthoredFlow<Input = undefined>(
     ...(options.onWait !== undefined ? { onWait: options.onWait } : {}),
   };
   const definition = getDefinition<Input>(handle);
-  const headerFields = Object.keys(definition.header).filter(key => key !== 'tools' && key !== 'budget' && key !== 'memory');
+  const headerFields = Object.keys(definition.header).filter(key => key !== 'tools' && key !== 'budget' && key !== 'memory' && key !== 'version' && key !== 'hooks');
   if (definition.header.tools && Object.keys(definition.header.tools).some(key => !['mcp', ...helperProviders.map(p => p.namespace)].includes(key))) headerFields.push('tools');
   if (definition.header.tools?.relayfile !== undefined) headerFields.push('tools.relayfile');
   const helperPreflight = checkSlackHelpers(definition);
@@ -188,6 +192,9 @@ export async function executeAuthoredFlow<Input = undefined>(
 
   const checkedMcp = await checkMcpHeader(definition, flowPath);
   if (!checkedMcp.report.ok) throw new McpPreflightError(checkedMcp.report);
+  for (const extension of options.extensions ?? []) {
+    if (extension.manifest !== undefined) await probeFlowExtension(extension.manifest);
+  }
 
   const budget = new AuthoredBudget(definition.header.budget);
   if (definition.header.memory?.agent === true) {
@@ -349,6 +356,17 @@ export async function executeAuthoredFlow<Input = undefined>(
     ));
   }
 
+  const evaluateHook = createHookEvaluator({
+    journal,
+    ...(options.rootRunId === undefined ? {} : { rootRunId: options.rootRunId }),
+    flowName: definition.name,
+    declared: definition.header?.hooks ?? [],
+    extensions: options.extensions ?? [],
+    peekStep: () => nextStep,
+    restoreStep: (step) => { nextStep = step; },
+    ...(options.signal === undefined ? {} : { signal: options.signal }),
+  });
+
   const context: Ctx = {
     ...createHelpers(<T>(call: HelperCall): Step<T> => {
       const verb = `${call.provider}.${call.verb}`;
@@ -477,6 +495,23 @@ export async function executeAuthoredFlow<Input = undefined>(
       assertOperationAllowed('dispatch', definition.name, requestedCompletion);
       throw unsupportedVerb('dispatch');
     },
+    hook(name, input) {
+      assertOperationAllowed('hook', definition.name, requestedCompletion);
+      const id = `hook-${nextStep++}`;
+      const snapshot = snapshotJsonValue(input, 'f.hook input');
+      return trackStep(authoredSteps, new AuthoredFlowOperation<boolean>(
+        id, 'hook',
+        () => assertOperationAllowed('hook', definition.name, requestedCompletion),
+        async () => {
+          const verdict = await evaluateHook(id, name, snapshot, context);
+          const record = { hook: name, step: id, verdict: verdict ? 'pass' : 'fail' };
+          const literal = `'${JSON.stringify(record).replaceAll("'", "'\\''")}'`;
+          await observeStep(id, 'deterministic', () => lowerDeterministic(id, `printf '%s' ${literal}`, false), options.onProgress);
+          return verdict;
+        },
+        lifecycle,
+      ));
+    },
     done(reason) {
       if (!isSurfaceFlowCompletionReason(reason)) {
         throw new AuthoredFlowExecutionError(

package/src/authored-flow-loader.ts

@@ -9,6 +9,9 @@ import {
   type AuthoredFlowDefinition,
   type FlowHandle,
 } from './authored-flow.js';
+import { canonicalize } from './canonical.js';
+import { composeDefinition, loadFlowExtensions, parseHooksExport, type ImportedFlow, type LoadedFlowExtension } from './flow-extension-loader.js';
+import type { RuntimeVersions } from './flow-extension-compat.js';
 
 export class AuthoredFlowLoadError extends Error {
   constructor(message: string, readonly kind: 'invalid_spec' | 'use_not_found' | 'use_invalid' | 'use_cycle' = 'invalid_spec') {
@@ -40,8 +43,20 @@ export interface LoadedAuthoredFlow {
   readonly getDefinition: GetFlowDefinition;
   /** Exact Surface package/runtime that owns the handle's WeakMap identity. */
   readonly surfaceAuthority: SurfaceModuleAuthority;
-  /** Dependency-first load order, each canonical absolute path appearing once. */
+  /**
+   * Dependency-first load order, each canonical absolute path appearing once.
+   * Flow-extension entries follow the root, so a graph of one node still
+   * means "one self-contained source" to the hosted paths that require it.
+   */
   readonly graph: readonly LoadedAuthoredFlowNode[];
+  /** Schema-2 flow extensions composed onto the root, in lock order; empty when the project declares none. */
+  readonly extensions: readonly LoadedFlowExtension[];
+}
+
+export interface LoadAuthoredFlowOptions {
+  /** `compose` (default) verifies and appends the project's flow extensions; `none` loads the root alone. */
+  readonly extensions?: 'compose' | 'none';
+  readonly versions?: RuntimeVersions;
 }
 
 export interface LoadedAuthoredFlowNode {
@@ -53,7 +68,7 @@ export interface LoadedAuthoredFlowNode {
 }
 
 /** Import and validate a direct-run module without executing its authored body. */
-export async function loadAuthoredFlow(path: string): Promise<LoadedAuthoredFlow> {
+export async function loadAuthoredFlow(path: string, options: LoadAuthoredFlowOptions = {}): Promise<LoadedAuthoredFlow> {
   const loaded = new Map<string, LoadedAuthoredFlowNode>();
   const visiting = new Set<string>();
   async function visit(sourcePath: string, isRoot = false): Promise<LoadedAuthoredFlowNode> {
@@ -98,11 +113,39 @@ export async function loadAuthoredFlow(path: string): Promise<LoadedAuthoredFlow
     }
   }
   const root = await visit(resolve(path), true);
-  return Object.freeze({ sourcePath: root.path, handle: root.handle, getDefinition: root.getDefinition,
-    surfaceAuthority: root.surfaceAuthority, graph: Object.freeze([...loaded.values()]) });
+  const graph = [...loaded.values()];
+  if (options.extensions === 'none') {
+    return Object.freeze({ sourcePath: root.path, handle: root.handle, getDefinition: root.getDefinition,
+      surfaceAuthority: root.surfaceAuthority, graph: Object.freeze(graph), extensions: Object.freeze([]) });
+  }
+  // Extensions are verified (lock, digest, manifest hash, compat) before their
+  // entry is imported, and are composed after the root in lock order. The
+  // composed definition is served for the root handle only; every other
+  // handle keeps the surface copy's own answer.
+  const baseDefinition = root.getDefinition(root.handle);
+  const extensions = await loadFlowExtensions(root.path, { definition: baseDefinition, surfaceAuthority: root.surfaceAuthority }, {
+    importFlow: importAuthoredFlow,
+    sameAuthority: (a, b) => canonicalize(a) === canonicalize(b),
+    ...(options.versions === undefined ? {} : { versions: options.versions }),
+  });
+  if (extensions.length === 0) {
+    return Object.freeze({ sourcePath: root.path, handle: root.handle, getDefinition: root.getDefinition,
+      surfaceAuthority: root.surfaceAuthority, graph: Object.freeze(graph), extensions });
+  }
+  const composed = composeDefinition(baseDefinition, extensions);
+  const getDefinition: GetFlowDefinition = <Input = unknown>(handle: FlowHandle) =>
+    (handle === root.handle ? composed : root.getDefinition(handle)) as AuthoredFlowDefinition<Input>;
+  for (const extension of extensions) {
+    // The node carries the accessor the entry's own surface copy handed back:
+    // the root's accessor answers for the root's WeakMap only.
+    graph.push(Object.freeze({ path: extension.entryPath, handle: extension.handle, getDefinition: extension.getDefinition,
+      surfaceAuthority: root.surfaceAuthority, use: Object.freeze([]) }));
+  }
+  return Object.freeze({ sourcePath: root.path, handle: root.handle, getDefinition,
+    surfaceAuthority: root.surfaceAuthority, graph: Object.freeze(graph), extensions });
 }
 
-async function importAuthoredFlow(path: string): Promise<Pick<LoadedAuthoredFlow, 'handle' | 'getDefinition' | 'surfaceAuthority'>> {
+async function importAuthoredFlow(path: string): Promise<ImportedFlow<SurfaceModuleAuthority>> {
   const absolutePath = resolve(path);
   try {
     accessSync(absolutePath, constants.R_OK);
@@ -128,7 +171,7 @@ async function importAuthoredFlow(path: string): Promise<Pick<LoadedAuthoredFlow
       `Flow "${path}" must default-export flow(...): ${errorMessage(error)}`,
     );
   }
-  return { handle, getDefinition, surfaceAuthority };
+  return { handle, getDefinition, surfaceAuthority, hooks: parseHooksExport(authoredModule, path) };
 }
 
 /**

package/src/authored-hooks.ts

@@ -0,0 +1,136 @@
+import type { Ctx } from '@relayflows/surface';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import type { LoadedFlowExtension } from './flow-extension-loader.js';
+import type { JournalClient } from './journal-client.js';
+
+const HOOK_STREAM = 'hooks';
+
+export interface HookRecord {
+  hook: string;
+  step: string;
+  plugin: string | null;
+  verdict: 'pass' | 'fail' | 'noop';
+  because?: string;
+  /** Parent `nextStep` after this verdict, so resume does not reuse inner step ids. */
+  afterStep?: number;
+}
+
+function recordKey(record: HookRecord): string {
+  return `${record.step}:${record.plugin ?? 'noop'}`;
+}
+
+/**
+ * AND-compose installed hook implementations in lock order. Verdicts are
+ * appended to the root run's `hooks` stream before the boolean is returned,
+ * so a resume reads the recorded verdict and never re-runs the closure.
+ * No implementations is a journaled no-op returning true. A false short-circuits.
+ */
+export function createHookEvaluator(options: {
+  readonly journal: JournalClient;
+  readonly rootRunId?: string;
+  readonly flowName: string;
+  readonly declared: readonly string[];
+  readonly extensions: readonly LoadedFlowExtension[];
+  readonly peekStep?: () => number;
+  readonly restoreStep?: (step: number) => void;
+  readonly signal?: AbortSignal;
+}): (id: string, name: string, input: unknown, context: Ctx) => Promise<boolean> {
+  let recorded: Promise<Map<string, HookRecord>> | undefined;
+
+  async function load(): Promise<Map<string, HookRecord>> {
+    const verdicts = new Map<string, HookRecord>();
+    if (options.rootRunId === undefined) return verdicts;
+    let offset = 0;
+    for (;;) {
+      const page = await options.journal.streamRead(options.rootRunId, HOOK_STREAM, offset, 1000);
+      for (const message of page.messages) {
+        const raw = (message as { message?: unknown }).message ?? message;
+        if (typeof raw !== 'object' || raw === null) continue;
+        const record = raw as HookRecord;
+        if (typeof record.hook !== 'string' || typeof record.step !== 'string') continue;
+        if (record.verdict !== 'pass' && record.verdict !== 'fail' && record.verdict !== 'noop') continue;
+        if (record.plugin !== null && typeof record.plugin !== 'string') continue;
+        verdicts.set(recordKey(record), record);
+      }
+      if (page.messages.length === 0 || page.next_offset <= offset) break;
+      offset = page.next_offset;
+    }
+    return verdicts;
+  }
+
+  async function lookup(key: string): Promise<HookRecord | undefined> {
+    if (options.rootRunId === undefined) return undefined;
+    recorded ??= load();
+    return (await recorded).get(key);
+  }
+
+  async function append(record: HookRecord): Promise<void> {
+    if (options.rootRunId === undefined) return;
+    recorded ??= load();
+    await options.journal.streamAppend(options.rootRunId, HOOK_STREAM, record);
+    (await recorded).set(recordKey(record), record);
+  }
+
+  return async (id, name, input, context) => {
+    if (!options.declared.includes(name)) {
+      throw new AuthoredFlowExecutionError(
+        'unsupported_verb',
+        `hook "${name}" is not declared by flow "${options.flowName}"`,
+      );
+    }
+    const impls = options.extensions.filter(extension => extension.hooks[name] !== undefined);
+    if (impls.length === 0) {
+      const existing = await lookup(`${id}:noop`);
+      const record = existing ?? { hook: name, step: id, plugin: null, verdict: 'noop' as const };
+      if (existing === undefined) await append(record);
+      else if (existing.afterStep !== undefined) options.restoreStep?.(existing.afterStep);
+      return true;
+    }
+    for (const extension of impls) {
+      const key = `${id}:${extension.name}`;
+      let record = await lookup(key);
+      if (record === undefined) {
+        let verdict = false;
+        let because: string | undefined;
+        try {
+          verdict = await boundHook(extension.hooks[name]!(context, input), options.signal) === true;
+        } catch (error) {
+          // Cancellation is control-plane state, not a plugin verdict. The
+          // shared execution signal also stops tracked f.run/f.agent work;
+          // rethrow so a later resume may run the hook again instead of
+          // replaying a permanent decline caused by an interrupted attempt.
+          if (options.signal?.aborted) throw error;
+          verdict = false;
+          because = error instanceof Error ? error.message : String(error);
+        }
+        record = {
+          hook: name, step: id, plugin: extension.name,
+          verdict: verdict ? 'pass' : 'fail',
+          ...(because === undefined ? {} : { because }),
+          ...(options.peekStep === undefined ? {} : { afterStep: options.peekStep() }),
+        };
+        await append(record);
+      } else if (record.afterStep !== undefined) {
+        options.restoreStep?.(record.afterStep);
+      }
+      if (record.verdict === 'fail') return false;
+    }
+    return true;
+  };
+}
+
+async function boundHook(run: Promise<boolean>, signal?: AbortSignal): Promise<boolean> {
+  // The parent run's wallclock budget owns the deadline. A second timer here
+  // would not be the signal captured by the hook's Ctx operations, allowing
+  // those operations to continue after this wrapper returned.
+  if (signal === undefined) return await run;
+  if (signal.aborted) throw signal.reason ?? new Error('hook cancelled');
+  return await new Promise<boolean>((resolve, reject) => {
+    const onAbort = () => reject(signal.reason ?? new Error('hook cancelled'));
+    signal.addEventListener('abort', onAbort, { once: true });
+    run.then(
+      value => { signal.removeEventListener('abort', onAbort); resolve(value); },
+      error => { signal.removeEventListener('abort', onAbort); reject(error); },
+    );
+  });
+}

package/src/authored-node-entry.ts

@@ -72,6 +72,7 @@ try {
     request.metadata.inputPresent ? request.metadata.input : undefined, {
       getDefinition: loaded.getDefinition, dataDir: request.dataDir,
       flowPath: request.metadata.flowPath, rootRunId: request.rootRunId,
+      extensions: loaded.extensions,
       localAgentStream: request.localAgentStream, signal: controller.signal,
       onProgress: event => send({ type: 'progress', event }),
       onWait: event => send({ type: 'wait', event }),

package/src/authored-root.ts

@@ -21,6 +21,12 @@ import { isSurfaceCompletionReason } from './authored-step-output.js';
 
 const ROOT_KIND = 'relayflows.authored-root.v1';
 
+export interface AuthoredRootExtension {
+  readonly name: string;
+  readonly digest: string;
+  readonly ref: string;
+}
+
 export interface AuthoredRootMetadata {
   readonly kind: typeof ROOT_KIND;
   readonly flowName: string;
@@ -28,6 +34,8 @@ export interface AuthoredRootMetadata {
   readonly sourceSha256: string;
   readonly surface: SurfaceModuleAuthority;
   readonly sources: readonly AuthoredRootSourceAuthority[];
+  /** Plugin-level provenance in lock order; empty when the project declares none. */
+  readonly extensions: readonly AuthoredRootExtension[];
   readonly localAgentStream?: string;
   readonly inputPresent: boolean;
   readonly input?: unknown;
@@ -68,6 +76,9 @@ export async function executeDurableAuthoredFlow(
     sourceSha256: sha256(source),
     surface: loaded.surfaceAuthority,
     sources: Object.freeze(sources),
+    extensions: Object.freeze((loaded.extensions ?? []).map(extension => Object.freeze({
+      name: extension.name, digest: extension.digest, ref: extension.ref,
+    }))),
     ...(options.localAgentStream === undefined ? {} : { localAgentStream: options.localAgentStream }),
     inputPresent: input !== undefined,
     ...(input === undefined ? {} : { input: jsonSnapshot(input, 'authored root input') }),
@@ -172,7 +183,7 @@ export async function readAuthoredRootMetadata(
   if (!isRootMetadata(value)) {
     throw new Error('authored root journal has malformed authority metadata');
   }
-  return value;
+  return Object.freeze({ ...value, extensions: value.extensions ?? [] });
 }
 
 async function driveRoot(
@@ -203,6 +214,7 @@ async function driveRoot(
           flowPath: metadata.flowPath,
           localAgentStream: options.localAgentStream,
           rootRunId: dispatch.run_id,
+          extensions: loaded.extensions,
           ...options.lifecycle,
           signal: callerSignal === undefined
             ? rootSignal
@@ -409,10 +421,19 @@ function isRootMetadata(value: unknown): value is AuthoredRootMetadata {
     && typeof surface.version === 'string' && /^[a-f0-9]{64}$/.test(surface.packageSha256 ?? '')
     && /^[a-f0-9]{64}$/.test(surface.runtimeSha256 ?? '')
     && Array.isArray(sources) && sources.length > 0 && sources.every(isRootSourceAuthority)
+    && (root.extensions === undefined || (Array.isArray(root.extensions) && root.extensions.every(isRootExtension)))
     && (root.localAgentStream === undefined
       || /^local-agent-[a-f0-9-]+$/.test(root.localAgentStream));
 }
 
+function isRootExtension(value: unknown): value is AuthoredRootExtension {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const extension = value as Partial<AuthoredRootExtension>;
+  return typeof extension.name === 'string' && extension.name.length > 0
+    && /^[a-f0-9]{64}$/.test(extension.digest ?? '')
+    && typeof extension.ref === 'string' && extension.ref.startsWith('github:');
+}
+
 function isRootSourceAuthority(value: unknown): value is AuthoredRootSourceAuthority {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
   const source = value as Partial<AuthoredRootSourceAuthority>;

package/src/authored-source-authority.ts

@@ -35,6 +35,12 @@ export async function loadPinnedAuthoredSource(metadata: AuthoredRootMetadata, i
   if (canonicalize(loadedSources) !== canonicalize(metadata.sources)) {
     throw new Error('authored root declared source graph authority mismatch');
   }
+  const loadedExtensions = (loaded.extensions ?? []).map(extension => ({
+    name: extension.name, digest: extension.digest, ref: extension.ref,
+  }));
+  if (canonicalize(loadedExtensions) !== canonicalize(metadata.extensions ?? [])) {
+    throw new Error('authored root declared extension authority mismatch');
+  }
   return loaded;
 }
 

package/src/bundle-extensions.ts

@@ -0,0 +1,85 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import type { BundleFile } from './bundle.js';
+import { safePath, sha256 } from './bundle.js';
+import { findPluginProject } from './plugin-loader.js';
+import { parsePluginLock, readPluginLock, reconcileDeclaredExtensions, type PluginLock } from './plugin-lock.js';
+import { PluginError } from './plugin-manifest.js';
+import { pluginStoreDirectory, readStoredPluginFiles, verifyStoredPlugin } from './plugin-store.js';
+
+const EMPTY_LOCK: PluginLock = Object.freeze({ version: 2, plugins: Object.freeze([]) });
+
+/**
+ * Plugin provenance and bytes to put in a sealed bundle: `lockfile.json` is
+ * the same v2 lock the project records, and each extension's materialized
+ * files land under `plugins/<name>/…`. No project / no github: plugins →
+ * `{ version: 2, plugins: [] }` and no files. Fail closed on lock/store drift.
+ */
+export async function collectBundleExtensions(flowPath: string): Promise<{ lock: PluginLock; files: BundleFile[] }> {
+  const root = findPluginProject(dirname(flowPath));
+  if (root === undefined) return { lock: EMPTY_LOCK, files: [] };
+  const locked = reconcileDeclaredExtensions(root);
+  const files: BundleFile[] = [];
+  for (const { entry } of locked) {
+    const stored = await readStoredPluginFiles(pluginStoreDirectory(root, entry.name, entry.digest), entry.digest);
+    for (const file of stored) files.push({ path: `plugins/${entry.name}/${file.path}`, data: file.data });
+  }
+  return { lock: readPluginLock(root), files };
+}
+
+/**
+ * After `verifyBundle` has hashed every payload file, check that `lockfile.json`
+ * is a v2 plugin lock (or a legacy v1 `{version:1, adapters}` with no plugins)
+ * and that each locked extension's store digest matches `plugins/<name>/manifest.json`.
+ */
+export async function verifyBundlePluginLock(bundle: string): Promise<void> {
+  let parsed: unknown;
+  try { parsed = JSON.parse(await readFile(join(bundle, 'lockfile.json'), 'utf8')); }
+  catch { throw new Error('lockfile.json: not valid JSON'); }
+  if (isLegacyV1Lock(parsed) || isLegacyNpmLock(parsed)) {
+    await assertNoLegacyPluginPayload(bundle);
+    return;
+  }
+  let lock: PluginLock;
+  try { lock = parsePluginLock(parsed); }
+  catch (error) {
+    throw new Error(error instanceof PluginError ? error.message : 'lockfile.json: not a plugin lock');
+  }
+  for (const entry of lock.plugins) {
+    if (!safePath(entry.name) || entry.name.includes('/')) {
+      throw new Error(`lockfile.json: plugin name ${entry.name} is not a safe path component`);
+    }
+    const directory = join(bundle, 'plugins', entry.name);
+    await verifyStoredPlugin(directory, entry.digest);
+    let pluginManifest: Buffer;
+    try { pluginManifest = await readFile(join(directory, 'flows-plugin.json')); }
+    catch { throw new Error(`lockfile.json: plugin ${entry.name} is missing plugins/${entry.name}/flows-plugin.json`); }
+    if (sha256(pluginManifest) !== entry.manifestSha256) {
+      throw new Error(`lockfile.json: plugin ${entry.name} flows-plugin.json does not match the lockfile manifest hash`);
+    }
+  }
+}
+
+async function assertNoLegacyPluginPayload(bundle: string): Promise<void> {
+  let entries: string[];
+  try { entries = await readdir(join(bundle, 'plugins')); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+    throw error;
+  }
+  if (entries.length > 0) {
+    throw new Error('lockfile.json: legacy locks cannot authenticate plugins/ payloads');
+  }
+}
+
+function isLegacyV1Lock(value: unknown): boolean {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    && (value as { version?: unknown }).version === 1
+    && Array.isArray((value as { adapters?: unknown }).adapters);
+}
+
+function isLegacyNpmLock(value: unknown): boolean {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const lock = value as { lockfileVersion?: unknown; packages?: unknown };
+  return (lock.lockfileVersion === 2 || lock.lockfileVersion === 3) && typeof lock.packages === 'object' && lock.packages !== null;
+}

package/src/bundle-typescript.ts

@@ -60,7 +60,7 @@ process.stdout.write(JSON.stringify({ spec, authored }));
       '--no-compile-autoload-bunfig', '--outfile', executable, input], directory);
     const files: BundleFile[] = [
       { path: 'flow', data: await readFile(executable) },
-      { path: 'lockfile.json', data: canonicalize(lock) },
+      { path: 'package-lock.json', data: canonicalize(lock) },
     ];
     return { spec, authored: inspected.authored === true, compiler, files };
   } finally { await rm(staging, { recursive: true, force: true }); }

package/src/bundle.ts

@@ -18,12 +18,24 @@ export function sha256(data: Uint8Array | string): string {
   return createHash('sha256').update(data).digest('hex');
 }
 
-function safePath(path: string): boolean {
+/** A bundle-relative path: no empty, `.`, or `..` component, no backslash, NUL, or drive colon. */
+export function safePath(path: string): boolean {
   return path.length > 0 && !path.includes('\\') && !path.includes('\0')
     && path.split('/').every(part => part !== '' && part !== '.' && part !== '..')
     && !path.includes(':');
 }
 
+/**
+ * The canonical entry list whose sha256 is a payload's content digest. Shared
+ * by sealed flow bundles and materialized plugins so `@sha256:` means one
+ * thing everywhere: the digest of `[{bytes,path,sha256}]`, sorted by path.
+ */
+export function payloadManifest(files: readonly { path: string; data: Uint8Array }[]): string {
+  return canonicalize([...files]
+    .sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)
+    .map(file => ({ path: file.path, sha256: sha256(file.data), bytes: file.data.length })));
+}
+
 /** Manifest and identity are envelopes, excluded to avoid circular hashing. */
 export async function sealBundle(options: BundleOptions): Promise<string> {
   if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(options.name)) {
@@ -41,9 +53,7 @@ export async function sealBundle(options: BundleOptions): Promise<string> {
   for (const required of ['spec.canonical.json', 'preflight.json', 'lockfile.json']) {
     if (!paths.has(required)) throw new Error(`${required}: missing bundle file`);
   }
-  const manifest = canonicalize(files.map(file => ({
-    path: file.path, sha256: sha256(file.data), bytes: file.data.length,
-  })));
+  const manifest = payloadManifest(files);
   const digest = sha256(manifest);
   const out = resolve(options.out);
   const target = join(out, `${options.name}@sha256:${digest}`);