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

package/src/library/second-package-owned-lowering.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const SECOND_PACKAGE_OWNED_LOWERING_PROOF_VERSION = 'pulsewasm.second-package-owned-lowering-proof.v1';
+const SECOND_PACKAGE_OWNED_LOWERING_PROOF_ARTIFACT = 'second-package-owned-lowering-proof.json';
+const GRIP_LOWERING_PLAN_VERSION = 'pulsewasm.grip-lowering-plan.v1';
+const GRIP_LOWERING_PLAN_ARTIFACT = 'grip-lowering-plan.json';
+
+const SECOND_PACKAGE_OWNED_LOWERING_SCOPE = Object.freeze({
+  phase: '54',
+  firstPackage: '@pulse-compute/assets',
+  secondPackage: '@pulse-compute/grip',
+  firstContractId: 'pulse.assets',
+  secondContractId: 'pulse.grip',
+  purpose: 'Prove the lowerable package protocol is not assets-specific by adding a second package-owned manifest/facade/compiler-builder/sidecar surface.',
+  productionRuntimeRequired: false,
+  providerRuntimeRequired: false
+});
+
+const SECOND_PACKAGE_OWNED_LOWERING_POLICY = Object.freeze({
+  packageOwnsFacade: true,
+  packageOwnsManifest: true,
+  packageOwnsCompilerBuilder: true,
+  packageOwnsSidecarDeclaration: true,
+  libraryKitOwnsGenericDiscovery: true,
+  compilerOwnsPackageMapping: false,
+  arbitraryThirdPartyLowererExecution: false,
+  firstPartyTrustRequired: true,
+  productionGripRuntimeBehavior: false,
+  betaProtocolBreadthOverProductionCompleteness: true
+});
+
+module.exports = {
+  SECOND_PACKAGE_OWNED_LOWERING_PROOF_VERSION,
+  SECOND_PACKAGE_OWNED_LOWERING_PROOF_ARTIFACT,
+  GRIP_LOWERING_PLAN_VERSION,
+  GRIP_LOWERING_PLAN_ARTIFACT,
+  SECOND_PACKAGE_OWNED_LOWERING_SCOPE,
+  SECOND_PACKAGE_OWNED_LOWERING_POLICY
+};

package/src/library/sidecars.js

