mesh-delivery-contracts: the build seats' part types Fetch, the toolchain, the artifacts, the check's levels and a step's result, and marks the times date-time; fixtures for a check ask and the three kinds of result (ADR 0634 §6; issue 1966)

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i

contracts/ts/seats/nodebuildnode/src/index.ts

@@ -102,20 +102,22 @@ export function parseToolchainsByNodeLanguageKey(key: string): { node: string; l
   return { node, language };
 }
 
+export type AskArtifact = buildStep.AskArtifact;
 export type BuildAnswer = buildStep.BuildAnswer;
-export type BuildAnswerArtifactsItem = buildStep.BuildAnswerArtifactsItem;
-export type BuildAnswerToolchain = buildStep.BuildAnswerToolchain;
+export type BuiltArtifact = buildStep.BuiltArtifact;
 export type Capacity = buildStep.Capacity;
 export type CheckAnswer = buildStep.CheckAnswer;
-export type CheckAnswerLevelsItem = buildStep.CheckAnswerLevelsItem;
-export type CheckAnswerLevelsItemDigest = buildStep.CheckAnswerLevelsItemDigest;
-export type CheckAnswerLevelsItemDigestNeedsItem = buildStep.CheckAnswerLevelsItemDigestNeedsItem;
-export type CheckAnswerLevelsItemDigestPackagesItem = buildStep.CheckAnswerLevelsItemDigestPackagesItem;
-export type CheckAnswerLevelsItemKeptItem = buildStep.CheckAnswerLevelsItemKeptItem;
-export type CheckAnswerLevelsItemUnmetItem = buildStep.CheckAnswerLevelsItemUnmetItem;
 export type ComposeAnswer = buildStep.ComposeAnswer;
 export type CurrentAnswer = buildStep.CurrentAnswer;
 export type CurrentInput = buildStep.CurrentInput;
+export type Fetch = buildStep.Fetch;
+export type FetchBesideItem = buildStep.FetchBesideItem;
+export type LevelAnswer = buildStep.LevelAnswer;
+export type LevelAnswerDigest = buildStep.LevelAnswerDigest;
+export type LevelAnswerDigestNeedsItem = buildStep.LevelAnswerDigestNeedsItem;
+export type LevelAnswerDigestPackagesItem = buildStep.LevelAnswerDigestPackagesItem;
+export type LevelAnswerKeptItem = buildStep.LevelAnswerKeptItem;
+export type LevelAnswerUnmetItem = buildStep.LevelAnswerUnmetItem;
 export type Pause = buildStep.Pause;
 export type PauseAnswer = buildStep.PauseAnswer;
 export type PauseInput = buildStep.PauseInput;
@@ -124,11 +126,11 @@ export type ResumeInput = buildStep.ResumeInput;
 export type Step = buildStep.Step;
 export type StepAsk = buildStep.StepAsk;
 export type StepAskBuild = buildStep.StepAskBuild;
-export type StepAskBuildArtifactsItem = buildStep.StepAskBuildArtifactsItem;
-export type StepAskBuildToolchain = buildStep.StepAskBuildToolchain;
 export type StepAskCheck = buildStep.StepAskCheck;
 export type StepAskCompose = buildStep.StepAskCompose;
+export type StepResult = buildStep.StepResult;
 export type Toolchain = buildStep.Toolchain;
+export type ToolchainUsed = buildStep.ToolchainUsed;
 
 /** is the body of delivery. */
 export type DeliveryAccept = StepAsk;

contracts/ts/seats/nodebuildnode/src/parts/build-step.ts

@@ -8,23 +8,26 @@ export const verbs = {
   resume: "resume",
 } as const;
 
-export interface BuildAnswerArtifactsItem {
+/** one artifact of a build ask: built from the fetched tree, or copied from an upstream pin */
+export interface AskArtifact {
   "artifact": string;
-  "digest": string;
-  "reference"?: string;
-}
-
-export interface BuildAnswerToolchain {
-  "language": string;
-  "recipe": string;
-  "version": string;
+  "from"?: string;
+  "seat"?: string;
+  "version"?: string;
 }
 
 export interface BuildAnswer {
-  "artifacts": BuildAnswerArtifactsItem[];
+  "artifacts": BuiltArtifact[];
   "imports"?: string[];
   "out-of-step"?: string[];
-  "toolchain"?: BuildAnswerToolchain;
+  "toolchain"?: ToolchainUsed;
+}
+
+/** one artifact a build made: its digest and the reference it was published under */
+export interface BuiltArtifact {
+  "artifact": string;
+  "digest": string;
+  "reference"?: string;
 }
 
 /** how many steps the node runs at once */
@@ -47,49 +50,9 @@ export interface Capacity {
   "why": string;
 }
 
-export interface CheckAnswerLevelsItemDigestNeedsItem {
-  "needs"?: string[];
-  "package"?: string;
-}
-
-export interface CheckAnswerLevelsItemDigestPackagesItem {
-  "digest": string;
-  "package": string;
-}
-
-export interface CheckAnswerLevelsItemDigest {
-  "beside"?: string[];
-  "judged_by"?: string;
-  "level"?: string;
-  "needs"?: CheckAnswerLevelsItemDigestNeedsItem[];
-  "packages"?: CheckAnswerLevelsItemDigestPackagesItem[];
-  "without_tests"?: string[];
-}
-
-export interface CheckAnswerLevelsItemKeptItem {
-  "digest"?: string;
-  "package"?: string;
-  "tests"?: number;
-}
-
-export interface CheckAnswerLevelsItemUnmetItem {
-  "needs"?: string[];
-  "package"?: string;
-}
-
-export interface CheckAnswerLevelsItem {
-  "digest"?: CheckAnswerLevelsItemDigest;
-  "judged"?: string;
-  "kept"?: CheckAnswerLevelsItemKeptItem[];
-  "level": string;
-  "tests"?: unknown[];
-  "unmet"?: CheckAnswerLevelsItemUnmetItem[];
-}
-
 export interface CheckAnswer {
-  /** what the build module fetches: the repository, commit and directory, as the indexer states it */
-  "fetch": unknown;
-  "levels"?: CheckAnswerLevelsItem[];
+  "fetch": Fetch;
+  "levels"?: LevelAnswer[];
 }
 
 export interface ComposeAnswer {
@@ -99,6 +62,71 @@ export interface ComposeAnswer {
   "verdict"?: unknown;
 }
 
+export interface FetchBesideItem {
+  "commit": string;
+  "repository": string;
+}
+
+/** what a build module's fetch tool is asked: the repository and the full commit, the pull request's ref when only its head carries the commit, the trunk commit to merge onto for a merge preview, the module's directory and named paths, the mesh packages to build against, and the sibling repositories placed beside */
+export interface Fetch {
+  /** the trunk commit a merge preview merges onto */
+  "base"?: string;
+  /** the sibling repositories placed beside the fetched tree */
+  "beside"?: FetchBesideItem[];
+  /** the full commit */
+  "commit": string;
+  /** the module's directory in the repository ("." for its root), with paths */
+  "dir"?: string;
+  /** the version (a full commit) of each mesh package to build against, by its module path */
+  "packages"?: Record<string, string>;
+  /** the paths the module names, relative to dir */
+  "paths"?: string[];
+  /** the pull request's ref, when only its head carries the commit */
+  "ref"?: string;
+  /** <owner>/<name> */
+  "repository": string;
+}
+
+export interface LevelAnswerDigestNeedsItem {
+  "needs"?: string[];
+  "package"?: string;
+}
+
+export interface LevelAnswerDigestPackagesItem {
+  "digest": string;
+  "package": string;
+}
+
+export interface LevelAnswerDigest {
+  "beside"?: string[];
+  "judged_by"?: string;
+  "level"?: string;
+  "needs"?: LevelAnswerDigestNeedsItem[];
+  "packages"?: LevelAnswerDigestPackagesItem[];
+  "without_tests"?: string[];
+}
+
+export interface LevelAnswerKeptItem {
+  "digest"?: string;
+  "package"?: string;
+  "tests"?: number;
+}
+
+export interface LevelAnswerUnmetItem {
+  "needs"?: string[];
+  "package"?: string;
+}
+
+/** one level of a check ask: the digest's answer, the kept verdicts taken, one test result per test step run, and the packages the node could not test */
+export interface LevelAnswer {
+  "digest"?: LevelAnswerDigest;
+  "judged"?: string;
+  "kept"?: LevelAnswerKeptItem[];
+  "level": string;
+  "tests"?: unknown[];
+  "unmet"?: LevelAnswerUnmetItem[];
+}
+
 /** whether the node takes no new ask */
 export interface Pause {
   /** when (RFC 3339 time) */
@@ -120,8 +148,7 @@ export interface Step {
   /** when (RFC 3339 time) */
   "phase-at"?: string;
   "reason"?: string;
-  /** what the step answered */
-  "result"?: unknown;
+  "result"?: StepResult;
   /** when (RFC 3339 time) */
   "started": string;
   /** running, passed, failed or refused */
@@ -132,33 +159,18 @@ export interface Step {
   "what"?: string;
 }
 
-export interface StepAskBuildArtifactsItem {
-  "artifact": string;
-  "from"?: string;
-  "seat"?: string;
-  "version"?: string;
-}
-
-export interface StepAskBuildToolchain {
-  "language": string;
-  "recipe": string;
-  "version": string;
-}
-
 export interface StepAskBuild {
-  "artifacts": StepAskBuildArtifactsItem[];
-  /** what the build module fetches: the repository, commit and directory, as the indexer states it */
-  "fetch"?: unknown;
+  "artifacts": AskArtifact[];
+  "fetch"?: Fetch;
   "fp"?: string;
   "module": string;
   "path"?: string;
   "publish"?: boolean;
-  "toolchain"?: StepAskBuildToolchain;
+  "toolchain"?: ToolchainUsed;
 }
 
 export interface StepAskCheck {
-  /** what the build module fetches: the repository, commit and directory, as the indexer states it */
-  "fetch": unknown;
+  "fetch": Fetch;
   "kept"?: boolean;
   "levels": string[];
   "packages"?: string[];
@@ -169,8 +181,7 @@ export interface StepAskCheck {
 
 export interface StepAskCompose {
   "dir": string;
-  /** what the build module fetches: the repository, commit and directory, as the indexer states it */
-  "fetch": unknown;
+  "fetch": Fetch;
   "package": string;
   "reader"?: string;
   /** the compose-candidate request */
@@ -197,6 +208,26 @@ export interface StepAsk {
   "v"?: number;
 }
 
+/** what a step answered, by the kind of ask: a build's artifacts, toolchain, imports and out-of-step modules; a check's fetch and levels; a compose's built, key and verdict; a declined ask's declined, needs and lacks. The fields of the kinds do not meet, so one layout holds the four */
+export interface StepResult {
+  "artifacts"?: BuiltArtifact[];
+  "built"?: boolean;
+  /** the holder declined the ask: its node lacks what the ask needs */
+  "declined"?: boolean;
+  "fetch"?: Fetch;
+  "imports"?: string[];
+  "key"?: string;
+  /** what the holder's node lacks of it */
+  "lacks"?: string[];
+  "levels"?: LevelAnswer[];
+  /** what the declined ask needs */
+  "needs"?: string[];
+  "out-of-step"?: string[];
+  "toolchain"?: ToolchainUsed;
+  /** the compose-candidate verdict (the composer's own layout) */
+  "verdict"?: unknown;
+}
+
 /** the toolchain a node reports */
 export interface Toolchain {
   /** when (RFC 3339 time) */
@@ -209,6 +240,13 @@ export interface Toolchain {
   "version": string;
 }
 
+/** the toolchain a build was made with: the language, the installed version and the build module's recipe */
+export interface ToolchainUsed {
+  "language": string;
+  "recipe": string;
+  "version": string;
+}
+
 /** is what current takes. */
 export interface CurrentInput {
 }