@pulse-compute/runtime 1.0.0-beta.4 → 1.0.0-beta.6

package/src/internal/response.js

@@ -12,6 +12,7 @@ const {
 
 const RESULT_DATA = new WeakMap();
 const FETCH_RESPONSE_DATA = new WeakMap();
+const FETCH_RESPONSE_CANCELLATIONS = new WeakMap();
 const RESPONSE_HEADER_DATA = new WeakMap();
 const RESPONSE_BODY_CLASS_DATA = new WeakMap();
 const RESULT_BRAND = Symbol('pulse.runtime.result');
@@ -180,6 +181,24 @@ function claimFetchResponse(data, mode) {
   data.ownershipMode = mode;
 }
 
+function retainFetchResponseForBudget(response, budget, onRelease) {
+  if (!(response instanceof Response) || !response.body) return;
+  const remove = budget?.onAbort(() => cancelResponseBody(response, budget.signal.reason));
+  let registrations = FETCH_RESPONSE_CANCELLATIONS.get(response);
+  if (!registrations) {
+    registrations = new Set();
+    FETCH_RESPONSE_CANCELLATIONS.set(response, registrations);
+  }
+  registrations.add(() => { remove?.(); onRelease?.(); });
+}
+
+function releaseFetchResponseCancellation(response) {
+  const registrations = FETCH_RESPONSE_CANCELLATIONS.get(response);
+  if (!registrations) return;
+  FETCH_RESPONSE_CANCELLATIONS.delete(response);
+  for (const remove of registrations) remove();
+}
+
 function readerForFetchData(data, options = {}) {
   claimFetchResponse(data, 'structured-projection');
   if (data.bodyReader) return data.bodyReader;
@@ -191,7 +210,10 @@ function readerForFetchData(data, options = {}) {
     label: 'fetched response',
     maxBytes: options.maxBodyBytes === undefined ? data.maxBodyBytes : options.maxBodyBytes,
     forceStructured: true,
-    signal: options.signal || data.signal
+    signal: options.signal || data.signal,
+    onReadSettled: () => {
+      if (data.response.bodyUsed && !data.response.body?.locked) releaseFetchResponseCancellation(data.response);
+    }
   });
   return data.bodyReader;
 }
@@ -355,9 +377,11 @@ function projectFetchResponse(value, projection, schemaId, options = {}) {
   );
 }
 
