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

package/src/project/javascript-application.js

@@ -0,0 +1,212 @@
+'use strict';
+
+const { sha256Hex, stableStringify } = require('../stable-id.js');
+
+const JAVASCRIPT_APPLICATION_PLAN_VERSION = 'pulse.javascript-application-plan.v1';
+const JAVASCRIPT_APPLICATION_LOADER_VERSION = 'pulse.javascript-application-loader.v1';
+const JAVASCRIPT_TARGET_DESCRIPTOR_VERSION = 'pulse.javascript-target-descriptor.v2';
+const JAVASCRIPT_RUNTIME_CLASS = 'javascript';
+
+function deepFreeze(value) {
+  if (Array.isArray(value)) {
+    for (const entry of value) deepFreeze(entry);
+    return Object.freeze(value);
+  }
+  if (value && typeof value === 'object') {
+    for (const entry of Object.values(value)) deepFreeze(entry);
+    return Object.freeze(value);
+  }
+  return value;
+}
+
+function requireString(label, value) {
+  if (typeof value !== 'string' || value.length === 0) throw new TypeError(`${label} must be a non-empty string.`);
+  return value;
+}
+
+function normalizeSource(source) {
+  if (!source) return null;
+  return Object.freeze({
+    file: requireString('JavaScript application source file', source.file),
+    line: Number.isInteger(source.line) && source.line > 0 ? source.line : 1,
+    column: Number.isInteger(source.column) && source.column > 0 ? source.column : 1
+  });
+}
+
+function normalizeModule(module, index) {
+  if (!module || typeof module !== 'object') throw new TypeError(`JavaScript application module ${index} must be an object.`);
+  return Object.freeze({
+    id: requireString(`JavaScript application module ${index} id`, module.id),
+    kind: requireString(`JavaScript application module ${index} kind`, module.kind),
+    format: requireString(`JavaScript application module ${index} format`, module.format),
+    runtime: module.runtime === true,
+    path: module.path == null ? null : requireString(`JavaScript application module ${index} path`, module.path),
+    packageName: module.packageName == null ? null : requireString(`JavaScript application module ${index} packageName`, module.packageName),
+    packageSubpath: module.packageSubpath == null ? null : String(module.packageSubpath),
+    packageContract: module.packageContract == null ? null : String(module.packageContract),
+    externalSpecifier: module.externalSpecifier == null ? null : String(module.externalSpecifier),
+    contentHash: requireString(`JavaScript application module ${index} contentHash`, module.contentHash)
+  });
+}
+
+function normalizeEdge(edge, index) {
+  if (!edge || typeof edge !== 'object') throw new TypeError(`JavaScript application edge ${index} must be an object.`);
+  return Object.freeze({
+    id: requireString(`JavaScript application edge ${index} id`, edge.id),
+    kind: requireString(`JavaScript application edge ${index} kind`, edge.kind),
+    from: requireString(`JavaScript application edge ${index} from`, edge.from),
+    to: requireString(`JavaScript application edge ${index} to`, edge.to),
+    specifier: requireString(`JavaScript application edge ${index} specifier`, edge.specifier),
+    resolutionKind: requireString(`JavaScript application edge ${index} resolutionKind`, edge.resolutionKind),
+    runtime: edge.runtime === true,
+    packageContract: edge.packageContract == null ? null : String(edge.packageContract),
+    source: normalizeSource(edge.source)
+  });
+}
+
+
+function normalizeBlocker(blocker, index) {
+  if (!blocker || typeof blocker !== 'object') throw new TypeError(`JavaScript application blocker ${index} must be an object.`);
+  return Object.freeze({
+    code: requireString(`JavaScript application blocker ${index} code`, blocker.code),
+    kind: requireString(`JavaScript application blocker ${index} kind`, blocker.kind),
+    message: requireString(`JavaScript application blocker ${index} message`, blocker.message),
+    moduleId: blocker.moduleId == null ? null : String(blocker.moduleId),
+    packageName: blocker.packageName == null ? null : String(blocker.packageName),
+    packageSubpath: blocker.packageSubpath == null ? null : String(blocker.packageSubpath),
+    contractId: blocker.contractId == null ? null : String(blocker.contractId),
+    source: normalizeSource(blocker.source)
+  });
+}
+
+function normalizePackage(entry, index) {
+  if (!entry || typeof entry !== 'object') throw new TypeError(`JavaScript application package ${index} must be an object.`);
+  const status = requireString(`JavaScript application package ${index} status`, entry.status);
+  if (!['supplied-core', 'node-require', 'package-runtime', 'unavailable'].includes(status)) {
+    throw new TypeError(`Unsupported JavaScript application package status ${status}.`);
+  }
+  return Object.freeze({
+    moduleId: requireString(`JavaScript application package ${index} moduleId`, entry.moduleId),
+    packageName: requireString(`JavaScript application package ${index} packageName`, entry.packageName),
+    packageSubpath: entry.packageSubpath == null ? '.' : String(entry.packageSubpath),
+    contractId: entry.contractId == null ? null : String(entry.contractId),
+    status,
+    runtimeEntry: entry.runtimeEntry == null ? null : String(entry.runtimeEntry),
+    reasonCode: entry.reasonCode == null ? null : String(entry.reasonCode),
+    sources: Object.freeze((entry.sources || []).map(normalizeSource).filter(Boolean))
+  });
+}
+
+function normalizeJavascriptApplicationPlan(input) {
+  if (!input || typeof input !== 'object') throw new TypeError('JavaScript application plan input must be an object.');
+  const modules = Object.freeze((input.modules || []).map(normalizeModule).sort((a, b) => a.id.localeCompare(b.id)));
+  const edges = Object.freeze((input.edges || []).map(normalizeEdge).sort((a, b) => a.id.localeCompare(b.id)));
+  const packages = Object.freeze((input.packages || []).map(normalizePackage).sort((a, b) => a.moduleId.localeCompare(b.moduleId)));
+  const blockers = Object.freeze((input.blockers || []).map(normalizeBlocker).sort((a, b) => (a.source?.file || '').localeCompare(b.source?.file || '') || (a.source?.line || 0) - (b.source?.line || 0) || a.code.localeCompare(b.code)));
+  const moduleIds = new Set(modules.map((entry) => entry.id));
+  if (moduleIds.size !== modules.length) throw new TypeError('JavaScript application plan module IDs must be unique.');
+  for (const edge of edges) {
+    if (!moduleIds.has(edge.from) || !moduleIds.has(edge.to)) throw new TypeError(`JavaScript application edge ${edge.id} references an unknown module.`);
+  }
+  const entryModuleId = requireString('JavaScript application entry module id', input.entryModuleId);
+  if (!moduleIds.has(entryModuleId)) throw new TypeError('JavaScript application entry module must be present in modules.');
+  const document = {
+    version: JAVASCRIPT_APPLICATION_PLAN_VERSION,
+    kind: 'pulse.javascript-application-plan',
+    provider: requireString('JavaScript application provider', input.provider),
+    target: 'javascript',
+    targetId: requireString('JavaScript application target id', input.targetId),
+    runtimeClass: JAVASCRIPT_RUNTIME_CLASS,
+    sourceApplication: true,
+    automaticFallback: false,
+    workspace: Object.freeze({
+      root: '.',
+      entry: requireString('JavaScript application entry path', input.entryPath)
+    }),
+    graph: Object.freeze({
+      version: requireString('JavaScript application graph version', input.graphVersion),
+      graphHash: requireString('JavaScript application graph hash', input.graphHash),
+      resolverHash: requireString('JavaScript application resolver hash', input.resolverHash),
+      entryModuleId,
+      modules,
+      edges
+    }),
+    packages,
+    loadable: blockers.length === 0,
+    blockers,
+    packageProduct: input.packageProduct || null,
+    nativeEligibility: input.nativeEligibility || null,
+    entrySafety: input.entrySafety || null,
+    capabilityEnvelope: input.capabilityEnvelope || null,
+    policy: Object.freeze({
+      graphBackedResolution: true,
+      oneModuleCache: true,
+      sourceHashVerifiedAtLoad: true,
+      applicationDefaultMustBeManaged: true,
+      packageSupportCheckedBeforeLoad: true,
+      providerLifecycleDeferred: input.providerLifecycleDeferred !== false,
+      automaticFallback: false
+    })
+  };
+  const planHash = sha256Hex(stableStringify(document));
+  return deepFreeze({ ...document, planHash });
+}
+
+function isJavascriptApplicationPlan(value) {
+  return Boolean(value && value.version === JAVASCRIPT_APPLICATION_PLAN_VERSION && value.kind === 'pulse.javascript-application-plan');
+}
+
+function normalizeJavascriptTargetDescriptor(input) {
+  if (!input || typeof input !== 'object') throw new TypeError('JavaScript target descriptor input must be an object.');
+  const commands = input.commands || {};
+  return deepFreeze({
+    version: JAVASCRIPT_TARGET_DESCRIPTOR_VERSION,
+    provider: requireString('JavaScript target provider', input.provider),
+    target: 'javascript',
+    targetId: requireString('JavaScript target id', input.targetId),
+    runtimeClass: JAVASCRIPT_RUNTIME_CLASS,
+    sourceApplication: true,
+    automaticFallback: false,
+    status: requireString('JavaScript target status', input.status),
+    hostBridge: input.hostBridge === true,
+    applicationLoader: input.applicationLoader === true,
+    requestAdapter: input.requestAdapter === true,
+    lifecycle: input.lifecycle === true,
+    capabilities: deepFreeze(input.capabilities || {
+      version: 'pulse.javascript-capability-envelope.v1',
+      provider: input.provider,
+      status: input.requestAdapter === true ? 'request-lifecycle-ready' : 'provider-adapters-deferred',
+      core: Object.freeze({
+        request: input.requestAdapter === true,
+        response: input.requestAdapter === true,
+        state: true
+      }),
+      effects: Object.freeze({ fetch: false, config: false, secret: false, kv: false }),
+      packages: Object.freeze([])
+    }),
+    reporting: deepFreeze(input.reporting || {
+      supported: true,
+      default: 'info',
+      levels: ['off', 'error', 'warn', 'info', 'debug']
+    }),
+    ...(input.crypto ? { crypto: deepFreeze(input.crypto) } : {}),
+    commands: Object.freeze({
+      compile: commands.compile === true,
+      inspect: commands.inspect === true,
+      doctor: commands.doctor === true,
+      build: commands.build === true,
+      test: commands.test === true,
+      dev: commands.dev === true
+    })
+  });
+}
+
+module.exports = Object.freeze({
+  JAVASCRIPT_APPLICATION_PLAN_VERSION,
+  JAVASCRIPT_APPLICATION_LOADER_VERSION,
+  JAVASCRIPT_TARGET_DESCRIPTOR_VERSION,
+  JAVASCRIPT_RUNTIME_CLASS,
+  isJavascriptApplicationPlan,
+  normalizeJavascriptApplicationPlan,
+  normalizeJavascriptTargetDescriptor
+});

