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

package/src/package/package-contract.schema.json

@@ -0,0 +1,303 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://pulsecompute.io/contracts/pulse.package-contract.v1.schema.json",
+  "title": "Pulse package contract v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "kind",
+    "contractId",
+    "npmPackage",
+    "authoring",
+    "ownership",
+    "composition",
+    "targets",
+    "lowering",
+    "conformance",
+    "docs"
+  ],
+  "properties": {
+    "version": {
+      "const": "pulse.package-contract.v1"
+    },
+    "kind": {
+      "const": "pulse.package-contract"
+    },
+    "contractId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)+$"
+    },
+    "npmPackage": {
+      "type": "string",
+      "pattern": "^(?:@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*$"
+    },
+    "description": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "authoring": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "namespace",
+        "import",
+        "symbols"
+      ],
+      "properties": {
+        "namespace": {
+          "type": "string",
+          "minLength": 1
+        },
+        "import": {
+          "$ref": "#/$defs/packageSpecifier"
+        },
+        "symbols": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        }
+      }
+    },
+    "ownership": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "profileFragment",
+        "helperImports",
+        "reExportImports"
+      ],
+      "properties": {
+        "profileFragment": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "helperImports": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/packageSpecifier"
+          },
+          "uniqueItems": true
+        },
+        "reExportImports": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/packageSpecifier"
+          },
+          "uniqueItems": true
+        }
+      }
+    },
+    "composition": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "profileToken"
+      ],
+      "properties": {
+        "status": {
+          "enum": [
+            "supported",
+            "reserved",
+            "not-realized",
+            "unsupported"
+          ]
+        },
+        "helperSymbol": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "minLength": 1
+        },
+        "profileToken": {
+          "const": "opaque-direct-use"
+        },
+        "reasonCode": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "minLength": 1
+        },
+        "version": {
+          "const": "pulse.package-composition.v1"
+        }
+      }
+    },
+    "targets": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "native",
+        "javascript"
+      ],
+      "properties": {
+        "native": {
+          "$ref": "#/$defs/target"
+        },
+        "javascript": {
+          "$ref": "#/$defs/target"
+        }
+      }
+    },
+    "lowering": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "manifest",
+        "trust",
+        "canonicalOperationVersion",
+        "bundleVersion",
+        "providerRequirementVersion"
+      ],
+      "properties": {
+        "manifest": {
+          "$ref": "#/$defs/packageRelativePath"
+        },
+        "trust": {
+          "const": "first-party"
+        },
+        "canonicalOperationVersion": {
+          "const": "pulse.canonical-package-operation.v1"
+        },
+        "bundleVersion": {
+          "const": "pulse.package-lowering-bundle.v1"
+        },
+        "providerRequirementVersion": {
+          "const": "pulse.provider-requirement-record.v1"
+        }
+      }
+    },
+    "conformance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "fixtureRoots",
+        "semanticCases"
+      ],
+      "properties": {
+        "status": {
+          "enum": [
+            "native-contract-only",
+            "target-overlap",
+            "not-realized"
+          ]
+        },
+        "fixtureRoots": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/packageRelativePath"
+          },
+          "uniqueItems": true
+        },
+        "semanticCases": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "version": {
+          "const": "pulse.package-conformance.v1"
+        }
+      }
+    },
+    "docs": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "readme",
+        "contract"
+      ],
+      "properties": {
+        "readme": {
+          "$ref": "#/$defs/packageRelativePath"
+        },
+        "contract": {
+          "$ref": "#/$defs/packageRelativePath"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "packageSpecifier": {
+      "type": "string",
+      "pattern": "^(?:@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*(?:/[A-Za-z0-9._-]+)*$"
+    },
+    "packageRelativePath": {
+      "type": "string",
+      "pattern": "^\\./(?!.*(?:^|/)\\.\\.(?:/|$)).+$"
+    },
+    "target": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "realization",
+        "providerRequirements"
+      ],
+      "properties": {
+        "status": {
+          "enum": [
+            "supported",
+            "provider-dependent",
+            "not-realized",
+            "unsupported"
+          ]
+        },
+        "realization": {
+          "enum": [
+            "canonical-package-lowering",
+            "javascript-package-runtime",
+            "provider-runtime",
+            "none"
+          ]
+        },
+        "entry": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "minLength": 1
+        },
+        "lowerableSubpath": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/packageSpecifier"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "providerRequirements": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "reasonCode": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "minLength": 1
+        },
+        "version": {
+          "const": "pulse.package-target-support.v1"
+        }
+      }
+    }
+  }
+}

