Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,11 @@ SPDX-License-Identifier: MPL-2.0
# Contributing to blocky-writer

**Read `README.adoc` first.** The short version of where this project stands:
the Rust/WASM core (`rust/pdftool_core`) is implemented, unit-tested and green
in CI. The AffineScript frontend (`src/*.affine`) is a prototype with no build
pipeline in this checkout. Nothing here is release-ready as a Firefox extension
yet.
the Rust/WASM core (`rust/pdftool_core`) is implemented and unit-tested. The
main baseline passed and PR #78 implementation revision `9f9370e` passed the
Rust CI job (run `41326285595` for the latter); other PR gates remain red. The
AffineScript frontend (`src/*.affine`) is a prototype with no build pipeline in
this checkout. Nothing here is release-ready as a Firefox extension yet.

---

Expand Down Expand Up @@ -135,8 +136,10 @@ See `SECURITY.adoc`.
cargo clippy --manifest-path rust/pdftool_core/Cargo.toml --locked --all-targets -- -D warnings
```

`cargo test` runs 6 tests. If you get a different number, something changed
and the wiki is stale — fix the wiki too.
The current `pdftool_core` source has 22 unit-test functions: 6 fill/error
tests, 14 detector tests, and 2 numeric-geometry tests. If the count changes,
update `TEST-NEEDS.adoc`, `EXPLAINME.adoc`, and the wiki in the same change.
Unit-test success is not a formal proof or general PDF conformance result.

If you cannot run these — no Rust toolchain, no crates.io access — **say so
explicitly in the PR** rather than implying you did. CI is the only authority
Expand Down
12 changes: 10 additions & 2 deletions CHANGELOG.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -46,13 +46,18 @@ not repeated verbatim — where a commit subject was mangled or carried an inlin

==== Fixed

* `+rust/pdftool_core+`: `+detect_blocks+` now accepts either PDF-defined
diagonal `/Rect` corner order, resolves indirect rectangle and numeric-object
chains with cycle protection, and reports malformed widget geometry using a
structured `+BW_PDF_WIDGET_RECT_INVALID+` error.
* `+rust/pdftool_core+`: resolved the two Clippy lints that were the only thing
keeping the `+Rust core (tests, formatting, lint)+` job red —
`+clippy::map_clone+` on `+doc.get_object(*id).map(Clone::clone)+` (now
`+.cloned()+`) and `+clippy::unnecessary_cast+` on
`+Object::Real(v) => Some(*v as f32)+` (now `+Some(*v)+`). The adjacent
`+Object::Integer+` cast was left alone because that `+i64+` → `+f32+` cast is real.
(#73)
`+Object::Integer+` cast was left alone because that `+i64+` → `+f32+` cast was real
at crate version 0.1.0. Version 0.2.0 subsequently widens the public `+Block+`
surface to `+f64+` (see *Changed* above). (#73)
* `+rust/pdftool_core+`: `+rustfmt+` applied so the formatting step of the
`+rust-core+` job passes. (e1b6225)
* `+actions.lock+` resynchronised after the #69/#70/#71 desync that startup-killed
Expand All @@ -77,6 +82,9 @@ not repeated verbatim — where a commit subject was mangled or carried an inlin

==== Changed

* `+rust/pdftool_core+` bumped to `+0.2.0+`; public `+Block+` coordinates now
use `+f64+`, and three new `+BW_*+` detector error codes are versioned as a
breaking contract change. Review compatibility before downstream adoption.
* `+.machine_readable/+` migrated from 6SCM to 6A2 (`+.scm+` → `+.a2ml+`).
* `+README.adoc+` gained an *Ecosystem position* section stating the boundary and
linking the other suite components, satisfying the first acceptance criterion
Expand Down
12 changes: 6 additions & 6 deletions EXPLAINME.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ declaration of anything.
|===
| Path | What's There

| `rust/pdftool_core/src/lib.rs` | The whole core: `detect_blocks`, `fill_blocks`, the field walkers, the `BW_*` error taxonomy, and 6 unit tests. ~1030 lines.
| `rust/pdftool_core/src/lib.rs` | The whole core: `detect_blocks`, `fill_blocks`, the field walkers, the `BW_*` error taxonomy, and 22 test functions (6 fill/error, 14 detector, 2 numeric-geometry). PR #78 implementation commit `9f9370e` passes Rust CI run `41326285595`.
| `src/*.affine` | AffineScript prototype: popup, content script, background script, `core/PdfTool`, `core/Storage`, `core/ProvenMount`, `components/Block`, `components/FormFiller`. Not buildable in this checkout.
| `public/` | `manifest.json`, `popup.html`, icons.
| `tests/aspect/` | Aspect-oriented test shell script.
Expand All @@ -47,11 +47,11 @@ declaration of anything.
|===
| Claim in the README | Where it is checked

| The Rust core is implemented and has unit tests
| `cargo test --manifest-path rust/pdftool_core/Cargo.toml --locked` — 6 tests, including AcroForm writeback for text/select and button widgets and the structured error taxonomy.
| The Rust core has unit tests
| The source contains 22 test functions: 6 fill/error tests, 14 detector tests, and 2 numeric-geometry guard tests. PR #78 implementation commit `9f9370e` passed all three Rust checks in run `41326285595`; synthetic tests do not establish general PDF conformance or formal proof.

| `cargo fmt`, `cargo test` and `cargo clippy -D warnings` all pass
| `.github/workflows/ci.yml`, job `Rust core (tests, formatting, lint)`. As of 2026-09-27 this job is green on `main` at `e1b6225`.
| `cargo fmt`, `cargo test` and `cargo clippy -D warnings` pass on the current implementation
| `.github/workflows/ci.yml`, job `Rust core (tests, formatting, lint)`. Run `41326285595` at `9f9370e` passed formatting, all 22 tests, and Clippy. Main baseline run `38818494415` at `3fd5ba1` is separate evidence.

| The frontend is a prototype with no build pipeline
| There is no AffineScript compiler configuration and no JavaScript package manifest in the tree. `deno.json` was deleted by #43.
Expand All @@ -60,7 +60,7 @@ declaration of anything.
| `apply_field_value` in `rust/pdftool_core/src/lib.rs`, dispatched on field type `Tx` / `Ch` / `Btn`.

| Errors carry structured codes
| `CoreErrorPayload { code, message, context }`; 20 `BW_*` codes.
| `CoreErrorPayload { code, message, context }`; 23 unique `BW_*` codes in the current source (20 baseline, 3 new). `pdftool_core` is bumped to `0.2.0` for the breaking public contract change; owner compatibility review remains open.

|===

Expand Down
24 changes: 16 additions & 8 deletions TEST-NEEDS.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

=== CRG Grade: C — ACHIEVED 2026-04-04

Last reviewed: 2026-09-27.
Last reviewed: 2026-11-01.

=== Current Test State

Expand All @@ -12,17 +12,25 @@ Last reviewed: 2026-09-27.
|Category |Count |Notes
|Test directories |1 |Location(s): /tests (aspect + fuzz placeholder)
|CI workflows |14 |`.github/workflows/*.yml`. `ci.yml` runs the Rust core checks; `actions.lock` is a file, not a workflow. See docs/ci/CHECK-DETERMINATIONS.adoc
|Unit tests |6 |Rust `pdftool_core` — `cargo test --manifest-path rust/pdftool_core/Cargo.toml --locked`
|Unit tests |22 in source |Rust `pdftool_core` — 6 fill/error tests, 14 detector tests, and 2 direct numeric-geometry tests. PR #78 implementation commit `9f9370e` passed formatting, all unit tests, and Clippy in run `41326285595`.
|===

=== What's Covered

* [x] Rust core unit tests (block detection, `fill_blocks_*` AcroForm writeback for
`Tx`/`Ch`/`Btn` fields, taxonomy errors) — 6 tests, all green on `main` at `e1b6225`
* [x] `cargo fmt -- --check` in CI — green
* [x] `cargo clippy --all-targets -- -D warnings` in CI — green (the two remaining
lints were fixed in #73)
* [x] `actions.lock` synchronisation gate (`lock-sync-gate.yml`) — green on `main`
* [x] Rust core baseline CI on `main` — run `38818494415` at `3fd5ba1`
passed formatting, tests, and Clippy (actor `hyperpolymath`). That run is
baseline evidence only.
* [x] PR #78 implementation revision `9f9370e` — run `41326285595` passed
formatting, all 22 unit tests, and Clippy. The synthetic fixtures exercise
PDF-defined corner ordering, chained indirect rectangles and numeric
references (including cycles), exact integer boundaries, null/dangling
annotations, and missing/unresolved/malformed widget geometry.
This is not real-world PDF corpus coverage or a formal proof receipt.
* [ ] `actions.lock` synchronisation gate — failing on PR run `41326285660`
and main run `38818494312`; the YAML uses `smtp-notify-action@v0.5.0` while
generated lock metadata records `v0.3.0`. Do not hand-edit the generated file.
* [ ] CodeQL and Hypatia — current PR jobs fail during `Set up job`; causes are
unknown, and the logs were unavailable.

=== Still Missing (for CRG B+)

Expand Down
18 changes: 9 additions & 9 deletions TOPOLOGY.adoc
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
== blocky-writer — Project Topology

....
Last updated: 2026-09-27
Status: Rust core green (fmt + 6 tests + clippy); frontend prototype, no build pipeline
Last updated: 2026-11-01
Status: main baseline and PR #78 Rust CI pass; implementation `9f9370e` passed run `41326285595` (22 tests); other merge gates remain blocked; frontend prototype, no build pipeline
....

=== System Architecture
Expand Down Expand Up @@ -65,20 +65,20 @@ EXTENSION LAYERS
Extension bundle pipeline ░░░░░░░░░░ 0% deno.json removed in #43; no toolchain

CORE (RUST/WASM)
pdftool_core (WASM) ████████░░ 80% detect_blocks + fill_blocks, 6 tests green
pdftool_core (WASM) ████████░░ 80% Project estimate; 9f9370e passes 22 Rust tests (run 41326285595), including chained-reference handling; no real-world PDF corpus or formal proof
AcroForm Writeback ████████░░ 80% Tx / Ch / Btn only; no Sig
Ruled-line & cell detection ░░░░░░░░░░ 0% NOT IMPLEMENTED — the "hand spacing" case
Error Taxonomy ██████████ 100% 20 stable BW_* codes
Error Taxonomy ████████░░ 80% 23 codes; 3 additions and f64 Block surface versioned in 0.2.0; owner review open

REPO INFRASTRUCTURE
Rust CI (fmt/test/clippy) ██████████ 100% ci.yml rust-core job — green
Lock Sync Gate ██████████ 100% lock-sync-gate.yml — green on main
Documentation ████████░░ 80% README/TOPOLOGY/wiki corrected 2026-09-27
.machine_readable/ ██████████ 100% STATE.a2ml tracking
Rust CI (fmt/test/clippy) ██████████ 100% PR #78 run 41326285595 passed on 9f9370e; main run 38818494415 also passed
Lock Sync Gate ░░░░░░░░░░ 0% PR run 41326285660 and main run 38818494312 fail on generated-lock drift
Documentation ████████░░ 80% Human-readable status refreshed 2026-11-01; machine state remains stale
.machine_readable/ ████░░░░░░ 40% STATE.a2ml exists but is stale; A2ML/DEED owner ruling pending
Containerfile ██████████ 100% Reproducible dev env

─────────────────────────────────────────────────────────────────────────────
OVERALL: █████░░░░░ ~50% Rust core ready; extension not release-ready
OVERALL: █████░░░░░ ~50% PR Rust checks pass; merge blocked by lock/analysis gates and review; extension not release-ready
....

=== Key Dependencies
Expand Down
174 changes: 147 additions & 27 deletions docs/ci/CHECK-DETERMINATIONS.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@ The record required by the estate stopping rule (hyperpolymath/standards#968,
#994): every CI check that has ever been red on `main` has exactly one of three
determinations -- *fixed*, *retired*, or *exempt* -- and none is ever closed by
muting it (`continue-on-error`, demotion to a warning, or silent removal).
The current-main snapshot below identifies active failures that are still
unresolved; this ledger remains incomplete until each receives an evidence-based
*fixed*, *retired*, or *exempt* determination. “Open” is not a fourth closure.

== Ledger

Expand Down Expand Up @@ -37,39 +40,156 @@ muting it (`continue-on-error`, demotion to a warning, or silent removal).
gone until the thing it would build exists.

| `rust-core` (CI)
| *Fixed -- awaiting one owner-triggered green run on `main`*
| 2026-09-27
| *Fixed on `main` and PR #78 implementation revision `9f9370e`*
| 2026-11-01
| Replacement for both retired jobs: `cargo fmt -- --check`, `cargo test
--locked`, `cargo clippy --all-targets -- -D warnings` on
`rust/pdftool_core`. It did execute once, contrary to the previous revision
of this row: run 36296845297 (push, `e1b6225`, actor `hyperpolymath`) got as
far as three of its steps -- *Check formatting* `success`, *Run unit tests*
`success` (6/6), *Run Clippy* `failure`. Clippy was the only red step and it
reported exactly two lints, both in `rust/pdftool_core/src/lib.rs`:
`clippy::map_clone` on `doc.get_object(*id).map(Clone::clone)` and
`clippy::unnecessary_cast` on `Object::Real(v) => Some(*v as f32)`. Both are
repaired in #73 (`.cloned()` and `Some(*v)` respectively); neither repair
weakens the gate, and the adjacent `Object::Integer(v) => Some(*v as f32)`
is deliberately left alone because that `i64` -> `f32` cast is real. The job
has *not* run with the repair in it: every run on #73's branch is
bot-triggered and refused at startup (<<actor>>), so the step is verified by
inspection only. This row therefore stays open until one run triggered by
`hyperpolymath` is green on `main`; if that run is red, the crate has a real
defect and this row becomes a repair item. It is not closed until such a run
exists.
--locked`, and `cargo clippy --all-targets -- -D warnings` on
`rust/pdftool_core`. The historical first run at `e1b6225` passed formatting
and six tests but failed two Clippy lints; #73 repaired those without
weakening the gate. Main push run `38818494415` at
`3fd5ba1ed3deee22288d3441b1f3a833246995e2` and PR run `41326285595` at
`9f9370e206ae8cc6dd3ac86cba3f0904e4838135` passed formatting, all 22 unit
tests, and Clippy. The latter validates the implementation revision only;
later Rust changes require a new receipt. Other PR gates remain unresolved.

| `Lock Sync Gate` / `actions.lock is in sync with the workflow YAML`
| *Fixed*
| 2026-09-27
| Red on `main` from #69 (2026-09-24) onward, and the cause of every other
workflow on `main` reporting `startup_failure` at d50a857 -- see
<<desync>>. Resynchronised in the fix for #67.
| *Open — failing on current `main` and PR #78*
| 2026-11-01
| The fix for #67 was valid at the time, but the lock drifted again after #74.
Main run `38818494312` at `3fd5ba1` and latest PR run `41326285660` at
`9f9370e` failed `Verify lockfile synchronisation`. The current workflow uses
`hyperpolymath/smtp-notify-action@v0.5.0`; the generated lock still records
`@v0.3.0`. The supported `gh actions-lock` generator is unavailable in this
sandbox, so the lock has deliberately not been hand-edited.
|===

== Current `main` run snapshot (2026-11-01)

Current `origin/main` is `3fd5ba1` (#75). PR #78's fork point is `c2b073e`
(#74), and its implementation revision is `9f9370e` (after merge commit `4a7be9e`).
The fork point and main
snapshot are shallow/grafted in this checkout, so ancestry is not inferred.
The following table records only outcomes on the stated main snapshot; PR #78
results are listed separately below.

[cols="2,1,1,3",options="header"]
|===
| Check / workflow | Run | Result | Evidence and current disposition

| Rust core (`CI`)
| `38818494415`
| Passed
| Push on `3fd5ba1`, actor `hyperpolymath`; formatting, tests, and Clippy all
succeeded. This is the main baseline; PR #78's separate Rust receipt is
`41326285595` at `9f9370e`.

| Governance / Actions lockfile verify
| `38818495000`
| Failed
| Push at `3fd5ba1`, actor `hyperpolymath`. Only `governance / Actions lockfile
verify` failed; its verification step failed. Other Governance jobs passed or
were explicitly skipped. Same visible lock drift as the standalone gate.

| Lock Sync Gate
| `38818494312`
| Failed
| Push at `3fd5ba1`, actor `hyperpolymath`; `Verify lockfile synchronisation`
failed. The workflow/lock mismatch is observable; do not replace the generated
lock by hand.

| Mirror to Git Forges
| `38818495057`
| Failed
| Push at `3fd5ba1`, actor `hyperpolymath`. mirror-bitbucket, mirror-gitea,
mirror-disroot, and mirror-codeberg failed; mirror-gitlab, mirror-sourcehut,
and mirror-radicle succeeded. Log retrieval
returned EOF; failure causes remain unknown.

| CodeQL Advanced
| `41099036814`
| Failed
| Scheduled run on `3fd5ba1`, actor `hyperpolymath`; both Analyze jobs failed at
`Set up job`. Log retrieval returned EOF, so cause is unknown.

| Hypatia Security Scan
| `41255373342`
| Failed
| Scheduled run on `3fd5ba1`, actor `hyperpolymath`;
`Hypatia Neurosymbolic Analysis` failed at `Set up job`. Log retrieval
returned EOF, so cause is unknown.

| Secret Scanner / GitHub Pages
| `38818495110` / `38818494311`
| Passed
| Both passed on the `3fd5ba1` main push, actor `hyperpolymath`.
|===

== Also red on `main`?
The only root cause established in this snapshot is the generated Actions lock
drift. Do not attribute the setup-step or mirror failures to code, credentials,
network, or remote policy without accessible evidence.

== PR #78 run snapshot (implementation revision `9f9370e`)

The session branch at `9f9370e206ae8cc6dd3ac86cba3f0904e4838135` passed the
Rust workflow in run `41326285595`: formatting, all 22 unit tests, and Clippy
passed. This includes chained indirect `/Rect` resolution and cycle checks. The
receipt confirms CI-tested behavior for that exact implementation commit; it is
not a formal proof, general PDF conformance result, or final merge receipt.

[cols="2,1,1,3",options="header"]
|===
| Check / workflow | Run | Result | Evidence and current disposition

| Rust core (`CI`)
| `41326285595`
| Passed
| `Rust core (tests, formatting, lint)` passed all three steps at `9f9370e`.

| Lock Sync Gate
| `41326285660`
| Failed
| `Verify lockfile synchronisation` failed. The generated action lock remains
out of sync; its visible `smtp-notify-action` entry is stale. Do not hand-edit it.

| CodeQL Advanced
| `41326285683`
| Failed
| `Analyze (actions)` and `Analyze (javascript-typescript)` failed at `Set up job`.
Cause unknown; logs were unavailable.

| Hypatia Security Scan
| `41326285619`
| Failed
| `Hypatia Neurosymbolic Analysis` failed at `Set up job`. Cause unknown; logs
were unavailable.

| Governance / Secret Scanner (earlier PR runs)
| `41325016132` / `41325016140`
| Failed before jobs
| GitHub reported a generic workflow-file issue and created no jobs. Cause not
established; do not infer it from the lock gate alone.

| GitGuardian / SonarCloud / Semgrep
| PR checks / scan `258901955`
| Passed
| These providers reported green on the `9f9370e` implementation revision.

| CodeRabbit
| PR check / review
| Skipped / changes requested
| The check was skipped after review allowance was exhausted. The prior review
is still `CHANGES_REQUESTED` on `0224ef6`; it has not been refreshed after the
later code revisions.
|===

The pull request remains blocked. Do not bypass the failed lock/analysis gates or
the outstanding review decision. If the implementation changes, record and use
new run IDs rather than carrying these receipts forward.

== Historical red checks for #67

Yes, for both checks named in #67, and for reasons that have nothing to do
with the `actions.lock` cure (#66) that surfaced them:
At the time of #67, both checks named in that fix were red for reasons that had
nothing to do with the `actions.lock` cure (#66) that surfaced them:

* `core-fill-tests` and `extension-build` were red on every run since #43,
which predates #66 by a month. #66 revived the workflow that runs them; it
Expand Down
Loading
Loading