From 82d2d561afc19def8b070c8dc2aaa30741c4a70b Mon Sep 17 00:00:00 2001 From: jedarden Date: Sun, 5 Jul 2026 22:50:03 -0400 Subject: [PATCH] docs(bf-24wu4): update plan.md layout to v1.2 with shipped workspace reconciliation - Update version from 1.1 to 1.2 (dated 2026-07-05) - Add revision 1.2 entry documenting workspace reconciliation - Expand File and Module Layout tree to include all shipped artifacts: - crates/pdftract-libpdftract (C ABI) - crates/pdftract-cer-diff (CER diff tool) - crates/pdftract-schema-migrate (schema migration tool) - xtask/ (build automation utilities) - sdk/ (PHP and Python subprocess SDKs) - templates/sdk-skeleton/ (SDK template) - e2e/phone-smoke/ (E2E phone smoke tests) - profiles/ (built-in and community profiles) - ci/ (CI gate scripts) - tools/ (fixture generation and debugging tools) - docs/user-docs/ (user-facing documentation) - Language SDK repositories (Node, Java, .NET, Go, Ruby, PHP, Swift) - Add SDK cross-reference to docs/notes/sdk-architecture.md - No semantic changes to phase specifications Verification: notes/bf-24wu4.md Closes: bf-24wu4 --- docs/plan/plan.md | 72 +++++++++++++++++++++++++++++++++++++++++++---- notes/bf-24wu4.md | 70 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 137 insertions(+), 5 deletions(-) create mode 100644 notes/bf-24wu4.md diff --git a/docs/plan/plan.md b/docs/plan/plan.md index f405946..bc588f2 100644 --- a/docs/plan/plan.md +++ b/docs/plan/plan.md @@ -1,9 +1,9 @@ # pdftract Implementation Plan -**Version:** 1.1 -**Status:** Active -**Repo:** jedarden/pdftract -**Last updated:** 2026-05-16 +**Version:** 1.2 +**Status:** Active +**Repo:** jedarden/pdftract +**Last updated:** 2026-07-05 --- @@ -13,6 +13,7 @@ |---|---|---| | 1.0 | 2026-05-16 | Initial plan: Phases 0–7, vector + OCR extraction, JSON/NDJSON/text output, PyO3 bindings, HTTP serve, StructTree, tables, forms, signatures, attachments. | | 1.1 | 2026-05-16 | Brilliant-ideas integration round: added MCP server (Phase 6.7), Markdown output (6.5), multi-output emission (6.6), visual citation receipts (6.8), content-addressed cache (6.9), folder grep (7.8), inspector web viewer (7.9), document profiles (7.10), structural fingerprint (1.7), remote HTTP range source (1.8), document type classification (5.6). Plus pre-flight categories 1–4: Non-Goals, Glossary, ADRs, Open Questions, Proof Obligations, Acceptance Scenarios, Edge Case Catalog, Failure Mode Taxonomy, Diagnostic Code Catalog, Cross-Cutting Concerns, Anti-Patterns Catalog, Invariants. | +| 1.2 | 2026-07-05 | Workspace reconciliation: updated File and Module Layout to reflect shipped artifacts missing from v1.1 tree — added C ABI library (pdftract-libpdftract), CER diff tool (pdftract-cer-diff), schema migration tool (pdftract-schema-migrate), xtask build utilities, SDK skeleton templates, language SDK bindings (Node, Java, .NET, Go, Ruby, PHP, Swift), Python subprocess SDK, E2E phone smoke tests, built-in profiles at repo root, CI gate scripts, and tools directory. Cross-referenced SDK strategy to docs/notes/sdk-architecture.md. No semantic changes to phase specifications. | Future revisions MUST append a new row before any material change lands in subsequent sections. The revision history is the single source of truth for "what changed when" — section-level edits MUST NOT silently mutate already-shipped semantics. @@ -235,8 +236,39 @@ pdftract/ │ │ └── verify_receipt.rs (Phase 6.8) │ ├── pdftract-py/ │ │ └── src/lib.rs (PyO3 bindings, Phase 6.3) +│ ├── pdftract-libpdftract/ +│ │ └── src/lib.rs (C ABI library; FFI layer for C/C++ integrations) +│ ├── pdftract-cer-diff/ +│ │ └── src/main.rs (Character error rate diff tool; compares extractions) +│ ├── pdftract-schema-migrate/ +│ │ └── src/main.rs (Schema migration tool; validates/translates schema versions) │ └── pdftract-inspector-ui/ │ └── ... (HTML/CSS/JS bundled via include_bytes!, Phase 7.9) +├── xtask/ +│ ├── Cargo.toml +│ └── src/ +│ ├── main.rs (Build automation tasks: codegen, dist, schema generation) +│ ├── migrate/ (Schema migration utilities) +│ └── bin/ (Generated executables) +├── sdk/ +│ ├── php/ (PHP subprocess SDK) +│ └── python-subprocess/ (Python subprocess SDK) +├── templates/ +│ └── sdk-skeleton/ (SDK template for new language bindings) +├── Language SDK repositories (sibling repos under jedarden/): +│ ├── pdftract-node/ (Node.js/TypeScript SDK) +│ ├── pdftract-java/ (Java SDK) +│ ├── pdftract-dotnet/ (.NET SDK) +│ ├── pdftract-go/ (Go SDK) +│ ├── pdftract-ruby/ (Ruby SDK) +│ ├── pdftract-php/ (PHP SDK) +│ ├── pdftract-swift/ (Swift SDK) +│ └── swift-sdk/ (Swift native SDK) +├── e2e/ +│ └── phone-smoke/ (End-to-end phone smoke tests) +├── profiles/ +│ ├── builtin/ (Built-in document profiles; Phase 7.10) +│ └── community/ (Community-contributed profiles) ├── benches/ │ └── competitors/ │ ├── requirements.txt (pdfminer.six, pypdf, pdfplumber pins) @@ -244,12 +276,40 @@ pdftract/ ├── build/ │ ├── font-fingerprints.json (Phase 2.2 Level 3 source data) │ └── glyph-shapes.json (Phase 2.5 shape DB source data) +├── ci/ +│ ├── rustdoc-gate.sh (Documentation coverage gate) +│ ├── schema-gate.sh (Schema validation gate) +│ └── wer-gate.sh (Word error rate gate) +├── tools/ +│ ├── README.md (Tools documentation) +│ ├── convert_pdf_to_scanned.sh (PDF to scanned image converter) +│ ├── count_docs.py, count_docs.sh (Documentation counters) +│ ├── count_public_api.py (Public API surface counter) +│ ├── generate_encoding_fixtures.py, .rs (Encoding test fixture generator) +│ ├── generate_encrypted_pdf_fixtures.py, .rs (Encrypted PDF fixture generator) +│ ├── generate_invoice_fixture.rs, .py (Invoice test fixture generator) +│ ├── generate_stress_pdf.py (Stress test PDF generator) +│ ├── build-objstm-fixture/ (Object stream fixture builder) +│ ├── build-xref-fixture/ (XRef fixture builder) +│ ├── debug-fingerprint/ (Font fingerprint debugging utilities) +│ └── debug-fingerprint-diff/ (Fingerprint diff utilities) ├── docs/ │ ├── plan/plan.md (this document) │ ├── research/ (per-feature deep dives referenced from phases) │ ├── schema/v1.0/pdftract.schema.json (Phase 6.1 deliverable) │ ├── integrations/ (MCP config snippets, IDE setup; populated post-v1) -│ └── notes/ (sdk-architecture.md, sdk-invocation.md, etc.) +│ ├── user-docs/ (User-facing documentation) +│ ├── notes/ +│ │ ├── sdk-architecture.md (SDK strategy and architecture — SEE: SDK cross-reference) +│ │ ├── sdk-conformance-runner.md (SDK conformance test runner) +│ │ ├── sdk-contract.md (SDK contract specification) +│ │ ├── sdk-invocation.md (SDK invocation patterns) +│ │ └── ... (Additional project notes) +│ ├── adr/ (Architecture Decision Records) +│ ├── operations/ (Operational procedures) +│ ├── security/ (Security documentation) +│ ├── conformance/ (Conformance test specifications) +│ └── research-index.md (Research document index) └── tests/ └── fixtures/ ├── vector/ (clean LaTeX/Word/InDesign PDFs) @@ -265,6 +325,8 @@ pdftract/ └── profiles/ (per-profile fixture sets, Phase 7.10) ``` +**SDK cross-reference:** The SDK strategy and architecture is documented in [`docs/notes/sdk-architecture.md`](docs/notes/sdk-architecture.md). Language SDK repositories are sibling repositories under the `jedarden/` organization; each SDK implements the contract specified in the SDK architecture document. + The layout is normative: phase-specific code MUST land in the file indicated for its phase. New top-level modules added in future revisions MUST be reflected here in the same plan revision that introduces them. --- diff --git a/notes/bf-24wu4.md b/notes/bf-24wu4.md new file mode 100644 index 0000000..eb3e288 --- /dev/null +++ b/notes/bf-24wu4.md @@ -0,0 +1,70 @@ +# bf-24wu4 Verification Note + +## Task +Update plan.md layout section and revision history to match the shipped workspace. + +## Work Completed + +### 1. Updated plan.md version and metadata +- **File:** `/home/coding/pdftract/docs/plan/plan.md` +- **Changes:** + - Updated version from 1.1 to 1.2 + - Updated last updated date from 2026-05-16 to 2026-07-05 + +### 2. Added Revision 1.2 entry +Added a new row to the Revision History table: + +| Version | Date | Material Changes | +|---|---|---| +| 1.2 | 2026-07-05 | Workspace reconciliation: updated File and Module Layout to reflect shipped artifacts missing from v1.1 tree — added C ABI library (pdftract-libpdftract), CER diff tool (pdftract-cer-diff), schema migration tool (pdftract-schema-migrate), xtask build utilities, SDK skeleton templates, language SDK bindings (Node, Java, .NET, Go, Ruby, PHP, Swift), Python subprocess SDK, E2E phone smoke tests, built-in profiles at repo root, CI gate scripts, and tools directory. Cross-referenced SDK strategy to docs/notes/sdk-architecture.md. No semantic changes to phase specifications. | + +### 3. Updated File and Module Layout tree +Expanded the layout tree to include all shipped artifacts that were missing from v1.1: + +**New crates added:** +- `crates/pdftract-libpdftract/` — C ABI library for C/C++ integrations +- `crates/pdftract-cer-diff/` — Character error rate diff tool +- `crates/pdftract-schema-migrate/` — Schema migration tool + +**New top-level directories added:** +- `xtask/` — Build automation tasks (codegen, dist, schema generation) +- `sdk/` — SDK implementations (php/, python-subprocess/) +- `templates/sdk-skeleton/` — SDK template for new language bindings +- `e2e/phone-smoke/` — End-to-end phone smoke tests +- `profiles/` — Built-in and community document profiles +- `ci/` — CI gate scripts (rustdoc-gate.sh, schema-gate.sh, wer-gate.sh) +- `tools/` — Utility scripts and tools for fixture generation and debugging + +**Language SDK repositories (sibling repos):** +- pdftract-node/ +- pdftract-java/ +- pdftract-dotnet/ +- pdftract-go/ +- pdftract-ruby/ +- pdftract-php/ +- pdftract-swift/ +- swift-sdk/ + +**Additional docs sections added:** +- `docs/user-docs/` — User-facing documentation +- Expanded `docs/notes/` section with SDK-related documentation references + +**SDK cross-reference added:** +Added a cross-reference note directing readers to `docs/notes/sdk-architecture.md` for SDK strategy and architecture details. + +### 4. Verification +- ✅ No semantic changes were made to shipped phase sections +- ✅ Layout tree now reflects the actual workspace structure as of 2026-07-05 +- ✅ All missing shipped artifacts from the task description have been added +- ✅ SDK architecture is properly cross-referenced +- ✅ Revision history properly documents the reconciliation + +## Commit +Committed as `docs(bf-24wu4): update plan.md layout to v1.2 with shipped workspace reconciliation` + +## Acceptance Criteria Status +- **PASS:** Append one revision 1.2 row describing the reconciliation ✅ +- **PASS:** Update the layout tree to the actual workspace ✅ +- **PASS:** Cross-reference SDK strategy to docs/notes/sdk-architecture.md ✅ +- **PASS:** Make no semantic changes to shipped phase sections ✅ +- **PASS:** Single plan-update bead for the 2026-07 gap review ✅