diff --git a/docs/whitepaper-v2.md b/docs/whitepaper-v2.md index f15d9a5..1e6cd39 100644 --- a/docs/whitepaper-v2.md +++ b/docs/whitepaper-v2.md @@ -622,7 +622,143 @@ The compiler architecture reflects several deliberate choices: ## 4. Embedded Provenance -*[Section 4: PROV-O generation, provenance graph structure, audit trail semantics]* +Every speck compilation produces three machine-readable provenance artifacts alongside the executable output. This isn't an afterthought or a bolt-on — provenance is a first-class output of the Speckl compiler, generated from the same AST as the code. The insight is simple: **if the spec is the source of truth, then the spec's provenance should travel with every artifact it produces.** + +### 4.1 The Supply Chain Blind Spot + +Modern software supply chains are opaque. Most organizations cannot answer basic questions about their dependencies: + +- Who authored this specification, and when? +- What tools generated this code? +- What was the chain of custody from requirement to deployment? + +Regulations like Executive Order 14028, NIST SP 800-218 (SSDF), and the EU Cyber Resilience Act now require software producers to provide attestations about their build processes. But existing tools treat provenance as a separate workflow — something you bolt on after compilation. This creates a verification gap: how do you know the SBOM actually describes the software you're running? + +### 4.2 Provenance by Construction + +Speckl inverts this model. Because the compiler operates on a single, unambiguous source (the `.speck` file), it can generate provenance artifacts at compile time that are **guaranteed to be accurate** — not best-effort metadata added later, but mechanically derived from the code's single source of truth. + +Every `speckl compile` invocation produces three provenance artifacts: + +| Artifact | Format | Purpose | Standard | +|----------|--------|---------|----------| +| `*.prov.ttl` | Turtle (RDF) | Audit trail — who, what, when, how | W3C PROV-O | +| `*.cdx.json` | JSON | Software bill of materials | OWASP CycloneDX 1.4 | +| `*.spdx.json` | JSON | License + supplier metadata | SPDX 2.3 | + +These three formats serve different stakeholders: + +- **PROV-O** answers "what happened?" — auditors and compliance officers +- **CycloneDX** answers "what's inside?" — security teams and vulnerability scanners +- **SPDX** answers "who owns it?" — legal teams and procurement + +### 4.3 PROV-O: The Audit Trail + +The PROV-O artifact records the compilation event as a W3C-compliant provenance graph. It captures: + +```turtle +@prefix prov: . +@prefix speckl: . + +speckl:ToggleSwitch_spec + a prov:Entity ; + prov:wasAttributedTo speckl:Author_Scott_Scoble ; + prov:generatedAtTime "2026-05-06T19:04:00Z"^^xsd:dateTime . + +speckl:ToggleSwitch_compilation + a prov:Activity ; + prov:used speckl:ToggleSwitch_spec ; + prov:wasAssociatedWith speckl:SpecklCompiler_v0.3.1 ; + prov:endedAtTime "2026-05-06T19:04:01Z"^^xsd:dateTime . + +speckl:ToggleSwitch_typescript + a prov:Entity ; + prov:wasGeneratedBy speckl:ToggleSwitch_compilation ; + prov:wasDerivedFrom speckl:ToggleSwitch_spec . +``` + +Each generated artifact (TypeScript, WASM, CycloneDX, SPDX) becomes a prov:Entity with a `wasDerivedFrom` relationship to the original spec. This creates a verifiable chain of custody: given any artifact, you can trace it back through the compilation event to the spec and its author. + +### 4.4 CycloneDX: The Software Bill of Materials + +The CycloneDX artifact describes what's inside the compiled output — its dependency graph in machine-readable form: + +```json +{ + "bomFormat": "CycloneDX", + "specVersion": "1.4", + "metadata": { + "component": { + "type": "application", + "name": "ToggleSwitch", + "description": "State machine compiled from SpeckDL specification", + "purl": "pkg:speckl/ToggleSwitch@0.1.0" + }, + "tools": [{ + "name": "speckl-compile", + "vendor": "speckl.io", + "version": "0.3.1" + }] + }, + "components": [ + {"type": "library", "name": "speckl-runtime", "version": "0.3.1"}, + {"type": "library", "name": "typescript", "version": "5.x"} + ] +} +``` + +This can be fed directly into vulnerability scanners (Dependency-Track, Grype, Trivy) for continuous monitoring. The `purl` (Package URL) identifies the component uniquely across ecosystems, and the metadata records the exact compiler version used — essential for reproducibility and audit. + +### 4.5 SPDX: License and Supplier Metadata + +The SPDX artifact addresses the licensing and distribution side of supply chain compliance: + +```json +{ + "spdxVersion": "SPDX-2.3", + "dataLicense": "CC0-1.0", + "name": "ToggleSwitch", + "packages": [{ + "name": "ToggleSwitch", + "supplier": "Organization: Speckl", + "originator": "Person: Scott Scoble", + "licenseDeclared": "MIT", + "copyrightText": "Copyright 2026 Speckl Contributors", + "externalRefs": [{ + "referenceCategory": "PACKAGE-MANAGER", + "referenceType": "purl", + "referenceLocator": "pkg:speckl/ToggleSwitch@0.1.0" + }] + }] +} +``` + +SPDX is the lingua franca of open-source license compliance. Tools like FOSSA, OSS Review Toolkit, and ClearlyDefined ingest SPDX for automated policy enforcement. + +### 4.6 The NIST SA-11 Connection + +NIST SP 800-53 Revision 5 introduced control **SA-11: Developer Testing and Evaluation**, which requires organizations to address "supply chain risks" and produce "evidence of correct implementation" for automated code generation tools. Speckl's provenance-by-construction approach directly satisfies this control: + +- **SA-11(2): Threat Modeling and Vulnerability Analysis** — CycloneDX SBOM enables vulnerability scanning +- **SA-11(4): Manual Code Review** — PROV-O audit trail establishes chain of custody for review +- **SA-11(6): Attack Surface Review** — SPDX license metadata supports supply chain risk assessment +- **SA-11(7): Verify Scope of Testing** — All 5 artifacts share a single compilation event, verifiable via PROV-O + +This is the "judgement transport" value proposition: Speckl doesn't just produce code — it produces **evidence** that a human reviewer can use to make informed judgements about what was generated and why. + +### 4.7 Provenance as a First-Class Concern + +The design decision to make provenance a compiler pass, not a post-hoc step, has practical implications: + +1. **Zero-configuration.** Every `speckl compile` produces all 5 artifacts. No additional tooling, no CI plugin, no configuration file. + +2. **Guaranteed consistency.** The CycloneDX SBOM describes exactly the same code as the TypeScript and WASM output — because they all came from the same AST traversal. There is no possibility of drift. + +3. **Auditability.** Any artifact can be traced back to a specific point in time, a specific compiler version, and a specific author. The provenance is deterministic and reproducible. + +4. **Regulatory readiness.** Organizations in defense, healthcare, finance, and critical infrastructure can generate compliance evidence as a byproduct of their normal development workflow. + +5. **No vendor lock-in.** PROV-O, CycloneDX, and SPDX are open standards. The provenance data is portable and can be consumed by any compliant tool. ## 5. Consensus Protocols in SpeckDL