@pulse-compute/wasm-guest-link 0.0.0 → 1.0.0-beta.2

package/README.md

@@ -1,5 +1,97 @@
 # @pulse-compute/wasm-guest-link
 
-> Bootstrap placeholder — no runtime or API.
+<!-- pulse-package-status:start -->
+> **Support tier:** Implementation/transitive surface<br>
+> **Audience:** Pulse compiler, release, and first-party guest-unit maintainers.<br>
+> **Install directly:** No for application projects; it is an internal synchronized compiler dependency.<br>
+> **Supported entry points:** `None for application authors.`<br>
+> **Stability:** Internal first-party prebuilt guest-link interface synchronized with the compiler; no application-author or third-party guest compatibility guarantee.<br>
+> **npm:** [`@pulse-compute/wasm-guest-link`](https://www.npmjs.com/package/@pulse-compute/wasm-guest-link)<br>
+> **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.2` package policy.
+<!-- pulse-package-status:end -->
 
-This inert 0.0.0 package reserves the npm name for future Pulse releases.
+Internal Pulse implementation package for connecting validated first-party core
+Wasm guest units into one final audited Native artifact.
+
+The package owns:
+
+- `pulse.guest-unit.v1` / `pulse.guest-unit-plan.v1` validation plus the
+  closed ES256-only v2 contracts;
+- package-prebuilt hash, source-provenance, and binary verification;
+- content-addressed `.pulse/guests/` materialization;
+- the direct pinned Binaryen toolchain;
+- static core-Wasm composition and post-link optimization;
+- `pulse.guest-link-report.v1` and `pulse.final-wasm-audit.v1`;
+- normalized, redacted guest-link diagnostics.
+
+The original implementation continues to accept the A4-bound
+`pulse.guest-memory.borrowed-span.v1` contract: one fixed 32-page
+link-stage-owned memory, synchronous read-only borrowed spans of at most 4096
+bytes, no allocation or retention, MVP features, and no fallback.
+
+G2 adds a separate closed `pulse.guest-unit.v2` /
+`pulse.guest-unit-plan.v2` path for the reviewed
+`pulse.crypto.es256.rustcrypto-p256.v1` package prebuilt. That path preserves
+the same single fixed memory while reserving the frozen 16,640-byte private
+invocation frame. It accepts no other v2 unit, owner, ABI, artifact, source
+tree, frame capacity, or toolchain identity. Both default Native and
+`experimental-native-size` realization plans perform post-link optimization
+and audit the layout before and after optimization.
+
+It does not own package semantics, provider packaging, source builds, local
+overrides, dynamic loading, or third-party guest registration. Package
+manifests contain normalized metadata only; they cannot supply executables,
+shell commands, or argument vectors. Every binary claim is independently
+verified before composition.
+
+The exported package root is an internal compiler integration surface. It is
+not an application-author API.
+
+The ES256 unit is linked and exercised as a G2 Node Native integration proof,
+but it is not selected by application lowering and is not executable through
+the crypto or JWT public surfaces. G3 owns that activation.
+
+## Release boundary
+
+The package is synchronized with the compiler as an implementation dependency.
+It accepts only trusted first-party `package-prebuilt` units selected through
+the compiler's closed package-lowering path. It does not expose project
+configuration, CLI guest commands, source-build adapters, local overrides,
+runtime loading, self-registration, or a third-party guest API.
+
+Selected-unit failures are terminal. No error path retries another owner,
+realization, execution mode, or provider path.
+
+## JWT/crypto proof relationship
+
+The sealed guest-link pipeline is evidence that the accepted borrowed-memory
+contract can produce one audited final core module. It is not load-bearing for
+HS256. The synchronized JWT/crypto packages select
+`guest-source:pulse-hmac-as` for Native targets and emits zero linked guest
+units; JavaScript selects the Web Crypto runtime builtin.
+
+The historical guest pipeline result is recorded in
+`wasm/.test-results/guest-link-b4/phase-b-seal.json`. Its relationship to the
+current four-target JWT proof is audited by
+`wasm/.test-results/jwt-e4/jwt-phase-e-seal.json`. Neither result creates a
+third-party guest ABI or authorizes publication, deployment, or activation.
+
+## Validation
+
+The Phase B seal replays the valid production pipeline, the complete negative
+diagnostic matrix, content-addressed reuse and deletion/recreation, Node
+execution, and `fastly compute serve` over the exact production core artifact.
+It cross-checks the core identity against the sealed A3 evidence without
+rebuilding the package-prebuilt Rust source:
+
+```bash
+PULSE_FASTLY_BIN=/path/to/fastly \
+PULSE_VICEROY_BIN=/path/to/viceroy \
+node ../../scripts/run-wasm-tests.cjs --task guest-link-b-seal --no-report
+```
+
+The seal writes `wasm/.test-results/guest-link-b4/phase-b-seal.json`, including
+artifact-size and focused validation wall-clock measurements. It performs no
+remote deployment.

package/package.json

@@ -1,16 +1,38 @@
 {
   "name": "@pulse-compute/wasm-guest-link",
-  "version": "0.0.0",
-  "description": "Inert bootstrap placeholder for @pulse-compute/wasm-guest-link.",
+  "version": "1.0.0-beta.2",
   "license": "Apache-2.0",
+  "description": "Internal first-party guest-unit validation, materialization, core Wasm composition, optimization, and final audit for Pulse.",
+  "type": "commonjs",
+  "engines": {
+    "node": "^22.14.0 || ^24.0.0"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./stage": "./src/stage.js",
+    "./toolchain": "./src/toolchain.js"
+  },
+  "dependencies": {
+    "@pulse-compute/wasm-contracts": "1.0.0-beta.2",
+    "binaryen": "129.0.0-nightly.20260428"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "files": [
+    "src",
     "README.md",
     "LICENSE",
     "NOTICE"
   ],
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/",
-    "tag": "bootstrap"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pulse-compute/pulse.git",
+    "directory": "wasm/packages/wasm-guest-link"
+  },
+  "homepage": "https://pulsecompute.io/v1.0.0-beta.2/packages/implementation-packages/",
+  "bugs": {
+    "url": "https://github.com/pulse-compute/pulse/issues"
   }
-}
+}

package/src/constants.js

@@ -0,0 +1,159 @@
+'use strict';
+
+const versions = Object.freeze({
+  guestUnit: 'pulse.guest-unit.v1',
+  guestUnitV2: 'pulse.guest-unit.v2',
+  guestUnitPlan: 'pulse.guest-unit-plan.v1',
+  guestUnitPlanV2: 'pulse.guest-unit-plan.v2',
+  guestLinkReport: 'pulse.guest-link-report.v1',
+  guestLinkReportV2: 'pulse.guest-link-report.v2',
+  finalWasmAudit: 'pulse.final-wasm-audit.v1',
+  finalWasmAuditV2: 'pulse.final-wasm-audit.v2',
+  memoryAbi: 'pulse.guest-memory.borrowed-span.v1',
+  memoryAbiV2: 'pulse.guest-memory.invocation-frame.v2'
+});
+
+const binaryenVersion = '129.0.0-nightly.20260428';
+
+const diagnosticCodes = Object.freeze({
+  invalid: 'PULSE_GUEST_UNIT_INVALID',
+  hashMismatch: 'PULSE_GUEST_UNIT_HASH_MISMATCH',
+  ownerMismatch: 'PULSE_GUEST_UNIT_OWNER_MISMATCH',
+  abiMismatch: 'PULSE_GUEST_UNIT_ABI_MISMATCH',
+  importMismatch: 'PULSE_GUEST_UNIT_IMPORT_MISMATCH',
+  exportMismatch: 'PULSE_GUEST_UNIT_EXPORT_MISMATCH',
+  memoryMismatch: 'PULSE_GUEST_UNIT_MEMORY_MISMATCH',
+  startMismatch: 'PULSE_GUEST_UNIT_START_MISMATCH',
+  featureMismatch: 'PULSE_GUEST_UNIT_FEATURE_MISMATCH',
+  materializationFailed: 'PULSE_GUEST_UNIT_MATERIALIZATION_FAILED',
+  linkFailed: 'PULSE_GUEST_LINK_FAILED',
+  optimizationFailed: 'PULSE_GUEST_OPTIMIZATION_FAILED',
+  finalAuditFailed: 'PULSE_GUEST_FINAL_AUDIT_FAILED'
+});
+
+const memoryAbi = Object.freeze({
+  identity: versions.memoryAbi,
+  pointerWidthBits: 32,
+  pageBytes: 65536,
+  minimumPages: 32,
+  maximumPages: 32,
+  bytes: 32 * 65536,
+  maximumBorrowedBytes: 4096,
+  invalidRangeStatus: 0x8000_0000,
+  importModule: 'env',
+  importName: 'memory',
+  layout: Object.freeze({
+    rustStack: Object.freeze({ start: 0, endExclusive: 65536 }),
+    rustStatic: Object.freeze({ start: 131072, endExclusive: 262144 }),
+    primaryStatic: Object.freeze({ start: 262144, endExclusive: 524288 }),
+    borrowedInput: Object.freeze({ start: 524288, endExclusive: 32 * 65536 })
+  })
+});
+
+const es256FrameV2 = Object.freeze({
+  identity: 'pulse.crypto.es256.invocation-frame.v2',
+  memoryIdentity: versions.memoryAbiV2,
+  pointerWidthBits: 32,
+  byteOrder: 'little-endian',
+  magic: 0x3253_4550,
+  version: 2,
+  headerBytes: 64,
+  capacityBytes: 16640,
+  alignmentBytes: 16,
+  signingInputBytesMaximum: 16340,
+  publicKeyBytes: 64,
+  signatureBytes: 64,
+  export: 'pulse_crypto_es256_verify',
+  parameters: Object.freeze(['i32', 'i32']),
+  results: Object.freeze(['i32'])
+});
+
+const memoryAbiV2 = Object.freeze({
+  identity: versions.memoryAbiV2,
+  pointerWidthBits: 32,
+  pageBytes: 65536,
+  minimumPages: 32,
+  maximumPages: 32,
+  bytes: 32 * 65536,
+  importModule: 'env',
+  importName: 'memory',
+  layout: Object.freeze({
+    rustStack: Object.freeze({ start: 0, endExclusive: 65536 }),
+    stackStaticGuard: Object.freeze({ start: 65536, endExclusive: 131072 }),
+    rustStatic: Object.freeze({ start: 131072, endExclusive: 262144 }),
+    primaryStatic: Object.freeze({ start: 262144, endExclusive: 524288 }),
+    invocationFrame: Object.freeze({
+      start: 524288,
+      endExclusive: 524288 + es256FrameV2.capacityBytes
+    }),
+    unallocated: Object.freeze({
+      start: 524288 + es256FrameV2.capacityBytes,
+      endExclusive: 32 * 65536
+    })
+  }),
+  frame: es256FrameV2
+});
+
+const es256GuestUnit = Object.freeze({
+  version: versions.guestUnitV2,
+  id: 'pulse.crypto.es256.rustcrypto-p256.v1',
+  module: 'pulse_crypto_es256',
+  owner: '@pulse-compute/crypto',
+  packageVersion: '1.0.0-beta.2',
+  abi: 'pulse.crypto.es256.verify.v1',
+  artifact: Object.freeze({
+    file: 'prebuilt/es256-verifier.wasm',
+    bytes: 21009,
+    sha256: 'ee5ab1639cbe1be5a9510c01ab15a3569c0394818a9db98f3e0114ae829fff50'
+  }),
+  source: Object.freeze({
+    directory: 'source',
+    treeSha256: '76c8cf985b2ed384d069f7ba0d7ff1c8513679ea7aec513e1a07a3eeaa3b7208'
+  }),
+  toolchain: Object.freeze({
+    rustc: '1.97.1 (8bab26f4f 2026-07-14)',
+    cargo: '1.97.1 (c980f4866 2026-06-30)',
+    binaryen: binaryenVersion
+  }),
+  provenance: Object.freeze({
+    cargoLockSha256: '7aa8c6d72751653717a371147e71a546d8f21dfcd1cf698919563e79e2946cb4',
+    reconstructionCommandIdentity: 'pulse.crypto.es256.rustcrypto-build.v1',
+    buildScript: 'build.cjs',
+    buildScriptSha256: 'c3b97e10e67cc2a34d0d6dced7bd81cb5fdaeeabe9cf75b5319d419b7dbebdf9',
+    optimizationPosture: 'native-size',
+    binaryenWasmOptSha256: '1304eb38ad315a0d70d8427757f641c110d972468c126af645ef800b09c26e56',
+    g0SourceDecision: '../../../../wasm/.test-results/jwt-g0/es256-source-decision.json',
+    g0SourceDecisionSha256: '58db9e3587ace112a8864c7916f603d8773dce653deafb7d743c0dc1f4d62d63'
+  })
+});
+
+const optimizationPostures = Object.freeze({
+  'native-default': Object.freeze([
+    '--mvp-features',
+    '--optimize-level',
+    '2',
+    '--shrink-level',
+    '0',
+    '--strip-debug'
+  ]),
+  'native-size': Object.freeze([
+    '--mvp-features',
+    '--optimize-level',
+    '3',
+    '--shrink-level',
+    '2',
+    '--converge',
+    '--strip-debug'
+  ])
+});
+
+module.exports = Object.freeze({
+  versions,
+  binaryenVersion,
+  diagnosticCodes,
+  memoryAbi,
+  memoryAbiV2,
+  es256FrameV2,
+  es256GuestUnit,
+  optimizationPostures
+});