@pulse-compute/wasm-compiler 1.0.0-beta.4 → 1.0.0-beta.6

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

@@ -0,0 +1,210 @@
+'use strict';
+
+const ts = require('typescript');
+function loadContract() {
+  try { return require('@pulse-compute/wasm-contracts/handler/canonical-native-plan'); }
+  catch (error) {
+    if (error && ['MODULE_NOT_FOUND', 'ERR_PACKAGE_PATH_NOT_EXPORTED'].includes(error.code)) return require('../../../contracts/src/handler/canonical-native-plan.js');
+    throw error;
+  }
+}
+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;
+  return node;
+}
+function number(node, expected) {
+  node = unwrap(node);
+  return node && ts.isNumericLiteral(node) && Number(node.text) === expected;
+}
+function named(node, name) { node = unwrap(node); return node && ts.isIdentifier(node) && node.text === name; }
+function firstConjunct(node) {
+  node = unwrap(node);
+  while (node && ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken) node = unwrap(node.left);
+  return node;
+}
+
+// Shared admission for original-source JavaScript and generated Native plans.
+// The literal bound is the first conjunct, so the terminating test cannot run
+// 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, 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;
+    }
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) || ts.isNumericLiteral(node)
+      || [ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword, ts.SyntaxKind.NullKeyword].includes(node.kind)) return;
+    if (ts.isPropertyAccessExpression(node)) {
+      if (node.questionDotToken) fail(node, 'Optional access is outside the bounded pure loop subset.');
+      expression(node.expression, counters, mutation); return;
+    }
+    if (ts.isElementAccessExpression(node)) {
+      if (node.questionDotToken) fail(node, 'Optional access is outside the bounded pure loop subset.');
+      expression(node.expression, counters, mutation); expression(node.argumentExpression, counters, mutation); return;
+    }
+    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;
+      }
+      expression(target.expression, counters, false); return;
+    }
+    if (ts.isBinaryExpression(node)) {
+      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, ...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, ...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)) {
+      expression(node.condition, counters, mutation); expression(node.whenTrue, counters, mutation); expression(node.whenFalse, counters, mutation); return;
+    }
+    if (ts.isTypeOfExpression(node) || ts.isVoidExpression(node)) { expression(node.expression, counters, mutation); return; }
+    if (ts.isArrayLiteralExpression(node)) {
+      for (const item of node.elements) expression(ts.isSpreadElement(item) ? item.expression : item, counters, mutation);
+      return;
+    }
+    if (ts.isObjectLiteralExpression(node)) {
+      for (const item of node.properties) {
+        if (ts.isSpreadAssignment(item)) expression(item.expression, counters, mutation);
+        else if (ts.isShorthandPropertyAssignment(item)) expression(item.name, counters, mutation);
+        else if (ts.isPropertyAssignment(item)) {
+          if (ts.isComputedPropertyName(item.name)) expression(item.name.expression, counters, mutation);
+          expression(item.initializer, counters, mutation);
+        } else fail(item, 'Methods and accessors are outside pure loop values.');
+      }
+      return;
+    }
+    if (ts.isTemplateExpression(node)) { for (const span of node.templateSpans) expression(span.expression, counters, mutation); return; }
+    fail(node, `${ts.SyntaxKind[node.kind]} is outside bounded pure loop expressions.`);
+  }
+  function body(node, counters, product) {
+    if (ts.isBlock(node)) { for (const child of node.statements) body(child, counters, product); return; }
+    if (ts.isForStatement(node)) { loop(node, counters, product); return; }
+    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) || 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;
+    }
+    if (ts.isIfStatement(node)) {
+      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, 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;
+    }
+    if (ts.isEmptyStatement(node)) return;
+    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)) {
+      fail(node, 'A bounded pure loop starts with for (let index = 0; ...; index++).'); return;
+    }
+    const name = declaration.name.text;
+    const bound = firstConjunct(node.condition);
+    if (!bound || !ts.isBinaryExpression(bound) || !named(bound.left, name) || bound.operatorToken.kind !== ts.SyntaxKind.LessThanToken || !ts.isNumericLiteral(unwrap(bound.right))) {
+      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 > (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);
+    if (!increment || !((ts.isPostfixUnaryExpression(increment) || ts.isPrefixUnaryExpression(increment)) && increment.operator === ts.SyntaxKind.PlusPlusToken && named(increment.operand, name))
+      && !(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) || 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);
+    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);
+  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, 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.js

@@ -1,6 +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, inspectBoundedReadLoop } = require('./bounded-pure-loop.js');
 const {
   extractFetchChain,
   extractKvNamespaceDeclaration,
@@ -30,6 +32,7 @@ const HANDLER_IR_OPERATION_KINDS = Object.freeze([
   'source-statement',
   'block',
   'if',
+  'read-loop',
   'fetch-single',
   'fetch-group',
   'provider-variable',
@@ -40,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',
@@ -159,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({
@@ -185,25 +193,53 @@ function buildPlainHandlerIr(frontend, options = {}) {
   const continuationSites = [];
   const effectCounters = new Map();
   let continuationIndex = 0;
-  const packageEffectsByStart = new Map();
+  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}`;
+  const inputKey = (input, start) => sourceKey(input.loc && input.loc.file || sourceFile.fileName, start);
+  const callKey = (call) => {
+    const owner = call.getSourceFile() || sourceFile;
+    return sourceKey(owner.fileName, call.getStart(owner));
+  };
+  const packageEffectsBySource = new Map();
   for (const effectInput of options.packageEffects || []) {
     if (!effectInput || effectInput.version !== canonicalRuntimeContract.CANONICAL_PACKAGE_EFFECT_VERSION || !effectInput.range) continue;
     const start = Number(effectInput.range.start);
-    if (!Number.isSafeInteger(start) || packageEffectsByStart.has(start)) {
+    const key = inputKey(effectInput, start);
+    if (!Number.isSafeInteger(start) || packageEffectsBySource.has(key)) {
       diagnostics.push(diagnostic(sourceFile, handler, 'PULSE_CANONICAL_PACKAGE_EFFECT_RANGE_INVALID', 'Package-owned canonical effects require unique source ranges.', { effect: effectInput }));
       continue;
     }
-    packageEffectsByStart.set(start, effectInput);
+    packageEffectsBySource.set(key, effectInput);
   }
-  const packageIntrinsicsByStart = new Map();
-  const linkedPackageIntrinsicsByStart = new Map();
+  const packageIntrinsicsBySource = new Map();
+  const linkedPackageIntrinsicsBySource = new Map();
   for (const intrinsicInput of options.packageIntrinsics || []) {
     const start = Number(intrinsicInput && intrinsicInput.range && intrinsicInput.range.start);
-    if (!Number.isSafeInteger(start) || packageIntrinsicsByStart.has(start)) {
+    const key = intrinsicInput && inputKey(intrinsicInput, start);
+    if (!Number.isSafeInteger(start) || packageIntrinsicsBySource.has(key)) {
       diagnostics.push(diagnostic(sourceFile, handler, 'PULSE_CANONICAL_PACKAGE_INTRINSIC_RANGE_INVALID', 'Package-owned intrinsics require unique source ranges.', { intrinsic: intrinsicInput }));
       continue;
     }
-    packageIntrinsicsByStart.set(start, intrinsicInput);
+    packageIntrinsicsBySource.set(key, intrinsicInput);
   }
 
   function unwrapPackageCall(expression) {
@@ -221,8 +257,11 @@ 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 = packageEffectsByStart.get(call.getStart(sourceFile));
+    const effect = packageEffectsBySource.get(callKey(call));
     if (effect) linkPackageIntrinsicsWithin(call);
     return effect;
   }
@@ -232,19 +271,22 @@ function buildPlainHandlerIr(frontend, options = {}) {
     if (typeof options.packageIntrinsicForCall === 'function') {
       const linked = options.packageIntrinsicForCall(call);
       if (linked) {
-        const start = call.getStart(sourceFile);
-        if (!linkedPackageIntrinsicsByStart.has(start)) {
-          linkedPackageIntrinsicsByStart.set(start, Object.freeze({
+        const owner = call.getSourceFile() || sourceFile;
+        const start = call.getStart(owner);
+        const key = callKey(call);
+        if (!linkedPackageIntrinsicsBySource.has(key)) {
+          linkedPackageIntrinsicsBySource.set(key, Object.freeze({
             ...linked,
             range: Object.freeze({ start, end: call.getEnd() })
           }));
         }
         return linked;
       }
+      if (options.internalGeneratedHandler) return undefined;
     }
-    const start = call.getStart(sourceFile);
-    const intrinsic = packageIntrinsicsByStart.get(start);
-    if (intrinsic && !linkedPackageIntrinsicsByStart.has(start)) linkedPackageIntrinsicsByStart.set(start, intrinsic);
+    const key = callKey(call);
+    const intrinsic = packageIntrinsicsBySource.get(key);
+    if (intrinsic && !linkedPackageIntrinsicsBySource.has(key)) linkedPackageIntrinsicsBySource.set(key, intrinsic);
     return intrinsic;
   }
 
@@ -265,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));
   }
@@ -303,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),
@@ -347,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;
@@ -437,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;
@@ -581,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));
@@ -623,8 +698,34 @@ function buildPlainHandlerIr(frontend, options = {}) {
         return createHandlerOperation('opaque-fetch-return', { statement, chain, site, continuation });
       }
     }
-    if (ts.isTryStatement(statement) || ts.isForStatement(statement) || ts.isForOfStatement(statement) || ts.isWhileStatement(statement) || ts.isDoStatement(statement) || ts.isSwitchStatement(statement)) {
-      diagnostics.push(diagnostic(sourceFile, statement, 'PULSE_CANONICAL_CONTROL_FLOW_UNSUPPORTED', 'The current canonical lowering supports straight-line code and if/else branching; loops, switch, and try/catch are reserved.'));
+    if (ts.isForStatement(statement)) {
+      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, 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' });
   }
@@ -670,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;
@@ -682,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);
@@ -709,11 +814,9 @@ function buildPlainHandlerIr(frontend, options = {}) {
     effectSites: Object.freeze(effectSites),
     continuationSites: Object.freeze(continuationSites),
     packageEffects: Object.freeze([...(options.packageEffects || [])]),
-    packageIntrinsics: Object.freeze(
-      typeof options.packageIntrinsicForCall === 'function'
-        ? [...linkedPackageIntrinsicsByStart.values()]
-        : [...(options.packageIntrinsics || [])]
-    ),
+    // The emitter consumes this handler's linked ranges, not the project-wide
+    // recognition index. Keep original loc metadata when rebasing a range.
+    packageIntrinsics: Object.freeze([...linkedPackageIntrinsicsBySource.values()]),
     packageResultAdapters: Object.freeze([...(options.packageResultAdapters || [])]),
     summary: Object.freeze({
       operationCount: operationSummary.operationCount,

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

@@ -174,6 +174,15 @@ 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([]) });
+    }
     if (namespace === 'config' && method === 'get' && current.arguments.length === 1) {
       return Object.freeze({ call: current, surfaceId: 'ctx.config.get', kind: 'config.get', providerKind: 'config', operation: 'get', capability: 'config.get', resource: current.arguments[0], name: current.arguments[0], args: Object.freeze([...current.arguments]) });
     }
@@ -197,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,
@@ -265,6 +275,7 @@ function recognizeHandlerSurface(node, options = {}) {
           param: 'ctx.param',
           json: 'ctx.json',
           encodeJson: 'ctx.encodeJson',
+          decodeJson: 'ctx.decodeJson',
           text: 'ctx.text',
           response: 'ctx.response'
         });
@@ -274,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);
         }