package/src/package/runtime-pulse-live.js

@@ -0,0 +1,100 @@
+'use strict';
+
+const RUNTIME_PULSE_LIVE_CONTRACT_VERSION = 'pulse.runtime-pulse-live-contract.v4';
+
+function freeze(value) {
+  if (Array.isArray(value)) return Object.freeze(value.map(freeze));
+  if (!value || typeof value !== 'object') return value;
+  return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key, freeze(item)])));
+}
+
+const ROOT_VALUE_EXPORTS = freeze({
+  '@pulse-compute/runtime': ['RUNTIME_API_VERSION', 'ROUTER_API_VERSION', 'Router'],
+  '@pulse-compute/pulse': ['defineConfig', 'Pulse', 'PULSE_APPLICATION_API_VERSION']
+});
+
+const LIVE_RUNTIME_SURFACES = freeze([
+  { id: 'router.registration', status: 'implemented', authority: 'historical TypeScript semantics adapted to Router IR ordering' },
+  { id: 'router.paths-params-mounts', status: 'implemented', authority: 'sealed path grammar and Router IR' },
+  { id: 'router.terminal-transfer', status: 'implemented', authority: 'forward-only next()/next(error) contract' },
+  { id: 'router.error-recovery', status: 'implemented', authority: 'normal/error lane and forward cursor contract' },
+  { id: 'router.default-404-500', status: 'implemented', authority: 'Router-owned response contract' },
+  { id: 'context.request-metadata', status: 'implemented', authority: 'PulseRequest TypeScript contract' },
+  { id: 'context.route-param', status: 'implemented', authority: 'PulseRouteContext TypeScript contract' },
+  { id: 'context.request-state', status: 'implemented', authority: 'request-local string map contract' },
+  { id: 'context.response-helpers', status: 'implemented', authority: 'Pulse result and response contracts' },
+  { id: 'context.effects', status: 'implemented-adapter-boundary', authority: 'PulseEffect TypeScript contract; provider realization remains external' },
+  { id: 'runtime.web-request-response', status: 'implemented-internal', authority: 'historical Web boundary adapted to current result algebra' },
+  { id: 'pulse.application-root', status: 'implemented', authority: 'Pulse extends the live Router implementation and shares Router IR' },
+  { id: 'pulse.event-registration', status: 'implemented-static-and-javascript-direct', authority: 'root Pulse-owned exact registration table, static compiler catalog, and transport-free JavaScript host execution' },
+  { id: 'runtime.event-execution', status: 'implemented-node-javascript-direct', authority: 'canonical event frame normalization, schema validation, exact selection, isolated context, and data-only completion result' },
+  { id: 'context.event-emit', status: 'implemented-node-javascript-direct', authority: 'schema-bound execution-owned event.emit effect with bounded host acceptance and no automatic loopback' },
+  { id: 'runtime.event-recording-adapter', status: 'implemented-reference-only', authority: 'bounded deterministic accepted-frame evidence without provider transport or local handler dispatch' },
+  { id: 'pulse.profile-token', status: 'implemented', authority: 'opaque stable token owned by one Pulse instance' },
+  { id: 'pulse.deferred-config', status: 'implemented-preserved', authority: 'symbolic defineConfig factory; no runtime evaluation' }
+]);
+
+const SUPERSEDED_OR_DEFERRED = freeze([
+  'recursive or onion next()',
+  'authored throw as supported application control flow',
+  'implicit handler fallthrough',
+  'Router/Pulse bind, handle, listen, or serve on the public root surface',
+  'dynamic context decoration',
+  'raw host access',
+  'ambient environment/profile resolution',
+  'nested profiles and readable active profile state',
+  'generic session/gateway core',
+  'Native and provider-integrated event handler execution',
+  'Native/provider event emit realization, channels, and local loopback',
+  'public normalized semantic trace',
+  'public JavaScript execution target',
+  'compiler or lowerer plugin registration'
+]);
+
+function defaultRuntimePulseLiveContract() {
+  return freeze({
+    version: RUNTIME_PULSE_LIVE_CONTRACT_VERSION,
+    internalRuntimeVersion: 'pulse.javascript-router-runtime.v1',
+    internalEventRuntimeVersion: 'pulse.javascript-event-runtime.v2',
+    internalApplicationVersion: 'pulse.javascript-application.v1',
+    rootValueExports: ROOT_VALUE_EXPORTS,
+    surfaces: LIVE_RUNTIME_SURFACES,
+    supersededOrDeferred: SUPERSEDED_OR_DEFERRED,
+    policies: {
+      publicRootExportsChanged: false,
+      rootHandleOrLifecyclePublished: false,
+      executionIsPackageInternal: true,
+      pulseSharesRouterImplementation: true,
+      pulseOwnsEventRegistration: true,
+      routerEventRegistration: false,
+      eventHandlersExecuted: true,
+      eventExecutionTarget: 'node-javascript-direct',
+      eventEmitPublished: true,
+      eventEmitTarget: 'node-javascript-direct',
+      eventEmitParallelEligible: true,
+      eventEmitAutomaticLoopback: false,
+      providerCapabilitiesInjected: true,
+      terminalTransferUsesBrandedInternalValue: true,
+      unexpectedFailuresContained: true,
+      requestStateIsolatedPerRequest: true,
+      eventStateIsolatedPerInvocation: true,
+      arbitraryObjectState: false,
+      dynamicContextDecoration: false,
+      rawHostAccess: false,
+      publicJavascriptTargetShipped: false,
+      handlerIrChanged: false,
+      routerIrChanged: false,
+      effectOrContinuationContractChanged: true,
+      packageLoweringSeamChanged: false,
+      providerRequirementContractChanged: false
+    }
+  });
+}
+
+module.exports = {
+  RUNTIME_PULSE_LIVE_CONTRACT_VERSION,
+  ROOT_VALUE_EXPORTS,
+  LIVE_RUNTIME_SURFACES,
+  SUPERSEDED_OR_DEFERRED,
+  defaultRuntimePulseLiveContract
+};

package/src/path-table.js

@@ -0,0 +1,12 @@
+'use strict';
+
+const PATH_TABLE_VERSION = 'pulsewasm.path-table.v1';
+
+const PATH_TABLE_POLICY = Object.freeze({
+  version: PATH_TABLE_VERSION
+});
+
+module.exports = {
+  PATH_TABLE_VERSION,
+  PATH_TABLE_POLICY
+};

package/src/path.js

@@ -0,0 +1,275 @@
+'use strict';
+
+const PATH_GRAMMAR_VERSION = 'pulsewasm.path-grammar.v1';
+
+const PATH_POLICY = {
+  grammarVersion: PATH_GRAMMAR_VERSION,
+  runtimeReference: 'pulse-runtime/src/router-path.ts',
+  normalizer: 'compileRoutePath-compatible strict PulseWasm subset',
+  allowed: {
+    literals: true,
+    params: ':param with JavaScript identifier names',
+    wildcard: 'one unnamed trailing * segment only',
+    scoped: 'mount/use prefixes compile as prefix/* patterns'
+  },
+  rejected: [
+    'dynamic path expressions',
+    'empty middle segments / duplicate slashes',
+    'named wildcard segments such as *rest',
+    'non-trailing wildcards',
+    'duplicate parameter names in a single compiled path',
+    'optional path segments',
+    'regex path segments',
+    'computed route paths'
+  ]
+};
+
+function ensureLeadingSlash(value) {
+  return value.startsWith('/') ? value : `/${value}`;
+}
+
+function trimTrailingSlash(value) {
+  let out = value;
+  while (out.length > 1 && out.endsWith('/')) {
+    out = out.slice(0, -1);
+  }
+  return out;
+}
+
+function normalizeRoutePath(path) {
+  const text = String(path ?? '').trim();
+  return trimTrailingSlash(ensureLeadingSlash(text || '/'));
+}
+
+function stripScopedWildcard(path) {
+  let normalized = normalizeRoutePath(path);
+  if (normalized === '/*') return '/';
+  if (normalized.endsWith('/*')) normalized = normalized.slice(0, -2);
+  if (normalized.endsWith('*')) normalized = normalized.slice(0, -1);
+  return trimTrailingSlash(normalized || '/');
+}
+
+function normalizeScopedPath(path) {
+  const stripped = stripScopedWildcard(path || '/');
+  if (stripped === '/') return '/*';
+  return `${stripped}/*`;
+}
+
+function rawSegments(normalizedPath) {
+  if (normalizedPath === '/') return [];
+  if (!normalizedPath.startsWith('/')) {
+    throw new Error(`PulseWasm path must be absolute after normalization: ${normalizedPath}`);
+  }
+  const body = normalizedPath.slice(1);
+  const segments = body.split('/');
+  const emptyIndex = segments.findIndex((segment) => segment.length === 0);
+  if (emptyIndex !== -1) {
+    throw new Error(`Duplicate or empty path segment is unsupported: ${normalizedPath}`);
+  }
+  return segments;
+}
+
+function parseSegments(normalizedPath, options = {}) {
+  const segments = rawSegments(normalizedPath);
+  const parsed = [];
+  const params = [];
+  const seenParams = new Set();
+  let wildcard = false;
+
+  segments.forEach((segment, index) => {
+    if (segment === '*') {
+      if (!options.allowWildcard) {
+        throw new Error(`Wildcard paths are not supported here: ${normalizedPath}`);
+      }
+      if (index !== segments.length - 1) {
+        throw new Error(`Wildcard must be the final path segment: ${normalizedPath}`);
+      }
+      wildcard = true;
+      parsed.push({ kind: 'wildcard' });
+      return;
+    }
+
+    if (segment.startsWith('*') || segment.includes('*')) {
+      throw new Error(`Only one unnamed trailing * wildcard segment is supported: ${normalizedPath}`);
+    }
+
+    if (segment.startsWith(':')) {
+      const name = segment.slice(1);
+      if (!name) {
+        throw new Error(`Path parameter name cannot be empty: ${normalizedPath}`);
+      }
+      if (!/^[A-Za-z_$][\w$]*$/.test(name)) {
+        throw new Error(`Unsupported path parameter name "${name}" in ${normalizedPath}`);
+      }
+      if (seenParams.has(name)) {
+        throw new Error(`Duplicate path parameter ":${name}" is unsupported: ${normalizedPath}`);
+      }
+      seenParams.add(name);
+      params.push(name);
+      parsed.push({ kind: 'param', name });
+      return;
+    }
+
+    if (!/^[A-Za-z0-9._~!$&'()+,;=@%-]+$/.test(segment)) {
+      throw new Error(`Unsupported literal path segment "${segment}" in ${normalizedPath}`);
+    }
+    parsed.push({ kind: 'literal', value: segment });
+  });
+
+  return { segments: parsed, params, wildcard };
+}
+
+function compileRoutePath(path, options = {}) {
+  const scoped = Boolean(options.scoped);
+  const normalized = scoped ? normalizeScopedPath(path) : normalizeRoutePath(path);
+  const parsed = parseSegments(normalized, {
+    allowWildcard: options.allowWildcard !== false
+  });
+  return {
+    original: String(path ?? ''),
+    normalized,
+    scoped,
+    wildcard: parsed.wildcard,
+    segments: parsed.segments,
+    params: parsed.params,
+    grammarVersion: PATH_GRAMMAR_VERSION
+  };
+}
+
+function publicPathPattern(compiled) {
+  return {
+    grammarVersion: compiled.grammarVersion || PATH_GRAMMAR_VERSION,
+    normalized: compiled.normalized,
+    scoped: Boolean(compiled.scoped),
+    wildcard: Boolean(compiled.wildcard),
+    segments: compiled.segments || [],
+    params: compiled.params || []
+  };
+}
+
+function validatePath(path, options = {}) {
+  const compiled = compileRoutePath(path, {
+    scoped: Boolean(options.scoped),
+    allowWildcard: options.allowWildcard
+  });
+  return {
+    normalized: options.scoped ? stripScopedWildcard(compiled.normalized) : compiled.normalized,
+    params: compiled.params,
+    wildcard: compiled.wildcard,
+    segments: compiled.segments,
+    pattern: publicPathPattern(compiled)
+  };
+}
+
+function joinPaths(prefix, path) {
+  const left = stripScopedWildcard(prefix || '/');
+  const right = normalizeRoutePath(path || '/');
+  if (left === '/') return right;
+  if (right === '/') return left;
+  return normalizeRoutePath(`${left}/${right.replace(/^\/+/, '')}`);
+}
+
+function joinScopedPrefix(prefix, scopedPath) {
+  return stripScopedWildcard(joinPaths(prefix || '/', stripScopedWildcard(scopedPath || '/')));
+}
+
+function splitSegments(path) {
+  const normalized = normalizeRoutePath(path);
+  return rawSegments(normalized);
+}
+
+function extractParams(path) {
+  return compileRoutePath(path, { allowWildcard: true }).params;
+}
+
+function scopedPathMatchDetails(routePath, scopedPath) {
+  const route = compileRoutePath(routePath, { allowWildcard: true });
+  const scoped = compileRoutePath(stripScopedWildcard(scopedPath), { scoped: true, allowWildcard: true });
+  const scopedSegments = scoped.segments.filter((segment) => segment.kind !== 'wildcard');
+  const captures = [];
+
+  if (scopedSegments.length === 0) {
+    return { matches: true, captures, diagnostics: [] };
+  }
+  if (scopedSegments.length > route.segments.length) {
+    return { matches: false, captures, diagnostics: [] };
+  }
+
+  const diagnostics = [];
+  for (let i = 0; i < scopedSegments.length; i += 1) {
+    const expected = scopedSegments[i];
+    const actual = route.segments[i];
+    if (!actual) return { matches: false, captures, diagnostics };
+
+    if (expected.kind === 'literal') {
+      if (actual.kind !== 'literal' || expected.value !== actual.value) {
+        return { matches: false, captures, diagnostics };
+      }
+      continue;
+    }
+
+    if (expected.kind === 'param') {
+      if (actual.kind !== 'param' || actual.name !== expected.name) {
+        diagnostics.push({
+          code: 'PULSEWASM_SCOPED_PARAM_MISMATCH',
+          message: `Scoped middleware parameter :${expected.name} must align with the same route parameter at segment ${i + 1}.`,
+          hint: 'For PulseWasm v1, path-scoped middleware params must be represented by the final flattened route path with the same name.'
+        });
+      } else {
+        captures.push({ name: expected.name, routeParam: actual.name, segmentIndex: i });
+      }
+      continue;
+    }
+  }
+
+  return { matches: diagnostics.length === 0, captures, diagnostics };
+}
+
+function scopedPathMatches(routePath, scopedPath) {
+  return scopedPathMatchDetails(routePath, scopedPath).matches;
+}
+
+function matchRoutePath(compiledPattern, path) {
+  const pattern = compiledPattern.segments ? compiledPattern : compileRoutePath(compiledPattern, { allowWildcard: true });
+  const pathSegments = rawSegments(normalizeRoutePath(path));
+  const params = {};
+  let pathIndex = 0;
+
+  for (const segment of pattern.segments) {
+    if (segment.kind === 'wildcard') {
+      const restSegments = pathSegments.slice(pathIndex);
+      return { params, rest: restSegments.length === 0 ? '/' : `/${restSegments.join('/')}` };
+    }
+
+    const value = pathSegments[pathIndex];
+    if (value == null) return null;
+
+    if (segment.kind === 'literal') {
+      if (segment.value !== value) return null;
+    } else if (segment.kind === 'param') {
+      params[segment.name] = value;
+    }
+    pathIndex += 1;
+  }
+
+  if (pathIndex !== pathSegments.length) return null;
+  return { params, rest: '/' };
+}
+
+module.exports = {
+  PATH_GRAMMAR_VERSION,
+  PATH_POLICY,
+  compileRoutePath,
+  ensureLeadingSlash,
+  extractParams,
+  joinPaths,
+  joinScopedPrefix,
+  matchRoutePath,
+  normalizeRoutePath,
+  normalizeScopedPath,
+  publicPathPattern,
+  scopedPathMatchDetails,
+  scopedPathMatches,
+  stripScopedWildcard,
+  validatePath
+};