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

package/src/handler/lifecycle-authoring-alignment.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const LIFECYCLE_AUTHORING_ALIGNMENT_VERSION = 'pulsewasm.lifecycle-authoring-alignment.v1';
+const LIFECYCLE_AUTHORING_ALIGNMENT_PHASE = '52';
+const LIFECYCLE_AUTHORING_ALIGNMENT_ARTIFACT = 'lifecycle-authoring-alignment.json';
+const LIFECYCLE_AUTHORING_ALIGNMENT_CONTRACT_ID = 'pulse.lifecycle-authoring-alignment';
+
+const LIFECYCLE_AUTHORING_ALIGNMENT_SCOPE = Object.freeze({
+  betaApp: 'examples/beta-lifecycle/app.js',
+  assetsPackageOutApp: 'examples/assets-package-out/app.js',
+  command: 'corepack pnpm run -s test:lifecycle-authoring-alignment',
+  publicRouterHeadRequired: true,
+  routeEffectMethodConsistencyRequired: true,
+  doctorAlignmentOutputRequired: true,
+  docsExamplesCurrentRequired: true
+});
+
+const LIFECYCLE_AUTHORING_ALIGNMENT_POLICY = Object.freeze({
+  purpose: 'make the beta lowerable authoring subset explicit and fail fast when route methods and package-owned lowerable effect methods diverge',
+  productionCompletenessRequired: false,
+  simpleUserFunctionLoweringIntentional: true,
+  routerMethods: Object.freeze(['GET', 'HEAD', 'POST']),
+  packageEffectAlignment: Object.freeze({
+    assets: Object.freeze({
+      rule: 'assets.lookup method must match the owning router route method when route metadata is available',
+      diagnostic: 'PULSEWASM_ASSETS_ROUTE_METHOD_MISMATCH',
+      fix: 'use router.head(...) with assets.lookup(..., { method: "HEAD" }) or router.get(...) with GET lookups'
+    })
+  }),
+  stillUnsupported: Object.freeze({
+    dynamicRouteRegistration: false,
+    computedRouterMethods: false,
+    dynamicAssetKeys: false,
+    dynamicBackends: false,
+    asyncAwait: false,
+    promises: false,
+    arbitraryObjectLowering: false,
+    binaryBodies: false,
+    streams: false,
+    multipart: false,
+    uploads: false
+  })
+});
+
+module.exports = {
+  LIFECYCLE_AUTHORING_ALIGNMENT_VERSION,
+  LIFECYCLE_AUTHORING_ALIGNMENT_PHASE,
+  LIFECYCLE_AUTHORING_ALIGNMENT_ARTIFACT,
+  LIFECYCLE_AUTHORING_ALIGNMENT_CONTRACT_ID,
+  LIFECYCLE_AUTHORING_ALIGNMENT_SCOPE,
+  LIFECYCLE_AUTHORING_ALIGNMENT_POLICY
+};

package/src/handler/lifecycle-readiness-aggregate.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const LIFECYCLE_READINESS_AGGREGATE_VERSION = 'pulsewasm.lifecycle-readiness-aggregate.v1';
+const LIFECYCLE_READINESS_AGGREGATE_PHASE = '53';
+const LIFECYCLE_READINESS_AGGREGATE_ARTIFACT = 'lifecycle-readiness-aggregate.json';
+const LIFECYCLE_READINESS_AGGREGATE_CONTRACT_ID = 'pulse.lifecycle-readiness-aggregate';
+
+const LIFECYCLE_READINESS_AGGREGATE_SCOPE = Object.freeze({
+  betaApp: 'examples/beta-lifecycle/app.js',
+  referenceApp: 'examples/reference-node-lifecycle/app.js',
+  assetsPackageOutApp: 'examples/assets-package-out/app.js',
+  command: 'corepack pnpm run -s test:lifecycle-readiness',
+  doctorCommand: 'pulsewasm doctor examples/beta-lifecycle/app.js',
+  nodeProviderReadinessRequired: true,
+  fastlyProviderReadinessRequired: true,
+  routeReadinessRequired: true,
+  packageReadinessRequired: true,
+  proofArtifactsAggregated: true,
+  productionCompletenessRequired: false
+});
+
+const LIFECYCLE_READINESS_STATES = Object.freeze({
+  implemented: 'implemented',
+  implementedNarrow: 'implemented-narrow',
+  implementedNarrowTerminalAssets: 'implemented-narrow-terminal-get-head-text',
+  symbolicParity: 'symbolic-parity',
+  proofAvailable: 'proof-available',
+  planOnly: 'plan-only',
+  reserved: 'reserved',
+  notRequired: 'not-required',
+  notSupported: 'not-supported',
+  splitProofRequired: 'split-proof-required',
+  unknown: 'unknown'
+});
+
+const LIFECYCLE_READINESS_AGGREGATE_POLICY = Object.freeze({
+  purpose: 'make pulsewasm doctor the developer-facing source of truth for beta lifecycle route, package, provider, and unsupported-edge readiness',
+  productionCompletenessRequired: false,
+  betaQualityTarget: true,
+  providerSpecificReadinessRequired: true,
+  aggregateSourceArtifacts: Object.freeze([
+    'handler-io-lifecycle-plan.json',
+    'reference-node-lifecycle-golden.json',
+    'beta-lifecycle-golden.json',
+    'lifecycle-authoring-alignment.json',
+    'node-live-origin-route-handler-effect-proof.json',
+    'node-compiled-route-handler-effect-bridge.json',
+    'node-backend-json-request-body-proof.json',
+    'fastly-lifecycle-parity-proof.json',
+    'assets-package-owned-lowering-proof.json',
+    'assets-package-out-discovery-proof.json',
+    'assets-compiled-wasm-sidecar-plan.json',
+    'assets-sidecar-compile-link-proof.json',
+    'node-compiled-wasm-assets-lifecycle-proof.json',
+    'fastly-assets-package-out-parity-proof.json'
+  ]),
+  routeReadinessMustExplain: Object.freeze([
+    'route',
+    'handler',
+    'node backend/live-origin/compiled-Wasm readiness',
+    'Fastly backend/parity readiness',
+    'request body/schema posture',
+    'backend JSON body posture',
+    'assets terminal response posture',
+    'unsupported/reserved body modes',
+    'diagnostics'
+  ]),
+  packageReadinessMustExplain: Object.freeze([
+    'package-owned lowerer',
+    'package-out discovery',
+    'sidecar readiness',
+    'Node direct/provider readiness',
+    'Node compiled-Wasm readiness',
+    'Fastly parity readiness',
+    'Fastly compiled-Wasm plan-only posture',
+    'reserved binary/stream posture'
+  ]),
+  knownBreaksRemainExplicit: Object.freeze({
+    combinedAppCompiledRouteBridge: 'split-proof-required-assets-handlers-not-yet-in-pass38-compiled-handler-lowerer',
+    realAssemblyScriptAssetsSidecarCompileLink: 'dependency-gated-or-implemented',
+    fastlyCompiledWasmAssets: 'plan-only'
+  })
+});
+
+module.exports = {
+  LIFECYCLE_READINESS_AGGREGATE_VERSION,
+  LIFECYCLE_READINESS_AGGREGATE_PHASE,
+  LIFECYCLE_READINESS_AGGREGATE_ARTIFACT,
+  LIFECYCLE_READINESS_AGGREGATE_CONTRACT_ID,
+  LIFECYCLE_READINESS_AGGREGATE_SCOPE,
+  LIFECYCLE_READINESS_AGGREGATE_POLICY,
+  LIFECYCLE_READINESS_STATES
+};

