@pulse-compute/wasm-library-kit 0.0.0 → 1.0.0-beta.1

package/README.md

@@ -1,3 +1,44 @@
 # @pulse-compute/wasm-library-kit
 
-This is an inert namespace-bootstrap package. It contains no executable code.
+<!-- pulse-package-status:start -->
+> **Support tier:** Implementation/transitive surface<br>
+> **Audience:** Pulse package-lowering and compiler maintainers.<br>
+> **Install directly:** No for application projects; it is installed transitively.<br>
+> **Supported entry points:** `None for application authors.`<br>
+> **Stability:** Internal package-lowering interface synchronized with this release set.<br>
+> **Canonical documentation:** [Package guide](https://pulsecompute.io/v1.0.0-beta.1/packages/implementation-packages/)
+>
+> This release-status block is generated from the synchronized `Pulse 1.0.0-beta.1` package policy.
+<!-- pulse-package-status:end -->
+
+PulseWasm package-owned library contract, sidecar, and host capability builders.
+
+## Current split status
+
+This package now owns the library-kit builder surface that was previously exposed through compiler codegen wrappers. The compiler still orchestrates extraction, but it imports these library builders from this package.
+
+## Exposed modules
+
+- `@pulse-compute/wasm-library-kit` — compatibility root exposing the package-owned builder groups
+- `@pulse-compute/wasm-library-kit/compiler` — build-time compiler integration helpers
+- `@pulse-compute/wasm-library-kit/compiler/handler-library-contracts`
+- `@pulse-compute/wasm-library-kit/compiler/library-sidecars`
+- `@pulse-compute/wasm-library-kit/compiler/host-capabilities`
+
+The compiler subpath exposes:
+
+- `handlerLibraryContracts`
+- `librarySidecars`
+- `hostCapabilities`
+- `buildHandlerLibraryContracts`
+- `buildLibrarySidecarConsumption`
+- `buildHostCapabilities`
+
+## Notes
+
+- Owns declared-library sidecar consumption and ctx-extension validation builder behavior.
+- Owns the host capability artifact builder because it aggregates library capability requirements.
+- Consumes stable contract surfaces from `@pulse-compute/wasm-contracts`.
+- Consumes shared build helpers from `@pulse-compute/wasm-build-support`.
+- Does not depend on `@pulse-compute/wasm-compiler`.
+- Examples under compiler/examples/libraries remain canonical fixtures for now.

package/package.json

@@ -1,15 +1,43 @@
 {
   "name": "@pulse-compute/wasm-library-kit",
-  "version": "0.0.0",
-  "description": "Inert namespace bootstrap for Pulse.",
+  "version": "1.0.0-beta.1",
   "license": "Apache-2.0",
+  "engines": {
+    "node": "^22.14.0 || ^24.0.0"
+  },
+  "description": "PulseWasm package-owned library contract, sidecar, and host capability builders.",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./compiler": "./src/compiler/index.js",
+    "./compiler/handler-library-contracts": "./src/compiler/handler-library-contracts.js",
+    "./compiler/library-sidecars": "./src/compiler/library-sidecars.js",
+    "./compiler/host-capabilities": "./src/compiler/host-capabilities.js",
+    "./compiler/assets-lowering": "./src/compiler/assets-lowering.js",
+    "./compiler/package-lowering": "./src/compiler/package-lowering.js",
+    "./compiler/package-contracts": "./src/compiler/package-contracts.js"
+  },
+  "dependencies": {
+    "@pulse-compute/wasm-build-support": "1.0.0-beta.1",
+    "@pulse-compute/wasm-contracts": "1.0.0-beta.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "files": [
+    "src",
     "README.md",
     "LICENSE",
     "NOTICE"
   ],
-  "publishConfig": {
-    "access": "public",
-    "tag": "bootstrap"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pulse-compute/pulse.git",
+    "directory": "wasm/packages/library-kit"
+  },
+  "homepage": "https://pulsecompute.io/v1.0.0-beta.1/packages/implementation-packages/",
+  "bugs": {
+    "url": "https://github.com/pulse-compute/pulse/issues"
   }
-}
+}

package/src/compiler/assets-lowering.js