package/src/project/javascript-core-capabilities.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const JAVASCRIPT_CORE_CAPABILITIES = Object.freeze([
+  'error',
+  'lifecycle',
+  'params',
+  'req.header',
+  'req.headers',
+  'req.method',
+  'req.path',
+  'req.text',
+  'req.url',
+  'request.header',
+  'request.header.at',
+  'request.header.count',
+  'request.header.first',
+  'request.headers',
+  'request.method',
+  'request.path',
+  'request.text',
+  'request.url',
+  'response.custom',
+  'response.header.append',
+  'response.header.delete',
+  'response.header.set',
+  'response.json',
+  'response.response',
+  'response.text',
+  'route.param',
+  'state',
+  'state.get',
+  'state.set'
+]);
+
+const javascriptCoreCapabilitySet = new Set(JAVASCRIPT_CORE_CAPABILITIES);
+
+function isJavascriptCoreCapability(value) {
+  return javascriptCoreCapabilitySet.has(String(value));
+}
+
+module.exports = Object.freeze({
+  JAVASCRIPT_CORE_CAPABILITIES,
+  isJavascriptCoreCapability
+});

package/src/project/native-optimization.js

@@ -0,0 +1,9 @@
+'use strict';
+
+const NATIVE_OPTIMIZATION_VERSION = 'pulse.native-optimization.v1';
+const EXPERIMENTAL_NATIVE_SIZE_MODE = 'experimental-native-size';
+
+module.exports = Object.freeze({
+  NATIVE_OPTIMIZATION_VERSION,
+  EXPERIMENTAL_NATIVE_SIZE_MODE
+});

