Skip to content

History

Revisions

  • Surface PrismModel + categorical structures (ADR-019, ADR-020) Two related additions that name the structures already present in the architecture and surface the developer's contract for declaring an application as a typed iso between input features and output labels. ADR-019 — Foundation is a closed signature endofunctor; `Term` is its initial algebra; `pipeline::run` is the catamorphism. The wiki has stated TC-01 (zero-cost runtime) and ADR-013 (closure under uor-foundation's vocabulary) as separate properties. They are not separate; they are two halves of one categorical theorem: closure makes F's signature complete; completeness lets the catamorphism be discharged at the application's compile time (TC-04, UORassembly); zero-cost follows. Stating the theorem in its native vocabulary lets later commitments compose against initiality + uniqueness + completeness rather than re-establishing them. The vocabulary uor-foundation gains is editorial: signature endofunctor, F-algebra, initial algebra, catamorphism, anamorphism, fixed point. None names a new runtime concern; each names a structure already present. Naturally extends ADR-007's three-position substrate-vs-implementor pattern: foundation defines the signature endofunctor and initial algebra; prism declares the bound (the F-algebra contract any Route satisfies); the application author selects the F-algebra by writing the model. ADR-020 — `PrismModel` is the application author's contract for declaring a typed iso between input features and output labels. Without a trait, the categorical structure exists but is not actionable: developers assemble ConstrainedTypeShape impls, pick substitution-axis selections, and write hand-rolled Rust to compose them, with no type system enforcing that the composition is the unique homomorphism the architecture demands. Real-world Prism applications observed in the field exhibit exactly this failure mode (the operations are foundation-vocabulary; the composition is hand-rolled outside the type system). `PrismModel` carries Input, Output, Route associated types and forward(input) -> Grounded<Output>. Route's bound is closure under foundation vocabulary, checked at the application's compile time (TC-04, ADR-006). forward is the catamorphism prism derives from Route via initiality of Term (ADR-019); the application author does not write forward's body. The framing the developer reads is Real-Time Inference; the framing the architecture supports underneath is the categorical iso. Both framings are the same statement. Naming considered: Prism (collides with crate name + optic concept), Model (ML connotation: parameterized weights, training), Inference (names the runtime behavior, not the declaration), Route (names a Route component, not the whole iso). Settled on PrismModel as the conjunction with no overload. Edits: - src/arc42/adoc/08_concepts.adoc: two new top-level sections — "Foundation as a Signature Category" (signature endofunctor, initial algebra, catamorphism, anamorphism, fixed points, the closure+TC-01 unification) and "PrismModel" (contract, compilation as monomorphism, Real-Time Inference framing, replay side). - src/arc42/adoc/05_building_block_view.adoc: new PrismModel row in the prism container's Level 3 component table; prism black-box description's author-interface row updated to lead with the PrismModel trait; layered-structure paragraph updated to describe PrismModel sitting at the top of the runtime stack. - src/arc42/adoc/09_architecture_decisions.adoc: appended ADR-019 (signature category) and ADR-020 (PrismModel) after ADR-018, each with three rejected alternatives. - src/arc42/adoc/12_glossary.adoc: 8 new entries — Anamorphism, Catamorphism, F-algebra, Fixed point, Initial algebra, PrismModel, Real-Time Inference, Signature endofunctor — placed alphabetically. Verification: ./scripts/build.sh complete, all 8 validators PASS, Stage 5 idempotence holds, ./tests/run-all.sh PASS (59 tests). No incidental SVG churn (the timestamp-stripping work makes C4 SVGs deterministic across builds). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 6, 2026
    16a8723
  • Adopt HostBounds capacity completeness (ADR-018) ADR-018 declares that every capacity bound flowing along the principal data path is carried by HostBounds, with foundation-global capacity constants and closed foundation-controlled enums explicitly rejected. This commit applies the architectural change across the wiki sources. Eliminated as foundation-global constants: FINGERPRINT_MIN_BYTES -> HostBounds-borne byte-width range (lower) FINGERPRINT_MAX_BYTES -> HostBounds-borne byte-width range (upper) TRACE_MAX_EVENTS -> HostBounds-borne trace event-count ceiling Retained as foundation-fixed: TRACE_REPLAY_FORMAT_VERSION -- protocol identifier, not a capacity. Cross-implementation interoperability requires a single shared format ID. Edits: - 02_architecture_constraints.adoc: HostBounds row in the substitution axes table now enumerates the capacities it carries (fingerprint output width range, trace event-count ceiling, algebraic-level bit-width ceiling, plus extension); names DefaultHostBounds. - 05_building_block_view.adoc: prism-verify Re-exports row, the enforcement::calibrations and enforcement::transcendentals sub- components, the bridge::trace::Trace and bridge::cert::ContentFinger- print rows, and the high-level enforcement-component description all reframed to refer to HostBounds-carried capacities (with ADR-018 cross-references). transcendentals now mentions only the wire-format version constant. - 06_runtime_view.adoc: Scenario 2 verification time bound now reads 'bounded by the trace event-count ceiling carried by the application's selected HostBounds'. - 08_concepts.adoc: Trace events length bound, DatumAdmitted variant width check, and Hashing Substrate Contract output width row all refer to HostBounds-carried ranges. - 09_architecture_decisions.adoc: ADR-007 context expanded with the list of capacities HostBounds carries; ADR-009 rejected alternative reworded; ADR-010 Decision reworded; NEW ADR-018 (HostBounds capacity completeness) appended after ADR-017 with three rejected alternatives (foundation-global constants, closed foundation- controlled enums, fourth substitution axis). - 10_quality_requirements.adoc: QS-03 response measure refers to HostBounds-carried trace event-count ceiling. - 12_glossary.adoc: removed glossary entries for FINGERPRINT_MIN_BYTES, FINGERPRINT_MAX_BYTES, TRACE_MAX_EVENTS; updated ContentFingerprint and HostBounds entries. - src/c4/workspace.dsl: prism-verify reExportsComp description updated to mention 'the HostBounds trait surface (whose associated constants carry every capacity bound) and the wire-format version constant TRACE_REPLAY_FORMAT_VERSION' instead of the deprecated FINGERPRINT_* and TRACE_* constants. The L3 prism-verify component SVG is the only C4 SVG affected by this change (the other 10 are byte-identical to e7508e8 because the timestamp-stripping work makes them deterministic). Verification: ./scripts/build.sh complete (V1-V8 all PASS, Stage 5 idempotence holds). The 2 remaining FINGERPRINT_MAX_BYTES occurrences in 09-Architecture-Decisions.md are ADR-018's intentional contrast of the canonical pattern '[u8; H::FINGERPRINT_MAX_BYTES]' against the non-conforming '[u8; FINGERPRINT_MAX_BYTES]'. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 5, 2026
    3d12151
  • Fix incoherent deployment views: hide container-instance descriptions The two C4 deployment views (c4-deployment-application, c4-deployment-verifier) were rendering each containerInstance's full description -- a paragraph appropriate to the L2 container view but visually overwhelming in a deployment topology. The verifier view, with three container instances per deployment node plus the wrapping prose, devolved to walls of text instead of a readable deployment topology. Fix: add a Container Instance style to the workspace styles block that hides description and metadata. Container Instance is the implicit tag Structurizr applies to every containerInstance declaration, so the rule targets exactly those elements without affecting the bare Container element used by the L2 view (which continues to show full descriptions and the [Container: <tech>] metadata badge). element "Container Instance" { description false metadata false } Visible text per element after the change: Deployment Node title + [Deployment Node: <tech>] Container Instance just the container name Infrastructure Node title + [Infrastructure Node] + short desc (relationships) relationship descriptions unchanged The deployment node descriptions remain hidden by Structurizr's default SVG export (this was the prior behaviour too -- structurizr emits hidden placeholder <text> elements with display="none" and fill-opacity:0 for them). Container details for someone studying the system live in section 5 (L2 container view) and chapter 7 (deployment view's surrounding prose), not the topology diagram. Verification: - ./scripts/build.sh PASS, all 8 validators PASS, Stage 5 idempotence holds. - L2 view still shows full container descriptions ("Substrate. Type-declaration vocabulary..." for uor-foundation, etc.). - Deployment views show just the container names inside each deployment node. - md5sum c4-deployment-application.svg byte-identical across two separate build invocations 2 seconds apart (no timestamp variance from the prior cleanup persists). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 5, 2026
    e7508e8
  • C4 diagram improvements: per-view autoLayout, no timestamps, no orphan keys The C4 SVGs were generated by Structurizr with bare autoLayout, which applies its default direction (top-bottom) and rank/node separation (300/600). The exporter also injected a per-build timestamp footer into every SVG, which produced ride-along SVG churn on every commit even when no C4 source changed. And the exporter writes a -key.svg legend per view that was never referenced from any chapter. This commit makes three changes that together produce cleaner, truly-deterministic C4 diagrams: 1. workspace.dsl: per-view autoLayout direction + spacing. - L1 system context (4 nodes, hub-and-spoke): lr 200 100 - L2 containers (3 + actors, stacked): tb 250 150 - L3 uor-foundation (densest, 10 components): tb 200 120 - L3 prism (medium, 7 components): tb 200 150 - L3 prism-verify (sparse, 2 components): lr 200 100 - 4 dynamic scenarios (sequence flow): tb 220 150 - 2 deployment views (nested topology): tb 220 150 Tighter than the default 300/600 across the board; direction chosen per view shape so each diagram fits the wiki page width without horizontal scrolling. 2. v3-structurizr.sh post-process (new Phase 2.5): After `structurizr export`, V3 now: a) Deletes the orphan <view>-key.svg legend files from src/arc42/images/. The keys are autogenerated by Structurizr but were never referenced from any chapter or wiki-frame file. They added 11 unused files to images/ and 11 entries of git noise per export. b) Strips the timestamp footer from each <view>.svg. The structurizr exporter injects a <g><g><text><tspan>...</tspan> </text></g></g> block containing a string like "Tuesday, May 5, 2026 at 6:16 PM Coordinated Universal Time" at the bottom of every diagram. The whole wrapper block is removed via sed; the diagram title and view description (also in identically-shaped wrappers, but with non-date content) are preserved. Result: SVGs are byte-identical across separate build invocations. The "C4 SVG re-render" lines in recent commit messages are gone. 3. stage-to-wiki-root.sh: wipe c4-*/opm-* SVGs before staging. Previously the staging step copied fresh SVGs but never removed stale ones. After change (1) dropped the -key.svg files from src/arc42/images/, the existing committed -key.svg files at the wiki root persisted (until manually removed). Now stage-to-wiki- root.sh wipes c4-*.svg and opm-*.svg from $DEST/images at the start of staging; hand-authored SVGs (anything without those prefixes) are preserved. Verification: - ./scripts/build.sh — all stages PASS, Stage 5 idempotence holds. - All 8 validators PASS (V1–V8). - md5sum of c4-l1-system-context.svg unchanged across two separate build invocations 2 seconds apart (no timestamp variance). - images/ count drops from 28 (17 functional + 11 orphan keys) to 17 (11 C4 + 6 OPM). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 5, 2026
    bd1ec6b
  • Render OPDs via graphviz; V7 filters by class=opm-entity The 6 opd.svg files previously contained only entity-name shapes laid out in a 4-column grid, with no relations rendered. They satisfied V7's bimodal-equivalence check (entity-name set in OPL == entity-name set in SVG) but conveyed none of the OPL's relational content. They were valid but inadequate as OPD renderings. This commit replaces the in-Ruby grid generator with a graphviz- backed renderer and updates V7 to filter SVG <text> elements by a new class marker so edge labels do not pollute the entity set. Generator (tools/opl-to-svg.rb): - Parses the OPL into entities + relations (declarations, procedural links, structural links, generalisation, classification). - Classifies each entity as object or process by examining its declaration's essence and its appearances in procedural-link sentences (an entity that is the subject of yields/consumes/ affects/requires/invokes is a process; an entity that is the object of "handles" is a process; otherwise object). - Emits a Graphviz dot description with OPM-style conventions: rectangles for objects, ellipses for processes, dashed strokes for environmental things, edge labels with the relation phrase, arrowhead glyph chosen per relation kind (onormal for "is a" / "is an instance of"; odiamond for "consists of" / "exhibits"; normal for procedural links). - Runs `dot -Tsvg`, post-processes the SVG to add class="opm-entity" to every <text> inside <g class="node">, and strips the dot-emitted <title> tooltip elements. - Deterministic across runs (verified by md5sum). V7 update (scripts/lib/opl_entity_extractor.rb): - Adds OPLEntityExtractor.svg_entity_text(svg_text), which returns the set of <text> contents whose class attribute contains the "opm-entity" token (multi-class membership accepted; whitespace- trimmed; empty drops). - v7-opd-opl-coherence.rb now calls into this lib helper rather than having an inline svg_text_content function. - The class filter means edge labels (relation phrases like "yields", "consists of") do not appear in the SVG entity set; only entity- name node labels count. Test updates (tests/test-v7-extractor.rb): - Four new unit tests for svg_entity_text covering single-class, multi-class membership, whitespace-trim/empty-drop, and ignoring unclassed text. - Existing end-to-end fixtures updated: the synthetic OPDs use <text class="opm-entity">Foo</text> for entity nodes and <text>yields</text> for an unclassed edge label, exercising the class filter end-to-end. Spec update (wiki-definition.md V7 section): The implementation step that was "extracts the text content of every <text> element" now reads "extracts text content of <text> elements that carry class='opm-entity' (multi-class accepted)" with a note that hand-authored SVGs MUST tag entity-name <text> elements with the class for V7 to recognise them. Tooling integration: - scripts/install-tools.sh: new step 6b installs graphviz via apt and records dot's reported version line in tools/versions.txt under graphviz-reported. Idempotent: re-runs are no-ops when dot is already present. - build.sh's pre-flight does NOT pin graphviz — opd.svg is a source artifact, so day-to-day builds do not invoke the renderer. - tools/versions.txt now records graphviz-reported = "dot - graphviz version 2.43.0 (0)" (the version present at this regeneration). Verification: all 8 validators PASS, Stage 5 idempotence holds, all 59 unit tests PASS (4 new svg_entity_text tests + 55 prior). C4 SVGs re-rendered (Structurizr exporter timestamp churn). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 5, 2026
    77fe724
  • Cleanup: drop \"Phase 4 not yet landed\" framing, tighten OPL fenced blocks Phase 4 reconciliation landed in 368326f. The wiki state now matches its defined state: V1–V8 all enforce, no skip-gaps remain in the normal build. The references to Phase 4 as a pending future event are stale. This commit reframes the prose without altering the underlying discipline. The reconciliation gap discipline itself stays — it is the safety property that keeps the build green during pin-replacement transitions where a pin file or its source dir is transiently absent. What changes is the framing: Phase 4 is no longer described as \"upcoming\" or \"not yet landed.\" Changes: - wiki-definition.md: \"Bootstrapping order\" / \"Phase 4 — V6/V7/V8 reconciliation\" sections replaced with \"Reconciliation gap discipline,\" preserving the discipline rules. Property 7 reworded to make the discipline (rather than Phase 4 specifically) the conditional that admits absence. - README.md: dropped \"Absent during Phase 4 reconciliation\" notes from the three pin-file authorities, the OPM and 15288 source dirs, and the wiki-root .md/images entries. Added rows for src/opm/opd-order.txt and tools/opl-to-svg.rb. - scripts/v6-opl-syntax.sh, v7-opd-opl-coherence.sh, v8-iso-15288-superset.sh: skip-gap reason strings now read \"pin file absent: <path>\" rather than referencing Phase 4. - scripts/render-opm-index.sh: dropped the leading \\n from the fence-close printf so the closing ``` sits directly after the last OPL line, not after a blank line. Conceptual-Model.md regenerated with the tightened fenced blocks. 12 C4 SVGs re-rendered (Structurizr exporter timestamp churn). Verification: ./scripts/build.sh complete (V1–V8 PASS, Stage 5 idempotence holds). ./tests/run-all.sh PASS (55 tests). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 5, 2026
    1a24cb0
  • Phase 4 reconciliation: OPM + ISO 15288 sources, V6/V7/V8 all PASS Lands the three transcribed-standard pin files, all six OPM Conceptual Model OPDs, and all four ISO/IEC/IEEE 15288 lifecycle process-group chapters. The wiki state now matches its declared state in wiki-definition.md: every validator runs (no skip-gap), Stages 3b/3c produce committable output, and Stage 5 idempotence holds. Pin files (tools/): - iso-19450-opl.ebnf — OPL formal syntax in ISO/IEC 14977 EBNF. Workspace-authored transcription of ISO/PAS 19450:2015 Annex A. Each production carries an inline source-attribution comment citing the standard plus seven public corroborating sources (Dori 2002, Dori 2016, OPCAT 3.0 manual, Svensson 2004 thesis, OPCloud linkTypeSelection.ts, Wikipedia, ISO 19450 free preview). Coverage: object/process/state declarations, the four fundamental structural relations, transformation links, enabling links, in-out link pairs, tagged structural links, invocation. Deferred to a later cycle: state-specified link variants, control-link modifiers, in-zoom/unfolding, multiplicity, path labels. - iso-19450-opd-coherence.txt — Maps the three entity-introducing productions to their name-bearing rules (object-declaration → object-name, process-declaration → process-name, state-declaration → state-name). Why these three: per ISO 19450 Clauses 7-9, only these introduce entities into the model; the other 13 sentence kinds reference pre-introduced things. - iso-15288-processes.txt — 30-process catalog across the four process groups (2 + 6 + 8 + 14). Verbatim from ISO/IEC/IEEE 15288:2023 Clause 6 section titles. ISO 15288 lifecycle (src/15288/): Per-process-group AsciiDoc chapters declaring Prism's instance of each of the 30 processes. For each process, the chapter records either (a) the artifact in Prism's architecture that satisfies the process (cross-referencing arc42 sections, ADRs, constraints, or codebase verification artifacts) or (b) "Not applicable to Prism" with the architectural reason for inapplicability. V8 verifies that every process named in the pin file appears as a `===` heading in the corresponding `<group>.adoc` file. OPM Conceptual Model (src/opm/): Six OPDs presenting Prism's static and dynamic conceptual structure: - SD : Top-level system context (chapter 3) - SD1-Prism-Structure : Three containers (chapter 5) - SD2-Principal-Data-Path : Pipeline stages (chapter 6 scenario 1) - SD3-Verification : Replay surface (chapter 6 scenario 2) - SD4-UORassembly-Enforcement : Compile-time bilateral check (scenario 3) - SD5-Distribute-and-Run : Author-to-user handoff (scenario 4) Each OPD comprises an opl.txt (canonical OPL declaration set, V6's input) and an opd.svg (rendering, V7's secondary input). V7 verifies the entity name set declared by opl.txt equals the <text> content set in opd.svg. OPL files for SD, SD1, SD2, SD3 are workspace-authored to match the architecture chapters; OPL for SD4 and SD5 is workspace-authored from chapter 6 scenarios 3 and 4. All six SVGs are generated by tools/opl-to-svg.rb (a developer aid; see below). OPL → SVG generator (tools/opl-to-svg.rb): A one-time / occasional bootstrap helper that produces a deterministic OPM-style SVG from an OPL file. NOT part of the build pipeline — opd.svg is a source artifact, not a build output. The generator classifies each entity as object (rectangle) or process (ellipse) by examining its declaration's essence and its appearances in procedural-link sentences; environmental things render with dashed borders. Layout is a 4-column grid; each entity receives one <text> element whose content matches the OPL declaration verbatim, so V7's coherence check holds by construction on first generation. The author may hand-tune the SVG layout subsequently; V7 catches any edit that drops or alters an entity-name <text>. Sidebar.adoc: Reorganized into three sections matching the three coordinated standards: - Architecture (arc42 + C4): 12 chapters, unchanged - Conceptual Model (OPM ISO 19450): Conceptual-Model - Lifecycle (ISO/IEC/IEEE 15288): four lifecycle pages Validator status (./scripts/validate.sh): V1 — arc42 structural alignment PASS V2 — arc42 build pipeline PASS V3 — Structurizr DSL PASS V4 — CommonMark / GFM PASS (21 files, +6 vs prev) V5 — GitHub-markup rendering PASS (21 files) V6 — OPL syntax PASS (6 OPL files) V7 — OPD/OPL bimodal coherence PASS (6 OPDs) V8 — ISO 15288 process superset PASS (4/4 groups, 30 processes) Build (./scripts/build.sh): Stages 1-5 complete. Stage 5 idempotence holds. Tests (./tests/run-all.sh): test-v6-translator.rb PASS (44 unit tests) test-v7-extractor.rb PASS (11 unit tests) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 5, 2026
    368326f
  • Complete V6 EBNF→PEG translator and V7 OPL entity extractor Removes the two NotImplementedError stubs that gated Phase 4 source content. The wiki infrastructure is now complete: every committed .rb/.sh script in scripts/ runs end-to-end, and the only remaining Phase 4 work is authoring transcribed-standard pin files and OPM/15288 source content. V6 (scripts/lib/ebnf_to_treetop.rb): - Mechanical ISO/IEC 14977 EBNF → treetop PEG translator. Lexer, recursive-descent parser, and treetop emitter. Handles: lhs = rhs ; → rule lhs<sanitized>; rhs ; end a , b → a b (juxtaposition) a | b → a / b (PEG ordered choice) [ a ] / { a } / ( a ) (postfix ?, *, parens) a - b → (!b a) (PEG negative lookahead, warn) "..." / '...' (passthrough) (* comment *) (stripped at lex) identifier with hyphens (sanitised to underscores) ? special ? (raises — author rewrites) - Every emitted rule wraps its body in __body__:(...) labeling so treetop preserves the rule's syntax-node identity (without it, treetop inlines a rule whose body is a single nonterminal reference, losing the outer rule's __rule__ tag). - Every emitted rule defines def __rule__; '<rulename>'; end via an inline extension block, so V7 can identify which production produced any node by walking the parse tree. V7 (scripts/lib/opl_entity_extractor.rb): - parse_coherence: reads tools/iso-19450-opd-coherence.txt as a list of "<entity-introducing-rule> : <name-bearing-rule>" mappings. Both rule names sanitized (hyphens → underscores). Comments and blank lines ignored. - entity_names: walks the V6 parse tree, finds nodes whose __rule__ matches an entity-introducing rule, and within each finds every descendant whose __rule__ matches the corresponding name-bearing rule. Collects text_value (whitespace-trimmed) into a Set. Tests (tests/): - test-v6-translator.rb: 44 unit tests over the lexer, parser, and emitter (constructs from the translation table; hyphenated identifier handling; precedence preservation; end-to-end load + parse with three synthetic mini-grammars). - test-v7-extractor.rb: 11 tests over coherence-file parsing, entity extraction (object/process/state declarations, dedup, nested structures), and a full subprocess invocation of v7-opd-opl-coherence.rb against a synthetic fixture set with both coherent and drifted OPDs. - run-all.sh: simple test runner. Both test files exit 0. Other changes: - scripts/v6-opl-syntax.rb: slim wrapper that requires the library and invokes the translator + parser. Same CLI as before. - scripts/v7-opd-opl-coherence.rb: rewritten to load V6's parser via the shared library, parse the coherence pin via the extractor, and cross-reference against opd.svg <text> elements. - Gemfile: added rexml ~> 3.2 (Ruby 3.4 removed it from defaults; V7 needs it to parse opd.svg). - wiki-definition.md V7 section: clarified the coherence file's mapping format and the parse-tree walking algorithm. Phase 4 reduced to three remaining steps (pin files + OPM sources + 15288 sources); the validator implementations and pipeline integration are now complete. - README.md: added scripts/lib/ and tests/ to the "What lives where" table. Verification: ./tests/run-all.sh PASS. ./scripts/build.sh PASS (V1–V5 PASS, V6/V7/V8 SKIP-GAP, Stage 5 idempotence holds). End-to-end smoke test of v6-opl-syntax.rb and v7-opd-opl-coherence.rb against synthetic pin files confirms both report PASS on coherent inputs and FAIL with symmetric difference on drifted inputs. C4 SVGs re-rendered (Structurizr exporter timestamps differ across build runs; the 12 affected files are byte-different from 738d368). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 5, 2026
    fb9b635
  • Audit cleanup: factor render-15288, refresh check-wiki-state and README Three real issues surfaced by audit of a3927ef: 1. scripts/check-wiki-state.sh only re-ran render-wiki-frame + stage-to-wiki-root. Missed Stage 3b (15288) and 3c (OPM). Once Phase 4 source content lands, the post-push detector would have produced false DRIFT alerts for Lifecycle-*.md and Conceptual-Model.md. Now invokes render-15288.sh and render-opm-index.sh as well. 2. README.md said "Runs V1–V5" and "wiki-definition.md is in the parent UOR-Framework repository" — both stale after the V6/V7/V8 + spec- relocation work. Updated to reflect: - V1–V8 with reconciliation-gap discipline - wiki-definition.md is at this repo's root - OPM (src/opm/) and ISO 15288 (src/15288/) source paths - Three transcribed-standard pin authorities (tools/iso-*) - Phase-4-content-absent line for the "What lives where" table 3. Stage 3b was inline in build.sh and duplicated as the render_15288 function in validate.sh. Factored into scripts/render-15288.sh; both build.sh and validate.sh now delegate. check-wiki-state.sh also uses it. Skip-on-empty discipline preserved. Other audit findings: - wiki-definition.md is a faithfully-condensed version of the user's source text (V2/V3/V5 sections refer to the bc7bf4d-pinned scripts rather than carrying verbatim text). Acceptable as in-repo spec; the committed scripts ARE the canonical behavior. - Sidebar.adoc lists 13 entries (Home + 12 chapters). Conceptual-Model and Lifecycle-* pages are deliberately not listed yet — adding them now would create broken links until Phase 4 source content lands. - Empty src/opm/ and src/15288/ directories not created. The reconciliation gap discipline allows source dirs to be absent. - C4 SVGs re-renderered (Structurizr exporter is non-deterministic across runs; the 12 affected files are byte-different from those in a3927ef). V1–V5 PASS, V6/V7/V8 SKIP-GAP. Build green. Stage 5 idempotence holds. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 5, 2026
    738d368
  • Phase 4 infrastructure: V6/V7/V8 + reconciliation gap discipline Lands the wiki-side scaffolding for the OPM (ISO 19450) and ISO 15288 layers per the updated wiki-definition.md. Pin files (transcribed standards) and source content (src/opm/, src/15288/) are deferred to subsequent commits per the user's "infrastructure first" direction. Validators V6/V7/V8 implemented with skip-on-gap discipline: when their pin files (tools/iso-19450-opl.ebnf, tools/iso-19450-opd-coherence.txt, tools/iso-15288-processes.txt) or their source directories (src/opm/, src/15288/) are absent, they report SKIP-GAP rather than failing — the build remains green throughout the reconciliation gap. Files added: - wiki-definition.md normative spec at the wiki root - scripts/v6-opl-syntax.{sh,rb} OPL parse against pinned EBNF - scripts/v7-opd-opl-coherence.{sh,rb} bimodal coherence: OPL entities ↔ SVG <text> - scripts/v8-iso-15288-superset.{sh,rb} process-heading structural superset - scripts/render-opm-index.sh Stage 3c assembler for Conceptual-Model.md Files modified: - Gemfile / Gemfile.lock added treetop ~> 1.6 (V6/V7 PEG parser) - scripts/validate.sh runs V1..V8 with skip-gap vs skip-upstream distinction; exit 0 iff every validator is pass or skip-gap (skip-upstream fails) - scripts/build.sh Stage 1d (transcribed-pin presence non-empty check), Stage 1e (bundle check), Stage 3a→3a (rename), Stage 3b (15288 pandoc render), Stage 3c (OPM index) - scripts/stage-to-wiki-root.sh Stage 4c collects SVGs from src/arc42/ AND per-OPD opd.svg with opm- prefix; Stage 4e (4 lifecycle pages with fixed rename map); Stage 4f (Conceptual-Model.md) - images/*.svg Structurizr re-exported (the C4 SVGs are re-renderered at every V3 invocation; the bytes differ from the previously-committed versions due to renderer non-determinism between runs, which is benign — the wiki spec's Stage 5 idempotence check covers same-run determinism, not cross-run) The 8-validator report after this commit: [x] V1, V2, V3, V4, V5 (architecture chain — pass) [~] V6, V7, V8 (skip-gap — pin files absent, Phase 4 not yet landed) When the next commits land the transcribed-standard pin files and source content, V6/V7/V8 will activate automatically without further infrastructure changes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 5, 2026
    a3927ef
  • 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
    bc7bf4d
  • 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
    063d0ac
  • 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
    527cc22
  • Pin pandoc, install Playwright deps, document arc42-template-pin.txt Closes the three pre-Phase-3 fit/trim items. 1. Pin pandoc 3.9.0.2 with SHA-256 in tools/checksums.txt; install-tools.sh downloads pandoc.deb and extracts it via dpkg-deb to tools/pandoc-prefix/ (no sudo, no system pollution). render-wiki-frame.sh now uses tools/bin/pandoc, not whatever is on $PATH — pandoc minor-version differences could otherwise shift the docbook→GFM output and break cross-developer build.sh idempotence. build.sh Stage 1 verifies the reported pandoc version against tools/versions.txt. 2. Install Playwright system libraries via `npx playwright install-deps chromium` in install-tools.sh and the devcontainer postCreateCommand. structurizr.war's SVG exporter launches headless Chromium that needs ~30 system libs; the canonical list shifts with Chromium versions, so delegating to Playwright's own installer beats hand-maintaining apt package names. Without this, V3 SVG export would have died on the first real view added in Phase 3 with libgbm.so.1 errors. 3. README's "Pin updates" section now explicitly enumerates all five pin authorities, including tools/arc42-template-pin.txt. The pin update procedure tells maintainers to reconsider the template pin whenever they bump arc42-generator (newer generator may want different layout). V3 incidentally refactored: stop parsing the DSL for view keys (fragile across DSL idioms — `key` is positional, not a property) and instead derive view keys from exported SVG filenames, which the parser produces authoritatively. Manually verified V3 export with a temporary L1 SystemContext view — 2 SVGs produced (the view + auto-generated -key.svg legend), workspace reverted to empty before commit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 4, 2026
    fdf48aa
  • Repo hygiene: ignore V3 working dir, pin bundle path, silence submodule noise Three small follow-ups from the post-bootstrap review: - .gitignore: add src/arc42/images/ — V3 deposits SVGs there; the committed copies live at images/ at the repo root, so the working dir is build artifact territory. - scripts/install-tools.sh: set bundle config --local path vendor/bundle before bundle install, so a fresh clone doesn't install gems globally. - .gitmodules: ignore = dirty for vendor/arc42-generator suppresses the permanent "modified content" status that arises because we override arc42-generator's recorded arc42-template pin via our own tools/arc42-template-pin.txt. Untracked-file changes still surface. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 4, 2026
    0fdb7aa
  • 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
    24adb79
  • Initial Home page

    @afflom afflom committed May 3, 2026
    d154ce6