@pulse-compute/provider-node 1.0.0-beta.1 → 1.0.0-beta.2

package/README.md

@@ -6,10 +6,11 @@
 > **Install directly:** No for application projects; select provider: node through the CLI.<br>
 > **Supported entry points:** `@pulse-compute/provider-node/toolchain`<br>
 > **Stability:** The listed built-in toolchain entry is synchronized with the Beta bootstrap contract; other canonical Node provider interfaces remain internal.<br>
+> **npm:** [`@pulse-compute/provider-node`](https://www.npmjs.com/package/@pulse-compute/provider-node)<br>
 > **Canonical replacement:** `provider: 'node' through @pulse-compute/cli`<br>
-> **Canonical documentation:** [Package guide](https://pulsecompute.io/v1.0.0-beta.1/packages/implementation-packages/)
+> **Canonical documentation:** [Package guide](https://pulsecompute.io/v1.0.0-beta.2/packages/implementation-packages/)
 >
-> This release-status block is generated from the synchronized `Pulse 1.0.0-beta.1` package policy.
+> This release-status block is generated from the synchronized `Pulse 1.0.0-beta.2` package policy.
 <!-- pulse-package-status:end -->
 
 Canonical Node provider implementation used internally when a project selects `provider: 'node'`.
@@ -59,4 +60,4 @@ The package exposes focused compiler and runtime modules for the synchronized
 repository, including `runtime/canonical-api-runtime`. Those exports are
 implementation interfaces, not application-author APIs.
 
-See [Contracts and providers](https://pulsecompute.io/v1.0.0-beta.1/concepts/contracts-and-providers/) and [Implementation packages](https://pulsecompute.io/v1.0.0-beta.1/packages/implementation-packages/).
+See [Contracts and providers](https://pulsecompute.io/v1.0.0-beta.2/concepts/contracts-and-providers/) and [Implementation packages](https://pulsecompute.io/v1.0.0-beta.2/packages/implementation-packages/).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulse-compute/provider-node",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "license": "Apache-2.0",
   "engines": {
     "node": "^22.14.0 || ^24.0.0"
@@ -42,12 +42,13 @@
     "./javascript/source-package": "./src/javascript/source-package.js"
   },
   "dependencies": {
-    "@pulse-compute/crypto": "1.0.0-beta.1",
-    "@pulse-compute/jwt": "1.0.0-beta.1",
-    "@pulse-compute/runtime": "1.0.0-beta.1",
-    "@pulse-compute/wasm-build-support": "1.0.0-beta.1",
-    "@pulse-compute/wasm-contracts": "1.0.0-beta.1",
-    "@pulse-compute/wasm-host-runtime": "1.0.0-beta.1"
+    "@pulse-compute/crypto": "1.0.0-beta.2",
+    "@pulse-compute/jwt": "1.0.0-beta.2",
+    "@pulse-compute/runtime": "1.0.0-beta.2",
+    "@pulse-compute/s3": "1.0.0-beta.2",
+    "@pulse-compute/wasm-build-support": "1.0.0-beta.2",
+    "@pulse-compute/wasm-contracts": "1.0.0-beta.2",
+    "@pulse-compute/wasm-host-runtime": "1.0.0-beta.2"
   },
   "publishConfig": {
     "access": "public"
@@ -63,7 +64,7 @@
     "url": "git+https://github.com/pulse-compute/pulse.git",
     "directory": "packages/provider-node"
   },
-  "homepage": "https://pulsecompute.io/v1.0.0-beta.1/packages/implementation-packages/",
+  "homepage": "https://pulsecompute.io/v1.0.0-beta.2/packages/implementation-packages/",
   "bugs": {
     "url": "https://github.com/pulse-compute/pulse/issues"
   }

package/src/capabilities.js

@@ -3,6 +3,7 @@
 const NODE_JWT_VERIFY_CAPABILITY = 'jwt.verify';
 
 const NODE_CANONICAL_PROVIDER_CAPABILITIES = Object.freeze([
+  's3.head', 's3.getText', 's3.putText',
   'request',
   'response.json',
   'response.text',
@@ -12,6 +13,7 @@ const NODE_CANONICAL_PROVIDER_CAPABILITIES = Object.freeze([
   'secret.get',
   'kv.get',
   'kv.put',
+  'kv.getVersioned', 'kv.insertIfAbsent', 'kv.compareAndSwap',
   'event.ingress',
   'event.emit',
   'assets.lookup',
@@ -30,8 +32,14 @@ const NODE_CANONICAL_PROVIDER_LOWERING = Object.freeze({
   'secret.get': 'node.runtime.secret.get',
   'kv.get': 'node.runtime.kv.get',
   'kv.put': 'node.runtime.kv.put',
+  'kv.getVersioned': 'node.runtime.kv.getVersioned',
+  'kv.insertIfAbsent': 'node.runtime.kv.insertIfAbsent',
+  'kv.compareAndSwap': 'node.runtime.kv.compareAndSwap',
   'event.ingress': 'node.event.reference.ingress',
   'event.emit': 'node.event.reference.accept',
+  's3.head': 'node.native.s3.head',
+  's3.getText': 'node.native.s3.getText',
+  's3.putText': 'node.native.s3.putText',
   'assets.lookup': 'node.runtime.assets.lookup',
   'grip.broadcast': 'node.http.grip.publish',
   [NODE_JWT_VERIFY_CAPABILITY]: 'node.native.jwt.verify',
@@ -39,6 +47,7 @@ const NODE_CANONICAL_PROVIDER_LOWERING = Object.freeze({
 });
 
 const NODE_NATIVE_TARGET_CAPABILITIES = Object.freeze([
+  's3.head', 's3.getText', 's3.putText',
   NODE_JWT_VERIFY_CAPABILITY,
   'jwt.verify.hs256',
   'jwt.verify.es256',

package/src/config/s3.js

@@ -0,0 +1,20 @@
+'use strict';
+const { normalizeBinding, namePattern } = require('@pulse-compute/s3/provider');
+function normalizeNodeS3(input = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input) || ![null, Object.prototype].includes(Object.getPrototypeOf(input))) throw new TypeError('Node S3 bindings must be a map.');
+  for (const key of Reflect.ownKeys(input)) {
+    const field = Object.getOwnPropertyDescriptor(input, key);
+    if (typeof key !== 'string' || !field.enumerable || !Object.hasOwn(field, 'value')) throw new TypeError('Node S3 bindings require data properties.');
+  }
+  return Object.freeze(Object.fromEntries(Object.entries(input).map(([name, value]) => {
+    if (!namePattern.test(name)) throw new TypeError('Node S3 logical binding name is invalid.');
+    return [name, normalizeBinding(value)];
+  })));
+}
+function validateNodeS3Operations(metadata, bindings) {
+  for (const effect of metadata.providerOperations || []) {
+    if (!['s3.head', 's3.getText', 's3.putText'].includes(effect.kind)) continue;
+    if (!bindings.s3 || !Object.hasOwn(bindings.s3, effect.resource && effect.resource.binding)) throw new TypeError('The required Node S3 binding is missing.');
+  }
+}
+module.exports = { normalizeNodeS3, validateNodeS3Operations };

package/src/javascript/bindings-adapter.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const { createNodeKvReference } = require('../runtime/conditional-kv.js');
 const runtimeHost = require('@pulse-compute/runtime/host');
 
 const NODE_JAVASCRIPT_BINDINGS_ADAPTER_VERSION = 'pulse.node-javascript-bindings-adapter.v1';
@@ -31,7 +32,7 @@ function recordEntries(input, label = 'binding record') {
 function createNodeJavascriptBindingCapabilities(options = {}) {
   const config = new Map();
   const secrets = new Map();
-  const stores = new Map();
+  const reference = options.kvReference || createNodeKvReference(options);
 
   for (const [rawName, rawValue] of recordEntries(options.config, 'config')) {
     const name = runtimeHost.normalizeBindingName('config', rawName, options);
@@ -41,22 +42,6 @@ function createNodeJavascriptBindingCapabilities(options = {}) {
     const name = runtimeHost.normalizeBindingName('secret', rawName, options);
     secrets.set(name, runtimeHost.normalizeBindingValue('secret.get', name, rawValue, options));
   }
-  for (const [rawNamespace, values] of recordEntries(options.kv, 'KV namespaces')) {
-    const namespace = runtimeHost.normalizeKvNamespace(rawNamespace, options);
-    const entries = new Map();
-    for (const [rawKey, value] of recordEntries(values, `KV namespace ${JSON.stringify(namespace)}`)) {
-      const key = runtimeHost.normalizeKvKey(rawKey, options);
-      entries.set(key, runtimeHost.cloneKvValue(value, options));
-    }
-    stores.set(namespace, entries);
-  }
-
-  function storeFor(namespaceInput) {
-    const namespace = runtimeHost.normalizeKvNamespace(namespaceInput, options);
-    if (!stores.has(namespace)) stores.set(namespace, new Map());
-    return Object.freeze({ namespace, store: stores.get(namespace) });
-  }
-
   return Object.freeze({
     version: NODE_JAVASCRIPT_BINDINGS_ADAPTER_VERSION,
     config(nameInput) {
@@ -67,23 +52,8 @@ function createNodeJavascriptBindingCapabilities(options = {}) {
       const name = runtimeHost.normalizeBindingName('secret', nameInput, options);
       return secrets.has(name) ? secrets.get(name) : undefined;
     },
-    kv(namespaceInput) {
-      const { store } = storeFor(namespaceInput);
-      return Object.freeze({
-        get(keyInput) {
-          const key = runtimeHost.normalizeKvKey(keyInput, options);
-          return runtimeHost.cloneKvValue(store.has(key) ? store.get(key) : undefined, {
-            ...options,
-            allowUndefined: true
-          });
-        },
-        put(keyInput, value) {
-          const key = runtimeHost.normalizeKvKey(keyInput, options);
-          store.set(key, runtimeHost.cloneKvValue(value, options));
-          return true;
-        }
-      });
-    }
+    prepareConditionalKv: reference.prepareConditionalKv,
+    kv: reference.kv
   });
 }
 
@@ -97,7 +67,7 @@ function withNodeBindingCapabilities(capabilities, options = {}) {
   const configured = options.bindings || createNodeJavascriptBindingCapabilities(options);
   if (needsConfig) output.config = configured.config;
   if (needsSecret) output.secret = configured.secret;
-  if (needsKv) output.kv = configured.kv;
+  if (needsKv) { output.kv = configured.kv; output.prepareConditionalKv = configured.prepareConditionalKv; }
   return Object.freeze(output);
 }
 

package/src/javascript/node-adapter.js

@@ -179,6 +179,7 @@ function createNodeJavascriptHandler(application, options = {}) {
         config: options.config,
         secrets: options.secrets,
         kv: options.kv,
+        kvReference: options.kvReference,
         maxBindingNameBytes: options.maxBindingNameBytes,
         maxBindingValueBytes: options.maxBindingValueBytes,
         maxKvNamespaceBytes: options.maxKvNamespaceBytes,
@@ -203,6 +204,7 @@ function createNodeJavascriptHandler(application, options = {}) {
     const kv = hasDynamicBindings ? await resolveRequestOption(options.kv, requestContext) : options.kv;
     const bindings = staticBindings || createNodeJavascriptBindingCapabilities({
       config, secrets, kv,
+      kvReference: options.kvReference,
       maxBindingNameBytes: options.maxBindingNameBytes,
       maxBindingValueBytes: options.maxBindingValueBytes,
       maxKvNamespaceBytes: options.maxKvNamespaceBytes,
@@ -234,6 +236,7 @@ function createNodeJavascriptHandler(application, options = {}) {
       assets: options.assets,
       grip: options.grip,
       maxEffects: options.maxEffects,
+      kvClock: options.kvClock, deadlineMonotonicMs: options.deadlineMonotonicMs,
       maxRequestBodyBytes: options.maxRequestBodyBytes ?? options.maxBodyBytes,
       maxFetchBodyBytes: options.maxFetchBodyBytes,
       maxStructuredBodyBytes: options.maxStructuredBodyBytes,

package/src/javascript/package-effects.js

@@ -31,9 +31,14 @@ function createNodeJavascriptPackageEffectCapabilities(options = {}) {
   const assetsLookup = options.assetsLookup || (options.assets && options.assets.lookup);
   const gripBroadcast = options.gripBroadcast || (options.grip && options.grip.broadcast);
   const jwtVerify = options.jwtVerify || (options.jwt && options.jwt.verify);
+  const s3 = options.s3;
   return Object.freeze({
     version: NODE_JAVASCRIPT_PACKAGE_EFFECTS_VERSION,
     async effect(effect, execution) {
+      if (effect && effect.contractId === 'pulse.s3') {
+        if (typeof s3 !== 'function') return unavailable(effect);
+        return s3(effect, execution);
+      }
       if (effect && effect.contractId === 'pulse.assets' && effect.operation === 'lookup') {
         if (typeof assetsLookup !== 'function') return unavailable(effect);
         return assetsLookup(effect.payload, execution);
@@ -61,6 +66,7 @@ function withNodePackageEffectCapabilities(capabilities, options = {}) {
         effect.contractId === 'pulse.assets'
         || effect.contractId === 'pulse.grip'
         || effect.contractId === 'pulse.jwt'
+        || effect.contractId === 'pulse.s3'
       )) {
         return packageCapabilities.effect(effect, execution);
       }

package/src/javascript/runtime-host.js

@@ -10,6 +10,7 @@ const { createNodeJavascriptFixtureFetch, withNodeFetchCapability } = require('.
 const { createNodeJavascriptAssetsLookup } = require('./assets-adapter.js');
 const { createNodeJavascriptGripBroadcast } = require('./grip-broadcast.js');
 const { createNodeJavascriptJwtVerify } = require('./jwt-verifier.js');
+const { createNodeJavascriptS3 } = require('./s3.js');
 const { createNodeJavascriptPackageEffectCapabilities, withNodePackageEffectCapabilities } = require('./package-effects.js');
 const { NODE_JAVASCRIPT_TARGET_DESCRIPTOR } = require('./target.js');
 
@@ -34,6 +35,7 @@ function nodeJavascriptProviderCapabilities(options) {
     ...(Object.prototype.hasOwnProperty.call(options, 'config') ? { config: options.config } : {}),
     ...(Object.prototype.hasOwnProperty.call(options, 'secrets') ? { secrets: options.secrets } : {}),
     ...(Object.prototype.hasOwnProperty.call(options, 'kv') ? { kv: options.kv } : {}),
+    kvReference: options.kvReference, kvInstanceId: options.kvInstanceId, kvGenerationStart: options.kvGenerationStart, kvHooks: options.kvHooks,
     maxBindingNameBytes: options.maxBindingNameBytes,
     maxBindingValueBytes: options.maxBindingValueBytes,
     maxKvNamespaceBytes: options.maxKvNamespaceBytes,
@@ -65,6 +67,7 @@ function nodeJavascriptProviderCapabilities(options) {
       assetsLookup: configuredAssetsLookup,
       gripBroadcast: configuredGripBroadcast,
       jwtVerify: configuredJwtVerify,
+      s3: createNodeJavascriptS3(options, bindingCapabilities.secret),
       assets: options.assets,
       grip: options.grip
     }
@@ -87,6 +90,7 @@ async function executeNodeJavascriptApplication(application, request, options =
     application: options.application,
     requestHeaders: options.requestHeaders,
     signal: options.signal,
+    kvClock: options.kvClock, deadlineMonotonicMs: options.deadlineMonotonicMs,
     maxEffects: options.maxEffects,
     maxRequestBodyBytes: options.maxRequestBodyBytes,
     maxFetchBodyBytes: options.maxFetchBodyBytes,
@@ -118,6 +122,7 @@ async function executeNodeJavascriptEvent(application, frame, options = {}) {
     effectAdapter: options.effectAdapter,
     application: options.application,
     signal: options.signal,
+    kvClock: options.kvClock, deadlineMonotonicMs: options.deadlineMonotonicMs,
     maxEffects: options.maxEffects,
     maxBindingNameBytes: options.maxBindingNameBytes,
     maxBindingValueBytes: options.maxBindingValueBytes,

package/src/javascript/s3.js

@@ -0,0 +1,21 @@
+'use strict';
+const { bindJavascriptDigestMac } = require('@pulse-compute/crypto/provider');
+const { normalizeNodeS3 } = require('../config/s3.js');
+const { readS3 } = require('../runtime/s3-reader.js');
+
+function createNodeJavascriptS3(options, secretLookup) {
+  const s3 = normalizeNodeS3(options.s3 || options.bindings && options.bindings.s3);
+  return (effect, execution = {}) => {
+    // This provider target explicitly selects Crypto's Web Crypto realization.
+    // Native execution supplies its own Wasm exports to the same Node transport.
+    let selected;
+    try { selected = bindJavascriptDigestMac(['SHA-256', 'HMAC-SHA256']); }
+    catch { selected = null; }
+    return readS3(effect, {
+      s3, signal: execution.signal, registerRedactionValue: execution.registerRedactionValue,
+      fetchImplementation: options.fetchImplementation, cryptoTarget: 'javascript',
+      cryptoVerifier: selected, cryptoRealization: selected && selected.realization
+    }, (name) => secretLookup(name, execution));
+  };
+}
+module.exports = { createNodeJavascriptS3 };

package/src/javascript/target-support-policy.js

@@ -10,6 +10,7 @@ function decision(id, status, reasonId, owner, required = true) {
 
 function classifyNodeJavascriptCapability(id, options = {}) {
   const capability = String(id);
+  if (['s3.head', 's3.getText', 's3.putText'].includes(capability)) return decision(capability, 'eligible', 'node-s3-bounded-origin-transport', 'provider-node');
   if (isJavascriptCoreCapability(capability)) {
     return decision(capability, 'eligible', 'node-router-context-parity', 'provider-node');
   }
@@ -75,6 +76,7 @@ function classifyNodeJavascriptCapability(id, options = {}) {
 
 function classifyNodeJavascriptProviderRequirement(id, compilerCapabilities, options = {}) {
   const requirement = String(id);
+  if (['s3.head', 's3.getText', 's3.putText'].includes(requirement)) return decision(requirement, 'eligible', 'node-s3-bounded-origin-transport', 'provider-node');
   if (requirement === 'request') {
     const bodyRequired = compilerCapabilities.some((entry) => entry === 'request.json' || entry.startsWith('request.body'));
     return bodyRequired
@@ -87,7 +89,7 @@ function classifyNodeJavascriptProviderRequirement(id, compilerCapabilities, opt
   if (requirement === 'fetch' || requirement === 'opaque.pass-through' || ['body', 'headers', 'result'].includes(requirement)) {
     return decision(requirement, 'eligible', 'javascript-fetch-projection-realization', 'runtime');
   }
-  if (['config.get', 'secret.get', 'kv.get', 'kv.put'].includes(requirement)) {
+  if (['config.get', 'secret.get', 'kv.get', 'kv.put', 'kv.getVersioned', 'kv.insertIfAbsent', 'kv.compareAndSwap'].includes(requirement)) {
     return options.bindingsRedaction === true
       ? decision(requirement, 'eligible', 'javascript-binding-redaction-implemented', 'provider-node')
       : decision(requirement, 'pending', 'javascript-binding-effect-pending', 'provider-node');

package/src/javascript/target.js

@@ -17,7 +17,7 @@ const NODE_JAVASCRIPT_TARGET_DESCRIPTOR = normalizeJavascriptTargetDescriptor({
   },
   crypto: defineCryptoTargetCapabilities({
     target: 'javascript',
-    algorithms: [{
+    algorithms: [...['SHA-256', 'HMAC-SHA256'].map((algorithm) => ({ algorithm, realization: 'runtime-builtin', implemented: true, status: 'implemented-o3' })), {
       algorithm: 'HS256',
       realization: 'runtime-builtin',
       implemented: true,

package/src/javascript/test-runtime.js

@@ -52,6 +52,7 @@ async function executeNodeJavascriptTestCase(application, testCase, options = {}
     jwtCaptureWallClock: options.jwtCaptureWallClock,
     config: testCase.config || {},
     secrets: testCase.secrets || {},
+    s3: options.s3 || options.bindings && options.bindings.s3,
     kv: testCase.kv || {},
     application: options.application,
     requestHeaders: adapted.headerPairs,

package/src/native/target.js

@@ -60,7 +60,7 @@ const NODE_NATIVE_TARGET_DESCRIPTOR = Object.freeze({
   automaticFallback: false,
   crypto: defineCryptoTargetCapabilities({
     target: 'native',
-    algorithms: [{
+    algorithms: [...['SHA-256', 'HMAC-SHA256'].map((algorithm) => ({ algorithm, realization: 'guest-source:pulse-hmac-as', implemented: true, status: 'implemented-o2' })), {
       algorithm: 'HS256',
       realization: 'guest-source:pulse-hmac-as',
       implemented: true,

package/src/runtime/canonical-api-runtime.js

@@ -1,4 +1,5 @@
 'use strict';
+const { createNodeKvReference } = require('./conditional-kv.js');
 
 const path = require('node:path');
 const { Readable } = require('node:stream');
@@ -361,6 +362,7 @@ function effectToProviderEffect(normalized) {
 
 function createNodeProviderAdapter(baseOptions = {}) {
   const kvExecutions = new Map();
+  const sharedKv = baseOptions.kvReference || createNodeKvReference(baseOptions);
   const verifyNativeJwt = createNodeNativeJwtVerify({
     captureWallClock: baseOptions.captureJwtWallClock,
     secretLookup(name, executionOptions) {
@@ -449,29 +451,14 @@ function createNodeProviderAdapter(baseOptions = {}) {
     };
   }
 
-  function kvStoresFor(executionOptions) {
+  function kvReferenceFor(executionOptions) {
+    if (executionOptions.kvReference) return executionOptions.kvReference;
+    if (!Object.prototype.hasOwnProperty.call(executionOptions, 'kv') || executionOptions.kv === baseOptions.kv) return sharedKv;
     const executionId = String(executionOptions.executionId || 'default');
-    if (!kvExecutions.has(executionId)) {
-      const stores = new Map();
-      const limits = bindingOptions(executionOptions);
-      for (const [rawName, values] of recordEntries(valuesFor(executionOptions, 'kv'), 'KV namespace record')) {
-        const name = portableRuntimeHost.normalizeKvNamespace(rawName, limits);
-        const entries = new Map();
-        for (const [rawKey, value] of recordEntries(values, `KV namespace ${JSON.stringify(name)}`)) {
-          const key = portableRuntimeHost.normalizeKvKey(rawKey, limits);
-          entries.set(key, portableRuntimeHost.cloneKvValue(value, {
-            operation: 'seed',
-            maxBytes: limits.maxKvValueBytes,
-            maxDepth: limits.maxKvValueDepth,
-            maxEntries: limits.maxKvValueEntries
-          }));
-        }
-        stores.set(name, entries);
-      }
-      kvExecutions.set(executionId, stores);
-    }
+    if (!kvExecutions.has(executionId)) kvExecutions.set(executionId, createNodeKvReference({ ...baseOptions, ...executionOptions, ...bindingOptions(executionOptions) }));
     return kvExecutions.get(executionId);
   }
+  function kvStoresFor(executionOptions) { return kvReferenceFor(executionOptions).legacyStores(); }
 
   async function dispatchFetch(normalized, executionOptions = {}) {
     const fetchFixtures = normalizeFetchFixtures(executionOptions.fetches || baseOptions.fetches);
@@ -505,6 +492,7 @@ function createNodeProviderAdapter(baseOptions = {}) {
   }
 
   return Object.freeze({
+    prepareConditionalKv(effect, execution) { return kvReferenceFor(execution).prepareConditionalKv(effect, execution); },
     id: 'node',
     version: CANONICAL_NODE_RUNTIME_VERSION,
     createCapabilities() { return {}; },
@@ -513,6 +501,9 @@ function createNodeProviderAdapter(baseOptions = {}) {
     },
     dispatchFetch,
     async dispatchEffect(effect, executionOptions = {}) {
+      if (['s3.head', 's3.getText', 's3.putText'].includes(effect.kind)) {
+        return require('./s3-reader.js').readS3(effect, { ...baseOptions, ...executionOptions }, (name) => bindingValue(executionOptions, 'secrets', name));
+      }
       if (effect.kind === 'fetch') return dispatchFetch(effect, executionOptions);
       if (effect.kind === 'jwt.verify') return verifyNativeJwt(effect, executionOptions);
       if (effect.kind === 'grip.broadcast') {
@@ -543,28 +534,9 @@ function createNodeProviderAdapter(baseOptions = {}) {
         );
       }
       if (effect.kind === 'kv.get' || effect.kind === 'kv.put') {
-        const limits = bindingOptions(executionOptions);
-        const namespace = portableRuntimeHost.normalizeKvNamespace(effect.store, limits);
-        const key = portableRuntimeHost.normalizeKvKey(effect.key, limits);
-        const stores = kvStoresFor(executionOptions);
-        if (!stores.has(namespace)) stores.set(namespace, new Map());
-        const store = stores.get(namespace);
-        if (effect.kind === 'kv.get') {
-          return portableRuntimeHost.cloneKvValue(store.get(key), {
-            operation: 'get',
-            allowUndefined: true,
-            maxBytes: bindingOptions(executionOptions).maxKvValueBytes,
-            maxDepth: bindingOptions(executionOptions).maxKvValueDepth,
-            maxEntries: bindingOptions(executionOptions).maxKvValueEntries
-          });
-        }
-        store.set(key, portableRuntimeHost.cloneKvValue(effect.value, {
-          operation: 'put',
-          maxBytes: bindingOptions(executionOptions).maxKvValueBytes,
-          maxDepth: bindingOptions(executionOptions).maxKvValueDepth,
-          maxEntries: bindingOptions(executionOptions).maxKvValueEntries
-        }));
-        return true;
+        const namespace = portableRuntimeHost.normalizeKvNamespace(effect.store, bindingOptions(executionOptions));
+        const store = kvReferenceFor(executionOptions).kv(namespace);
+        return effect.kind === 'kv.get' ? store.get(effect.key) : store.put(effect.key, effect.value);
       }
       if (effect.kind === 'event.emit') {
         const eventAdapter = executionOptions.eventAdapter || baseOptions.eventAdapter;

package/src/runtime/conditional-kv.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const { randomUUID } = require('node:crypto');
+const host = require('@pulse-compute/runtime/host');
+
+// One explicit instance is one local authority. Reuse it across requests/targets
+// to exercise shared storage. Identity/sequence injection is for deterministic
+// host tests, never application input. This is not durable production storage.
+function createNodeKvReference(options = {}) {
+  const identity = options.kvInstanceId === undefined ? randomUUID() : options.kvInstanceId;
+  if (typeof identity !== 'string' || !/^[a-zA-Z0-9_-]{1,64}$/.test(identity)) throw new TypeError('Node KV instance identity must be bounded ASCII.');
+  let sequence = options.kvGenerationStart === undefined ? 0n : BigInt(options.kvGenerationStart);
+  if (sequence < 0n || sequence >= (1n << 128n)) throw new TypeError('Node KV generation sequence is out of range.');
+  const stores = new Map(), records = new Map();
+  const hooks = options.kvHooks || {};
+  function nextGeneration() {
+    if (sequence >= (1n << 128n) - 1n) throw new Error('Node KV generation space exhausted.');
+    sequence += 1n;
+    return `node-kv-v1:${identity}:${sequence.toString(16).padStart(32, '0')}`;
+  }
+  function namespace(name) {
+    host.normalizeKvNamespace(name, options);
+    if (!stores.has(name)) { stores.set(name, new Map()); records.set(name, new Map()); }
+    return { values: stores.get(name), entries: records.get(name) };
+  }
+  function put(name, key, value) {
+    const { entries, values } = namespace(name);
+    const wire = host.encodeConditionalKvValue(value, options);
+    const detached = host.decodeConditionalKvValue(wire, options);
+    const generation = nextGeneration();
+    entries.set(key, { wire, generation }); values.set(key, detached);
+  }
+  // Reject accessors instead of executing configuration as ambient code.
+  function entries(input) {
+    if (input === undefined || input === null) return [];
+    if (typeof input !== 'object' || Array.isArray(input) || ![null, Object.prototype].includes(Object.getPrototypeOf(input))) throw new TypeError('Node KV seed must be a data record.');
+    return Reflect.ownKeys(input).map((key) => {
+      const d = Object.getOwnPropertyDescriptor(input, key);
+      if (typeof key !== 'string' || !d.enumerable || !Object.prototype.hasOwnProperty.call(d, 'value')) throw new TypeError('Node KV seed must contain data properties.');
+      return [key, d.value];
+    });
+  }
+  for (const [name, values] of entries(options.kv)) for (const [key, value] of entries(values)) {
+    host.normalizeKvKey(key, options); put(name, key, value);
+  }
+  function apply(effect) {
+    const { entries } = namespace(effect.namespace);
+    const current = entries.get(effect.key);
+    if (effect.kind === 'kv.getVersioned') return current
+      ? Object.freeze({ status: 'found', generation: current.generation, value: host.decodeConditionalKvValue(current.wire, options) })
+      : Object.freeze({ status: 'not-found' });
+    if (effect.kind === 'kv.compareAndSwap' && !new RegExp(`^node-kv-v1:${identity}:[0-9a-f]{32}$`).test(effect.generation)) {
+      return Object.freeze({ status: 'not-stored', reason: 'invalid-generation' });
+    }
+    // No await, callback, or provider GET/PUT between predicate and mutation.
+    const matches = effect.kind === 'kv.insertIfAbsent' ? !current : current && current.generation === effect.generation;
+    if (!matches) return Object.freeze({ status: 'conflict' });
+    put(effect.namespace, effect.key, effect.value);
+    return Object.freeze({ status: 'stored' });
+  }
+  async function prepareConditionalKv(effect, execution = {}) {
+    if (hooks.prepare) await hooks.prepare(effect, execution);
+    return async () => {
+      if (hooks.dispatch) await hooks.dispatch(effect, execution);
+      if (execution.signal && execution.signal.aborted) throw new Error('Node KV operation stopped before acceptance.');
+      const result = apply(effect);
+      if (result.status === 'found' && hooks.read) return hooks.read(result, effect, execution);
+      if (result.status === 'stored' && hooks.afterCommit) await hooks.afterCommit(effect, execution);
+      return result;
+    };
+  }
+  return Object.freeze({
+    version: 'pulse.node-kv-reference.v1',
+    prepareConditionalKv,
+    // Historical Assets reads use this semantic view, never the generation table.
+    legacyStores() { return stores; },
+    kv(name) {
+      const { values } = namespace(name);
+      const conditional = (operation, key, generation, value) => {
+        const admitted = host.admitConditionalKv({ kind: `kv.${operation}`, namespace: name, key, generation, value }, options);
+        return host.executeConditionalKv(admitted, prepareConditionalKv, {}, options);
+      };
+      return Object.freeze({
+        get(key) { host.normalizeKvKey(key, options); return host.cloneKvValue(values.get(key), { ...options, allowUndefined: true }); },
+        put(key, value) { host.normalizeKvKey(key, options); put(name, key, value); return true; },
+        getVersioned(key) { return conditional('getVersioned', key); },
+        insertIfAbsent(key, value) { return conditional('insertIfAbsent', key, undefined, value); },
+        compareAndSwap(key, generation, value) { return conditional('compareAndSwap', key, generation, value); }
+      });
+    }
+  });
+}
+module.exports = Object.freeze({ createNodeKvReference });

package/src/runtime/index.js

@@ -6,6 +6,7 @@ const routeHandlerEffects = require('./route-handler-effects.js');
 const canonicalApiRuntime = require('./canonical-api-runtime.js');
 
 module.exports = {
+  ...require('./conditional-kv.js'),
   compiledWasmNodeAdapterKv,
   assetsProvider,
   routeHandlerEffects,

package/src/runtime/s3-reader.js

@@ -0,0 +1,131 @@
+'use strict';
+const https = require('node:https');
+const { Readable } = require('node:stream');
+const { performance } = require('node:perf_hooks');
+const protocol = require('@pulse-compute/s3/provider');
+
+function originRequest(request, signal) {
+  return new Promise((resolve, reject) => {
+    const req = https.request(request.url, { method: request.method, headers: request.headers, signal, maxHeaderSize: 16384 }, (response) => {
+      let headers = [];
+      try {
+        const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+        // Node exposes HTTP header octets as Latin-1 strings. Interpret the
+        // bounded protocol metadata as UTF-8, matching the Native host ABI.
+        for (let i = 0; i < response.rawHeaders.length; i += 2) headers.push([response.rawHeaders[i], decoder.decode(Buffer.from(response.rawHeaders[i + 1], 'latin1'))]);
+      } catch { headers = null; }
+      resolve({ status: response.statusCode, headers, body: response, close: () => response.destroy() });
+    });
+    req.once('error', reject);
+    req.end(request.body);
+  });
+}
+async function fetchFixture(fetch, request, signal) {
+  const pending = Promise.resolve().then(() => fetch(request.url, { method: request.method, headers: request.headers, ...(request.body === undefined ? {} : { body: request.body }), redirect: 'manual', cache: 'no-store', signal }));
+  pending.then((response) => { if (signal.aborted && response.body) void response.body.cancel().catch(() => {}); }, () => {});
+  const response = await abortable(pending, signal);
+  const body = response.body ? Readable.fromWeb(response.body, { signal }) : null;
+  // A deadline can fire before iteration begins; always observe the stream error.
+  if (body) body.on('error', () => {});
+  return { status: response.status, headers: [...response.headers], body, close: () => { if (body) body.destroy(); } };
+}
+function abortable(promise, signal) {
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    signal.addEventListener('abort', abort, { once: true });
+    promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+    if (signal.aborted) abort();
+  });
+}
+async function readS3(effect, options, lookup) {
+  const operation = effect.operation, put = operation === 'putText';
+  const payload = effect.payload || {};
+  if (!['head', 'getText', 'putText'].includes(operation) || effect.kind !== `s3.${operation}` || effect.capability !== effect.kind
+    || effect.package !== '@pulse-compute/s3' || effect.contractId !== 'pulse.s3' || effect.providerKind !== 's3') throw new TypeError('Invalid S3 package effect authority.');
+  let dispatched = false, status;
+  const failure = (reason) => put ? protocol.putFailure(reason, dispatched, status) : protocol.failure(reason, status);
+  if (options.signal && options.signal.aborted) throw options.signal.reason || new Error('Request cancelled.');
+  const configured = typeof payload.binding === 'string' && options.s3 && Object.hasOwn(options.s3, payload.binding) && options.s3[payload.binding];
+  let binding;
+  try { binding = protocol.normalizeBinding(configured); } catch { return failure('configuration'); }
+  const controller = new AbortController();
+  const onAbort = () => controller.abort(options.signal.reason);
+  if (options.signal) options.signal.addEventListener('abort', onAbort, { once: true });
+  let timedOut = false;
+  const deadline = performance.now() + binding.timeoutMs;
+  const check = () => {
+    if (performance.now() >= deadline) { timedOut = true; controller.abort(); }
+    if (controller.signal.aborted) throw controller.signal.reason || new Error('S3 deadline expired.');
+  };
+  const timer = setTimeout(() => { timedOut = true; controller.abort(); }, binding.timeoutMs);
+  const wait = async (value) => { const result = await abortable(Promise.resolve(value), controller.signal); check(); return result; };
+  let response;
+  try {
+    const key = protocol.encodeKey(payload.key);
+    if (key === null) return failure('invalid-key');
+    let body, contentType;
+    if (put) {
+      if (typeof payload.text !== 'string' || !payload.text.isWellFormed()) return failure('invalid-text');
+      body = protocol.bytes(payload.text);
+      if (body.length > binding.maxTextBytes) return failure('too-large');
+      try { contentType = protocol.normalizePutOptions({ contentType: payload.contentType }).contentType; }
+      catch { return failure('configuration'); }
+    }
+    let accessId, secret, token;
+    try {
+      accessId = await wait(lookup(binding.accessKeyIdSecret));
+      secret = await wait(lookup(binding.secretAccessKeySecret));
+      token = binding.sessionTokenSecret === undefined ? undefined : await wait(lookup(binding.sessionTokenSecret));
+    } catch (error) { check(); return failure('credentials'); }
+    if (!protocol.credentialsValid(accessId, secret, token)) return failure('credentials');
+    for (const value of [accessId, secret, token]) if (typeof options.registerRedactionValue === 'function' && typeof value === 'string') options.registerRedactionValue(value);
+    const crypto = options.cryptoVerifier && options.cryptoVerifier.bytes;
+    const algorithms = options.cryptoRealization && options.cryptoRealization.algorithms;
+    const realization = options.cryptoTarget === 'javascript' ? 'runtime-builtin' : 'guest-source:pulse-hmac-as';
+    if (!crypto || !Array.isArray(algorithms) || ['SHA-256', 'HMAC-SHA256'].some((algorithm) => !algorithms.some((entry) => entry.algorithm === algorithm && entry.available && entry.realization === realization))) return failure('configuration');
+    let request;
+    try {
+      request = await wait(protocol.signRequest({ binding, method: put ? 'PUT' : operation === 'head' ? 'HEAD' : 'GET', encodedKey: key, accessId, secret, token, now: Date.now(), body, contentType }, crypto));
+    } catch (error) { check(); return failure('configuration'); }
+    check();
+    // The send primitive may have side effects even if it throws synchronously.
+    dispatched = true;
+    response = options.fetchImplementation
+      ? await fetchFixture(options.fetchImplementation, request, controller.signal)
+      : await originRequest(request, controller.signal);
+    status = response.status;
+    check();
+    const rejected = put ? protocol.putStatusResult(status) : protocol.statusResult(status);
+    if (rejected && (!put || rejected.status === 'unknown')) return rejected;
+    const metadata = protocol.metadataFromHeaders(response.headers, operation === 'head');
+    if (!metadata) return failure('protocol');
+    if (operation === 'head') return protocol.normalizeResult(operation, { status: 'found', ...metadata });
+    const maximum = put ? rejected ? binding.maxTextBytes : 0 : binding.maxTextBytes;
+    if (metadata.byteLength > maximum) return failure(put ? 'protocol' : 'too-large');
+    const chunks = []; let total = 0;
+    if (response.body) for await (const chunk of response.body) {
+      check(); total += chunk.length;
+      if (total > maximum) return failure(put ? 'protocol' : 'too-large');
+      if (!put) chunks.push(Buffer.from(chunk));
+    }
+    check();
+    if (metadata.byteLength !== undefined && metadata.byteLength !== total) return failure('protocol');
+    if (put) return rejected || protocol.normalizeResult(operation, { status: 'stored', byteLength: body.length, sha256: request.headers['x-amz-content-sha256'], ...(metadata.etag === undefined ? {} : { etag: metadata.etag }) });
+    const raw = Buffer.concat(chunks, total);
+    const digest = protocol.hex(await wait(crypto.sha256(raw)));
+    let text;
+    try { text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(raw); }
+    catch { return failure('invalid-utf8'); }
+    check();
+    return protocol.normalizeResult(operation, { status: 'found', ...metadata, byteLength: total, text, sha256: digest });
+  } catch (error) {
+    if (options.signal && options.signal.aborted) throw options.signal.reason || error;
+    return failure(timedOut ? 'timeout' : status === undefined ? 'transport' : 'protocol');
+  } finally {
+    clearTimeout(timer);
+    if (options.signal) options.signal.removeEventListener('abort', onAbort);
+    controller.abort();
+    if (response) { try { await response.close(); } catch {} }
+  }
+}
+module.exports = { readS3, originRequest };

package/src/toolchain.js

@@ -32,8 +32,11 @@ const reportingTargetCapability = Object.freeze({
   levels: Object.freeze(['off', 'error', 'warn', 'info', 'debug'])
 });
 
-function genericProviderConfig() {
-  return Object.freeze({ kind: 'node', bindings: Object.freeze({}), local: Object.freeze({}) });
+function genericProviderConfig(value) {
+  const input = value && typeof value === 'object' ? value : {};
+  const bindings = input.bindings || {};
+  if (Object.keys(bindings).some((key) => key !== 's3')) throw new TypeError('Unknown Node binding field.');
+  return Object.freeze({ kind: 'node', bindings: Object.freeze({ s3: require('./config/s3.js').normalizeNodeS3(bindings.s3) }), local: Object.freeze({}) });
 }
 
 function nodeRealization(nativeArtifact) {
@@ -139,14 +142,21 @@ function createDriver() {
     sourceOnlySupported: false,
     targetSupport: Object.freeze({ javascript: NODE_JAVASCRIPT_TARGET_SUPPORT_DECLARATION }),
     normalizeConfig: genericProviderConfig,
+    configReference: Object.freeze({
+      sections: [{ id: 'node', title: 'Node provider options', description: 'Provider-owned Node profile configuration.' }],
+      fields: [{ section: 'node', path: 'node.bindings.s3', type: 'Readonly<Record<string, S3Binding>>', default: '`{}`', scope: 'Node Native and JavaScript S3',
+        description: 'Maps literal logical names to fixed HTTPS endpoint, bucket, region, accessKeyIdSecret, secretAccessKeySecret, optional sessionTokenSecret, maxTextBytes (1–32768, default 32768) and timeoutMs (1–30000, default 10000).',
+        security: 'Only named credential references are configuration. Runtime keys cannot override authority.' }]
+    }),
     defaultLocalNetworkFetch: true,
-    projectConfigDocument() { return undefined; },
+    projectConfigDocument(config) { return Object.keys(config.bindings.s3).length ? config : undefined; },
     initTemplate() {
       return Object.freeze({ profileFragment: '', dependencies: Object.freeze({}) });
     },
-    executionOptions(_config, values) {
+    executionOptions(config, values) {
       return Object.freeze({
         ...values,
+        s3: config.bindings.s3,
         providerAdapter: nodeRuntime.createNodeProviderAdapter()
       });
     },
@@ -205,7 +215,8 @@ function createDriver() {
       javascript: NODE_JAVASCRIPT_TARGET_DESCRIPTOR
     }),
     execute: nodeRuntime.executeCanonicalProgram,
-    createLoweringPlan(metadata) {
+    createLoweringPlan(metadata, config = {}) {
+      require('./config/s3.js').validateNodeS3Operations(metadata, config.bindings || {});
       return canonicalProvider.createProviderLoweringPlan(metadata, nodeRuntime.NODE_PROVIDER_DESCRIPTOR, {
         grip: 'node-reference-broadcaster'
       });