data-modeling.md

data-modeling — notes

Hand-written. docs/knowledge/harvested/data-modeling.md is what the styleguide says; this file records how this repository bounded one of its rules, and it wins. Each entry names the harvested entry it answers by that entry's stable key.

Conflicts

• #private-vs-private: the runtime-privacy carve-out is scoped to packages/core/src/http/, and that scoping is the settled answer rather than an unfinished sweep. Resolves http-domain-model/d26b9192, the conflict statement left unresolved 2026-07-25, and bounds data-modeling/2765e3ba and data-modeling/7ea87f23 rather than overturning either. CLAUDE.md's "Domain model construction pattern" opens "Every model in packages/core/src/http/ follows one shape" and mandates "#private fields only. Not TS private." inside that shape; the justification it cites is the styleguide's own carve-out for library internals that must stay unreachable reflectively, which is a claim about what a consumer can reach. Outside that directory the styleguide's default stands. The blanket reading the conflict entry worried about — "blanket across every model class, not per-use" — is not what shipped.

  Measured 2026-09-04: 15 TS private/protected members against 75 #private fields. Reproduce over packages/*/src, excluding tests and constructor parameters, with grep -rnE '^\s+(private|protected)\s+(readonly\s+)?[a-zA-Z_]' --include='*.ts' packages/*/src | grep -v '\.test\.' | grep -v constructor and grep -rnE '^\s+#[a-zA-Z_]' --include='*.ts' packages/*/src | grep -v '\.test\.'. packages/core/src/http/ holds none of the 15 — it is at 100% compliance. The 15 are NonceCountStore.counts (packages/core/src/auth/digest.ts), BearerTokenCache's six including its startPostEviction and refresh methods (packages/core/src/auth/bearer-cache.ts), and CollisionWarningGate.warned plus RealLogEvent's seven (packages/core/src/observability/logger.ts). The first two classes are exported @internal; the last two are module-local and exported from nothing. None reaches the public barrel or any packages/*/etc/*.api.md, so no consumer can hold one to reflect on — which is the condition the carve-out is granted for, and it is absent.

  Sweeping the 15 to #private was considered and rejected 2026-09-04. It would churn bearer-cache.ts's single-flight logic for no consumer-visible gain and would apply the carve-out past the reasoning that earns it. The deferral this had sat under since the Phase 4b validation review (F7, 2026-07-28) closes on that reasoning, not on a sweep, and its own summary was wrong: it called the residue "cosmetic (no per-class comment stating the justification)" when the residue was in fact 15 members using the other style entirely. Recording it here rather than in the register is what makes it survive the row's removal. _{review · CLAUDE.md · high · sha:manual-2026-09-04-private-field-scope}