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

package/src/canonical-project-compiler.js

@@ -3,6 +3,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const ts = require('typescript');
+const { attachTerminalPackageNative } = require('./spine/terminal-package-native.js');
 const { buildSchemaJsonCompile } = require('@pulse-compute/wasm-schema-json/compiler/schema-json-compile');
 const { buildCanonicalSchemaBundle } = require('@pulse-compute/wasm-schema-json/compiler/canonical-schema-codecs');
 const {
@@ -509,6 +510,23 @@ function sourceDiagnosticForPackageEffect(effect, message, detail = {}) {
   });
 }
 
+// Native must lower every reachable package site. JavaScript executes helpers
+// from the original source graph; only sites owned by normalized Router handlers
+// require a generated counterpart. Keep the full recognition bundle for package
+// inspection, validation and provider requirements on both targets.
+function packageSitesRequiringRouterLink(sites, records, options) {
+  if (options.target !== 'javascript') return sites;
+  return sites.filter((site) => records.some((record) => {
+    const ir = record && record.operationIr;
+    if (!ir || !ir.sourceFile || !ir.handler) return false;
+    const start = Number(site && site.range && site.range.start);
+    const end = Number(site && site.range && site.range.end);
+    return sameModulePath(site && site.loc && site.loc.file, ir.sourceFile.fileName || ir.file, options.rootDir)
+      && Number.isSafeInteger(start) && Number.isSafeInteger(end)
+      && start >= ir.handler.getStart(ir.sourceFile) && end <= ir.handler.getEnd();
+  }));
+}
+
 function routerGeneratedPackageEffectLookup(router, recognition, options = {}) {
   const effects = [...(recognition && recognition.operations || [])].map((operation) => operation.canonicalEffect);
   if (!router || effects.length === 0) return undefined;
@@ -588,12 +606,15 @@ function routerGeneratedPackageEffectLookup(router, recognition, options = {}) {
     }
   }
 
