Skip to content

docs(architecture): describe the single-environment runtime, without invented figures - #69

Merged
os-zhuang merged 2 commits into
mainfrom
claude/issue-64-architecture-runtime-model
Aug 18, 2026
Merged

docs(architecture): describe the single-environment runtime, without invented figures#69
os-zhuang merged 2 commits into
mainfrom
claude/issue-64-architecture-runtime-model

Conversation

@os-zhuang

Copy link
Copy Markdown
Contributor

Fixes#64

architecture.mdx described 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 — the
initial import of the pre-July free-runtime era — and were never sourced by any
later commit (git log -S finds no other author).

Gone:

WasWhy it could not stay
Per-kernel warmup (first request to a project) — 50-300ms"First request to a project" is not an event a single-environment reader has
Memory footprint — ~150MB base; ~10-30MB per active project kernelDescribes a different product's memory profile, per active project kernel
Concurrent app kernels per instanceNot a dimension this shape scales on — replicas are
Cold start — ~1 second, Warm request latency — sub-10ms, Steps 4-8 typically execute in 5msSame class: unsourced runtime measurements. Keeping two rows while deleting the others would have made the survivors read as the verified ones

The 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, and
so 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) and
reference/environment-variables:

  • One app per deployment.OS_ARTIFACT_URL is "the one variable that
    selects the app", and metadata "is scoped to the deployment, not to an
    organization". Organizations that share a walled deployment share its app.
  • No per-request app resolution.Hostname → project resolution and
    Get or build per-project kernel from LRU left the request path; the kernel
    is built at startup and readiness gates traffic behind it.
  • Scale is replicas, not kernels. Past one replica the cluster driver and
    identical shared secrets become mandatory (deploy/docker).
  • The diagram box Per-project ObjectKernel (LRU cached) is now
    ObjectKernel — this deployment's app.
  • reference/environment-variables calls this shape a "single-environment
    runtime"; 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:

  1. "fits in a Lambda-like environment" → "fits in a long-lived container or
    VM". resources/faq.mdx already states the opposite and is the newer claim:
    "The runtime is a long-lived Node process — designed for containers or VMs,
    not stateless functions."
  2. "If you're running an internal app marketplace with many tenants and
    apps
    " → "If you publish apps that several deployments install". The
    catalog is real (build/marketplace.mdx, build/packages.mdx); the
    many-apps-per-runtime framing around it was not.

Also: the diagram's HTTP dispatcher row was one character wider than every
other row on main. All rows are now 55 characters.

Verification

Run on the final commit, 6711c94:

CheckResult
pnpm turbo run type-check --continue1 successful, 1 total (--force, 0 cached)
pnpm turbo run build1 successful, 740 static pages, 0 cached
pnpm turbo run test0 tasks — no package in this repo defines a test script
node .github/scripts/check-translations.mjs✓ gate passed
check-translation-ownership.mjs0 translation artifacts touched, 1 other file

The rendered page was read out of the build output
(.next/server/app/en/docs/architecture.html), not just the diff — which is
how 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 on
both. The six architecture.* locale siblings were deleted in #63 under
the 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.

| Locale | Stale | Missing | Guide-stale |
|:-- | --:| --:| --:|
| zh-Hans | 1 | 17 | 0 |
| ja | 3 | 40 | 0 |
| de | 3 | 41 | 0 |
| es | 3 | 40 | 0 |
| fr | 3 | 40 | 0 |
| ko | 3 | 40 | 0 |

No locale file is touched by this PR.


Generated by Claude Code

…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
@os-zhuang
os-zhuang merged commit 3b5160c into mainAug 18, 2026
2 checks passed
@os-zhuangClaude

Copy link
Copy Markdown
ContributorAuthor

Merged as 3b5160c under a direct maintainer instruction, quoted verbatim for the audit trail: 「ci 绿了就合并」.

Updated from main before merging so it was re-checked against the repaired gate rather than the swallowed one. That run is the first time the new output validator ran on a real PR: it reported the 91 pre-existing corpus findings and passed, which is the designed behaviour — fidelity rules block only on locale files a PR changes, and this PR changes none.

Verified on main after landing: the invented runtime figures return 0 matches.


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
Sign up for freeto 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.

architecture.mdx describes the runtime with the hosted multi-environment model, on a page about the single-environment self-hosted product

2 participants

@os-zhuang@claude