@@ -0,0 +1,160 @@
+'use strict';
+
+const {
+  discoverLowerableLibraryManifests,
+  loadLowerableCompilerBuilder,
+  resolveDefaultLibraryContracts
+} = require('./handler-library-contracts.js');
+
+function loadAssetsContracts() {
+  try {
+    return require('@pulse-compute/wasm-contracts/assets/contracts');
+  } catch (error) {
+    if (error && error.code === 'MODULE_NOT_FOUND' && String(error.message).includes('@pulse-compute/wasm-contracts')) {
+      return require('../../../contracts/src/assets/contracts.js');
+    }
+    throw error;
+  }
+}
+
+const assetsContracts = loadAssetsContracts();
+const phaseName = 'assets-lowering-plan';
+
+function findAssetsManifestRecord(inputs = {}) {
+  const manifestRecords = Array.isArray(inputs.manifestRecords) && inputs.manifestRecords.length > 0
+    ? inputs.manifestRecords
+    : discoverLowerableLibraryManifests({ cwd: inputs.cwd || process.cwd(), workspaceRoot: inputs.workspaceRoot });
+
+  const explicitManifest = inputs.assetsManifest || inputs.manifest;
+  if (explicitManifest) {
+    const record = manifestRecords.find((entry) => entry.manifest === explicitManifest || (
+      entry.manifest &&
+      entry.manifest.contractId === explicitManifest.contractId &&
+      entry.manifest.npmPackage === explicitManifest.npmPackage
+    ));
+    if (record) return { record, manifestRecords };
+    return {
+      record: {
+        packageDir: inputs.packageDir || process.cwd(),
+        packageName: explicitManifest.npmPackage,
+        manifestFile: inputs.manifestFile,
+        manifest: explicitManifest,
+        validation: { status: 'ok', diagnostics: [] }
+      },
+      manifestRecords
+    };
+  }
+
+  return {
+    record: manifestRecords.find((entry) => entry.manifest && entry.manifest.contractId === assetsContracts.ASSETS_CONTRACT_ID),
+    manifestRecords
+  };
+}
+
+function buildAssetsLoweringPlan(inputs = {}) {
+  const cwd = inputs.cwd || process.cwd();
+  const { record, manifestRecords } = findAssetsManifestRecord(inputs);
+  const libraryContracts = Array.isArray(inputs.libraryContracts) && inputs.libraryContracts.length > 0
+    ? inputs.libraryContracts
+    : resolveDefaultLibraryContracts({ cwd, workspaceRoot: inputs.workspaceRoot });
+
+  if (!record) {
+    // Delegate the precise missing-manifest diagnostic to the package builder when possible;
+    // otherwise keep the historical surface by throwing through an empty package-owned input.
+    const error = new Error('Could not discover the package-owned @pulse-compute/assets PulseWasm manifest.');
+    error.diagnostics = [];
+    throw error;
+  }
+
+  const loaded = loadLowerableCompilerBuilder(record);
+  return loaded.builder({
+    ...inputs,
+    cwd,
+    manifest: record.manifest,
+    assetsManifest: record.manifest,
+    manifestRecord: record,
+    manifestRecords,
+    libraryContracts,
+    packageCompilerBuilder: {
+      owner: record.manifest && record.manifest.compiler ? record.manifest.compiler.builderOwner : record.packageName,
+      entry: loaded.entry,
+      export: loaded.exportName,
+      trust: loaded.compiler && loaded.compiler.trust
+    }
+  });
+}
+
+
+function buildAssetsCompiledWasmSidecarPlan(inputs = {}) {
+  const cwd = inputs.cwd || process.cwd();
+  const { record, manifestRecords } = findAssetsManifestRecord(inputs);
+  if (!record) {
+    const error = new Error('Could not discover the package-owned @pulse-compute/assets PulseWasm manifest for sidecar planning.');
+    error.diagnostics = [];
+    throw error;
+  }
+  const loaded = loadLowerableCompilerBuilder(record);
+  const builder = loaded.module && loaded.module.buildAssetsCompiledWasmSidecarPlan;
+  if (typeof builder !== 'function') {
+    const error = new Error('Package-owned assets compiler builder does not export buildAssetsCompiledWasmSidecarPlan.');
+    error.diagnostics = [];
+    throw error;
+  }
+  return builder({
+    ...inputs,
+    cwd,
+    manifest: record.manifest,
+    assetsManifest: record.manifest,
+    manifestRecord: record,
+    manifestRecords,
+    packageDir: record.packageDir,
+    packageCompilerBuilder: {
+      owner: record.manifest && record.manifest.compiler ? record.manifest.compiler.builderOwner : record.packageName,
+      entry: loaded.entry,
+      export: 'buildAssetsCompiledWasmSidecarPlan',
+      trust: loaded.compiler && loaded.compiler.trust
+    }
+  });
+}
+
+
+
+function buildAssetsSidecarCompileLinkProof(inputs = {}) {
+  const cwd = inputs.cwd || process.cwd();
+  const { record, manifestRecords } = findAssetsManifestRecord(inputs);
+  if (!record) {
+    const error = new Error('Could not discover the package-owned @pulse-compute/assets PulseWasm manifest for sidecar compile/link proof.');
+    error.diagnostics = [];
+    throw error;
+  }
+  const loaded = loadLowerableCompilerBuilder(record);
+  const builder = loaded.module && loaded.module.buildAssetsSidecarCompileLinkProof;
+  if (typeof builder !== 'function') {
+    const error = new Error('Package-owned assets compiler builder does not export buildAssetsSidecarCompileLinkProof.');
+    error.diagnostics = [];
+    throw error;
+  }
+  return builder({
+    ...inputs,
+    cwd,
+    manifest: record.manifest,
+    assetsManifest: record.manifest,
+    manifestRecord: record,
+    manifestRecords,
+    packageDir: record.packageDir,
+    packageCompilerBuilder: {
+      owner: record.manifest && record.manifest.compiler ? record.manifest.compiler.builderOwner : record.packageName,
+      entry: loaded.entry,
+      export: 'buildAssetsSidecarCompileLinkProof',
+      trust: loaded.compiler && loaded.compiler.trust
+    }
+  });
+}
+
+module.exports = {
+  buildAssetsLoweringPlan,
+  buildAssetsCompiledWasmSidecarPlan,
+  buildAssetsSidecarCompileLinkProof,
+  findAssetsManifestRecord,
+  phaseName
+};