Skip to content

Architectural Decisions

ADRs (Architecture Decision Records) capture the rationale behind binoc's design — including alternatives that were considered and rejected. They are the canonical long-form record of the project's reasoning.

Newer entries appear first. Each entry shows its date and current status. Create a new ADR with just adr <title>. See the Documentation platform ADR for how this index is produced and how ADRs fit into the docs site.

Date Title Status
2026-06-30 Fat-binoc Distribution and the ABI Canary Accepted; implemented
2026-06-29 SDK Annotation Package Identity Stays Explicit Accepted
2026-06-29 Renderers Are Ecosystem-Ignorant; Ugly Output From an Unknown Rule Is an Upstream Bug Accepted
2026-06-29 Memory and Wall-Clock Contract for Large Dataset Diffs Proposed
2026-06-29 Inference Is Allowed, But Always Disclosed and Overridable; the High-Churn Guardrail Is the Backstop Accepted
2026-06-29 Feedback Report Bundles for Imperfect Results Implemented
2026-06-29 Binary Byte-Range Edit Kind Proposed
2026-06-29 A Unified Per-Path Dataset Config Model Accepted
2026-06-22 The Vintage Audience: a Kept Benchmark for Metadata-Over-Data Reading Accepted (benchmark landed; features deliberately deferred)
2026-06-15 Tiered Artifact Metadata: Column, Table, and a parser_metadata_v1 Artifact Implemented (channels + producers in CFM-80; rendering + significance in CFM-82)
2026-06-15 The Engine Overhaul, Told Whole: Single-Tree to Correspondence-First Retrospective
2026-06-15 Partition Identities: a JIT, Format-Owned Capability for N↔M Correspondence (CFM-72) Implemented
2026-06-15 Multi-Input Claims: Grouping Sibling Files into One Logical Dataset Implemented (CFM-83; supersedes the earlier registry/composite-node framing of this ADR)
2026-06-15 Composable Per-Artifact Writers: the Artifact Is the Rendering Unit Implemented (CFM-81)
2026-06-14 Typed Records: a Greenfield tabular Artifact and a Generic structured_document Accepted
2026-06-14 Parsed Children and Decompose Boundaries (CFM-69) Accepted
2026-06-14 Default Markdown Is A Changelog, Not An IR Dump Implemented
2026-06-13 Stable ABI Tier Assessment for CFM-27b Implemented
2026-06-13 Derive Parse-Rule Link Gating from Pair Reads Implemented
2026-06-13 CFM-44 Measured Correspondence Performance Implemented
2026-06-12 Tiered Plugin Surface During Pre-1.0: In-Process Proposed Tier, ABI Stable Tier Accepted
2026-06-12 Invariant and Lint Tiers: Harness, Mechanical, Agent Implemented
2026-06-12 Correspondence-First Engine: Two Trees, Links, and Edit-List Compaction Accepted (prototype validated; migration gated by structural projection)
2026-06-12 Binoc: the architecture, told as a story Historical
2026-06-11 Inline Pure-Reorder Judgment; Retire Tag-Handoff Layering Implemented
2026-06-11 Declared Write-Sets on TransformerDescriptor Superseded in part by Correspondence-First EngineTransformerDescriptor was removed in the migration; the write-set discipline carried over to rule descriptors and is mechanized in Invariant and Lint Tiers
2026-06-03 Transformer-Initiated Recompare as a Correspondence Contract Superseded by Correspondence-First Engine
2026-06-03 Structured Summary Segments Implemented
2026-06-03 Progressive Renderer Annotations Implemented
2026-06-03 Error Diagnostics Are Reportable Findings Implemented
2026-06-02 Markdown Renderer Groups Replace Significance-Map Grouping Implemented
2026-06-01 Unified Dataset Config and Identity Policy Superseded by A Unified Per-Path Dataset Config Model
2026-06-01 Tabular Collection Artifact Model Accepted
2026-06-01 Single-stream gzip as an expanding comparator Implemented
2026-06-01 Optional First-Party Plugins and binoc[all] Superseded by Fat-binoc Distribution and the ABI Canary
2026-06-01 Example Verbosity and Plugin-Supplied Details Decided
2026-06-01 Diagnostics Channel for Non-Fatal Warnings and Suggestions Implemented
2026-05-13 Rename-and-modify detection: fuzzy correlation + transformer-initiated re-dispatch Superseded in part by Correspondence-First Engine
2026-04-17 Documentation Platform and Information Design Proposed
2026-04-16 Transient Fields Are Wire-Visible; Output Stripping Is a Boundary Concern Implemented
2026-04-16 Transformer dispatch: bottom-up by default, Root for tree-wide walkers Implemented
2026-04-16 Test vector materialization: plugin trait, not a runtime plugin point Implemented
2026-04-16 Opportunistic ItemRef Metadata, Transformer-Hydrated for Correlation Implemented
2026-04-10 Security posture and how to audit Binoc (core and plugins) Accepted
2026-04-10 Rust MSRV and dependency update policy Implemented (MSRV raised to 1.95 on 2026-06-29 — see Addendum)
2026-04-10 Independent release tags and published version policy Implemented
2026-04-08 Release Surface And Automated Publishing Implemented
2026-03-20 Transformer Dispatch Refinement Implemented
2026-03-20 Transformer Composition and Artifact Flow Superseded in part by Correspondence-First Engine
2026-03-19 Published artifacts for cross-plugin composition Implemented
2026-03-18 Terminology Accepted; updated by the 2026-06-12 correspondence-first migration
2026-03-12 Plugin SDK, ABI Safety, and Native Plugin Loading Implemented
2026-03-09 Test Vector Root Defaults and Plugin Test Vectors Implemented
2026-03-09 Standard Library Boundary Policy Accepted
2026-03-09 Shared Test-Vector Harness for Plugins Implemented
2026-03-09 Per-Renderer Config and Significance as a Renderer Concern Decided (implemented)
2026-03-09 Output Routing and CLI UX Implemented
2026-03-09 Deferred Performance Optimizations Decided (not pursuing)
2026-03-06 just as the Canonical Task Runner Implemented
2026-03-06 Tutorial Regeneration Is a Build Step, Not a Test Implemented
2026-03-06 Plugin Discovery and the Rust/Python Boundary Implemented
2026-03-05 Snapshot Testing for Test Vectors Implemented
2026-03-05 Provenance Tracking and the Extract Chain Implemented
2026-03-05 Media Type Detection and Content-Aware Dispatch Implemented (phase 1)
2026-03-05 Full Comparison Tree and Content Hash Propagation Superseded in part by Correspondence-First Engine
2026-03-05 Cross-Phase Data Cache in CompareContext Superseded by Published artifacts for cross-plugin composition and Correspondence-First Engine