Skip to content

docs(quickstart): declare the Path B compile timing as machine-variable - #260

Merged
os-bill merged 1 commit into
mainfrom
claude/issue-249-declare-the-compile-timing
Sep 2, 2026
Merged

docs(quickstart): declare the Path B compile timing as machine-variable#260
os-bill merged 1 commit into
mainfrom
claude/issue-249-declare-the-compile-timing

Conversation

@os-bill

@os-bill os-bill commented Sep 2, 2026

Copy link
Copy Markdown
Collaborator

Fixes #249

Path B's sample block publishes ✓ Build complete (72ms). Every other visible byte in both blocks is deterministic; that one is whatever the transcribing machine measured — 117ms when the block was transcribed at CLI 17.1.0, 72ms when it was re-transcribed at 17.2.0, with no behavioural change behind the difference.

What changed

One clause in Path B's existing declaration sentence — the sentence that already tells the reader which parts of their own output will differ.

Before:

Project paths show as my-app/… — the CLI prints yours expanded.

After:

Project paths show as my-app/… — the CLI prints yours expanded, and the Build complete timing is whatever the transcribing machine measured, so yours will differ.

The paragraph is re-wrapped to absorb the clause; nothing else in it changed. Diff is 5 insertions, 4 deletions, one file.

What deliberately did not change

The captured line is byte-for-byte as captured. The number is not deleted, not rounded, and not replaced with a placeholder. The block stays a faithful transcript, which is the property the recurring re-transcription card depends on. Mechanical check: the diff adds and removes zero lines inside either sample block (git diff | grep -c over the block's line prefixes returns 0), and quickstart.mdx:164 still reads ✓ Build complete (72ms).

Neither block was re-transcribed. That belongs to the refresh card and was just done at 17.2.0.

No locale sibling was touched. The ownership gate states it: "This PR touches 0 translation artifact(s) and 1 other file(s)."

Path A was checked and needs nothing

The card asked for Path A to be checked for the same shape rather than assumed. It carries no machine-variable published value, verified at source rather than by re-booting (re-transcription is out of scope here), against a packages/cli tree declaring version 17.2.0 — the same version both blocks were transcribed from:

  • printServerReady in packages/cli/src/utils/format.ts — the ready banner both paths share, covering every line from ✓ Server is ready through Press Ctrl+C to stop — interpolates no measured duration. Its variable values are paths, mode, driver label, tenancy posture and plugin count/names, all already declared or version-determined.
  • packages/cli/src/commands/start.ts matches nothing for timer, Date.now, elapsed, duration or a ms interpolation. Path A's header rows are printKV calls carrying paths and ids only.
  • Exactly one Build complete timer exists in the CLI source, at packages/cli/src/commands/compile.ts:812, on the compile path that only Path B exercises.

So this card is Path B only, and no Path A edit was manufactured for symmetry.

Gates

Every job CI runs for this diff was run locally at 55bff71, no narrowing. Each gate's own conclusion:

Gate Exit Its own verdict
check-translation-ownership.mjs 0 "This PR touches 0 translation artifact(s) and 1 other file(s)."
check-translations.mjs (freshness) 0 "✓ translations gate passed"
check-translation-output.mjs --self-test 0 "✓ self-test: 29 rule case(s), 9 split case(s) and 5 derived-locale case(s) … every rule demonstrated able to fail"
gen-zh-hant.mjs --check 0 "✓ zh-Hant: 73 generated file(s) match the zh-Hans sources byte for byte."
check-node-floor.mjs 0 "✅ Every declared floor clears what the dependency tree requires, and the declarations agree."
turbo run type-check 0 "@objectos/docs:type-check: ✓ Types generated successfully"
turbo run build 0 "Tasks: 1 successful, 1 total" (uncached, 1m16s)
check-locale-surface.mjs 0 "✓ every advertised URL has a source file and every source file is advertised …" — sitemap.xml 409 URLs, 0 unexpected, 0 missing
turbo run test 0 "✓ 4 self-test(s) passed" (re-run with --force; the first pass was a legitimate cache hit, the task's declared inputs exclude content/docs/**)

Exit codes were captured before any pipe. The substantive uncached run was taken on the tree that is now 55bff71 with git diff HEAD empty, and the union was re-run after the commit at that sha.

No changeset: this repo has no changeset flow (no .changeset/, nothing published from a package).

🤖 Generated with Claude Code

Generated by Claude Code


Generated by Claude Code

`content/docs/quickstart.mdx`'s Path B block publishes `✓ Build complete
(72ms)`. Every other visible byte in both blocks is deterministic; that
number is whatever the transcribing machine measured — `117ms` at CLI
17.1.0, `72ms` at 17.2.0, with no behavioural change behind the difference.

The block is a faithful transcript, so the number stays exactly as captured.
What changes is the declaration sentence that already tells the reader which
parts of their own output will differ: it named the expanded project paths
but not the timing, so a reader whose scaffold compiles in 300ms had no way
to know that is expected rather than a symptom. The timing now sits in that
same list.

Second effect: the recurring re-transcription of these blocks at each CLI
publish no longer has to justify a one-line timing change as drift, because
the value is declared rather than asserted.

Path A checked for the same shape and needs nothing: its published lines
carry no measured value. Verified against `@objectstack/cli` 17.2.0 source
rather than by re-booting — `printServerReady` (the banner both paths share)
interpolates no duration, `start.ts` prints no timer at all, and the only
`Build complete` timer in the CLI is on the compile path Path B exercises.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ChPQM8jamxLUfUAxwFpJ8S
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.

[finding] quickstart Path B publishes a machine-variable compile timing as a literal

2 participants