semantifold 0.9.0 → 0.10.0

package/src/publication.js

@@ -29,6 +29,26 @@ const publicationBoundaries = new Set([
 const injectedPublicationFailures = new WeakMap()
 /** @type {WeakMap<GeneratedArtifactPublisher, (operation: string) => void>} */
 const publicationFilesystemObservers = new WeakMap()
+/** @type {WeakMap<GeneratedArtifactPublisher, (() => Promise<void> | void)[]>} */
+const publicationCommitGuards = new WeakMap()
+
+/**
+ * Queues one internal caller-owned currentness guard for the publisher's next transaction.
+ * The guard runs after every validator closes and immediately before the active-pointer commit.
+ * This helper is intentionally not part of the package root API.
+ * @param {GeneratedArtifactPublisher} publisher - Publisher instance.
+ * @param {() => Promise<void> | void} guard - Exact pre-commit guard.
+ * @returns {void}
+ */
+export function guardNextPublicationCommit(publisher, guard) {
+  if (!(publisher instanceof GeneratedArtifactPublisher) || typeof guard != "function") {
+    throw new TypeError("Invalid publication commit guard.")
+  }
+  const queued = publicationCommitGuards.get(publisher) ?? []
+
+  queued.push(guard)
+  publicationCommitGuards.set(publisher, queued)
+}
 
 /**
  * Installs one internal, one-shot deterministic failure used by real-filesystem interruption specs.
@@ -71,6 +91,8 @@ export class GeneratedArtifactPublisher {
   #publicationRoot
   /** @type {readonly string[]} */
   #sourceRoots
+  /** @type {readonly string[]} */
+  #sourceFiles
   /** @type {Promise<void>} */
   #publicationTail = Promise.resolve()
 
@@ -80,13 +102,14 @@ export class GeneratedArtifactPublisher {
    * @param {string} options.projectId - Stable lowercase project identity.
    * @param {string} options.projectRoot - Canonical absolute project root.
    * @param {string} options.publicationRoot - Canonical absolute publisher-owned directory beneath the project root.
-   * @param {readonly string[]} options.sourceRoots - Canonical absolute project source roots kept disjoint from publication.
+   * @param {readonly string[]} [options.sourceRoots] - Canonical absolute project source directories kept disjoint from publication.
+   * @param {readonly string[]} [options.sourceFiles] - Canonical absolute project source files kept disjoint from publication.
    */
   constructor(options) {
     if (!isPlainObject(options)) {
       publicationFailure("INVALID_PUBLICATION_REQUEST", "publication", "Publisher options must be a plain object.")
     }
-    const {projectId, projectRoot, publicationRoot, sourceRoots} = options
+    const {projectId, projectRoot, publicationRoot, sourceFiles = [], sourceRoots = []} = options
 
     if (!identityPattern.test(projectId ?? "")) {
       publicationFailure("INVALID_PUBLICATION_REQUEST", "publication", "Project identity must be a stable lowercase ID.")
@@ -96,8 +119,9 @@ export class GeneratedArtifactPublisher {
       publicationFailure("INVALID_PUBLICATION_ROOT", projectId,
         "Project and publication roots must be canonical absolute paths with publication strictly beneath the project root.")
     }
-    if (!isDenseArray(sourceRoots) || sourceRoots.length == 0) {
-      publicationFailure("INVALID_PUBLICATION_ROOT", projectId, "Source roots must be a non-empty array of canonical absolute paths.")
+    if (!isDenseArray(sourceRoots) || !isDenseArray(sourceFiles) || sourceRoots.length + sourceFiles.length == 0) {
+      publicationFailure("INVALID_PUBLICATION_ROOT", projectId,
+        "Publisher requires canonical absolute source directories or source files.")
     }
     /** @type {string[]} */
     const validatedSourceRoots = []
@@ -119,20 +143,43 @@ export class GeneratedArtifactPublisher {
       }
       validatedSourceRoots.push(sourceRoot)
     }
+    /** @type {string[]} */
+    const validatedSourceFiles = []
+
+    for (let index = 0; index < sourceFiles.length; index += 1) {
+      const sourceFile = sourceFiles[index]
+
+      if (!isCanonicalAbsolutePath(sourceFile) || !isPathWithin(projectRoot, sourceFile)) {
+        publicationFailure("INVALID_PUBLICATION_ROOT", projectId,
+          "Source files must be canonical absolute paths within the project root.")
+      }
+      if (pathsOverlap(publicationRoot, sourceFile)) {
+        publicationFailure("PUBLICATION_SOURCE_OVERLAP", projectId,
+          "Publication root and source files must be disjoint.")
+      }
+      validatedSourceFiles.push(sourceFile)
+    }
 
     this.#projectId = projectId
     this.#projectRoot = projectRoot
     this.#publicationRoot = publicationRoot
     this.#sourceRoots = Object.freeze(validatedSourceRoots)
+    this.#sourceFiles = Object.freeze(validatedSourceFiles)
   }
 
   /**
    * Stages, validates, and publishes one complete immutable project generation.
    * Calls on one publisher instance are serialized in invocation order.
    * @param {import("./semantic/types.js").PublicationRequest} request - Complete publication request.
+   * @param {import("./semantic/types.js").PublicationOptions} [options] - Transaction lifecycle controls.
    * @returns {Promise<import("./semantic/types.js").PublishedGeneration>} Committed immutable snapshot.
    */
-  publish(request) {
+  publish(request, options = {}) {
+    const signal = validatePublicationOptions(options, this.#projectId)
+    const queuedGuards = publicationCommitGuards.get(this)
+    const commitGuard = queuedGuards?.shift()
+
+    if (queuedGuards?.length == 0) publicationCommitGuards.delete(this)
     /** @type {(value: import("./semantic/types.js").PublishedGeneration) => void} */
     let resolveResult
     /** @type {(reason?: unknown) => void} */
@@ -143,7 +190,7 @@ export class GeneratedArtifactPublisher {
     })
     const operation = this.#publicationTail.then(async () => {
       try {
-        resolveResult(await this.#publish(request))
+        resolveResult(await this.#publish(request, signal, commitGuard))
       } catch (error) {
         rejectResult(error)
       }
@@ -173,11 +220,14 @@ export class GeneratedArtifactPublisher {
   /**
    * Performs one serialized publication.
    * @param {import("./semantic/types.js").PublicationRequest} request - Complete request.
+   * @param {AbortSignal | undefined} signal - Optional transaction cancellation authority.
+   * @param {(() => Promise<void> | void) | undefined} commitGuard - Optional currentness guard.
    * @returns {Promise<import("./semantic/types.js").PublishedGeneration>} Publication result.
    */
-  async #publish(request) {
+  async #publish(request, signal, commitGuard) {
     const validated = validatePublicationRequest(request, this.#projectId)
 
+    assertPublicationActive(signal, this.#projectId)
     await this.#prepareRoot()
     await reconcilePublication(this.#publicationRoot, this.#projectId, this)
     await verifyAtomicReplacement(this.#publicationRoot, this.#projectId)
@@ -188,55 +238,80 @@ export class GeneratedArtifactPublisher {
     const tempPointerName = `.active-generation.${validated.generationId}.tmp`
     const tempPointerPath = path.join(this.#publicationRoot, tempPointerName)
     const journalPath = path.join(this.#publicationRoot, journalName, `${validated.generationId}.json`)
+    const retainedGeneration = await optionalStatus(generationPath, this.#projectId, "retained generation") !== null
     let committed = false
     let journalCreated = false
     let generationCreated = false
     let tempPointerCreated = false
     let failureCode = "PUBLICATION_STAGE_WRITE_FAILED"
+    /** @type {import("./semantic/types.js").GenerationManifest | null} */
+    let manifest = null
+    /** @type {Buffer | null} */
+    let manifestBytes = null
 
     try {
-      await assertAbsent(generationPath, "PUBLICATION_UNOWNED_CONFLICT", this.#projectId,
-        "Generation identity is already owned or ambiguous.")
       await assertAbsent(tempPointerPath, "PUBLICATION_UNOWNED_CONFLICT", this.#projectId,
         "Temporary active pointer path is already owned or ambiguous.")
       await assertAbsent(journalPath, "PUBLICATION_UNOWNED_CONFLICT", this.#projectId,
         "Publication journal identity is already owned or ambiguous.")
-      const journal = {
-        generationId: validated.generationId,
-        projectId: this.#projectId,
-        schema: "SemantifoldPublicationJournal",
-        tempPointer: tempPointerName,
-        version: 1
+      if (retainedGeneration) {
+        const retained = await verifyRetainedGeneration(generationPath, validated, this.#projectId)
+
+        manifest = retained.manifest
+        manifestBytes = retained.manifestBytes
       }
+      const journal = retainedGeneration
+        ? {
+            generationId: validated.generationId,
+            operation: "reactivate",
+            projectId: this.#projectId,
+            schema: "SemantifoldPublicationJournal",
+            tempPointer: tempPointerName,
+            version: 2
+          }
+        : {
+            generationId: validated.generationId,
+            projectId: this.#projectId,
+            schema: "SemantifoldPublicationJournal",
+            tempPointer: tempPointerName,
+            version: 1
+          }
 
       await writeSyncedFile(journalPath, serializeJson(journal), "wx")
       journalCreated = true
       await syncDirectory(path.dirname(journalPath))
-      await mkdir(generationPath, {mode: 0o700})
-      generationCreated = true
-      await syncDirectory(path.dirname(generationPath))
+      if (!retainedGeneration) {
+        await mkdir(generationPath, {mode: 0o700})
+        generationCreated = true
+        await syncDirectory(path.dirname(generationPath))
+
+        /** @type {import("./semantic/types.js").GenerationTargetManifest[]} */
+        const targetManifests = []
+
+        for (const target of validated.targets) {
+          targetManifests.push(await stageTarget(generationPath, target, this.#projectId))
+        }
+        const manifestCandidate = /** @type {import("./semantic/types.js").GenerationManifest} */ ({
+          generationId: validated.generationId,
+          projectId: this.#projectId,
+          schema: /** @type {const} */ ("SemantifoldGenerationManifest"),
+          targets: targetManifests,
+          version: /** @type {const} */ (1)
+        })
 
-      /** @type {import("./semantic/types.js").GenerationTargetManifest[]} */
-      const targetManifests = []
+        manifestBytes = serializeJson(manifestCandidate)
+        manifest = validateGenerationManifest(JSON.parse(manifestBytes.toString("utf8")), this.#projectId,
+          validated.generationId)
 
-      for (const target of validated.targets) {
-        targetManifests.push(await stageTarget(generationPath, target, this.#projectId))
+        await writeSyncedFile(manifestPath, manifestBytes, "wx")
+        await syncTreeDirectories(generationPath)
+        await verifyManifestFiles(generationPath, manifest, this.#projectId)
+      }
+      if (manifest === null || manifestBytes === null) {
+        publicationFailure("PUBLICATION_STAGE_WRITE_FAILED", this.#projectId,
+          "Candidate generation manifest could not be prepared.")
       }
       reachPublicationBoundary(this, "after-stage")
-      const manifestCandidate = /** @type {import("./semantic/types.js").GenerationManifest} */ ({
-        generationId: validated.generationId,
-        projectId: this.#projectId,
-        schema: /** @type {const} */ ("SemantifoldGenerationManifest"),
-        targets: targetManifests,
-        version: /** @type {const} */ (1)
-      })
-      const manifestBytes = serializeJson(manifestCandidate)
-      const manifest = validateGenerationManifest(JSON.parse(manifestBytes.toString("utf8")), this.#projectId,
-        validated.generationId)
-
-      await writeSyncedFile(manifestPath, manifestBytes, "wx")
-      await syncTreeDirectories(generationPath)
-      await verifyManifestFiles(generationPath, manifest, this.#projectId)
       failureCode = "PUBLICATION_POINTER_FAILED"
 
       const pointer = {
@@ -251,6 +326,8 @@ export class GeneratedArtifactPublisher {
         tempPointerCreated = true
       })
       reachPublicationBoundary(this, "before-pointer-replace")
+      await commitGuard?.()
+      assertPublicationActive(signal, this.#projectId)
       await rename(tempPointerPath, path.join(this.#publicationRoot, activePointerName))
       tempPointerCreated = false
       committed = true
@@ -339,11 +416,65 @@ export class GeneratedArtifactPublisher {
           "Publication root and source roots resolve to overlapping paths.")
       }
     }
+    for (const sourceFile of this.#sourceFiles) {
+      await ensureDirectoryWithoutSymlinks(path.dirname(sourceFile), false, this.#projectId)
+      let status
+      let exactSource
+
+      try {
+        status = await lstat(sourceFile)
+        exactSource = await realpath(sourceFile)
+      } catch (error) {
+        publicationFailure("INVALID_PUBLICATION_ROOT", this.#projectId,
+          "Source file could not be resolved safely.", error)
+      }
+      if (status.isSymbolicLink()) {
+        publicationFailure("PUBLICATION_SYMLINK_TRAVERSAL", this.#projectId,
+          "Source file traversal encountered a symbolic link.")
+      }
+      if (!status.isFile() || exactSource != sourceFile || !isPathWithin(exactProject, exactSource)) {
+        publicationFailure("INVALID_PUBLICATION_ROOT", this.#projectId,
+          "Source files must resolve to real regular files within the project root.")
+      }
+      if (pathsOverlap(exactPublication, exactSource)) {
+        publicationFailure("PUBLICATION_SOURCE_OVERLAP", this.#projectId,
+          "Publication root and source files resolve to overlapping paths.")
+      }
+    }
     await ensureOwnedDirectory(path.join(this.#publicationRoot, generationsName), this.#projectId)
     await ensureOwnedDirectory(path.join(this.#publicationRoot, journalName), this.#projectId)
   }
 }
 
+/**
+ * Validates and snapshots transaction lifecycle controls before publication is queued.
+ * @param {unknown} options - Candidate options.
+ * @param {string} projectId - Project diagnostic identity.
+ * @returns {AbortSignal | undefined} Optional cancellation signal.
+ */
+function validatePublicationOptions(options, projectId) {
+  if (!isPlainObject(options) || Object.keys(options).some(key => key != "signal") ||
+    options.signal !== undefined && !(options.signal instanceof AbortSignal)) {
+    publicationFailure("INVALID_PUBLICATION_REQUEST", projectId,
+      "Publication options require only an optional AbortSignal.")
+  }
+
+  return /** @type {AbortSignal | undefined} */ (options.signal)
+}
+
+/**
+ * Rejects cancellation before the atomic active-pointer commit begins.
+ * @param {AbortSignal | undefined} signal - Optional transaction cancellation authority.
+ * @param {string} projectId - Project diagnostic identity.
+ * @returns {void}
+ */
+function assertPublicationActive(signal, projectId) {
+  if (signal?.aborted) {
+    publicationFailure("PUBLICATION_CANCELLED", projectId,
+      "Publication was cancelled before the active generation pointer commit.")
+  }
+}
+
 /**
  * Throws and consumes a configured internal failure at an exact lifecycle boundary.
  * @param {GeneratedArtifactPublisher} publisher - Active publisher.
@@ -388,8 +519,9 @@ async function reconcilePublication(publicationRoot, projectId, publisher) {
     const candidatePath = ownedPath(path.join(publicationRoot, generationsName), journal.generationId, projectId)
     const temporaryPointerPath = path.join(publicationRoot, journal.tempPointer)
     const committed = pointer?.generationId == journal.generationId
+    const candidateOwned = journal.version == 1
 
-    if (!committed) {
+    if (candidateOwned && !committed) {
       const candidateStatus = await optionalStatus(candidatePath, projectId, "candidate generation")
 
       if (candidateStatus) {
@@ -408,7 +540,7 @@ async function reconcilePublication(publicationRoot, projectId, publisher) {
       }
     }
     await removeJournalOwnedState({
-      ...(!committed ? {candidatePath} : {}),
+      ...(candidateOwned && !committed ? {candidatePath} : {}),
       journalPath,
       projectId,
       publicationRoot,
@@ -542,7 +674,7 @@ async function optionalStatus(filename, projectId, subject) {
  * Validates and snapshots one publication request before staging.
  * @param {unknown} request - Request candidate.
  * @param {string} projectId - Project diagnostic identity.
- * @returns {{generationId: string, targets: readonly ValidatedPublicationTarget[]}} Validated request.
+ * @returns {ValidatedPublicationRequest} Validated request.
  */
 function validatePublicationRequest(request, projectId) {
   if (!isPlainObject(request)) {
@@ -661,6 +793,56 @@ function validatePublicationRequest(request, projectId) {
   return {generationId, targets: Object.freeze(targets)}
 }
 
+/**
+ * Verifies that one retained immutable generation exactly represents a validator-free request.
+ * The retained directory is never modified or removed on either success or failure.
+ * @param {string} generationPath - Existing generation path.
+ * @param {ValidatedPublicationRequest} request - Validated candidate request.
+ * @param {string} projectId - Project diagnostic identity.
+ * @returns {Promise<{manifest: import("./semantic/types.js").GenerationManifest, manifestBytes: Buffer}>} Exact retained manifest.
+ */
+async function verifyRetainedGeneration(generationPath, request, projectId) {
+  if (request.targets.some(target => target.validators.length != 0)) {
+    publicationFailure("PUBLICATION_UNOWNED_CONFLICT", projectId,
+      "Retained generations can be reactivated only for exact validator-free candidates.")
+  }
+  const targetManifests = request.targets.map(target => Object.freeze({
+    artifacts: Object.freeze(target.artifactSet.artifacts.map(artifact => describeGeneratedArtifact(artifact).manifest)),
+    buildArtifacts: Object.freeze([]),
+    id: target.id,
+    ...(target.artifactSet.metadata === undefined ? {} : {metadata: target.artifactSet.metadata}),
+    projections: Object.freeze({build: target.buildProjection, source: target.sourceProjection}),
+    role: target.role,
+    target: target.artifactSet.target
+  }))
+  const candidate = {
+    generationId: request.generationId,
+    projectId,
+    schema: "SemantifoldGenerationManifest",
+    targets: targetManifests,
+    version: 1
+  }
+  const expectedBytes = serializeJson(candidate)
+  const manifest = validateGenerationManifest(JSON.parse(expectedBytes.toString("utf8")), projectId, request.generationId)
+  let manifestBytes
+
+  try {
+    manifestBytes = await readAndSyncRegularFile(path.join(generationPath, "manifest.json"), projectId,
+      "MALFORMED_GENERATION_MANIFEST", "Retained generation manifest must be a regular file.")
+    if (!manifestBytes.equals(expectedBytes)) {
+      publicationFailure("PUBLICATION_UNOWNED_CONFLICT", projectId,
+        "Retained generation does not exactly match the requested candidate.")
+    }
+    await verifyManifestFiles(generationPath, manifest, projectId)
+  } catch (error) {
+    if (error instanceof SemantifoldDiagnostic && error.code == "PUBLICATION_UNOWNED_CONFLICT") throw error
+    publicationFailure("PUBLICATION_UNOWNED_CONFLICT", projectId,
+      "Retained generation could not be verified as the exact requested candidate.", error)
+  }
+
+  return {manifest, manifestBytes}
+}
+
 /**
  * Stages one validated target and invokes its ordered validators.
  * @param {string} generationPath - Candidate generation path.
@@ -679,27 +861,17 @@ async function stageTarget(generationPath, target, projectId) {
 
   for (const artifact of target.artifactSet.artifacts) {
     const filename = ownedPath(sourcePath, artifact.path, projectId)
-    const bytes = artifact.contentKind == "text"
-      ? Buffer.from(/** @type {string} */ (artifact.content), "utf8")
-      : Buffer.from(/** @type {Uint8Array} */ (artifact.content))
+    const described = describeGeneratedArtifact(artifact)
 
     await mkdir(path.dirname(filename), {mode: 0o700, recursive: true})
     try {
-      await writeSyncedFile(filename, bytes, "wx")
+      await writeSyncedFile(filename, described.bytes, "wx")
     } catch (error) {
       if (error instanceof SemantifoldDiagnostic) throw error
       publicationFailure("PUBLICATION_STAGE_WRITE_FAILED", projectId,
         `Generated artifact '${artifact.path}' could not be staged.`, error)
     }
-    artifacts.push(Object.freeze({
-      byteLength: bytes.byteLength,
-      contentKind: artifact.contentKind,
-      hash: Object.freeze({algorithm: /** @type {const} */ ("sha256"), value: sha256(bytes)}),
-      mediaType: artifact.mediaType,
-      path: artifact.path,
-      provenance: artifact.provenance,
-      role: artifact.role
-    }))
+    artifacts.push(described.manifest)
   }
 
   /** @type {import("./semantic/types.js").PublicationBuildArtifactInput[]} */
@@ -765,6 +937,30 @@ async function stageTarget(generationPath, target, projectId) {
   })
 }
 
+/**
+ * Derives exact staged bytes and their deterministic generation-manifest record.
+ * @param {import("./semantic/types.js").GeneratedSetArtifact} artifact - Validated generated artifact.
+ * @returns {{bytes: Buffer, manifest: import("./semantic/types.js").GenerationArtifactManifest}} Bytes and manifest record.
+ */
+function describeGeneratedArtifact(artifact) {
+  const bytes = artifact.contentKind == "text"
+    ? Buffer.from(/** @type {string} */ (artifact.content), "utf8")
+    : Buffer.from(/** @type {Uint8Array} */ (artifact.content))
+
+  return {
+    bytes,
+    manifest: Object.freeze({
+      byteLength: bytes.byteLength,
+      contentKind: artifact.contentKind,
+      hash: Object.freeze({algorithm: /** @type {const} */ ("sha256"), value: sha256(bytes)}),
+      mediaType: artifact.mediaType,
+      path: artifact.path,
+      provenance: artifact.provenance,
+      role: artifact.role
+    })
+  }
+}
+
 /**
  * Validates validator/compiler output metadata.
  * @param {unknown} descriptor - Metadata candidate.
@@ -1748,11 +1944,14 @@ function isActivePointer(value) {
  * @returns {value is PublicationJournal} Whether the value is strict and versioned.
  */
 function isPublicationJournal(value) {
-  return isPlainObject(value) && hasExactKeys(value, ["generationId", "projectId", "schema", "tempPointer", "version"]) &&
-    value.schema == "SemantifoldPublicationJournal" && value.version == 1 &&
-    typeof value.projectId == "string" && identityPattern.test(value.projectId) &&
-    typeof value.generationId == "string" && generationPattern.test(value.generationId) &&
-    value.tempPointer == `.active-generation.${value.generationId}.tmp`
+  if (!isPlainObject(value) || value.schema != "SemantifoldPublicationJournal" ||
+    typeof value.projectId != "string" || !identityPattern.test(value.projectId) ||
+    typeof value.generationId != "string" || !generationPattern.test(value.generationId) ||
+    value.tempPointer != `.active-generation.${value.generationId}.tmp`) return false
+
+  return value.version == 1 && hasExactKeys(value, ["generationId", "projectId", "schema", "tempPointer", "version"]) ||
+    value.version == 2 && value.operation == "reactivate" &&
+      hasExactKeys(value, ["generationId", "operation", "projectId", "schema", "tempPointer", "version"])
 }
 
 /**
@@ -1835,6 +2034,12 @@ function publicationFailure(code, projectId, message, error) {
  * @property {readonly import("./semantic/types.js").PublicationValidator[]} validators - Ordered validators.
  */
 
+/**
+ * @typedef ValidatedPublicationRequest
+ * @property {string} generationId - Snapshotted generation identity.
+ * @property {readonly ValidatedPublicationTarget[]} targets - Snapshotted ordered targets.
+ */
+
 /**
  * @typedef ActivePointer
  * @property {"SemantifoldActiveGeneration"} schema - Schema discriminator.
@@ -1845,10 +2050,22 @@ function publicationFailure(code, projectId, message, error) {
  */
 
 /**
- * @typedef PublicationJournal
+ * @typedef CandidatePublicationJournal
  * @property {"SemantifoldPublicationJournal"} schema - Schema discriminator.
  * @property {1} version - Schema version.
  * @property {string} projectId - Project identity.
  * @property {string} generationId - Candidate generation identity.
  * @property {string} tempPointer - Owned sibling temporary-pointer filename.
  */
+
+/**
+ * @typedef ReactivationPublicationJournal
+ * @property {"SemantifoldPublicationJournal"} schema - Schema discriminator.
+ * @property {2} version - Schema version.
+ * @property {"reactivate"} operation - Retained-generation activation without candidate ownership.
+ * @property {string} projectId - Project identity.
+ * @property {string} generationId - Retained generation identity.
+ * @property {string} tempPointer - Owned sibling temporary-pointer filename.
+ */
+
+/** @typedef {CandidatePublicationJournal | ReactivationPublicationJournal} PublicationJournal */

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.
  */
 
 /**
@@ -425,10 +433,15 @@
 
 /**
  * @typedef PublicationRequest
- * @property {string} generationId - Unique explicit generation/cycle identity.
+ * @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.
@@ -504,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.