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

package/src/library/api-surface.js

@@ -0,0 +1,99 @@
+'use strict';
+
+const { PACKAGE_VERSION } = require('../diagnostics.js');
+
+const API_SURFACE_PHASE = '12C';
+const API_SURFACE_VERSION = 'pulsewasm.api-surface.v1';
+const LIFECYCLE_ORDERING_VERSION = 'pulsewasm.lifecycle-ordering.v1';
+const API_SURFACE_POLICY = {
+  driftVisibleByArtifact: true,
+  canonicalSurfaceExplicit: true,
+  reservedAliasesRecorded: true,
+  librarySurfacesRequireContracts: true,
+  lifecycleDefaultOrdering: 'serial-source-order'
+};
+
+const API_SURFACE_DEFINITIONS = [
+  { symbol: 'ctx.param', kind: 'ctx-dsl', status: 'implemented-compiled-handler', canonical: true, phase: '12A', notes: 'Trusted param DSL lowered to runtime-core helpers.' },
+  { symbol: 'ctx.result.text', kind: 'ctx-dsl', status: 'implemented-compiled-handler', canonical: true, phase: '12A', notes: 'Text result builder.' },
+  { symbol: 'ctx.result.jsonText', kind: 'ctx-dsl', status: 'implemented-compiled-handler', canonical: true, phase: '12A.1', notes: 'JSON text result builder; schema parsing remains sidecar path.' },
+  { symbol: 'ctx.request.header.*', kind: 'ctx-dsl', status: 'implemented-compiled-handler', canonical: true, phase: '12A.1', notes: 'Read-only ordered request header access.' },
+  { symbol: 'ctx.response.header.*', kind: 'ctx-dsl', status: 'implemented-compiled-handler', canonical: true, phase: '12A.1', notes: 'Mutable ordered response header access.' },
+  { symbol: 'ctx.fetch', kind: 'effect', status: 'planned-route-effect', canonical: true, phase: '30', notes: 'Declared backend-fetch effect; Pass 30 can plan ctx.resolve lifecycle, execution reserved until provider/runtime proof.' },
+  { symbol: 'ctx.sleep', kind: 'effect', status: 'contracted-proof-target', canonical: true, phase: '11F/11G', notes: 'Sleep is the first explicit effect proof target; execution not implemented yet.' },
+  { symbol: 'ctx.resolve', kind: 'effect-composition', status: 'planned-route-effect', canonical: true, phase: '30', notes: 'Effect submission boundary with named top-level continuation; no promise/microtask semantics.' },
+  { symbol: 'ctx.resolved', kind: 'effect-continuation', status: 'planned-route-effect', canonical: true, phase: '30', notes: 'Continuation-only resolved fetch response handle accessor for ctx.resolve groups.' },
+  { symbol: 'ctx.req.parse', kind: 'body-parser', status: 'contracted-reserved', canonical: true, phase: '12B.1', notes: 'Canonical parser surface; schema id selects codec/sidecar.' },
+  { symbol: 'ctx.req.json', kind: 'body-parser-sugar', status: 'reserved-alias', canonical: false, canonicalTarget: 'ctx.req.parse', phase: '12B.1', notes: 'JSON-only sugar; not the root API.' },
+  { symbol: 'ctx.<extension>.*', kind: 'library-ctx-extension', status: 'library-declared', canonical: true, phase: '12C', notes: 'Only valid when declared by pulse.library.json, installed in scope, and lowered by AS sidecar.' },
+  { symbol: 'grip.hold/channel/publish', kind: 'package-owned-lowerable-facade', status: 'package-owned-plan-only', canonical: true, phase: '54', notes: '@pulse-compute/grip now ships its own PulseWasm manifest, lowerable facade, compiler builder, and sidecar declaration. Provider runtime behavior remains plan-only.' },
+  { symbol: 'app.timeout', kind: 'router-metadata', status: 'implemented-contract', canonical: true, phase: '11G', notes: 'Static scope timeout metadata, not middleware behavior.' },
+  { symbol: 'lifecycle.connect/disconnect', kind: 'lifecycle', status: 'serial-source-order-locked', canonical: true, phase: '12C', notes: 'Lifecycle handlers execute serially in source/scope order. Parallel lifecycle execution is reserved.' }
+];
+
+function defaultApiSurfaces() {
+  return API_SURFACE_DEFINITIONS.map((surface) => ({ ...surface }));
+}
+
+function summarizeApiSurfaces(surfaces) {
+  return {
+    surfaces: surfaces.length,
+    implemented: surfaces.filter((surface) => String(surface.status).startsWith('implemented')).length,
+    contractedReserved: surfaces.filter((surface) => surface.status.includes('reserved')).length,
+    libraryDeclared: surfaces.filter((surface) => surface.kind === 'library-ctx-extension').length,
+    lifecycleSerial: true
+  };
+}
+
+function buildApiSurfaceContract(inputs = {}) {
+  const surfaces = defaultApiSurfaces();
+  return {
+    version: API_SURFACE_VERSION,
+    generatedBy: inputs.generatedBy || PACKAGE_VERSION,
+    phase: inputs.phase || API_SURFACE_PHASE,
+    status: 'locked',
+    policy: { ...API_SURFACE_POLICY },
+    summary: summarizeApiSurfaces(surfaces),
+    surfaces
+  };
+}
+
+function buildLifecycleOrderingContract(executionPlan, inputs = {}) {
+  const scopes = Array.isArray(executionPlan?.scopes) ? executionPlan.scopes : [];
+  const lifecycleLinks = scopes.flatMap((scope) => [
+    ...(scope.connect || []).map((handler, index) => ({ scopeId: scope.id, event: 'connect', order: index, handlerId: handler.handlerId || handler.id, name: handler.name })),
+    ...(scope.disconnect || []).map((handler, index) => ({ scopeId: scope.id, event: 'disconnect', order: index, handlerId: handler.handlerId || handler.id, name: handler.name }))
+  ]);
+  return {
+    version: LIFECYCLE_ORDERING_VERSION,
+    generatedBy: inputs.generatedBy || PACKAGE_VERSION,
+    phase: inputs.phase || API_SURFACE_PHASE,
+    status: 'locked',
+    policy: {
+      defaultOrdering: 'serial-source-order',
+      parallelLifecycleExecution: 'reserved-explicit-only',
+      hiddenScheduler: false,
+      promiseSemantics: false
+    },
+    summary: {
+      scopes: scopes.length,
+      lifecycleLinks: lifecycleLinks.length,
+      connectHandlers: lifecycleLinks.filter((link) => link.event === 'connect').length,
+      disconnectHandlers: lifecycleLinks.filter((link) => link.event === 'disconnect').length,
+      serialByDefault: true
+    },
+    lifecycleLinks
+  };
+}
+
+module.exports = {
+  API_SURFACE_PHASE,
+  API_SURFACE_VERSION,
+  LIFECYCLE_ORDERING_VERSION,
+  API_SURFACE_POLICY,
+  API_SURFACE_DEFINITIONS,
+  defaultApiSurfaces,
+  summarizeApiSurfaces,
+  buildApiSurfaceContract,
+  buildLifecycleOrderingContract
+};

