Skip to content

History / 07 Deployment View

Revisions

  • Eradicate \`-escape rendering artifacts: AsciiDoc {empty} boundary attribute + passthrough conversion for angle-bracket spans Root cause: AsciiDoc smart-quote substitution + Pandoc DocBook→markdown backtick-escape interaction. When an AsciiDoc inline code-span `text` is immediately followed by a trigger character (letter, ASCII apostrophe, or ASCII double-quote), Pandoc escapes the opening backtick because the smart-quote substitution makes the code-span boundary ambiguous in markdown. Result: literal `\\`text` artifacts in the rendered wiki — the closing backtick is consumed by the entity, and the opening backtick appears as `\\`` text rather than a styled code span. Two-part fix: (1) Insert AsciiDoc `{empty}` attribute substitution between the closing backtick and the trigger character via a state-machine parser (`/tmp/fix_backtick_boundary.py`). `{empty}` is a zero-width attribute that breaks the AsciiDoc/Pandoc bonding without affecting rendered output. The parser tracks opening/closing backtick pairing using AsciiDoc constrained-span rules (opening flanked by start-of- line, whitespace, or specific opening punctuation; closing flanked by non-whitespace), so it only inserts at true closing positions. Applied 462 fixes across 14 .adoc source files (12 arc42 chapters plus 2 ISO 15288 lifecycle pages). (2) Convert 6 specific AsciiDoc inline code spans containing `<...>` angle brackets to `++...++` passthrough form. AsciiDoc inline code spans wrapping content with HTML-significant characters get the angle brackets escaped through the DocBook→markdown conversion, producing literal `\\<` and `\\>` plus the opening-backtick escape. Converting these to `++...++` passthrough preserves the content verbatim (the rendered output remains code-styled monospace). Fixed spans: ADR-026 G6 (match grammar, 4 spans); glossary's first_admit + fold_n + Term::FirstAdmit grammar forms. Build pipeline preserved; all 8 validators pass on clean rebuild (vendor/arc42-generator/build/ cleared); zero `\\` artifacts remain in any of the 22 rendered wiki pages. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 15, 2026
  • ADR-035 + ADR-036 reframe: canonical k-invariants branch + ψ-residuals discipline + uniform byte-buffer resolver surface + R = NullResolverTuple default + no axes value parameter ADR-035 reframe (Block A): - Title extended: "Canonical ψ-pipeline + ψ-chain Term variants + ψ-residuals discipline on verb body composition" - Decision restructured into three coupled amendments: (1) nine ψ-Term variants, (2) canonical k-invariants branch ψ_1 → ψ_7 → ψ_8 → ψ_9 as the architectural composition for the verifiability commitment, (3) ψ-residuals discipline forbidding Term::FirstAdmit, Term::AxisInvocation, byte-comparison/concat PrimitiveOps in verb-body terms - Conceptual model paragraph: compiled binary IS the canonical circuit; data representation minimal (input bytes + κ-label); client conceptually larger than data; complete model fuses into a single reference - Closure check at verb!/prism_model! invocation extended with ψ-residuals walk - Composition example switched from `betti(homology_groups(chain_complex(nerve(input))))` to canonical `k_invariants(homotopy_groups(postnikov_tower(nerve(input))))` - Rejected alternatives 5-7 rewritten: partial-coverage / homology-branch / permit-ψ-residuals ADR-036 reframe (Block B): - PrismModel<H, B, A, R = NullResolverTuple> trait shape with R defaulting to NullResolverTuple; A: AxisTuple + Hasher bound (canonical hash axis bound) - ResolverTuple trait: drop per-category accessor methods (live in marker traits); add RESOLVER_ABSENT_DISCRIMINATOR byte const - Eight resolver traits: uniform writer-style byte-buffer surface `fn resolve(&self, input: &[u8], out: &mut [u8]) -> Result<usize, ShapeViolation>` (no typed *Record<H> returns) - resolver! macro emits all eight Has<Category>Resolver impls unconditionally (declared fields delegate; undeclared categories delegate to NullResolverTuple Null* impls) - pipeline::run_route<H, B, A, M, R>(input, resolvers: &R): five type params, no axes value parameter, all eight Has<Category>Resolver<A> bounds unconditionally - Application-side instantiation: no axes value (axis methods type-associated via <A as Hasher>::initial()) - MAX_RESOLVER_TUPLE_ARITY = 16 explicit (twice AxisTuple cap) - Replace GenericImpossibilityWitness with ShapeViolation + RESOLVER_ABSENT shape IRI + foundation-internal RESOLVER_ABSENT_DISCRIMINATOR byte - Rejected alternatives reorganized: AxisTuple-conflation / typed-records / ad-hoc-per-category-params / global / foundation-provided-impls Block C cross-references: - ADR-013 Consequences: ψ-residuals, canonical k-invariants branch, byte-buffer resolver surface, RESOLVER_ABSENT_DISCRIMINATOR - ADR-022 D4 comment block: <H, B, A: AxisTuple + Hasher, R = NullResolverTuple>; asymmetric threading rationale - ADR-022 D4 trait declaration: same shape - ADR-022 D5 run_route signature: drop axes value param, add unconditional Has<Category>Resolver<A> bounds - ADR-022 D5 forward body: run_route::<H, B, A, Self, R>(input, &resolvers) - ADR-026 G12 + TR-12 + ADR-030 closure-check: already at twenty reserved identifiers (no change) - ADR-029 fold-rule preamble: four substrate parameters; ψ-residuals discipline - ADR-029 ψ-Term fold-rules: byte-buffer resolver.resolve(input, out_buffer) signatures; KInvariants noted as canonical-branch terminal - ADR-029 variant-count statement: FirstAdmit noted as verb-body-forbidden - ADR-030 Consequences: ResolverTuple parallels AxisTuple with asymmetric threading - ADR-031 Consequences: resolver baselines parallel axis baselines Block D Section 4 + Section 8: - Strategic decision row updated: canonical k-invariants branch + ψ-residuals + R = NullResolverTuple + conceptual-model framing - Closure Across Layers paragraphs: canonical k-invariants branch + ψ-residuals + byte-buffer surface Block E glossary: - New: Canonical k-invariants branch (under C), NullResolverTuple, RESOLVER_ABSENT_DISCRIMINATOR, Resolver trait shape (under R/N), ψ-chain umbrella + ψ-residuals discipline (Greek-letter cluster) - Updates: ψ-chain resolver traits to byte-buffer surface; Has<Category>Resolver<H> to all-eight-emission pattern; PrismModel to new signature + run_route call; ResolverTuple drop per-category accessor mention; ResolverCategory annotated with ψ-stage numbers; MAX_RESOLVER_TUPLE_ARITY explicit value 16; resolver! to all-eight-emission pattern; nine Term:: variant entries annotated with canonical-branch / strictly-weaker positions Reconciliation in Sections 02/03/05/06/07/08/10 + 15288 docs: - TC-03 substitution axes table: R = NullResolverTuple default; A: AxisTuple + Hasher bound; byte-buffer signature; ψ-residuals - Section 03 author-input row: R optional with default - Section 05 pipeline component: run_route<H, B, A, M, R>(input, &resolvers) signature; no axes value param - Section 06 Scenario 1 steps 7-8: four substrate parameters, no axes value param; canonical k-invariants branch; ψ-residuals discipline - Section 07 deployment view executable: canonical resolver branch list; type-associated axis dispatch - Section 08 PrismModel trait + forward call: same shape - Section 10 QS-01: canonical-branch resolver list; byte-buffer surface; ψ-residuals - 15288 technical.adoc + technical-management.adoc: R optional with default; A: AxisTuple + Hasher; canonical k-invariants branch All 8 validators pass; Stage 5 idempotent. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 11, 2026
  • Audit-gap-closure for ADR-035/036: reconcile sections 2/3/5/6/7/8/9/10/12 + c4 + 15288 to ψ-chain Term variants and ResolverTuple substrate parameter - TC-03: ten Term variants → twenty-one (original 9 + AxisInvocation + ProjectField + FirstAdmit + nine ψ-chain) - Section 02 substitution-axes: add ResolverTuple subsection as fourth model-declaration substrate parameter per ADR-036 - Section 03 author-input row: include ResolverTuple selection - Section 05 BBV substrate trait list, prism whitebox interface, vocabulary re-exports, bridge component, pipeline component: add ResolverTuple, eight ψ-chain resolver traits, marker traits, ResolverCategory, MAX_RESOLVER_TUPLE_ARITY, resolver! macro - Section 06 Scenario 1: catamorphism step extended with all twenty-one Term variants including the ψ-chain fold-rules consulting ResolverTuple - Section 07 deployment view author's executable: include axis impls + resolver impls as monomorphized native code - Section 08 PrismModel trait signature: <H, B, A> → <H, B, A, R>; forward call updated to run_route::<H, B, A, R, Self>(input, &axes, &resolvers) - Section 09 ADR-020 Consequences + ADR-022 D4/D5/D6 Consequences: trait signature, model-author impl example, run_route signature, and reconciled rejected-alternative count for D4 - Section 10 QS-01: per-variant fold-rule recital extended with the resolver-bound and resolver-free ψ-chain variants - Section 12 glossary PrismModel entry: signature + forward call updated - Section c4 workspace.dsl: bridge component + vocabulary re-exports include ResolverTuple cluster - Section 15288 technical.adoc + technical-management.adoc: add ResolverTuple as fourth model-declaration substrate parameter alongside the three substitution axes All 8 validators pass; Stage 5 idempotence check clean. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 10, 2026
  • Split deployment views: one deployment node per view (autoLayout works) User report: 'the content is just a jumble in the center of the frame, all piled in the middle without organization and unreadable.' Root cause analysis (cumulative-transform layout audit on c4-deployment-application.svg): Outer deployment-node 1 (Application User's Execution Environment) absolute position: (-50, -50), size 707x479 Outer deployment-node 2 (Application Author's Compilation Env) absolute position: (-50, -50), size 776x479 Both top-level deployment nodes anchored at the same point. They were not stacked, not side-by-side — they were drawn on top of each other, with their inner container instances and infrastructure nodes interleaving. autoLayout (whether bare or with explicit tb/lr parameters) does not position multiple top-level deployment nodes within a single Structurizr deployment view; the JointJS-based web UI Structurizr-CLI renders through doesn't compose them. Fix: split each multi-node deployment view into one view per deployment node. autoLayout works correctly when there is exactly one top-level deployment node per view; the inner topology (container instances, infrastructure nodes, intra-node relationships) is laid out properly. Old views (2): c4-deployment-application = authorCompilation + userExecution c4-deployment-verifier = userExecution + userVerification New views (3): c4-deployment-author-compilation c4-deployment-user-execution c4-deployment-user-verification The author→user→verifier flow between environments is conveyed by the dynamic Distribute and Run view (chapter 6, scenario 4) and the prose in chapter 7. The deployment views themselves now focus on what they're best at: the internal topology of one environment. Edits: - src/c4/workspace.dsl: replaced the two old deployment views with three new single-node views, each with bare 'autoLayout'. - src/arc42/adoc/07_deployment_view.adoc: updated the image references from 2 SVGs to 3, with a short connecting paragraph pointing to the dynamic view for inter-environment flow. Layout audit on c4-deployment-author-compilation.svg (new): Outer node at (259, 143), size 2130x1179 Inner elements at (1099, 193), (1656, 262), (1099, 543), (1889, 649), (1669, 699), (309, 718), (1099, 893) All inner elements within the outer node's bbox (259, 143) → (2389, 1322); positions distinct, no overlap. Verification: ./scripts/build.sh complete; all 8 validators PASS; Stage 5 idempotence holds. Stage 4 staged 18 SVGs (was 17 — net +1 because 3 deployment views replace 2; old SVGs deleted). The other C4 SVGs in the diff are timestamp-deterministic from the prior cleanup but rebuild via the autoLayout-revert change in 4d26aeb, so their byte content shifted slightly under non-customized autoLayout — they're rendered with Structurizr's default rank/node spacing now (which produces marginally different positions than the explicit tb/lr 200-250 params). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 6, 2026
  • Rename prism-sdk → prism + canonical UOR-address surface (ADR-017) Two architectural changes on top of 063d0ac: 1. Crate rename: prism-sdk → prism. Symmetric with uor-foundation (no -sdk suffix on either). prism-verify stays separate to preserve ADR-005's verifier-minimal-surface property. The Prism repo continues publishing both prism and prism-verify. 2. Canonical UOR-address surface (ADR-017). prism's standard library types are canonical UOR-address mappings: each standard type's IRI is content-deterministic in its constraint declaration; two applications using the same standard type produce values addressing identically. Closure under uor-foundation (ADR-013) makes the canonicality hold derivatively rather than via a claimed namespace. The catalog stays in prism's crate documentation; the wiki commits to canonicality, not to a specific catalog. Rename mechanics: - 282+ occurrences of prism-sdk → prism across all 12 chapters - workspace.dsl: softwareSystem identifier prism → prismSystem (the container needed the prism identifier, and Structurizr DSL requires identifiers be unique workspace-wide) - workspace.dsl: container prismSdk → prism - workspace.dsl deployment instances: prismSdkDep → prismDep prismSdkLinked → prismLinked prismSdkVerifyLinked → prismLinkedInVerify (avoids clash with the existing prismVerifyLinked for prism-verify in the verification env) - 13 orphaned "SDK" prose references cleaned up - ADR-005 title trimmed to "Decompose Prism into three crates" - ADR-007 title: "foundation defines, prism bounds, author selects" New content: - §5.2 standard library row: amended to specify decomposition by uor-foundation's shape primitives + canonical UOR-address mapping note + reference to ADR-017 - §8 closure section: extended from 2 consequences to 4. Bullets 3 and 4 cover IRI determinacy (closure makes UOR addresses derivative of constraint declarations, not namespace-claimed) and author-declared types (standard library is convenience, not capability — authors declare their own first-class Prism types via prism's vocabulary re-exports) - ADR-017: full Nygard ADR with two rejected alternatives - Glossary: new entry "Canonical UOR-address mapping" The rename is purely nominative; every architectural commitment (sealing, principal data path, UORassembly, closure, mint primitives, repo split) holds identically before and after. ADR-017 is the only new architectural commitment. V1, V2, V3, V4, V5 all PASS. Stage 5 idempotence holds. 22 SVGs regenerated. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 4, 2026
  • Three-crate reallocation: substrate / runtime / replay façade Restructures the wiki to disentangle the conflation between uor-foundation (substrate) and Prism (the system Prism realizes). The architectural commitments do not change; the allocation of those commitments across the three crates does. Crate role allocation (was → is): uor-foundation "principal data path + 7 sealed types + traits" → substrate. Type-declaration vocabulary (incl. shape proc-macros via internal sub-crate); 4 UOR-domain sealed types (Datum, Triad, Derivation, FreeRank); wire-format type definitions as data; mint primitives as cross-crate construction surface. uor-foundation-sdk → prism-sdk was "compile-time enforcement only, no runtime code" → Prism runtime. Pipeline runtime; 3 Prism-mechanism sealed types (Validated, Grounded, Certified); operation-declaration vocabulary; standard type library. Closed under uor-foundation's vocabulary. Re-exports uor-foundation's vocabulary so authors import only prism-sdk. uor-foundation-verify → prism-verify was "validates traces; depends on foundation type defs and replay primitives" → replay façade. Re-exports prism-sdk's certify_from_trace and Certified, plus uor-foundation's wire-format types. Carries no implementation. Source-side changes: - 12 chapters substantively amended for the new allocation: ch1 Introduction: three-crate roles + sealed-type allocation note ch2 TC-02 + TC-03 prose: cross-crate seal clarification ch3 Channels table: substantive updates per row + new mint-primitive channel; cross-boundary Sealing bullet ch4 6-row strategic table substantively rewritten; "How These Decisions Compose" rewritten ch5 Black-box descriptions and component decompositions substantively rewritten; pipeline relocates to prism-sdk; replay relocates to prism-sdk; mint-primitives component added; new L3 sub-section for prism-sdk seal regime + replay ch6 Scenario 1 properties bullet, Scenario 2 control transfer, Scenario 3 substantive steps, Cross-Scenario Properties first bullet substantively updated ch7 Mapping table cell contents change (prism-sdk now Present in user-execution and user-verification environments); repo-source clarification in Level 2 prose ch8 Sealing Discipline rewritten; UORassembly Contract Definition amended; #![no_std] Posture rewritten; Feature Flags expanded; three new H2s: Operation Declaration, Closure Under uor-foundation, Cross-Crate Construction Surface ch9 ADR-005, 006, 007, 011 substantively rewritten; ADR-002, 003, 008, 009, 010 amended (renames + role refs); five new ADRs: ADR-012 Pipeline runtime placement; ADR-013 Closure of prism-sdk under uor-foundation; ADR-014 Operation declaration vs operation shipment; ADR-015 Repo split (UOR-Framework + Prism); ADR-016 Cross-crate seal mechanism (mint primitives) ch10 QS-01, QS-04 Scenario A/B, QS-05 substantive updates ch11 TR-01 substantive (proc-macro location); TR-03 substantive (cross-crate flag combinatorics); TR-06 substantive (cross-repo coordination); two new TRs: TR-08 vocabulary insufficiency, TR-09 prism-sdk version pin lag ch12 Glossary: 18 entries updated for new sealed-type allocations + crate roles; 5 new entries (prism-sdk, prism-verify, mint primitive, operation declaration, closure under uor-foundation); plus certify_from_trace, replay, seal regime, vocabulary re-exports as new component entries - workspace.dsl: container descriptions rewritten; uor-foundation L3 drops pipelineComp, gains mintPrimitivesComp + 4 shape macro components; prism-sdk L3 replaces 4-component view with 6 (pipeline, sealRegime, replay, operationDeclaration, standardTypeLibrary, vocabularyReExports); prism-verify L3 re-anchored at prism-sdk's replay; dynamic views updated for pipeline-in-prism-sdk; deployment views add prismSdkLinked to user-execution and user-verification environments - 22 SVGs regenerated (Structurizr export) V1, V2, V3, V4, V5 all PASS. Stage 5 idempotence holds. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 4, 2026
  • Phase 3 first content: import full Prism architecture wiki Replaces the 12 heading-only chapter skeletons and the empty workspace.dsl with their authored versions, plus the 11 Structurizr SVG views (+ 11 -key.svg legends) generated from the workspace. Chapters added: 01 Introduction and Goals 103 lines (4 H2) 02 Architecture Constraints 107 lines (3 H2) 03 Context and Scope 74 lines (3 H2) 04 Solution Strategy 59 lines (2 H2) 05 Building Block View 249 lines (3 H2) 06 Runtime View 382 lines (5 H2 + upstream placeholders) 07 Deployment View 199 lines (4 H2) 08 Cross-cutting Concepts 290 lines (9 H2 + upstream placeholders) 09 Architecture Decisions 387 lines (11 ADRs) 10 Quality Requirements 211 lines (4 H2) 11 Risks and Technical Debts 197 lines (7 TRs) 12 Glossary 67 lines (1 H2) C4 model added (12 view keys, 22 SVGs after legends): L1: c4-l1-system-context L2: c4-l2-prism-containers L3: c4-l3-{foundation,sdk,verify}-components Dynamic: c4-dynamic-{principal-data-path, trace-replay, uorassembly-enforcement, distribute-and-run} Deployment: c4-deployment-{application,verifier} Source-side fix-ups applied during validation: - workspace.dsl: removed `applicationUser -> uorFoundationVerify` from the system-landscape-scoped `c4-dynamic-distribute-and-run` view; Structurizr rejects person->container relationships at landscape scope. - Chapters 5,6,7,8,10,11: wrapped `#![no_std]` and `#![feature(generic_const_exprs)]` in `++...++` passthrough so the `#` characters do not collide with AsciiDoc's mark-text formatting and produce malformed DocBook in V2's pandoc step. Rendered output unchanged (still monospace `#![...]`). V1 still PASSes (heading text comparison is exact-match against upstream; chapters add new H2 sections beyond the upstream set, which V1 explicitly allows as a structural superset). Imported v1-structural-alignment.rb and v3-structurizr.sh from the content drop were stale earlier versions and were not copied -- current in-tree versions are the working ones. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 4, 2026
  • Phase 0 + Phase 1 + Phase 2 bootstrap Adds the full validation, build, and authoring infrastructure defined in the parent UOR-Framework repo's wiki-definition.md, plus skeleton chapter sources and the first end-to-end-passing rendered output. Phase 0 (tooling): - 12 scripts under scripts/ (V1..V5 validators, install-tools, validate, build, render-wiki-frame, stage-to-wiki-root, check-wiki-state) - vendor/arc42-generator submodule pinned at 46bd7ce (Feb 2026) - arc42-template pinned at b29e08 via tools/arc42-template-pin.txt (overrides the generator's own stale submodule pin) - structurizr.war v2026.04.19 (Playwright variant) pinned in tools/checksums.txt by SHA-256 - cmark-gfm 0.29.0.gfm.13, built from source by install-tools.sh - Gemfile pins asciidoctor ~> 2.0, github-markup ~> 5.0, commonmarker ~> 0.23 (5.0.x github-markup needs the 0.x API) - tools/versions.txt as build.sh Stage 1's pin authority Phase 1 (skeleton sources): - src/arc42/adoc/NN_*.adoc — 12 chapter skeletons matching upstream H1+H2 - src/arc42/arc42-template.adoc — top-level include for direct asciidoctor - src/arc42/version.properties - src/c4/workspace.dsl — empty workspace (V3 PASS / 0 views) - src/wiki/{Home,Sidebar,Footer}.adoc Phase 2 (rendered artifacts at the wiki root): - 12 chapter files NN-Title-Case-Name.md - Home.md, _Sidebar.md, _Footer.md - images/ (placeholder .gitkeep until the C4 model gains views) Validators: - V1 — structural alignment with upstream arc42-template - V2 — drives the arc42-generator Docker pipeline (gitHubMarkdownMP / plain), bypassing build-arc42.sh's destructive submodule reset - V3 — Structurizr DSL validate + SVG export (skips export when no views, avoiding Playwright Chromium dependency on empty workspaces) - V4 — cmark-gfm with GitHub's wiki extension set - V5 — github-markup gem to catch markup-stage rendering failures build.sh runs the five-stage pipeline (pre-flight pin check, validate, render wiki-frame, stage to wiki root, idempotence check via cmp). Spec deviations (vs wiki-definition.md): - Chapter 3 filename is 03_context_and_scope.adoc (upstream-actual), not 03_system_scope_and_context.adoc; rendered as 03-Context-and-Scope.md - arc42-template pinned at our level (separate file) rather than relying on the generator's transitive pin, because arc42-generator's Templates.groovy expects a layout newer than its own pinned submodule - v2-arc42-build.sh invokes `groovy build.groovy` directly, skipping the generator's build-arc42.sh wrapper (which wipes our staged edits and fails inside our nested-submodule git layout) - V2's chosen output format is gitHubMarkdownMP (Multi-Page GFM) for per-chapter files, not the spec's unspecified default Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 4, 2026