package/src/project/package-ownership.js

@@ -0,0 +1,242 @@
+'use strict';
+
+const PACKAGE_OWNERSHIP_CONTRACT_VERSION = 'pulse.package-ownership.v1';
+const APPLICATION_IR_ENVELOPE_VERSION = 'pulse.application-ir-envelope.v1';
+
+function freezeList(values) {
+  return Object.freeze(Array.from(values || []));
+}
+
+function packageOwner(definition) {
+  return Object.freeze({
+    ...definition,
+    owns: freezeList(definition.owns),
+    mustNotOwn: freezeList(definition.mustNotOwn),
+    directRecognizedImports: freezeList(definition.directRecognizedImports)
+  });
+}
+
+const PACKAGE_OWNERSHIP_DEFINITIONS = Object.freeze([
+  packageOwner({
+    package: '@pulse-compute/runtime',
+    layer: 'low-level-application-contract',
+    currentStatus: 'public',
+    sprint1Status: 'public-vnext-candidate',
+    owns: [
+      'Router topology and terminal control flow',
+      'request, response, context, capability, and handler types',
+      'low-level plain-handler and Router authoring',
+      'target-neutral application semantics'
+    ],
+    mustNotOwn: [
+      'workspace discovery',
+      'profile selection',
+      'configuration factory normalization',
+      'provider lifecycle',
+      'compiler internals'
+    ],
+    directRecognizedImports: ['Router'],
+    publicationGate: 'already-public'
+  }),
+  packageOwner({
+    package: '@pulse-compute/pulse',
+    layer: 'ergonomic-project-wrapper',
+    currentStatus: 'private-reserved',
+    sprint1Status: 'implementation-candidate-not-yet-released',
+    owns: [
+      'Pulse application root',
+      'defineConfig deferred factory marker',
+      'symbolic config scope types',
+      'project/profile composition ergonomics',
+      'opaque profile composition token'
+    ],
+    mustNotOwn: [
+      'a second Router dispatcher',
+      'host lifecycle',
+      'runtime filesystem discovery',
+      'resolved config or secret values',
+      'compiler rule registration'
+    ],
+    directRecognizedImports: ['Pulse', 'defineConfig'],
+    publicationGate: 'separate-human-authorized-release-change'
+  }),
+  packageOwner({
+    package: '@pulse-compute/cli',
+    layer: 'project-tooling',
+    currentStatus: 'public',
+    sprint1Status: 'public-convergence-candidate',
+    owns: [
+      'workspace and config discovery',
+      'profile selection precedence',
+      'project command orchestration',
+      'provider lifecycle delegation',
+      'inspection and local artifact evidence'
+    ],
+    mustNotOwn: [
+      'Router semantics',
+      'handler semantic classification',
+      'package capability semantics',
+      'resolved secret values in artifacts'
+    ],
+    directRecognizedImports: [],
+    publicationGate: 'existing-public-package'
+  }),
+  packageOwner({
+    package: '@pulse-compute/wasm-contracts',
+    layer: 'internal-shared-contract-authority',
+    currentStatus: 'public-implementation-package',
+    sprint1Status: 'shared-authority',
+    owns: [
+      'compiler spine phase vocabulary',
+      'handler surface classifications',
+      'project/profile plan schema',
+      'package ownership declarations',
+      'provider-neutral operation contracts'
+    ],
+    mustNotOwn: [
+      'TypeScript AST traversal',
+      'provider execution',
+      'package-specific lowering behavior',
+      'public third-party compiler plugins'
+    ],
+    directRecognizedImports: [],
+    publicationGate: 'existing-public-package'
+  })
+]);
+
+const IMPLEMENTATION_ROLE_OWNERSHIP = Object.freeze([
+  Object.freeze({
+    role: 'compiler-orchestration',
+    owner: 'pulse.compiler-orchestration',
+    owns: Object.freeze([
+      'TypeScript source extraction',
+      'surface recognition and normalization adapters',
+      'contract validation',
+      'canonical IR construction',
+      'provider-neutral native lowering orchestration'
+    ]),
+    mustNotOwn: Object.freeze([
+      'provider runtime behavior',
+      'arbitrary package source interpretation',
+      'public plugin discovery',
+      'alternate Router semantics for Pulse'
+    ])
+  })
+]);
+
+const PUBLIC_SYMBOL_OWNERSHIP = Object.freeze([
+  Object.freeze({ symbol: 'Router', package: '@pulse-compute/runtime', role: 'application-root', importPolicy: 'direct-named-import', aliases: false }),
+  Object.freeze({ symbol: 'Pulse', package: '@pulse-compute/pulse', role: 'application-root', importPolicy: 'direct-named-import', aliases: false }),
+  Object.freeze({ symbol: 'defineConfig', package: '@pulse-compute/pulse', role: 'config-factory-marker', importPolicy: 'direct-named-import', aliases: false })
+]);
+
+const APPLICATION_IR_ENVELOPE = Object.freeze({
+  version: APPLICATION_IR_ENVELOPE_VERSION,
+  kind: 'pulse.application-ir',
+  routerField: 'router',
+  projectField: 'project',
+  router: Object.freeze({
+    required: true,
+    authority: 'existing-canonical-router-ir',
+    semanticsMayDependOnProjectMetadata: false
+  }),
+  project: Object.freeze({
+    requiredFor: Object.freeze(['pulse-root']),
+    forbiddenFor: Object.freeze([]),
+    contents: Object.freeze([
+      'construction-mode',
+      'config-plan-hash',
+      'selected-profile',
+      'strict-policy',
+      'symbolic-bindings',
+      'package-fragments'
+    ]),
+    resolvedSecretValues: false
+  }),
+  policies: Object.freeze({
+    pulseCreatesSecondRouterIr: false,
+    pulseChangesRouterCursorSemantics: false,
+    pulseChangesErrorLaneSemantics: false,
+    pulseChangesResponseOwnership: false,
+    configurationBranchesInsideRouterIr: false
+  })
+});
+
+function validatePackageOwnership(
+  definitions = PACKAGE_OWNERSHIP_DEFINITIONS,
+  symbols = PUBLIC_SYMBOL_OWNERSHIP,
+  implementationRoles = IMPLEMENTATION_ROLE_OWNERSHIP
+) {
+  const packages = new Map();
+  for (const definition of definitions) {
+    if (!definition || typeof definition.package !== 'string' || definition.package.length === 0) {
+      throw new TypeError('Package ownership definition requires a package name.');
+    }
+    if (packages.has(definition.package)) throw new TypeError(`Duplicate package ownership definition: ${definition.package}`);
+    packages.set(definition.package, definition);
+  }
+  const symbolOwners = new Map();
+  for (const entry of symbols) {
+    if (!packages.has(entry.package)) throw new TypeError(`Public symbol ${entry.symbol} references unknown package ${entry.package}.`);
+    if (symbolOwners.has(entry.symbol)) throw new TypeError(`Public symbol ${entry.symbol} has multiple package owners.`);
+    symbolOwners.set(entry.symbol, entry);
+  }
+  const roles = new Map();
+  for (const entry of implementationRoles) {
+    if (!entry || typeof entry.role !== 'string' || entry.role.length === 0) {
+      throw new TypeError('Implementation-role ownership definition requires a role.');
+    }
+    if (typeof entry.owner !== 'string' || entry.owner.length === 0) {
+      throw new TypeError(`Implementation role ${entry.role} requires an owner.`);
+    }
+    if (roles.has(entry.role)) throw new TypeError(`Duplicate implementation-role ownership definition: ${entry.role}`);
+    roles.set(entry.role, entry);
+  }
+  return Object.freeze({ packages, symbolOwners, roles });
+}
+
+const DEFAULT_PACKAGE_OWNERSHIP_REGISTRY = validatePackageOwnership();
+
+function packageOwnerFor(name) {
+  return DEFAULT_PACKAGE_OWNERSHIP_REGISTRY.packages.get(name);
+}
+
+function publicSymbolOwner(symbol) {
+  return DEFAULT_PACKAGE_OWNERSHIP_REGISTRY.symbolOwners.get(symbol);
+}
+
+function implementationRoleOwner(role) {
+  return DEFAULT_PACKAGE_OWNERSHIP_REGISTRY.roles.get(role);
+}
+
+function defaultPackageOwnershipContract() {
+  return Object.freeze({
+    version: PACKAGE_OWNERSHIP_CONTRACT_VERSION,
+    packages: PACKAGE_OWNERSHIP_DEFINITIONS,
+    symbols: PUBLIC_SYMBOL_OWNERSHIP,
+    implementationRoles: IMPLEMENTATION_ROLE_OWNERSHIP,
+    applicationIr: APPLICATION_IR_ENVELOPE,
+    policies: Object.freeze({
+      runtimeIsLowLevelEscapeHatch: true,
+      pulseSharesRouterIr: true,
+      cliOwnsProjectOrchestration: true,
+      packageLowerersReceiveCanonicalOperations: true,
+      publicCompilerPluginApi: false
+    })
+  });
+}
+
+module.exports = {
+  PACKAGE_OWNERSHIP_CONTRACT_VERSION,
+  APPLICATION_IR_ENVELOPE_VERSION,
+  PACKAGE_OWNERSHIP_DEFINITIONS,
+  PUBLIC_SYMBOL_OWNERSHIP,
+  IMPLEMENTATION_ROLE_OWNERSHIP,
+  APPLICATION_IR_ENVELOPE,
+  DEFAULT_PACKAGE_OWNERSHIP_REGISTRY,
+  validatePackageOwnership,
+  packageOwnerFor,
+  publicSymbolOwner,
+  implementationRoleOwner,
+  defaultPackageOwnershipContract
+};