package/src/library/contracts.js

@@ -0,0 +1,273 @@
+'use strict';
+
+const { normalizeDiagnostic } = require('../diagnostics.js');
+const {
+  LOWERABLE_LIBRARY_MANIFEST_VERSION,
+  LOWERABLE_LIBRARY_MANIFEST_KIND,
+  clone,
+  validateLowerableLibraryManifest
+} = require('./manifest.js');
+
+const LIBRARY_CONTRACTS_PHASE = '11D';
+const HANDLER_LIBRARY_CONTRACTS_PHASE = LIBRARY_CONTRACTS_PHASE;
+const HANDLER_LIBRARY_CONTRACTS_VERSION = 'pulsewasm.handler-library-contracts.v1';
+const HANDLER_EXECUTION_MODES_VERSION = 'pulsewasm.handler-execution-modes.v1';
+const LIBRARY_CONTRACT_SCHEMA_VERSION = 'pulsewasm.library-contract-schema.v1';
+const LIBRARY_CONTRACT_VERSION = 'pulsewasm.library-contract.v1';
+const LIBRARY_CAPABILITIES_VERSION = 'pulsewasm.library-capabilities.v1';
+const LIBRARY_COMPATIBILITY_REPORT_VERSION = 'pulsewasm.library-compatibility-report.v1';
+
+const ALLOWED_HANDLER_EXECUTION_MODES = ['host-imports', 'compiled-wasm', 'js-engine'];
+const ALLOWED_LIBRARY_MODES = ['typescript', 'js-engine', 'wasm-sidecar'];
+const ALLOWED_HOST_CAPABILITIES = [
+  'headers',
+  'broadcaster',
+  'clock',
+  'assets',
+  'json',
+  'body',
+  'backend-fetch',
+  'state',
+  'params',
+  'result',
+  'error',
+  'lifecycle',
+  'channel'
+];
+
+function makeDiagnostic(code, message, hint, details) {
+  return normalizeDiagnostic({
+    phase: 'handler-library-contracts',
+    severity: 'error',
+    code,
+    message,
+    hint,
+    details,
+    loc: { file: '<library-contract>' }
+  });
+}
+
+function sortedUnique(values) {
+  return Array.from(new Set((values || []).filter(Boolean))).sort();
+}
+
+function defaultLibraryContracts() {
+  return [
+    {
+      version: LIBRARY_CONTRACT_VERSION,
+      package: 'pulse.grip',
+      description: 'Contract fixture for GRIP/Fanout-style header and channel control-plane helpers.',
+      modes: {
+        typescript: { entry: './dist/index.js' },
+        jsEngine: { entry: './dist/index.js' },
+        wasm: {
+          mode: 'wasm-sidecar',
+          sidecar: './as/index.as.ts',
+          lowerings: [
+            { tsSymbol: 'grip.hold', asSymbol: 'pulse_grip_hold', callShape: 'literal-mode', hostCapabilities: ['headers'] },
+            { tsSymbol: 'grip.channel', asSymbol: 'pulse_grip_channel', callShape: 'literal-channel', hostCapabilities: ['headers', 'channel', 'broadcaster'] },
+            { tsSymbol: 'grip.publish', asSymbol: 'pulse_grip_publish', callShape: 'declared-channel-message', hostCapabilities: ['broadcaster', 'clock'] }
+          ],
+          hostCapabilities: ['headers', 'channel', 'broadcaster', 'clock']
+        }
+      },
+      policy: {
+        inferredCompatibility: false,
+        arbitraryTsCompilation: false,
+        sidecarRequiredForWasm: true,
+        effectRuntimeRequired: false,
+        driftRequiresParityTests: true
+      }
+    }
+  ];
+}
+
+function libraryContractFromLowerableManifest(manifest, options = {}) {
+  const validation = validateLowerableLibraryManifest(manifest);
+  const normalized = validation.manifest;
+  const wasm = normalized.modes.wasm;
+  const facadeImport = normalized.facade.import || normalized.lowerableSubpath;
+  const publicApiPackage = normalized.publicApi.package || normalized.npmPackage;
+  const policy = {
+    inferredCompatibility: false,
+    arbitraryTsCompilation: false,
+    sidecarRequiredForWasm: true,
+    effectRuntimeRequired: true,
+    driftRequiresParityTests: true,
+    ...(normalized.policy || {})
+  };
+
+  return {
+    version: options.libraryContractVersion || LIBRARY_CONTRACT_VERSION,
+    package: normalized.contractId,
+    npmPackage: normalized.npmPackage,
+    lowerableSubpath: normalized.lowerableSubpath,
+    manifest: {
+      version: normalized.version || LOWERABLE_LIBRARY_MANIFEST_VERSION,
+      kind: normalized.kind || LOWERABLE_LIBRARY_MANIFEST_KIND,
+      owner: 'package'
+    },
+    facade: {
+      namespace: normalized.facade.namespace,
+      import: facadeImport,
+      symbols: Array.isArray(normalized.facade.symbols) ? normalized.facade.symbols.slice() : []
+    },
+    publicApi: {
+      package: publicApiPackage,
+      symbols: Array.isArray(normalized.publicApi.symbols) ? normalized.publicApi.symbols.slice() : [],
+      loweringIntentionallyNarrow: Boolean(normalized.publicApi.loweringIntentionallyNarrow)
+    },
+    compiler: normalized.compiler ? clone(normalized.compiler) : undefined,
+    description: normalized.description || `Package-owned lowerable library manifest for ${normalized.contractId}.`,
+    modes: {
+      typescript: clone(normalized.modes.typescript),
+      jsEngine: clone(normalized.modes.jsEngine),
+      wasm: {
+        mode: wasm.mode || 'wasm-sidecar',
+        sidecar: wasm.sidecar,
+        lowerings: (wasm.lowerings || []).map((lowering) => ({
+          ...lowering,
+          hostCapabilities: Array.isArray(lowering.hostCapabilities) ? lowering.hostCapabilities.slice() : []
+        })),
+        hostCapabilities: Array.isArray(wasm.hostCapabilities) ? wasm.hostCapabilities.slice() : []
+      }
+    },
+    policy,
+    diagnostics: validation.diagnostics
+  };
+}
+
+function normalizeContractModeKeys(modes) {
+  const out = {};
+  if (modes && typeof modes === 'object') {
+    if (modes.typescript) out.typescript = modes.typescript;
+    if (modes.jsEngine || modes.js_engine || modes['js-engine']) out.jsEngine = modes.jsEngine || modes.js_engine || modes['js-engine'];
+    if (modes.wasm || modes.wasmSidecar || modes['wasm-sidecar']) out.wasm = modes.wasm || modes.wasmSidecar || modes['wasm-sidecar'];
+  }
+  return out;
+}
+
+function validateLibraryContract(contract) {
+  const diagnostics = [];
+  const normalized = contract && typeof contract === 'object' ? contract : {};
+  const modes = normalizeContractModeKeys(normalized.modes);
+  const wasm = modes.wasm || {};
+  const lowerings = Array.isArray(wasm.lowerings) ? wasm.lowerings : [];
+  const hostCapabilities = sortedUnique([...(wasm.hostCapabilities || []), ...lowerings.flatMap((lowering) => lowering.hostCapabilities || [])]);
+
+  if (normalized.version !== LIBRARY_CONTRACT_VERSION) {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LIBRARY_CONTRACT_VERSION_UNSUPPORTED',
+      `Library contract ${normalized.package || '<unknown>'} must use ${LIBRARY_CONTRACT_VERSION}.`,
+      'Update pulse.library.json to the locked v1 contract version.',
+      { version: normalized.version }
+    ));
+  }
+  if (!normalized.package || typeof normalized.package !== 'string') {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LIBRARY_CONTRACT_PACKAGE_REQUIRED',
+      'Library contracts must declare a static package name.',
+      'Add "package": "your.package" to pulse.library.json.',
+      { package: normalized.package }
+    ));
+  }
+  if (!modes.typescript || typeof modes.typescript.entry !== 'string') {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LIBRARY_TYPESCRIPT_ENTRY_REQUIRED',
+      `Library ${normalized.package || '<unknown>'} must declare a TypeScript entry.`,
+      'Declare modes.typescript.entry for normal TS/dev ergonomics.',
+      { package: normalized.package }
+    ));
+  }
+  if (!modes.jsEngine || typeof modes.jsEngine.entry !== 'string') {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LIBRARY_JS_ENGINE_ENTRY_REQUIRED',
+      `Library ${normalized.package || '<unknown>'} must declare a JS engine entry.`,
+      'Declare modes.jsEngine.entry for the manual JS escape hatch path.',
+      { package: normalized.package }
+    ));
+  }
+  if (!wasm || typeof wasm.sidecar !== 'string') {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LIBRARY_WASM_SIDECAR_REQUIRED',
+      `Library ${normalized.package || '<unknown>'} must declare a Wasm sidecar for Wasm compatibility.`,
+      'Declare modes.wasm.sidecar, or do not claim Wasm-sidecar compatibility.',
+      { package: normalized.package }
+    ));
+  }
+  if (!Array.isArray(wasm.lowerings) || wasm.lowerings.length === 0) {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LIBRARY_LOWERINGS_REQUIRED',
+      `Library ${normalized.package || '<unknown>'} must declare at least one TS-to-AS lowering.`,
+      'Declare modes.wasm.lowerings with tsSymbol and asSymbol entries.',
+      { package: normalized.package }
+    ));
+  }
+  for (const lowering of lowerings) {
+    if (!lowering || typeof lowering.tsSymbol !== 'string' || typeof lowering.asSymbol !== 'string') {
+      diagnostics.push(makeDiagnostic(
+        'PULSEWASM_LIBRARY_LOWERING_INVALID',
+        `Library ${normalized.package || '<unknown>'} declares an invalid lowering.`,
+        'Each lowering must include static tsSymbol and asSymbol strings.',
+        { package: normalized.package, lowering }
+      ));
+    }
+  }
+  for (const capability of hostCapabilities) {
+    if (!ALLOWED_HOST_CAPABILITIES.includes(capability)) {
+      diagnostics.push(makeDiagnostic(
+        'PULSEWASM_LIBRARY_UNKNOWN_HOST_CAPABILITY',
+        `Library ${normalized.package || '<unknown>'} requires unknown host capability ${JSON.stringify(capability)}.`,
+        `Use one of: ${ALLOWED_HOST_CAPABILITIES.join(', ')}.`,
+        { package: normalized.package, capability }
+      ));
+    }
+  }
+
+  return {
+    package: normalized.package || '<unknown>',
+    status: diagnostics.length === 0 ? 'ok' : 'error',
+    modes: {
+      typescript: Boolean(modes.typescript),
+      jsEngine: Boolean(modes.jsEngine),
+      wasmSidecar: Boolean(wasm && wasm.sidecar)
+    },
+    sidecar: wasm.sidecar,
+    lowerings: lowerings.map((lowering) => ({
+      tsSymbol: lowering.tsSymbol,
+      asSymbol: lowering.asSymbol,
+      callShape: lowering.callShape || 'unspecified',
+      hostCapabilities: sortedUnique(lowering.hostCapabilities || [])
+    })),
+    hostCapabilities,
+    policy: {
+      inferredCompatibility: false,
+      arbitraryTsCompilation: false,
+      sidecarRequiredForWasm: true,
+      contractRequiredForWasm: true,
+      debtRecordedInJsEngineMode: true,
+      effectRuntimeRequired: Boolean(normalized.policy && normalized.policy.effectRuntimeRequired)
+    },
+    diagnostics: [...(normalized.diagnostics || []), ...diagnostics]
+  };
+}
+
+module.exports = {
+  LIBRARY_CONTRACTS_PHASE,
+  HANDLER_LIBRARY_CONTRACTS_PHASE,
+  HANDLER_LIBRARY_CONTRACTS_VERSION,
+  HANDLER_EXECUTION_MODES_VERSION,
+  LIBRARY_CONTRACT_SCHEMA_VERSION,
+  LIBRARY_CONTRACT_VERSION,
+  LIBRARY_CAPABILITIES_VERSION,
+  LIBRARY_COMPATIBILITY_REPORT_VERSION,
+  ALLOWED_HANDLER_EXECUTION_MODES,
+  ALLOWED_LIBRARY_MODES,
+  ALLOWED_HOST_CAPABILITIES,
+  defaultLibraryContracts,
+  libraryContractFromLowerableManifest,
+  normalizeContractModeKeys,
+  normalizeLibraryContractModeKeys: normalizeContractModeKeys,
+  sortedUnique,
+  validateLibraryContract
+};

