semantifold 0.8.0 → 0.10.0

package/src/semantic/types.js

@@ -165,6 +165,13 @@
  * @property {readonly string[]} toolchains - Required canonical toolchain IDs.
  */
 
+/**
+ * @typedef LanguageCheckCapabilities
+ * @property {boolean} supported - Whether the target owns a developer check plan.
+ * @property {readonly AcceptanceStage[]} stages - Ordered non-executing developer-check stages.
+ * @property {readonly string[]} toolchains - Exact canonical tools required to construct the plan.
+ */
+
 /**
  * @typedef LanguageFeatureCapabilities
  * @property {boolean} generalFunctionsAndCalls - Task 005 arbitrary required signatures, resolved direct calls, and void functions.
@@ -189,6 +196,7 @@
  * @property {Readonly<LanguageFeatureCapabilities>} features - Semantic feature capabilities.
  * @property {Readonly<LanguageMappingCapabilities>} mapping - Mapping forms.
  * @property {Readonly<LanguageAcceptanceCapabilities>} acceptance - Stages and toolchains.
+ * @property {Readonly<LanguageCheckCapabilities>} check - Non-executing developer-check capability.
  */
 
 /**
@@ -395,6 +403,109 @@
  * @property {Readonly<Record<string, unknown>>} [metadata] - Detached target-specific JSON metadata.
  */
 
+/**
+ * @typedef PublicationBuildArtifactInput
+ * @property {string} path - Normalized path relative to the target build projection.
+ * @property {string} mediaType - Stable media type for the validator/compiler output.
+ * @property {string} role - Stable language-neutral role for the validator/compiler output.
+ */
+
+/**
+ * @typedef PublicationValidatorContext
+ * @property {string} targetId - Explicit target identity.
+ * @property {string} sourcePath - Exact generation-scoped generated-source directory.
+ * @property {string} buildPath - Exact generation-scoped compiler-output directory.
+ */
+
+/** @typedef {(context: Readonly<PublicationValidatorContext>) => Promise<PublicationBuildArtifactInput[] | void> | PublicationBuildArtifactInput[] | void} PublicationValidator */
+
+/** @typedef {"text" | "binary" | "application"} PublicationTargetRole */
+
+/**
+ * @typedef PublicationTargetInput
+ * @property {string} id - Explicit project target identity.
+ * @property {GeneratedArtifactSet} artifactSet - Complete already-validated generated artifacts.
+ * @property {PublicationTargetRole} role - Explicit language-neutral target role.
+ * @property {string} sourceProjection - Generation-relative generated-source projection.
+ * @property {string} buildProjection - Generation-relative compiler-output projection.
+ * @property {readonly PublicationValidator[]} [validators] - Ordered candidate validators.
+ */
+
+/**
+ * @typedef PublicationRequest
+ * @property {string} generationId - Explicit generation/cycle identity, fresh or an exact retained validator-free candidate.
+ * @property {readonly PublicationTargetInput[]} targets - Complete ordered project targets.
+ */
+
+/**
+ * @typedef PublicationOptions
+ * @property {AbortSignal} [signal] - Cancellation authority through the active-pointer commit boundary.
+ */
+
+/**
+ * @typedef GenerationContentHash
+ * @property {"sha256"} algorithm - Hash algorithm.
+ * @property {string} value - Lowercase hexadecimal digest.
+ */
+
+/**
+ * @typedef GenerationArtifactManifest
+ * @property {string} path - Artifact-set-relative path.
+ * @property {"text" | "binary"} contentKind - Original artifact content representation.
+ * @property {string} mediaType - Declared artifact media type.
+ * @property {GeneratedArtifactRole} role - Declared artifact role.
+ * @property {ArtifactProvenance} provenance - Complete persisted rich, byte, or synthetic provenance.
+ * @property {number} byteLength - Exact staged byte length.
+ * @property {GenerationContentHash} hash - Exact staged byte hash.
+ */
+
+/**
+ * @typedef GenerationBuildArtifactManifest
+ * @property {string} path - Build-projection-relative path.
+ * @property {string} mediaType - Declared validator/compiler output media type.
+ * @property {string} role - Declared language-neutral validator/compiler output role.
+ * @property {number} byteLength - Exact staged byte length.
+ * @property {GenerationContentHash} hash - Exact staged byte hash.
+ */
+
+/**
+ * @typedef GenerationTargetManifest
+ * @property {string} id - Explicit project target identity.
+ * @property {PublicationTargetRole} role - Explicit language-neutral target role.
+ * @property {string} target - Artifact-set backend target identity.
+ * @property {{source: string, build: string}} projections - Disjoint generation-relative projections.
+ * @property {readonly GenerationArtifactManifest[]} artifacts - Ordered generated artifacts.
+ * @property {readonly GenerationBuildArtifactManifest[]} buildArtifacts - Ordered validator/compiler outputs.
+ * @property {Readonly<Record<string, unknown>>} [metadata] - Persisted target-specific artifact-set metadata.
+ */
+
+/**
+ * @typedef GenerationManifest
+ * @property {"SemantifoldGenerationManifest"} schema - Schema discriminator.
+ * @property {1} version - Manifest schema version.
+ * @property {string} projectId - Explicit project identity.
+ * @property {string} generationId - Explicit generation/cycle identity.
+ * @property {readonly GenerationTargetManifest[]} targets - Complete ordered target records.
+ */
+
+/**
+ * @typedef PublishedTargetPaths
+ * @property {string} id - Explicit project target identity.
+ * @property {PublicationTargetRole} role - Explicit language-neutral target role.
+ * @property {string} sourcePath - Exact immutable generated-source directory.
+ * @property {string} buildPath - Exact immutable compiler-output directory.
+ */
+
+/**
+ * @typedef PublishedGeneration
+ * @property {string} generationId - Resolved generation identity.
+ * @property {string} generationPath - Exact immutable generation directory.
+ * @property {string} manifestPath - Exact generation manifest path.
+ * @property {GenerationManifest} manifest - Verified immutable generation manifest.
+ * @property {readonly PublishedTargetPaths[]} targets - Exact generation-scoped target paths.
+ * @property {boolean} cleanupPending - Whether post-commit journal cleanup remains for recovery.
+ */
+
 /**
  * @typedef DiscoveredToolchain
  * @property {string} id - Toolchain ID.
@@ -406,6 +517,79 @@
  * @property {readonly string[]} versionArguments - Exact version argument array.
  */
 
