Skip to content

Commit 500785c

Browse files
hyperpolymatharena-agentcoderabbitai[bot]
authored
docs: declare suite boundary with blocky-writer (#61) (#67)
Closes #61. ## What this is blocky-writer filed #61 to say: viewing and editing one logical document is Formatrix Docs; fitting content into fixed-layout PDF and application-form boxes is theirs. Nothing was blocking, and no integration was proposed. This PR is the neighbour answering that notice. It also satisfies the README half of [docmatrix#71](hyperpolymath/docmatrix#71 first acceptance criterion: each repo states its own boundary and links the other optional components. ## Boundary, as recorded - **Formatrix Docs** (this repo): tabbed viewing/editing of one logical document. Cursor mapping, tab state, undo/redo are proved here or they are not proved. - **DocMatrix**: multi-format conversion and precision coordination. - **blocky-writer**: fixed-layout PDF and application-form placement. - **ForthWall**: proposed, unbuilt; never a mandatory product. Proof obligations do not transfer. A green editor test does not prove page geometry, and exact page coordinates do not prove semantic correctness. ## The `detect_blocks` seam blocky-writer emits, per widget annotation: ```json { "label": "Name", "x": 50.0, "y": 700.0, "width": 200.0, "height": 24.0 } ``` `label` is AcroForm `/T` (else parent `/T`, else `field_<page>_<index>`). Coordinates are PDF user space. If graph/relationship views (FD-C01) ever show *where* a value lands, that is the shape we consume. This PR records it; it does not consume it. ## A2ML honesty #61 assumed the README listed A2ML as a tab. It did not, and `SourceFormat` still does not. A2ML is machine-readable project metadata under `.machine_readable/`. The blocky-writer corpus (`STATE.a2ml`, `ECOSYSTEM.a2ml`, `CLADE.a2ml`, contractiles) is noted as future test material *if* a document-tab parser is added. Implemented tabs remain TXT, MD, ADOC, DJOT, ORG, RST, TYP. ## README identity The README titled this repository **DocMatrix**. That is a different project. The title, intro, and `EXPLAINME.adoc` / `TOPOLOGY.md` headers now say Formatrix Docs. This is the same class of correction blocky-writer made in [blocky-writer#73](hyperpolymath/blocky-writer#73). ## GitHub description (owner follow-up) `gh repo edit` returned 403 from this integration, so the GitHub description was **not** updated. docmatrix#71 also asks for the description to state the boundary. Suggested text, matching docmatrix's: > Tabbed multi-format viewer/editor of one logical document. DocMatrix owns conversion; Blocky Writer owns fixed-layout PDF placement; ForthWall remains proposed. Synchronised editing is under development. ## Files | File | Role | | --- | --- | | `docs/ecosystem/ECOSYSTEM.adoc` | Long-form boundary (mirrors blocky-writer's) | | `README.adoc` | Title correction + suite section | | `.machine_readable/6a2/ECOSYSTEM.a2ml` | Machine-readable boundary | | `.machine_readable/integrations/blocky-writer.a2ml` | `detect_blocks` seam record | | `docs/SEAM-CHECK-MUSTS.adoc` | SEAM-6, recorded not consumed | | `docs/MOSCOW-REQUIREMENTS.adoc` | FD-S06 / FD-C01 / SEAM-6A notes | No code, no integration, no new format handler. --------- Co-authored-by: arena-agent <297053741+arena-agent@users.noreply.github.com> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
1 parent 85e6692 commit 500785c

12 files changed

Lines changed: 476 additions & 15 deletions

File tree

‎.machine_readable/6a2/ECOSYSTEM.a2ml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,63 @@
11
# SPDX-License-Identifier: MPL-2.0
22
# ECOSYSTEM.a2ml — Ecosystem position
33
# Converted from ECOSYSTEM.scm on 2026-03-15
4+
# Expanded 2026-10-10 to carry the suite boundary, so machine readers get it
5+
# without parsing prose. The authoritative, versioned contract is
6+
# https://github.com/hyperpolymath/docmatrix/issues/71 — if this file and that
7+
# issue disagree, the issue wins and this file is stale.
8+
# Inbound notice: https://github.com/hyperpolymath/formatrix-docs/issues/61
49

510
[metadata]
611
project = "formatrix-docs"
712
ecosystem = "hyperpolymath"
813

914
[position]
1015
type = "component"
16+
suite = "precision document suite"
17+
contract = "https://github.com/hyperpolymath/docmatrix/issues/71"
18+
contract-owner = "hyperpolymath/docmatrix"
19+
20+
[boundary]
21+
owns = "tabbed viewing and editing of one logical document across format tabs; synchronised editing is the intended progression"
22+
does-not-own = [
23+
"multi-format conversion and precision coordination — hyperpolymath/docmatrix",
24+
"fixed-layout PDF and application-form placement — hyperpolymath/blocky-writer",
25+
"OCR, NER and metadata extraction — hyperpolymath/docudactyl",
26+
"print routing — hyperpolymath/presswerk",
27+
"cross-document consistency reconciliation — hyperpolymath/recon-silly-ation",
28+
"capability-bounded critical execution — ForthWall, proposed and unbuilt",
29+
]
30+
hard-constraint = "never silently normalise document structure across tabs — composition contract clause 4; page geometry is not ours"
31+
32+
[suite]
33+
docmatrix = "multi-format conversion and precision coordination"
34+
formatrix-docs = "tabbed multi-format viewing and editing (this repo)"
35+
blocky-writer = "fixed-layout PDF and application-form placement"
36+
forthwall = "proposed capability-bounded execution layer — not implemented"
37+
38+
[seam.detect-blocks]
39+
owner = "hyperpolymath/blocky-writer"
40+
notice = "https://github.com/hyperpolymath/formatrix-docs/issues/61"
41+
shape = "{ label, x, y, width, height }"
42+
coordinates = "PDF user space"
43+
consumed-by = "optional future graph/relationship overlay (FD-C01); not implemented"
44+
integration-proposed = false
45+
46+
[formats]
47+
implemented = ["txt", "md", "adoc", "djot", "org", "rst", "typ"]
48+
not-a-tab-today = ["tabular-text", "a2ml", "deed"]
49+
a2ml-role = "machine-readable project metadata under .machine_readable/; not a SourceFormat"
50+
51+
[adjacent]
52+
affinescript = "hyperpolymath/affinescript — frontend language"
53+
recon-silly-ation = "hyperpolymath/recon-silly-ation — cross-document reconciler; SEAM-1"
54+
docudactyl = "hyperpolymath/docudactyl — OCR/NER/metadata extraction"
55+
presswerk = "hyperpolymath/presswerk — print routing, downstream of a rendered PDF"
56+
gv-clade-index = "hyperpolymath/gv-clade-index — taxonomy registry; CLADE.a2ml registered here"
57+
deed-ecosystem = "hyperpolymath/deed-ecosystem — .deed manifest format"
58+
standards = "hyperpolymath/standards — estate governance"
59+
60+
[communication]
61+
norm = "each repo states its own boundary in its README and links the others; a short issue is filed on a neighbour when a status change unblocks or affects it"
62+
no-standing-integration-programme = true
63+
long-form = "docs/ecosystem/ECOSYSTEM.adoc"

‎.machine_readable/6a2/STATE.a2ml‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,17 @@
55
[metadata]
66
project = "formatrix-docs"
77
version = "0.1.0"
8-
last-updated = "2026-03-15"
8+
last-updated = "2026-10-10"
99
status = "active"
1010

1111
[project-context]
1212
name = "formatrix-docs"
1313
completion-percentage = 0
1414
phase = "In development"
15+
16+
[ecosystem]
17+
suite = "precision document suite"
18+
contract = "https://github.com/hyperpolymath/docmatrix/issues/71"
19+
inbound-notice = "https://github.com/hyperpolymath/formatrix-docs/issues/61"
20+
siblings = "docmatrix (conversion), blocky-writer (PDF placement), ForthWall (proposed, unbuilt)"
21+
long-form = "docs/ecosystem/ECOSYSTEM.adoc"

‎.machine_readable/integrations/blocky-writer.a2ml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# SPDX-License-Identifier: MPL-2.0
2+
# blocky-writer integration — detect_blocks seam
3+
# Recorded from hyperpolymath/formatrix-docs#61. Not an integration:
4+
# the neighbour declared the shape so neither side invents it twice.
5+
6+
[integration]
7+
name = "blocky-writer"
8+
type = "suite-neighbour"
9+
repository = "https://github.com/hyperpolymath/blocky-writer"
10+
inbound-notice = "https://github.com/hyperpolymath/formatrix-docs/issues/61"
11+
contract = "https://github.com/hyperpolymath/docmatrix/issues/71"
12+
status = "boundary-declared"
13+
14+
[boundary]
15+
they-own = "fixed-layout PDF and application-form placement"
16+
we-own = "tabbed viewing and editing of one logical document"
17+
integration-proposed = false
18+
19+
[seam]
20+
name = "detect_blocks"
21+
owner = "hyperpolymath/blocky-writer"
22+
surface = "rust/pdftool_core (WASM export)"
23+
purpose = "If graph or relationship views show where in a document a value lands, consume this shape."
24+
coordinates = "PDF user space"
25+
label-resolution = "AcroForm field /T, else parent /T, else field_<page>_<index>"
26+
page-number-on-struct = false
27+
28+
[seam.block]
29+
label = "string"
30+
x = "f32"
31+
y = "f32"
32+
width = "f32"
33+
height = "f32"
34+
35+
[seam.example]
36+
json = "{ \"label\": \"Name\", \"x\": 50.0, \"y\": 700.0, \"width\": 200.0, \"height\": 24.0 }"
37+
38+
[corpus]
39+
# Offered by #61; useful only if A2ML becomes a document tab (it is not one today).
40+
a2ml = "blocky-writer .machine_readable/ (STATE.a2ml, ECOSYSTEM.a2ml, CLADE.a2ml, contractiles)"
41+
asciidoc = "blocky-writer docs/ecosystem/ECOSYSTEM.adoc"
42+
markdown = "blocky-writer wiki/ (BerryWiki)"

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0
5050

5151
### Documentation
5252

53+
- docs: declare the precision-document-suite boundary (viewer/editor stays here; PDF placement is blocky-writer) (#61)
5354
- docs: add post-audit status report for M5 sweep
5455
- docs: add TEST-NEEDS.md (CRG C)
5556
- docs: add EXPLAINME.adoc — prove-it file backing README claims

‎EXPLAINME.adoc‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
// SPDX-License-Identifier: CC-BY-SA-4.0
22
// Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
3-
= DocMatrix — Show Me The Receipts
3+
= Formatrix Docs — Show Me The Receipts
44
:toc:
55
:icons: font
66

77
The README makes claims. This file backs them up.
88

99
[quote, README]
1010
____
11-
This project must declare **MPL-2.0-or-later** for platform/tooling compatibility.
11+
Formatrix Docs is the tabbed viewer and editor of one logical document.
1212
____
1313

1414
== Technology Choices
@@ -35,8 +35,27 @@ https://github.com/hyperpolymath/gossamer[gossamer].
3535
|===
3636
| Path | What's There
3737

38-
| `src/` | Source code
38+
| `crates/formatrix-core/` | Unified AST, parsers, renderers (seven `SourceFormat`s)
3939
| `ffi/` | Foreign function interface
40+
| `docs/ecosystem/ECOSYSTEM.adoc` | Suite boundary vs DocMatrix and blocky-writer
41+
|===
42+
43+
== Suite boundary
44+
45+
[cols="1,2"]
46+
|===
47+
| Claim | Where it is checked
48+
49+
| We are Formatrix Docs, not DocMatrix
50+
| `README.adoc` title and "Precision document suite" section;
51+
`docs/ecosystem/ECOSYSTEM.adoc`
52+
53+
| Viewing/editing stays here; PDF form placement stays in blocky-writer
54+
| https://github.com/hyperpolymath/formatrix-docs/issues/61[formatrix-docs#61];
55+
`.machine_readable/integrations/blocky-writer.a2ml`
56+
57+
| Proof obligations do not transfer
58+
| https://github.com/hyperpolymath/docmatrix/issues/71[docmatrix#71]
4059
|===
4160

4261
== Questions?

‎README.adoc‎

Lines changed: 35 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
// SPDX-License-Identifier: CC-BY-SA-4.0
22
// Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
33
image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[MPL-2.0-or-later,link="https://opensource.org/licenses/MPL-2.0"]
4-
= DocMatrix
5-
image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=openssourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/formatrix-docs"]
4+
= Formatrix Docs
5+
image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/formatrix-docs"]
66

77

88

@@ -20,18 +20,46 @@ This project must declare **MPL-2.0-or-later** for platform/tooling compatibilit
2020

2121
Philosophy: **Palimpsest**. The MPL-2.0 (PMPL) text is provided in `license/MPL-2.0.txt`, and the canonical source is the palimpsest-license repository.
2222

23-
Cross-platform document editor with format tabs (TXT/MD/ADOC/DJOT/ORG/RST/TYP). Gossamer GUI + Ada TUI. Graph visualization, OCR, TTS/STT, Nickel pipelines.
23+
Formatrix Docs is the tabbed viewer and editor of one logical document
24+
(TXT/MD/ADOC/DJOT/ORG/RST/TYP). Gossamer GUI + Ada TUI. Graph visualization,
25+
OCR, TTS/STT, and Nickel pipelines are in-tree capabilities of *this* project.
26+
Multi-format conversion is the separate
27+
https://github.com/hyperpolymath/docmatrix[DocMatrix] project; GUI, TUI, graph,
28+
and editor claims must not be attributed to DocMatrix.
2429

2530
== Features
2631

2732
* *Format Tabs* - View and edit the same document in multiple markup formats
28-
* *Unified AST* - Lossless conversion between formats
33+
* *Suite boundary* - Viewing/editing stays here; conversion is DocMatrix; PDF placement is Blocky Writer
34+
* *Unified AST* - Shared representation behind the format tabs
2935
* *GUI* - Gossamer with AffineScript frontend
3036
* *TUI* - Ada with AdaCurses for terminal usage
3137
* *Graph Visualization* - ArangoDB for document relationships
3238
* *Accessibility* - OCR, TTS, STT support
3339
* *Pipelines* - Nickel-based import/export transformations
3440

41+
== Precision document suite
42+
43+
Formatrix Docs owns exactly one thing: **tabbed viewing and editing of one
44+
logical document**. Synchronised editing across tabs is the intended
45+
progression.
46+
47+
It deliberately does *not* do any of the following, and each has an owner:
48+
49+
* Multi-format conversion and precision coordination — https://github.com/hyperpolymath/docmatrix[DocMatrix]
50+
* Fixed-layout PDF and application-form placement — https://github.com/hyperpolymath/blocky-writer[Blocky Writer]
51+
52+
Viewer/editor behaviours such as cursor mapping, synchronised tabs, and
53+
undo/redo are proved here. Conversion round-trips are proved in DocMatrix.
54+
Page-coordinate geometry is proved in Blocky Writer. Those proof obligations
55+
do not transfer.
56+
57+
The versioned composition contract is
58+
https://github.com/hyperpolymath/docmatrix/issues/71[docmatrix#71]. The
59+
long-form boundary statement — including the `detect_blocks` seam Blocky Writer
60+
emits, recorded so neither side invents it twice — is
61+
link:docs/ecosystem/ECOSYSTEM.adoc[docs/ecosystem/ECOSYSTEM.adoc].
62+
3563
== Supported Formats
3664

3765
[cols="1,2", options="header"]
@@ -143,7 +171,10 @@ MPL-2.0 with Palimpsest philosophy.
143171

144172
== Links
145173

174+
* link:docs/ecosystem/ECOSYSTEM.adoc[Suite boundary (long form)]
146175
* link:.machine_readable/6a2/STATE.a2ml[Project State]
147176
* link:.machine_readable/6a2/ECOSYSTEM.a2ml[Ecosystem Position]
148177
* link:.machine_readable/6a2/META.a2ml[Architecture Decisions]
149178
* link:PALIMPSEST.adoc[Palimpsest Philosophy]
179+
* https://github.com/hyperpolymath/docmatrix[DocMatrix]
180+
* https://github.com/hyperpolymath/blocky-writer[Blocky Writer]

‎TOPOLOGY.md‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,15 @@ SPDX-License-Identifier: CC-BY-SA-4.0
33
Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
44
-->
55
<!-- TOPOLOGY.md — Project architecture map and completion dashboard -->
6-
<!-- Last updated: 2026-02-19 -->
6+
<!-- Last updated: 2026-10-10 -->
77

8-
# DocMatrix (formatrix-docs) — Project Topology
8+
# Formatrix Docs — Project Topology
9+
10+
This repository is the tabbed viewer/editor of one logical document.
11+
Conversion belongs to [DocMatrix](https://github.com/hyperpolymath/docmatrix);
12+
fixed-layout PDF placement belongs to
13+
[blocky-writer](https://github.com/hyperpolymath/blocky-writer).
14+
See `docs/ecosystem/ECOSYSTEM.adoc`.
915

1016
## System Architecture
1117

@@ -60,7 +66,7 @@ Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
6066
COMPONENT STATUS NOTES
6167
───────────────────────────────── ────────────────── ─────────────────────────────────
6268
CORE ENGINE (RUST)
63-
Unified AST ██████████ 100% Lossless conversion stable
69+
Unified AST ██████████ 100% Shared representation behind the format tabs
6470
Format Parsers (MD/ADOC/etc) ████████░░ 80% Typst parser refining
6571
Nickel Pipeline Executor ██████████ 100% Transformations active
6672
ArangoDB Client ██████████ 100% Document persistence stable

‎docs/MOSCOW-REQUIREMENTS.adoc‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ This document defines Must/Should/Could requirements for each component of the d
102102
|🔲 Pending
103103

104104
|FD-S06
105-
|Print/export to PDF
105+
|Print/export to PDF (render of the logical document; AcroForm placement is blocky-writer — see `docs/ecosystem/ECOSYSTEM.adoc`)
106106
|🔲 Pending
107107

108108
|FD-S07
@@ -137,7 +137,7 @@ This document defines Must/Should/Could requirements for each component of the d
137137
|ID |Requirement |Status
138138

139139
|FD-C01
140-
|Graph view (document links visualization)
140+
|Graph view (document links visualization; page-coordinate overlays consume blocky-writer `detect_blocks` — formatrix-docs#61)
141141
|🔲 Pending
142142

143143
|FD-C02
@@ -715,6 +715,17 @@ This document defines Must/Should/Could requirements for each component of the d
715715
|🔲 Pending
716716
|===
717717

718+
=== Seam 6: Formatrix ↔ blocky-writer
719+
720+
[cols="1,4,2",options="header"]
721+
|===
722+
|ID |Seam Requirement |Status
723+
724+
|SEAM-6A
725+
|Consume blocky-writer `detect_blocks` shape (fields: label, x, y, width, height; PDF user space) if graph views show where a value lands. Shape recorded; no integration proposed (formatrix-docs#61).
726+
|⚪ Recorded
727+
|===
728+
718729
== Ecosystem-Level Requirements (v1 Publish)
719730

720731
=== MUST Have for v1

‎docs/SEAM-CHECK-MUSTS.adoc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ This document validates integration seams between ecosystem components after imp
2020
| Recon-Silly-Ation | recon-silly-ation | ✓ Implemented
2121
| Docubot | recon-silly-ation/Docubot.res | ✓ Implemented
2222
| Docudactyl | recon-silly-ation/Docudactyl.res | ✓ Implemented
23+
| blocky-writer | blocky-writer | Boundary declared (formatrix-docs#61); no integration
2324
|===
2425

2526
== SEAM-1: Formatrix ↔ RSA
@@ -276,6 +277,37 @@ Different field structures between Protocol.res and Docubot.res.
276277

277278
**Resolution:** Harmonize audit log schemas.
278279

280+
== SEAM-6: Formatrix ↔ blocky-writer
281+
282+
Inbound notice: https://github.com/hyperpolymath/formatrix-docs/issues/61[formatrix-docs#61].
283+
Long form: link:ecosystem/ECOSYSTEM.adoc[docs/ecosystem/ECOSYSTEM.adoc].
284+
Machine-readable: link:../.machine_readable/integrations/blocky-writer.a2ml[`.machine_readable/integrations/blocky-writer.a2ml`].
285+
286+
No integration is proposed. The seam is recorded so neither side invents a
287+
second, incompatible shape.
288+
289+
=== SEAM-6A: `detect_blocks` widget geometry
290+
291+
[cols="2,2,1"]
292+
|===
293+
| blocky-writer (`rust/pdftool_core`) | Formatrix Docs consumer | Status
294+
295+
| `Block` with fields label, x, y, width, height (`f32` coordinates, PDF user space)
296+
| Optional overlay on graph / relationship views (FD-C01)
297+
| ⚪ RECORDED, not consumed
298+
299+
| `label` from AcroForm `/T`, else parent `/T`, else `field_<page>_<index>`
300+
| Display name for a landed value
301+
| ⚪ RECORDED, not consumed
302+
|===
303+
304+
==== Note: Not an integration
305+
306+
blocky-writer owns placement. Formatrix Docs owns viewing and editing. A green
307+
editor test does not prove page geometry, and exact page coordinates do not
308+
prove semantic correctness. Do not add a second JSON shape for "where a value
309+
lands in a PDF".
310+
279311
== Summary of Gaps
280312

281313
=== Critical (Must Fix for v1)
@@ -318,6 +350,7 @@ Will implement in SHOULDs phase.
318350
| SEAM-3 | RSA | Docudactyl | ⚠️ 4 gaps
319351
| SEAM-4 | Docubot | Docudactyl | ✓ 1 minor gap
320352
| SEAM-5 | All | ArangoDB | ❌ Not implemented
353+
| SEAM-6 | Formatrix Docs | blocky-writer | ⚪ Boundary declared; seam recorded, not consumed
321354
|===
322355

323356
== Next Steps

0 commit comments

Comments
 (0)