docs: implementation-accuracy audit of the #4212-family affected docs

Ran the repo's docs-accuracy-audit workflow scoped to the drift-check advisory
from #4242 (14 docs) plus 4 the retired-surface grep implicated. 158
evidence-backed fixes across 18 docs, each cited to file:line. The largest
classes:

- kernel/cluster.mdx (22): a documented `eventBus.emit(...)` that exists
  nowhere in packages/, a `ctx.cluster` PluginContext property that does not
  exist, `defineStack({ cluster })` that stack.zod.ts silently strips,
  `postgres`/`nats` listed as shipped drivers when neither package exists,
  `REDIS_URL` for the real `OS_CLUSTER_DRIVER`, and an at-least-once delivery
  promise no shipped driver provides.
- protocol/kernel/plugin-spec.mdx (20): `plugin.manifest.ts` as the manifest
  filename — grep-empty across packages/, apps/ and examples/; the real one is
  `objectstack.plugin.json`. Plus `context.plugins.isInstalled()` (no such
  member), compound semver ranges (`'>=1.0.0 <2.0.0'`) that make the resolver
  throw, and init ordering described as registration order when bootstrap()
  runs a dependency topological sort.
- data-modeling/external-datasources.mdx: `credentialsRef: 'secret:…'` — the
  shipped binder only resolves `sys_secret:<id>`, so the sample as written
  fails closed at connect.
- deployment/migration-from-objectql.mdx: a `^3.1.0` pin that can never
  resolve to the current 16.1.0 line.

VERIFICATION STATUS — 7 of 18 docs carry an adversarial-verifier pass; the
other 11 do not (the run hit the session limit mid-phase). The verifier earned
its keep on the 7 it reached: 8 repairs, including a fabricated
`enforceNetworkAccess` (real: `enforceNetworkRequest`,
plugin-permission-enforcer.ts:212) and an over-broad retirement claim that
would have contradicted the live app-bundle `onEnable`. The remaining 11 are
committed unverified and MUST NOT ship until their verifier pass runs — the PR
stays draft until then.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HrRNgrWaRtggzmrHpbomyh

Author: claude

.changeset/docs-accuracy-audit-4212-scope.md

@@ -0,0 +1,6 @@
+---
+---
+
+docs: implementation-accuracy audit of the #4212-family affected docs. Fixes
+fabricated APIs, wrong manifest filenames, unresolvable version pins and
+credential-ref formats. Releases nothing.

content/docs/data-modeling/external-datasources.mdx

@@ -122,9 +122,10 @@ from external configuration. Auto-connect is idempotent with it (whichever
 registers the datasource name first wins), so the two never conflict.
 </Callout>
 
-A connected external datasource is also visible in **Setup → Datasources** (stamped
-`origin: code`, read-only in the UI) and via `GET /api/v1/datasources` and
-`GET /api/v1/meta/datasource`, where an admin can run the "Sync objects" wizard.
+A connected external datasource is also visible in **Setup → Integrations →
+Datasources** (stamped `origin: code`, read-only in the UI) and via
+`GET /api/v1/datasources` and `GET /api/v1/meta/datasource`, where an admin can
+run the "Sync objects" wizard.
 
 ### When auto-connect fails
 
@@ -161,8 +162,8 @@ Every connect attempt's verdict is retained, so a datasource that is down no
 longer has to be diagnosed by restarting the server and re-reading boot logs
 ([#3827](https://github.com/objectstack-ai/objectstack/issues/3827)).
 
-**Setup → Datasources** and `GET /api/v1/datasources` report a `status` per
-datasource:
+**Setup → Integrations → Datasources** and `GET /api/v1/datasources` report a
+`status` per datasource:
 
 | `status` | Meaning |
 |:---|:---|
@@ -203,7 +204,7 @@ const policy: DatasourceConnectPolicy = {
       ? { allow: true }
       : {
           allow: false,
-          // operator-facing: logs + Setup → Datasources only
+          // operator-facing: logs + the Setup datasource list only
           reason: `egress allow-list miss for ${ds.name} (${tenant.id}, plan=${tenant.plan})`,
           // tenant-facing: appended to the query-time error
           publicReason: 'External datasources require the Scale plan.',

content/docs/kernel/cluster.mdx

@@ -417,8 +417,10 @@ Ask: **if I deploy 5 nodes, should there be 5 of these or 1?**
   - "Reacts to events with idempotent writes" → `idempotent-broadcast`
 
 Declaring `cluster` does not yet *do* anything (§5.1) — until Phase 4 lands
-you still have to hold the invariant yourself, e.g. by wrapping the work in
-`cluster.lock.withLock(key, fn)` the way `service-job`'s cron scheduler does.
+you still have to hold the invariant yourself, either by wrapping the work in
+`cluster.lock.withLock(key, fn)` or by acquiring and releasing by hand the way
+`service-job`'s cron scheduler does (`cluster.lock.acquire(key, { waitMs: 0 })`,
+bail out when it returns `null`, release in a `finally`).
 
 ### 7.3 "I want to read metadata in a long-lived cache"
 
@@ -631,7 +633,11 @@ of the declarative wiring below exists yet.
 - `service-job` declares `clusterScope: 'cluster' / 'leader-elected'`.
 - `service-cache` gains a cluster-backed cache derived from `KV + PubSub`.
 - `service-realtime` adds cross-node fan-out via PubSub.
-- Webhook dispatcher uses `partitioned` strategy from day one.
+- Webhook dispatcher declares the `partitioned` strategy. (The behaviour
+  already ships hand-rolled: webhook deliveries drain through
+  `service-messaging`'s `HttpDispatcher`, which walks `partitionCount`
+  partitions behind per-partition `cluster.lock` keys — only the declarative
+  annotation is missing.)
 
 ### Phase 5 — Postgres / NATS drivers (deferred, optional)
 

content/docs/kernel/events.mdx

@@ -19,7 +19,7 @@ Triggered by the Kernel during bootstrap and shutdown:
 | Event | Description |
 | :--- | :--- |
 | `kernel:ready` | All plugins have successfully started. System is live. |
-| `kernel:bootstrapped` | Fired after every `kernel:ready` handler has settled, before `kernel:listening`. The "all bootstrap + seed data is ready" anchor — use it for reconcile/backfill work that consumes data a later-starting plugin produces during `kernel:ready`. |
+| `kernel:bootstrapped` | Fired after every `kernel:ready` handler has settled, before `kernel:listening`. The "all **synchronous** bootstrap has settled" anchor — use it for reconcile/backfill work that consumes data a later-starting plugin produces during `kernel:ready`. It does **not** guarantee app *seed* data has settled: an inline seed that overruns `OS_INLINE_SEED_BUDGET_MS` (default 8s) keeps seeding in the background and can outlast even `kernel:listening`. Subscribe to `app:seeded` for the true per-app seed-settle point. |
 | `kernel:listening` | Fired after every `kernel:ready` and `kernel:bootstrapped` handler has completed (e.g. the HTTP server is accepting connections). |
 | `kernel:shutdown` | Shutdown signal received. Plugins should clean up resources. |
 
@@ -74,7 +74,7 @@ Every data hook is a single-argument handler `(ctx: HookContext) => void | Promi
 | `ctx.input` | **Mutable** input. Shapes: find `{ ast, options }`, insert `{ data, options }`, update `{ id, data, options }`, delete `{ id, options }`. Modify this to change the operation. |
 | `ctx.result` | Operation result, available in `after*` events (mutable). |
 | `ctx.previous` | Record state before the operation (update/delete). |
-| `ctx.session` | Auth/tenancy info (`userId`, `organizationId`, `roles`, …). |
+| `ctx.session` | Auth/tenancy info (`userId`, `organizationId`, `positions`, `accessToken`, …). Absent entirely when the call carried no identity envelope. |
 | `ctx.api` | Scoped cross-object data access. |
 
 ### Registering Data Hooks

content/docs/plugins/index.mdx

@@ -211,11 +211,23 @@ The `os serve` and `os dev` commands automatically detect and load plugins:
 | Condition | Auto-loaded Plugin |
 |:----------|:-------------------|
 | `objects` defined, no ObjectQL | `@objectstack/objectql` |
-| `objects` defined, no driver | `DefaultDatasourcePlugin` (runtime) — driver kind from `OS_DATABASE_DRIVER` / `OS_DATABASE_URL`, defaulting to SQLite in dev and to nothing in production |
+| `objects` defined, no driver | `DefaultDatasourcePlugin` (runtime) — driver kind from `OS_DATABASE_DRIVER` / `OS_DATABASE_URL`, defaulting to SQLite |
 | `objects`, `manifest`, `apps`, `flows`, or `apis` defined | `AppPlugin` (runtime) |
 | Server not disabled | `@objectstack/plugin-hono-server` |
 | Server enabled | `@objectstack/rest` (REST API) |
 
+<Callout type="info">
+**Which SQLite default you get depends on the boot path.** A bare `defineStack()`
+config — one whose `plugins` array instantiates nothing — boots through
+`createStandaloneStack`, which anchors a SQLite *file* under the project
+(`.objectstack/data/standalone.db`) in development **and** production. A host config
+that already instantiates plugins takes `serve`'s own fallback instead: with no
+`OS_DATABASE_URL` / `OS_DATABASE_DRIVER` set it declares SQLite `:memory:` in dev and
+registers **no** datasource in production, so a missing driver surfaces loudly
+downstream. `os dev` sidesteps both defaults by exporting
+`OS_DATABASE_URL=file:<project>/.objectstack/data/dev.db`.
+</Callout>
+
 This means a minimal config like this already works:
 
 ```typescript

content/docs/protocol/kernel/index.mdx

@@ -276,12 +276,13 @@ await kernel.use(new AppPlugin(stack));
 await kernel.bootstrap();
 ```
 
-The kernel validates each plugin at `use()`, then `bootstrap()` topologically
-sorts the registry — declared `dependencies` / `optionalDependencies` are
-hoisted ahead of their dependents, registration order breaking ties — and runs
-every plugin's `init` (Phase 1) followed by every plugin's `start` (Phase 2),
-exposing the resulting services through DI. It then fires `kernel:ready`,
-`kernel:bootstrapped`, and `kernel:listening` in that order.
+The kernel validates each plugin's structure and version compatibility at
+`use()`, then `bootstrap()` topologically sorts the registry — each plugin's
+declared `dependencies` are hoisted ahead of it, registration order breaking
+ties — and runs every plugin's `init` (kernel Phase 1) followed by every
+plugin's `start` (kernel Phase 2), exposing the resulting services through DI.
+It then fires `kernel:ready`, `kernel:bootstrapped`, and `kernel:listening` in
+that order.
 
 ### 2. Request Handling
 ```typescript
@@ -298,8 +299,9 @@ const context = await resolveExecutionContext({ getService, getQl, request });
 // → ExecutionContext { userId, tenantId, locale, timezone, positions,
 //                      permissions, isSystem, ... }
 
-// 2. Data — the context travels as `options.context`, which is what the engine
-//    enforces permissions and RLS against.
+// 2. Data — the context rides along as `context`, on the query itself or on
+//    the engine's trailing options argument (the engine merges both). It is
+//    what permissions and RLS are enforced against.
 const ql = ctx.getService<any>('objectql');
 const account = await ql.findOne('account', { where: { id: '123' }, context });
 ```
@@ -399,9 +401,12 @@ packages/plugins/plugin-slack-integration/
 
 ### Configuration Management
 ```typescript
-// Declare a Zod `configSchema` on the plugin object — the kernel's plugin
-// loader validates the plugin's config against it at `use()` time and refuses
-// to load the plugin when it fails.
+// A plugin object may carry a Zod `configSchema` describing its settings.
+// NOTE: the kernel RECORDS the schema but does not enforce it yet — `use()`
+// takes no config argument, so the loader has nothing to parse and logs
+// "config validation postponed" instead of running the schema. Treat
+// `configSchema` as a declaration of shape, and validate values you actually
+// depend on yourself.
 export const slackPlugin: Plugin = {
   name: 'slack-integration',
   version: '0.1.0',
@@ -477,7 +482,14 @@ const message = i18n.t('slack.button.send', context.locale);
 
 **Why:** Catch errors before customers see them.
 
-**Example:** A plugin declares `apiKey` in its `configSchema`. If it is missing, the plugin loader fails the load with the Zod issues spelled out per key — `Plugin slack-integration configuration validation failed:` followed by `  - apiKey: Required` — so boot stops instead of a request failing later.
+**Example:** Wiring, not config, is what the kernel currently enforces at boot. A plugin that declares a dependency the kernel never received fails `bootstrap()` outright — `[Kernel] Dependency 'com.objectstack.engine.objectql' not found for plugin 'com.objectstack.audit'` — and a dependency cycle throws `[Kernel] Circular dependency detected: <plugin>`. Boot stops there instead of a request failing later.
+
+<Callout type="warn">
+  Plugin `configSchema` is **not** part of this fail-fast path yet. The loader
+  stores the schema and postpones the check, so a missing or malformed value in
+  a plugin's config will not stop boot today. Validate config you depend on in
+  your own `init`.
+</Callout>
 
 ## Comparison: Kernel vs Alternatives
 

content/docs/protocol/kernel/plugin-spec.mdx

@@ -593,9 +593,15 @@ boot — not at install.
 <Callout type="warn">
 Earlier revisions of this page documented an `onInstall` / `onEnable` /
 `onDisable` / `onUninstall` / `onUpgrade` / `onBoot` hook family loaded from a
-manifest `lifecycle` file-map. **None of it existed** — ManifestSchema never
-declared the map and the kernel never called the hooks, so code written
-against them silently never ran. The family was retired from the protocol
+manifest `lifecycle` file-map. **That file-map never existed** — `ManifestSchema`
+has no `lifecycle` key and the kernel never invoked any of these hooks, so code
+written against them silently never ran. `PluginLifecycleSchema`
+(`packages/spec/src/kernel/plugin.zod.ts`) still *declares* `onInstall`,
+`onEnable`, `onDisable`, `onUninstall` and `onUpgrade` as optional functions, but
+nothing calls them; `onBoot` appears nowhere in the implementation at all. The
+single live exception is the **module-level** `onEnable` export of an app bundle
+described above, which `AppPlugin.start()` calls at boot — that is a stack-entry
+export, not a manifest hook. The family was retired from the protocol
 (#4212, ADR-0049 enforce-or-remove).
 </Callout>
 
@@ -632,8 +638,9 @@ implementation.
 `canAccessService` / `canTriggerHook` / `canReadFile` / `canWriteFile` /
 `canNetworkRequest` from the granted set, but only **service access** is wired into a
 live code path: `SecurePluginContext.getService()` and `.replaceService()` call
-`enforceServiceAccess`. `enforceNetworkAccess`, `enforceFileRead` and `enforceFileWrite`
-have no non-test call sites, and nothing patches global `fetch` — a plugin that calls
+`enforceServiceAccess`. `enforceNetworkRequest`, `enforceFileRead` and `enforceFileWrite`
+have no call sites outside the enforcer module itself, and nothing patches global
+`fetch` — a plugin that calls
 `fetch()` directly is **not** intercepted today. Treat `network` / `fs` declarations as
 consent metadata, not a runtime jail.
 </Callout>