JSON Impl and schema for BuildResult

doc/manual/package.nix

@@ -37,9 +37,11 @@ mkMesonDerivation (finalAttrs: {
         ../../src/libutil-tests/data/hash
         ../../src/libstore-tests/data/content-address
         ../../src/libstore-tests/data/store-path
+        ../../src/libstore-tests/data/realisation
         ../../src/libstore-tests/data/derived-path
         ../../src/libstore-tests/data/path-info
         ../../src/libstore-tests/data/nar-info
+        ../../src/libstore-tests/data/build-result
         # Too many different types of files to filter for now
         ../../doc/manual
         ./.

doc/manual/source/SUMMARY.md.in

@@ -126,6 +126,8 @@
     - [Store Object Info](protocols/json/store-object-info.md)
     - [Derivation](protocols/json/derivation.md)
     - [Deriving Path](protocols/json/deriving-path.md)
+    - [Build Trace Entry](protocols/json/build-trace-entry.md)
+    - [Build Result](protocols/json/build-result.md)
   - [Serving Tarball Flakes](protocols/tarball-fetcher.md)
   - [Store Path Specification](protocols/store-path.md)
   - [Nix Archive (NAR) Format](protocols/nix-archive/index.md)

doc/manual/source/protocols/json/build-result.md

@@ -0,0 +1,21 @@
+{{#include build-result-v1-fixed.md}}
+
+## Examples
+
+### Successful build
+
+```json
+{{#include schema/build-result-v1/success.json}}
+```
+
+### Failed build (output rejected)
+
+```json
+{{#include schema/build-result-v1/output-rejected.json}}
+```
+
+### Failed build (non-deterministic)
+
+```json
+{{#include schema/build-result-v1/not-deterministic.json}}
+```

doc/manual/source/protocols/json/build-trace-entry.md

@@ -0,0 +1,27 @@
+{{#include build-trace-entry-v1-fixed.md}}
+
+## Examples
+
+### Simple build trace entry
+
+```json
+{{#include schema/build-trace-entry-v1/simple.json}}
+```
+
+### Build trace entry with dependencies
+
+```json
+{{#include schema/build-trace-entry-v1/with-dependent-realisations.json}}
+```
+
+### Build trace entry with signature
+
+```json
+{{#include schema/build-trace-entry-v1/with-signature.json}}
+```
+
+<!--
+## Raw Schema
+
+[JSON Schema for Build Trace Entry v1](schema/build-trace-entry-v1.json)
+-->

doc/manual/source/protocols/json/meson.build

@@ -15,6 +15,8 @@ schemas = [
   'store-object-info-v1',
   'derivation-v3',
   'deriving-path-v1',
+  'build-trace-entry-v1',
+  'build-result-v1',
 ]
 
 schema_files = files()

doc/manual/source/protocols/json/schema/build-result-v1

@@ -0,0 +1 @@
+../../../../../../src/libstore-tests/data/build-result

doc/manual/source/protocols/json/schema/build-result-v1.yaml

@@ -0,0 +1,136 @@
+"$schema": "http://json-schema.org/draft-04/schema"
+"$id": "https://nix.dev/manual/nix/latest/protocols/json/schema/build-result-v1.json"
+title: Build Result
+description: |
+  This schema describes the JSON representation of Nix's `BuildResult` type, which represents the result of building a derivation or substituting store paths.
+
+  Build results can represent either successful builds (with built outputs) or various types of failures.
+
+oneOf:
+  - "$ref": "#/$defs/success"
+  - "$ref": "#/$defs/failure"
+type: object
+required:
+  - success
+  - status
+properties:
+  timesBuilt:
+    type: integer
+    minimum: 0
+    title: Times built
+    description: |
+      How many times this build was performed.
+
+  startTime:
+    type: integer
+    minimum: 0
+    title: Start time
+    description: |
+      The start time of the build (or one of the rounds, if it was repeated), as a Unix timestamp.
+
+  stopTime:
+    type: integer
+    minimum: 0
+    title: Stop time
+    description: |
+      The stop time of the build (or one of the rounds, if it was repeated), as a Unix timestamp.
+
+  cpuUser:
+    type: integer
+    minimum: 0
+    title: User CPU time
+    description: |
+      User CPU time the build took, in microseconds.
+
+  cpuSystem:
+    type: integer
+    minimum: 0
+    title: System CPU time
+    description: |
+      System CPU time the build took, in microseconds.
+
+"$defs":
+  success:
+    type: object
+    title: Successful Build Result
+    description: |
+      Represents a successful build with built outputs.
+    required:
+      - success
+      - status
+      - builtOutputs
+    properties:
+      success:
+        const: true
+        title: Success indicator
+        description: |
+          Always true for successful build results.
+
+      status:
+        type: string
+        title: Success status
+        description: |
+          Status string for successful builds.
+        enum:
+          - "Built"
+          - "Substituted"
+          - "AlreadyValid"
+          - "ResolvesToAlreadyValid"
+
+      builtOutputs:
+        type: object
+        title: Built outputs
+        description: |
+          A mapping from output names to their build trace entries.
+        additionalProperties:
+          "$ref": "build-trace-entry-v1.yaml"
+
+  failure:
+    type: object
+    title: Failed Build Result
+    description: |
+      Represents a failed build with error information.
+    required:
+      - success
+      - status
+      - errorMsg
+    properties:
+      success:
+        const: false
+        title: Success indicator
+        description: |
+          Always false for failed build results.
+
+      status:
+        type: string
+        title: Failure status
+        description: |
+          Status string for failed builds.
+        enum:
+          - "PermanentFailure"
+          - "InputRejected"
+          - "OutputRejected"
+          - "TransientFailure"
+          - "CachedFailure"
+          - "TimedOut"
+          - "MiscFailure"
+          - "DependencyFailed"
+          - "LogLimitExceeded"
+          - "NotDeterministic"
+          - "NoSubstituters"
+          - "HashMismatch"
+
+      errorMsg:
+        type: string
+        title: Error message
+        description: |
+          Information about the error if the build failed.
+
+      isNonDeterministic:
+        type: boolean
+        title: Non-deterministic flag
+        description: |
+          If timesBuilt > 1, whether some builds did not produce the same result.
+
+          Note that 'isNonDeterministic = false' does not mean the build is deterministic,
+          just that we don't have evidence of non-determinism.

doc/manual/source/protocols/json/schema/build-trace-entry-v1

@@ -0,0 +1 @@
+../../../../../../src/libstore-tests/data/realisation

doc/manual/source/protocols/json/schema/build-trace-entry-v1.yaml

@@ -0,0 +1,74 @@
+"$schema": "http://json-schema.org/draft-04/schema"
+"$id": "https://nix.dev/manual/nix/latest/protocols/json/schema/build-trace-entry-v1.json"
+title: Build Trace Entry
+description: |
+  A record of a successful build outcome for a specific derivation output.
+
+  This schema describes the JSON representation of a [build trace entry](@docroot@/store/build-trace.md) entry.
+
+  > **Warning**
+  >
+  > This JSON format is currently
+  > [**experimental**](@docroot@/development/experimental-features.md#xp-feature-ca-derivations)
+  > and subject to change.
+
+type: object
+required:
+  - id
+  - outPath
+  - dependentRealisations
+  - signatures
+properties:
+  id:
+    type: string
+    title: Derivation Output ID
+    pattern: "^sha256:[0-9a-f]{64}![a-zA-Z_][a-zA-Z0-9_-]*$"
+    description: |
+      Unique identifier for the derivation output that was built.
+
+      Format: `{hash-quotient-drv}!{output-name}`
+
+      - **hash-quotient-drv**: SHA-256 [hash of the quotient derivation](@docroot@/store/derivation/outputs/input-address.md#hash-quotient-drv).
+        Begins with `sha256:`.
+
+      - **output-name**: Name of the specific output (e.g., "out", "dev", "doc")
+
+      Example: `"sha256:ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad!foo"`
+
+  outPath:
+    "$ref": "store-path-v1.yaml"
+    title: Output Store Path
+    description: |
+      The path to the store object that resulted from building this derivation for the given output name.
+
+  dependentRealisations:
+    type: object
+    title: Underlying Base Build Trace
+    description: |
+      This is for [*derived*](@docroot@/store/build-trace.md#derived) build trace entries to ensure coherence.
+
+      Keys are derivation output IDs (same format as the main `id` field).
+      Values are the store paths that those dependencies resolved to.
+
+      As described in the linked section on derived build trace traces, derived build trace entries must be kept in addition and not instead of the underlying base build entries.
+      This is the set of base build trace entries that this derived build trace is derived from.
+      (The set is also a map since this miniature base build trace must be coherent, mapping each key to a single value.)
+
+    patternProperties:
+      "^sha256:[0-9a-f]{64}![a-zA-Z_][a-zA-Z0-9_-]*$":
+        $ref: "store-path-v1.yaml"
+        title: Dependent Store Path
+        description: Store path that this dependency resolved to during the build
+    additionalProperties: false
+
+  signatures:
+    type: array
+    title: Build Signatures
+    description: |
+      A set of cryptographic signatures attesting to the authenticity of this build trace entry.
+    items:
+      type: string
+      title: Signature
+      description: A single cryptographic signature
+
+additionalProperties: false

doc/manual/source/store/build-trace.md

@@ -29,7 +29,7 @@ And even in that case, a different result doesn't mean the original entry was a
 As such, the decision of whether to trust a counterparty's build trace is a fundamentally subject policy choice.
 Build trace entries are typically *signed* in order to enable arbitrary public-key-based trust polices.
 
-## Derived build traces
+## Derived build traces {#derived}
 
 Implementations that wish to memoize the above may also keep additional *derived* build trace entries that do map unresolved derivations.
 But if they do so, they *must* also keep the underlying base entries with resolved derivation keys around.

src/json-schema-checks/build-result

@@ -0,0 +1 @@
+../../src/libstore-tests/data/build-result

src/json-schema-checks/build-trace-entry

@@ -0,0 +1 @@
+../../src/libstore-tests/data/realisation

src/json-schema-checks/meson.build

@@ -54,6 +54,15 @@ schemas = [
       'single_built_built.json',
     ],
   },
+  {
+    'stem' : 'build-trace-entry',
+    'schema' : schema_dir / 'build-trace-entry-v1.yaml',
+    'files' : [
+      'simple.json',
+      'with-dependent-realisations.json',
+      'with-signature.json',
+    ],
+  },
 ]
 
 # Derivation and Derivation output
@@ -141,6 +150,15 @@ schemas += [
       'impure.json',
     ],
   },
+  {
+    'stem' : 'build-result',
+    'schema' : schema_dir / 'build-result-v1.yaml',
+    'files' : [
+      'success.json',
+      'output-rejected.json',
+      'not-deterministic.json',
+    ],
+  },
   # Match exact variant
   {
     'stem' : 'store-object-info',

src/json-schema-checks/package.nix

@@ -23,10 +23,12 @@ mkMesonDerivation (finalAttrs: {
     ../../src/libutil-tests/data/hash
     ../../src/libstore-tests/data/content-address
     ../../src/libstore-tests/data/store-path
+    ../../src/libstore-tests/data/realisation
     ../../src/libstore-tests/data/derivation
     ../../src/libstore-tests/data/derived-path
     ../../src/libstore-tests/data/path-info
     ../../src/libstore-tests/data/nar-info
+    ../../src/libstore-tests/data/build-result
     ./.
   ];