Skip to content

docs: reconcile design §10 against as-built code, apply C1–C25 - #106

Merged
Wahbeh-Mohammad merged 1 commit into
mainfrom
docs-reconcile-design-deviations
Sep 26, 2026
Merged

Wahbeh-Mohammad merged 1 commit into
mainfrom
docs-reconcile-design-deviations

Conversation

@Wahbeh-Mohammad

Copy link
Copy Markdown
Contributor

docs: reconcile design §10 against as-built code, apply C1–C25

Audits all nineteen entries of design §10, the normative deviation
ledger, against the as-built tree (gems/**/lib, sig/, the suites)
rather than against the phase documents that produced it, applies the
amendment set phase 10 wrote out, and consolidates every phase's as-built
Deviation Ledger into the chapter. Both halves of the first-release
blocker phase 10 left for a human are done.

Seven entries hold exactly as written (3, 7, 8, 11, 14, 16, 19). Five
hold and gain a dated clause carrying a narrower as-built fact a phase
ledger recorded (1, 2, 4, 9, 15). Seven were wrong about the code and
are corrected in place, each with a "[Corrected/Amended 2026-09-25: ...]"
note quoting what it replaced rather than a silent overwrite:

5 "the only entries that are not mechanism substitutions", and the
socket-closing hook attributed to "an adapter" -- only the two
transports own a socket (C12)
6 the trail is Dexpace::Suppressible, not Dexpace::Error#suppressed
(C14); a frozen primary is a documented no-op (4b P4-13)
10 send(:new) bypasses .build but not validation; .allocate and duck
typing are the holes left (C19, re-measured on 4.0.6 and 3.2.11)
12 the I/O ownership rule is IO-6, not the retired SEAM-3 (C3)
13 the encode profiles take the value first (C18); the buffer
profile takes a mutable BINARY String only (7a P7-5)
17 its last clause described a close path that does not exist:
Pool#close takes no token and is bounded by shutdown_timeout
(8b P8-24, C21)
18 omitted SSE-19's two rejecting caps (C15), the per-call ceiling
(5a P5-56) and the pacing parser's digit bound (6a P6-61)

The chapter's opening claim -- two unmet MUSTs and nothing else
narrowed -- is corrected too. Consolidating the ledgers adds entries
20-38, one per group of genuine deviations from the reference contract
the phases recorded and §10 did not, each citing its ledger row and the
as-built file. Three are MUST clauses unmet on a stated domain and are
admitted, not argued: SERDE-27's no-materialisation clause in the JSON
codec (7a P7-1), TRANSPORT-14 on the async transport (8c P8-38, with the
TRANSPORT-27 half no row carried), and HTTP-45's no-pinning clause for a
second fiber of one thread with no scheduler (3b P3-27), which reached
neither §10, §12 nor docs/first-release.md until now. Rows that record
only a departure from the design or the plan, with the specification met
exactly, are not deviations and are not carried.

Applies C1-C19 to §3, §4, §8, §9, §10, §11 and §12 after re-verifying
each against the code; all nineteen held, C19 narrowed to HTTP domain
models (Pipeline::Entry validates in .build alone) and C8 re-measured
against the resolved bundle. C11 is a dated recommendation note on
appendix C's SSE-19 and OBS-29 rows, the only edit under
docs/product-spec/. Six more sentences of the same kind are applied the
same way as C20-C25: the chapter's MUST counts and §12's TRANSPORT-30
deferral, the §3.7/§10.17 close, §3.4's SERDE-24 "by construction",
the json-2.9.1 "stateless JSON" premise behind SERDE-26, §7.2's SSE line
primitive, and §9's NFR-10 row. §12's lists, rows and MUST-level summary
follow: TRANSPORT-2 and TRANSPORT-8 leave the vacuous list, PAGE-15's
wrapping clause and CFG-19 join it.

docs/deviations.md gains rows 20-38 with as-built evidence and records
the re-audit; gates:ledger_audit holds 38 rows to 38 entries. The
first-release blocker is ticked, and the two unmet clauses it never
carried are added under Unsatisfied MUSTs.

No live defect was found: wherever a sentence and the code disagreed,
the code was right.

Audits all nineteen entries of design §10, the normative deviation
ledger, against the as-built tree (gems/**/lib, sig/, the suites)
rather than against the phase documents that produced it, applies the
amendment set phase 10 wrote out, and consolidates every phase's as-built
Deviation Ledger into the chapter. Both halves of the first-release
blocker phase 10 left for a human are done.

Seven entries hold exactly as written (3, 7, 8, 11, 14, 16, 19). Five
hold and gain a dated clause carrying a narrower as-built fact a phase
ledger recorded (1, 2, 4, 9, 15). Seven were wrong about the code and
are corrected in place, each with a "[Corrected/Amended 2026-09-25: ...]"
note quoting what it replaced rather than a silent overwrite:

  5   "the only entries that are not mechanism substitutions", and the
      socket-closing hook attributed to "an adapter" -- only the two
      transports own a socket (C12)
  6   the trail is Dexpace::Suppressible, not Dexpace::Error#suppressed
      (C14); a frozen primary is a documented no-op (4b P4-13)
  10  send(:new) bypasses .build but not validation; .allocate and duck
      typing are the holes left (C19, re-measured on 4.0.6 and 3.2.11)
  12  the I/O ownership rule is IO-6, not the retired SEAM-3 (C3)
  13  the encode profiles take the value first (C18); the buffer
      profile takes a mutable BINARY String only (7a P7-5)
  17  its last clause described a close path that does not exist:
      Pool#close takes no token and is bounded by shutdown_timeout
      (8b P8-24, C21)
  18  omitted SSE-19's two rejecting caps (C15), the per-call ceiling
      (5a P5-56) and the pacing parser's digit bound (6a P6-61)

The chapter's opening claim -- two unmet MUSTs and nothing else
narrowed -- is corrected too. Consolidating the ledgers adds entries
20-38, one per group of genuine deviations from the reference contract
the phases recorded and §10 did not, each citing its ledger row and the
as-built file. Three are MUST clauses unmet on a stated domain and are
admitted, not argued: SERDE-27's no-materialisation clause in the JSON
codec (7a P7-1), TRANSPORT-14 on the async transport (8c P8-38, with the
TRANSPORT-27 half no row carried), and HTTP-45's no-pinning clause for a
second fiber of one thread with no scheduler (3b P3-27), which reached
neither §10, §12 nor docs/first-release.md until now. Rows that record
only a departure from the design or the plan, with the specification met
exactly, are not deviations and are not carried.

Applies C1-C19 to §3, §4, §8, §9, §10, §11 and §12 after re-verifying
each against the code; all nineteen held, C19 narrowed to HTTP domain
models (Pipeline::Entry validates in .build alone) and C8 re-measured
against the resolved bundle. C11 is a dated recommendation note on
appendix C's SSE-19 and OBS-29 rows, the only edit under
docs/product-spec/. Six more sentences of the same kind are applied the
same way as C20-C25: the chapter's MUST counts and §12's TRANSPORT-30
deferral, the §3.7/§10.17 close, §3.4's SERDE-24 "by construction",
the json-2.9.1 "stateless JSON" premise behind SERDE-26, §7.2's SSE line
primitive, and §9's NFR-10 row. §12's lists, rows and MUST-level summary
follow: TRANSPORT-2 and TRANSPORT-8 leave the vacuous list, PAGE-15's
wrapping clause and CFG-19 join it.

docs/deviations.md gains rows 20-38 with as-built evidence and records
the re-audit; gates:ledger_audit holds 38 rows to 38 entries. The
first-release blocker is ticked, and the two unmet clauses it never
carried are added under Unsatisfied MUSTs.

No live defect was found: wherever a sentence and the code disagreed,
the code was right.
@Wahbeh-Mohammad
Wahbeh-Mohammad force-pushed the docs-reconcile-design-deviations branch from 44cfbac to 7b84257 Compare September 25, 2026 20:56
@Wahbeh-Mohammad
Wahbeh-Mohammad merged commit a13a8da into main Sep 26, 2026
5 checks passed
Wahbeh-Mohammad added a commit that referenced this pull request Sep 26, 2026
Six sentences went stale when #106 applied the frozen-chapter amendments
and consolidated the phase ledgers into design §10: the construction
bullet now names Pipeline::Entry as the one model that validates in
.build alone (C19); the interrupt ban covers code this repository
writes, not its dependencies (C8); the deadline bullet counts two unmet
MUSTs and one vacuous, and names the three MUST clauses §10.20-§10.22
now admit; the decode-boundary bullet says C1 corrected §3.1; and the
phase-10 paragraph records that the maintainer applied C1-C25 and that
§10 carries 38 entries matched by docs/deviations.md.
Wahbeh-Mohammad added a commit that referenced this pull request Sep 26, 2026
* docs: describe the finished roadmap and add community files

All eleven roadmap phases are merged and nothing is published, but
the root README, CLAUDE.md's opening and the community files still
read as a project mid-build. Re-derived from the tree:

- README.md: a short pre-release status, one row per gem, the
  supported Rubies and the twenty-four gates, in place of the
  phase-by-phase inventory.
- CLAUDE.md: the opening inventory becomes a per-gem, per-layer
  table pointing at the as-built pages and checklists; the next
  step is named as docs/first-release.md's release path; the stale
  "(planned)" markers and the checklist sentence are corrected, and
  the phase workflow says how post-v1 work follows it.
- docs/README.md: the two knowledge entries exist; drop "(planned)".
- dexpace-core's README: the adapter gems 8b and 8c shipped.
- CONTRIBUTING.md and SECURITY.md: the gates, the Ruby range with
  async_http's 3.3 floor, the spec-driven contribution flow, and a
  concrete in-scope list for vulnerability reports.
- .github: bug and feature/requirement issue forms, config.yml,
  a pull request template and CODEOWNERS.

* docs: align CLAUDE.md with the design §10 reconciliation

Six sentences went stale when #106 applied the frozen-chapter amendments
and consolidated the phase ledgers into design §10: the construction
bullet now names Pipeline::Entry as the one model that validates in
.build alone (C19); the interrupt ban covers code this repository
writes, not its dependencies (C8); the deadline bullet counts two unmet
MUSTs and one vacuous, and names the three MUST clauses §10.20-§10.22
now admit; the decode-boundary bullet says C1 corrected §3.1; and the
phase-10 paragraph records that the maintainer applied C1-C25 and that
§10 carries 38 entries matched by docs/deviations.md.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant