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

package/src/report-handler-topology.js

@@ -0,0 +1,104 @@
+'use strict';
+
+const { createHash } = require('node:crypto');
+const { topologyForCanonicalRouterOutput, surfaceFactsForCanonicalRouterOutput, handlerIrsForCanonicalRouterOutput } = require('./spine/canonical-router');
+const { sourceModelForRouterRecognition, capabilityForHandlerSurface, staticString } = require('./spine/handler-surface-authority');
+const { projectRouterControl } = require('./report-router-control');
+const { bindingOwnership } = require('./spine/binding-ownership');
+const unavailable = () => ({ state: 'unavailable', value: null, reason: 'not-recorded' });
+const available = value => ({ state: 'available', value, reason: null });
+const freeze = value => { if (value && typeof value === 'object') { Object.values(value).forEach(freeze); Object.freeze(value); } return value; };
+
+// Post-emission observation only. Read retained compiler objects, never reparse
+// emitted source or read files. Nothing here enters executable metadata/hashes.
+function collectHandlerTopology(compiled) {
+  const topology = topologyForCanonicalRouterOutput(compiled.router);
+  if (!topology) return undefined;
+  // A newer/other topology must not turn successful compilation into a report
+  // failure, nor acquire a fabricated role. Its analytics remain unavailable.
+  if (topology.entries.some(({ entry }) => !['route', 'use', 'mount', 'error', 'event', 'fallback'].includes(entry.kind))) return undefined;
+  const linked = topology.options.linkedProjectModules;
+  const files = new Map();
+  const sourceFile = file => linked?.sourceFileForPath(file)
+    || (topology.sourceFile.fileName === file ? topology.sourceFile : undefined);
+  function span(file, start, end) {
+    const source = sourceFile(file);
+    if (!source || !Number.isSafeInteger(start) || !Number.isSafeInteger(end)
+      || start < 0 || end <= start || end > source.text.length) return unavailable();
+    if (!files.has(file)) files.set(file, createHash('sha256').update(source.text).digest('hex'));
+    const point = offset => { const p = source.getLineAndCharacterOfPosition(offset);
+      return { offset, line: p.line + 1, column: p.character + 1 }; };
+    return available({ file, sha256: files.get(file), start: point(start), end: point(end) });
+  }
+  const location = loc => span(loc?.file, loc?.start?.offset, loc?.end?.offset);
+  const modules = new Map((compiled.reachableGraph?.modules || []).filter(m => m.path).map(m => [m.path, m]));
+  function packageFor(file) {
+    const module = modules.get(file);
+    if (!module) return unavailable();
+    return module.packageName && module.packageVersion
+      ? available({ name: module.packageName, version: module.packageVersion, sourceIdentity: module.path })
+      : { state: 'not-applicable', value: null, reason: 'not-applicable' };
+  }
+  const handlers = topology.handlerTable.handlers.map(handler => ({
+    id: handler.id, kind: 'handler', name: handler.localName || handler.exportName || handler.inlineName || null,
+    source: location(handler.loc), package: packageFor(handler.file),
+    evidence: [{ basis: 'handler-table', producer: 'canonical-router-handler-table' }]
+  }));
+  for (const helper of linked?.sourceHelpers || []) {
+    const file = helper.source.file, node = helper.functionNode, source = sourceFile(file);
+    handlers.push({ id: helper.id, kind: 'helper', name: helper.source.name || null,
+      source: source && node ? span(file, node.getStart(source), node.end) : unavailable(), package: packageFor(file),
+      evidence: [{ basis: 'handler-table', producer: 'canonical-router-linked-helper' }] });
+  }
+  const http = new Map(topology.entries.filter(d => d.entry.kind !== 'event').map(d => [d.entry.index, d.entry.stableId]));
+  const controls = new Map((handlerIrsForCanonicalRouterOutput(compiled.router) || []).map(row => [row.entryStableId, row.operationIr]));
+  const mounts = [];
+  const registrations = topology.entries.map(({ entry, rawEntry }) => {
+    // The compiler's child/parent-return interval identifies this particular
+    // mount expansion, even when router definition paths are identical.
+    while (mounts.length && entry.index >= mounts.at(-1).end) mounts.pop();
+    const registration = {
+      id: entry.stableId, handlerId: entry.handlerId || null,
+      kind: entry.kind === 'use' ? 'middleware' : entry.kind,
+      authored: Boolean(rawEntry.loc) && entry.kind !== 'fallback',
+      source: location(rawEntry.loc), routerId: entry.router, routerPath: [...entry.routerPath],
+      mountPath: entry.kind === 'event' ? [] : mounts.map(m => m.id), order: entry.index,
+      match: available({ method: entry.method || null, path: entry.path ?? null, eventType: entry.eventType || null }),
+      control: projectRouterControl(entry, rawEntry, controls.get(entry.stableId)),
+      flow: { next: http.get(entry.nextIndex) || null, child: http.get(entry.childStartIndex) || null,
+        parentContinue: http.get(entry.parentContinueIndex) || null },
+      evidence: [{ basis: 'router-topology', producer: 'canonical-router-execution-topology' }]
+    };
+    if (entry.kind === 'mount' && entry.childStartIndex > entry.index && entry.parentContinueIndex >= entry.childStartIndex) {
+      mounts.push({ id: entry.stableId, end: entry.parentContinueIndex });
+    }
+    return registration;
+  });
+  const model = sourceModelForRouterRecognition(surfaceFactsForCanonicalRouterOutput(compiled.router)?.recognition);
+  const nodeSource = row => span(row.sourceFile.fileName, row.node.getStart(row.sourceFile), row.node.end);
+  const useSites = model?.authoredSites.map(row => {
+    const recognized = row.recognized, capability = capabilityForHandlerSurface(recognized);
+    const provider = recognized.detail?.provider, effect = recognized.detail?.packageEffect;
+    const name = provider ? staticString(provider.resource, { unwrap: true }) : effect?.resource?.kind === 'literal' ? effect.resource.value : undefined;
+    const binding = bindingOwnership(provider?.providerKind || effect?.providerKind, name,
+      Boolean(provider?.resource) && name === undefined || effect?.resource?.kind === 'dynamic');
+    return { ownerId: row.ownerId, surfaceId: recognized.surfaceId, operation: recognized.canonicalOperation,
+      capability: capability ? available(capability) : unavailable(),
+      binding: binding || { state: 'not-applicable', kind: null, canonicalId: null },
+      source: nodeSource(row), evidence: [{ basis: 'authored-recognition', producer: 'canonical-handler-surface-authority' }] };
+  });
+  const calls = new Map();
+  let helperCallsComplete = true;
+  for (const row of model?.validatedCalls || []) {
+    const source = nodeSource(row);
+    // No lowered offsets, call order or guessed identities stand in for source.
+    if (source.state !== 'available') { helperCallsComplete = false; continue; }
+    const key = JSON.stringify([row.callerId, row.calleeId, source.value.file, source.value.start.offset, source.value.end.offset]);
+    if (!calls.has(key)) calls.set(key, { canonicalId: null, callerId: row.callerId, calleeId: row.calleeId,
+      registrationIds: [], source, evidence: [{ basis: 'validated-helper-call', producer: 'canonical-router-handler-validation' }] });
+    calls.get(key).registrationIds.push(row.registrationId);
+  }
+  return freeze({ version: 'pulse.compiler-report-topology.v1', handlers, registrations,
+    ...(model ? { useSites, helperCalls: [...calls.values()], helperCallsComplete } : {}) });
+}
+module.exports = { collectHandlerTopology };

package/src/report-reference-provenance.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const { bindingOwnership } = require('./spine/binding-ownership');
+const { packageOperationRecognitionForCompiled } = require('./spine/package-operation-seam');
+
+// Build-time projection of compiler facts. This record never enters the Native
+// plan, executable source, recipe or provider configuration. Unknown expressions
+// are not evaluated or serialized, and reference resolution is not host binding.
+function collectCanonicalReportReferences(compiled, plan) {
+  const raw = compiled.metadata.applicationEntries || plan.routing?.entries || [];
+  const entries = new Set(raw.map(row => row.stableId));
+  if (!raw.length) entries.add('default');
+  const helpers = new Map(), rows = new Map();
+  const schemas = new Set((compiled.schema?.registry || plan.schemas?.registry)?.schemas?.map(row => row.id) || []);
+  const unique = values => [...new Set(values)].sort();
+  function calls(value, stageConsumers) {
+    if (!value || typeof value !== 'object') return;
+    if (value.kind === 'helper-call' || value.kind === 'pure-helper-call') {
+      if (!helpers.has(value.helperId)) helpers.set(value.helperId, new Set());
+      for (const entry of stageConsumers || [value.callerEntryId]) helpers.get(value.helperId).add(entry);
+    }
+    for (const child of Object.values(value)) if (child && typeof child === 'object') {
+      if (Array.isArray(child)) child.forEach(row => calls(row, stageConsumers)); else calls(child, stageConsumers);
+    }
+  }
+  for (const body of [plan.entry.body, ...(plan.handlers || []).map(row => row.body)]) calls(body);
+  for (const stage of plan.stages || []) calls(stage.body, stage.registrations.map(row => row.entryId));
+  // Package provenance comes from the trusted recognition bundle, never a file
+  // name, schema name or usage-string guess. Keep it outside executable metadata.
+  const packageSources = new Map();
+  const referenceKey = row => JSON.stringify([row.id, row.usage, row.capability,
+    row.file || compiled.metadata.file || '', row.position?.offset]);
+  for (const source of packageOperationRecognitionForCompiled(compiled)?.publicExtensions?.plans || []) {
+    for (const reference of source.schemaReferences || []) {
+      const key = referenceKey(reference);
+      if (!packageSources.has(key)) packageSources.set(key, new Set());
+      packageSources.get(key).add(source.package);
+    }
+  }
+  function owners(effect) {
+    if (effect.helperId) return [...(helpers.get(effect.helperId) || [])];
+    const entry = effect.applicationEntryStableId || effect.routerEntryStableId;
+    return entry ? [entry] : raw.length ? [] : ['default'];
+  }
+  function add(kind, canonicalId, bindingKind, consumers, observationId, detail = {}) {
+    const state = canonicalId === null ? detail.dynamic ? 'dynamic' : 'unknown' : detail.unresolved ? 'unknown' : 'resolved';
+    const key = JSON.stringify([kind, bindingKind, state, state === 'resolved' ? canonicalId : observationId]);
+    let row = rows.get(key);
+    if (!row) {
+      row = { kind, canonicalId, bindingKind, state, observationId: state === 'resolved' ? null : observationId,
+        entryIds: [], entriesComplete: true, ...(detail.resource ? { resource: detail.resource } : {}) };
+      rows.set(key, row);
+    }
+    row.entryIds.push(...consumers.filter(id => entries.has(id)));
+    row.entriesComplete &&= consumers.length > 0 && consumers.every(id => entries.has(id));
+    if (detail.externalPackages?.length) row.externalPackages = unique([...(row.externalPackages || []), ...detail.externalPackages]);
+  }
+  const literal = value => value?.kind === 'literal' && typeof value.value === 'string' ? value.value : null;
+  const input = (effect, name) => effect.inputs?.find(row => row.name === name)?.value;
+  const field = (object, name) => object?.kind === 'object'
+    ? object.entries?.find(row => row.key?.kind === 'literal' && row.key.value === name)?.value : null;
+  for (const effect of plan.effects || []) {
+    const consumers = owners(effect), kind = effect.providerKind;
+    if (['config', 'secret', 'kv', 's3'].includes(kind)) {
+      const expression = kind === 's3' ? field(input(effect, 'resource'), 'binding')
+        : input(effect, kind === 'kv' ? 'store' : 'name');
+      const resolved = literal(expression);
+      const name = resolved ?? (effect.resource?.kind === 'literal' && typeof effect.resource.value === 'string' ? effect.resource.value : null);
+      const binding = bindingOwnership(kind, name, effect.resource?.kind === 'dynamic' || Boolean(expression && expression.kind !== 'literal'));
+      add('binding', binding.canonicalId, binding.kind, consumers, effect.id, { dynamic: binding.state === 'dynamic' });
+    }
+    if (effect.kind === 'event.emit') {
+      const schema = literal(field(input(effect, 'emission'), 'schema'));
+      if (schema !== null) add('schema', schema, null, consumers, effect.id, { unresolved: !schemas.has(schema) });
+    }
+    if (effect.kind !== 'assets.lookup') continue;
+    const payload = input(effect, 'payload'), embeddedId = literal(field(payload, 'embeddedId'));
+    const key = literal(field(payload, 'key'));
+    const found = field(payload, 'embeddedFound')?.value === true;
+    const bytes = field(payload, 'embeddedLength')?.value;
+    const encoded = literal(field(payload, 'embeddedData'));
+    const known = embeddedId !== null && key !== null && found && Number.isSafeInteger(bytes) && bytes >= 0;
+    add('resource', embeddedId !== null && key !== null ? embeddedId + ':' + key : null, null, consumers, effect.id, {
+      unresolved: !known,
+      dynamic: Boolean(field(payload, 'key') && field(payload, 'key').kind !== 'literal'),
+      ...(known ? { resource: { name: key, mediaType: literal(field(payload, 'embeddedType')), inputBytes: bytes,
+        encodedBytes: encoded === null ? null : Buffer.byteLength(encoded, 'utf8') } } : {})
+    });
+  }
+  // These offsets are compiler-generated entry/helper ranges, not a reader's source
+  // heuristic. Authored package references from another file cannot borrow an
+  // unrelated generated offset. Unassociated references remain observations.
+  for (const [index, reference] of (compiled.metadata.schemaReferences || []).entries()) {
+    const sameFile = !reference.file || reference.file === compiled.metadata.file;
+    const offset = reference.position?.offset;
+    const contains = row => row.generatedRange && offset >= row.generatedRange.start && offset < row.generatedRange.end;
+    const located = sameFile && Number.isSafeInteger(offset);
+    const matches = located ? raw.filter(contains) : [];
+    const helperMatches = located ? (plan.routing?.helpers || []).filter(contains) : [];
+    const consumers = !raw.length && sameFile ? ['default']
+      : matches.length === 1 && !helperMatches.length ? [matches[0].stableId]
+      : !matches.length && helperMatches.length === 1 ? [...(helpers.get(helperMatches[0].id) || [])] : [];
+    const name = typeof reference.id === 'string' && reference.id ? reference.id : null;
+    add('schema', name, null, consumers, 'schema:' + index, { unresolved: !schemas.has(name),
+      externalPackages: [...(packageSources.get(referenceKey(reference)) || [])] });
+  }
+  for (const event of compiled.eventCatalog?.events || []) if (event.schemaId) {
+    add('schema', event.schemaId, null, [event.stableId], event.stableId, { unresolved: !schemas.has(event.schemaId) });
+  }
+  // Only compact allowlisted data crosses into Report. No provider metadata,
+  // effect payloads, binding values, resource bodies or expression text survives.
+  const routeBehaviors = require('./report-route-behavior').routeBehaviorForMetadata(compiled.metadata.router);
+  const topology = require('./report-handler-topology').collectHandlerTopology(compiled);
+  return Object.freeze({ version: 'pulse.compiler-report-references.v1',
+    ...(topology ? { topology } : {}),
+    ...(routeBehaviors ? { routeBehaviors } : {}),
+    responsePayloads: require('./report-response-payloads').collectResponsePayloads(plan, entries, helpers),
+    references: Object.freeze([...rows.values()].map(row => Object.freeze({ ...row, entryIds: Object.freeze(unique(row.entryIds)),
+      ...(row.externalPackages ? { externalPackages: Object.freeze(row.externalPackages) } : {}),
+      ...(row.resource ? { resource: Object.freeze(row.resource) } : {}) }))) });
+}
+
+module.exports = { collectCanonicalReportReferences };

