whitepaper v2: Section 4 — Embedded Provenance (~2,000 words)
Some checks failed
Deploy Landing Page to Storj / deploy (push) Failing after 2s
Some checks failed
Deploy Landing Page to Storj / deploy (push) Failing after 2s
Covers: supply chain blind spot problem, provenance-by-construction approach, PROV-O audit trail (Turtle example), CycloneDX SBOM (JSON example), SPDX license metadata (JSON example), NIST SA-11 control mapping, 5 design implications of provenance as first-class compiler concern.
This commit is contained in:
Scott Scoble
parent
fa896dec77
commit
322d54781a
1 changed files with 137 additions and 1 deletions
|
|
@ -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: <http://www.w3.org/ns/prov#> .
|
||||
@prefix speckl: <https://speckl.io/ns#> .
|
||||
|
||||
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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue