Uh oh!
There was an error while loading. Please reload this page.
docs(architecture): describe the single-environment runtime, without invented figures - #69
Merged
Merged
Conversation
…invented figures architecture.mdx described runtime behaviour with the hosted, many-environments-per-instance model — per-project kernels in an LRU, "first request to a project" warmup, "~10-30MB per active project kernel" — on a page whose subject is the single-environment runtime a customer deploys from the release bundle. The performance figures are removed rather than restated. No measurable source for the shipped image exists in this repository, and a range with a unit reads as measured. The section now describes where each cost comes from and what to measure it as. Fixes#64 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CJPxtTxoxTUnjNdTbiEaRa
This was referenced Aug 18, 2026
os-zhuang
marked this pull request as ready for review
August 18, 2026 09:47
Uh oh!
There was an error while loading. Please reload this page.
os-zhuang
commented
Aug 18, 2026
ContributorAuthor
Merged as Updated from Verified on Generated by Claude Code |
os-zhuang pushed a commit
that referenced
this pull request
Aug 18, 2026
Two current pages named the same boot shape differently, and the deploy bundle ships one environment template per shape — so a reader who has seen both pages could not tell whether "Config-authored" and "Shipped runtime" were one shape or two, while deploy/index.mdx warns against adapting one template into another. The card guessed deploy/index.mdx's "Shipped runtime" was canonical because it is the newer page. It is not the newer page, and the corpus does not use that name anywhere else: - Three pages carry this table, not two. configure/runtime.mdx:24 also names row one "Config-authored", so the corpus stands 2-1. - The commit order inverts the guess. deploy/index.mdx's table landed in #62 at 13:14; "Config-authored" was written into architecture.mdx and configure/runtime.mdx by #63 at 14:49 — after it, by a pass whose scope was explicitly "outside Deploy" and which reconciled contradictions with the Deploy rewrite. #69 then rewrote architecture.mdx at 17:40 and kept the name. "Shipped runtime" is the oldest of the three writes. - #63 checked its rows "against the deployment bundle that ships with the release, and against the runtime and CLI source that reads it" — the template-mapping authority, and it sits with "Config-authored". - "Artifact-pinned" is the framework's own term (packages/runtime/src/ artifact-reference.ts, packages/cli/src/commands/serve.ts). The paradigm is a past-participle describing where the app came from; "Shipped runtime" is a noun phrase naming the runtime, and is the odd one out even inside its own table. - "the shipped runtime" is already an established generic phrase for the product runtime — three uses upstream, plus environment-variables.mdx:158 ("Nothing in the shipped runtime reads OS_ARTIFACT_FILE"). Promoting it to a proper noun would make the boot-contract reference page use the phrase in two senses at once. Row three differed in substance too, and the evidence settles it rather than contradicting: air-gapped.mdx and the OS_COMPOSED_ARTIFACT_URL entry both state the two claims jointly — the composed shape is the hosted multi-organization shape AND is air-gap-licensed only, enforced at startup. deploy/index.mdx already carried both; architecture.mdx carried only the licence half, so it gains the purpose half and the link to where the refusal is stated. No headings are renamed, so no anchor moves: /docs/architecture#boot-modes still resolves. Fixes#71
os-zhuang pushed a commit
that referenced
this pull request
Aug 18, 2026
The hosted many-Environments-per-process model that #64/#69 removed from architecture.mdx was still the model six other English pages taught. Each row got its own decision rather than a search-and-replace. - faq.mdx: the multi-tenancy answer promised per-Environment database, identity and audit isolation the single OS_DATABASE_URL contract does not give. Rewritten against the walled tenancy posture. Also drops the "kernel cache" framing from the serverless answer, replaces the dead "kernel cache miss rate" metric, and points the monitor at /api/v1/health + /api/v1/ready like the shipped deploy pages. - glossary.mdx: Kernel, Environment, Tenant and Project rewritten. The first three carried the retired model as load-bearing definitions. - why.mdx: the fit-scenario row named a mechanism (per-project kernel + LRU cache) that does not exist. Row removed; the positioning question is escalated rather than decided here. - observability.mdx: kernel_cache_misses_total is emitted by nothing on objectstack@origin/main and OS_KERNEL_CACHE_SIZE is in no section of the environment contract, so the alert is deleted rather than reworded. - troubleshooting.mdx, ai-builder.mdx: wording. English only; locale siblings go stale and are re-derived by the translation pass. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CJPxtTxoxTUnjNdTbiEaRa
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 freeto 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.
Fixes#64
architecture.mdxdescribed runtime behaviour with the hosted,many-environments-per-instance model, on a page whose subject is the
single-environment runtime a customer deploys from the release bundle.
The figures are removed, not restated
No authoritative measurement of the shipped image was available here, so the
numbers were removed and the shape is described instead. This repository is
the docs site; it holds no benchmark, no runtime source, and no measurement
artifact for the licensed image, and the image itself is behind licensed
registry credentials. Adapting the hosted figures by reasoning about them was
explicitly out of bounds, and it is the defect being fixed: a range with a unit
reads as measured.
Provenance, for the record: the figures entered the tree in
393f3d3— theinitial import of the pre-July free-runtime era — and were never sourced by any
later commit (
git log -Sfinds no other author).Gone:
Per-kernel warmup (first request to a project)— 50-300msMemory footprint— ~150MB base; ~10-30MB per active project kernelConcurrent app kernels per instanceCold start— ~1 second,Warm request latency— sub-10ms,Steps 4-8 typically execute in 5msThe section is now a table of where each cost comes from and what to measure
it as — time-to-
/api/v1/ready, the container's RSS under your own load, andso on.
The model, not just three cells
The hosted model was load-bearing across the page, so the prose around the
table moved with it. Verified against the shipped pages that are the authority
for the deployment shape —
deploy/index,deploy/docker,deploy/kubernetes,deploy/air-gapped(#62/#63) andreference/environment-variables:OS_ARTIFACT_URLis "the one variable thatselects the app", and metadata "is scoped to the deployment, not to an
organization". Organizations that share a walled deployment share its app.
Hostname → project resolutionandGet or build per-project kernel from LRUleft the request path; the kernelis built at startup and readiness gates traffic behind it.
identical shared secrets become mandatory (
deploy/docker).Per-project ObjectKernel (LRU cached)is nowObjectKernel — this deployment's app.reference/environment-variablescalls this shape a "single-environmentruntime"; the page now matches that vocabulary.
Two bounded in-place corrections, named because they are not in the card
Both are the same defect class — the page asserting a runtime shape the product
does not have — and both are pinned by a shipped page, so they were corrected
rather than filed:
VM".
resources/faq.mdxalready states the opposite and is the newer claim:"The runtime is a long-lived Node process — designed for containers or VMs,
not stateless functions."
apps" → "If you publish apps that several deployments install". The
catalog is real (
build/marketplace.mdx,build/packages.mdx); themany-apps-per-runtime framing around it was not.
Also: the diagram's
HTTP dispatcherrow was one character wider than everyother row on
main. All rows are now 55 characters.Verification
Run on the final commit,
6711c94:pnpm turbo run type-check --continue--force, 0 cached)pnpm turbo run buildpnpm turbo run testtestscriptnode .github/scripts/check-translations.mjscheck-translation-ownership.mjsThe rendered page was read out of the build output
(
.next/server/app/en/docs/architecture.html), not just the diff — which ishow a scripted re-pad that had clobbered step 2 of the request path got caught
before the commit.
Note on the translation gate. The freshness table is byte-identical before
and after this change (verified by running the gate in a second worktree at
origin/main): stale 1/3/3/3/3/3, missing 17/40/41/40/40/40, gate passes onboth. The six
architecture.*locale siblings were deleted in #63 underthe AGENTS.md rule that a stale translation is worse than a missing one, so
this page has no siblings left to move into the stale column — it is already in
missing, and already on the worklist.No locale file is touched by this PR.
Generated by Claude Code