chore(devtools): record bitty-core jurisdiction + fix stale docs + sync trace accounting semantics - #131
Merged
Conversation
…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
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
… (review PX-0390)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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-devtoolsunder bitty-core jurisdiction. No code behavior changes.Changes
repo.toml—ownerTBD->bitty-core, matching the workspace map (workspace.tomlalready recordsbitty-core). This carries the uncommitted local edit from the workspace restructure.AGENTS.md— records management by thebitty-corecommander (terminal-platform jurisdiction, alongsidebittyandbitty-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'srecording/); replaces the blanket pre-implementation claim only where stale against merged code (tracing phases 1/2, inspect-only watch mode, live-socket fixtures) withImplemented-only wording. NoVerified/Compatibleupgrade.README.md— new "Trace accounting semantics (Implemented, CTX-0053 / CTX-0054)" section syncing the client trace helper clarification inbitty-terminal-docsspecifications/devtools-rfc.md(mergeda205c17, CTX-0026): retained redacted logical UTF-8 export-byte accounting (not heap/filesystem occupancy), independent per-record normalization with a leadingU+FEFFpreserved as data, effectivemin(trace maxBytes, retention maxBytes)rejection with one counted drop and unchanged retained state, opaque raw append vs typed stream coalescing, andfetchTraceChunkpagination on retained UTF-8 byte offsets.CHANGELOG.md— docs-onlyChangedentry 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.tsappendToTrace(redact -> per-record UTF-8 normalize -> byte length),appendStructuredEvent(serialized JSON bytes), both billmin(rec.options.maxBytes, rec.retention.maxBytes), incrementdropsonce on rejection, and leave retained bytes/chunks/events/previews unchanged.src/tracing.tsfetchTraceChunk: 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.rsappend_to_trace/append_structuredmirror the same accounting; testsraw_retention_matches_utf8_model,structured_retention_matches_serialized_bytes, andretained_redaction_is_measuredassert retained state is unchanged on rejection.tests/tracing.test.tscovers BOM/U+FEFF preservation and per-record normalization ("\uFFFD\uFFFD\uFEFFéz"), UTF-8 boundary offsets, continuation, and raw-vs-typed coalescing.Evidence
just checkgreen: 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/*.ymlclean.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 thetaiki-e/install-actionremote (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/mainbun.lockis stale relative topackage.json(@types/bun/bun-types1.4.0vs pinned1.4.2,carryctx0.11.2vs0.11.4), sobun install --frozen-lockfilefails on a clean clone. Untouched here (docs-only scope); needs its own chore task.actlimitation, not a workflow defect; actionlint and offline dry-run are clean.Task: CTX-0075