package/src/project/package-product-projection.js

@@ -0,0 +1,171 @@
+
+'use strict';
+
+const { prefixedStableId, stableStringify, sha256Hex } = require('../stable-id.js');
+
+const PACKAGE_PRODUCT_PROJECTION_VERSION = 'pulse.package-product-projection.v1';
+const PACKAGE_PRODUCT_BINDING_VERSION = 'pulse.package-product-binding.v1';
+const PACKAGE_FRAGMENT_OWNERSHIP_VERSION = 'pulse.package-fragment-ownership.v1';
+const PACKAGE_BINDING_ROLES = Object.freeze(['authoring', 'helper', 're-export']);
+const PACKAGE_COMPOSITION_STATUSES = Object.freeze(['supported', 'reserved', 'not-realized', 'unsupported']);
+
+function isPlainObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function assertKnownKeys(input, allowed, field) {
+  for (const key of Object.keys(input)) if (!allowed.has(key)) throw new TypeError(`${field} contains unsupported field ${key}.`);
+}
+
+function string(value, field) {
+  if (typeof value !== 'string' || value.trim() === '') throw new TypeError(`${field} must be a non-empty string.`);
+  if (value.includes('\0')) throw new TypeError(`${field} must not contain NUL.`);
+  return value.trim();
+}
+
+function nullableString(value, field) {
+  return value == null ? null : string(value, field);
+}
+
+function bool(value, field) {
+  if (typeof value !== 'boolean') throw new TypeError(`${field} must be a boolean.`);
+  return value;
+}
+
+function strings(values, field) {
+  if (values == null) return Object.freeze([]);
+  if (!Array.isArray(values)) throw new TypeError(`${field} must be an array.`);
+  return Object.freeze([...new Set(values.map((value, index) => string(value, `${field}[${index}]`)))].sort());
+}
+
+function source(input, field) {
+  if (!isPlainObject(input)) throw new TypeError(`${field} must be an object.`);
+  assertKnownKeys(input, new Set(['file', 'line', 'column']), field);
+  return Object.freeze({
+    file: string(input.file, `${field}.file`).replace(/\\/g, '/'),
+    line: Number(input.line || 1),
+    column: Number(input.column || 1)
+  });
+}
+
+function normalizeTarget(input, field) {
+  if (!isPlainObject(input)) throw new TypeError(`${field} must be an object.`);
+  assertKnownKeys(input, new Set(['version', 'status', 'realization', 'entry', 'lowerableSubpath', 'providerRequirements', 'reasonCode']), field);
+  return Object.freeze({
+    status: string(input.status, `${field}.status`),
+    realization: string(input.realization || 'none', `${field}.realization`),
+    entry: nullableString(input.entry, `${field}.entry`),
+    lowerableSubpath: nullableString(input.lowerableSubpath, `${field}.lowerableSubpath`),
+    providerRequirements: strings(input.providerRequirements, `${field}.providerRequirements`),
+    reasonCode: nullableString(input.reasonCode, `${field}.reasonCode`)
+  });
+}
+
+function normalizeContract(input, index) {
+  if (!isPlainObject(input)) throw new TypeError(`contracts[${index}] must be an object.`);
+  assertKnownKeys(input, new Set([
+    'contractId', 'packageName', 'packageVersion', 'metadataHash', 'profileFragment',
+    'helperImports', 'reExportImports', 'authoringImport', 'authoringSymbols',
+    'compositionStatus', 'compositionHelper', 'compositionReasonCode',
+    'nativeTarget', 'javascriptTarget', 'conformanceStatus', 'conformanceFixtureRoots', 'conformanceSemanticCases'
+  ]), `contracts[${index}]`);
+  const compositionStatus = string(input.compositionStatus, `contracts[${index}].compositionStatus`);
+  if (!PACKAGE_COMPOSITION_STATUSES.includes(compositionStatus)) throw new TypeError(`Unsupported composition status ${compositionStatus}.`);
+  return Object.freeze({
+    contractId: string(input.contractId, `contracts[${index}].contractId`),
+    packageName: string(input.packageName, `contracts[${index}].packageName`),
+    packageVersion: string(input.packageVersion, `contracts[${index}].packageVersion`),
+    metadataHash: string(input.metadataHash, `contracts[${index}].metadataHash`),
+    profileFragment: string(input.profileFragment, `contracts[${index}].profileFragment`),
+    helperImports: strings(input.helperImports, `contracts[${index}].helperImports`),
+    reExportImports: strings(input.reExportImports, `contracts[${index}].reExportImports`),
+    authoringImport: string(input.authoringImport, `contracts[${index}].authoringImport`),
+    authoringSymbols: strings(input.authoringSymbols, `contracts[${index}].authoringSymbols`),
+    compositionStatus,
+    compositionHelper: nullableString(input.compositionHelper, `contracts[${index}].compositionHelper`),
+    compositionReasonCode: nullableString(input.compositionReasonCode, `contracts[${index}].compositionReasonCode`),
+    nativeTarget: normalizeTarget(input.nativeTarget, `contracts[${index}].nativeTarget`),
+    javascriptTarget: normalizeTarget(input.javascriptTarget, `contracts[${index}].javascriptTarget`),
+    conformanceStatus: string(input.conformanceStatus, `contracts[${index}].conformanceStatus`),
+    conformanceFixtureRoots: strings(input.conformanceFixtureRoots, `contracts[${index}].conformanceFixtureRoots`),
+    conformanceSemanticCases: strings(input.conformanceSemanticCases, `contracts[${index}].conformanceSemanticCases`)
+  });
+}
+
+function normalizeBinding(input, index) {
+  if (!isPlainObject(input)) throw new TypeError(`bindings[${index}] must be an object.`);
+  assertKnownKeys(input, new Set([
+    'moduleId', 'localName', 'exportName', 'importedName', 'packageModuleId', 'packageName',
+    'contractId', 'role', 'source', 'via', 'direct', 'used'
+  ]), `bindings[${index}]`);
+  const role = string(input.role, `bindings[${index}].role`);
+  if (!PACKAGE_BINDING_ROLES.includes(role)) throw new TypeError(`Unsupported package product binding role ${role}.`);
+  const semantic = Object.freeze({
+    version: PACKAGE_PRODUCT_BINDING_VERSION,
+    moduleId: string(input.moduleId, `bindings[${index}].moduleId`),
+    localName: nullableString(input.localName, `bindings[${index}].localName`),
+    exportName: nullableString(input.exportName, `bindings[${index}].exportName`),
+    importedName: string(input.importedName, `bindings[${index}].importedName`),
+    packageModuleId: string(input.packageModuleId, `bindings[${index}].packageModuleId`),
+    packageName: string(input.packageName, `bindings[${index}].packageName`),
+    contractId: string(input.contractId, `bindings[${index}].contractId`),
+    role,
+    source: source(input.source, `bindings[${index}].source`),
+    via: string(input.via, `bindings[${index}].via`),
+    direct: bool(input.direct, `bindings[${index}].direct`),
+    used: bool(input.used, `bindings[${index}].used`)
+  });
+  return Object.freeze({ ...semantic, id: prefixedStableId('pkgproduct', semantic, { length: 32 }) });
+}
+
+function normalizeFragment(input, index) {
+  if (!isPlainObject(input)) throw new TypeError(`fragments[${index}] must be an object.`);
+  assertKnownKeys(input, new Set(['key', 'contractId', 'packageName', 'present', 'selected']), `fragments[${index}]`);
+  return Object.freeze({
+    version: PACKAGE_FRAGMENT_OWNERSHIP_VERSION,
+    key: string(input.key, `fragments[${index}].key`),
+    contractId: nullableString(input.contractId, `fragments[${index}].contractId`),
+    packageName: nullableString(input.packageName, `fragments[${index}].packageName`),
+    present: bool(input.present, `fragments[${index}].present`),
+    selected: bool(input.selected, `fragments[${index}].selected`)
+  });
+}
+
+function normalizePackageProductProjection(input) {
+  if (!isPlainObject(input)) throw new TypeError('Package product projection must be an object.');
+  assertKnownKeys(input, new Set(['graphHash', 'contracts', 'bindings', 'fragments', 'selectedContracts', 'composedContracts']), 'Package product projection');
+  const contracts = Object.freeze([...(input.contracts || [])].map(normalizeContract)
+    .sort((a, b) => a.contractId.localeCompare(b.contractId)));
+  const bindings = Object.freeze([...(input.bindings || [])].map(normalizeBinding)
+    .sort((a, b) => a.moduleId.localeCompare(b.moduleId) || (a.localName || a.exportName || '').localeCompare(b.localName || b.exportName || '') || a.id.localeCompare(b.id)));
+  const fragments = Object.freeze([...(input.fragments || [])].map(normalizeFragment)
+    .sort((a, b) => a.key.localeCompare(b.key)));
+  const semantic = Object.freeze({
+    version: PACKAGE_PRODUCT_PROJECTION_VERSION,
+    graphHash: string(input.graphHash, 'graphHash'),
+    contracts,
+    bindings,
+    fragments,
+    selectedContracts: strings(input.selectedContracts, 'selectedContracts'),
+    composedContracts: strings(input.composedContracts, 'composedContracts'),
+    policy: Object.freeze({
+      graphOwnsAttribution: true,
+      productMetadataExecutesCode: false,
+      helperOwnershipUnique: true,
+      profileFragmentOwnershipUnique: true,
+      nativeLoweringTrustSeparate: true,
+      automaticFallback: false
+    })
+  });
+  return Object.freeze({ ...semantic, projectionHash: sha256Hex(stableStringify(semantic)) });
+}
+
+module.exports = Object.freeze({
+  PACKAGE_PRODUCT_PROJECTION_VERSION,
+  PACKAGE_PRODUCT_BINDING_VERSION,
+  PACKAGE_FRAGMENT_OWNERSHIP_VERSION,
+  PACKAGE_BINDING_ROLES,
+  normalizePackageProductProjection
+});