@@ -0,0 +1,147 @@
+'use strict';
+
+const { normalizeDiagnostic } = require('../diagnostics.js');
+const {
+  LIBRARY_CONTRACT_VERSION,
+  ALLOWED_HOST_CAPABILITIES,
+  normalizeContractModeKeys
+} = require('./contracts.js');
+const LIBRARY_SIDECAR_PHASE = '12C';
+const LIBRARY_SIDECAR_CONSUMPTION_VERSION = 'pulsewasm.library-sidecar-consumption.v1';
+const CTX_EXTENSION_SCOPE_MAP_VERSION = 'pulsewasm.ctx-extension-scope-map.v1';
+const LIBRARY_SIDECAR_SMOKE_VERSION = 'pulsewasm.library-sidecar-smoke.v1';
+
+function makeDiagnostic(code, message, hint, details) {
+  return normalizeDiagnostic({
+    phase: 'library-sidecars',
+    severity: 'error',
+    code,
+    message,
+    hint,
+    details,
+    loc: { file: '<library-sidecars>' }
+  });
+}
+
+function defaultCtxExtensionContract() {
+  return {
+    version: LIBRARY_CONTRACT_VERSION,
+    package: 'pulse.test-extension',
+    description: 'Phase 12C fixture contract proving declared ctx extension installation, scope checking, AS sidecar linking, and lowering.',
+    modes: {
+      typescript: { entry: './dist/index.js' },
+      jsEngine: { entry: './dist/index.js' },
+      wasm: {
+        mode: 'wasm-sidecar',
+        sidecar: './as/index.as.ts',
+        hostCapabilities: ['headers', 'result'],
+        lowerings: [
+          {
+            tsSymbol: 'ctx.test.mark',
+            asSymbol: 'pulse_test_mark',
+            callShape: 'ctx-extension-literal-string',
+            hostCapabilities: ['headers', 'result']
+          }
+        ],
+        ctxExtensions: [
+          {
+            namespace: 'test',
+            installedBy: { kind: 'middleware', tsSymbol: 'testExtension' },
+            methods: [
+              {
+                tsPath: 'ctx.test.mark',
+                asSymbol: 'pulse_test_mark',
+                callShape: 'literal-string',
+                hostCapabilities: ['headers', 'result']
+              }
+            ]
+          }
+        ]
+      }
+    },
+    policy: {
+      fixtureOnly: true,
+      inferredCompatibility: false,
+      arbitraryTsCompilation: false,
+      sidecarRequiredForWasm: true,
+      scopeCheckedCtxExtension: true,
+      realGripSemanticsImplemented: false,
+      assetsImplemented: false
+    }
+  };
+}
+
+function validateCtxExtensions(contract) {
+  const diagnostics = [];
+  const modes = normalizeContractModeKeys(contract.modes);
+  const wasm = modes.wasm || {};
+  const extensions = Array.isArray(wasm.ctxExtensions) ? wasm.ctxExtensions : [];
+  for (const extension of extensions) {
+    if (!extension || typeof extension.namespace !== 'string' || extension.namespace.length === 0) {
+      diagnostics.push(makeDiagnostic(
+        'PULSEWASM_LIBRARY_CTX_EXTENSION_NAMESPACE_REQUIRED',
+        `Library ${contract.package || '<unknown>'} declares a ctx extension without a static namespace.`,
+        'Declare modes.wasm.ctxExtensions[].namespace as a static string.',
+        { package: contract.package, extension }
+      ));
+      continue;
+    }
+    if (!extension.installedBy || extension.installedBy.kind !== 'middleware' || typeof extension.installedBy.tsSymbol !== 'string') {
+      diagnostics.push(makeDiagnostic(
+        'PULSEWASM_LIBRARY_CTX_EXTENSION_INSTALLER_REQUIRED',
+        `ctx.${extension.namespace} must declare the middleware symbol that installs it.`,
+        'Declare installedBy: { kind: "middleware", tsSymbol: "..." } for compiled-Wasm scope tracking.',
+        { package: contract.package, extension }
+      ));
+    }
+    const methods = Array.isArray(extension.methods) ? extension.methods : [];
+    if (methods.length === 0) {
+      diagnostics.push(makeDiagnostic(
+        'PULSEWASM_LIBRARY_CTX_EXTENSION_METHODS_REQUIRED',
+        `ctx.${extension.namespace} declares no lowerable methods.`,
+        'Declare at least one methods[] entry with tsPath and asSymbol.',
+        { package: contract.package, extension }
+      ));
+    }
+    for (const method of methods) {
+      if (!method || typeof method.tsPath !== 'string' || typeof method.asSymbol !== 'string') {
+        diagnostics.push(makeDiagnostic(
+          'PULSEWASM_LIBRARY_CTX_EXTENSION_METHOD_INVALID',
+          `ctx.${extension.namespace} declares an invalid extension method.`,
+          'Each method must include static tsPath and asSymbol strings.',
+          { package: contract.package, extension, method }
+        ));
+      }
+      for (const capability of method.hostCapabilities || []) {
+        if (!ALLOWED_HOST_CAPABILITIES.includes(capability)) {
+          diagnostics.push(makeDiagnostic(
+            'PULSEWASM_LIBRARY_CTX_EXTENSION_UNKNOWN_CAPABILITY',
+            `ctx.${extension.namespace}.${method && method.tsPath ? method.tsPath : '<method>'} requires unknown host capability ${JSON.stringify(capability)}.`,
+            `Use one of: ${ALLOWED_HOST_CAPABILITIES.join(', ')}.`,
+            { package: contract.package, capability }
+          ));
+        }
+      }
+    }
+  }
+  return { extensions, diagnostics };
+}
+
+function ctxExtensionValidationExamples() {
+  return [
+    { source: 'ctx.test.mark("ok")', status: 'allowed-in-installed-scope', lowering: 'pulse_test_mark(ctx, "ok")' },
+    { source: 'ctx.test.mark("ok")', status: 'rejected-outside-installed-scope', diagnostic: 'PULSEWASM_CTX_EXTENSION_NOT_IN_SCOPE' },
+    { source: 'ctx.anythingElse.foo()', status: 'rejected-undeclared-extension', diagnostic: 'PULSEWASM_CTX_EXTENSION_UNDECLARED' },
+    { source: 'const t = ctx.test; t.mark("ok")', status: 'rejected-extension-aliasing', diagnostic: 'PULSEWASM_CTX_EXTENSION_ESCAPE_UNSUPPORTED' }
+  ];
+}
+
+module.exports = {
+  LIBRARY_SIDECAR_PHASE,
+  LIBRARY_SIDECAR_CONSUMPTION_VERSION,
+  CTX_EXTENSION_SCOPE_MAP_VERSION,
+  LIBRARY_SIDECAR_SMOKE_VERSION,
+  defaultCtxExtensionContract,
+  validateCtxExtensions,
+  ctxExtensionValidationExamples
+};

