@relayflows/sdk 2.0.32 → 2.0.34

package/src/helper-reference.ts

@@ -27,7 +27,8 @@ export function helperNamespacesUsed(body: string, root: string): ReadonlySet<st
   const program = parseFlowBody(body);
   if (program === null) return textFallback(body, root);
   const used = new Set<string>();
-  walk(program, (node) => {
+  const scope = { rootFunctionFound: false };
+  walkReferences(program, root, false, scope, (node) => {
     if (node.type !== 'MemberExpression') return;
     const object = node.object as AstNode | undefined;
     if (object?.type !== 'Identifier' || object.name !== root) return;
@@ -111,20 +112,144 @@ type AstNode = {
   [key: string]: unknown;
 };
 
-/** Depth-first over every child node, without pulling in a second package. */
-function walk(node: AstNode, visit: (node: AstNode) => void): void {
-  visit(node);
+/**
+ * Depth-first over references that still resolve to the outer flow context.
+ *
+ * A nested callback/method parameter or lexical destructuring can reuse the
+ * context's spelling while binding an unrelated value. Counting its members
+ * would refuse the flow for a mount it never touches. Acorn gives us binding
+ * shapes, so scopes are tracked as syntax instead of guessed from text.
+ */
+function walkReferences(
+  node: AstNode,
+  root: string,
+  shadowed: boolean,
+  state: { rootFunctionFound: boolean },
+  visit: (node: AstNode) => void,
+): void {
+  if (isFunction(node)) {
+    const parameters = Array.isArray(node.params) ? node.params.filter(isNode) : [];
+    const bindsParameter = parameters.some(parameter => patternBinds(parameter, root));
+    let bodyHidden = shadowed;
+    const isRootFunction = bindsParameter && !state.rootFunctionFound;
+    if (isRootFunction) state.rootFunctionFound = true;
+    else if (bindsParameter || (isNode(node.id) && patternBinds(node.id, root)) || functionVarBinds(node, root)) {
+      bodyHidden = true;
+    }
+    // Parameter initializers run before the function body and are outside a
+    // body-level `var` scope. Keep them visible unless the parameter list
+    // itself binds the root name (in which case all parameter references are
+    // local to that parameter environment).
+    const parameterHidden = shadowed || (bindsParameter && !isRootFunction);
+    for (const parameter of parameters) walkReferences(parameter, root, parameterHidden, state, visit);
+    const body = isNode(node.body) ? node.body : undefined;
+    if (body !== undefined) walkReferences(body, root, bodyHidden, state, visit);
+    return;
+  }
+  let hidden = shadowed;
+  if (node.type === 'BlockStatement' && blockBinds(node, root)) {
+    hidden = true;
+  } else if (node.type === 'CatchClause' && isNode(node.param) && patternBinds(node.param, root)) {
+    hidden = true;
+  }
+
+  if (!hidden) visit(node);
   for (const key of Object.keys(node)) {
     if (key === 'type' || key === 'start' || key === 'end' || key === 'loc') continue;
     const child = node[key];
     if (Array.isArray(child)) {
-      for (const entry of child) if (isNode(entry)) walk(entry, visit);
+      for (const entry of child) if (isNode(entry)) walkReferences(entry, root, hidden, state, visit);
     } else if (isNode(child)) {
-      walk(child, visit);
+      walkReferences(child, root, hidden, state, visit);
     }
   }
 }
 
+function isFunction(node: AstNode): boolean {
+  return node.type === 'ArrowFunctionExpression'
+    || node.type === 'FunctionExpression'
+    || node.type === 'FunctionDeclaration';
+}
+
+/** Lexical declarations bind across their complete block, including TDZ. */
+function blockBinds(node: AstNode, root: string): boolean {
+  const statements = Array.isArray(node.body) ? node.body.filter(isNode) : [];
+  return statements.some((statement) => {
+    if (statement.type === 'VariableDeclaration' && statement.kind !== 'var') {
+      const declarations = Array.isArray(statement.declarations)
+        ? statement.declarations.filter(isNode) : [];
+      return declarations.some(declaration => isNode(declaration.id) && patternBinds(declaration.id, root));
+    }
+    return (statement.type === 'FunctionDeclaration' || statement.type === 'ClassDeclaration')
+      && isNode(statement.id) && patternBinds(statement.id, root);
+  });
+}
+
+/** Identifier occurrences that introduce bindings, including nested patterns. */
+function patternBinds(pattern: AstNode, root: string): boolean {
+  switch (pattern.type) {
+    case 'Identifier':
+      return pattern.name === root;
+    case 'AssignmentPattern':
+      return isNode(pattern.left) && patternBinds(pattern.left, root);
+    case 'RestElement':
+      return isNode(pattern.argument) && patternBinds(pattern.argument, root);
+    case 'ArrayPattern': {
+      const elements = Array.isArray(pattern.elements) ? pattern.elements : [];
+      return elements.some(element => isNode(element) && patternBinds(element, root));
+    }
+    case 'ObjectPattern': {
+      const properties = Array.isArray(pattern.properties) ? pattern.properties : [];
+      return properties.some(property => {
+        if (!isNode(property)) return false;
+        if (property.type === 'RestElement') {
+          return isNode(property.argument) && patternBinds(property.argument, root);
+        }
+        // Object keys are labels, not bindings. Only the value side introduces
+        // the local (including a default-value AssignmentPattern's left side).
+        return property.type === 'Property'
+          && isNode(property.value)
+          && patternBinds(property.value, root);
+      });
+    }
+    default:
+      return false;
+  }
+}
+
+/** `var` is function-scoped, so a nested function's declaration hides the
+ * outer flow context for its entire body, including code before the
+ * declaration. Nested functions have their own var scopes and are skipped. */
+function functionVarBinds(node: AstNode, root: string): boolean {
+  const body = isNode(node.body) ? node.body : undefined;
+  if (body === undefined) return false;
+  let found = false;
+  const scan = (current: AstNode): void => {
+    if (found) return;
+    if (current !== body && isFunction(current)) return;
+    if (current.type === 'VariableDeclaration' && current.kind === 'var') {
+      const declarations = Array.isArray(current.declarations)
+        ? current.declarations.filter(isNode) : [];
+      if (declarations.some(declaration => isNode(declaration.id) && patternBinds(declaration.id, root))) {
+        found = true;
+        return;
+      }
+    }
+    for (const key of Object.keys(current)) {
+      if (key === 'type' || key === 'start' || key === 'end' || key === 'loc') continue;
+      const child = current[key];
+      if (Array.isArray(child)) {
+        for (const entry of child) if (isNode(entry)) scan(entry);
+      } else if (isNode(child)) {
+        scan(child);
+      }
+      if (found) return;
+    }
+  };
+  scan(body);
+  return found;
+}
+
 function isNode(value: unknown): value is AstNode {
   return typeof value === 'object' && value !== null && typeof (value as { type?: unknown }).type === 'string';
 }

package/src/hosted-extension-declarations.ts

@@ -67,6 +67,9 @@ const STRING_STARTS_WITH = Function.prototype.call.bind(
 ) as (value: string, search: string) => boolean;
 const LOCK_HEX64 = /^[0-9a-f]{64}$/;
 const LOCK_SHA = /^[0-9a-f]{40}$/;
+// `name` reaches pluginStoreDirectory as a path segment, so it stays one
+// lowercase kebab-case component: no separators, no `.`/`..`, no traversal.
+const LOCK_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const LOCK_OWNER = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
 const LOCK_REPO = /^[A-Za-z0-9_.-]{1,100}$/;
 const HTTPS_GITHUB = /^https:\/\/github\.com\//;
@@ -240,6 +243,7 @@ function parseHostedPluginLock(input: unknown): {
       ]) ||
       entry.kind !== "flow-extension" ||
       typeof entry.name !== "string" ||
+      !REGEXP_TEST(LOCK_NAME, entry.name) ||
       typeof entry.version !== "string" ||
       typeof entry.digest !== "string" ||
       !REGEXP_TEST(LOCK_HEX64, entry.digest) ||

package/src/hosted-extension-isolation.ts

@@ -10,6 +10,7 @@ import {
 import {
   assertHostedInstallationAuthority,
   assertHostedRuntimeAuthority,
+  loadHostedExtensionRuntime,
   type HostedExtensionArtifact,
   type HostedExtensionBase,
   type HostedExtensionInstallation,
@@ -104,8 +105,42 @@ export interface RunHostedExtensionOptions {
   readonly prlimitPath?: string;
 }
 
+export interface RunHostedSoftwareGardenBabysitterOptions
+  extends Omit<RunHostedExtensionOptions, 'installation' | 'base'> {
+  /** Exact reviewed Software Garden source inside its lock-backed project. */
+  readonly flowPath: string;
+}
+
 export type HostedExtensionResult = HostedExtensionProtocolResult;
 
+/**
+ * Compose the canonical Software Garden base with its installed native
+ * Babysitter and execute one host-verified delivery. Base source, extension
+ * declarations, lock entries and stored bytes are captured as one opaque
+ * generation; the capability runner rechecks that generation immediately
+ * before the isolated process starts.
+ *
+ * Hosted callers use this entrypoint instead of the ordinary authored loader,
+ * which imports extension JavaScript in the host and therefore keeps refusing
+ * matched hosted handlers.
+ */
+export async function runHostedSoftwareGardenBabysitter(
+  options: RunHostedSoftwareGardenBabysitterOptions,
+): Promise<HostedExtensionResult> {
+  const runtime = await loadHostedExtensionRuntime(options.flowPath);
+  return await runHostedCapabilityExtension({
+    installation: runtime.installation,
+    base: runtime.base,
+    dispatch: options.dispatch,
+    input: options.input,
+    babysitterTurn: options.babysitterTurn,
+    ...(OBJECT_HAS_OWN(options, 'timeoutMs') ? { timeoutMs: options.timeoutMs } : {}),
+    ...(OBJECT_HAS_OWN(options, 'bubblewrapPath') ? { bubblewrapPath: options.bubblewrapPath } : {}),
+    ...(OBJECT_HAS_OWN(options, 'nodePath') ? { nodePath: options.nodePath } : {}),
+    ...(OBJECT_HAS_OWN(options, 'prlimitPath') ? { prlimitPath: options.prlimitPath } : {}),
+  });
+}
+
 /**
  * Execute a capability-only hosted extension in a Linux mount/PID/network/user
  * namespace. The extension is first imported inside that namespace. It sees
@@ -114,8 +149,9 @@ export type HostedExtensionResult = HostedExtensionProtocolResult;
  * authenticated capability adapter and passes the original branded dispatch
  * authority to that adapter out of band.
  *
- * This is deliberately not wired into executeAuthoredFlow yet. #549's refusal
- * remains the rollout gate until the Cloud adapter and independent review land.
+ * The ordinary authored executor deliberately stays refused: it imports
+ * extension JavaScript in the host. `runHostedSoftwareGardenBabysitter` is the
+ * canonical composition boundary for a hosted Software Garden delivery.
  */
 export async function runHostedCapabilityExtension(
   options: RunHostedExtensionOptions,

package/src/hosted-extension-runtime.ts

@@ -26,7 +26,7 @@ const REALPATH = realpath;
 const PATH_DIRNAME = dirname;
 const PATH_JOIN = join;
 const PATH_RESOLVE = resolve;
-const SOFTWARE_FACTORY_SHA256 = 'b97a3466c2affabb61afa655d4b2f726942d753c0466740b64ba26a78da359c6';
+const SOFTWARE_FACTORY_SHA256 = '8bbcf0e42f47d6bc6491a129935f96b791be03c8a5ed5b73d651c4e77913e2d7';
 const ARRAY_IS_ARRAY = Array.isArray;
 const OBJECT_FREEZE = Object.freeze;
 const WEAK_MAP_GET = Function.prototype.call.bind(WeakMap.prototype.get) as <K extends object, V>(
@@ -243,7 +243,7 @@ async function baseAt(origin: string, generation: RuntimeGeneration): Promise<Ho
     }
     const value = frozenHostedPromiseValue({
       name: 'software-factory',
-      version: '2.0.22',
+      version: '2.0.23',
     });
     WEAK_SET_ADD(BASE_AUTHORITY, value);
     WEAK_MAP_SET(BASE_GENERATION, value, generation);

package/src/hosted-extension-sandbox.ts

@@ -53,6 +53,22 @@ const PATH_RESOLVE = resolve;
 const SPAWN = spawn;
 const PROCESS_EXEC_PATH = process.execPath;
 const PROCESS_NODE_VERSION = process.versions.node;
+
+/**
+ * The host's own `@relayflows/surface` entry, resolved once while this module
+ * initializes. `require.resolve` consults `Module._resolveFilename`, which is
+ * writable: resolving lazily would run after authored flow code has had a
+ * chance to replace it and could hand the sandbox a different package. The
+ * lookup therefore happens before any authored module can load, and a failure
+ * is reported when a caller actually needs the root.
+ */
+const SURFACE_ENTRY: string | undefined = (() => {
+  try { return REALPATH_SYNC(CREATE_REQUIRE(import.meta.url).resolve('@relayflows/surface')); }
+  catch { return undefined; }
+})();
+
+/** @internal Seam for the regression that pins initialization-time capture. */
+export function capturedSurfaceEntry(): string | undefined { return SURFACE_ENTRY; }
 const PROCESS_PLATFORM = process.platform;
 const PROMISE = Promise;
 const EVENT_ON = Function.prototype.call.bind(EventEmitter.prototype.on) as (
@@ -109,7 +125,7 @@ const ADDRESS_SPACE_BYTES = 16 * 1024 * 1024 * 1024;
 const DATA_BYTES = 3 * 1024 * 1024 * 1024;
 const SURFACE_RUNTIME_SHA256 = OBJECT_FREEZE({
   'flow.js': '4aaeacc55de3074f4d121ce7253c3be50a93757e6540ba8159889a9450d1c05c',
-  'helpers/providers.js': '7bc62eccaa3a9e786ae0a689bf74160585149e91feef8208e17ef8eca51eed7f',
+  'helpers/providers.js': '4eb06d0d85ca0a3434bb2dbba7407e3d95eef2dfbedaeb0e2de0c0c0ea812457',
   'provider-trigger.js': 'e2664c65397f93fb486eb6f1e756c7cec3f88b3851d79c23567cad986f80f1ff',
   'schedule.js': '8fe72f176a75ec0b5f26e12db7a597575c259a2e2cbb59690f9dc20a5e63940b',
   'triggers.js': '4a3515b571a318f6c7a5661f9310bc9af43e3faf20ea39903a9b363c51258e4c',
@@ -250,9 +266,8 @@ export async function runHostedExtensionSandbox(
 
 async function resolveSurfaceRoot(expectedVersion: string, override?: string): Promise<string> {
   if (override !== undefined) return await checkedSurfaceRoot(override, expectedVersion);
-  let resolved: string;
-  try { resolved = REALPATH_SYNC(CREATE_REQUIRE(import.meta.url).resolve('@relayflows/surface')); }
-  catch { return unsupported('hosted extension cannot resolve @relayflows/surface'); }
+  const resolved = SURFACE_ENTRY;
+  if (resolved === undefined) return unsupported('hosted extension cannot resolve @relayflows/surface');
   let directory = PATH_DIRNAME(resolved);
   const root = PATH_PARSE(directory).root;
   while (directory !== root) {

package/src/index.ts

@@ -61,6 +61,7 @@ export type { StepSpend } from './protocol.js';
 export { SPEC_SCHEMA_VERSION } from './spec.js';
 
 export {
+  runHostedSoftwareGardenBabysitter,
   runHostedCapabilityExtension,
   loadHostedExtensionRuntime,
   type HostedExtensionArtifact,
@@ -70,6 +71,7 @@ export {
   type HostedCapabilityAuthority,
   type HostedBabysitterCapability,
   type RunHostedExtensionOptions,
+  type RunHostedSoftwareGardenBabysitterOptions,
   type HostedExtensionResult,
 } from './hosted-extension-isolation.js';
 export {