docs(adr): verified APA 7th citations for ADR-0001–0008

CHANGELOG.md

@@ -6,6 +6,11 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
 
+- Expand ADR-0001 through ADR-0008 with APA 7th References citing opened JWZ,
+  RFC 5322/2047/5051/5256/6532/8474/9051, PEP 561, and official GitHub/PyPI
+  catalog records, and keep the root README a customer/host guide with only a
+  maintainer pointer to
+  [`docs/operations/hourly-autonomous-maintenance.md`](docs/operations/hourly-autonomous-maintenance.md).
 - Keep the root README a customer/operator guide for standalone
   `pip install threadweave` and host composition through
   `from threadweave import thread_messages`, and move the hourly autonomous

README.md

@@ -240,7 +240,7 @@ presentation layer rather than protocol state embedded in the core model.
 See the [documentation home](docs/index.md) and [`docs/research`](docs/research/README.md) for JWZ, RFC 5322, RFC 2047,
 RFC 5051, RFC 5256, RFC 6532, RFC 9051, Unicode-version boundaries, and PEP 561.
 
-Hourly autonomous maintenance is documented in
+Maintainer operating procedure is recorded in
 [`docs/operations/hourly-autonomous-maintenance.md`](docs/operations/hourly-autonomous-maintenance.md).
 
 ## License

docs/adr/0001-canonical-batch-oracle.md

@@ -5,7 +5,37 @@
 
 ## Context
 
-Reference threading combines container identity, reference precedence, cycle prevention, dummy pruning, optional subject grouping, and optional sent-date ordering. Reimplementing those rules in protocol adapters, incremental state, or host integrations would create multiple correctness definitions and make parity difficult to prove.
+Reference threading combines container identity, reference precedence, cycle
+prevention, dummy pruning, optional subject grouping, and optional sent-date
+ordering. Reimplementing those rules in protocol adapters, incremental state, or
+host integrations would create multiple correctness definitions and make parity
+difficult to prove.
+
+The container model is the algorithm Zawinski (1997–2002) documented for
+Netscape Mail and News 2.0/3.0: map each `Message-ID` to a container, link
+parent/child edges from the reference chain, gather parentless containers as
+roots, and prune empty containers so a missing root can still group its
+descendants. RFC 5256 later standardized that approach as the IMAP `REFERENCES`
+threading algorithm and recorded the historical dependence explicitly
+(Crispin & Murchison, 2008, Introduction historical note; informative reference
+`[THREADING]`).
+
+RFC 5256 §2 also fixes the structural steps that a second implementation would
+be tempted to “simplify”:
+
+- link the complete valid `References` chain without stealing an existing good
+  parent;
+- when that chain is unavailable, use only the first valid `In-Reply-To`
+  identifier as the parent, because later tokens are often addresses rather than
+  message identifiers;
+- prune empty childless containers, splice-promote empty internal containers,
+  and retain a multi-child dummy at the root as a missing-thread-root grouping
+  node.
+
+RFC 5322 §3.6.4 supplies the identification-field grammar (`Message-ID`,
+`In-Reply-To`, `References`, `msg-id`) that those linking rules consume
+(Resnick, 2008). Optional subject grouping and sent-date ordering are later
+policy stages of the same RFC 5256 algorithm; they are not a second oracle.
 
 ## Decision
 
@@ -16,4 +46,15 @@ Reference threading combines container identity, reference precedence, cycle pre
 - One set of RFC/JWZ structural tests defines correctness.
 - Performance work may optimize indexing, partitioning, projection, and caching but cannot introduce a second thread-construction algorithm.
 - Incremental/full-rebuild parity is a release gate for incremental work.
-- A future replacement algorithm requires a superseding ADR and side-by-side truth-recovery evidence, not a silent refactor.
+- A future replacement algorithm requires a superseding ADR and side-by-side truth-recovery evidence, not a silent refactor.
+
+## References
+
+Crispin, M., & Murchison, K. (2008). *Internet Message Access Protocol—SORT and
+THREAD extensions* (RFC 5256). RFC Editor. https://doi.org/10.17487/RFC5256
+
+Resnick, P. (Ed.). (2008). *Internet Message Format* (RFC 5322). RFC Editor.
+https://doi.org/10.17487/RFC5322
+
+Zawinski, J. (1997–2002). *Message threading*.
+https://www.jwz.org/doc/threading.html

docs/adr/0002-transport-neutral-core.md

@@ -5,7 +5,32 @@
 
 ## Context
 