package/src/handler/reference-node-lifecycle-golden.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const REFERENCE_NODE_LIFECYCLE_GOLDEN_VERSION = 'pulsewasm.reference-node-lifecycle-golden.v1';
+const REFERENCE_NODE_LIFECYCLE_GOLDEN_PHASE = '45';
+const REFERENCE_NODE_LIFECYCLE_GOLDEN_ARTIFACT = 'reference-node-lifecycle-golden.json';
+const REFERENCE_NODE_LIFECYCLE_GOLDEN_CONTRACT_ID = 'pulse.reference-node-lifecycle-golden';
+
+const REFERENCE_NODE_LIFECYCLE_GOLDEN_SCOPE = Object.freeze({
+  referenceApp: 'examples/reference-node-lifecycle/app.js',
+  command: 'corepack pnpm run -s test:reference-node-lifecycle',
+  publicSurfaceOnly: true,
+  compilerOrchestrates: true,
+  providersOwnProviderBehavior: true,
+  nodeLiveOriginProviderProof: true,
+  nodeCompiledWasmResolveResumeBridge: true,
+  requestJsonDecodeLifecycle: true,
+  schemaEncodeDecodeLifecycle: true,
+  backendJsonRequestBodies: true,
+  fastlyLifecycleParity: true,
+  fastlyPostJsonRequestBodyReadiness: 'plan-only',
+  noReferenceAppSpecialPath: true,
+  noHiddenEagerWork: true,
+  noUserAuthoredAsync: true,
+  promises: false,
+  asyncAwait: false,
+  asyncify: false
+});
+
+const REFERENCE_NODE_LIFECYCLE_GOLDEN_POLICY = Object.freeze({
+  appBoundary: 'reference app uses only public router/ctx surfaces',
+  harnessBoundary: 'tests and proof builders may orchestrate origins/providers/CLI commands',
+  requiredCommand: 'corepack pnpm run -s test:reference-node-lifecycle',
+  validates: [
+    'CLI plan',
+    'CLI doctor',
+    'CLI build',
+    'artifact freshness',
+    'handler I/O lifecycle artifact',
+    'Node live-origin provider proof',
+    'Node compiled-Wasm resolve/resume bridge',
+    'lazy ctx.req.json',
+    'schema-backed request decode',
+    'schema decode result ergonomics',
+    'schema-backed final response encode',
+    'origin response schema decode',
+    'backend JSON request bodies',
+    'Fastly lifecycle parity',
+    'unsupported body-mode diagnostics',
+    'public-surface-only reference app',
+    'no reference app special path'
+  ],
+  unsupportedOutOfScope: [
+    'binary bodies',
+    'stream bodies',
+    'async/await lowering',
+    'Promise lowering',
+    'Asyncify',
+    'automatic schema generation',
+    'arbitrary JS object lowering',
+    'multipart/form-data',
+    'uploads',
+    'general object-store semantics'
+  ]
+});
+
+module.exports = {
+  REFERENCE_NODE_LIFECYCLE_GOLDEN_VERSION,
+  REFERENCE_NODE_LIFECYCLE_GOLDEN_PHASE,
+  REFERENCE_NODE_LIFECYCLE_GOLDEN_ARTIFACT,
+  REFERENCE_NODE_LIFECYCLE_GOLDEN_CONTRACT_ID,
+  REFERENCE_NODE_LIFECYCLE_GOLDEN_SCOPE,
+  REFERENCE_NODE_LIFECYCLE_GOLDEN_POLICY
+};

package/src/handler/request-json-body.js

