Planning and stage-contract types

Pipeline-emitted planning, diagnostics, and stage-manifest contracts.

Back to the reference overview.

Type index

• CheckReportV1 — Machine-readable result of site-pipeline check.
• CheckSummary — Outcome counts and pass/fail decision for one check run.
• CliDiagnostic — Structured operator-facing failure without internal exception details.
• CliDiagnosticIssue — One bounded, actionable detail attached to a CLI failure.
• CliFailureReportV1 — Stable JSON envelope emitted when no command report can be produced.
• PipelineDiagnosticEntry — Structured diagnostic emitted during planning, checking, or staging.
• ReducedDiagnosticDetailsSummary — Compact placeholder used when full diagnostic details were too large to keep.
• ResolvedMaterializationEntry — One local checkout or fetched input that the planner expects to exist.
• ResolvedMaterializationReportV1 — Machine-readable planning report for required local inputs.
• StageDataFiles — Stage-relative paths of aggregate metadata files currently present in one stage tree.
• StageManifestV1 — Authoritative entry-point document for a staged output tree.
• StageRoots — Named top-level directories inside a stage tree.
• StageRunReportV1 — Machine-readable result of build or one completed watch cycle.
• StageRunSummary — Outcome counts and usability flags for one stage-producing run or watch cycle.

CheckReportV1

Machine-readable result of site-pipeline check.

• category: emitted
• ownership: pipeline-derived
• file contract: (inner type)

Example: Validation report with one warning that does not fail the run.

 1{
 2  "schemaVersion": 1,
 3  "generatedAt": "2026-04-06T08:35:00Z",
 4  "command": "check",
 5  "summary": {
 6    "status": "warnings",
 7    "passed": true,
 8    "failOnSeverity": "error",
 9    "errorCount": 0,
10    "warningCount": 1,
11    "infoCount": 0
12  },
13  "diagnostics": [
14    {
15      "severity": "warning",
16      "code": "catalog.redirectReasonMissing",
17      "message": "Redirect /spark/docs/current/ has no reader-facing reason.",
18      "componentSlug": "spark",
19      "targetId": "/spark/docs/current/"
20    }
21  ]
22}

CheckSummary

Outcome counts and pass/fail decision for one check run.

• category: emitted
• ownership: pipeline-derived
• file contract: (inner type)

CliDiagnostic

Structured operator-facing failure without internal exception details.

• category: emitted
• ownership: pipeline-derived
• file contract: (inner type)

Selected field examples

• code: Example: "input-validation-failed"
• source: Example: "site/catalog.yaml"

CliDiagnosticIssue

One bounded, actionable detail attached to a CLI failure.

• category: emitted
• ownership: pipeline-derived
• file contract: (inner type)

Selected field examples

• location: Example: "components[0].slug"
• code: Example: "required"
• message: Example: "Field required"

CliFailureReportV1

Stable JSON envelope emitted when no command report can be produced.

• category: emitted
• ownership: pipeline-derived
• file contract: (inner type)

Example: Authored input validation failure with one actionable issue.

 1{
 2  "schemaVersion": 1,
 3  "kind": "cliFailure",
 4  "command": "check",
 5  "exitCode": 1,
 6  "error": {
 7    "category": "input",
 8    "code": "input-validation-failed",
 9    "message": "Document does not satisfy its schema",
10    "source": "site/catalog.yaml",
11    "issues": [
12      {
13        "location": "components[0].slug",
14        "code": "required",
15        "message": "Field required"
16      }
17    ],
18    "omittedIssueCount": 0
19  }
20}

PipelineDiagnosticEntry

Structured diagnostic emitted during planning, checking, or staging.

• category: emitted
• ownership: pipeline-derived
• file contract: (inner type)

Selected field examples

• code: Example: "catalog.invalidRedirectTarget"
• message: Example: "Redirect target route:/spark/missing/ could not be resolved."
• componentSlug: Example: "spark"
• artifactKey: Example: "runtime"
• targetId: Example: "/spark/docs/current/"

ReducedDiagnosticDetailsSummary

Compact placeholder used when full diagnostic details were too large to keep.

• category: emitted
• ownership: pipeline-derived
• file contract: (inner type)

Selected field examples

• actualBytes: Example: 524288
• limitBytes: Example: 65536

ResolvedMaterializationEntry

One local checkout or fetched input that the planner expects to exist.

• category: emitted
• ownership: pipeline-derived
• file contract: (inner type)