-Threading is useful to IMAP servers, migration tools, local archives, and CWL services. If the core owns sockets, command parsing, authentication, mailbox persistence, tenant state, or database access, it becomes difficult to reuse and much harder to test deterministically.
+Threading is useful to IMAP servers, migration tools, local archives, and CWL
+services. If the core owns sockets, command parsing, authentication, mailbox
+persistence, tenant state, or database access, it becomes difficult to reuse and
+much harder to test deterministically.
+
+The published standards already separate conversation structure from transport
+session state. Zawinski (1997–2002) describes a container graph over message
+identifiers. RFC 5256 §4 then defines `thread-data` as a presentation encoding
+of that graph for IMAP `THREAD` responses (Crispin & Murchison, 2008). RFC 9051
+is the current IMAP4rev2 base protocol: CRLF-terminated lines, `nz-number`
+identifiers, and the rule that registered IMAP4rev1 extensions remain valid
+unless an extension says otherwise (Melnikov & Leiba, 2021). Neither document
+requires the threading implementation to own sockets, capability advertisement,
+or mailbox persistence.
+
+Header identity is likewise transport-neutral. RFC 5322 §3.6.4 defines the
+identification fields (Resnick, 2008). RFC 2047 defines MIME encoded-words used
+in those headers (Moore, 1996). RFC 6532 permits UTF-8 in most header values so
+a host can carry internationalized text without ASCII coercion (Yang et al.,
+2012). The runtime therefore normalizes identifiers and header text in process,
+then lets a host or IMAP gateway project the resulting tree.
+
+ThreadWeave is a leaf standard-library package. Naruon is a composition hub that
+imports the published package; there is no sibling-checkout contract. PEP 561
+requires a `py.typed` marker when a distribution ships inline type information
+(Smith, 2017), which is how hosts consume the public typed API.
 
 ## Decision
 
@@ -16,4 +41,29 @@ The runtime package owns pure metadata normalization, thread construction, optio
 - The package remains zero-runtime-dependency and independently testable.
 - Naruon or another host integrates through public typed values rather than database coupling.
 - Mailbox sequence numbers and UIDs are caller-supplied protocol metadata, not ThreadWeave persistence keys.
-- Adding a network/database capability to runtime requires a new ADR and security/operability redesign.
+- Adding a network/database capability to runtime requires a new ADR and security/operability redesign.
+
+## References
+
+Crispin, M., & Murchison, K. (2008). *Internet Message Access Protocol—SORT and
+THREAD extensions* (RFC 5256). RFC Editor. https://doi.org/10.17487/RFC5256
+
+Melnikov, A., & Leiba, B. (Eds.). (2021). *Internet Message Access Protocol
+(IMAP)—Version 4rev2* (RFC 9051). RFC Editor.
+https://doi.org/10.17487/RFC9051
+
+Moore, K. (1996). *MIME (Multipurpose Internet Mail Extensions) Part Three:
+Message Header Extensions for Non-ASCII Text* (RFC 2047). RFC Editor.
+https://doi.org/10.17487/RFC2047
+
+Resnick, P. (Ed.). (2008). *Internet Message Format* (RFC 5322). RFC Editor.
+https://doi.org/10.17487/RFC5322
+
+Smith, E. H. (2017). *Distributing and packaging type information* (PEP 561).
+Python Enhancement Proposals. https://peps.python.org/pep-0561/
+
+Yang, A., Steele, S., & Freed, N. (2012). *Internationalized Email Headers*
+(RFC 6532). RFC Editor. https://doi.org/10.17487/RFC6532
+
+Zawinski, J. (1997–2002). *Message threading*.
+https://www.jwz.org/doc/threading.html

docs/adr/0003-optional-subject-date-policies.md

@@ -7,6 +7,32 @@
 
 RFC-grounded subject grouping and sent-date ordering are useful for protocol-compatible presentation, but changing historical defaults can reorder existing callers' results. Subject equality is also weaker evidence than explicit reference headers.
 