package/src/report-response-payloads.js

@@ -0,0 +1,62 @@
+'use strict';
+
+// Observational projection of canonical text-response sites, after emission.
+// Never evaluate application expressions or expose literal contents/hashes.
+function collectResponsePayloads(plan, entryIds, helperConsumers) {
+  const sites = [];
+  const unique = values => [...new Set(values)].sort();
+  const literal = value => value?.kind === 'literal' && typeof value.value === 'string' ? value.value : null;
+  const objectFields = value => value?.kind === 'object' && value.entries.every(row => row.kind === 'property'
+    && row.key?.kind === 'literal' && typeof row.key.value === 'string') ? value.entries : null;
+  const field = (rows, key) => rows?.filter(row => row.key.value === key).at(-1)?.value;
+  function mediaType(options) {
+    if (!options || options.kind === 'undefined') return 'text/plain';
+    const fields = objectFields(options);
+    if (!fields) return null;
+    const headers = field(fields, 'headers');
+    if (!headers) return 'text/plain';
+    const values = objectFields(headers);
+    if (!values) return null;
+    const types = values.filter(row => row.key.value.toLowerCase() === 'content-type');
+    if (!types.length) return 'text/plain';
+    // Case variants can be merged by the runtime header adapter; do not guess.
+    if (types.length !== 1) return null;
+    const type = literal(types[0].value)?.split(';')[0].trim().toLowerCase();
+    return ['text/plain', 'text/css', 'text/html', 'text/javascript', 'application/javascript'].includes(type) ? type : null;
+  }
+  function scan(body, owner, consumers) {
+    const constants = new Map();
+    function visit(value, fn, path = 'body') {
+      if (!value || typeof value !== 'object') return;
+      fn(value, path);
+      for (const [key, child] of Object.entries(value)) if (child && typeof child === 'object') {
+        if (Array.isArray(child)) child.forEach((row, i) => visit(row, fn, path + '.' + key + '[' + i + ']'));
+        else visit(child, fn, path + '.' + key);
+      }
+    }
+    visit(body, node => {
+      if (node.kind === 'local' && node.declaration === 'const' && literal(node.value) !== null)
+        constants.set(node.localId, node.value.value);
+    });
+    visit(body, (node, path) => {
+      if (node.kind !== 'intrinsic' || node.name !== 'response.text') return;
+      const input = node.arguments[0];
+      const value = literal(input) ?? (input?.kind === 'local' ? constants.get(input.id) : null);
+      const known = typeof value === 'string';
+      const state = known ? 'resolved' : !input || ['literal', 'undefined'].includes(input.kind) ? 'unknown' : 'dynamic';
+      const valid = unique(consumers.filter(id => entryIds.has(id)));
+      sites.push(Object.freeze({ canonicalId: JSON.stringify([owner, path]),
+        state, inputBytes: known ? Buffer.byteLength(value, 'utf8') : null,
+        mediaType: mediaType(node.arguments[1]), entryIds: Object.freeze(valid),
+        entriesComplete: consumers.length > 0 && consumers.every(id => entryIds.has(id)) }));
+    });
+  }
+  scan(plan.entry.body, 'entry', plan.entry.kind === 'router' ? [] : ['default']);
+  for (const row of plan.handlers || []) scan(row.body, 'handler:' + row.id, [row.id]);
+  for (const row of plan.stages || []) scan(row.body, 'stage:' + row.id, row.registrations.map(item => item.entryId));
+  for (const row of plan.helpers || []) scan(row.body, 'helper:' + row.id, [...(helperConsumers.get(row.id) || [])]);
+  sites.sort((a, b) => a.canonicalId < b.canonicalId ? -1 : a.canonicalId > b.canonicalId ? 1 : 0);
+  return Object.freeze({ version: 'pulse.report-text-responses.v1', sites: Object.freeze(sites) });
+}
+
+module.exports = { collectResponsePayloads };

