import{_ as t,o as a,c as i,ag as n}from"./chunks/framework.CmQHR1bQ.js";const u=JSON.parse('{"title":"ADR-001: Headless Artifact Compiler vs SaaS Integration","description":"","frontmatter":{},"headers":[],"relativePath":"adr/ADR-002-headless-artifact-compiler.md","filePath":"adr/ADR-002-headless-artifact-compiler.md"}'),r={name:"adr/ADR-002-headless-artifact-compiler.md"};function s(o,e,l,d,c,p){return a(),i("div",null,[...e[0]||(e[0]=[n(`<h1 id="adr-001-headless-artifact-compiler-vs-saas-integration" tabindex="-1">ADR-001: Headless Artifact Compiler vs SaaS Integration <a class="header-anchor" href="#adr-001-headless-artifact-compiler-vs-saas-integration" aria-label="Permalink to &quot;ADR-001: Headless Artifact Compiler vs SaaS Integration&quot;">​</a></h1><p><strong>date:</strong> 2026-02-21 <strong>status:</strong> ACCEPTED <strong>decision:</strong> Build headless artifact compiler (in-process IR rendering) rather than integrate third-party SaaS</p><hr><h2 id="context" tabindex="-1">Context <a class="header-anchor" href="#context" aria-label="Permalink to &quot;Context&quot;">​</a></h2><h3 id="problem" tabindex="-1">Problem <a class="header-anchor" href="#problem" aria-label="Permalink to &quot;Problem&quot;">​</a></h3><p>Venture needs to generate production artifacts (slides, documents, timelines, audio scripts, org charts) as part of autonomous agent workflows. Three options were evaluated:</p><ol><li><strong>Headless Compiler</strong> (in-process): IR schema → render → export pipeline, deterministic, full ownership</li><li><strong>SaaS Integration</strong> (external): Third-party API (Canva, Figma, etc.), easier UX but less control</li><li><strong>Hybrid</strong> (internal IR + optional SaaS export): IR first, SaaS as optional destination</li></ol><h3 id="constraints" tabindex="-1">Constraints <a class="header-anchor" href="#constraints" aria-label="Permalink to &quot;Constraints&quot;">​</a></h3><ul><li><strong>Determinism</strong>: Artifact builds must be reproducible (same input → same hash)</li><li><strong>Autonomy</strong>: No human-in-the-loop during agent execution</li><li><strong>Auditability</strong>: Full artifact lineage (IR → provenance metadata → output)</li><li><strong>Multi-artifact</strong>: Must support 5+ artifact types (slides, docs, timelines, audio, boards)</li><li><strong>Compliance</strong>: Treasury integration means spend tracking and policy enforcement per artifact</li></ul><h3 id="alternatives-considered" tabindex="-1">Alternatives Considered <a class="header-anchor" href="#alternatives-considered" aria-label="Permalink to &quot;Alternatives Considered&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Option</th><th>Pros</th><th>Cons</th><th>Decision</th></tr></thead><tbody><tr><td><strong>Headless</strong></td><td>Deterministic, full control, no external deps, auditability, policy-native</td><td>Build complexity, design effort, schema freeze required</td><td>✅ CHOSEN</td></tr><tr><td><strong>SaaS Integration</strong></td><td>Easy UX, pre-built designs, no render engine</td><td>Non-deterministic, vendor lock-in, slower, harder to audit</td><td>❌ REJECTED</td></tr><tr><td><strong>Hybrid</strong></td><td>Best of both</td><td>Complexity, dual maintenance, mixed control</td><td>⚠️ FUTURE OPTION</td></tr></tbody></table><hr><h2 id="decision" tabindex="-1">Decision <a class="header-anchor" href="#decision" aria-label="Permalink to &quot;Decision&quot;">​</a></h2><p><strong>Build a headless artifact compiler</strong> as the primary artifact generation subsystem.</p><h3 id="what-this-means" tabindex="-1">What This Means <a class="header-anchor" href="#what-this-means" aria-label="Permalink to &quot;What This Means&quot;">​</a></h3><ol><li><strong>IR Schema Family Frozen</strong>: SlideSpec, DocSpec, TimelineSpec, AudioSpec, BoardSpec (v1.0) locked in ARTIFACT_COMPILER_SPEC.md</li><li><strong>Deterministic Build Pipeline</strong>: Input schema → render engine → output file with provenance metadata</li><li><strong>No External Render SaaS</strong>: Canva, Figma, etc. are not integrated as primary targets</li><li><strong>Native Cost Tracking</strong>: Each artifact build emits spend events tied to TRACK_B treasury system</li><li><strong>Replay Guarantee</strong>: Same IR + render version → identical output byte-for-byte (for archive/audit)</li></ol><h3 id="architecture" tabindex="-1">Architecture <a class="header-anchor" href="#architecture" aria-label="Permalink to &quot;Architecture&quot;">​</a></h3><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>Artifact Request</span></span>
<span class="line"><span>  ↓</span></span>
<span class="line"><span>[IR Schema Validation]</span></span>
<span class="line"><span>  ↓</span></span>
<span class="line"><span>[Render Engine Dispatch]</span></span>
<span class="line"><span>  ├─ SlideSpec → PDF/PNG renderer</span></span>
<span class="line"><span>  ├─ DocSpec → HTML/Markdown renderer</span></span>
<span class="line"><span>  ├─ TimelineSpec → SVG/JSON renderer</span></span>
<span class="line"><span>  ├─ AudioSpec → SSML → audio encoder</span></span>
<span class="line"><span>  └─ BoardSpec → SVG/PNG renderer</span></span>
<span class="line"><span>  ↓</span></span>
<span class="line"><span>[Provenance Attachment] (hash, timestamp, render version, trace_id)</span></span>
<span class="line"><span>  ↓</span></span>
<span class="line"><span>[Output Export] (blob store + ledger entry)</span></span>
<span class="line"><span>  ↓</span></span>
<span class="line"><span>[Spend Event] (tied to TRACK_B)</span></span></code></pre></div><h3 id="renderer-implementations" tabindex="-1">Renderer Implementations <a class="header-anchor" href="#renderer-implementations" aria-label="Permalink to &quot;Renderer Implementations&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Artifact Type</th><th>Renderer</th><th>Output Format</th><th>Notes</th></tr></thead><tbody><tr><td>SlideSpec</td><td>Custom (Python/Go)</td><td>PDF, PNG</td><td>Deterministic typography via embedded fonts</td></tr><tr><td>DocSpec</td><td>Markdown → HTML</td><td>HTML, Markdown</td><td>Standard Markdown rendering</td></tr><tr><td>TimelineSpec</td><td>SVG templating</td><td>SVG, PNG</td><td>Deterministic layout via constraint solver</td></tr><tr><td>AudioSpec</td><td>SSML → TTS</td><td>WAV, MP3</td><td>Deterministic via fixed TTS provider + pitch/speed params</td></tr><tr><td>BoardSpec</td><td>Canvas rendering</td><td>SVG, PNG</td><td>Deterministic grid-based layout</td></tr></tbody></table><hr><h2 id="rationale" tabindex="-1">Rationale <a class="header-anchor" href="#rationale" aria-label="Permalink to &quot;Rationale&quot;">​</a></h2><h3 id="why-headless-not-saas" tabindex="-1">Why Headless, Not SaaS? <a class="header-anchor" href="#why-headless-not-saas" aria-label="Permalink to &quot;Why Headless, Not SaaS?&quot;">​</a></h3><ol><li><strong>Determinism</strong>: Critical for compliance and audit. SaaS APIs drift (UI changes, version upgrades); headless IR+renderer stays frozen.</li><li><strong>Autonomy</strong>: No rate limits, no external approval gates, no async callback dependencies.</li><li><strong>Cost Control</strong>: Spend is deterministic and predictable; no surprise API charges.</li><li><strong>Audit Readiness</strong>: Full lineage (agent → IR → render → output → ledger entry); SaaS integration breaks this chain.</li><li><strong>Integration with TRACK_B</strong>: Directly emits spend events; SaaS integration would require translation layer.</li></ol><h3 id="why-not-saas-later" tabindex="-1">Why Not SaaS Later? <a class="header-anchor" href="#why-not-saas-later" aria-label="Permalink to &quot;Why Not SaaS Later?&quot;">​</a></h3><p>SaaS integration remains a <strong>future option</strong> (see ADR-NNN-SaaS-export-targets):</p><ul><li>Once headless IR is stable, can export SlideSpec → Canva design (one-way)</li><li>Canva becomes optional <strong>destination</strong>, not primary generation mechanism</li><li>Users get &quot;polish in SaaS&quot; only if they explicitly opt in post-generation</li></ul><hr><h2 id="consequences" tabindex="-1">Consequences <a class="header-anchor" href="#consequences" aria-label="Permalink to &quot;Consequences&quot;">​</a></h2><h3 id="positive" tabindex="-1">Positive <a class="header-anchor" href="#positive" aria-label="Permalink to &quot;Positive&quot;">​</a></h3><ol><li>✅ Deterministic artifact generation (Foundation for TRACK_A)</li><li>✅ Native integration with spend tracking (TRACK_B treasury)</li><li>✅ Full auditability from agent intent → artifact → ledger</li><li>✅ No external API dependencies or rate limits</li><li>✅ Schema freezing enables long-term replay guarantees</li><li>✅ Simpler control plane (no async callback state)</li></ol><h3 id="negative" tabindex="-1">Negative <a class="header-anchor" href="#negative" aria-label="Permalink to &quot;Negative&quot;">​</a></h3><ol><li>❌ <strong>Rendering complexity</strong>: Must build/maintain 5 specialized renderers</li><li>❌ <strong>Design sophistication</strong>: Headless outputs may look less polished than SaaS-native</li><li>❌ <strong>Typography lock-in</strong>: Fonts and styling frozen at v1.0; no easy updates</li><li>❌ <strong>Learning curve</strong>: Agents must learn IR schema (vs. native SaaS design tools)</li></ol><h3 id="mitigation" tabindex="-1">Mitigation <a class="header-anchor" href="#mitigation" aria-label="Permalink to &quot;Mitigation&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Risk</th><th>Mitigation</th></tr></thead><tbody><tr><td>Rendering complexity</td><td>Use established libraries (reportlab, drawsvg, etc.); build incrementally (Phase 2 only DocSpec, Phase 3 add SlideSpec, etc.)</td></tr><tr><td>Design sophistication</td><td>Accept v1 outputs as &quot;functional not beautiful&quot;; SaaS export option in v2 for polish</td></tr><tr><td>Typography lock-in</td><td>Freeze fonts and styles at v1.0; document constraints clearly; separate design v2 work into future ADR</td></tr><tr><td>Agent learning</td><td>Provide agent library with IR builders; auto-suggest IR fields based on context</td></tr></tbody></table><hr><h2 id="civ-integration-notes" tabindex="-1">CIV Integration Notes <a class="header-anchor" href="#civ-integration-notes" aria-label="Permalink to &quot;CIV Integration Notes&quot;">​</a></h2><h3 id="civ-→-venture-artifact-export-integration-point-1" tabindex="-1">CIV → Venture Artifact Export (Integration Point 1) <a class="header-anchor" href="#civ-→-venture-artifact-export-integration-point-1" aria-label="Permalink to &quot;CIV → Venture Artifact Export (Integration Point 1)&quot;">​</a></h3><p>This decision enables a key integration point with CIV:</p><p><strong>CIV simulation outputs can become Venture artifacts:</strong></p><ul><li>CIV time-series (population, economy, energy) → TimelineSpec</li><li>CIV policy decisions → DocSpec</li><li>CIV org hierarchy → BoardSpec</li><li>CIV citizen journeys → combination of SlideSpec + TimelineSpec</li></ul><p><strong>Alignment:</strong></p><ul><li>CIV&#39;s tick-based state → Venture&#39;s IR snapshot</li><li>Deterministic artifact generation mirrors CIV&#39;s deterministic simulation</li><li>Spend tracking (Venture) can model &quot;cost of visualization&quot; in CIV&#39;s energy accounting</li></ul><h3 id="replay-guarantee-integration-point-5" tabindex="-1">Replay Guarantee (Integration Point 5) <a class="header-anchor" href="#replay-guarantee-integration-point-5" aria-label="Permalink to &quot;Replay Guarantee (Integration Point 5)&quot;">​</a></h3><p>Headless compiler enables CIV-Venture replay:</p><ul><li>Same CIV tick snapshot → same IR → same artifact bytes</li><li>Supports auditing CIV decisions: &quot;what policy decisions led to this artifact?&quot;</li></ul><hr><h2 id="validation-next-steps" tabindex="-1">Validation &amp; Next Steps <a class="header-anchor" href="#validation-next-steps" aria-label="Permalink to &quot;Validation &amp; Next Steps&quot;">​</a></h2><h3 id="validation-criteria-before-phase-1-starts" tabindex="-1">Validation Criteria (Before Phase 1 Starts) <a class="header-anchor" href="#validation-criteria-before-phase-1-starts" aria-label="Permalink to &quot;Validation Criteria (Before Phase 1 Starts)&quot;">​</a></h3><ul><li>[ ] SlideSpec and DocSpec IR schemas frozen and validated against rendering constraints</li><li>[ ] Prototype renderers confirm determinism (byte-for-byte reproducibility tested)</li><li>[ ] Provenance metadata schema defined and integrated with TRACK_B ledger</li><li>[ ] Cost model for rendering (compute per artifact type) defined</li><li>[ ] Agent library for IR builders designed and approved</li></ul><h3 id="phase-milestones" tabindex="-1">Phase Milestones <a class="header-anchor" href="#phase-milestones" aria-label="Permalink to &quot;Phase Milestones&quot;">​</a></h3><ol><li><strong>Phase 1</strong> (Foundation): DocSpec renderer + IR schema validation</li><li><strong>Phase 2</strong> (Expansion): SlideSpec + TimelineSpec renderers</li><li><strong>Phase 3</strong> (Audio+Board): AudioSpec + BoardSpec renderers</li><li><strong>Phase 4</strong> (Optimization): Performance, caching, incremental builds</li><li><strong>Phase 5</strong> (SaaS Bridge): Optional export targets (future ADR)</li></ol><h3 id="related-adrs" tabindex="-1">Related ADRs <a class="header-anchor" href="#related-adrs" aria-label="Permalink to &quot;Related ADRs&quot;">​</a></h3><ul><li>ADR-002: Joule-Treasury integration (spend tracking for artifacts)</li><li>ADR-NNN: SaaS export targets (future, v2+)</li><li>ADR-NNN: Typography v2 upgrade (future, if design debt accrues)</li></ul><hr><h2 id="references" tabindex="-1">References <a class="header-anchor" href="#references" aria-label="Permalink to &quot;References&quot;">​</a></h2><ul><li><strong>Artifact Compiler Spec</strong>: <code>ARTIFACT_COMPILER_SPEC.md</code></li><li><strong>Track A Determinism Spec</strong>: <code>TRACK_A_ARTIFACT_DETERMINISM_SPEC.md</code></li><li><strong>Product Model</strong>: <code>PRODUCT_MODEL.md</code> (artifact generation as core feature)</li><li><strong>Integration Points</strong>: <code>../SPECS_INDEX.md</code> (Integration Point 1: CIV artifact export)</li></ul><hr><p><strong>Decision Made By:</strong> Venture Autonomy Platform Team <strong>Implementation Lead:</strong> TBD <strong>Last Updated:</strong> 2026-02-21</p>`,59)])])}const g=t(r,[["render",s]]);export{u as __pageData,g as default};