+RFC 5256 `REFERENCES` threading is a six-step algorithm whose first structural
+steps reconstruct parent/child edges from identification fields (Crispin &
+Murchison, 2008; Resnick, 2008; Zawinski, 1997–2002). Subject gathering and
+sent-date sorting are later, optional stages of that same algorithm:
+
+- §2.1 requires a fixed base-subject extraction procedure after RFC 2047
+  encoded-word decoding (Moore, 1996). A message is a reply or forward only when
+  extraction removes a `subj-refwd`, `(fwd)` trailer, or `[fwd: ...]` wrapper.
+  Removing a mailing-list blob alone does not classify the message.
+- Subject comparison uses the RFC 5051 `i;unicode-casemap` preparation
+  (simple titlecase from `UnicodeData.txt`, then compatibility decomposition)
+  rather than locale-sensitive APIs or visual-confusable heuristics
+  (Crispin, 2007). RFC 5051 is not locale-sensitive and warns that Latin `A`
+  and Greek `Α` remain distinct.
+- §2.2 defines sent-date recovery: adjust a valid RFC 5322 `Date` to UTC, treat
+  an invalid or absent zone as UTC, treat an invalid time as `00:00:00`, fall
+  back to mailbox `INTERNALDATE`, then the earliest representable UTC instant,
+  and break exact ties with the mailbox sequence number. Dummy children are
+  sorted before a dummy key is derived; after subject grouping, every sibling
+  set is sorted bottom-up.
+
+Those stages are standards-track presentation policy, not a replacement for
+reference ancestry. Enabling them by default would silently merge unrelated
+conversations that share a base subject and would reorder historical
+first-appearance results.
+
 ## Decision
 
 Reference threading remains authoritative. Subject fallback grouping is opt-in. RFC sent-date ordering is opt-in through `sort_by_sent_date`; first-appearance behavior remains the compatibility default. When ordering is enabled, the implementation uses the documented RFC 5256 date normalization/order rules. An explicit `sequence_number` is validated as a positive mailbox sequence number; when it is absent, the one-based input position is used only as an internal ordering fallback. The resulting effective ordering sequence values must be unique across all sorted messages. Input position is never inferred, exposed, or persisted as a public IMAP sequence number.
@@ -17,4 +43,22 @@ Reference threading remains authoritative. Subject fallback grouping is opt-in.
 - Standards-compatible hosts can explicitly request the richer policy.
 - Hosts that need public IMAP sequence-number serialization still supply and validate real mailbox identifiers at the presentation boundary; the ordering fallback does not create them.
 - Tests must cover explicit sequence numbers, omitted-sequence fallback, duplicate effective values, both option states, and prove reference relationships are not weakened by subject grouping.
-- Future default changes require a versioned compatibility decision and migration guidance.
+- Future default changes require a versioned compatibility decision and migration guidance.
+
+## References
+
+Crispin, M. (2007). *i;unicode-casemap - Simple Unicode Collation Algorithm*
+(RFC 5051). RFC Editor. https://doi.org/10.17487/RFC5051
+
+Crispin, M., & Murchison, K. (2008). *Internet Message Access Protocol—SORT and
+THREAD extensions* (RFC 5256). RFC Editor. https://doi.org/10.17487/RFC5256
+
+Moore, K. (1996). *MIME (Multipurpose Internet Mail Extensions) Part Three:
+Message Header Extensions for Non-ASCII Text* (RFC 2047). RFC Editor.
+https://doi.org/10.17487/RFC2047
+
+Resnick, P. (Ed.). (2008). *Internet Message Format* (RFC 5322). RFC Editor.
+https://doi.org/10.17487/RFC5322
+
+Zawinski, J. (1997–2002). *Message threading*.
+https://www.jwz.org/doc/threading.html

docs/adr/0004-incremental-state-boundary.md

@@ -8,6 +8,24 @@
 
 A full mailbox rebuild after every arrival, expunge, or metadata correction is expensive for large mailboxes. However, an independent incremental threading algorithm would duplicate standards logic and could diverge from the batch result. Durable state also introduces versioning, concurrency, identity, snapshot, and host-ownership questions.
 
+The structural truth remains the JWZ container model as standardized by RFC 5256
+`REFERENCES` (Zawinski, 1997–2002; Crispin & Murchison, 2008). ADR-0001 already
+requires every affected component to pass through that batch oracle. An
+incremental index may remember which components changed; it may not invent a
+second parent-selection, dummy-pruning, or subject-grouping procedure.
+
+RFC 8474 defines persistent IMAP object identifiers: `EMAILID` uniquely
+identifies identical message content and is immutable once reported; `THREADID`
+correlates related messages and MUST NOT change after the server reports it
+(Gondwana, 2018, §5). Those values are host-owned mailbox identities. ThreadWeave
+may validate them as external identifiers and must not silently rewrite them to
+repair threading. Sequence numbers and UIDs remain caller-supplied protocol
+metadata under RFC 9051 `nz-number` / `uniqueid` rules (Melnikov & Leiba, 2021).
+
+ThreadWeave remains a leaf standard-library package. Naruon or another host may
+persist a documented snapshot under its own durable transaction boundary. This
+ADR does not create a ThreadWeave database.
+
 ## Proposed decision
 
 Introduce a process-local `IncrementalThreadIndex` that uses stable caller-owned message keys, optimistic versions, atomic change sets, bounded affected-component indexes, explicit merge/split deltas, and payload-free versioned snapshots. Every affected structural component is rebuilt by the canonical batch oracle. RFC 8474 EMAILID/THREADID values are validated as external identities and are never silently rewritten.
