Skip to content

chore(devtools): record bitty-core jurisdiction + fix stale docs + sync trace accounting semantics - #131

Merged
Xuepoo merged 3 commits into
mainfrom
ctx-0075/chore-jurisdiction-docs
Sep 18, 2026
Merged

Xuepoo merged 3 commits into
mainfrom
ctx-0075/chore-jurisdiction-docs

Conversation

@Xuepoo

@Xuepoo Xuepoo commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

Priority: P2 | Area: docs | Labels: chore,P2,area:docs | Milestone: v0.1.0 | RFC: none | Task: CTX-0075

Closes #130

Docs-only governance sync for bitty-devtools under bitty-core jurisdiction. No code behavior changes.

Changes

  • repo.tomlowner TBD -> bitty-core, matching the workspace map (workspace.toml already records bitty-core). This carries the uncommitted local edit from the workspace restructure.
  • AGENTS.md — records management by the bitty-core commander (terminal-platform jurisdiction, alongside bitty and bitty-terminal-docs) while keeping the boundary sentences (core debug/command contracts -> bitty; canonical architecture/security/public behavior -> bitty-docs); applies the scratch-wording unification hunk (ephemeral under /tmp/bitty/, durable under this repository's recording/); replaces the blanket pre-implementation claim only where stale against merged code (tracing phases 1/2, inspect-only watch mode, live-socket fixtures) with Implemented-only wording. No Verified/Compatible upgrade.
  • README.md — new "Trace accounting semantics (Implemented, CTX-0053 / CTX-0054)" section syncing the client trace helper clarification in bitty-terminal-docs specifications/devtools-rfc.md (merged a205c17, CTX-0026): retained redacted logical UTF-8 export-byte accounting (not heap/filesystem occupancy), independent per-record normalization with a leading U+FEFF preserved as data, effective min(trace maxBytes, retention maxBytes) rejection with one counted drop and unchanged retained state, opaque raw append vs typed stream coalescing, and fetchTraceChunk pagination on retained UTF-8 byte offsets.
  • CHANGELOG.md — docs-only Changed entry recording the same semantics sync.

Claim verification (read-only against current code)

Each README claim was verified before writing, not copied from the RFC:

  • src/tracing.ts appendToTrace (redact -> per-record UTF-8 normalize -> byte length), appendStructuredEvent (serialized JSON bytes), both bill min(rec.options.maxBytes, rec.retention.maxBytes), increment drops once on rejection, and leave retained bytes/chunks/events/previews unchanged.
  • src/tracing.ts fetchTraceChunk: rejects non-safe-integer/negative offsets and non-UTF-8-boundary offsets, returns the remaining bytes of the addressed stored chunk, computes continuation from actual retained byte lengths, and asserts preview-equals-export.
  • crates/devtools-client/src/tracing.rs append_to_trace/append_structured mirror the same accounting; tests raw_retention_matches_utf8_model, structured_retention_matches_serialized_bytes, and retained_redaction_is_measured assert retained state is unchanged on rejection.
  • tests/tracing.test.ts covers BOM/U+FEFF preservation and per-record normalization ("\uFFFD\uFFFD\uFEFFéz"), UTF-8 boundary offsets, continuation, and raw-vs-typed coalescing.

Evidence

  • just check green: prettier 3.9.6 check, markdownlint-cli2 0.23.1 (0 issues), tsc --noEmit, bun test (444 pass / 0 fail), cargo fmt --check, cargo check --locked, cargo clippy -D warnings, cargo test (79 + 20 pass).
  • actionlint .github/workflows/*.yml clean.
  • act -n -W .github/workflows/ci.yml --action-offline-mode: all three jobs (Quality gates, actionlint, Fuzz smoke) dry-run succeeded. Without --action-offline-mode, act dry-run fails resolving the taiki-e/install-action remote (act network limitation); workflows are unchanged by this PR.

Trust boundaries

Docs-only: no protocol, wire, or code behavior change. Terminal and trace content remains untrusted observation data; no secrets, captures, or host-specific paths added.

Residual risks / follow-ups

  • origin/main bun.lock is stale relative to package.json (@types/bun/bun-types 1.4.0 vs pinned 1.4.2, carryctx 0.11.2 vs 0.11.4), so bun install --frozen-lockfile fails on a clean clone. Untouched here (docs-only scope); needs its own chore task.
  • The act dry-run online action-fetch failure above is an act limitation, not a workflow defect; actionlint and offline dry-run are clean.

Task: CTX-0075

…race docs

Docs-only governance sync under bitty-core jurisdiction; no code behavior
changes.

- repo.toml: owner TBD -> bitty-core (matches workspace.toml).
- AGENTS.md: record bitty-core commander jurisdiction; keep the core-vs-docs
  boundary sentences; unify the scratch wording (ephemeral under /tmp/bitty/,
  durable under recording/); replace the blanket pre-implementation claim only
  where stale against merged code (tracing phases 1/2, inspect-only watch mode,
  live-socket fixtures) with Implemented-only wording.
- README.md: document the trace accounting semantics implemented by
  CTX-0053/#117 and CTX-0054/#119 and clarified in bitty-terminal-docs
  specifications/devtools-rfc.md (CTX-0026): retained redacted logical UTF-8
  export-byte accounting, independent per-record normalization with leading
  U+FEFF preserved, effective min(trace maxBytes, retention maxBytes)
  rejection with one counted drop and unchanged retained state, raw append vs
  typed stream coalescing, and fetchTraceChunk pagination on retained UTF-8
  byte offsets. Each claim verified read-only against src/tracing.ts and
  crates/devtools-client/src/tracing.rs.
- CHANGELOG.md: docs-only entry recording the same semantics sync.

Gates: just check green (prettier, markdownlint, tsc, bun test 444,
cargo fmt/check/clippy/test); actionlint clean; act -n CI dry-run clean
(offline action mode).

Refs #130
Task: CTX-0075
@Xuepoo Xuepoo added this to the v0.1.0 milestone Sep 18, 2026
@Xuepoo Xuepoo added chore Maintenance tasks P2 Priority: medium area:docs docs area labels Sep 18, 2026
NEEDS-FIX PX-0389: README.md pointed the accepted DevTools RFC at
bitty-docs/docs/specifications/devtools-rfc.md (404); the canonical copy
lives in bitty-terminal-docs specifications/devtools-rfc.md (HTTP 200).
Sweep all four occurrences in README.md (45, 169, 201, 454; the review
cited 45/169/424) and correct the CTX-0026 attribution to
bitty-terminal-docs.

Gates: just check green (prettier 3.9.6, markdownlint 0 issues, tsc,
bun test 444 pass, cargo fmt/check/clippy/test 79+20 pass).

Refs #130
Task: CTX-0075
@Xuepoo
Xuepoo merged commit 74f0ad4 into main Sep 18, 2026
5 checks passed
@Xuepoo
Xuepoo deleted the ctx-0075/chore-jurisdiction-docs branch September 18, 2026 10:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:docs docs area chore Maintenance tasks P2 Priority: medium

Projects

None yet

Development

Successfully merging this pull request may close these issues.

chore(devtools): record bitty-core jurisdiction + fix stale docs + sync trace accounting semantics

1 participant