package/src/library/manifest.js

@@ -0,0 +1,317 @@
+'use strict';
+
+const { normalizeDiagnostic } = require('../diagnostics.js');
+
+const LOWERABLE_LIBRARY_MANIFEST_VERSION = 'pulsewasm.lowerable-library-manifest.v2';
+const LOWERABLE_LIBRARY_MANIFEST_KIND = 'pulsewasm.lowerable-library-manifest';
+
+const LOWERABLE_LIBRARY_PAYLOAD_MODE_STATUSES = Object.freeze([
+  'implemented-now',
+  'lowering-plan-only',
+  'reserved-with-diagnostic',
+  'provider-specific',
+  'unsupported'
+]);
+
+const LOWERABLE_LIBRARY_MANIFEST_REQUIRED_FIELDS = Object.freeze([
+  'version',
+  'contractId',
+  'npmPackage',
+  'lowerableSubpath',
+  'facade.namespace',
+  'facade.symbols',
+  'modes.typescript.entry',
+  'modes.jsEngine.entry',
+  'modes.wasm.sidecar',
+  'modes.wasm.lowerings',
+  'compiler.version',
+  'compiler.entry',
+  'compiler.export',
+  'compiler.builderOwner',
+  'compiler.trust'
+]);
+
+const LOWERABLE_LIBRARY_MANIFEST_POLICY = Object.freeze({
+  packageOwnsIdentity: true,
+  packageOwnsFacadeMapping: true,
+  contractsOwnSchema: true,
+  contractsOwnPayloadStatusVocabulary: true,
+  compilerMayValidateButNotDefinePackageRules: true,
+  packageOwnsCompilerBuilder: true,
+  genericLoaderMayExecuteTrustedFirstPartyBuilders: true,
+  thirdPartyManifestsRequireCorePr: false
+});
+
+function clone(value) {
+  if (Array.isArray(value)) return value.map(clone);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, clone(entry)]));
+  }
+  return value;
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function sortedUnique(values) {
+  return Array.from(new Set((values || []).filter(Boolean))).sort();
+}
+
+function makeDiagnostic(code, message, hint, details) {
+  return normalizeDiagnostic({
+    phase: 'lowerable-library-manifest',
+    severity: 'error',
+    code,
+    message,
+    hint,
+    details,
+    loc: { file: '<lowerable-library-manifest>' }
+  });
+}
+
+function normalizeManifest(manifest) {
+  const normalized = manifest && typeof manifest === 'object' ? manifest : {};
+  const facade = normalized.facade && typeof normalized.facade === 'object' ? normalized.facade : {};
+  const publicApi = normalized.publicApi && typeof normalized.publicApi === 'object' ? normalized.publicApi : {};
+  const modes = normalized.modes && typeof normalized.modes === 'object' ? normalized.modes : {};
+  const wasm = modes.wasm && typeof modes.wasm === 'object' ? modes.wasm : {};
+  const compiler = normalized.compiler && typeof normalized.compiler === 'object' ? normalized.compiler : {};
+
+  return {
+    ...normalized,
+    kind: normalized.kind || LOWERABLE_LIBRARY_MANIFEST_KIND,
+    facade,
+    publicApi,
+    compiler: {
+      version: compiler.version,
+      entry: compiler.entry,
+      export: compiler.export,
+      artifact: compiler.artifact,
+      builderOwner: compiler.builderOwner,
+      trust: compiler.trust,
+      inputs: Array.isArray(compiler.inputs) ? compiler.inputs : []
+    },
+    modes: {
+      typescript: modes.typescript || {},
+      jsEngine: modes.jsEngine || modes.js_engine || modes['js-engine'] || {},
+      wasm: {
+        ...wasm,
+        lowerings: Array.isArray(wasm.lowerings) ? wasm.lowerings : [],
+        hostCapabilities: Array.isArray(wasm.hostCapabilities) ? wasm.hostCapabilities : []
+      }
+    }
+  };
+}
+
+function validateLowerableLibraryManifest(manifest) {
+  const diagnostics = [];
+  const normalized = normalizeManifest(manifest);
+  const facadeSymbols = normalized.facade.symbols;
+  const publicApiSymbols = normalized.publicApi.symbols;
+  const wasm = normalized.modes.wasm;
+  const compiler = normalized.compiler || {};
+
+  if (normalized.version !== LOWERABLE_LIBRARY_MANIFEST_VERSION) {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LOWERABLE_LIBRARY_MANIFEST_VERSION_UNSUPPORTED',
+      `Lowerable library manifest ${normalized.contractId || '<unknown>'} must use ${LOWERABLE_LIBRARY_MANIFEST_VERSION}.`,
+      'Import or copy the locked manifest version for the package-owned manifest declaration.',
+      { version: normalized.version }
+    ));
+  }
+
+  if (!isNonEmptyString(normalized.contractId)) {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LOWERABLE_LIBRARY_CONTRACT_ID_REQUIRED',
+      'Lowerable library manifests must declare a stable contractId.',
+      'Add a package-owned contractId such as "vendor.feature" or a blessed platform contract id.',
+      { contractId: normalized.contractId }
+    ));
+  }
+
+  if (!isNonEmptyString(normalized.npmPackage)) {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LOWERABLE_LIBRARY_NPM_PACKAGE_REQUIRED',
+      `Lowerable library manifest ${normalized.contractId || '<unknown>'} must declare the npm package that owns the facade.`,
+      'Add npmPackage to the package-owned manifest instead of adding package identity to wasm-contracts.',
+      { npmPackage: normalized.npmPackage }
+    ));
+  }
+
+  if (!isNonEmptyString(normalized.lowerableSubpath)) {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LOWERABLE_LIBRARY_SUBPATH_REQUIRED',
+      `Lowerable library manifest ${normalized.contractId || '<unknown>'} must declare a lowerable facade subpath.`,
+      'Add lowerableSubpath to the package-owned manifest.',
+      { lowerableSubpath: normalized.lowerableSubpath }
+    ));
+  }
+
+  if (!isNonEmptyString(normalized.facade.namespace)) {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LOWERABLE_LIBRARY_NAMESPACE_REQUIRED',
+      `Lowerable library manifest ${normalized.contractId || '<unknown>'} must declare facade.namespace.`,
+      'Add the static namespace that compiler extraction may recognize.',
+      { namespace: normalized.facade.namespace }
+    ));
+  }
+
+  if (!Array.isArray(facadeSymbols) || facadeSymbols.length === 0 || facadeSymbols.some((symbol) => !isNonEmptyString(symbol))) {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LOWERABLE_LIBRARY_SYMBOLS_REQUIRED',
+      `Lowerable library manifest ${normalized.contractId || '<unknown>'} must declare one or more facade symbols.`,
+      'Add facade.symbols with the narrow lowerable symbols only.',
+      { symbols: facadeSymbols }
+    ));
+  }
+
+  if (publicApiSymbols !== undefined && (!Array.isArray(publicApiSymbols) || publicApiSymbols.some((symbol) => !isNonEmptyString(symbol)))) {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LOWERABLE_LIBRARY_PUBLIC_API_SYMBOLS_INVALID',
+      `Lowerable library manifest ${normalized.contractId || '<unknown>'} has an invalid publicApi.symbols list.`,
+      'Use static strings when documenting the ergonomic public package API.',
+      { symbols: publicApiSymbols }
+    ));
+  }
+
+  if (!isNonEmptyString(normalized.modes.typescript.entry)) {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LOWERABLE_LIBRARY_TYPESCRIPT_ENTRY_REQUIRED',
+      `Lowerable library manifest ${normalized.contractId || '<unknown>'} must declare modes.typescript.entry.`,
+      'Declare the package runtime TypeScript/ESM entry for normal JS ergonomics.',
+      { entry: normalized.modes.typescript.entry }
+    ));
+  }
+
+  if (!isNonEmptyString(normalized.modes.jsEngine.entry)) {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LOWERABLE_LIBRARY_JS_ENGINE_ENTRY_REQUIRED',
+      `Lowerable library manifest ${normalized.contractId || '<unknown>'} must declare modes.jsEngine.entry.`,
+      'Declare the manual JS engine escape-hatch entry.',
+      { entry: normalized.modes.jsEngine.entry }
+    ));
+  }
+
+  if (!isNonEmptyString(wasm.sidecar)) {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LOWERABLE_LIBRARY_WASM_SIDECAR_REQUIRED',
+      `Lowerable library manifest ${normalized.contractId || '<unknown>'} must declare modes.wasm.sidecar.`,
+      'Declare the AssemblyScript sidecar used by compiled-Wasm compatibility.',
+      { sidecar: wasm.sidecar }
+    ));
+  }
+
+  if (!Array.isArray(wasm.lowerings) || wasm.lowerings.length === 0) {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LOWERABLE_LIBRARY_LOWERINGS_REQUIRED',
+      `Lowerable library manifest ${normalized.contractId || '<unknown>'} must declare modes.wasm.lowerings.`,
+      'Declare the static facade-to-sidecar symbols that lowering may recognize.',
+      { lowerings: wasm.lowerings }
+    ));
+  }
+
+  for (const lowering of wasm.lowerings || []) {
+    if (!lowering || !isNonEmptyString(lowering.tsSymbol) || !isNonEmptyString(lowering.asSymbol)) {
+      diagnostics.push(makeDiagnostic(
+        'PULSEWASM_LOWERABLE_LIBRARY_LOWERING_INVALID',
+        `Lowerable library manifest ${normalized.contractId || '<unknown>'} declares an invalid lowering.`,
+        'Each lowering must include static tsSymbol and asSymbol strings.',
+        { lowering }
+      ));
+    }
+  }
+
+  if (!isNonEmptyString(compiler.version)) {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LOWERABLE_LIBRARY_COMPILER_VERSION_REQUIRED',
+      `Lowerable library manifest ${normalized.contractId || '<unknown>'} must declare compiler.version.`,
+      'Declare the package-owned compiler builder protocol version, for example pulsewasm.lowerable-compiler-builder.v1.',
+      { compiler }
+    ));
+  }
+
+  if (!isNonEmptyString(compiler.entry)) {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LOWERABLE_LIBRARY_COMPILER_ENTRY_REQUIRED',
+      `Lowerable library manifest ${normalized.contractId || '<unknown>'} must declare compiler.entry.`,
+      'Declare the package-owned compiler builder entry path such as ./pulsewasm.compiler.cjs.',
+      { compiler }
+    ));
+  }
+
+  if (!isNonEmptyString(compiler.export)) {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LOWERABLE_LIBRARY_COMPILER_EXPORT_REQUIRED',
+      `Lowerable library manifest ${normalized.contractId || '<unknown>'} must declare compiler.export.`,
+      'Declare the exported builder function name, for example buildAssetsLoweringPlan.',
+      { compiler }
+    ));
+  }
+
+  if (!isNonEmptyString(compiler.builderOwner)) {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LOWERABLE_LIBRARY_COMPILER_OWNER_REQUIRED',
+      `Lowerable library manifest ${normalized.contractId || '<unknown>'} must declare compiler.builderOwner.`,
+      'The package that owns the facade must also own the lowerer entry for this package-out track.',
+      { compiler }
+    ));
+  }
+
+  if (compiler.builderOwner && normalized.npmPackage && compiler.builderOwner !== normalized.npmPackage) {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LOWERABLE_LIBRARY_COMPILER_OWNER_MISMATCH',
+      `Lowerable library manifest ${normalized.contractId || '<unknown>'} compiler builderOwner must match npmPackage.`,
+      'Keep package-specific lowering rules in the package that owns the lowerable facade.',
+      { npmPackage: normalized.npmPackage, builderOwner: compiler.builderOwner }
+    ));
+  }
+
+  if (compiler.trust !== 'first-party') {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_LOWERABLE_LIBRARY_COMPILER_TRUST_REQUIRED',
+      `Lowerable library manifest ${normalized.contractId || '<unknown>'} compiler.trust must be "first-party" in this track.`,
+      'Arbitrary third-party lowerer execution is not enabled; first-party package builders must opt in explicitly.',
+      { trust: compiler.trust }
+    ));
+  }
+
+  return {
+    status: diagnostics.length === 0 ? 'ok' : 'error',
+    manifest: normalized,
+    contractId: normalized.contractId || '<unknown>',
+    npmPackage: normalized.npmPackage,
+    lowerableSubpath: normalized.lowerableSubpath,
+    facade: {
+      namespace: normalized.facade.namespace,
+      symbols: Array.isArray(facadeSymbols) ? facadeSymbols.slice() : []
+    },
+    publicApi: {
+      package: normalized.publicApi.package || normalized.npmPackage,
+      symbols: Array.isArray(publicApiSymbols) ? publicApiSymbols.slice() : []
+    },
+    compiler: {
+      version: normalized.compiler.version,
+      entry: normalized.compiler.entry,
+      export: normalized.compiler.export,
+      artifact: normalized.compiler.artifact,
+      builderOwner: normalized.compiler.builderOwner,
+      trust: normalized.compiler.trust,
+      inputs: Array.isArray(normalized.compiler.inputs) ? normalized.compiler.inputs.slice() : []
+    },
+    hostCapabilities: sortedUnique([...(wasm.hostCapabilities || []), ...((wasm.lowerings || []).flatMap((lowering) => lowering.hostCapabilities || []))]),
+    diagnostics
+  };
+}
+
+module.exports = {
+  LOWERABLE_LIBRARY_MANIFEST_VERSION,
+  LOWERABLE_LIBRARY_MANIFEST_KIND,
+  LOWERABLE_LIBRARY_PAYLOAD_MODE_STATUSES,
+  LOWERABLE_LIBRARY_MANIFEST_REQUIRED_FIELDS,
+  LOWERABLE_LIBRARY_MANIFEST_POLICY,
+  clone,
+  sortedUnique,
+  normalizeManifest,
+  validateLowerableLibraryManifest
+};