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>
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>
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>
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>
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>