@@ -0,0 +1,147 @@
+'use strict';
+
+const REQUEST_JSON_BODY_PLAN_VERSION = 'pulsewasm.request-json-body-plan.v1';
+const REQUEST_JSON_BODY_PLAN_PHASE = '39';
+const REQUEST_JSON_BODY_PLAN_ARTIFACT = 'request-json-body-plan.json';
+const REQUEST_JSON_BODY_CONTRACT_ID = 'pulse.request-json-body';
+const NODE_REQUEST_JSON_BODY_PROOF_VERSION = 'pulsewasm.node-request-json-body-proof.v1';
+const NODE_REQUEST_JSON_BODY_PROOF_PHASE = '39';
+const NODE_REQUEST_JSON_BODY_PROOF_ARTIFACT = 'node-request-json-body-proof.json';
+const NODE_REQUEST_JSON_BODY_RUNTIME_VERSION = 'pulsewasm.node-request-json-body-runtime.v1';
+
+const REQUEST_JSON_BODY_SCOPE = Object.freeze({
+  lazyRequestBodyRead: true,
+  routeDemandOnly: true,
+  perRequestDecodeCache: true,
+  compiledWasmRuntimeImplemented: true,
+  nodeCompiledProofImplemented: true,
+  providerNetworkFetchRequired: false,
+  backendJsonRequestBodyImplemented: false,
+  binaryRequestBodyParsing: false,
+  streamRequestBodyParsing: false,
+  requestBodyEffects: false,
+  asyncAwait: false,
+  promises: false,
+  asyncify: false,
+  automaticSchemaGeneration: false,
+  arbitraryJsObjectInference: false
+});
+
+const REQUEST_JSON_BODY_SURFACE = Object.freeze({
+  canonical: 'ctx.req.parse("Schema")',
+  schemaSugar: 'ctx.req.json("Schema")',
+  genericSugar: 'ctx.req.json()',
+  aliases: Object.freeze(['ctx.request.json("Schema")', 'ctx.request.json()']),
+  compiledHandle: 'opaque request-json ref',
+  schemaMode: 'schema-backed request JSON decode',
+  genericMode: 'explicit as-json generic parser fallback'
+});
+
+const REQUEST_JSON_BODY_MODES = Object.freeze({
+  none: { status: 'implemented-now', description: 'route does not read a request JSON body' },
+  schemaJson: { status: 'implemented-compiled-node-proof', surface: 'ctx.req.json("Schema") / ctx.req.parse("Schema")' },
+  genericJson: { status: 'implemented-compiled-node-proof', surface: 'ctx.req.json() with explicit as-json fallback config' },
+  text: { status: 'reserved-with-diagnostic', surface: 'ctx.req.text()' },
+  binary: { status: 'reserved-with-diagnostic', surface: 'ctx.req.arrayBuffer() / binary request body parsing' },
+  stream: { status: 'reserved-with-diagnostic', surface: 'ctx.req.stream() / stream request body parsing' }
+});
+
+const REQUEST_JSON_BODY_ACCESSORS = Object.freeze([
+  'ok',
+  'errorText',
+  'jsonText',
+  'getString',
+  'getI32',
+  'getU32',
+  'getF64',
+  'getBool',
+  'has'
+]);
+
+const REQUEST_JSON_BODY_RESERVED_ACCESSORS = Object.freeze([
+  'bytes',
+  'stream',
+  'json object materialization',
+  'typed schema-specific accessors',
+  'schema-backed result ergonomics are owned by @pulse-compute/wasm-contracts/handler/schema-decode-result',
+  'mutation APIs',
+  'automatic schema inference'
+]);
+
+const REQUEST_JSON_BODY_LAZY_POLICY = Object.freeze({
+  bodyRead: 'route-demand-only',
+  parse: 'first ctx.req.json/parse call only',
+  cache: 'per-request body/decode refs',
+  repeatedReads: 'cached; no reread or reparse',
+  noEagerParsing: true,
+  noImplicitGenericParserBundle: true,
+  missingBody: 'empty text decoded as invalid JSON for json helpers',
+  invalidJson: 'inspectable decode result; no throw'
+});
+
+const REQUEST_JSON_BODY_DIAGNOSTICS = Object.freeze({
+  planMissing: 'PULSEWASM_REQUEST_JSON_BODY_PLAN_MISSING',
+  nonLiteralSchema: 'PULSEWASM_REQUEST_JSON_SCHEMA_MUST_BE_LITERAL',
+  genericParserRequired: 'PULSEWASM_REQUEST_JSON_GENERIC_PARSER_REQUIRED',
+  unsupportedParser: 'PULSEWASM_REQUEST_JSON_GENERIC_PARSER_UNSUPPORTED',
+  schemaRequired: 'PULSEWASM_REQUEST_JSON_SCHEMA_REQUIRED',
+  accessorUnsupported: 'PULSEWASM_REQUEST_JSON_ACCESSOR_UNSUPPORTED',
+  accessorPathMustBeLiteral: 'PULSEWASM_REQUEST_JSON_ACCESSOR_PATH_MUST_BE_LITERAL',
+  bodyTextReserved: 'PULSEWASM_REQUEST_JSON_TEXT_BODY_RESERVED',
+  binaryReserved: 'PULSEWASM_REQUEST_JSON_BINARY_BODY_RESERVED',
+  streamReserved: 'PULSEWASM_REQUEST_JSON_STREAM_BODY_RESERVED',
+  compiledSmokeFailed: 'PULSEWASM_REQUEST_JSON_COMPILED_SMOKE_FAILED',
+  wasmMissing: 'PULSEWASM_REQUEST_JSON_COMPILED_WASM_MISSING'
+});
+
+function defaultRequestJsonBodyPolicy() {
+  return {
+    contractId: REQUEST_JSON_BODY_CONTRACT_ID,
+    artifact: REQUEST_JSON_BODY_PLAN_ARTIFACT,
+    phase: REQUEST_JSON_BODY_PLAN_PHASE,
+    scope: { ...REQUEST_JSON_BODY_SCOPE },
+    surface: JSON.parse(JSON.stringify(REQUEST_JSON_BODY_SURFACE)),
+    modes: JSON.parse(JSON.stringify(REQUEST_JSON_BODY_MODES)),
+    accessors: [...REQUEST_JSON_BODY_ACCESSORS],
+    reservedAccessors: [...REQUEST_JSON_BODY_RESERVED_ACCESSORS],
+    lazy: JSON.parse(JSON.stringify(REQUEST_JSON_BODY_LAZY_POLICY)),
+    diagnostics: { ...REQUEST_JSON_BODY_DIAGNOSTICS }
+  };
+}
+
+function defaultNodeRequestJsonBodyProofPolicy() {
+  return {
+    ...defaultRequestJsonBodyPolicy(),
+    provider: 'node',
+    proofArtifact: NODE_REQUEST_JSON_BODY_PROOF_ARTIFACT,
+    proofVersion: NODE_REQUEST_JSON_BODY_PROOF_VERSION,
+    runtimeVersion: NODE_REQUEST_JSON_BODY_RUNTIME_VERSION,
+    compiledWasmRuntimeImplemented: true,
+    nodeCompiledProofImplemented: true,
+    actualNetworkFetch: false,
+    userAuthoredAsync: false,
+    promises: false,
+    asyncAwait: false,
+    asyncify: false
+  };
+}
+
+module.exports = {
+  REQUEST_JSON_BODY_PLAN_VERSION,
+  REQUEST_JSON_BODY_PLAN_PHASE,
+  REQUEST_JSON_BODY_PLAN_ARTIFACT,
+  REQUEST_JSON_BODY_CONTRACT_ID,
+  NODE_REQUEST_JSON_BODY_PROOF_VERSION,
+  NODE_REQUEST_JSON_BODY_PROOF_PHASE,
+  NODE_REQUEST_JSON_BODY_PROOF_ARTIFACT,
+  NODE_REQUEST_JSON_BODY_RUNTIME_VERSION,
+  REQUEST_JSON_BODY_SCOPE,
+  REQUEST_JSON_BODY_SURFACE,
+  REQUEST_JSON_BODY_MODES,
+  REQUEST_JSON_BODY_ACCESSORS,
+  REQUEST_JSON_BODY_RESERVED_ACCESSORS,
+  REQUEST_JSON_BODY_LAZY_POLICY,
+  REQUEST_JSON_BODY_DIAGNOSTICS,
+  defaultRequestJsonBodyPolicy,
+  defaultNodeRequestJsonBodyProofPolicy
+};