+/**
+ * @typedef TargetCheckPathArgument
+ * @property {number} index - Exact argv index containing the path.
+ * @property {"source" | "build"} ownership - Candidate subtree that owns the path.
+ * @property {string} [prefix] - Exact non-path argv prefix preceding an owned absolute path.
+ */
+
+/**
+ * @typedef TargetCheckEnvironmentPath
+ * @property {string} name - Exact environment variable containing an owned absolute path.
+ * @property {"source" | "build" | "tool"} ownership - Candidate subtree or discovered tool that owns the path.
+ * @property {DiscoveredToolchain} [tool] - Exact tool executable bound by a tool-owned environment value.
+ */
+
+/**
+ * @typedef TargetCheckOutputOwnership
+ * @property {"build"} ownership - Compiler outputs belong only to the candidate build subtree.
+ * @property {string} path - Exact generation-scoped build root.
+ * @property {string} mediaType - Media type assigned to every produced regular file.
+ * @property {string} role - Language-neutral compiler-output role.
+ */
+
+/**
+ * @typedef TargetCheckStageRequest
+ * @property {AcceptanceStage} stage - Declared non-executing acceptance stage.
+ * @property {DiscoveredToolchain} tool - Exact immutable discovered tool record.
+ * @property {string} executable - Exact executable copied from the tool record.
+ * @property {readonly string[]} argv - Exact shell-free argument vector.
+ * @property {readonly TargetCheckPathArgument[]} pathArguments - Complete ownership declaration for argv paths.
+ * @property {string} cwd - Exact candidate-scoped working directory.
+ * @property {Readonly<Record<string, string>>} environment - Exact deterministic environment.
+ * @property {readonly TargetCheckEnvironmentPath[]} environmentPaths - Owned absolute environment paths.
+ * @property {string | null} inputHash - SHA-256 of declared restore inputs, or null for unconditional stages.
+ * @property {readonly string[]} inputs - Complete staged artifact inputs read by the stage.
+ * @property {Readonly<TargetCheckOutputOwnership> | null} output - Build output ownership, or null for non-producing checks.
+ * @property {readonly string[]} transientPaths - Candidate source/build cache or intermediate directories removed after checking.
+ */
+
+/**
+ * @typedef TargetCheckPlan
+ * @property {"SemantifoldTargetCheckPlan"} schema - Plan schema discriminator.
+ * @property {1} version - Plan schema version.
+ * @property {"developer-check"} mode - Non-executing developer-check mode.
+ * @property {string} projectId - Exact project identity.
+ * @property {string} targetId - Exact project target identity.
+ * @property {string} target - Registered backend target identity.
+ * @property {string} sourcePath - Exact staged generated-source root.
+ * @property {string} buildPath - Exact staged compiler-output root.
+ * @property {readonly string[]} artifactPaths - Exact staged artifact paths.
+ * @property {readonly TargetCheckStageRequest[]} stages - Ordered target-owned requests.
+ */
+
+/**
+ * @typedef TargetCheckStageResult
+ * @property {AcceptanceStage} stage - Completed stage identity.
+ * @property {Readonly<{command: string, executable: string, id: string, source: "override" | "canonical", version: string}>} tool - Exact tool identity.
+ * @property {readonly string[]} argv - Exact executed argument vector.
+ * @property {number} exitCode - Successful process exit code.
+ * @property {null} signal - Successful process signal state.
+ * @property {string} stdout - Bounded captured standard output.
+ * @property {string} stderr - Bounded captured standard error.
+ * @property {number} durationMs - Non-negative stage duration.
+ */
+
+/**
+ * @typedef TargetCheckResult
+ * @property {string} projectId - Exact project identity.
+ * @property {string} targetId - Exact project target identity.
+ * @property {string} target - Registered backend target identity.
+ * @property {readonly TargetCheckStageResult[]} stages - Ordered successful stage evidence.
+ * @property {readonly PublicationBuildArtifactInput[]} outputs - Complete compiler-owned build files.
+ */
+
 /**
  * @typedef AcceptanceStageResult
  * @property {AcceptanceStage} stage - Completed stage.

package/src/subprocess.js

@@ -6,6 +6,7 @@ import {StringDecoder} from "node:string_decoder"
 const forcedTerminationGraceMs = 250
 const retainedPipeGraceMs = 250
 const deadlineFailures = new WeakSet()
+const cancellationFailures = new WeakSet()
 
 /**
  * Executes one exact file while owning its complete bounded lifecycle.
@@ -15,6 +16,7 @@ const deadlineFailures = new WeakSet()
  * @param {Readonly<Record<string, string>>} input.environment - Exact environment.
  * @param {string} input.executable - Exact executable path.
  * @param {number} input.maxBuffer - Maximum bytes captured per output stream.
+ * @param {AbortSignal} [input.signal] - Optional owned cancellation signal.
  * @param {number} input.timeoutMs - Deadline before termination begins.
  * @returns {Promise<{stderr: string, stdout: string}>} Output after the owned process group closes.
  */
