From acc5b6a3366f6de71b947e4fe0a4e76c3fedce4f Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 12:51:30 +0000 Subject: [PATCH] docs: retire the multi-Environment runtime model from six pages 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 Claude-Session: https://claude.ai/code/session_01CJPxtTxoxTUnjNdTbiEaRa --- content/docs/build/ai-builder.mdx | 4 ++-- content/docs/operate/observability.mdx | 12 ++++------ content/docs/operate/troubleshooting.mdx | 5 ++-- content/docs/resources/faq.mdx | 30 ++++++++++++++++-------- content/docs/resources/glossary.mdx | 30 +++++++++++++++--------- content/docs/why.mdx | 1 - 6 files changed, 48 insertions(+), 34 deletions(-) diff --git a/content/docs/build/ai-builder.mdx b/content/docs/build/ai-builder.mdx index da293da..d1770cb 100644 --- a/content/docs/build/ai-builder.mdx +++ b/content/docs/build/ai-builder.mdx @@ -137,8 +137,8 @@ If the AI can't do it, it says so — and points you at the manual path ## Live preview After each approved change, Console re-renders the affected views in -place. No reload needed. The kernel cache invalidates the touched -package; subsequent requests use the new metadata. +place. No reload needed. The runtime hot-loads the touched package's new +metadata; subsequent requests use it. ## Roll back diff --git a/content/docs/operate/observability.mdx b/content/docs/operate/observability.mdx index df5ad46..3281105 100644 --- a/content/docs/operate/observability.mdx +++ b/content/docs/operate/observability.mdx @@ -37,7 +37,7 @@ Track at least: | Request duration | Detect latency regressions | | 5xx errors | Alert on runtime failures | | Auth failures | Detect configuration or attack patterns | -| Artifact/kernel cache misses | Understand cold-start behavior | +| Readiness transitions | The process reports ready only once its kernel is built, and `/api/v1/ready` answers 503 when a data driver stops | ### Minimal Prometheus example @@ -72,14 +72,12 @@ groups: for: 10m annotations: summary: "Sustained auth failure rate — check for misconfiguration or attack" - - - alert: ObjectOSKernelColdStartHigh - expr: rate(kernel_cache_misses_total[15m]) > 1 - for: 15m - annotations: - summary: "Frequent project kernel cold starts — consider raising OS_KERNEL_CACHE_SIZE" ``` +Cold starts are not on that list. The kernel is built once, at startup, and +the process reports [ready](/docs/deploy/docker) only afterwards — there is +no steady-state cache-miss signal to alert on, so alert on readiness instead. + For OpenTelemetry, set `OS_OBS_EXPORTER=otlp` **and** `OS_OTLP_ENDPOINT` (e.g. `https:///otlp`) and ObjectOS will emit traces and metrics in OTLP format. The exporter defaults to `noop` (zero runtime cost), so OTLP diff --git a/content/docs/operate/troubleshooting.mdx b/content/docs/operate/troubleshooting.mdx index 490caee..a81c8b2 100644 --- a/content/docs/operate/troubleshooting.mdx +++ b/content/docs/operate/troubleshooting.mdx @@ -63,14 +63,13 @@ Check: - public URL and callback URL match; - OIDC discovery URL is reachable from ObjectOS; - trusted origins include the public domain; -- cookies are scoped to the correct project hostname; -- the project kernel has auth enabled. +- cookies are scoped to the deployment's public hostname. ## User cannot see records Check: -1. Correct project hostname. +1. Correct deployment hostname. 2. User belongs to the expected organization. 3. Object `read` permission. 4. Row-level security. diff --git a/content/docs/resources/faq.mdx b/content/docs/resources/faq.mdx index e2e5f97..959533d 100644 --- a/content/docs/resources/faq.mdx +++ b/content/docs/resources/faq.mdx @@ -46,15 +46,23 @@ protocol for an *external* datasource, which is a client of someone else's API rather than a surface ObjectOS serves. **Q: How is multi-tenancy handled?** -A: One ObjectOS process can serve many Environments (tenants). Hostname -→ Environment resolution caches in an LRU; each Environment has its own -database, identity, and audit log. Cookies are scoped per hostname so -sessions can't leak across tenants. +A: One deployment serves one app, against one database — see +[Architecture](/docs/architecture). Several organizations can share that +deployment: a **walled** tenancy posture (`OS_TENANCY_POSTURE`) puts up the +per-organization isolation wall, and it is a licensed capability the runtime +refuses to start without. What the wall separates is the organizations' data +and memberships, not the metadata — schema is scoped to the deployment, not +to an organization, which is why a walled deployment must also declare which +AI agents are mounted. Isolation stronger than the wall is deployment +separation: a customer that must have its own database gets its own +deployment. See [Multi-organization +deployments](/docs/reference/environment-variables#multi-organization-deployments). **Q: Can ObjectOS run in a serverless / Lambda environment?** A: The runtime is a long-lived Node process — designed for containers -or VMs, not stateless functions. The kernel cache and Better Auth -session model both depend on warm in-process state. +or VMs, not stateless functions. The kernel is built at startup and the +process reports ready only afterwards; that warm in-process state, and the +Better Auth session model, are what a per-invocation function cannot keep. **Q: Does it scale horizontally?** A: Yes. Run multiple instances behind a load balancer. Sessions live in @@ -146,13 +154,15 @@ for files + your secret manager for `OS_AUTH_SECRET`. See [Production Readiness](/docs/operate/production). **Q: Does ObjectOS have a status page?** -A: For your self-hosted deployment, status is your concern — wire -`/health` to your monitor. For hosted services, see +A: For your self-hosted deployment, status is your concern — point your +monitor at `/api/v1/health` for liveness and `/api/v1/ready` for readiness, +the pair [Docker](/docs/deploy/docker) and +[Kubernetes](/docs/deploy/kubernetes) wire up. For hosted services, see [status.objectstack.ai](https://status.objectstack.ai). **Q: What metrics should I monitor?** -A: 5xx rate, p95 latency, auth failure rate, kernel cache miss rate, -queue depth. Minimal Prometheus example in [Observability](/docs/operate/observability). +A: 5xx rate, p95 latency, auth failure rate, readiness +(`/api/v1/ready`), queue depth. Minimal Prometheus example in [Observability](/docs/operate/observability). **Q: How do I take a backup?** A: Back up the **database** and the **storage bucket** — those hold diff --git a/content/docs/resources/glossary.mdx b/content/docs/resources/glossary.mdx index 2238ecc..e1cd9c2 100644 --- a/content/docs/resources/glossary.mdx +++ b/content/docs/resources/glossary.mdx @@ -77,9 +77,12 @@ See [AI Service](/docs/configure/ai). ### Environment -A per-tenant runtime instance backed by its own database and identity. -On v4.x sometimes called *Project* (alias kept). v5.0 standardizes on -*Environment* across CLI, HTTP, env vars, and schemas. +A deployment's own identity — the id it reports as `OS_ENVIRONMENT_ID`, +persisted once a cloud binding completes. A self-hosted ObjectOS is a +**single-environment** runtime: one process, one environment, one app. +Holding many environments, and publishing an artifact for each, is what a +control plane does. See +[Environment Variables](/docs/reference/environment-variables). ### Field @@ -108,9 +111,10 @@ hooks are first-class code; flows are metadata. ### Kernel The microkernel inside ObjectOS that loads plugins, holds the DI -container, dispatches events, and serves a single Environment's -metadata. One process can hold many cached kernels (one per -Environment) in an LRU. +container, dispatches events, and serves the deployment's metadata. One +process builds one kernel, during startup, and does not report +[ready](/docs/deploy/docker) until it is built — so nothing per request +decides which metadata to serve. ### Manifest @@ -172,8 +176,9 @@ A framework package that extends the runtime with a capability — ### Project -Old name for **Environment**. Still used in v4.x CLI/env (aliased). -Removed in v5.0. +Old name for **Environment**. It survives in inherited configuration and +in framework-internal identifiers; ObjectOS documentation says +*Environment*. ### Record Share @@ -208,9 +213,12 @@ code. ### Tenant -A logical isolation boundary in multi-tenant deployments. One tenant -typically maps to one Environment. Cookies and sessions are scoped per -hostname; data is scoped per Environment. +An isolation boundary between the organizations sharing one deployment. +A walled tenancy posture puts the wall up and is a licensed capability. +Those organizations still share the deployment's app, its database and its +metadata, so the wall separates their data and memberships rather than +their schema. See [Multi-organization +deployments](/docs/reference/environment-variables#multi-organization-deployments). ### Trigger diff --git a/content/docs/why.mdx b/content/docs/why.mdx index 4a1a138..52a9c1d 100644 --- a/content/docs/why.mdx +++ b/content/docs/why.mdx @@ -42,7 +42,6 @@ Common scenarios where it's a fit: | Building a compliance / risk / vendor management tool for a regulated business | Audit log, RBAC, field security, row-level isolation are first-class — and every AI-driven change is itself an audit entry | | Standing up an internal admin for a SaaS product | One Node process, slots in next to your existing services | | Air-gapped or on-prem deployment for an enterprise customer | First-class deployment target, no internet egress required (BYO local model) | -| Multi-tenant internal portal (one runtime, many small apps) | Per-project kernel + LRU cache designed for this | | You want your users to "vibe-code" their own extensions safely | The AI Builder + HITL approval queue + audit log are the whole point | ## Don't use ObjectOS if you …