-  if (generatedByStart.size !== effects.length) {
-    const linked = new Set([...generatedByStart.values()]);
-    const missing = effects.filter((effect) => !linked.has(effect));
-    const first = missing[0];
+  // A handler can be registered more than once. Each entry must link all of its
+  // generated calls above, while coverage here is over authored source effects.
+  // Counting generated sites would reject valid one-to-many source mappings.
+  const linked = new Set(generatedByStart.values());
+  const required = packageSitesRequiringRouterLink(effects, records, options);
+  const missing = required.filter((effect) => !linked.has(effect));
+  if (missing.length > 0) {
     throw new CanonicalProjectCompileError(
-      `Generated Router source linked ${generatedByStart.size} of ${effects.length} reachable package effect(s).`,
+      `Generated Router source linked ${linked.size} of ${required.length} required package effect(s).`,
       missing.map((effect) => sourceDiagnosticForPackageEffect(effect, `Reachable package effect ${effect.kind} was not linked into generated Router source.`, {
         contractId: effect.contractId
       })),
@@ -728,11 +749,13 @@ function routerGeneratedPackageIntrinsicLookup(router, recognition, options = {}
     }
   }
 
-  if (generatedByStart.size !== intrinsics.length) {
-    const linked = new Set([...generatedByStart.values()]);
-    const missing = intrinsics.filter((intrinsic) => !linked.has(intrinsic));
+  // Intrinsic calls share the same source-to-registration multiplicity as effects.
+  const linked = new Set(generatedByStart.values());
+  const required = packageSitesRequiringRouterLink(intrinsics, records, options);
+  const missing = required.filter((intrinsic) => !linked.has(intrinsic));
+  if (missing.length > 0) {
     throw new CanonicalProjectCompileError(
-      `Generated Router source linked ${generatedByStart.size} of ${intrinsics.length} reachable package intrinsic(s).`,
+      `Generated Router source linked ${linked.size} of ${required.length} required package intrinsic(s).`,
       missing.map((intrinsic) => sourceDiagnosticForPackageEffect(
         intrinsic,
         `Reachable package intrinsic ${intrinsic.kind} was not linked into generated Router source.`,
@@ -1045,7 +1068,20 @@ function compileCanonicalProjectLegacy(entryFile, options = {}) {
   const terminalPackageApplication = terminalPackageIntrinsicApplication(root, packageOperationRecognition);
 
   let linkedProjectModules;
-  if (multiModule) {
+  let localHelperCall = false;
+  if (root?.kind === 'router') {
+    const visit = node => {
+      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+        if (options.target !== 'javascript') localHelperCall = true;
+        else for (let parent = node.parent; parent && !ts.isFunctionLike(parent); parent = parent.parent) {
+          if (ts.isForStatement(parent)) localHelperCall = true;
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(root.module.sourceFile);
+  }
+  if (multiModule || localHelperCall) {
     try {
       linkedProjectModules = root.kind === 'router'
         ? linkProjectRouterModules(graphBuild, { rootDir, target: options.target })
@@ -1095,13 +1131,13 @@ function compileCanonicalProjectLegacy(entryFile, options = {}) {
       ? terminalPackageApplication.sourceText
       : authoringSourceText;
   const generatedPackageEffectForCall = router
-    ? routerGeneratedPackageEffectLookup(router, packageOperationRecognition, { rootDir })
+    ? routerGeneratedPackageEffectLookup(router, packageOperationRecognition, { rootDir, target: options.target })
     : packageEffectLookup(packageOperationRecognition);
   const generatedPackageResultAdapterForCall = router
     ? routerGeneratedPackageResultAdapterLookup(router, packageOperationRecognition, { rootDir })
     : packageResultAdapterLookup(packageOperationRecognition);
   const generatedPackageIntrinsicForCall = router
-    ? routerGeneratedPackageIntrinsicLookup(router, packageOperationRecognition, { rootDir })
+    ? routerGeneratedPackageIntrinsicLookup(router, packageOperationRecognition, { rootDir, target: options.target })
     : packageIntrinsicLookup(packageOperationRecognition);
   const applicationEnvelope = createApplicationEnvelope(router, options.applicationProjectMetadata);
   const compileOptions = {
@@ -1198,6 +1234,10 @@ function compileCanonicalProjectLegacy(entryFile, options = {}) {
     ].map((file) => path.resolve(file)))])
   });
   attachPackageOperationRecognition(project, packageOperationRecognition);
+  if (terminalPackageApplication) attachTerminalPackageNative(project, {
+    application: terminalPackageApplication, recognition: packageOperationRecognition,
+    managedHandlers, schemaBundle: schema.bundle, cwd: rootDir, workspaceRoot: options.workspaceRoot
+  });
   return project;
 }
 

package/src/execution-plan.js

@@ -301,6 +301,7 @@ function buildExecutionPlan(routerTreeArtifact, dispatchTable, options = {}) {
           pattern: mountPattern,
           scopeId: scopeBefore,
           childRouter: op.router,
+          ...(op.eligibility ? { eligibility: op.eligibility } : {}),
           childStartIndex: null,
           parentContinueIndex: null,
           loc: op.loc

package/src/extractor.js

@@ -421,6 +421,29 @@ function parseTimeoutLiteral(sourceFile, node, diagnostics, phase = 'extract') {
   return config;
 }
 
+function parseMountEligibility(sourceFile, node, diagnostics) {
+  const result = {};
+  let valid = ts.isObjectLiteralExpression(node) && node.properties.length === 2;
+  if (valid) {
+    for (const property of node.properties) {
+      if (!ts.isPropertyAssignment(property) ||
+          !(ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) ||
+          !['state', 'equals'].includes(property.name.text) ||
+          Object.hasOwn(result, property.name.text) || !ts.isStringLiteral(property.initializer)) {
+        valid = false;
+        break;
+      }
+      result[property.name.text] = property.initializer.text;
+    }
+  }
+  if (valid && Object.hasOwn(result, 'state') && Object.hasOwn(result, 'equals')) return result;
+  diagnostics.push(diagnostic(sourceFile, node, DIAGNOSTIC_CODES.UNSUPPORTED_MOUNT_ELIGIBILITY,
+    'Mount eligibility must be an inline { state: "key", equals: "value" } descriptor with exactly two string literals.',
+    'Select a family in earlier middleware. Eligibility cannot call functions, run effects, use getters, spreads, computed keys or dynamic values.',
+    { phase: 'extract' }));
+  return undefined;
+}
+
 function parsePathLiteral(sourceFile, node, diagnostics, usage, phase = 'extract') {
   if (!isStringLiteralLike(node)) {
     diagnostics.push(
@@ -732,6 +755,7 @@ function parseRouterOperation(sourceFile, step, diagnostics, options = {}) {
     return {
       ...base(definition.opKind),
       path: stripScopedWildcard(parsePathLiteral(sourceFile, args[signature.pathArg], diagnostics, 'mount')),
+      ...(signature.eligibilityArg !== undefined ? { eligibility: parseMountEligibility(sourceFile, args[signature.eligibilityArg], diagnostics) } : {}),
       router: ts.isIdentifier(unwrappedRouter.expression) ? unwrappedRouter.expression.text : nodeText(sourceFile, routerArg),
       ...(unwrappedRouter.wrappers.length > 0 ? { routerWrappers: unwrappedRouter.wrappers } : {})
     };
@@ -1625,6 +1649,18 @@ function extractFromSourceFile(sourceFile, options = {}) {
   }
 
   const ir = buildRouterIR(sourceFile, options);
+  // Historical table/harness emitters have no request-state eligibility ABI.
+  // Keep this new authoring form on the canonical Router pipeline only.
+  const selectedMount = ir.routerIR.flatMap(router => router.ops || []).find(op => op.eligibility);
+  if (selectedMount) {
+    throw new ExtractionError([{
+      code: DIAGNOSTIC_CODES.UNSUPPORTED_MOUNT_ELIGIBILITY,
+      severity: 'error', phase: 'extract', loc: selectedMount.loc,
+      message: 'Selected mounts require the canonical Router compiler; historical table/harness emitters do not support eligibility.',
+      hint: 'Use the canonical Pulse project compile/build workflow.'
+    }], { passes, source });
+  }
+
   const indexDiagnostics = ir.diagnostics.filter((diag) => (diag.phase || diag.pass) === 'index');
   const extractDiagnostics = ir.diagnostics.filter((diag) => (diag.phase || diag.pass) !== 'index');
   passes.push(makePass('index', indexDiagnostics.length === 0 ? 'ok' : 'error', {

package/src/javascript-application-plan.js

@@ -38,7 +38,10 @@ function packageStatus(module, graphBuild) {
     .find((entry) => entry.packageName === module.packageName);
   if (product) {
     const target = product.javascriptTarget;
-    if (target && target.status === 'supported') {
+    // Source loadability is separate from selected-provider eligibility. The
+    // target-support owner checks provider-dependent requirements before build.
+    if (target && ['supported', 'provider-dependent'].includes(target.status)
+      && target.realization === 'javascript-package-runtime' && target.entry) {
       return Object.freeze({ status: 'package-runtime', runtimeEntry: target.entry, reasonCode: null });
     }
     return Object.freeze({

package/src/native-result-facts.js

@@ -0,0 +1,50 @@
+'use strict';
+
+// Private planning facts about the existing, normalized S3GetTextResult contract.
+// They never change an effect envelope or validate an arbitrary object by shape.
+function bind(local, effect) {
+  return local.declaration === 'const' && effect.kind === 's3.getText'
+    && effect.declaredResult === 's3-get-text-result'
+    ? { ...local, textResult: { invalidated: false }, textFound: false } : local;
+}
+
+function refine(test, truth, scope) {
+  if (test.kind === 'unary' && test.operator === '!') return refine(test.value, !truth, scope);
+  if (test.kind !== 'binary') return;
+  if (test.operator === (truth ? '&&' : '||')) {
+    refine(test.left, truth, scope);
+    refine(test.right, truth, scope);
+    return;
+  }
+  if (!['===', '!=='].includes(test.operator) || truth !== (test.operator === '===')) return;
+  const read = test.left.kind === 'literal' && test.left.value === 'found' ? test.right
+    : test.right.kind === 'literal' && test.right.value === 'found' ? test.left : undefined;
+  if (read?.kind !== 'property' || read.property !== 'status' || read.object.kind !== 'local') return;
+  const local = scope.get(read.object.name);
+  if (local?.id === read.object.id && local.textResult && !local.textResult.invalidated) {
+    scope.set(local.name, { ...local, textFound: true });
+  }
+}
+
+function propertyKind(object, property, scope) {
+  if (object.kind !== 'local' || property !== 'text') return;
+  const local = scope.get(object.name);
+  if (local?.id === object.id && local.textFound && !local.textResult.invalidated) return 'string';
+}
+
+function join(scope, thenScope, elseScope, thenReturns, elseReturns) {
+  for (const [name, local] of scope) {
+    if (!local.textResult || local.textResult.invalidated) continue;
+    const yes = thenScope.get(name)?.textFound;
+    const no = elseScope.get(name)?.textFound;
+    if (thenReturns && no || elseReturns && yes || yes && no) scope.set(name, { ...local, textFound: true });
+  }
+}
+
+// Property writes may use aliases. Conservatively retire all live result facts,
+// including sibling scopes sharing the record, instead of assuming no aliasing.
+function invalidate(scope) {
+  for (const local of scope.values()) if (local.textResult) local.textResult.invalidated = true;
+}
+
+module.exports = { bind, refine, propertyKind, join, invalidate };

package/src/project/router-module-linker.js

@@ -561,6 +561,63 @@ function linkProjectRouterModules(graphBuild, options = {}) {
     }
   }
 
+  // Only HTTP handler loop calls enter JavaScript's bounded inspection. Never
+  // walk an ordinary dependency function into a new purity requirement.
+  const httpFunctions = new Set();
+  if (options.target === 'javascript') for (const ref of handlerReferences) {
+    if (!['route', 'middleware'].includes(ref.role)) continue;
+    const module = context.projectModules.get(ref.module);
+    if (!module) continue;
+    if (!ref.localName.startsWith('<inline:')) {
+      httpFunctions.add(functionForNamedHandler(module.sourceFile, ref.localName));
+    } else {
+      const visit = node => {
+        if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+          const pos = module.sourceFile.getLineAndCharacterOfPosition(node.getStart(module.sourceFile));
+          if (pos.line + 1 === ref.source.line && pos.character + 1 === ref.source.column) httpFunctions.add(node);
+        }
+        ts.forEachChild(node, visit);
+      };
+      visit(module.sourceFile);
+    }
+  }
+
+  const sourceHelpers = [];
+  const helperCalls = new WeakMap();
+  {
+    const byIdentity = new Map();
+    for (const module of context.projectModules.values()) {
+      function visit(node) {
+        if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+          const call = node;
+          const awaited = ts.isAwaitExpression(node.parent);
+          const target = resolveLocal(context, indexes, module, call.expression.text, [], [], undefined, consumedImports);
+          const fn = target?.module && functionForNamedHandler(target.module.sourceFile, target.localName);
+          // JavaScript keeps ordinary calls in its original graph. Only bounded
+          // loop calls enter the shared pure-helper inspection contract.
+          let inLoop = false;
+          let owner = call.parent;
+          for (; owner && !ts.isFunctionLike(owner); owner = owner.parent) {
+            if (ts.isForStatement(owner)) inLoop = true;
+          }
+          const inspectPureLoopCall = inLoop && httpFunctions.has(owner) && fn && !fn.modifiers?.some(m => m.kind === ts.SyntaxKind.AsyncKeyword);
+          if (fn && (options.target !== 'javascript' || inspectPureLoopCall) && (awaited && fn.parameters.length > 1 || !awaited)) {
+            const identity = `${target.module.path}#${target.localName}`;
+            let helper = byIdentity.get(identity);
+            if (!helper) {
+              helper = { pure: !fn.modifiers?.some(m => m.kind === ts.SyntaxKind.AsyncKeyword), id: `helper:${identity}`, name: `__pulse_helper_${sourceHelpers.length}`, functionNode: fn,
+                resolveType: node => require('../spine/pure-helper-source').resolvePureType(context, target.module, node),
+                sourceFile: target.module.sourceFile, source: { file: target.module.path, name: target.localName } };
+              sourceHelpers.push(helper); byIdentity.set(identity, helper);
+            }
+            helperCalls.set(call, helper);
+          }
+        }
+        ts.forEachChild(node, visit);
+      }
+      visit(module.sourceFile);
+    }
+  }
   const rootGlobalName = routerSymbols.get(`${root.module.path}:${root.localName}`);
   const ordered = orderLinkedRouters(routers, rootGlobalName);
   if (options.target !== 'javascript') validateRuntimeProjectImports(context, consumedImports, diagnostics);
@@ -616,7 +673,14 @@ function linkProjectRouterModules(graphBuild, options = {}) {
     entrySourceFile: entryModule.sourceFile,
     entrySourceText: entryModule.sourceText,
     retainedDeclarations: retained,
+    sourceHelpers,
+    helperForCall: call => helperCalls.get(ts.getOriginalNode(call)),
     functionNodeForHandler,
+    pureTypeForNode(node) {
+      const original = ts.getOriginalNode(node);
+      const module = [...context.projectModules.values()].find(m => m.sourceFile === original.getSourceFile());
+      return module && require('../spine/pure-helper-source').resolvePureType(context, module, original);
+    },
     sourceFileForPath(file) {
       const module = context.projectModules.get(file);
       return module && module.sourceFile;

package/src/project-target-support.js

@@ -92,7 +92,8 @@ function classifyPackage(reachable, planned, product, context, options = {}) {
   }
 
   const targetStatus = product && product.javascriptTarget && product.javascriptTarget.status;
-  if (targetStatus === 'not-realized' || targetStatus === 'provider-dependent') {
+  if (targetStatus === 'not-realized'
+    || (targetStatus === 'provider-dependent' && (!planned || planned.status !== 'package-runtime'))) {
     return Object.freeze({ ...common, status: 'pending', reasonId: 'package-javascript-realization-pending', owner: pendingPackageOwner(product) });
   }
   if (targetStatus === 'unsupported') {
@@ -335,7 +336,14 @@ function buildJavascriptTargetSupportEvidence(project, options = {}, policy = {}
   const capabilities = Object.freeze(compilerCapabilities
     .map((id) => policy.classifyCapability(id, context))
     .sort((a, b) => a.id.localeCompare(b.id)));
-  const providerRequirements = Object.freeze(requirementsFromMetadata(compiled.metadata)
+  const requiredContracts = new Set(packages.filter((entry) => entry.required).map((entry) => entry.contractId));
+  const packageRequirements = (compiled.packageProduct && compiled.packageProduct.contracts || [])
+    .filter((entry) => requiredContracts.has(entry.contractId) && entry.javascriptTarget
+      && entry.javascriptTarget.status === 'provider-dependent')
+    .flatMap((entry) => entry.javascriptTarget.providerRequirements || []);
+  const providerRequirements = Object.freeze([...new Set([
+    ...requirementsFromMetadata(compiled.metadata), ...packageRequirements
+  ])]
     .map((id) => policy.classifyProviderRequirement(id, compilerCapabilities, context))
     .sort((a, b) => a.id.localeCompare(b.id)));
   const status = expectedProjectStatus(application, capabilities, providerRequirements, packages);

package/src/provider-toolchain.js

@@ -139,7 +139,7 @@ function projectRequire(projectRoot) {
 function resolveToolchainEntry(selector, packageName, options = {}) {
   const request = `${packageName}/toolchain`;
   const builtin = BUILTIN_PROVIDER_IDS.includes(selector);
-  const resolver = builtin ? require : projectRequire(options.projectRoot);
+  const resolver = projectRequire(builtin ? options.builtinRoot || options.projectRoot : options.projectRoot);
   try {
     return resolver.resolve(request);
   } catch (cause) {
@@ -263,13 +263,13 @@ function providerTargetAvailability(provider, options = {}) {
 
 function providerIds(options = {}) {
   return Object.freeze(BUILTIN_PROVIDER_IDS.filter((id) => (
-    options.executable !== true || getProviderDriver(id).executable === true
+    options.executable !== true || getProviderDriver(id, options).executable === true
   )));
 }
 
-function providerConfigReferences() {
+function providerConfigReferences(options = {}) {
   return Object.freeze(BUILTIN_PROVIDER_IDS
-    .map((id) => getProviderDriver(id))
+    .map((id) => getProviderDriver(id, options))
     .filter((driver) => driver.configReference)
     .map((driver) => driver.configReference));
 }
@@ -283,7 +283,7 @@ for (const id of BUILTIN_PROVIDER_IDS) {
 }
 Object.freeze(drivers);
 
-module.exports = Object.freeze({
+const api = Object.freeze({
   PROVIDER_PACKAGE_SCOPE,
   PROVIDER_PACKAGE_PREFIX,
   BUILTIN_PROVIDER_IDS,
@@ -297,3 +297,27 @@ module.exports = Object.freeze({
   providerIds,
   providerConfigReferences
 });
+
+// Bind a composition-owned resolution root without process-global registration.
+// The CLI supplies its own package root for bundled IDs; scoped providers still
+// resolve exactly from the project. A compiler consumer supplies only its project.
+function createProviderResolver(defaults = {}) {
+  const options = Object.freeze({ ...defaults });
+  const resolver = { ...api };
+  for (const name of ['resolveProviderToolchain', 'getProviderDriver', 'providerTargetAvailability']) {
+    resolver[name] = (value, input = {}) => api[name](value, { ...input, ...options });
+  }
+  for (const name of ['getProviderTargetDescriptor', 'getProviderTargetSupportDeclaration']) {
+    resolver[name] = (value, target, input = {}) => api[name](value, target, { ...input, ...options });
+  }
+  resolver.providerIds = (input = {}) => providerIds({ ...input, ...options });
+  resolver.providerConfigReferences = () => providerConfigReferences(options);
+  const boundDrivers = {};
+  for (const id of BUILTIN_PROVIDER_IDS) Object.defineProperty(boundDrivers, id, {
+    enumerable: true, get() { return resolver.getProviderDriver(id); }
+  });
+  resolver.drivers = Object.freeze(boundDrivers);
+  return Object.freeze(resolver);
+}
+
+module.exports = Object.freeze({ ...api, createProviderResolver });

package/src/pure-helper-values.js

@@ -0,0 +1,138 @@
+'use strict';
+const { CANONICAL_NATIVE_TYPED_KV_BORROW_VERSION } = require('@pulse-compute/wasm-contracts/handler/canonical-native-plan');
+// These descriptors prove reads of existing handles, never runtime conversions.
+const SCALAR_TYPES = Object.freeze(['string', 'number', 'boolean']);
+const BORROW_LIMITS = Object.freeze({ recordDepth: 2, recordFields: 32 });
+const FORBIDDEN_FIELDS = Object.freeze(['__proto__', 'constructor', 'prototype']);
+const scalar = type => SCALAR_TYPES.includes(type);
+const kind = type => typeof type === 'string' ? type : type?.kind === 'record' ? 'object' : type?.kind === 'number-array' ? 'array' : 'unknown';
+function validType(type, depth = 0) {
+  if (scalar(type)) return true;
+  if (!type || typeof type !== 'object' || depth > BORROW_LIMITS.recordDepth) return false;
+  if (type.kind === 'number-array') return Object.keys(type).length === 1;
+  return type.kind === 'record' && depth < BORROW_LIMITS.recordDepth && Object.keys(type).sort().join() === 'fields,kind'
+    && Array.isArray(type.fields) && type.fields.length > 0 && type.fields.length <= BORROW_LIMITS.recordFields
+    && new Set(type.fields.map(f => f?.name)).size === type.fields.length
+    && type.fields.every(f => f && Object.keys(f).sort().join() === 'name,type' && typeof f.name === 'string'
+      && /^[A-Za-z_$][\w$]*$/.test(f.name) && !FORBIDDEN_FIELDS.includes(f.name) && validType(f.type, depth + 1));
+}
+function same(a, b) {
+  if (a === undefined && b === undefined) return true;
+  if (typeof a === 'string' || typeof b === 'string') return a === b;
+  if (!a || !b || a.kind !== b.kind) return false;
+  return a.kind === 'number-array' || Array.isArray(a.fields) && Array.isArray(b.fields) && a.fields.length === b.fields.length && a.fields.every(f => same(f.type, b.fields.find(g => g.name === f.name)?.type));
+}
+function member(type, property) {
+  if ((type === 'string' || type?.kind === 'number-array') && property === 'length') return 'number';
+  return type?.kind === 'record' && Array.isArray(type.fields) ? type.fields.find(f => f.name === property)?.type : undefined;
+}
+// Result facts are not admission. These two existing inference boundaries have
+// different evidence: plan kinds describe dynamic values; readType reconstructs
+// proven structural types. Preserve their differences until policy is changed
+// deliberately. Independent helper validation still owns operand/admission proof.
+const BINARY_RULES = Object.freeze({
+  '===': 'comparison', '!==': 'comparison', '==': 'comparison', '!=': 'comparison',
+  '<': 'comparison', '<=': 'comparison', '>': 'comparison', '>=': 'comparison',
+  '&&': 'logical', '||': 'logical', '??': 'logical',
+  '+': 'numeric', '-': 'numeric', '*': 'numeric', '/': 'numeric', '%': 'numeric',
+  '**': 'numeric', '&': 'numeric', '|': 'numeric', '^': 'numeric',
+  '<<': 'numeric', '>>': 'numeric', '>>>': 'numeric'
+});
+const UNARY_TYPES = Object.freeze({ '!': 'boolean', typeof: 'string', '+': 'number', '-': 'number', '~': 'number' });
+function binaryRule(operator) {
+  return Object.hasOwn(BINARY_RULES, operator) ? BINARY_RULES[operator] : undefined;
+}
+function binaryResult(operator, a, b, planKind, optionalStringDefault = true) {
+  const rule = binaryRule(operator);
+  const unknown = planKind ? 'unknown' : undefined;
+  if (rule === 'logical') {
+    if (planKind ? a === b : same(a, b)) return a;
+    if (optionalStringDefault && ['||', '??'].includes(operator) && (planKind
+      ? a === 'string-or-undefined' && b === 'string'
+        || operator === '??' && a === 'string' && b === 'string-or-undefined'
+      : a === 'string-or-undefined' && b === 'string')) return 'string';
+    return unknown;
+  }
+  if (rule === 'comparison' || planKind && operator === 'in') return 'boolean';
+  if (!planKind && (!scalar(a) || !scalar(b))) return undefined;
+  if (operator === '+' && (a === 'string' || b === 'string')) return 'string';
+  // The proven reader historically reports numeric result facts for scalar
+  // operands, even before operator admission. It must not become a validator.
+  return !planKind || rule === 'numeric' ? 'number' : unknown;
+}
+function binaryKind(operator, leftKind, rightKind, optionalStringDefault = true) {
+  return binaryResult(operator, leftKind, rightKind, true, optionalStringDefault);
+}
+function unaryType(operator) {
+  return Object.hasOwn(UNARY_TYPES, operator) ? UNARY_TYPES[operator] : undefined;
+}
+function unaryKind(operator) { return unaryType(operator) || 'number'; }
+function element(type, indexType, literalIndex, optionalStringIndex = false) {
+  if (indexType === 'number') {
+    if (type === 'string') return optionalStringIndex ? 'string-or-undefined' : 'string';
+    if (type?.kind === 'number-array') return 'number';
+  }
+  if (typeof literalIndex === 'string') return member(type, literalIndex);
+}
+// Projection types are derived from declarations, literals and schema boundaries.
+// They describe existing dynamic handles; they do not validate external data.
+function schemaType(node) {
+  if (['string','boolean'].includes(node?.kind)) return node.kind;
+  if (['i32','u32','f64'].includes(node?.kind)) return 'number';
+  if (node?.kind === 'array' && schemaType(node.element) === 'number') return {kind:'number-array'};
+  if (node?.kind === 'object') return {kind:'record', ...(node.open || node.additionalProperties ? {open:true} : {}), fields: node.fields.map(f => ({name:f.name,
+    type: f.required ? schemaType(f.value) : schemaType(f.value) === 'string' ? 'string-or-undefined' : undefined}))};
+}
+function schemaRead(id, registry) {
+  return id?.kind === 'literal' && typeof id.value === 'string' ? schemaType(registry?.schemas?.find(s => s.id === id.value)?.root) : undefined;
+}
+function effectType(effect, registry) {
+  if (effect.kind === 'kv.getVersioned' && effect.borrowedValue?.version === CANONICAL_NATIVE_TYPED_KV_BORROW_VERSION
+    && validType(effect.borrowedValue.type)) return {kind:'record', fields:[
+      {name:'status',type:'string'}, {name:'value',type:effect.borrowedValue.type}]};
+  if (effect.result?.decoder?.kind === 'json') return schemaRead(effect.result.decoder.arguments?.[0], registry);
+}
+function readType(e, types, optionalStringIndex = false) {
+  if (!e) return;
+  const read = value => readType(value, types, optionalStringIndex);
+  if (e.kind === 'local') return types?.get(e.id);
+  if (e.kind === 'literal' && scalar(typeof e.value)) return typeof e.value;
+  if (e.kind === 'property') return member(read(e.object), e.property);
+  if (e.kind === 'element') {
+    const type = element(read(e.object), read(e.index), e.index?.kind === 'literal' ? e.index.value : undefined, optionalStringIndex);
+    if (type) return type;
+  }
+  if (e.kind === 'intrinsic' && e.name === 'request.text' && Array.isArray(e.arguments) && e.arguments.length === 0) return 'string';
+  if (e.kind === 'intrinsic' && e.name === 'state.get' && Array.isArray(e.arguments)
+    && e.arguments.length === 1 && read(e.arguments[0]) === 'string') return 'string-or-undefined';
+  if (e.kind === 'intrinsic' && ['request.json','schema.decode.text'].includes(e.name)) return schemaRead(e.arguments?.[e.name === 'request.json' ? 0 : 1], types?.schemas);
+  if (e.kind === 'array' && e.items.every(item => read(item) === 'number')) return {kind:'number-array'};
+  if (e.kind === 'object') {
+    if (!e.entries.some(entry => entry.kind === 'spread')) {
+      if (e.entries.every(f => f.kind === 'property' && f.key?.kind === 'literal' && typeof f.key.value === 'string')
+        && new Set(e.entries.map(f => f.key.value)).size === e.entries.length)
+        return {kind:'record',fields:e.entries.map(f=>({name:f.key.value,type:read(f.value)}))};
+      return;
+    }
+    const fields = new Map(), explicit = new Set();
+    for (const entry of e.entries) {
+      if (entry.kind === 'spread') {
+        const spread = read(entry.value);
+        if (spread?.kind !== 'record' || !validType(spread)) return;
+        for (const field of spread.fields) fields.set(field.name, field.type);
+      } else if (entry.kind === 'property' && entry.key?.kind === 'literal' && typeof entry.key.value === 'string'
+        && !explicit.has(entry.key.value)) {
+        explicit.add(entry.key.value);
+        fields.set(entry.key.value, read(entry.value));
+      } else return;
+    }
+    const result = {kind:'record', fields:[...fields].map(([name,type]) => ({name,type}))};
+    if (validType(result)) return result;
+  }
+  if (e.kind === 'conditional') { const a=read(e.whenTrue),b=read(e.whenFalse); if(same(a,b))return a; }
+  if (e.kind === 'binary') return binaryResult(e.operator, read(e.left), read(e.right), false);
+  if (e.kind === 'unary') return unaryType(e.operator);
+  if (e.kind === 'template') return 'string';
+}
+module.exports = { SCALAR_TYPES, BORROW_LIMITS, FORBIDDEN_FIELDS, scalar, kind, validType, same, member,
+  binaryRule, binaryKind, unaryKind, element, readType, schemaType, schemaRead, effectType };