@pulse-compute/wasm-compiler 1.0.0-beta.5 → 1.0.0-beta.7

package/src/spine/bounded-pure-loop.js

@@ -8,7 +8,7 @@ function loadContract() {
     throw error;
   }
 }
-const { CANONICAL_PURE_LOOP_LIMITS } = loadContract();
+const { CANONICAL_PURE_LOOP_LIMITS, CANONICAL_READ_LOOP_CONTRACT } = loadContract();
 
 function unwrap(node) {
   while (node && (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isTypeAssertionExpression(node) || ts.isNonNullExpression(node))) node = node.expression;
@@ -30,10 +30,18 @@ function firstConjunct(node) {
 // extra application expressions after the counter reaches its cap.
 function inspectBoundedPureLoop(statement, options = {}) {
   const errors = [];
+  let loopDepth = 0;
+  let effectCount = 0;
+  let checkingHeader = false;
+  let activeProduct = 1;
+  let maxIterationProduct = 1;
+  const readBody = () => options.readLoop === true && loopDepth === 1 && !checkingHeader;
+  const protectedNames = new Set(options.readLoop ? [options.ctxName, ...(options.namespaceAliases || [])] : []);
   function fail(node, message) { errors.push({ node, message }); }
-  function expression(input, counters, mutation = true) {
-    const node = unwrap(input);
+  function expression(input, counters, mutation = true, effectRoot = false) {
+    let node = unwrap(input);
     if (!node) return;
+    if (readBody() && effectRoot && ts.isAwaitExpression(node)) node = unwrap(node.expression);
     if (ts.isIdentifier(node)) {
       if (node.text === options.ctxName) fail(node, 'Read context values before entering a pure loop.');
       return;
@@ -50,6 +58,44 @@ function inspectBoundedPureLoop(statement, options = {}) {
     }
     if (ts.isCallExpression(node)) {
       const target = unwrap(node.expression);
+      const pure = !checkingHeader && options.pureHelperForCall?.(node);
+      if (pure) {
+        if (activeProduct * (pure.maxIterationProduct || 1) > CANONICAL_PURE_LOOP_LIMITS.maxNestedIterations) fail(node, 'Pure helper exceeds the combined caller/callee iteration bound.');
+        if (node.questionDotToken || node.typeArguments?.length) fail(node, 'Pure loop calls require a static synchronous helper.');
+        for (const argument of node.arguments) expression(argument, counters, false);
+        return;
+      }
+      const helper = readBody() && options.helperForCall && options.helperForCall(node);
+      if (helper) {
+        if (!effectRoot) { fail(node, 'Read-loop helpers require a directly bound sequential call.'); return; }
+        effectCount += 1;
+        for (const argument of node.arguments) {
+          // Original-source JavaScript calls retain their explicit context input.
+          if (!named(argument, options.ctxName)) expression(argument, counters, false);
+        }
+        return;
+      }
+      const effect = readBody() && options.effectForCall && options.effectForCall(node);
+      if (effect) {
+        if (!effectRoot || !CANONICAL_READ_LOOP_CONTRACT.effectKinds.includes(effect.kind)) {
+          fail(node, 'Read loops admit only directly bound or discarded sequential s3.getText, kv.getVersioned, crypto.digestText, output.write and req.readTextChunk effects.'); return;
+        }
+        effectCount += 1;
+        for (const argument of node.arguments) {
+          // Package facades receive the context as their first argument.
+          if (!named(argument, options.ctxName)) expression(argument, counters, false);
+        }
+        // A direct KV namespace expression is also evaluated at the call site.
+        if (ts.isPropertyAccessExpression(target) && ts.isCallExpression(unwrap(target.expression))) {
+          for (const argument of unwrap(target.expression).arguments) expression(argument, counters, false);
+        }
+        return;
+      }
+      if (readBody() && ts.isPropertyAccessExpression(target) && named(target.expression, options.ctxName)
+        && ['decodeJson', 'encodeJson', 'text', 'json', 'response'].includes(target.name.text) && !node.questionDotToken && !target.questionDotToken) {
+        for (const argument of node.arguments) expression(argument, counters, mutation);
+        return;
+      }
       if (!ts.isPropertyAccessExpression(target) || target.name.text !== 'trim' || node.arguments.length || node.questionDotToken || target.questionDotToken) {
         fail(node, 'Pure loops admit only zero-argument string .trim() calls; effects, helpers and callbacks are separate contracts.'); return;
       }
@@ -59,12 +105,12 @@ function inspectBoundedPureLoop(statement, options = {}) {
       const assignment = node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && node.operatorToken.kind <= ts.SyntaxKind.LastAssignment;
       const target = unwrap(node.left);
       if (assignment && !ts.isIdentifier(target) && !ts.isPropertyAccessExpression(target) && !ts.isElementAccessExpression(target)) fail(node, 'Destructuring assignment is outside the pure loop subset.');
-      if (assignment && (!mutation || [...counters].some(name => named(node.left, name)))) fail(node, 'Loop tests cannot mutate values, and loop counters cannot be assigned in the body.');
+      if (assignment && (!mutation || [...counters, ...protectedNames].some(name => named(node.left, name)))) fail(node, 'Loop tests cannot mutate values, and active counters or context/namespace aliases cannot be assigned in the body.');
       expression(node.left, counters, mutation); expression(node.right, counters, mutation); return;
     }
     if (ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) {
       const update = node.operator === ts.SyntaxKind.PlusPlusToken || node.operator === ts.SyntaxKind.MinusMinusToken;
-      if (update && (!mutation || [...counters].some(name => named(node.operand, name)))) fail(node, 'Loop tests cannot mutate values, and loop counters cannot be updated in the body.');
+      if (update && (!mutation || [...counters, ...protectedNames].some(name => named(node.operand, name)))) fail(node, 'Loop tests cannot mutate values, and active counters or context/namespace aliases cannot be updated in the body.');
       expression(node.operand, counters, mutation); return;
     }
     if (ts.isConditionalExpression(node)) {
@@ -95,8 +141,8 @@ function inspectBoundedPureLoop(statement, options = {}) {
     if (ts.isVariableStatement(node)) {
       if (!(node.declarationList.flags & ts.NodeFlags.BlockScoped)) fail(node, 'Pure loop locals must use let or const.');
       for (const declaration of node.declarationList.declarations) {
-        if (!ts.isIdentifier(declaration.name) || counters.has(declaration.name.text)) fail(declaration, 'Loop locals require identifiers and cannot shadow an active counter.');
-        if (declaration.initializer) expression(declaration.initializer, counters);
+        if (!ts.isIdentifier(declaration.name) || counters.has(declaration.name.text) || protectedNames.has(declaration.name.text)) fail(declaration, 'Loop locals require identifiers and cannot shadow active counters or context/namespace aliases.');
+        if (declaration.initializer) expression(declaration.initializer, counters, true, readBody() && node.declarationList.declarations.length === 1);
       }
       return;
     }
@@ -104,7 +150,8 @@ function inspectBoundedPureLoop(statement, options = {}) {
       expression(node.expression, counters); body(node.thenStatement, counters, product);
       if (node.elseStatement) body(node.elseStatement, counters, product); return;
     }
-    if (ts.isExpressionStatement(node)) { expression(node.expression, counters); return; }
+    if (ts.isExpressionStatement(node)) { expression(node.expression, counters, true, readBody()); return; }
+    if ((readBody() || options.pureHelper === true) && ts.isReturnStatement(node)) { expression(node.expression, counters); return; }
     if (ts.isBreakStatement(node) || ts.isContinueStatement(node)) {
       if (node.label) fail(node, 'Pure loop break and continue must be unlabelled.');
       return;
@@ -113,6 +160,7 @@ function inspectBoundedPureLoop(statement, options = {}) {
     fail(node, 'Pure loop bodies accept locals, value assignments, if/else, nested bounded for, break and continue only.');
   }
   function loop(node, inherited, product) {
+    const isReadLoop = options.readLoop === true && loopDepth === 0;
     const list = node.initializer;
     const declaration = list && ts.isVariableDeclarationList(list) && list.declarations.length === 1 && list.declarations[0];
     if (!declaration || !(list.flags & ts.NodeFlags.Let) || !ts.isIdentifier(declaration.name) || !number(declaration.initializer, 0)) {
@@ -124,7 +172,7 @@ function inspectBoundedPureLoop(statement, options = {}) {
       fail(node, 'The first loop condition must be index < a literal iteration cap.'); return;
     }
     const maxIterations = Number(unwrap(bound.right).text);
-    if (!Number.isInteger(maxIterations) || maxIterations < 0 || maxIterations > CANONICAL_PURE_LOOP_LIMITS.maxIterations || product * Math.max(1, maxIterations) > CANONICAL_PURE_LOOP_LIMITS.maxNestedIterations) {
+    if (!Number.isInteger(maxIterations) || maxIterations < 0 || maxIterations > (isReadLoop ? CANONICAL_READ_LOOP_CONTRACT.maxIterations : CANONICAL_PURE_LOOP_LIMITS.maxIterations) || product * Math.max(1, maxIterations) > CANONICAL_PURE_LOOP_LIMITS.maxNestedIterations) {
       fail(node, 'The literal loop cap or nested iteration product exceeds the portable limit.'); return;
     }
     const increment = unwrap(node.incrementor);
@@ -132,14 +180,31 @@ function inspectBoundedPureLoop(statement, options = {}) {
       && !(ts.isBinaryExpression(increment) && increment.operatorToken.kind === ts.SyntaxKind.PlusEqualsToken && named(increment.left, name) && number(increment.right, 1))) {
       fail(node, 'The loop increment must be index++ or index += 1.'); return;
     }
-    if (inherited.has(name)) fail(declaration, 'Nested loop counters cannot shadow active counters.');
+    if (inherited.has(name) || protectedNames.has(name)) fail(declaration, 'Nested loop counters cannot shadow active counters or context/namespace aliases.');
     const counters = new Set([...inherited, name]);
+    // Header tests retain the pure value contract, including no effects.
+    const previousHeader = checkingHeader;
+    checkingHeader = true;
     expression(node.condition, counters, false);
-    body(node.statement, counters, product * Math.max(1, maxIterations));
+    checkingHeader = previousHeader;
+    if (!options.headerOnly) {
+      loopDepth += 1;
+      const previousProduct = activeProduct;
+      activeProduct = product * Math.max(1, maxIterations);
+      maxIterationProduct = Math.max(maxIterationProduct, activeProduct);
+      body(node.statement, counters, activeProduct);
+      activeProduct = previousProduct;
+      loopDepth -= 1;
+    }
     return { name, maxIterations };
   }
   const result = loop(statement, new Set(), 1);
-  return { ...result, errors };
+  if (options.readLoop && !options.headerOnly && !effectCount) fail(statement, 'A bounded read loop requires at least one admitted sequential effect site.');
+  return { ...result, errors, effectCount, maxIterationProduct };
+}
+
+function inspectBoundedReadLoop(statement, options = {}) {
+  return inspectBoundedPureLoop(statement, { ...options, readLoop: true });
 }
 
-module.exports = { inspectBoundedPureLoop };
+module.exports = { inspectBoundedPureLoop, inspectBoundedReadLoop };

package/src/spine/canonical-handler-ir.js

@@ -39,7 +39,9 @@ function annotateSites(effectSites, continuationSites, routerMetadata) {
   }
 
   function annotate(site) {
-    const owner = ownerForPosition(site && site.position);
+    // Package diagnostics retain authored locations, including imported files.
+    // Router ownership instead follows the mapped call in generated source.
+    const owner = ownerForPosition(site && (site.generatedPosition || site.position));
     if (!owner) return site;
     const ownerKind = owner.kind || 'route';
     const plane = owner.plane || (ownerKind === 'event' ? 'event' : 'http');

package/src/spine/guest-unit-stage.js

@@ -32,6 +32,10 @@ const {
 
 function optimizationPosture(value) {
   if (value === undefined || value === null || value === false) return 'native-default';
+  if (
+    value === 'experimental-native-bounded-size'
+    || (value && typeof value === 'object' && value.mode === 'experimental-native-bounded-size')
+  ) return 'native-default';
   if (
     value === true
     || value === 'experimental-native-size'
@@ -67,8 +71,13 @@ function realizeSelectedGuestUnits(realization, guestUnits, options = {}) {
   return Object.freeze({
     ...realization,
     wasm: result.wasm,
-    wat: result.wat,
-    guestUnits: result.guestUnits,
+    // Guest linking retains its mandatory independent disassembly audit.
+    // Only an explicitly requested diagnostic becomes an output artifact.
+    wat: realization.textEmitted ? result.wat : '',
+    // Preserve trusted package roots for subsequent provider-specific linking.
+    guestUnits: Object.freeze(result.guestUnits.map(unit => Object.freeze({
+      ...unit, packageRoot: selected.find(selection => selection.id === unit.id).packageRoot
+    }))),
     guestLink: Object.freeze({
       version: result.version,
       plan: result.plan,

package/src/spine/handler-ir-emitter.js

@@ -66,6 +66,8 @@ function providerEffectExpression(factory, sourceFile, site, providerOperation)
     properties.push(literalProperty(factory, 'key', providerOperation.key));
     if (providerOperation.generation) properties.push(literalProperty(factory, 'generation', providerOperation.generation));
     if (providerOperation.value) properties.push(literalProperty(factory, 'value', providerOperation.value));
+  } else if (providerOperation.providerKind === 'output') {
+    if (providerOperation.args[0]) properties.push(literalProperty(factory, 'argument0', providerOperation.args[0]));
   } else if (providerOperation.kind === 'event.emit') {
     properties.push(literalProperty(factory, 'type', providerOperation.type));
     properties.push(literalProperty(factory, 'emission', providerOperation.emission));
@@ -262,6 +264,22 @@ function emitCanonicalHandlerGenerator(ir) {
 
   function emitOperation(entry) {
     switch (entry.kind) {
+      case 'helper-body':
+        return factory.updateFunctionDeclaration(entry.statement, entry.statement.modifiers,
+          entry.pure ? undefined : factory.createToken(ts.SyntaxKind.AsteriskToken), entry.statement.name,
+          undefined, entry.statement.parameters, undefined, emitOperation(entry.body));
+      case 'helper-call':
+        return factory.updateVariableStatement(entry.statement, entry.statement.modifiers,
+          factory.updateVariableDeclarationList(entry.statement.declarationList, [factory.updateVariableDeclaration(
+            entry.declaration, entry.declaration.name, undefined, entry.declaration.type,
+            factory.createYieldExpression(factory.createToken(ts.SyntaxKind.AsteriskToken), entry.call))]));
+      case 'router-body':
+        return factory.updateFunctionDeclaration(entry.statement, entry.statement.modifiers,
+          factory.createToken(ts.SyntaxKind.AsteriskToken), entry.statement.name,
+          undefined, [], undefined, emitOperation(entry.body));
+      case 'router-body-call':
+        return factory.updateReturnStatement(entry.statement,
+          factory.createYieldExpression(factory.createToken(ts.SyntaxKind.AsteriskToken), entry.statement.expression));
       case 'source-statement':
         return rewritePackageIntrinsics(entry.statement);
       case 'block':
@@ -276,6 +294,8 @@ function emitCanonicalHandlerGenerator(ir) {
           emitOperation(entry.thenOperation),
           entry.elseOperation ? emitOperation(entry.elseOperation) : undefined
         );
+      case 'read-loop':
+        return factory.updateForStatement(entry.statement, entry.initializer, entry.test, entry.increment, emitOperation(entry.body));
       case 'fetch-single': {
         const { candidate, site, continuation } = entry;
         const marker = fetchEffectExpression(factory, sourceFile, site, candidate.chain);

package/src/spine/handler-ir-managed.js

@@ -815,7 +815,7 @@ function effectPlanForHandler(options) {
   });
 }
 
-function compileHandler(resolved, graphBuild, allResolved, diagnostics, packageRecognition) {
+function compileHandler(resolved, graphBuild, allResolved, diagnostics, packageRecognition, options = {}) {
   const descriptor = resolved.descriptor;
   const sourceFile = resolved.sourceModule.sourceFile;
   const original = resolved.functionNode;
@@ -868,10 +868,18 @@ function compileHandler(resolved, graphBuild, allResolved, diagnostics, packageR
     frontend: 'canonical-source',
     role: MANAGED_HANDLER_ROLE,
     strict: true,
-    requireEffectAwait: false,
+    requireEffectAwait: options.target === 'javascript',
+    target: options.target,
     packageEffectForCall
   });
   diagnostics.push(...normalizer.diagnostics);
+  // JavaScript executes the original source graph. Native expression admission
+  // is independent, and cannot prevent inspection of that explicit target.
+  const nativeDiagnostics = options.target === 'javascript' ? [] : diagnostics;
+  if (options.target === 'javascript') nativeDiagnostics.push(...normalizeManagedHandler(original, {
+    sourceFile, ctxName, frontend: 'canonical-source', role: MANAGED_HANDLER_ROLE,
+    strict: true, requireEffectAwait: false, packageEffectForCall
+  }).diagnostics);
   const handler = normalizer.functionNode;
 
   const schemaReferences = Object.freeze([
@@ -896,6 +904,7 @@ function compileHandler(resolved, graphBuild, allResolved, diagnostics, packageR
     })
   };
   const rawOperationIr = buildPlainHandlerIr(frontend, {
+    target: options.target,
     packageEffects: packageInputs.effects,
     packageIntrinsics: packageInputs.intrinsics,
     packageResultAdapters: packageInputs.resultAdapters,
@@ -916,7 +925,7 @@ function compileHandler(resolved, graphBuild, allResolved, diagnostics, packageR
   const compileExpression = createExpressionCompiler({
     sourceFile,
     descriptor,
-    diagnostics,
+    diagnostics: nativeDiagnostics,
     ctxName,
     inputName,
     handlerTargets,
@@ -938,7 +947,7 @@ function compileHandler(resolved, graphBuild, allResolved, diagnostics, packageR
   ]);
 
   function fail(node, code, message, detail = {}) {
-    diagnostics.push(diagnostic({ descriptor, sourceFile, node, code, message, detail }));
+    nativeDiagnostics.push(diagnostic({ descriptor, sourceFile, node, code, message, detail }));
   }
 
   function registerEffectRuntimeInputs(site, candidate, scope) {
@@ -1377,6 +1386,9 @@ function compileHandler(resolved, graphBuild, allResolved, diagnostics, packageR
     packageEffects: packageInputs.effects,
     packageLowering: packageInputs.lowering
   });
+  if (options.target === 'javascript') diagnostics.push(...nativeDiagnostics.filter(entry => [
+    'PULSE_MANAGED_HANDLER_RECURSION_UNSUPPORTED', 'PULSE_MANAGED_HANDLER_DIRECT_CALL_UNSUPPORTED'
+  ].includes(entry.code)));
   const semantic = {
     version: managedHandlerIrVersion,
     kind: 'managed-handler',
@@ -1408,7 +1420,8 @@ function compileHandler(resolved, graphBuild, allResolved, diagnostics, packageR
       inspected: true,
       packageTargetPromotion: false,
       javascript: Object.freeze({ eligible: true, blockers: Object.freeze([]) }),
-      native: Object.freeze({ eligible: true, blockers: Object.freeze([]) })
+      native: Object.freeze({ eligible: options.target !== 'javascript' || nativeDiagnostics.length === 0,
+        blockers: Object.freeze(options.target === 'javascript' ? sortedUnique(nativeDiagnostics.map(entry => entry.code)) : []) })
     })
   };
   const record = deepFreeze({ ...semantic, handlerHash: sha256Hex(stableStringify(semantic)) });
@@ -1465,7 +1478,7 @@ function compileManagedHandlerDescriptors(inputs = {}) {
   const resolved = resolveDescriptors(inputs.graphBuild, descriptors, diagnostics);
   const handlers = [];
   for (const entry of resolved) {
-    const handler = compileHandler(entry, inputs.graphBuild, resolved, diagnostics, packageRecognition);
+    const handler = compileHandler(entry, inputs.graphBuild, resolved, diagnostics, packageRecognition, { target: inputs.target });
     if (handler) handlers.push(handler);
   }
   if (diagnostics.length > 0) {

package/src/spine/handler-ir.js

@@ -1,7 +1,8 @@
 'use strict';
+const { CANONICAL_NATIVE_TYPED_KV_BORROW_VERSION } = require('@pulse-compute/wasm-contracts/handler/canonical-native-plan');
 
 const ts = require('typescript');
-const { inspectBoundedPureLoop } = require('./bounded-pure-loop.js');
+const { inspectBoundedPureLoop, inspectBoundedReadLoop } = require('./bounded-pure-loop.js');
 const {
   extractFetchChain,
   extractKvNamespaceDeclaration,
@@ -31,6 +32,7 @@ const HANDLER_IR_OPERATION_KINDS = Object.freeze([
   'source-statement',
   'block',
   'if',
+  'read-loop',
   'fetch-single',
   'fetch-group',
   'provider-variable',
@@ -41,7 +43,11 @@ const HANDLER_IR_OPERATION_KINDS = Object.freeze([
   'opaque-fetch-return'
 ]);
 const HANDLER_IR_EXTENSION_OPERATION_KINDS = Object.freeze([
-  'parallel-group'
+  'parallel-group',
+  'router-body',
+  'router-body-call',
+  'helper-body',
+  'helper-call'
 ]);
 const ROUTER_HANDLER_IR_OPERATION_KINDS = Object.freeze([
   'router-transfer',
@@ -160,6 +166,7 @@ function summarizeHandlerOperation(body) {
       if (entry.elseOperation) countOperation(entry.elseOperation);
     }
     if (entry.kind === 'router-guard') countOperation(entry.body);
+    if (entry.kind === 'read-loop' || entry.kind === 'router-body' || entry.kind === 'helper-body') countOperation(entry.body);
   }
   countOperation(body);
   return Object.freeze({
@@ -186,6 +193,24 @@ function buildPlainHandlerIr(frontend, options = {}) {
   const continuationSites = [];
   const effectCounters = new Map();
   let continuationIndex = 0;
+  const helperBodies = new Map((options.internalGeneratedHandler && options.metadataExtensions?.router?.helpers || []).map(helper => [helper.name, helper]));
+  const pureHelperBounds = new Map();
+  for (const declaration of handler.body.statements || []) {
+    if (!ts.isFunctionDeclaration(declaration) || !helperBodies.get(declaration.name?.text)?.pure) continue;
+    let maxIterationProduct = 1;
+    const visit = node => {
+      if (ts.isForStatement(node)) {
+        const loop = inspectBoundedPureLoop(node, { pureHelper: true });
+        maxIterationProduct = Math.max(maxIterationProduct, loop.maxIterationProduct);
+        return; // The shared inspector includes all nested bounds.
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(declaration.body);
+    pureHelperBounds.set(declaration.name.text, { maxIterationProduct });
+  }
+  const routerBodies = new Map((options.internalGeneratedHandler && options.metadataExtensions?.router?.entries || [])
+    .filter(entry => entry.nativeBody).map(entry => [entry.nativeBody.name, entry]));
   // Offsets belong to a source file. Project-wide contributions can share an
   // offset; only duplicate ranges within the same owning source are invalid.
   const sourceKey = (file, start) => `${String(file).replace(/\\/g, '/')}\u0000${start}`;
@@ -232,6 +257,9 @@ function buildPlainHandlerIr(frontend, options = {}) {
         linkPackageIntrinsicsWithin(call);
         return linked;
       }
+      // Generated Router offsets belong to a different source tree. A miss in
+      // its explicit mapping must not fall back to authored-source offsets.
+      if (options.internalGeneratedHandler) return undefined;
     }
     const effect = packageEffectsBySource.get(callKey(call));
     if (effect) linkPackageIntrinsicsWithin(call);
@@ -254,6 +282,7 @@ function buildPlainHandlerIr(frontend, options = {}) {
         }
         return linked;
       }
+      if (options.internalGeneratedHandler) return undefined;
     }
     const key = callKey(call);
     const intrinsic = packageIntrinsicsBySource.get(key);
@@ -278,6 +307,7 @@ function buildPlainHandlerIr(frontend, options = {}) {
     if (typeof options.packageResultAdapterForCall === 'function') {
       const linked = options.packageResultAdapterForCall(call);
       if (linked) return linked;
+      if (options.internalGeneratedHandler) return undefined;
     }
     return packageResultAdaptersByStart.get(call.getStart(sourceFile));
   }
@@ -316,10 +346,13 @@ function buildPlainHandlerIr(frontend, options = {}) {
   }
 
   function nextProviderEffectSite(providerOperation, grouped = false, groupKey) {
-    const prefix = providerOperation.providerKind === 'kv' ? `kv-${providerOperation.operation}` : providerOperation.providerKind;
+    const valueType = providerOperation.valueTypeNode && require('./pure-helper-source').resolvePureType(
+      { projectModules: new Map() }, { sourceFile, path: sourceFile.fileName, imports: [] }, providerOperation.valueTypeNode);
+    const prefix = providerOperation.providerKind === 'kv'  ? `kv-${providerOperation.operation}` : providerOperation.providerKind;
     const site = Object.freeze({
       id: nextEffectId(prefix),
       kind: providerOperation.kind,
+      ...(valueType ? { borrowedValue: { version: CANONICAL_NATIVE_TYPED_KV_BORROW_VERSION, type: valueType } } : {}),
       providerKind: providerOperation.providerKind,
       operation: providerOperation.operation,
       grouped: Boolean(grouped),
@@ -360,7 +393,8 @@ function buildPlainHandlerIr(frontend, options = {}) {
       payload: Object.freeze({ ...(effect.payload || {}) }),
       result: String(effect.result || 'value'),
       resource: effect.resource || Object.freeze({ kind: 'none' }),
-      position: packageEffectPosition(effect, call)
+      position: packageEffectPosition(effect, call),
+      ...(options.internalGeneratedHandler ? { generatedPosition: positionFor(sourceFile, call) } : {})
     });
     effectSites.push(site);
     return site;
@@ -450,6 +484,10 @@ function buildPlainHandlerIr(frontend, options = {}) {
         continue;
       }
       const provider = extractProviderCall(property.initializer, ctxName, aliases, { unwrap: true });
+      if (provider && provider.providerKind === 'output') {
+        diagnostics.push(diagnostic(sourceFile, property.initializer, 'PULSE_OUTPUT_PARALLEL_FORBIDDEN', 'Output operations cannot be members of ctx.parallel.'));
+        continue;
+      }
       if (provider) {
         members.push(Object.freeze({ key, kind: 'provider', property, operation: provider }));
         continue;
@@ -594,13 +632,37 @@ function buildPlainHandlerIr(frontend, options = {}) {
         index += 1;
         continue;
       }
-      out.push(buildStatement(statement, aliases));
+      out.push(buildStatement(statement, aliases, true));
       index += 1;
     }
     return Object.freeze(out.flat().filter(Boolean));
   }
 
-  function buildStatement(statement, aliases) {
+  let activePureHelper = false;
+  function buildStatement(statement, aliases, fromList = false) {
+    if (ts.isFunctionDeclaration(statement) && helperBodies.has(statement.name?.text)) {
+      const previous = activePureHelper;
+      activePureHelper = helperBodies.get(statement.name.text).pure === true;
+      const body = buildStatement(statement.body, new Map());
+      activePureHelper = previous;
+      return createHandlerOperation('helper-body', { statement, pure: helperBodies.get(statement.name.text).pure === true, body });
+    }
+    if (ts.isVariableStatement(statement) && statement.declarationList.declarations.length === 1) {
+      const declaration = statement.declarationList.declarations[0], call = declaration.initializer;
+      if (call && ts.isCallExpression(call) && ts.isIdentifier(call.expression) && helperBodies.has(call.expression.text) && !helperBodies.get(call.expression.text).pure)
+        return createHandlerOperation('helper-call', { statement, declaration, call });
+    }
+    if (ts.isFunctionDeclaration(statement) && routerBodies.has(statement.name?.text)) {
+      return createHandlerOperation('router-body', { statement, body: buildStatement(statement.body, new Map()) });
+    }
+    if (ts.isReturnStatement(statement) && statement.expression && ts.isCallExpression(statement.expression)
+      && ts.isIdentifier(statement.expression.expression) && routerBodies.has(statement.expression.expression.text)) {
+      return createHandlerOperation('router-body-call', { statement });
+    }
+    if (!fromList && (ts.isExpressionStatement(statement) || ts.isVariableStatement(statement))) {
+      const statements = buildStatementList([statement], aliases);
+      return statements.length === 1 ? statements[0] : createHandlerOperation('block', { statement: ts.factory.createBlock([statement], true), statements });
+    }
     if (ts.isBlock(statement)) return createHandlerOperation('block', { statement, statements: buildStatementList(statement.statements, aliases) });
     if (ts.isIfStatement(statement)) {
       const thenOperation = buildStatement(statement.thenStatement, new Map(aliases));
@@ -637,12 +699,33 @@ function buildPlainHandlerIr(frontend, options = {}) {
       }
     }
     if (ts.isForStatement(statement)) {
-      const loop = inspectBoundedPureLoop(statement, { ctxName });
+      const effectForCall = call => extractProviderCall(call, ctxName, aliases) || packageEffectForCall(call);
+      const pureHelperForCall = call => ts.isIdentifier(call.expression) && pureHelperBounds.get(call.expression.text);
+      const helperForCall = call => ts.isIdentifier(call.expression) && (
+        (helperBodies.get(call.expression.text)?.pure ? undefined : helperBodies.get(call.expression.text))
+        // JavaScript inspection retains ordinary ctx-first source calls. The
+        // original graph executes them; this is not Native callee admission.
+        || options.target === 'javascript' && call.arguments.length > 0 && ts.isIdentifier(call.arguments[0]) && call.arguments[0].text === ctxName);
+      let hasEffect = false;
+      function findEffect(node) {
+        if (ts.isCallExpression(node) && (effectForCall(node) || helperForCall(node))) hasEffect = true;
+        ts.forEachChild(node, findEffect);
+      }
+      findEffect(statement);
+      if (hasEffect) {
+        const loop = inspectBoundedReadLoop(statement, { ctxName, effectForCall, helperForCall, pureHelperForCall, namespaceAliases: [...aliases.keys()] });
+        for (const error of loop.errors) diagnostics.push(diagnostic(sourceFile, error.node, 'PULSE_CANONICAL_READ_LOOP_UNSUPPORTED', error.message));
+        if (loop.errors.length) return createHandlerOperation('source-statement', { statement, role: 'read-loop-rejected' });
+        return createHandlerOperation('read-loop', { statement, counter: loop.name, maxIterations: loop.maxIterations,
+          initializer: statement.initializer, test: statement.condition, increment: statement.incrementor,
+          body: buildStatement(statement.statement, new Map(aliases)) });
+      }
+      const loop = inspectBoundedPureLoop(statement, { ctxName, pureHelper: activePureHelper, pureHelperForCall });
       for (const error of loop.errors) diagnostics.push(diagnostic(sourceFile, error.node, 'PULSE_CANONICAL_PURE_LOOP_UNSUPPORTED', error.message));
       return createHandlerOperation('source-statement', { statement, role: 'bounded-pure-loop' });
     }
     if (ts.isTryStatement(statement) || ts.isForInStatement(statement) || ts.isForOfStatement(statement) || ts.isWhileStatement(statement) || ts.isDoStatement(statement) || ts.isSwitchStatement(statement)) {
-      diagnostics.push(diagnostic(sourceFile, statement, 'PULSE_CANONICAL_CONTROL_FLOW_UNSUPPORTED', 'Canonical lowering supports if/else and literal-capped pure for loops; other loops, switch, and try/catch are reserved.'));
+      diagnostics.push(diagnostic(sourceFile, statement, 'PULSE_CANONICAL_CONTROL_FLOW_UNSUPPORTED', 'Canonical lowering supports if/else, literal-capped pure for loops and bounded sequential read loops; other loops, switch, and try/catch are reserved.'));
     }
     return createHandlerOperation('source-statement', { statement, role: 'preserved-source' });
   }
@@ -688,6 +771,9 @@ function buildPlainHandlerIr(frontend, options = {}) {
     const aliases = new Map(inheritedAliases);
     for (let index = 0; index < statements.length; index += 1) {
       const statement = statements[index];
+      if (ts.isFunctionDeclaration(statement) && (routerBodies.has(statement.name?.text) || helperBodies.has(statement.name?.text))) {
+        scanOriginalStatements(statement.body.statements); continue;
+      }
       const namespace = extractKvNamespaceDeclaration(statement, ctxName);
       if (namespace) { aliases.set(namespace.variableName, namespace.store); continue; }
       if (parallelInvocationStatement(statement, ctxName)) continue;
@@ -700,6 +786,7 @@ function buildPlainHandlerIr(frontend, options = {}) {
       if (ts.isReturnStatement(statement) && packageEffectForCall(unwrapPackageCall(statement.expression))) continue;
       if (ts.isReturnStatement(statement) && extractFetchChain(statement.expression, ctxName)) continue;
       if (ts.isBlock(statement)) { scanOriginalStatements(statement.statements, aliases); continue; }
+      if (ts.isForStatement(statement)) { scanOriginalStatements([statement.statement], aliases); continue; }
       if (ts.isIfStatement(statement)) {
         scanOriginalStatements(ts.isBlock(statement.thenStatement) ? statement.thenStatement.statements : [statement.thenStatement], aliases);
         if (statement.elseStatement) scanOriginalStatements(ts.isBlock(statement.elseStatement) ? statement.elseStatement.statements : [statement.elseStatement], aliases);

package/src/spine/handler-surface-authority.js

@@ -174,6 +174,12 @@ function extractProviderCall(expression, ctxName, kvAliases = new Map(), options
 
   if (receiver && ts.isPropertyAccessExpression(receiver) && isIdentifierNamed(receiver.expression, ctxName, options)) {
     const namespace = receiver.name.text;
+    if (namespace === 'req' && method === 'readTextChunk' && current.arguments.length === 0) {
+      return Object.freeze({ call: current, surfaceId: 'ctx.req.readTextChunk', kind: 'output.readTextChunk', providerKind: 'output', operation: 'readTextChunk', capability: 'request.body.transform', args: Object.freeze([]) });
+    }
+    if (namespace === 'output' && ((method === 'start' && current.arguments.length <= 1) || (method === 'write' && current.arguments.length === 1))) {
+      return Object.freeze({ call: current, surfaceId: `ctx.output.${method}`, kind: `output.${method}`, providerKind: 'output', operation: method, capability: 'response.output', args: Object.freeze([...current.arguments]) });
+    }
     if (namespace === 'time' && method === 'now' && current.arguments.length === 0) {
       return Object.freeze({ call: current, surfaceId: 'ctx.time.now', kind: 'time.now', providerKind: 'time', operation: 'now', capability: 'time.wall-clock', args: Object.freeze([]) });
     }
@@ -200,6 +206,7 @@ function extractProviderCall(expression, ctxName, kvAliases = new Map(), options
         return Object.freeze({
           call: current,
           surfaceId: `ctx.kv.${method}`,
+          valueTypeNode: method === 'getVersioned' && (ts.isCallExpression(receiver) ? receiver : store.parent)?.typeArguments?.length === 1 ? (ts.isCallExpression(receiver) ? receiver : store.parent).typeArguments[0] : undefined,
           kind: `kv.${method}`,
           providerKind: 'kv',
           operation: method,
@@ -278,8 +285,10 @@ function recognizeHandlerSurface(node, options = {}) {
       if (receiver && ts.isPropertyAccessExpression(receiver) && isIdentifierNamed(receiver.expression, ctxName, options)) {
         const namespace = receiver.name.text;
         const method = target.name.text;
+        if (namespace === 'output' && method === 'close' && current.arguments.length === 0) return createRecognition('ctx.output.close', current, { arguments: Object.freeze([]) }, options);
         if (namespace === 'req' && method === 'header') return createRecognition('ctx.req.header', current, { arguments: Object.freeze([...current.arguments]) }, options);
         if (namespace === 'req' && method === 'text') return createRecognition('ctx.req.text', current, { arguments: Object.freeze([...current.arguments]) }, options);
+        if (namespace === 'req' && method === 'body') return createRecognition('ctx.req.body', current, { arguments: Object.freeze([...current.arguments]) }, options);
         if (namespace === 'req' && method === 'json') {
           return createRecognition(current.arguments.length === 0 ? 'ctx.req.json.generic' : 'ctx.req.json.schema', current, { arguments: Object.freeze([...current.arguments]) }, options);
         }

package/src/spine/incoming-body-source.js

@@ -0,0 +1,48 @@
+'use strict';
+const ts = require('typescript');
+const { createCanonicalDiagnostic } = require('./diagnostic-authority.js');
+
+function validateIncomingBodySource(handler, options) {
+  const diagnostics = [];
+  let calls = 0, marker, structuredRead = false;
+  const ctx = options.ctxName || 'ctx';
+  function reject(node, code, message) {
+    diagnostics.push(createCanonicalDiagnostic({ ...options, node, code, message }));
+  }
+  function visit(node) {
+    if (ts.isTypeNode(node)) return;
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)
+      && ['text', 'json'].includes(node.expression.name.text)
+      && ts.isPropertyAccessExpression(node.expression.expression)
+      && node.expression.expression.name.text === 'req'
+      && ts.isIdentifier(node.expression.expression.expression)
+      && node.expression.expression.expression.text === ctx) structuredRead = true;
+    const property = ts.isPropertyAccessExpression(node) && node.name.text === 'body';
+    const computed = ts.isElementAccessExpression(node) && ts.isStringLiteral(node.argumentExpression) && node.argumentExpression.text === 'body';
+    if ((property || computed) && ts.isPropertyAccessExpression(node.expression)
+      && node.expression.name.text === 'req' && ts.isIdentifier(node.expression.expression)
+      && node.expression.expression.text === ctx) {
+      const call = node.parent, field = call?.parent, init = field?.parent, fetch = init?.parent;
+      const named = name => init && ts.isObjectLiteralExpression(init) && init.properties.find(p =>
+        ts.isPropertyAssignment(p) && (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) && p.name.text === name);
+      const method = named('method');
+      calls++;
+      marker = node;
+      if (computed || !call || !ts.isCallExpression(call) || call.expression !== node || call.arguments.length
+        || !field || !ts.isPropertyAssignment(field) || field.initializer !== call || field.name.getText(options.sourceFile) !== 'body'
+        || !init || !ts.isObjectLiteralExpression(init) || init.properties.some(p => ts.isSpreadAssignment(p))
+        || !fetch || !ts.isCallExpression(fetch) || fetch.arguments[1] !== init
+        || !ts.isPropertyAccessExpression(fetch.expression) || !ts.isIdentifier(fetch.expression.expression)
+        || fetch.expression.expression.text !== ctx || fetch.expression.name.text !== 'fetch'
+        || !method || !ts.isStringLiteral(method.initializer) || method.initializer.text !== 'POST'
+        || named('json') || named('schema') || calls > 1) {
+        reject(node, 'PULSE_REQUEST_FORWARDING_FORM_UNSUPPORTED', 'Use one ctx.req.body() inline as the body of a literal outbound POST; markers cannot escape, be awaited, or be duplicated.');
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(handler.body || handler);
+  if (marker && structuredRead) reject(marker, 'PULSE_REQUEST_BODY_OWNERSHIP', 'A forwarding handler cannot also project the incoming body as text or JSON.');
+  return diagnostics;
+}
+module.exports = { validateIncomingBodySource };

package/src/spine/plain-handler-frontend.js

@@ -360,6 +360,10 @@ function analyzeHandler(sourceFile, handler, ctxName, diagnostics, schemaBundleI
           } else if (surface.surfaceId === 'ctx.req.text') {
             capabilities.add('request.text');
             validateDecoderCall(node, 'request-decode');
+          } else if (surface.surfaceId === 'ctx.output.close') {
+            capabilities.add('response.output');
+          } else if (surface.surfaceId === 'ctx.req.body') {
+            capabilities.add('request.body.forward');
           } else if (surface.surfaceId === 'ctx.state.get' || surface.surfaceId === 'ctx.state.set') {
             capabilities.add(surface.surfaceId.slice('ctx.'.length));
           } else if (surface.surfaceId.startsWith('ctx.log.')) {
@@ -508,6 +512,7 @@ function preparePlainHandlerSource(sourceText, options = {}, recognition) {
       role: 'handler',
       strict: options.strict === true,
       frontend: 'canonical-source',
+      internalGeneratedHandler: options.internalGeneratedHandler === true,
       target: options.target,
       handlerAuthoring: options.handlerAuthoring,
       requireAsync: options.requireAsync === true,