Skip to content

History / README

Revisions

  • ADR-030 + ADR-031 + Scientific Methods and Results partition (issue #7) ADR-030 — `axis!` SDK macro: universal substrate-extension declaration mechanism. Generalizes Hasher to one axis among many; introduces AxisExtension, AxisTuple, MAX_AXIS_TUPLE_ARITY, AXIS_OUTPUT_BYTES_CEILING. Term::HasherProjection becomes Term::AxisInvocation (Term enum stays at ten variants). Catamorphism's per-variant fold-rule dispatches through A::dispatch(axis_index, kernel_id, &evaluated_inputs). ADR-031 — `prism` is the standard library: a façade over `uor-foundation` plus standard-library Layer-3 sub-crates (prism-numerics, prism-crypto, prism-tensor, prism-fhe) published from the Prism repository. Inclusion criteria, layered consumption pattern, content-addressing invariance, conformance vetting. Repository allocation made explicit: architecture in UOR-Framework, standard library in Prism. Drops prior "blessed" framing. Cross-references: ADR-007 third-position generalization to A: AxisTuple; ADR-013 Consequences extension; ADR-024 axis-declaration mechanism alongside verb-declaration; ADR-026 G19 generalization to axis-trait method calls; ADR-029 fold-rule + Substitution-axis-realized verbs paragraph rewritten for AxisTuple. Section 4 strategic decision row + composition paragraph; Section 8 Closure Across Layers paragraph. Glossary: 11 new/updated entries (axis!, AxisExtension, AxisTuple, AXIS_ADDRESS, AXIS_OUTPUT_BYTES_CEILING, MAX_AXIS_TUPLE_ARITY, Standard-library Layer-3 sub-crate, prism-numerics, prism-crypto, prism-tensor, prism-fhe, Term::AxisInvocation rename). Scientific Methods and Results — new non-normative academic-documentation partition (Director of Research stream per issue #7). Adds src/scientific/Scientific-Methods-and-Results.adoc with the landing-page content; scripts/render-scientific.sh (Stage 3d, mirrors render-15288.sh with reconciliation-gap discipline); Stage 3d wiring in build.sh + Stage 4g in stage-to-wiki-root.sh + render_scientific in validate.sh; sidebar entry in src/wiki/Sidebar.adoc; partition specification in wiki-definition.md (Non-normative content partitions section, source-tree, build-stages, correctness-contract Property 7); SOP in README.md (Robin issues -> wiki maintainer authors AsciiDoc -> build.sh -> commit). Pin refresh: tools/versions.txt java line refreshed from openjdk 21.0.11 to openjdk 21.0.10 (the JDK 21.x actually installed on the build host). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

    @afflom afflom committed May 9, 2026
  • 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
  • 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
  • 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
  • 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
  • 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