Artifact Contracts

The artifact layer is the first product contract. It lets the runner, API, dashboard, and audit reports evolve without coupling the web app directly to DocPull or PolicyStrata internals.

Compatibility rule

Consumers must tolerate unknown fields. Producers should prefer additive changes and only bump schema versions for breaking changes.

Files

File	Meaning
`schemas/assurance-run.schema.json`	One runner execution for one project/release candidate
`schemas/context-finding.schema.json`	Normalized DocPull/context issue
`schemas/policy-finding.schema.json`	Normalized PolicyStrata/policy issue
`schemas/evidence-pack.schema.json`	Reviewable release evidence bundle

Required Run Fields

schemaVersion: semantic schema version, starting at 0.1.0.
runId: stable run identifier from the runner or CI system.
project: project slug/name.
status: passed, failed, blocked, or needs_review.
tools: DocPull and PolicyStrata versions used.
inputs: named source sets, policy suites, and trace sets.
findings: normalized context and policy findings.

Severity Semantics

Severity	Release meaning
`info`	Non-blocking signal
`warning`	Review recommended
`fail`	Release should not ship without remediation or waiver

Evidence Pack Shape

Evidence packs should be reviewable without requiring raw customer data in the hosted app.

evidence-pack.schema.json

{
  "packId": "pack_demo_saas_bi_20260706",
  "schemaVersion": "0.1.0",
  "status": "blocked",
  "runRefs": ["run_demo_saas_bi_20260706"],
  "summary": {
    "release": "blocked before production",
    "blockers": ["tenant_scope_required"]
  },
  "artifacts": [
    {
      "name": "assurance-run.demo.json",
      "sha256": "..."
    }
  ]
}

Compatibility Rules

Additive fields are preferred.
Breaking changes require a schema version bump.
Dashboard code should tolerate unknown fields.
Runner output should validate before upload.