@@ -38,7 +40,7 @@ export function createExecuteFileWithDeadline({registerSpawnListener}) {
  * @param {(child: import("node:child_process").ChildProcess, listener: () => void) => void} registerSpawnListener - Registers deadline initialization.
  * @returns {Promise<{stderr: string, stdout: string}>} Output after the owned process group closes.
  */
-function executeFileWithDeadlineUsing({arguments: processArguments, cwd, environment, executable, maxBuffer, timeoutMs}, registerSpawnListener) {
+function executeFileWithDeadlineUsing({arguments: processArguments, cwd, environment, executable, maxBuffer, signal, timeoutMs}, registerSpawnListener) {
   if (process.platform == "win32") {
     return Promise.reject(Object.assign(new Error("Owned process-tree termination is unavailable on this platform."), {
       code: "ENOTSUP",
@@ -46,6 +48,12 @@ function executeFileWithDeadlineUsing({arguments: processArguments, cwd, environ
       stdout: ""
     }))
   }
+  if (signal?.aborted) {
+    const cancellationError = Object.assign(new Error("Subprocess was cancelled before launch."), {stderr: "", stdout: ""})
+
+    cancellationFailures.add(cancellationError)
+    return Promise.reject(cancellationError)
+  }
 
   return new Promise((resolve, reject) => {
     /** @type {ReturnType<typeof setTimeout> | undefined} */
@@ -56,8 +64,10 @@ function executeFileWithDeadlineUsing({arguments: processArguments, cwd, environ
     let pipeTimer
     /** @type {Error | undefined} */
     let launchError
+    let cancellationRequested = false
     let deadlineExceeded = false
     let outputExceeded = false
+    let processGroupOwned = false
     let settled = false
     const stderr = outputCapture(maxBuffer, () => terminateForOutputLimit())
     const stdout = outputCapture(maxBuffer, () => terminateForOutputLimit())
@@ -68,9 +78,15 @@ function executeFileWithDeadlineUsing({arguments: processArguments, cwd, environ
       stdio: ["ignore", "pipe", "pipe"]
     })
     const processGroupId = child.pid
+    const cancel = () => {
+      if (settled || cancellationRequested || deadlineExceeded || outputExceeded) return
+      cancellationRequested = true
+      if (processGroupOwned && processGroupId != undefined) beginTermination(processGroupId)
+    }
 
     child.stderr.on("data", stderr.receive)
     child.stdout.on("data", stdout.receive)
+    signal?.addEventListener("abort", cancel, {once: true})
     child.once("error", (error) => {
       launchError = error
     })
@@ -80,18 +96,24 @@ function executeFileWithDeadlineUsing({arguments: processArguments, cwd, environ
         child.kill("SIGKILL")
         return
       }
+      processGroupOwned = true
+      if (cancellationRequested) {
+        beginTermination(processGroupId)
+        return
+      }
 
       deadlineTimer = setTimeout(() => {
-        if (settled) return
+        if (settled || cancellationRequested || deadlineExceeded || outputExceeded) return
         deadlineExceeded = true
         beginTermination(processGroupId)
       }, timeoutMs)
     })
-    child.once("close", (code, signal) => {
+    child.once("close", (code, closeSignal) => {
       settled = true
       if (deadlineTimer != undefined) clearTimeout(deadlineTimer)
       if (forceTimer != undefined) clearTimeout(forceTimer)
       if (pipeTimer != undefined) clearTimeout(pipeTimer)
+      signal?.removeEventListener("abort", cancel)
       const capturedStderr = stderr.finish()
       const capturedStdout = stdout.finish()
 
@@ -100,24 +122,34 @@ function executeFileWithDeadlineUsing({arguments: processArguments, cwd, environ
       } else if (outputExceeded) {
         reject(Object.assign(new Error(`Subprocess exceeded its ${maxBuffer}-byte output capture limit.`), {
           code: "ERR_CHILD_PROCESS_STDIO_MAXBUFFER",
-          signal,
+          signal: closeSignal,
           stderr: capturedStderr,
           stdout: capturedStdout
         }))
+      } else if (cancellationRequested) {
+        const cancellationError = Object.assign(new Error("Subprocess was cancelled."), {
+          code,
+          signal: closeSignal,
+          stderr: capturedStderr,
+          stdout: capturedStdout
+        })
+
+        cancellationFailures.add(cancellationError)
+        reject(cancellationError)
       } else if (deadlineExceeded) {
         const timeoutError = Object.assign(new Error("Subprocess exceeded its owned deadline."), {
           code,
-          signal,
+          signal: closeSignal,
           stderr: capturedStderr,
           stdout: capturedStdout
         })
 
         deadlineFailures.add(timeoutError)
         reject(timeoutError)
-      } else if (code != 0 || signal != null) {
+      } else if (code != 0 || closeSignal != null) {
         reject(Object.assign(new Error("Subprocess failed after launch."), {
           code,
-          signal,
+          signal: closeSignal,
           stderr: capturedStderr,
           stdout: capturedStdout
         }))
@@ -126,7 +158,7 @@ function executeFileWithDeadlineUsing({arguments: processArguments, cwd, environ
 
     /** Begins bounded termination after output capture crosses its limit. */
     function terminateForOutputLimit() {
-      if (outputExceeded || settled) return
+      if (settled || cancellationRequested || deadlineExceeded || outputExceeded) return
       outputExceeded = true
       if (processGroupId != undefined) beginTermination(processGroupId)
     }
@@ -230,3 +262,12 @@ function signalOwnedProcessGroup(processGroupId, signal) {
 export function exceededOwnedDeadline(error) {
   return typeof error == "object" && error != null && deadlineFailures.has(error)
 }
+
+/**
+ * Reports whether this module's cancellation signal initiated termination.
+ * @param {unknown} error - Subprocess failure.
+ * @returns {boolean} Whether the failure belongs to owned cancellation.
+ */
+export function cancelledOwnedProcess(error) {
+  return typeof error == "object" && error != null && cancellationFailures.has(error)
+}