semantifold 0.3.0 → 0.5.0

package/src/stdlib-providers.js

@@ -0,0 +1,377 @@
+// @ts-check
+
+import {isDenseArray} from "./array.js"
+import {isSafeArtifactPath} from "./artifact-path.js"
+import {SemantifoldDiagnostic} from "./diagnostic.js"
+import {languageRegistry} from "./language-registry.js"
+import {
+  listStdlibModules,
+  parseStdlibVersion,
+  parseStdlibVersionRange,
+  protectedEntryName,
+  resolveStdlibModule
+} from "./semantic/stdlib.js"
+
+export {protectedEntryName} from "./semantic/stdlib.js"
+
+/**
+ * @typedef StdlibProviderRecord
+ * @property {{mediaType: string, path: string}} artifact - Generated provider artifact declaration.
+ * @property {readonly {module: string, range: string}[]} dependencies - Canonical module dependencies with declared ranges.
+ * @property {string} identity - Stable provider identity rooted at the target.
+ * @property {Readonly<Record<string, string>>} nativeEntries - Operation to protected native entry name.
+ * @property {readonly {module: string, operations: string[], version: string}[]} provides - Exactly one provided canonical module.
+ * @property {string} runtimeProfile - Closed target runtime/provider profile.
+ * @property {string} target - Adopted target language identity.
+ */
+
+/**
+ * @typedef StdlibProviderRegistry
+ * @property {readonly StdlibProviderRecord[]} records - Registered provider records in stable order.
+ * @property {{(target: string, module: string, version: string): readonly StdlibProviderRecord[]}} providersFor - Exact provider lookup.
+ */
+
+const providerIdentityPrefix = "semantifold.provider."
+/** @type {Readonly<Record<string, string>>} */
+const targetExtensions = Object.freeze({
+  javascript: "js",
+  java: "java",
+  php: "php",
+  ruby: "rb",
+  typescript: "ts"
+})
+const builtinProviderTargets = Object.freeze(["php", "ruby", "javascript", "typescript", "java"])
+const probeIdentity = "semantifold.task034.resource-probe"
+const probeOperations = Object.freeze(["probeEffect", "probeAcquire", "probeRead", "probeClose", "probeTrace"])
+const recordKeys = Object.freeze(["artifact", "dependencies", "identity", "nativeEntries", "provides", "runtimeProfile", "target"])
+const task037ProviderModules = Object.freeze([
+  Object.freeze({dependencies: [], identity: "semantifold.resource", operations: ["v1_close"]}),
+  Object.freeze({dependencies: [{module: "semantifold.resource", range: "1"}], identity: "semantifold.socket-client", operations: ["v1_connect"]}),
+  Object.freeze({dependencies: [{module: "semantifold.resource", range: "1"}], identity: "semantifold.text-stream", operations: ["v1_read_line"]}),
+  Object.freeze({dependencies: [], identity: "semantifold.output", operations: ["v1_write_line"]})
+])
+/** @type {Readonly<Record<string, string>>} */
+const legacyRuntimeProfiles = Object.freeze({
+  javascript: "node24-core-v1",
+  java: "java17-core-v1",
+  php: "php82-core-v1",
+  ruby: "ruby3-core-v1",
+  typescript: "node24-typescript7-core-v1"
+})
+
+/**
+ * Creates the versioned target host stdlib provider registry.
+ * @param {unknown} records - Ordered provider records; built-in providers by default.
+ * @returns {Readonly<StdlibProviderRegistry>} Frozen registry.
+ */
+export function createStdlibProviderRegistry(records = builtinProviderRecords()) {
+  if (!isDenseArray(records)) invalidProvider("Provider records must be an ordered dense array.")
+
+  /** @type {StdlibProviderRecord[]} */
+  const validated = []
+  /** @type {Set<string>} */
+  const identities = new Set()
+
+  for (const candidate of records) {
+    const record = validateProviderRecord(candidate)
+
+    if (identities.has(record.identity)) invalidProvider(`Duplicate stdlib provider identity '${record.identity}'.`)
+    identities.add(record.identity)
+    validated.push(record)
+  }
+  const frozenRecords = deepFreeze(validated)
+
+  return Object.freeze(/** @type {Readonly<StdlibProviderRegistry>} */ ({
+    records: frozenRecords,
+    providersFor(target, module, version) {
+      if (typeof target != "string" || typeof module != "string" || typeof version != "string") return Object.freeze([])
+      return Object.freeze(frozenRecords.filter((record) =>
+        record.target == target && record.provides[0].module == module && record.provides[0].version == version))
+    }
+  }))
+}
+
+/**
+ * Lists the built-in target host providers for the probe contract in stable target order.
+ * @returns {readonly StdlibProviderRecord[]} Frozen provider records.
+ */
+export function listStdlibProviders() {
+  return builtinProviderRegistry().records
+}
+
+/**
+ * Authoritative built-in provider lookup keyed by exact target, module, and version.
+ * @type {{providersFor(target: string, module: string, version: string): readonly StdlibProviderRecord[]}}
+ */
+export const stdlibProviderRegistry = {
+  providersFor(target, module, version) {
+    return builtinProviderRegistry().providersFor(target, module, version)
+  }
+}
+
+/**
+ * Validates one provider record against the target roles and canonical contract registry.
+ * @param {unknown} candidate - Candidate record.
+ * @returns {StdlibProviderRecord} Detached frozen record.
+ */
+function validateProviderRecord(candidate) {
+  if (!isPlainObject(candidate)) invalidProvider("Every stdlib provider record must be a plain object.")
+  if (Object.keys(candidate).sort().join(",") != recordKeys.join(",")) {
+    invalidProvider("Every stdlib provider record declares the exact provider record fields.")
+  }
+  const target = /** @type {string} */ (candidate.target)
+
+  if (typeof target != "string" || !providerTargetRegistered(target)) {
+    invalidProvider(`Stdlib provider target '${String(target)}' is not an adopted target host provider.`)
+  }
+  const identity = /** @type {string} */ (candidate.identity)
+  const identityPrefix = providerIdentityPrefix + target + "."
+
+  if (typeof identity != "string" || !identity.startsWith(identityPrefix) || identity.length == identityPrefix.length) {
+    invalidProvider(`Stdlib provider identity '${String(identity)}' must be rooted at '${identityPrefix}'.`)
+  }
+  const provides = /** @type {unknown} */ (candidate.provides)
+
+  if (!isDenseArray(provides) || provides.length != 1) invalidProvider("Every stdlib provider provides exactly one canonical module.")
+  const provision = /** @type {unknown} */ (provides[0])
+
+  if (!isPlainObject(provision) || Object.keys(provision).sort().join(",") != "module,operations,version") {
+    invalidProvider("Every stdlib provider provision declares the exact provision fields.")
+  }
+  const module = /** @type {string} */ (provision.module)
+
+  if (typeof module != "string" || !/^[a-z][a-z0-9.-]*$/u.test(module)) {
+    invalidProvider(`Stdlib provider module '${String(module)}' is not a canonical identity.`)
+  }
+  const version = /** @type {string} */ (provision.version)
+
+  if (parseStdlibVersion(version) === null) {
+    throw new SemantifoldDiagnostic({
+      code: "STDLIB_VERSION_MALFORMED",
+      language: target,
+      message: `Stdlib provider version '${String(version)}' is not a strict semantic version.`
+    })
+  }
+  const operations = /** @type {unknown} */ (provision.operations)
+
+  if (!isDenseArray(operations) || operations.length == 0 || !operations.every((operation) =>
+    typeof operation == "string" && /^[A-Za-z_][A-Za-z0-9_]*$/u.test(operation)) ||
+    new Set(/** @type {string[]} */ (operations)).size != operations.length) {
+    invalidProvider(`Stdlib provider '${identity}' declares invalid operations.`)
+  }
+  const operationList = /** @type {string[]} */ (operations)
+
+  if (moduleKnown(module)) validateProvision(module, version, operationList)
+  const nativeEntries = /** @type {unknown} */ (candidate.nativeEntries)
+
+  if (!isPlainObject(nativeEntries) || Object.keys(nativeEntries).sort().join(",") !=
+    [...operationList].sort().join(",")) {
+    invalidProvider(`Stdlib provider '${identity}' native entries must match its operations exactly.`)
+  }
+  for (const operation of operationList) {
+    const expectedEntry = module == probeIdentity
+      ? protectedEntryName(target, operation)
+      : protectedEntryName(target, module, operation)
+
+    if (/** @type {string} */ (nativeEntries[operation]) != expectedEntry) {
+      invalidProvider(`Stdlib provider '${identity}' declares an invalid protected native entry.`)
+    }
+  }
+  const artifact = /** @type {unknown} */ (candidate.artifact)
+
+  if (!isPlainObject(artifact) || Object.keys(artifact).sort().join(",") != "mediaType,path") {
+    invalidProvider(`Stdlib provider '${identity}' declares an invalid artifact.`)
+  }
+  const mediaType = /** @type {string} */ (artifact.mediaType)
+  const path = /** @type {string} */ (artifact.path)
+  const derivedPath = `providers/${target}/${module.replaceAll(".", "/")}.${targetExtensions[target]}`
+
+  if (typeof mediaType != "string" || mediaType.length == 0 || typeof path != "string" ||
+    path != derivedPath || !isSafeArtifactPath(path)) {
+    invalidProvider(`Stdlib provider '${identity}' artifact must be generated at '${derivedPath}'.`)
+  }
+  const dependencies = /** @type {unknown} */ (candidate.dependencies)
+
+  if (!isDenseArray(dependencies)) invalidProvider(`Stdlib provider '${identity}' dependencies must be a dense array.`)
+  /** @type {{module: string, range: string}[]} */
+  const validatedDependencies = []
+
+  for (const dependency of dependencies) {
+    if (!isPlainObject(dependency) || Object.keys(dependency).sort().join(",") != "module,range") {
+      invalidProvider(`Stdlib provider '${identity}' declares an invalid dependency.`)
+    }
+    const dependencyModule = /** @type {string} */ (dependency.module)
+    const dependencyRange = /** @type {string} */ (dependency.range)
+
+    if (typeof dependencyModule != "string" || !/^[a-z][a-z0-9.-]*$/u.test(dependencyModule) ||
+      parseStdlibVersionRange(dependencyRange) === null) {
+      throw new SemantifoldDiagnostic({
+        code: "STDLIB_VERSION_MALFORMED",
+        language: target,
+        message: `Stdlib provider dependency range '${String(dependencyRange)}' is not a canonical version range.`
+      })
+    }
+    validatedDependencies.push({module: dependencyModule, range: /** @type {string} */ (dependencyRange)})
+  }
+  const runtimeProfile = /** @type {string} */ (candidate.runtimeProfile)
+
+  if (typeof runtimeProfile != "string" || !/^[a-z][a-z0-9-]*-v[1-9][0-9]*$/u.test(runtimeProfile)) {
+    invalidProvider(`Stdlib provider '${identity}' declares an invalid runtime profile.`)
+  }
+  if (module != probeIdentity && (target != "php" || runtimeProfile != "php82-core-streams-v1")) {
+    invalidProvider(`Stdlib provider '${identity}' does not use the Task 037 PHP 8.2 core-streams profile.`)
+  }
+  return deepFreeze(/** @type {StdlibProviderRecord} */ ({
+    artifact: {mediaType, path},
+    dependencies: validatedDependencies,
+    identity,
+    nativeEntries: Object.freeze(Object.fromEntries(operationList.map((operation) => [
+      operation,
+      /** @type {string} */ (nativeEntries[operation])
+    ]))),
+    provides: [{module, operations: operationList, version: /** @type {string} */ (version)}],
+    runtimeProfile,
+    target
+  }))
+}
+
+/**
+ * Checks the provisioned module version and operations against the canonical contract registry.
+ * @param {string} module - Canonical module identity.
+ * @param {string} version - Strict provider version.
+ * @param {string[]} operations - Provided operations.
+ * @returns {void}
+ */
+function validateProvision(module, version, operations) {
+  const listed = listStdlibModules().find(({identity}) => identity == module)
+
+  if (!listed || !listed.versions.includes(version)) {
+    invalidProvider(`Stdlib provider version '${version}' is not registered for module '${module}'.`)
+  }
+  const declared = new Set(resolveStdlibModule(module, version).operations.map(({name}) => name))
+
+  for (const operation of operations) {
+    if (!declared.has(operation)) {
+      throw new SemantifoldDiagnostic({
+        code: "STDLIB_OPERATION_UNDECLARED",
+        language: module,
+        message: `Operation '${operation}' is not declared by canonical module '${module}'.`
+      })
+    }
+  }
+}
+
+/**
+ * Reports whether a target is registered with the provider role.
+ * @param {unknown} target - Candidate target identity.
+ * @returns {boolean} Whether the target adopts the provider role.
+ */
+function providerTargetRegistered(target) {
+  if (typeof target != "string") return false
+  try {
+    return languageRegistry.record(target).provider === true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Reports whether a module identity is known to the built-in canonical contract registry.
+ * @param {string} module - Canonical module identity.
+ * @returns {boolean} Whether the identity resolves.
+ */
+function moduleKnown(module) {
+  try {
+    resolveStdlibModule(module)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Builds the built-in provider records for the adopted targets.
+ * @returns {unknown[]} Unvalidated built-in records.
+ */
+function builtinProviderRecords() {
+  const probeProviders = builtinProviderTargets.map((target) => ({
+    artifact: {
+      mediaType: /** @type {string} */ (languageRegistry.record(target).mediaType),
+      path: `providers/${target}/${probeIdentity.replaceAll(".", "/")}.${targetExtensions[target]}`
+    },
+    dependencies: [],
+    identity: `semantifold.provider.${target}.${probeIdentity}`,
+    nativeEntries: Object.fromEntries(probeOperations.map((operation) => [operation, protectedEntryName(target, operation)])),
+    provides: [{module: probeIdentity, operations: [...probeOperations], version: "1.0.0"}],
+    runtimeProfile: legacyRuntimeProfiles[target],
+    target
+  }))
+  const task037Providers = task037ProviderModules.map((module) => ({
+    artifact: {
+      mediaType: /** @type {string} */ (languageRegistry.record("php").mediaType),
+      path: `providers/php/${module.identity.replaceAll(".", "/")}.php`
+    },
+    dependencies: module.dependencies,
+    identity: `semantifold.provider.php.${module.identity}`,
+    nativeEntries: Object.fromEntries(module.operations.map((operation) => [
+      operation,
+      protectedEntryName("php", module.identity, operation)
+    ])),
+    provides: [{module: module.identity, operations: module.operations, version: "1.0.0"}],
+    runtimeProfile: "php82-core-streams-v1",
+    target: "php"
+  }))
+
+  return [...probeProviders, ...task037Providers]
+}
+
+/** @type {Readonly<StdlibProviderRegistry> | null} */
+let builtinProviderRegistryValue = null
+
+/**
+ * Lazily materializes the built-in provider registry after language-registry initialization.
+ * @returns {Readonly<StdlibProviderRegistry>} Built-in registry.
+ */
+function builtinProviderRegistry() {
+  if (builtinProviderRegistryValue === null) {
+    builtinProviderRegistryValue = createStdlibProviderRegistry(builtinProviderRecords())
+  }
+  return builtinProviderRegistryValue
+}
+
+/**
+ * Throws a normalized provider-registry diagnostic.
+ * @param {string} message - Failure detail.
+ * @returns {never} Always throws.
+ */
+function invalidProvider(message) {
+  throw new SemantifoldDiagnostic({code: "STDLIB_PROVIDER_INVALID", language: "stdlib", message})
+}
+
+/**
+ * Checks for an ordinary string-keyed object.
+ * @param {unknown} value - Candidate value.
+ * @returns {value is Record<string, unknown>} Whether the value is a plain object.
+ */
+function isPlainObject(value) {
+  if (typeof value != "object" || value === null) return false
+  const prototype = Object.getPrototypeOf(value)
+
+  return prototype === Object.prototype || prototype === null
+}
+
+/**
+ * Deep-freezes a detached value.
+ * @template T
+ * @param {T} value - Detached value.
+ * @returns {Readonly<T>} Frozen value.
+ */
+function deepFreeze(value) {
+  if (typeof value != "object" || value === null || Object.isFrozen(value)) return /** @type {Readonly<T>} */ (value)
+  Object.freeze(value)
+
+  for (const property of Object.getOwnPropertyNames(value)) {
+    deepFreeze(/** @type {unknown} */ ((/** @type {Record<string, unknown>} */ (value))[property]))
+  }
+  return /** @type {Readonly<T>} */ (value)
+}

package/src/toolchains.js

@@ -11,17 +11,28 @@ import {isSupportedTimeoutMs, maximumTimeoutMs} from "./timeout.js"
 const defaultTimeoutMs = 10_000
 
 export const canonicalToolchains = deepFreeze({
+  dart: definition("dart", "SEMANTIFOLD_DART", ["--version"],
+    /^Dart SDK version: 3\.13\.3 \(stable\) \(Tue Sep 1 01:07:17 2026 -0700\) on "linux_x64"$/u),
   php: definition("php", "SEMANTIFOLD_PHP", ["--version"], /^PHP 8\./u),
+  php82: definition("php", "SEMANTIFOLD_PHP", ["--version"], /^PHP (?:8\.(?:[2-9]|[1-9][0-9]+)|(?:9|[1-9][0-9]+)\.[0-9]+)\./u),
   ruby: definition("ruby", "SEMANTIFOLD_RUBY", ["--version"], /^ruby 3\./u),
   node: definition("node", "SEMANTIFOLD_NODE", ["--version"], /^v24\./u),
   tsc: definition("tsc", "SEMANTIFOLD_TSC", ["--version"], /^Version 7\./u),
   javac: definition("javac", "SEMANTIFOLD_JAVAC", ["-version"], /^javac (?:1[7-9]|2[0-9])\./u),
   java: definition("java", "SEMANTIFOLD_JAVA", ["-version"], /^(?:openjdk|java) version "(?:1[7-9]|2[0-9])\./u),
+  java25: definition("java", "SEMANTIFOLD_JAVA", ["-version"],
+    /^openjdk version "25\.0\.4" 2026-07-21\nOpenJDK Runtime Environment \(build 25\.0\.4\+7-1-((?:24|26)\.04)-Ubuntu\)\nOpenJDK 64-Bit Server VM \(build 25\.0\.4\+7-1-\1-Ubuntu, mixed mode, sharing\)$/u),
+  kotlinc: definition("kotlinc", "SEMANTIFOLD_KOTLINC", ["-version"], /^info: kotlinc-jvm 2\.4\.20 \(JRE 25\.0\.4\+7-1-(?:24|26)\.04-Ubuntu\)$/u),
   python: definition("python3", "SEMANTIFOLD_PYTHON", ["--version"], /^Python 3\./u),
   dotnet: definition("dotnet", "SEMANTIFOLD_DOTNET", ["--version"], /^10\./u),
   go: definition("go", "SEMANTIFOLD_GO", ["version"], /^go version go1\.26\.\d+ linux\/amd64$/u),
   clangpp: definition("clang++", "SEMANTIFOLD_CLANGPP", ["--version"], /^Ubuntu clang version 21\.1\.8 [^\n]+\nTarget: x86_64-pc-linux-gnu\n/u),
-  clang: definition("clang", "SEMANTIFOLD_CLANG", ["--version"], /^Ubuntu clang version 21\.1\.8 [^\n]+\nTarget: x86_64-pc-linux-gnu\n/u)
+  clang: definition("clang", "SEMANTIFOLD_CLANG", ["--version"], /^Ubuntu clang version 21\.1\.8 [^\n]+\nTarget: x86_64-pc-linux-gnu\n/u),
+  rustc: definition("rustc", "SEMANTIFOLD_RUSTC", ["--version", "--verbose"], /^rustc 1\.98\.1 \(48a229cea 2026-09-01\)\nbinary: rustc\ncommit-hash: 48a229ceaefd4985c50990b14116b6d856af0985\ncommit-date: 2026-09-01\nhost: x86_64-unknown-linux-gnu\nrelease: 1\.98\.1\nLLVM version: 22\.1\.8$/u),
+  cargo: definition("cargo", "SEMANTIFOLD_CARGO", ["--version", "--verbose"], /^cargo 1\.98\.1 \(797e8a9bc 2026-08-05\)\nrelease: 1\.98\.1\ncommit-hash: 797e8a9bca276c1c9f9f738d2a20f484fa4eea9d\ncommit-date: 2026-08-05\nhost: x86_64-unknown-linux-gnu\n/u),
+  swiftc: definition("swiftc", "SEMANTIFOLD_SWIFTC", ["--driver-mode=swiftc", "--version"], /^Swift version 6\.3\.3 \(swift-6\.3\.3-RELEASE\)\nTarget: x86_64-unknown-linux-gnu$/u),
+  "wasm-validate": definition("wasm-validate", "SEMANTIFOLD_WASM_VALIDATE", ["--version"], /^1\.0\.36$/u),
+  chromium: definition("chromium", "SEMANTIFOLD_CHROMIUM", ["--version"], /^Google Chrome 152\.0\.7977\.82$/u)
 })
 
 /**
@@ -68,7 +79,7 @@ export async function discoverCanonicalToolchain(id, options = {}) {
  * @param {Readonly<Record<string, string | undefined>>} [input.environment] - Explicit discovery environment.
  * @param {string} input.id - Toolchain ID.
  * @param {string} [input.override] - Configured absolute executable path.
- * @param {RegExp} [input.supportedVersion] - Full captured-output version policy.
+ * @param {RegExp} [input.supportedVersion] - Full selected-stream version policy.
  * @param {number} [input.timeoutMs] - Version command timeout.
  * @param {string[]} input.versionArguments - Exact version argument array.
  * @returns {Promise<import("./semantic/types.js").DiscoveredToolchain>} Discovered tool.
@@ -132,7 +143,9 @@ export async function discoverToolchain(input) {
   }
 
   const {stderr, stdout} = result
-  const versionOutput = [stdout, stderr].filter((value) => value.length > 0).join("\n").trim()
+  const normalizedStdout = stdout.trim()
+  const normalizedStderr = stderr.trim()
+  const versionOutput = normalizedStdout.length > 0 ? normalizedStdout : normalizedStderr
   const version = versionOutput.split(/\r?\n/u)[0] ?? ""
 
   if (version.length == 0) {