@@ -29,4 +47,19 @@ This ADR becomes `Accepted` only when an implementing PR lands on protected `mai
 
 ## Consequences if accepted
 
-Small mailbox deltas can avoid rebuilding unrelated reference components while structural truth remains centralized. Hosts gain a reusable state handoff but remain responsible for durable concurrency and persistence.
+Small mailbox deltas can avoid rebuilding unrelated reference components while structural truth remains centralized. Hosts gain a reusable state handoff but remain responsible for durable concurrency and persistence.
+
+## References
+
+Crispin, M., & Murchison, K. (2008). *Internet Message Access Protocol—SORT and
+THREAD extensions* (RFC 5256). RFC Editor. https://doi.org/10.17487/RFC5256
+
+Gondwana, B. (Ed.). (2018). *IMAP Extension for Object Identifiers* (RFC 8474).
+RFC Editor. https://doi.org/10.17487/RFC8474
+
+Melnikov, A., & Leiba, B. (Eds.). (2021). *Internet Message Access Protocol
+(IMAP)—Version 4rev2* (RFC 9051). RFC Editor.
+https://doi.org/10.17487/RFC9051
+
+Zawinski, J. (1997–2002). *Message threading*.
+https://www.jwz.org/doc/threading.html

docs/adr/0005-automation-authority-separation.md

@@ -7,6 +7,26 @@
 
 Autonomous model-backed development is useful only if untrusted repository/model execution cannot acquire the credentials or authority needed to approve, merge, tag, or publish its own work. Repository-controlled tests are also untrusted relative to workflow secrets.
 
+Official publication and workflow-identity records already treat credentials as
+job-scoped, least-privilege material rather than a shared development secret:
+
+- GitHub OpenID Connect issues a short-lived JWT unique to one workflow job.
+  After a cloud or package registry validates the claims, it returns a token
+  that exists only for that job and then expires (GitHub, n.d.-a).
+- The workflow `GITHUB_TOKEN` is an automatic job identity. GitHub documents
+  that workflows should grant it only the minimum permissions required, and that
+  a separate GitHub App or stored token is required only when those built-in
+  permissions are insufficient (GitHub, n.d.-b).
+- PyPI Trusted Publishing exists specifically to replace long-lived API tokens.
+  The security model requires trusting a named owner, repository, and isolated
+  publishing workflow; it recommends job-level `id-token: write`, a dedicated
+  environment, and never treating a successful workflow run as proof that the
+  uploaded code is safe (Python Packaging Authority, n.d.-a, n.d.-b).
+
+Those records do not authorize a development model to approve, merge, tag, or
+publish its own output. Combining model execution with OIDC, reviewer, or
+release credentials would collapse the identity boundary the catalogs describe.
+
 ## Decision
 
 Autonomous development uses distinct trust phases: model proposal, credential-free independent verification, trusted bounded PR publication, organization-central review/security/merge, and separately gated release. NVIDIA model credentials are held outside repository-controlled execution. GitHub/OIDC/reviewer/release credentials are not exposed to the development model or repository test process. The development loop never grants itself formal approval or protected-branch merge/release authority.
@@ -17,4 +37,22 @@ Autonomous development uses distinct trust phases: model proposal, credential-fr
 - Exact-head verification and independent review remain separate gates.
 - Credential boundary regressions require dedicated workflow-contract tests.
 - Central `.github` policy can evolve without embedding privileged merge logic in runtime source.
-- Any change that combines model execution with publication/review/release credentials requires a superseding ADR and threat-model review.
+- Any change that combines model execution with publication/review/release credentials requires a superseding ADR and threat-model review.
+
+## References
+
+GitHub. (n.d.-a). *OpenID Connect*. GitHub Docs. Retrieved September 25, 2026,
+from
+https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect
+
+GitHub. (n.d.-b). *Use GITHUB_TOKEN for authentication in workflows*. GitHub
+Docs. Retrieved September 25, 2026, from
+https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication
+
+Python Packaging Authority. (n.d.-a). *Publishing with a Trusted Publisher*.
+PyPI Docs. Retrieved September 25, 2026, from
+https://docs.pypi.org/trusted-publishers/using-a-publisher/
+
+Python Packaging Authority. (n.d.-b). *Security model and considerations*. PyPI
+Docs. Retrieved September 25, 2026, from
+https://docs.pypi.org/trusted-publishers/security-model/