package/src/report-route-behavior.js

@@ -0,0 +1,15 @@
+'use strict';
+
+// Observational only: keep IR facts out of serialized compiler metadata, source
+// and plan hashes. A deserialized/foreign metadata object supplies no evidence.
+const records = new WeakMap();
+function retainRouteBehavior(metadata, handlers) {
+  const routes = new Set(metadata.entries.filter(row => row.kind === 'route').map(row => row.stableId));
+  records.set(metadata, Object.freeze(handlers.filter(row => routes.has(row.entryStableId)).map(row => Object.freeze({
+    entryId: row.entryStableId,
+    kind: row.operationIr.summary.operationKinds['router-transfer'] ? 'continuing' : 'terminal',
+    basis: 'canonical-handler-ir'
+  }))));
+}
+function routeBehaviorForMetadata(metadata) { return records.get(metadata); }
+module.exports = { retainRouteBehavior, routeBehaviorForMetadata };

package/src/report-router-control.js

@@ -0,0 +1,42 @@
+'use strict';
+
+// Project only accepted canonical operations. No AST text, predicates, provider
+// values or generated positions enter the report, and no runtime IR is changed.
+function projectRouterControl(entry, rawEntry, ir) {
+  const unavailable = { state: 'unavailable', value: null, reason: 'not-recorded' };
+  const value = { pattern: null, eligibility: Boolean(rawEntry.eligibility),
+    normal: false, error: false, terminal: false, basis: 'canonical-router-control' };
+  if (entry.kind === 'route' || entry.kind === 'mount' || entry.kind === 'use' && entry.scoped) {
+    if (!rawEntry.pattern?.normalized) return unavailable;
+    value.pattern = rawEntry.pattern.normalized;
+  }
+  if (entry.kind === 'mount' || !entry.handlerId) value.normal = true;
+  else {
+    if (!ir?.body) return unavailable;
+    let known = true;
+    function visit(operation) {
+      if (!operation) return;
+      switch (operation.kind) {
+        case 'block': operation.statements.forEach(visit); break;
+        case 'if': visit(operation.thenOperation); visit(operation.elseOperation); break;
+        case 'router-guard': visit(operation.body); break;
+        case 'router-transfer':
+          if (operation.clearNormalMode) value.normal = true;
+          else if (operation.errorExpression) value.error = true;
+          else known = false;
+          break;
+        case 'source-statement':
+          if (operation.role === 'router-return') value.terminal = true;
+          else if (operation.role !== 'router-source') known = false;
+          break;
+        default: known = false;
+      }
+    }
+    visit(ir.body);
+    if (entry.kind === 'event') value.terminal = true; // Accepted void fallthrough.
+    if (!known || !value.normal && !value.error && !value.terminal) return unavailable;
+  }
+  return { state: 'available', value, reason: null };
+}
+
+module.exports = { projectRouterControl };

package/src/report-source-inputs.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const reads = new WeakMap(), outputs = new WeakMap();
+const stamp = s => (s.isDirectory() ? [s.dev, s.ino, s.mode] : [s.dev, s.ino, s.size, s.mtimeNs, s.ctimeNs]).map(String).join(':');
+// In-memory read receipts only: never enter the graph, plan or executable hashes.
+function state(file) {
+  const chain = []; let directory = path.parse(file).root;
+  for (const part of path.relative(directory, file).split(path.sep)) {
+    directory = path.join(directory, part); chain.push(stamp(fs.lstatSync(directory, { bigint: true })));
+  }
+  return { real: fs.realpathSync(file), token: JSON.stringify(chain) };
+}
+function receiptFor(owner) {
+  if (!reads.has(owner)) reads.set(owner, { rows: [], error: null, bytes: 0 });
+  return reads.get(owner);
+}
+function readSourceInput(owner, file, kind, identity) {
+  const receipt = receiptFor(owner);
+  let before; try { before = state(file); } catch { receipt.error = 'REPORT_INPUT_UNBOUND'; }
+  const source = fs.readFileSync(file, 'utf8'); // Preserve the compiler's ordinary read/error behavior.
+  try {
+    const after = state(file), bytes = Buffer.byteLength(source);
+    if (!before || before.real !== after.real || before.token !== after.token) receipt.error = 'REPORT_CONCURRENT_CHANGE';
+    receipt.bytes += bytes;
+    if (receipt.rows.length >= 20000 || receipt.bytes > 256 * 1024 * 1024) receipt.error = 'REPORT_LIMIT';
+    if (!receipt.error) receipt.rows.push(Object.freeze({ file, ...after, kind, identity, bytes,
+      sha256: createHash('sha256').update(source).digest('hex') }));
+  } catch { receipt.error = 'REPORT_INPUT_UNBOUND'; }
+  return source;
+}
+function missingManifest(owner, file, identity) {
+  if (!owner) return;
+  const receipt = receiptFor(owner);
+  if (receipt.rows.length >= 20000) receipt.error = 'REPORT_LIMIT';
+  if (!receipt.error) receipt.rows.push(Object.freeze({ file, real: null, token: 'absent', kind: 'missing-manifest', identity, bytes: 0, sha256: null }));
+}
+function sourceResolution(owner, file, real, identity) {
+  if (!owner || file === real) return;
+  const receipt = receiptFor(owner);
+  try {
+    const observed = state(file);
+    if (observed.real !== real) receipt.error = 'REPORT_CONCURRENT_CHANGE';
+    if (receipt.rows.length >= 20000) receipt.error = 'REPORT_LIMIT';
+    if (!receipt.error) receipt.rows.push(Object.freeze({ file, ...observed, kind: 'source-link', identity, bytes: 0, sha256: null }));
+  } catch { receipt.error = 'REPORT_INPUT_UNBOUND'; }
+}
+function retainSourceInputs(compiled, context) {
+  const receipt = reads.get(context);
+  outputs.set(compiled, Object.freeze({ rows: Object.freeze([...(receipt?.rows || [])]), error: receipt?.error || null }));
+}
+function sourceInputsForCompiled(compiled) { return outputs.get(compiled); }
+module.exports = { readSourceInput, missingManifest, sourceResolution, retainSourceInputs, sourceInputsForCompiled };