-async function cancelResponseBody(response) {
-  if (!(response instanceof Response) || !response.body || response.bodyUsed) return;
-  try { await response.body.cancel(); } catch (_) { /* ownership cleanup is best effort */ }
+function cancelResponseBody(response, reason) {
+  if (!(response instanceof Response) || !response.body || response.body.locked) return;
+  // A provider's cancellation callback may reject or never settle. Cleanup must
+  // observe rejection without delaying request completion or decoding the body.
+  try { void response.body.cancel(reason).catch(() => {}); } catch (_) { /* best effort */ }
 }
 
 async function fetchResponseToResponse(value, requestMethod = 'GET') {
@@ -371,7 +395,7 @@ async function fetchResponseToResponse(value, requestMethod = 'GET') {
     if (bodyAllowed && !statusChanged) {
       return rememberResponseMetadata(data.response, headers, value.bodyClass);
     }
-    if (!bodyAllowed) await cancelResponseBody(data.response);
+    if (!bodyAllowed) cancelResponseBody(data.response);
     return rememberResponseMetadata(
       new Response(bodyAllowed ? data.response.body : null, {
         status: value.status,
@@ -394,6 +418,7 @@ async function fetchResponseToResponse(value, requestMethod = 'GET') {
 module.exports = Object.freeze({
   PulseRuntimeContractError,
   PulseUnhandledError,
+  cancelResponseBody,
   createJsonResult,
   createOpaqueFetchResponse,
   createResponseResult,
@@ -403,6 +428,8 @@ module.exports = Object.freeze({
   isPulseResult,
   markOpaqueResponse,
   normalizeFetchResponse,
+  retainFetchResponseForBudget,
+  releaseFetchResponseCancellation,
   normalizeHeaders,
   projectFetchResponse,
   responseAllowsBody,

package/src/internal/router.js

@@ -1,12 +1,15 @@
 'use strict';
+const { createRequestBudget } = require('./request-budget.js');
 
 const { compileRoutePath, matchRoutePath, normalizeRoutePath } = require('./path.js');
 const { createContext, createRequestView } = require('./context.js');
 const { createJavascriptEffectExecution } = require('./effect-adapter.js');
 const { reportingLevel } = require('./logging.js');
+const { isApplicationError } = require('./errors.js');
 const {
   PulseRuntimeContractError,
   PulseUnhandledError,
+  cancelResponseBody,
   fetchResponseToResponse,
   isPulseFetchResponse,
   isPulseResult,
@@ -31,6 +34,17 @@ function requireRouter(value) {
   return value;
 }
 
+function mountEligibility(value) {
+  if (value === undefined) return undefined;
+  const invalid = () => { throw new TypeError('Pulse Router mount eligibility requires { state: "key", equals: "value" } with string data properties.'); };
+  if (!value || typeof value !== 'object') return invalid();
+  const properties = Object.getOwnPropertyDescriptors(value);
+  if (Reflect.ownKeys(properties).length !== 2 ||
+      !properties.state || !properties.equals ||
+      typeof properties.state.value !== 'string' || typeof properties.equals.value !== 'string') return invalid();
+  return Object.freeze({ state: properties.state.value, equals: properties.equals.value });
+}
+
 function mergeParams(left, right) {
   return Object.freeze({ ...(left || {}), ...(right || {}) });
 }
@@ -111,10 +125,11 @@ class Router {
     return this;
   }
 
-  mount(path, router) {
+  mount(path, router, eligibility) {
     ROUTER_STATE.get(this).entries.push(entry('mount', {
       path: compileRoutePath(path, { scoped: true, allowWildcard: true }),
-      router: requireRouter(router)
+      router: requireRouter(router),
+      eligibility: mountEligibility(eligibility)
     }));
     return this;
   }
@@ -159,7 +174,7 @@ function redactedError(frame, error) {
 
 function containUnexpected(error, frame) {
   const safe = redactedError(frame, error);
-  return safe instanceof PulseUnhandledError ? safe : new PulseUnhandledError(safe);
+  return isApplicationError(error) || safe instanceof PulseUnhandledError ? safe : new PulseUnhandledError(safe);
 }
 
 function contractError(code, message) {
@@ -171,9 +186,7 @@ async function normalizeHandlerResponse(value, requestMethod) {
   if (isPulseFetchResponse(value)) return fetchResponseToResponse(value, requestMethod);
   if (value instanceof Response) {
     if (String(requestMethod).toUpperCase() !== 'HEAD' && statusAllowsBody(value.status)) return value;
-    if (value.body && !value.bodyUsed) {
-      try { await value.body.cancel(); } catch (_) { /* ownership cleanup is best effort */ }
-    }
+    cancelResponseBody(value);
     const response = new Response(null, { status: value.status, statusText: value.statusText, headers: value.headers });
     return responseBodyClass(value) === 'opaque'
       ? markOpaqueResponse(response, responseHeaderPairs(value))
@@ -192,6 +205,7 @@ async function dispatchRouter(router, frame, startIndex, activeError) {
   let error = activeError;
 
   while (index < entries.length) {
+    frame.signal?.throwIfAborted();
     const current = entries[index];
 
     if (error !== NO_ERROR) {
@@ -215,7 +229,7 @@ async function dispatchRouter(router, frame, startIndex, activeError) {
 
     if (current.kind === 'mount') {
       const match = matchRoutePath(current.path, frame.relativePath);
-      if (!match) {
+      if (!match || (current.eligibility && frame.state.get(current.eligibility.state) !== current.eligibility.equals)) {
         index += 1;
         continue;
       }
@@ -300,10 +314,13 @@ async function runNormalHandler(_router, frame, index, handler, routeContext) {
   } catch (error) {
     if (handlerError === undefined) handlerError = error;
   }
+  frame.signal?.throwIfAborted();
+  if (handlerError !== undefined && frame.executionOptions.outputExecution?.started) throw handlerError;
   if (handlerError !== undefined) {
     return Object.freeze({ kind: 'continue', index: index + 1, error: containUnexpected(handlerError, frame), frame });
   }
 
+  frame.executionOptions.outputExecution?.validateResult(output);
   const transfer = transferData(output, transferFactory.token);
   if (transferFactory.wasCalled()) {
     if (!transfer || output !== transferFactory.transfer()) {
@@ -353,10 +370,13 @@ async function runErrorHandler(_router, frame, index, activeError, handler) {
   } catch (error) {
     if (handlerError === undefined) handlerError = error;
   }
+  frame.signal?.throwIfAborted();
+  if (handlerError !== undefined && frame.executionOptions.outputExecution?.started) throw handlerError;
   if (handlerError !== undefined) {
     return Object.freeze({ kind: 'continue', index: index + 1, error: containUnexpected(handlerError, frame), frame });
   }
 
+  frame.executionOptions.outputExecution?.validateResult(output);
   const transfer = transferData(output, transferFactory.token);
   if (transferFactory.wasCalled()) {
     if (!transfer || output !== transferFactory.transfer()) {
@@ -409,53 +429,63 @@ async function executeRouter(router, request, options = {}) {
       // Logging evidence is best effort.
     }
   }
-  const executionSignal = options.signal || request.signal;
-  const effectExecution = createJavascriptEffectExecution({
-    effectAdapter: options.effectAdapter,
-    capabilities: options.capabilities,
-    application: options.application,
-    request,
-    executionKind: 'request',
-    signal: executionSignal,
-    maxEffects: options.maxEffects,
-    kvClock: options.kvClock, deadlineMonotonicMs: options.deadlineMonotonicMs,
-    maxBindingNameBytes: options.maxBindingNameBytes,
-    maxBindingValueBytes: options.maxBindingValueBytes,
-    maxKvNamespaceBytes: options.maxKvNamespaceBytes,
-    maxKvKeyBytes: options.maxKvKeyBytes,
-    maxKvValueBytes: options.maxKvValueBytes,
-    maxKvValueDepth: options.maxKvValueDepth,
-    maxKvValueEntries: options.maxKvValueEntries,
-    schemaCodecs: options.schemaCodecs,
-    strict: options.strict,
-    target: options.target,
-    provider: options.provider,
-    redactionValues: options.redactionValues,
-    onEffectObservation: options.onEffectObservation
-  });
-  const req = createRequestView(request, options.requestHeaders, effectExecution, {
-    ...options,
-    signal: executionSignal,
-    redactJsonTraceValue(value) { return effectExecution.redactValue(value); }
-  });
-  const executionOptions = Object.freeze({
-    ...options,
-    signal: executionSignal,
-    redactJsonTraceValue(value) { return effectExecution.redactValue(value); }
-  });
-  const frame = {
-    request,
-    req,
-    relativePath: normalizeRoutePath(req.path),
-    params: Object.freeze({}),
-    state: new Map(),
-    effectExecution,
-    signal: executionSignal,
-    executionOptions
-  };
+  const ownsBudget = options.requestBudget === undefined;
+  const budget = createRequestBudget({ ...options, requestSignal: request.signal });
+  options = { ...options, requestBudget: budget, signal: budget.signal, deadlineMonotonicMs: budget.deadlineMonotonicMs ?? options.deadlineMonotonicMs, kvClock: budget.deadlineMonotonicMs === undefined ? options.kvClock : budget.clock };
+  const executionSignal = budget.signal;
+  let effectExecution;
+  let transferredResponse;
   try {
-    const result = await dispatchRouter(router, frame, 0, NO_ERROR);
-    if (result.kind === 'response') return result.response;
+    budget.check();
+    effectExecution = createJavascriptEffectExecution({
+      outputExecution: options.outputExecution,
+      effectAdapter: options.effectAdapter,
+      capabilities: options.capabilities,
+      application: options.application,
+      request,
+      executionKind: 'request',
+      signal: executionSignal,
+      requestBudget: budget,
+      maxEffects: options.maxEffects,
+      kvClock: options.kvClock, deadlineMonotonicMs: options.deadlineMonotonicMs,
+      maxBindingNameBytes: options.maxBindingNameBytes,
+      maxBindingValueBytes: options.maxBindingValueBytes,
+      maxKvNamespaceBytes: options.maxKvNamespaceBytes,
+      maxKvKeyBytes: options.maxKvKeyBytes,
+      maxKvValueBytes: options.maxKvValueBytes,
+      maxKvValueDepth: options.maxKvValueDepth,
+      maxKvValueEntries: options.maxKvValueEntries,
+      schemaCodecs: options.schemaCodecs,
+      strict: options.strict,
+      target: options.target,
+      provider: options.provider,
+      redactionValues: options.redactionValues,
+      onEffectObservation: options.onEffectObservation
+    });
+    const req = createRequestView(request, options.requestHeaders, effectExecution, {
+      ...options,
+      signal: executionSignal,
+      redactJsonTraceValue(value) { return effectExecution.redactValue(value); }
+    });
+    const executionOptions = Object.freeze({
+      ...options,
+      signal: executionSignal,
+      redactJsonTraceValue(value) { return effectExecution.redactValue(value); }
+    });
+    const frame = {
+      request,
+      req,
+      relativePath: normalizeRoutePath(req.path),
+      params: Object.freeze({}),
+      state: new Map(),
+      effectExecution,
+      signal: executionSignal,
+      executionOptions
+    };
+    budget.check();
+    const result = await budget.race(dispatchRouter(router, frame, 0, NO_ERROR));
+    executionSignal?.throwIfAborted();
+    if (result.kind === 'response') return (transferredResponse = result.response);
     if (result.error !== NO_ERROR) {
       return new Response('Internal Server Error', {
         status: 500,
@@ -468,9 +498,10 @@ async function executeRouter(router, request, options = {}) {
     });
   } finally {
     try {
-      await effectExecution.close();
+      await effectExecution?.close(transferredResponse);
     } finally {
-      if (typeof options.onEffectSummary === 'function') options.onEffectSummary(effectExecution.summary());
+      if (ownsBudget) budget.close();
+      if (effectExecution && typeof options.onEffectSummary === 'function') options.onEffectSummary(effectExecution.summary());
     }
   }
 }

package/src/internal/schema.js

@@ -144,7 +144,17 @@ function utf8Bytes(value) {
 
 function assertSchemaBodySize(options, text, schemaId, source) {
   const configured = Number(schemaRegistry(options)?.maxBytes);
-  const maxBytes = Number.isSafeInteger(configured) && configured > 0 ? configured : 65_536;
+  let maxBytes = Number.isSafeInteger(configured) && configured > 0 ? configured : 65_536;
+  const jsonLimits = schemaCodecs(options)?.schema?.(schemaId)?.jsonLimits;
+  if (jsonLimits) {
+    maxBytes = Math.min(maxBytes, jsonLimits.maxTextBytes);
+    // UTF-16 length is a lower bound on UTF-8 bytes. Reject large application
+    // strings before TextEncoder allocates their complete encoded form.
+    if (typeof text === 'string' && text.length > maxBytes) {
+      throw schemaRuntimeError('PULSE_BODY_TOO_LARGE', `Pulse ${source} schema body exceeds the ${maxBytes} byte limit.`,
+        { schemaId: String(schemaId), source, bytesAtLeast: text.length, maxBytes });
+    }
+  }
   const bytes = utf8Bytes(text);
   if (bytes <= maxBytes) return bytes;
   throw schemaRuntimeError(
@@ -187,6 +197,7 @@ function emitSchemaTrace(options, event, value) {
 
 function decodeSchemaText(schemaId, text, options = {}, context = {}) {
   const source = String(context.source || 'json');
+  const applicationText = source === 'application-text';
   const id = requireSchemaId(schemaId, options, source);
   if (id === undefined) {
     try {
@@ -197,24 +208,28 @@ function decodeSchemaText(schemaId, text, options = {}, context = {}) {
   }
   let contentType = normalizeContentType(headerValue(context.headers, 'content-type'));
   const event = {
-    boundary: source === 'request' ? 'request' : 'fetch-response',
+    boundary: applicationText ? source : source === 'request' ? 'request' : 'fetch-response',
     schemaId: id,
     responseCaseId: null,
     operationId: String(context.operationId || `${source}:${id}`),
     status: context.status ?? null,
     headers: context.headers || [],
-    bodyOwnership: source === 'request' ? 'request-snapshot' : 'fetched-response-snapshot',
+    bodyOwnership: applicationText ? 'application-owned' : source === 'request' ? 'request-snapshot' : 'fetched-response-snapshot',
     effectId: context.effectId || null,
     groupId: context.groupId || null
   };
   try {
-    contentType = assertSchemaContentType(options, context.headers, id, source);
+    if (applicationText && typeof text !== 'string') {
+      throw schemaRuntimeError('PULSE_SCHEMA_DECODE', 'Application JSON text must be a string.',
+        { schemaId: id, source, expected: 'string', actualKind: typeof text });
+    }
+    if (!applicationText) contentType = assertSchemaContentType(options, context.headers, id, source);
     assertSchemaBodySize(options, text, id, source);
     const codecs = requireSchemaCodecs(options, id, source);
     const value = codecs.decodeJsonText(id, String(text), source);
     emitSchemaTrace(options, {
       ...event,
-      kind: source === 'request' ? 'json.decode.request' : 'json.decode.fetch',
+      kind: applicationText ? 'json.decode.text' : source === 'request' ? 'json.decode.request' : 'json.decode.fetch',
       contentType: contentType || null
     }, value);
     return value;

package/src/internal/time.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const { PulseRuntimeContractError } = require('./errors.js');
+
+// UTC years 1970–9999; integer milliseconds remain exactly representable.
+const WALL_TIME_MAX_MS = 253402300799999;
+const unavailable = Object.freeze({ status: 'failed', reason: 'unavailable' });
+const invalid = Object.freeze({ status: 'failed', reason: 'invalid-clock' });
+
+function validMilliseconds(value) {
+  return Number.isSafeInteger(value) && value >= 0 && value <= WALL_TIME_MAX_MS;
+}
+
+/** The provider supplies the clock. Formatting never samples ambient time. */
+function readWallTime(clock) {
+  if (typeof clock !== 'function') return unavailable;
+  let value;
+  try { value = clock(); } catch { return unavailable; }
+  if (!validMilliseconds(value)) return invalid;
+  return Object.freeze({ status: 'ok', unixEpochMs: value === 0 ? 0 : value, iso8601: new Date(value).toISOString() });
+}
+
+/** Validate and detach a trusted adapter result before guest/application use. */
+function normalizeTimeResult(input) {
+  const fail = () => { throw new PulseRuntimeContractError('PULSE_TIME_RESULT_INVALID', 'Pulse time provider returned an invalid result.'); };
+  if (!input || typeof input !== 'object' || ![Object.prototype, null].includes(Object.getPrototypeOf(input))) return fail();
+  const properties = Object.getOwnPropertyDescriptors(input);
+  const keys = Reflect.ownKeys(properties);
+  if (keys.some(key => typeof key !== 'string' || !Object.hasOwn(properties[key], 'value'))) return fail();
+  const status = properties.status?.value;
+  if (status === 'failed' && keys.length === 2 && properties.reason
+    && ['unavailable', 'invalid-clock'].includes(properties.reason.value)) {
+    return properties.reason.value === 'unavailable' ? unavailable : invalid;
+  }
+  const ms = properties.unixEpochMs?.value;
+  if (status !== 'ok' || keys.length !== 3 || !validMilliseconds(ms)
+    || properties.iso8601?.value !== new Date(ms).toISOString()) return fail();
+  return Object.freeze({ status: 'ok', unixEpochMs: ms === 0 ? 0 : ms, iso8601: properties.iso8601.value });
+}
+
+module.exports = Object.freeze({ WALL_TIME_MAX_MS, readWallTime, normalizeTimeResult });