package/src/logging.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const LOGGING_CONTRACT_VERSION = 'pulse.logging.v1';
+const DEFAULT_REPORTING_LEVEL = 'info';
+const REPORTING_LEVEL_NAMES = Object.freeze(['off', 'error', 'warn', 'info', 'debug']);
+const REPORTING_LEVELS = Object.freeze(Object.fromEntries(
+  REPORTING_LEVEL_NAMES.map((name, level) => [name, level])
+));
+const LOG_METHOD_LEVELS = Object.freeze({
+  error: REPORTING_LEVELS.error,
+  warn: REPORTING_LEVELS.warn,
+  info: REPORTING_LEVELS.info,
+  debug: REPORTING_LEVELS.debug
+});
+const PULSE_LOG_ABI = Object.freeze({
+  version: 'pulse.log-abi.v1',
+  operation: 'pulse_log',
+  signature: 'pulse_log(level:i32,message_ptr:i32,message_len:i32)->void',
+  parameters: Object.freeze([
+    Object.freeze({ name: 'level', type: 'i32' }),
+    Object.freeze({ name: 'message_ptr', type: 'i32' }),
+    Object.freeze({ name: 'message_len', type: 'i32' })
+  ]),
+  result: 'void',
+  synchronous: true,
+  effect: false,
+  continuation: false,
+  suspension: false,
+  providerAdapterOwned: true
+});
+
+function normalizeReportingLevel(value = DEFAULT_REPORTING_LEVEL, field = 'reporting') {
+  const normalized = String(value).trim().toLowerCase();
+  if (!Object.prototype.hasOwnProperty.call(REPORTING_LEVELS, normalized)) {
+    const error = new TypeError(`${field} must be one of ${REPORTING_LEVEL_NAMES.join(', ')}.`);
+    error.code = 'PULSE_REPORTING_LEVEL_UNSUPPORTED';
+    error.details = Object.freeze({ field, value, allowed: REPORTING_LEVEL_NAMES });
+    throw error;
+  }
+  return normalized;
+}
+
+function reportingLevelNumber(value = DEFAULT_REPORTING_LEVEL, field = 'reporting') {
+  return REPORTING_LEVELS[normalizeReportingLevel(value, field)];
+}
+
+function resolveReportingLevel(profileReporting, pulseReporting = DEFAULT_REPORTING_LEVEL) {
+  return normalizeReportingLevel(
+    profileReporting === undefined || profileReporting === null
+      ? pulseReporting
+      : profileReporting,
+    'reporting'
+  );
+}
+
+function reportingDescriptor(value = DEFAULT_REPORTING_LEVEL) {
+  const name = normalizeReportingLevel(value);
+  return Object.freeze({
+    version: LOGGING_CONTRACT_VERSION,
+    name,
+    level: REPORTING_LEVELS[name],
+    default: name === DEFAULT_REPORTING_LEVEL,
+    abi: PULSE_LOG_ABI
+  });
+}
+
+function logStatementEnabled(statementLevel, reportingLevel) {
+  const statement = typeof statementLevel === 'number'
+    ? statementLevel
+    : LOG_METHOD_LEVELS[String(statementLevel)];
+  const reporting = typeof reportingLevel === 'number'
+    ? reportingLevel
+    : reportingLevelNumber(reportingLevel);
+  return Number.isInteger(statement) && statement >= REPORTING_LEVELS.error && statement <= reporting;
+}
+
+module.exports = Object.freeze({
+  LOGGING_CONTRACT_VERSION,
+  DEFAULT_REPORTING_LEVEL,
+  REPORTING_LEVEL_NAMES,
+  REPORTING_LEVELS,
+  LOG_METHOD_LEVELS,
+  PULSE_LOG_ABI,
+  normalizeReportingLevel,
+  reportingLevelNumber,
+  resolveReportingLevel,
+  reportingDescriptor,
+  logStatementEnabled
+});