package/src/spine/binding-ownership.js

@@ -0,0 +1,13 @@
+'use strict';
+
+// A named binding is compiler evidence, independent of a host's configured
+// value. Both authored recognition and lowered-reference projection use this
+// state policy; absence of a literal never invents a resolved binding.
+function bindingOwnership(kind, name, dynamic = false) {
+  if (!['config', 'secret', 'kv', 's3'].includes(kind)) return undefined;
+  const canonicalId = typeof name === 'string' ? name : null;
+  return Object.freeze({ kind, canonicalId,
+    state: canonicalId !== null ? 'resolved' : dynamic ? 'dynamic' : 'unknown' });
+}
+
+module.exports = { bindingOwnership };

package/src/spine/canonical-router.js

@@ -118,6 +118,7 @@ function executeCanonicalRouterSpine(sourceText, options = {}) {
   if (output && typeof output === 'object') {
     traces.set(output, result.trace);
     handlerIrBundles.set(output, bundle.handlers);
+    require('../report-route-behavior').retainRouteBehavior(output.metadata, bundle.handlers);
     surfaceFacts.set(output, Object.freeze({
       recognition: bundle.recognition,
       classification: bundle.classification,

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

@@ -469,6 +469,25 @@ function routerHandlerNames(entry) {
   });
 }
 
+// Shared compiler projection. Recognition details own provider/package capability
+// names; synchronous surfaces use the same mapping as router analysis.
+function capabilityForHandlerSurface(fact) {
+  if (fact.detail?.provider) return fact.detail.provider.capability;
+  if (fact.detail?.packageEffect) return String(fact.detail.packageEffect.capability || fact.detail.packageEffect.kind);
+  const id = fact.surfaceId;
+  if (id === 'ctx.req.body') return 'request.body.forward';
+  if (id.startsWith('ctx.fetch.')) return 'fetch';
+  if (id.startsWith('ctx.req.')) return id.slice(4);
+  if (id.startsWith('ctx.config.')) return 'config.get';
+  if (id.startsWith('ctx.secret.')) return 'secret.get';
+  if (id.startsWith('ctx.kv.') || id.startsWith('ctx.state.')) return id.slice(4);
+  if (id === 'ctx.emit') return 'event.emit';
+  if (id.startsWith('ctx.log.')) return 'logging';
+  if (['ctx.json', 'ctx.text', 'ctx.response'].includes(id)) return `response.${id.slice(4)}`;
+  if (id === 'ctx.param') return 'route.param';
+  return undefined;
+}
+
 function inspectCanonicalRouterSurfaces(topology, options = {}) {
   if (!topology || topology.frontend !== 'canonical-router' || !topology.sourceFile || !Array.isArray(topology.entries)) {
     throw new TypeError('inspectCanonicalRouterSurfaces requires a prepared canonical Router topology.');
@@ -476,6 +495,47 @@ function inspectCanonicalRouterSurfaces(topology, options = {}) {
   const sourceFile = topology.sourceFile;
   const facts = [];
   const surfacesByEntry = new Map();
+  // Private observations retain original nodes before normalization. They never
+  // enter recognition facts, summaries, executable metadata or identity hashes.
+  const authoredSites = [], validatedCalls = [], seenOwners = new Set();
+  function retainAuthored(ownerId, fn, file, names) {
+    if (seenOwners.has(ownerId)) return;
+    seenOwners.add(ownerId);
+    const seenNodes = new WeakSet();
+    function visit(node, aliases) {
+      if (seenNodes.has(node)) return;
+      seenNodes.add(node);
+      if (ts.isTypeNode(node) || ts.isFunctionLike(node)) return;
+      if (ts.isBlock(node)) {
+        const local = new Map(aliases);
+        for (const statement of node.statements) {
+          const namespace = extractKvNamespaceDeclaration(statement, names.ctxName, { unwrap: true });
+          if (namespace) local.set(namespace.variableName, namespace.store);
+          visit(statement, local);
+        }
+        return;
+      }
+      // Await/parentheses are syntax wrappers, not additional operation sites.
+      const current = expressionFor(node, { unwrap: true });
+      if (current !== node) { visit(current, aliases); return; }
+      if (ts.isAwaitExpression(node)) { visit(node.expression, aliases); return; }
+      const recognized = recognizeHandlerSurface(node, { ...names, unwrap: true,
+        kvAliases: aliases, packageEffectForCall: options.packageEffectForCall });
+      if (recognized && recognized.class !== 'handler-wrapper') {
+        authoredSites.push(Object.freeze({ ownerId, sourceFile: file, node, recognized }));
+        if (ts.isCallExpression(node)) {
+          for (const argument of node.arguments) visit(argument, aliases);
+          // A fetch projection owns its fetch receiver; provider receiver inputs
+          // can themselves contain synchronous context operations.
+          if (recognized.detail?.provider?.resource) visit(recognized.detail.provider.resource, aliases);
+          for (const argument of recognized.detail?.fetch?.fetchCall?.arguments || []) visit(argument, aliases);
+          return;
+        }
+      }
+      ts.forEachChild(node, child => visit(child, aliases));
+    }
+    if (fn.body) visit(fn.body, new Map());
+  }
 
   function record(entry, node, names) {
     const recognized = recognizeHandlerSurface(node, {
@@ -514,6 +574,7 @@ function inspectCanonicalRouterSurfaces(topology, options = {}) {
   for (const entry of topology.entries) {
     if (!entry.functionNode) continue;
     const names = routerHandlerNames(entry);
+    retainAuthored(entry.entry.handlerId, entry.functionNode, entry.sourceFile || sourceFile, names);
     record(entry, entry.functionNode, names);
     function visit(node) {
       if (typeof ts.isTypeNode === 'function' && ts.isTypeNode(node)) return;
@@ -528,6 +589,9 @@ function inspectCanonicalRouterSurfaces(topology, options = {}) {
     if (entry.functionNode.body) visit(entry.functionNode.body);
   }
 
+  for (const helper of options.linkedProjectModules?.sourceHelpers || []) {
+    if (!helper.pure) retainAuthored(helper.id, helper.functionNode, helper.sourceFile, { ctxName: 'ctx' });
+  }
   const recognition = Object.freeze({
     version: HANDLER_SURFACE_AUTHORITY_VERSION,
     contractVersion: contract.HANDLER_SURFACE_CONTRACT_VERSION,
@@ -543,6 +607,12 @@ function inspectCanonicalRouterSurfaces(topology, options = {}) {
   });
   canonicalRouterModels.set(recognition, Object.freeze({
     topology,
+    authoredSites: Object.freeze(authoredSites),
+    get validatedCalls() { return Object.freeze([...validatedCalls]); },
+    retainValidatedCall(entry, helper, node, sourceFile) {
+      validatedCalls.push(Object.freeze({ callerId: entry.handlerId, calleeId: helper.id,
+        registrationId: entry.stableId, node: ts.getOriginalNode(node), sourceFile }));
+    },
     namesForEntry(entryStableId) {
       const entry = topology.entries.find((candidate) => candidate.entry.stableId === entryStableId);
       return entry ? routerHandlerNames(entry) : undefined;
@@ -587,6 +657,7 @@ module.exports = Object.freeze({
   staticString,
   recognizeManagedHandlerWrapper,
   recognizeHandlerSurface,
+  capabilityForHandlerSurface,
   classifyRecognizedHandlerSurface,
   extractFetchChain,
   extractEventEmitCall,

package/src/spine/package-operation-seam.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const crypto = require('node:crypto');
+const { isTrustedLowerer } = require('@pulse-compute/wasm-contracts/library/manifest');
 const fs = require('node:fs');
 const { createRequire } = require('node:module');
 const path = require('node:path');
@@ -82,7 +83,7 @@ function catalogDescriptor(record, productRecord) {
   const nativeSupported = Boolean(
     product
     && ['supported', 'provider-dependent'].includes(product.targets.native.status)
-    && compiler.trust === 'first-party'
+    && isTrustedLowerer(compiler.trust)
     && validation.status === 'ok'
     && wasm.mode !== 'lowering-plan-only'
     && wasm.sidecar
@@ -130,11 +131,13 @@ function discoverPackageContractCatalog(options = {}) {
   const records = discoverLowerableLibraryManifests({
     cwd,
     workspaceRoot: options.workspaceRoot,
+    packageDirs: options.packageDirs,
     scanNodeModules: options.scanNodeModules !== false
   });
   const productCatalog = discoverPulsePackageContracts({
     cwd,
     workspaceRoot: options.workspaceRoot,
+    packageDirs: options.packageDirs,
     scanNodeModules: options.scanNodeModules !== false
   });
   const productsByContract = new Map(productCatalog.contracts.map((entry) => [entry.contractId, { contract: entry, metadataHash: entry.metadataHash }]));
@@ -168,7 +171,7 @@ function discoverPackageContractCatalog(options = {}) {
     }),
     contracts: Object.freeze(contracts),
     policy: Object.freeze({
-      trustedFirstPartyOnly: true,
+      trustedBuildDependencies: true,
       sourceSubstringSelection: false,
       graphReachabilitySelection: true,
       publicRegistration: false,
@@ -333,6 +336,10 @@ function canonicalRealizationArtifact(artifact, record) {
       { id, version, kind, mediaType, contractId, package: packageName }
     );
   }
+  if (kind === 'package-runtime-wasm') {
+    try { return require('@pulse-compute/wasm-contracts/package/runtime-binding').validateRuntimeBinding(value).artifact; }
+    catch { throw new PackageOperationSeamError('PULSE_PACKAGE_REALIZATION_ARTIFACT_INVALID', 'Package runtime Wasm must match the supported bounded ABI.', { id }); }
+  }
   return deepFreeze(value);
 }
 
@@ -615,6 +622,7 @@ function recognizeProjectPackageOperations(entryFile, options = {}) {
   const manifestRecords = discoverLowerableLibraryManifests({
     cwd: rootDir,
     workspaceRoot: options.workspaceRoot,
+    packageDirs: options.packageDirs,
     scanNodeModules: true
   });
   const selected = selectPackageRecords(manifestRecords, sourceText, options.selectedContracts);
@@ -638,8 +646,10 @@ function recognizeProjectPackageOperations(entryFile, options = {}) {
     // This source-aware step is package recognition and validation. The later
     // package-lowering phase receives only the canonical operations below.
     const result = buildPackageOwnedLoweringPlan({
+      typescript: ts,
       cwd: rootDir,
       workspaceRoot: options.workspaceRoot,
+    packageDirs: options.packageDirs,
       manifestRecords,
       contractId: record.manifest.contractId,
       sourcePath: sourceName,
@@ -666,8 +676,12 @@ function recognizeProjectPackageOperations(entryFile, options = {}) {
       .map(canonicalPackageSchemaReference)
       .map((reference) => schemaReferenceWithSourceFile(reference, sourceName));
     schemaReferences.push(...recognizedSchemaReferences);
-    realizationArtifacts.push(...(contributions.realizationArtifacts || [])
-      .map((artifact) => canonicalRealizationArtifact(artifact, record)));
+    const runtimeArtifacts = (contributions.realizationArtifacts || []).map(artifact => canonicalRealizationArtifact(artifact, record));
+    for (const effect of canonicalEffects.filter(effect => effect.kind === 'package.invoke')) {
+      try { require('@pulse-compute/wasm-contracts/package/runtime-binding').validateRuntimeInvocation(effect, runtimeArtifacts); }
+      catch { throw new PackageOperationSeamError('PULSE_PACKAGE_REALIZATION_ARTIFACT_INVALID', 'Package invocation requires an exact declared static runtime binding.', { contractId: record.manifest.contractId }); }
+    }
+    realizationArtifacts.push(...runtimeArtifacts);
     inspectionArtifacts.push(...(contributions.inspectionArtifacts || [])
       .map((artifact) => canonicalInspectionArtifact(artifact, record)));
     managedHandlers.push(...(contributions.managedHandlers || [])
@@ -736,7 +750,7 @@ function recognizeProjectPackageOperations(entryFile, options = {}) {
       lateLoweringReceivesSourceAst: false,
       lateLoweringReceivesSourceText: false,
       lateLoweringInput: CANONICAL_PACKAGE_OPERATION_VERSION,
-      firstPartyBuildersOnly: true,
+      trustedBuildDependencies: true,
       externalRegistration: false
     })
   });
@@ -880,7 +894,7 @@ function combinePackageOperationRecognitions(recognitions = []) {
       lateLoweringReceivesSourceAst: false,
       lateLoweringReceivesSourceText: false,
       lateLoweringInput: CANONICAL_PACKAGE_OPERATION_VERSION,
-      firstPartyBuildersOnly: true,
+      trustedBuildDependencies: true,
       externalRegistration: false
     })
   });
@@ -944,7 +958,7 @@ function packageOperationRecognitionFromEffects(effects = []) {
       lateLoweringReceivesSourceAst: false,
       lateLoweringReceivesSourceText: false,
       lateLoweringInput: CANONICAL_PACKAGE_OPERATION_VERSION,
-      firstPartyBuildersOnly: true,
+      trustedBuildDependencies: true,
       externalRegistration: false
     })
   });