Selected field examples

• sourceKey: Example: "apache-spark"
• componentSlug: Example: "spark"
• artifactKey: Example: "runtime"
• releaseLine: Example: "4.0"
• version: Example: "4.0.0"
• ref: Example: "refs/heads/main"
• tag: Example: "v4.0.0"
• commitSha: Example: "6f0fd1f7b2c4a6d8e9f00123456789abcdef0123"
• expectedLocalPath: Example: ".buildish/materialized/apache-spark/main"

ResolvedMaterializationReportV1

Machine-readable planning report for required local inputs.

• category: emitted
• ownership: pipeline-derived
• file contract: (inner type)

Example: Planning report with one required release checkout.

 1{
 2  "schemaVersion": 1,
 3  "generatedAt": "2026-04-06T08:30:00Z",
 4  "target": "build",
 5  "entries": [
 6    {
 7      "sourceKey": "apache-spark",
 8      "inputKind": "released",
 9      "componentSlug": "spark",
10      "artifactKey": "runtime",
11      "version": "4.0.0",
12      "tag": "v4.0.0",
13      "expectedLocalPath": ".buildish/materialized/apache-spark/v4.0.0",
14      "status": "present",
15      "watchEligible": false,
16      "reason": "Release docs are staged from the release tag checkout."
17    }
18  ],
19  "diagnostics": []
20}

StageDataFiles

Stage-relative paths of aggregate metadata files currently present in one stage tree.

• category: emitted
• ownership: pipeline-derived
• file contract: (inner type)

Selected field examples

• components: Example: "data/components.json"
• artifacts: Example: "data/artifacts.json"
• routes: Example: "data/routes.json"
• redirects: Example: "data/redirects.json"
• releases: Example: "data/releases.json"
• candidates: Example: "data/candidates.json"
• refs: Example: "data/refs.json"
• translations: Example: "data/translations.json"
• compatibility: Example: "data/compatibility.json"
• mounts: Example: "data/mounts.json"
• providers: Example: "data/providers.json"
• contentIndex: Example: "data/content-index.json"
• diagnostics: Example: "data/diagnostics.json"
• unitContributions: Example: "data/unit-contributions.json"
• outputOwnership: Example: "data/output-ownership.json"
• aggregateDependencies: Example: "data/aggregate-dependencies.json"

StageManifestV1

Authoritative entry-point document for a staged output tree.

• category: emitted
• ownership: pipeline-derived
• file contract: manifest.json

Example: Stage manifest that points at content, static, and aggregate roots.

 1{
 2  "schemaVersion": 1,
 3  "stageLayoutVersion": 1,
 4  "generatedAt": "2026-04-06T08:40:00Z",
 5  "command": "build",
 6  "frontMatterFormat": "yaml",
 7  "aggregateFormat": "json",
 8  "roots": {
 9    "content": "content",
10    "static": "static",
11    "data": "data"
12  },
13  "dataFiles": {
14    "components": "data/components.json",
15    "artifacts": "data/artifacts.json",
16    "routes": "data/routes.json",
17    "redirects": "data/redirects.json",
18    "releases": "data/releases.json",
19    "refs": "data/refs.json",
20    "contentIndex": "data/content-index.json"
21  }
22}

StageRoots

Named top-level directories inside a stage tree.

• category: emitted
• ownership: pipeline-derived
• file contract: (inner type)

Selected field examples

• content: Example: "content"
• static: Example: "static"
• data: Example: "data"

StageRunReportV1

Machine-readable result of build or one completed watch cycle.

• category: emitted
• ownership: pipeline-derived
• file contract: (inner type)

Selected field examples

• cycle: Example: 3

Example: Successful build report with a usable stage manifest.

 1{
 2  "schemaVersion": 1,
 3  "generatedAt": "2026-04-06T08:40:00Z",
 4  "command": "build",
 5  "summary": {
 6    "status": "clean",
 7    "succeeded": true,
 8    "wroteStage": true,
 9    "stageUsable": true,
10    "errorCount": 0,
11    "warningCount": 0,
12    "infoCount": 2
13  },
14  "stageRootPath": ".buildish/stage/current",
15  "manifestPath": ".buildish/stage/current/manifest.json",
16  "diagnostics": []
17}

StageRunSummary

Outcome counts and usability flags for one stage-producing run or watch cycle.

• category: emitted
• ownership: pipeline-derived
• file contract: (inner type)