@pulse-compute/s3 0.0.0 → 1.0.0-beta.2

package/README.md

@@ -1,5 +1,83 @@
 # @pulse-compute/s3
 
-> Bootstrap placeholder — no runtime or API.
+<!-- pulse-package-status:start -->
+> **Support tier:** Supported provider/extension surface<br>
+> **Audience:** Applications using bounded exact-key object reads and writes through Pulse effects.<br>
+> **Install directly:** Yes, when an application uses S3 object operations.<br>
+> **Supported entry points:** `@pulse-compute/s3`<br>
+> **Stability:** The package root supports head, getText and putText on Node Native, Node JavaScript and Fastly Native. Fastly JavaScript is ineligible. Provider and lowering subpaths are toolchain-only; live origin acceptance is separate.<br>
+> **npm:** [`@pulse-compute/s3`](https://www.npmjs.com/package/@pulse-compute/s3)<br>
+> **Canonical documentation:** [Package guide](https://pulsecompute.io/v1.0.0-beta.2/packages/s3/)
+>
+> This release-status block is generated from the synchronized `Pulse 1.0.0-beta.2` package policy.
+<!-- pulse-package-status:end -->
 
-This inert 0.0.0 package reserves the npm name for future Pulse releases.
+This package provides bounded, exact-key `head`, `getText` and `putText` effects for
+Node Native, Node JavaScript and Fastly Native. Await an operation into a local
+variable or use it directly in keyed `ctx.parallel`. The binding is a literal
+logical name; key and text may be runtime strings.
+
+Providers own fixed HTTPS origin, bucket, region, named credential references,
+deadline and transport. Fastly additionally requires a named static backend.
+Crypto selection must include `SHA-256` and `HMAC-SHA256`. Crypto owns the
+digest and MAC primitives; S3 owns signing and exact object semantics.
+
+Put mappings under `<profile>.node.bindings.s3` or
+`<profile>.fastly.bindings.s3`. A logical `objects` entry has these fields:
+
+| Field | Value |
+| --- | --- |
+| `endpoint` | Fixed HTTPS origin, for example `https://objects.example.invalid` |
+| `bucket`, `region` | Explicit bucket and signing region |
+| `accessKeyIdSecret`, `secretAccessKeySecret` | Named provider secret references |
+| `sessionTokenSecret` | Optional named session-token reference |
+| `maxTextBytes` | 1–32768; default 32768 |
+| `timeoutMs` | 1–30000; default 10000 |
+| `backend` | Fastly-only named static backend |
+
+The profile declares `crypto: ['SHA-256', 'HMAC-SHA256']`. A read looks like
+`const object = await s3.getText(ctx, 'objects', key)` inside a handler.
+
+GET accepts at most 32,768 raw bytes and strictly decodes UTF-8, preserving a BOM.
+It returns the raw-byte SHA-256 digest and byte length with optional opaque ETag
+and content type. HEAD requires a safe integer Content-Length but does not read a
+body. A 404 returns `not-found`; other failures return a bounded reason and an
+HTTP status when observed. Redirects, compression, retries and caching are disabled.
+
+PUT accepts scalar text encoded once as UTF-8, including empty text, up to the
+binding's byte limit. Use `const result = await s3.putText(ctx, 'objects', key,
+text, { contentType: 'application/json' })`. Options are literal metadata; they
+do not serialize text. The default content type is `text/plain; charset=utf-8`.
+A complete 200 acknowledgement with an empty bounded body returns `stored`,
+sent byte length, SHA-256 and optional opaque ETag. The digest identifies sent
+bytes; it is not an origin durability receipt.
+
+Before dispatch, validation, credential, signing and deadline failures return
+`not-stored`. A complete explicit 4xx rejection, except 408, also returns
+`not-stored`. After entering send, transport loss, timeout, unavailable origin
+or malformed acknowledgement returns `unknown`: bytes may already be stored.
+There are no retries. Cancellation terminates the operation through the existing
+request lifecycle; it does not return an S3 outcome or promise rollback. Fastly
+has no pending-request cancel hostcall; invocation termination owns its release.
+
+Node JavaScript explicitly uses Crypto's bounded Web Crypto byte realization.
+Native targets compose Crypto's AssemblyScript primitives. Fastly JavaScript S3
+is ineligible because its SDK projects raw headers and loses required metadata
+information. This target exclusion does not gate supported targets.
+
+For a JSON request carrying the maximum text consisting of escaped control
+characters, configure the existing `schemas.maxBytes` request envelope to
+262144; the object itself remains bounded to 32768 UTF-8 bytes. The acceptance
+consumer uses generic JSON responses (`strict: false`) to compare the complete
+result unions. Applications using strict JSON must declare response schemas.
+
+The package root is the supported application API in the synchronized
+`1.0.0-beta.2` release candidate. Provider, manifest, compiler and Native
+subpaths are trusted toolchain integration, not application imports. Install
+S3 with the exact compatible Pulse, CLI and provider candidate set; candidate
+preparation does not imply npm publication.
+
+See the [S3 guide](https://pulsecompute.io/v1.0.0-beta.2/packages/s3/) for the
+lowering contract, support matrix and acceptance boundaries. Local acceptance
+executes Node Native, Node JavaScript and compiled Fastly Native Wasm against
+controlled origins. Live Object Storage evidence follows infrastructure setup.

package/as/read.as.ts

@@ -0,0 +1,115 @@
+// S3 owns exact-key encoding, SigV4 composition and strict byte interpretation.
+// Crypto supplies the selected digest/MAC exports. Providers supply credentials,
+// time and transport; none of those authorities are application imports.
+function __pulse_s3_bytes(text: string): Uint8Array { return Uint8Array.wrap(String.UTF8.encode(text, false)) }
+function __pulse_s3_scalar(text: string, controls: bool = false): bool {
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    if (controls && (c < 32 || (c >= 127 && c <= 159))) return false;
+    if (c >= 0xd800 && c <= 0xdbff) {
+      if (++i >= text.length) return false;
+      const low = text.charCodeAt(i);
+      if (low < 0xdc00 || low > 0xdfff) return false;
+    } else if (c >= 0xdc00 && c <= 0xdfff) return false;
+  }
+  return true;
+}
+function __pulse_s3_key(key: string): string | null {
+  if (!key.length || !__pulse_s3_scalar(key, true)) return null;
+  const segments = key.split('/');
+  for (let i = 0; i < segments.length; i++) if (segments[i] == '.' || segments[i] == '..') return null;
+  const bytes = __pulse_s3_bytes(key);
+  if (bytes.length > 1024) return null;
+  const alphabet = '0123456789ABCDEF'; let output = '';
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i];
+    if ((b >= 65 && b <= 90) || (b >= 97 && b <= 122) || (b >= 48 && b <= 57) || b == 45 || b == 46 || b == 95 || b == 126 || b == 47) output += String.fromCharCode(b);
+    else output += '%' + alphabet.charAt(b >> 4) + alphabet.charAt(b & 15);
+  }
+  return output;
+}
+function __pulse_s3_utf8_valid(bytes: Uint8Array): bool {
+  for (let i = 0; i < bytes.length;) {
+    const lead = bytes[i++]; if (lead < 128) continue;
+    let count = 0, minimum = 128, maximum = 191;
+    if (lead >= 194 && lead <= 223) count = 1;
+    else if (lead >= 224 && lead <= 239) { count = 2; if (lead == 224) minimum = 160; if (lead == 237) maximum = 159; }
+    else if (lead >= 240 && lead <= 244) { count = 3; if (lead == 240) minimum = 144; if (lead == 244) maximum = 143; }
+    else return false;
+    if (i + count > bytes.length || i32(bytes[i]) < minimum || i32(bytes[i]) > maximum) return false;
+    i++; for (let n = 1; n < count; n++, i++) if (bytes[i] < 128 || bytes[i] > 191) return false;
+  }
+  return true;
+}
+function __pulse_s3_hex(bytes: Uint8Array): string {
+  const alphabet = '0123456789abcdef'; let output = '';
+  for (let i = 0; i < bytes.length; i++) output += alphabet.charAt(bytes[i] >> 4) + alphabet.charAt(bytes[i] & 15);
+  return output;
+}
+function __pulse_s3_sha(bytes: Uint8Array): Uint8Array {
+  const output = new Uint8Array(32);
+  if (pulse_crypto_sha256_bytes_v1(i32(bytes.dataStart), bytes.length, i32(output.dataStart), 32) != 1) unreachable();
+  return output;
+}
+function __pulse_s3_mac(key: Uint8Array, text: string): Uint8Array {
+  const data = __pulse_s3_bytes(text), output = new Uint8Array(32);
+  const status = pulse_crypto_hmac_sha256_bytes_v1(i32(key.dataStart), key.length, i32(data.dataStart), data.length, i32(output.dataStart), 32);
+  key.fill(0);
+  if (status != 1) unreachable();
+  return output;
+}
+function __pulse_s3_ascii(text: string, max: i32): bool {
+  if (!text.length || text.length > max) return false;
+  for (let i = 0; i < text.length; i++) if (text.charCodeAt(i) < 33 || text.charCodeAt(i) > 126) return false;
+  return true;
+}
+function __pulse_s3_credentials(id: string, secret: string, token: string): bool {
+  return __pulse_s3_ascii(id, 256) && __pulse_s3_scalar(secret) && secret.length > 0 && __pulse_s3_bytes(secret).length <= 4096
+    && secret.indexOf('\r') < 0 && secret.indexOf('\n') < 0 && (!token.length || __pulse_s3_ascii(token, 4096));
+}
+function __pulse_s3_pad(value: i32, digits: i32): string { return value.toString().padStart(digits, '0') }
+function __pulse_s3_date(seconds: i64): string {
+  if (seconds < 0 || seconds > 253402300799) return '';
+  // Gregorian civil date from Unix days, bounded to years 1970..9999.
+  const z = i32(seconds / 86400) + 719468, era = z / 146097, doe = z - era * 146097;
+  const yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365;
+  let year = yoe + era * 400;
+  const doy = doe - (365 * yoe + yoe / 4 - yoe / 100), mp = (5 * doy + 2) / 153;
+  const day = doy - (153 * mp + 2) / 5 + 1, month = mp + (mp < 10 ? 3 : -9);
+  if (month <= 2) year++;
+  return __pulse_s3_pad(year, 4) + __pulse_s3_pad(month, 2) + __pulse_s3_pad(day, 2) + 'T'
+    + __pulse_s3_pad(i32(seconds / 3600 % 24), 2) + __pulse_s3_pad(i32(seconds / 60 % 60), 2) + __pulse_s3_pad(i32(seconds % 60), 2) + 'Z';
+}
+class __PulseS3Signature {
+  date: string = ''; digest: string = ''; authorization: string = '';
+}
+function __pulse_s3_sign(method: string, path: string, host: string, region: string, id: string, secret: string, token: string, seconds: i64, body: Uint8Array, contentType: string): __PulseS3Signature {
+  const result = new __PulseS3Signature(); result.date = __pulse_s3_date(seconds);
+  result.digest = __pulse_s3_hex(__pulse_s3_sha(body));
+  const names = (contentType.length ? 'content-type;' : '') + 'host;x-amz-content-sha256;x-amz-date' + (token.length ? ';x-amz-security-token' : '');
+  const headers = (contentType.length ? 'content-type:' + __pulse_s3_header_spaces(contentType) + '\n' : '') + 'host:' + host + '\nx-amz-content-sha256:' + result.digest + '\nx-amz-date:' + result.date + '\n'
+    + (token.length ? 'x-amz-security-token:' + token + '\n' : '');
+  const canonical = method + '\n' + path + '\n\n' + headers + '\n' + names + '\n' + result.digest;
+  const day = result.date.slice(0, 8), scope = day + '/' + region + '/s3/aws4_request';
+  const toSign = 'AWS4-HMAC-SHA256\n' + result.date + '\n' + scope + '\n' + __pulse_s3_hex(__pulse_s3_sha(__pulse_s3_bytes(canonical)));
+  let key = __pulse_s3_mac(__pulse_s3_bytes('AWS4' + secret), day);
+  key = __pulse_s3_mac(key, region); key = __pulse_s3_mac(key, 's3'); key = __pulse_s3_mac(key, 'aws4_request');
+  const signature = __pulse_s3_mac(key, toSign);
+  result.authorization = 'AWS4-HMAC-SHA256 Credential=' + id + '/' + scope + ', SignedHeaders=' + names + ', Signature=' + __pulse_s3_hex(signature);
+  signature.fill(0); return result;
+}
+function __pulse_s3_status_reason(status: i32): string {
+  if (status == 401 || status == 403) return 'not-authorized';
+  if (status == 429) return 'throttled'; if (status == 408) return 'timeout';
+  if (status >= 500 && status <= 599) return 'unavailable'; return 'protocol';
+}
+
+function __pulse_s3_header_spaces(text: string): string {
+  let output = '', space = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charAt(i);
+    if (c != ' ' || !space) output += c;
+    space = c == ' ';
+  }
+  return output;
+}

package/conformance/README.md

@@ -0,0 +1,13 @@
+# S3 conformance
+
+`read.json` contains exact key-encoding and raw-body vectors. The package
+contract records all three operations: `head`, `getText` and `putText`.
+
+Repository acceptance runs the same read and write failure corpus against
+Node Native, Node JavaScript and Fastly Native, then repeats it with the exact
+installed release tarballs. It checks independent SigV4 signatures, UTF-8,
+metadata limits, truncation, deadlines, write uncertainty and secret redaction.
+Fastly Native executes compiled Wasm against host ABI fixtures. These checks
+do not establish live origin behavior; that evidence follows infrastructure
+setup. Fastly JavaScript is ineligible for S3 because its SDK loses raw header
+metadata. See the [S3 guide](https://pulsecompute.io/v1.0.0-beta.2/packages/s3/).

package/conformance/read.json

@@ -0,0 +1,101 @@
+{
+  "keys": [
+    {
+      "key": "plain",
+      "encoded": "plain"
+    },
+    {
+      "key": "/a//b/",
+      "encoded": "/a//b/"
+    },
+    {
+      "key": "%2F",
+      "encoded": "%252F"
+    },
+    {
+      "key": "a b?#",
+      "encoded": "a%20b%3F%23"
+    },
+    {
+      "key": "!'()*",
+      "encoded": "%21%27%28%29%2A"
+    },
+    {
+      "key": "caf\u00e9/\u96ea",
+      "encoded": "caf%C3%A9/%E9%9B%AA"
+    },
+    {
+      "key": "cafe\u0301",
+      "encoded": "cafe%CC%81"
+    },
+    {
+      "key": "a\\b",
+      "encoded": "a%5Cb"
+    }
+  ],
+  "invalidKeys": [
+    "",
+    ".",
+    "..",
+    "a/../b",
+    "./a",
+    "a/.",
+    "\u0000",
+    "\u007f",
+    "\u0085",
+    "\ud800",
+    "\udfff"
+  ],
+  "bodies": [
+    {
+      "id": "empty",
+      "hex": "",
+      "text": "",
+      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+    },
+    {
+      "id": "json",
+      "hex": "7b2261223a317d0a",
+      "text": "{\"a\":1}\n",
+      "sha256": "e346432021b04179518d9614f3560ccd71354a4ee101ddcb893d6959a9d6301c"
+    },
+    {
+      "id": "unicode",
+      "hex": "636166c3a92fe99baa",
+      "text": "caf\u00e9/\u96ea",
+      "sha256": "3e5e62d27765a8a7bcb9866e733e86ee7c001fd768d8b0a3a7beaa60afd90ade"
+    },
+    {
+      "id": "bom",
+      "hex": "efbbbf68656c6c6f",
+      "text": "\ufeffhello",
+      "sha256": "7489ebbcc2a00056ddaaaac190bce473e5c03696ea1bd8ed83cf59a174283862"
+    },
+    {
+      "id": "nul",
+      "hex": "00",
+      "text": "\u0000",
+      "sha256": "6e340b9cffb37a989ca544e6bb780a2c78901d3fb33738768511a30617afa01d"
+    }
+  ],
+  "invalidUtf8": [
+    "c080",
+    "eda080",
+    "f4908080",
+    "e282",
+    "80",
+    "ff"
+  ],
+  "signing": {
+    "source": "https://docs.aws.amazon.com/AmazonS3/latest/developerguide/sig-v4-header-based-auth.html",
+    "date": "20130524T000000Z",
+    "region": "us-east-1",
+    "host": "examplebucket.s3.amazonaws.com",
+    "path": "/test.txt",
+    "range": "bytes=0-9",
+    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
+    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
+    "canonicalRequestSha256": "7344ae5b7ee6c3e7e6b0fe0640412a37625d1fbfff95c48bbb2dc43964946972",
+    "signature": "f0e8bdb87c964420e857bd35b5d6ed310bd44f0170aba48dd91039c6036bdb41"
+  }
+}

package/package.json

@@ -1,16 +1,57 @@
 {
   "name": "@pulse-compute/s3",
-  "version": "0.0.0",
-  "description": "Inert bootstrap placeholder for @pulse-compute/s3.",
+  "version": "1.0.0-beta.2",
   "license": "Apache-2.0",
+  "engines": {
+    "node": "^22.14.0 || ^24.0.0"
+  },
+  "description": "Bounded exact-key S3 reads and writes through Pulse effects.",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "require": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./provider": "./src/provider.js",
+    "./pulsewasm/manifest": "./pulsewasm.manifest.cjs",
+    "./pulsewasm/compiler": "./pulsewasm.compiler.cjs",
+    "./pulsewasm-native": "./pulsewasm.native.cjs"
+  },
   "files": [
+    "src",
+    "as",
+    "conformance",
+    "pulse.package.json",
+    "pulsewasm.manifest.cjs",
+    "pulsewasm.compiler.cjs",
+    "pulsewasm.native.cjs",
     "README.md",
     "LICENSE",
     "NOTICE"
   ],
+  "pulse": {
+    "contract": "./pulse.package.json"
+  },
+  "pulsewasm": {
+    "manifest": "./pulsewasm.manifest.cjs"
+  },
+  "dependencies": {
+    "@pulse-compute/runtime": "1.0.0-beta.2",
+    "@pulse-compute/wasm-contracts": "1.0.0-beta.2"
+  },
   "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/",
-    "tag": "bootstrap"
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pulse-compute/pulse.git",
+    "directory": "packages/s3"
+  },
+  "homepage": "https://pulsecompute.io/v1.0.0-beta.2/packages/s3/",
+  "bugs": {
+    "url": "https://github.com/pulse-compute/pulse/issues"
   }
-}
+}

package/pulse.package.json

@@ -0,0 +1,76 @@
+{
+  "version": "pulse.package-contract.v1",
+  "kind": "pulse.package-contract",
+  "contractId": "pulse.s3",
+  "npmPackage": "@pulse-compute/s3",
+  "description": "Bounded exact-key S3 reads and writes.",
+  "authoring": {
+    "namespace": "s3",
+    "import": "@pulse-compute/s3",
+    "symbols": [
+      "head",
+      "getText",
+      "putText"
+    ]
+  },
+  "ownership": {
+    "profileFragment": "s3",
+    "helperImports": [],
+    "reExportImports": []
+  },
+  "composition": {
+    "status": "reserved",
+    "helperSymbol": "s3",
+    "profileToken": "opaque-direct-use",
+    "reasonCode": "PULSE_PACKAGE_COMPOSITION_HELPER_NOT_REALIZED"
+  },
+  "targets": {
+    "native": {
+      "status": "provider-dependent",
+      "realization": "canonical-package-lowering",
+      "lowerableSubpath": "@pulse-compute/s3",
+      "providerRequirements": [
+        "s3.head",
+        "s3.getText",
+        "s3.putText",
+        "secret.get",
+        "time.wall-clock"
+      ],
+      "reasonCode": "PULSE_PACKAGE_PROVIDER_CAPABILITY_REQUIRED"
+    },
+    "javascript": {
+      "status": "supported",
+      "realization": "javascript-package-runtime",
+      "entry": "./",
+      "providerRequirements": [
+        "s3.head",
+        "s3.getText",
+        "s3.putText",
+        "secret.get",
+        "time.wall-clock"
+      ]
+    }
+  },
+  "lowering": {
+    "manifest": "./pulsewasm.manifest.cjs",
+    "trust": "first-party",
+    "canonicalOperationVersion": "pulse.canonical-package-operation.v1",
+    "bundleVersion": "pulse.package-lowering-bundle.v1",
+    "providerRequirementVersion": "pulse.provider-requirement-record.v1"
+  },
+  "conformance": {
+    "status": "target-overlap",
+    "fixtureRoots": [
+      "./conformance"
+    ],
+    "semanticCases": [
+      "s3.head",
+      "s3.getText",
+      "s3.putText"
+    ]
+  },
+  "docs": {
+    "readme": "./README.md",
+    "contract": "./pulse.package.json"
+  }
+}

package/pulsewasm.compiler.cjs

@@ -0,0 +1,96 @@
+'use strict';
+const { normalizeDiagnostic, sourceLoc } = require('@pulse-compute/wasm-contracts/diagnostics');
+const { CANONICAL_PACKAGE_EFFECT_VERSION } = require('@pulse-compute/wasm-contracts/handler/canonical-runtime');
+const { PACKAGE_CRYPTO_REQUIREMENT_VERSION } = require('@pulse-compute/wasm-contracts/package/package-contract');
+const { S3_PACKAGE, S3_CONTRACT_ID, S3_OPERATIONS, S3_LOWERING_PLAN_VERSION, S3_CRYPTO_ALGORITHMS } = require('@pulse-compute/wasm-contracts/s3/contracts');
+const { normalizePutOptions } = require('./src/provider.js');
+
+function buildS3LoweringPlan(input = {}) {
+  const ts = input.typescript || require('typescript');
+  const source = input.sourceFile || ts.createSourceFile(input.sourcePath || 'index.ts', input.sourceText || '', ts.ScriptTarget.ES2022, true);
+  const namespaces = new Set();
+  const diagnostics = [];
+  const effects = [];
+  const error = (node, suffix, message) => diagnostics.push(normalizeDiagnostic({
+    phase: 's3-lowering', severity: 'error', code: `PULSEWASM_S3_${suffix}`, message,
+    hint: 'Use a supported s3 call with literal binding/options and runtime key/text in an awaited handler position.', loc: sourceLoc(source, node)
+  }));
+  for (const statement of source.statements) {
+    if (!ts.isImportDeclaration(statement) || statement.moduleSpecifier.text !== S3_PACKAGE) continue;
+    const named = statement.importClause && statement.importClause.namedBindings;
+    if (!named || !ts.isNamedImports(named)) { error(statement, 'IMPORT_UNSUPPORTED', 'Import the named s3 facade.'); continue; }
+    for (const entry of named.elements) {
+      if ((entry.propertyName || entry.name).text !== 's3') error(entry, 'IMPORT_UNSUPPORTED', 'Only the s3 facade is lowerable.');
+      else namespaces.add(entry.name.text);
+    }
+  }
+  function visit(node) {
+    if (ts.isIdentifier(node) && namespaces.has(node.text) && !ts.isImportSpecifier(node.parent)) {
+      const access = node.parent;
+      if (!ts.isPropertyAccessExpression(access) || access.expression !== node || !ts.isCallExpression(access.parent) || access.parent.expression !== access) {
+        error(node, 'FACADE_UNSUPPORTED', 'S3 facade methods cannot be detached or aliased.');
+      }
+    }
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)
+      && ts.isIdentifier(node.expression.expression) && namespaces.has(node.expression.expression.text)) {
+      const method = node.expression.name.text;
+      const op = S3_OPERATIONS[method];
+      if (!op) { error(node, 'OPERATION_UNSUPPORTED', 'S3 supports head, getText and putText.'); return; }
+      const put = method === 'putText';
+      let fn = node.parent;
+      while (fn && !ts.isArrowFunction(fn) && !ts.isFunctionExpression(fn)) fn = fn.parent;
+      const ctx = fn && fn.parameters[0] && fn.parameters[0].name;
+      if (!(put ? [4, 5].includes(node.arguments.length) : node.arguments.length === 3) || !ctx || !ts.isIdentifier(ctx)
+        || !ts.isIdentifier(node.arguments[0]) || node.arguments[0].text !== ctx.text) {
+        error(node, 'ARGUMENTS_UNSUPPORTED', 'S3 requires current handler context, literal binding, runtime key and, for PUT, text with optional literal options.'); return;
+      }
+      const binding = node.arguments[1];
+      if (!ts.isStringLiteralLike(binding) || !/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(binding.text)) {
+        error(binding, 'BINDING_UNSUPPORTED', 'S3 binding must be a valid literal logical name.'); return;
+      }
+      let options = {};
+      if (put) {
+        const nodeOptions = node.arguments[4];
+        try {
+          if (nodeOptions) {
+            if (!ts.isObjectLiteralExpression(nodeOptions) || nodeOptions.properties.length > 1) throw new TypeError();
+            for (const property of nodeOptions.properties) {
+              if (!ts.isPropertyAssignment(property) || !ts.isIdentifier(property.name) && !ts.isStringLiteralLike(property.name)
+                || property.name.text !== 'contentType' || !ts.isStringLiteralLike(property.initializer)) throw new TypeError();
+              options.contentType = property.initializer.text;
+            }
+          }
+          options = normalizePutOptions(options);
+        } catch { error(nodeOptions || node, 'OPTIONS_UNSUPPORTED', 'PUT options must be a literal object containing only a valid literal contentType.'); return; }
+      }
+      let placement = '';
+      const parent = node.parent;
+      if (ts.isAwaitExpression(parent) && ts.isVariableDeclaration(parent.parent)) placement = 'variable';
+      if (ts.isPropertyAssignment(parent) && ts.isObjectLiteralExpression(parent.parent)) {
+        const call = parent.parent.parent;
+        if (ts.isCallExpression(call) && ts.isPropertyAccessExpression(call.expression)
+          && ts.isIdentifier(call.expression.expression) && call.expression.expression.text === ctx.text
+          && call.expression.name.text === 'parallel' && ts.isAwaitExpression(call.parent)) placement = 'statement';
+      }
+      if (!placement) { error(node, 'PLACEMENT_UNSUPPORTED', 'Await S3 into a local variable or a direct keyed ctx.parallel member.'); return; }
+      effects.push({
+        version: CANONICAL_PACKAGE_EFFECT_VERSION, contractId: S3_CONTRACT_ID, package: S3_PACKAGE, import: S3_PACKAGE,
+        ...op, providerKind: 's3', operation: method, placement,
+        range: { start: node.getStart(source), end: node.getEnd() },
+        resource: { binding: binding.text }, payload: { binding: binding.text, ...options },
+        runtimeInputs: [{ name: 'key', argumentIndex: 2, source: 'package-call-argument' }, ...(put ? [{ name: 'text', argumentIndex: 3, source: 'package-call-argument' }] : [])],
+        providerRequirements: [op.kind, 'secret.get', 'time.wall-clock'], schemaReferences: [],
+        redaction: ['key', 'text', 'sha256', 'etag', 'contentType'], loc: sourceLoc(source, node)
+      });
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(source);
+  const cryptoRequirements = effects.length ? [{ version: PACKAGE_CRYPTO_REQUIREMENT_VERSION, algorithms: S3_CRYPTO_ALGORITHMS, reachable: true, requestedBy: S3_PACKAGE, semanticOwner: '@pulse-compute/crypto' }] : [];
+  return {
+    artifact: { version: S3_LOWERING_PLAN_VERSION, contractId: S3_CONTRACT_ID, package: S3_PACKAGE, lowerableSubpath: S3_PACKAGE,
+      status: diagnostics.length ? 'error' : 'ok', canonicalEffects: effects, cryptoRequirements },
+    canonicalEffects: effects, cryptoRequirements, diagnostics, hasErrors: diagnostics.length > 0
+  };
+}
+module.exports = { buildS3LoweringPlan };

package/pulsewasm.manifest.cjs

@@ -0,0 +1,20 @@
+'use strict';
+const { S3_PACKAGE, S3_CONTRACT_ID, S3_OPERATIONS } = require('@pulse-compute/wasm-contracts/s3/contracts');
+module.exports = Object.freeze({
+  version: 'pulsewasm.lowerable-library-manifest.v2', kind: 'pulsewasm.lowerable-library-manifest',
+  contractId: S3_CONTRACT_ID, npmPackage: S3_PACKAGE, lowerableSubpath: S3_PACKAGE,
+  facade: { namespace: 's3', import: S3_PACKAGE, symbols: ['head', 'getText', 'putText'] },
+  publicApi: { package: S3_PACKAGE, symbols: ['s3'], compatibilitySubpaths: [], loweringIntentionallyNarrow: true },
+  compiler: { version: 'pulsewasm.lowerable-compiler-builder.v1', entry: './pulsewasm.compiler.cjs', export: 'buildS3LoweringPlan', artifact: 's3-lowering-plan.json', builderOwner: S3_PACKAGE, trust: 'first-party', inputs: ['typescript.SourceFile'] },
+  modes: {
+    typescript: { entry: './src/index.js' }, jsEngine: { entry: './src/index.js', behavior: 'provider-dependent' },
+    wasm: {
+      mode: 'wasm-sidecar', sidecar: './as/read.as.ts',
+      // The builder emits canonical effects. Native realizations
+      // compose the shared package-owned signing protocol, not a direct call.
+      lowerings: Object.keys(S3_OPERATIONS).map((name) => ({ tsSymbol: `s3.${name}`, asSymbol: '__pulse_s3_sign', callShape: name === 'putText' ? 'context-literal-binding-runtime-key-text-literal-options' : 'context-literal-binding-runtime-key', hostCapabilities: ['backend-fetch', 'body', 'clock', 'result'] })),
+      hostCapabilities: ['backend-fetch', 'body', 'clock', 'result']
+    }
+  },
+  policy: { packageOwnsFacadeMapping: true, canonicalRootLowering: true, automaticFallback: false }
+});

package/pulsewasm.native.cjs

@@ -0,0 +1,11 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+function pulseS3AssemblyScriptSource() {
+  const source = fs.readFileSync(path.join(__dirname, 'as/read.as.ts'), 'utf8');
+  return Object.freeze({ id: 'pulse-s3-read-as', owner: '@pulse-compute/s3', version: 'pulse.s3-native-read.v1',
+    source, sourceSha256: crypto.createHash('sha256').update(source).digest('hex'),
+    cryptoRequirements: Object.freeze(['SHA-256', 'HMAC-SHA256']) });
+}
+module.exports = { pulseS3AssemblyScriptSource };

package/src/index.d.ts

@@ -0,0 +1,51 @@
+// Bounded S3 contract. Provider/target eligibility remains explicit.
+import type { PulseContext, PulseParallelEffect } from '@pulse-compute/runtime';
+
+export type S3ReadFailureReason =
+  | 'invalid-key' | 'configuration' | 'credentials' | 'not-authorized'
+  | 'throttled' | 'unavailable' | 'transport' | 'timeout' | 'protocol'
+  | 'too-large' | 'invalid-utf8';
+
+export interface S3Metadata {
+  readonly byteLength: number;
+  readonly etag?: string;
+  readonly contentType?: string;
+}
+
+export interface S3ReadFailure {
+  readonly status: 'failed';
+  readonly reason: S3ReadFailureReason;
+  readonly httpStatus?: number;
+}
+
+export type S3HeadResult =
+  | ({ readonly status: 'found' } & S3Metadata)
+  | { readonly status: 'not-found' }
+  | S3ReadFailure;
+
+export type S3GetTextResult =
+  | ({ readonly status: 'found'; readonly text: string; readonly sha256: string } & S3Metadata)
+  | { readonly status: 'not-found' }
+  | S3ReadFailure;
+
+export type S3PutTextResult =
+  | { readonly status: 'stored'; readonly byteLength: number; readonly sha256: string; readonly etag?: string }
+  | { readonly status: 'not-stored'; readonly reason:
+      'invalid-key' | 'invalid-text' | 'too-large' | 'configuration' | 'credentials'
+      | 'not-authorized' | 'rejected' | 'throttled' | 'transport' | 'timeout';
+      readonly httpStatus?: number }
+  | { readonly status: 'unknown'; readonly reason: 'transport' | 'timeout' | 'unavailable' | 'protocol';
+      readonly httpStatus?: number };
+
+export interface S3PutTextOptions {
+  readonly contentType?: string;
+}
+
+// Binding and options must be compiler-proven literals. Key and text may be
+// runtime strings. TypeScript alone cannot enforce that lowering restriction.
+export declare const s3: {
+  head(ctx: PulseContext, binding: string, key: string): PulseParallelEffect<S3HeadResult>;
+  getText(ctx: PulseContext, binding: string, key: string): PulseParallelEffect<S3GetTextResult>;
+  putText(ctx: PulseContext, binding: string, key: string, text: string,
+    options?: S3PutTextOptions): PulseParallelEffect<S3PutTextResult>;
+};

package/src/index.js

@@ -0,0 +1,10 @@
+'use strict';
+const { createPackageRuntime } = require('@pulse-compute/runtime/package');
+const { S3_PACKAGE, S3_CONTRACT_ID, S3_OPERATIONS } = require('@pulse-compute/wasm-contracts/s3/contracts');
+const { normalizeResult, normalizePutOptions } = require('./provider.js');
+const runtime = createPackageRuntime({ package: S3_PACKAGE, contractId: S3_CONTRACT_ID, providerKind: 's3', operations: S3_OPERATIONS });
+exports.s3 = Object.freeze({
+  head(ctx, binding, key) { return runtime.effect(ctx, 'head', { binding, key }, (result) => normalizeResult('head', result)); },
+  getText(ctx, binding, key) { return runtime.effect(ctx, 'getText', { binding, key }, (result) => normalizeResult('getText', result)); },
+  putText(ctx, binding, key, text, options) { return runtime.effect(ctx, 'putText', { binding, key, text, ...normalizePutOptions(options) }, (result) => normalizeResult('putText', result)); }
+});

package/src/provider.js

@@ -0,0 +1,136 @@
+'use strict';
+
+// Trusted provider surface; never an application lowering escape. Protocol
+// composition is S3-owned, while crypto, secrets and I/O are supplied by hosts.
+const { S3_LIMITS } = require('@pulse-compute/wasm-contracts/s3/contracts');
+const encoder = new TextEncoder();
+const namePattern = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+const bytes = (text) => encoder.encode(text);
+const hex = (value) => Array.from(value, (b) => b.toString(16).padStart(2, '0')).join('');
+function record(value, fields) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw new TypeError('S3 expects an ordinary record.');
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!fields.includes(key) || !descriptor.enumerable || !Object.hasOwn(descriptor, 'value')) throw new TypeError('S3 record contains an unsupported field.');
+  }
+  return value;
+}
+function normalizeBinding(value) {
+  const input = record(value, ['endpoint', 'bucket', 'region', 'accessKeyIdSecret', 'secretAccessKeySecret', 'sessionTokenSecret', 'maxTextBytes', 'timeoutMs']);
+  if (typeof input.endpoint !== 'string' || !/^https:\/\/[a-z0-9.-]+\/?$/.test(input.endpoint)) throw new TypeError('S3 endpoint must be a fixed HTTPS origin.');
+  const url = new URL(input.endpoint);
+  if (url.hostname.length > 253 || !url.hostname.includes('.') || url.hostname.split('.').some((part) => !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(part))) throw new TypeError('S3 endpoint hostname is invalid.');
+  if (typeof input.bucket !== 'string' || !/^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$/.test(input.bucket) || input.bucket.includes('--')) throw new TypeError('S3 bucket is outside the portable naming subset.');
+  if (typeof input.region !== 'string' || !/^[a-z0-9-]{1,64}$/.test(input.region)) throw new TypeError('S3 signing region must be explicit.');
+  for (const field of ['accessKeyIdSecret', 'secretAccessKeySecret', 'sessionTokenSecret']) {
+    if (field === 'sessionTokenSecret' && input[field] === undefined) continue;
+    if (typeof input[field] !== 'string' || !namePattern.test(input[field])) throw new TypeError('S3 credentials must be valid named secret references.');
+  }
+  const maxTextBytes = input.maxTextBytes === undefined ? S3_LIMITS.textBytes : input.maxTextBytes;
+  const timeoutMs = input.timeoutMs === undefined ? 10000 : input.timeoutMs;
+  if (!Number.isInteger(maxTextBytes) || maxTextBytes < 1 || maxTextBytes > S3_LIMITS.textBytes || !Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000) throw new TypeError('S3 limits are outside the bounded subset.');
+  return Object.freeze({ ...input, endpoint: url.origin, maxTextBytes, timeoutMs });
+}
+function encodeKey(key) {
+  if (typeof key !== 'string' || !key.isWellFormed() || !key.length || bytes(key).length > S3_LIMITS.keyBytes
+    || /[\u0000-\u001f\u007f-\u009f]/u.test(key) || key.split('/').some((p) => p === '.' || p === '..')) return null;
+  // One-time adaptation of Assets' RFC3986 segment encoder. Deliberately no
+  // AssetBucket normalization, path joining, middleware or cache policy.
+  return key.split('/').map((part) => encodeURIComponent(part).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)).join('/');
+}
+function credentialsValid(accessId, secret, token) {
+  return typeof accessId === 'string' && /^[\x21-\x7e]{1,256}$/.test(accessId)
+    && typeof secret === 'string' && secret.isWellFormed() && bytes(secret).length > 0 && bytes(secret).length <= 4096 && !/[\r\n]/.test(secret)
+    && (token === undefined || typeof token === 'string' && /^[\x21-\x7e]{1,4096}$/.test(token));
+}
+function normalizePutOptions(options = {}) {
+  record(options, ['contentType']);
+  const contentType = options.contentType === undefined ? 'text/plain; charset=utf-8' : options.contentType;
+  if (typeof contentType !== 'string' || !/^[\x20-\x7e]{1,128}$/.test(contentType) || contentType.trim() !== contentType) throw new TypeError('S3 content type is outside the bounded literal subset.');
+  return Object.freeze({ contentType });
+}
+async function signRequest(input, crypto) {
+  const { binding, method, encodedKey, accessId, secret, token, now } = input;
+  const body = method === 'PUT' ? input.body : new Uint8Array();
+  const contentType = method === 'PUT' ? normalizePutOptions({ contentType: input.contentType }).contentType : undefined;
+  if (!['HEAD', 'GET', 'PUT'].includes(method) || !(body instanceof Uint8Array) || body.length > binding.maxTextBytes || !credentialsValid(accessId, secret, token) || !Number.isFinite(now) || now < 0) throw new TypeError('S3 signing input is invalid.');
+  const date = new Date(now).toISOString().replace(/[:-]|\.\d{3}/g, '');
+  if (!/^\d{8}T\d{6}Z$/.test(date)) throw new TypeError('S3 signing clock is invalid.');
+  const digest = hex(await crypto.sha256(body));
+  const host = new URL(binding.endpoint).host;
+  const headers = { ...(contentType === undefined ? {} : { 'content-type': contentType }), host, 'x-amz-content-sha256': digest, 'x-amz-date': date, ...(token === undefined ? {} : { 'x-amz-security-token': token }) };
+  const names = Object.keys(headers).sort();
+  const uri = `/${binding.bucket}/${encodedKey}`;
+  const canonical = `${method}\n${uri}\n\n${names.map((name) => `${name}:${headers[name].replace(/ +/g, ' ')}\n`).join('')}\n${names.join(';')}\n${digest}`;
+  const scope = `${date.slice(0, 8)}/${binding.region}/s3/aws4_request`;
+  const toSign = `AWS4-HMAC-SHA256\n${date}\n${scope}\n${hex(await crypto.sha256(bytes(canonical)))}`;
+  let key = bytes(`AWS4${secret}`);
+  try {
+    for (const part of [date.slice(0, 8), binding.region, 's3', 'aws4_request']) {
+      const next = await crypto.hmacSha256(key, bytes(part)); key.fill(0); key = next;
+    }
+    const signature = await crypto.hmacSha256(key, bytes(toSign));
+    headers.authorization = `AWS4-HMAC-SHA256 Credential=${accessId}/${scope}, SignedHeaders=${names.join(';')}, Signature=${hex(signature)}`;
+    signature.fill(0);
+    headers['accept-encoding'] = 'identity';
+    return { method, url: binding.endpoint + uri, headers, ...(method === 'PUT' ? { body } : {}) };
+  } finally { key.fill(0); }
+}
+function failure(reason, httpStatus) { return Object.freeze({ status: 'failed', reason, ...(httpStatus === undefined ? {} : { httpStatus }) }); }
+function putFailure(reason, dispatched, httpStatus) {
+  return Object.freeze({ status: dispatched ? 'unknown' : 'not-stored', reason, ...(httpStatus === undefined ? {} : { httpStatus }) });
+}
+function putStatusResult(status) {
+  if (status === 200) return null;
+  if (status >= 400 && status <= 499 && status !== 408) return putFailure(status === 401 || status === 403 ? 'not-authorized' : status === 429 ? 'throttled' : 'rejected', false, status);
+  return putFailure(status === 408 ? 'timeout' : status >= 500 && status <= 599 ? 'unavailable' : 'protocol', true, status);
+}
+function statusResult(status) {
+  if (status === 200) return null;
+  if (status === 404) return Object.freeze({ status: 'not-found' });
+  return failure(status === 401 || status === 403 ? 'not-authorized' : status === 429 ? 'throttled' : status === 408 ? 'timeout' : status >= 500 && status <= 599 ? 'unavailable' : 'protocol', status);
+}
+function metadataFromHeaders(headers, head) {
+  if (!Array.isArray(headers)) return null;
+  const selected = new Map(); let total = 0;
+  for (const [rawName, value] of headers) {
+    total += bytes(rawName).length + bytes(value).length + 4;
+    if (total > S3_LIMITS.headerBytes) return null;
+    const name = rawName.toLowerCase();
+    if (!['content-length', 'content-type', 'etag', 'content-encoding'].includes(name)) continue;
+    if (selected.has(name) || !value.isWellFormed() || /[\u0000-\u001f\u007f-\u009f]/u.test(value) || bytes(value).length > S3_LIMITS.metadataBytes) return null;
+    selected.set(name, value);
+  }
+  if (selected.has('content-encoding') && selected.get('content-encoding').toLowerCase() !== 'identity') return null;
+  const length = selected.get('content-length');
+  if ((head && length === undefined) || (length !== undefined && (!/^(0|[1-9][0-9]*)$/.test(length) || !Number.isSafeInteger(Number(length))))) return null;
+  if (selected.has('etag') && !selected.get('etag').length) return null;
+  return { ...(length === undefined ? {} : { byteLength: Number(length) }),
+    ...(selected.has('etag') ? { etag: selected.get('etag') } : {}),
+    ...(selected.has('content-type') ? { contentType: selected.get('content-type') } : {}) };
+}
+function normalizeResult(operation, result) {
+  if (!['head', 'getText', 'putText'].includes(operation)) throw new TypeError('Unknown S3 result operation.');
+  const allowed = ['status', 'reason', 'httpStatus', 'byteLength', 'etag', 'contentType', 'text', 'sha256'];
+  record(result, allowed);
+  if (operation === 'putText') {
+    const reasons = result.status === 'not-stored' ? ['invalid-key', 'invalid-text', 'too-large', 'configuration', 'credentials', 'not-authorized', 'rejected', 'throttled', 'transport', 'timeout'] : result.status === 'unknown' ? ['transport', 'timeout', 'unavailable', 'protocol'] : [];
+    if (reasons.includes(result.reason) && Object.keys(result).every((key) => ['status', 'reason', 'httpStatus'].includes(key))
+      && (result.httpStatus === undefined || Number.isInteger(result.httpStatus) && result.httpStatus >= 100 && result.httpStatus <= 599)) return Object.freeze({ ...result });
+    if (result.status !== 'stored' || !Number.isInteger(result.byteLength) || result.byteLength < 0 || result.byteLength > S3_LIMITS.textBytes || typeof result.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(result.sha256)
+      || Object.keys(result).some((key) => !['status', 'byteLength', 'sha256', 'etag'].includes(key))
+      || result.etag !== undefined && (typeof result.etag !== 'string' || !result.etag.length || !result.etag.isWellFormed() || bytes(result.etag).length > S3_LIMITS.metadataBytes || /[\u0000-\u001f\u007f-\u009f]/u.test(result.etag))) throw new TypeError('PUT returned an invalid bounded result.');
+    return Object.freeze({ ...result });
+  }
+  if (result.status === 'not-found' && Object.keys(result).length === 1) return Object.freeze({ ...result });
+  if (result.status === 'failed' && ['invalid-key', 'configuration', 'credentials', 'not-authorized', 'throttled', 'unavailable', 'transport', 'timeout', 'protocol', 'too-large', 'invalid-utf8'].includes(result.reason)
+    && Object.keys(result).every((name) => ['status', 'reason', 'httpStatus'].includes(name))
+    && (result.httpStatus === undefined || Number.isInteger(result.httpStatus) && result.httpStatus >= 100 && result.httpStatus <= 599)) return Object.freeze({ ...result });
+  if (result.status !== 'found' || !Number.isSafeInteger(result.byteLength) || result.byteLength < 0 || Object.hasOwn(result, 'reason') || Object.hasOwn(result, 'httpStatus')) throw new TypeError('S3 returned an invalid bounded result.');
+  if (operation === 'head' && (Object.hasOwn(result, 'text') || Object.hasOwn(result, 'sha256'))) throw new TypeError('HEAD cannot return object bytes or a digest.');
+  if (operation === 'getText' && (typeof result.text !== 'string' || !result.text.isWellFormed() || bytes(result.text).length !== result.byteLength || result.byteLength > S3_LIMITS.textBytes || typeof result.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(result.sha256))) throw new TypeError('GET returned an invalid exact-text result.');
+  for (const field of ['etag', 'contentType']) if (result[field] !== undefined && (typeof result[field] !== 'string' || !result[field].isWellFormed() || bytes(result[field]).length > S3_LIMITS.metadataBytes || /[\u0000-\u001f\u007f-\u009f]/u.test(result[field]) || field === 'etag' && !result[field].length)) throw new TypeError('S3 metadata exceeds its result contract.');
+  if (bytes(JSON.stringify(result)).length > S3_LIMITS.envelopeBytes) throw new TypeError('S3 result envelope exceeds its bound.');
+  return Object.freeze({ ...result });
+}
+module.exports = Object.freeze({ normalizeBinding, namePattern, encodeKey, credentialsValid, normalizePutOptions, signRequest, signRead: signRequest, failure, putFailure, putStatusResult, statusResult, metadataFromHeaders, normalizeResult, hex, bytes });