semantifold 0.8.0 → 0.10.0

package/build/src/semantic/types.d.ts

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