docs(core): repair four copy-fails in PHASE2_IMPLEMENTATION.md

[huangyiirene]

Fixes #18620

Clause-②: no

packages/core/PHASE2_IMPLEMENTATION.md carried four copy-fails that the edit boundary of PR #18615 (the seven retired key spellings) deliberately left alone. Triage refused to split the card, so all four land here in one sweep of one file. packages/spec was read-only for this work: the schemas were read to learn the right spelling, never edited.

Every reading below was re-taken on this branch's head. The card's line numbers moved after PR #18615 landed, so each anchor was located by content.

The four items are NOT one species

Exactly one of them is a silently dropped key. The other three are a compile failure and stale prose.

1. blockedHosts — a key the runtime silently drops, in a security example

The sandbox example wrote blockedHosts. SandboxConfigSchema (packages/spec/src/kernel/plugin-security-advanced.zod.ts:392) declares deniedHosts, and sandbox-runtime.ts:261-262 reads config.network.deniedHosts. The network object is a plain z.object, not .strict(), and there is no retiredKey tombstone for blockedHosts — so the parse succeeds and the key is stripped with no diagnostic at all.

Measured against the schema source, the documented block beside a positive control:

--- DOCUMENTED blockedHosts ---
  success: true
  parsed network keys: ["mode","allowedHosts","maxConnections"]
  network.deniedHosts: undefined
--- CONTROL deniedHosts ---
  success: true
  parsed network keys: ["mode","allowedHosts","deniedHosts","maxConnections"]
  network.deniedHosts: ["malicious.com"]

A reader who copied that block got a sandbox that did not deny the host it named, and was told nothing. blockedHosts occurred exactly once repo-wide before this PR (that documentation line) and occurs zero times after it. The Features bullet above the block said "allowed/blocked hosts" and now says "allowed/denied hosts", matching the filesystem bullet beside it.

Species: a silently dropped key. This is the only one of the four.

2. kernel.logger — a compile failure by member visibility, not a dropped key

The Integration with Kernel block passed kernel.logger to five constructors. ObjectKernel declares private logger: ObjectLogger (packages/core/src/kernel.ts:107), KernelBase declares protected logger: Logger (packages/core/src/kernel-base.ts:36), and neither class has a public getter. The block never compiled, so nothing about it ever reached a runtime that could drop anything.

Measured with tsc --noEmit --strict, the documented line against the repaired one:

documented:  exit 2
  error TS2341: Property 'logger' is private and only accessible within class 'ObjectKernel'.
repaired:    exit 0, no output

The repair builds the ObjectLogger those five constructors take with createLogger — already exported from @objectstack/core through the logger.js barrel — from the same config the kernel is given, rather than reaching into the kernel. The whole repaired block is what the exit-0 run above typechecked.

Species: an example that fails when copied, by member visibility. No metadata key is involved.

3. Prose advertising a capability no runtime delivers

The intro claimed "auto-recovery" and the Features list claimed "Auto-restart with backoff strategies (fixed, linear, exponential)". packages/core/src/health-monitor.ts:160 states the opposite in as many words: "Monitors plugin health status. It REPORTS; it does not act on what it finds." The three keys that once configured a restart were retired under ADR-0049 and deleted from this file's examples by PR #18615, which is how the prose became conspicuous.

The intro now says the monitor reports and that acting on a report belongs to the host, and the untrue Features bullet is replaced by the true integration point the example already demonstrates — polling getHealthStatus and getHealthReport. The adjacent bullets were checked rather than assumed: the recovering status is real and asserted by health-monitor.test.ts, so that bullet stands.

Species: stale prose, Prime Directive #10. No key.

4. Three observations in the same file

• MICROKERNEL_IMPROVEMENT_PLAN.md was linked from the References section. Repo-wide the name occurred once — that link — and no such file exists at the repo root or anywhere else, while its sibling ARCHITECTURE.md does. The dead link is removed.
• npm test in a pnpm workspace is now pnpm --filter @objectstack/core test, which is what the package's own test script answers to. The three test files the section lists all exist.
• "File watching integration points" was listed as a hot-reload feature. HotReloadConfig.watchPatterns was retired in [finding] HotReloadManager.startWatching watches nothing and logs "File watching started" at info; watchPatterns has no reader and watchHandles is never populated #12428 because no watcher was ever constructed, and this file's own body already tells the reader that file watching is the host's job. The bullet is folded into the debounce bullet, which now names scheduleReload and says the host runs the watcher.

Species: stale prose and one dead reference. No keys.

Changeset: measured, not guessed

packages/core/PHASE2_IMPLEMENTATION.md sits at a package root, outside every fast-track path, so whether it ships is a property of @objectstack/core's files[], which is ["dist", "README.md", "CHANGELOG.md"].

The reading, taken after a real build of @objectstack/core and its dependency closure:

• npm pack --dry-run --json in packages/core lists 16 tarball entries. The non-dist/ entries are CHANGELOG.md, LICENSE, README.md and package.json. PHASE2_IMPLEMENTATION.md is not among them.
• Grepping the published paths (dist, README.md, CHANGELOG.md, package.json, LICENSE) for symbols unique to this diff: PHASE2_IMPLEMENTATION 0 files, MICROKERNEL_IMPROVEMENT_PLAN 0 files, Auto-restart with backoff strategies 0 files, blockedHosts 0 files.
• Positive control on the same grep: PluginSandboxRuntime hits 4 published files (dist/index.cjs, dist/index.js, dist/index.d.cts, dist/index.d.ts), so the grep was capable of finding something.

Verdict forced by that reading: this diff publishes nothing from any released package, so it takes skip-changeset rather than a patch changeset.

Clause-②: no stands after the diff was written: the schema is untouched, no accept set moves, and no surface is published. scripts/pm/check-widening-tells.mjs --declaration no exits 0 on this diff but reports it NOT MEASURED — no declared surface covers a Markdown file — so that exit is recorded as evidence about no surface rather than as a clearance.

Verification

• Gate families derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack from the tool's own change set: 39 families. 37 exited 0. Reconciled with --ran carrying every exit code: 39 derived, 37 run, 2 NOT MEASURED, 0 UNRUN.
• The 2 NOT MEASURED are check:dual-build-cjs-loads and check:lean-entry-closure, both exit 3 PREREQUISITE NOT MET: they load built output for every package in the tree and 74 or more packages have no dist/. A whole-tree pnpm build is CI's run, not this card's; declared as a narrowing rather than reported as a pass.
• pnpm --filter @objectstack/core typecheck exit 0 (three legs: tsc --noEmit, tsconfig.examples.json, check:test-typecheck).
• pnpm --filter @objectstack/core test exit 0 — 51 test files, 1316 tests passed.
• pnpm --filter '@objectstack/core...' build exit 0 (core plus its dependency closure), run before every gate and measurement that reads dist/.
• pnpm lint narrowed to a measurement rather than skipped. ESLint's universe read from eslint.config.mjs itself: every config block's files is a {ts,tsx,mts,cts,js,jsx,mjs,cjs} glob and no block names Markdown. ESLint's own count over the changed file, from --format json: 1 result, 0 errors, and the one message is "File ignored because no matching configuration was supplied." Invariance over untouched files: the config enables no type-aware linting anywhere — no parserOptions.project, no typed rules, as the config's own recorded measurement at line 328 states — so this diff cannot move any other file's verdict.
• pnpm check:nul-bytes exit 0, plus a direct control-character scan of the changed file, which found none.
• All heavy runs went through scripts/pm/os-verify-lock.sh with a stable slot; every verdict above is read from its VERDICT command-exit line.

Measurements taken at b6606cdc2d, which is the only commit on this branch.

Acceptance notes

• The ## References section still links [Protocol Definitions](../spec/src/system/), while the Phase 2 components this file documents are Kernel-domain schemas under packages/spec/src/kernel/. The link resolves to a directory that exists, so it is not dead and nothing fails when copied — a documentation nit, none of the three filable classes. Noted, not filed. No PR and no person is queued on this file today, so there is no carrier for it beyond the next sweep of the document.
• needs:contract-review is the dispatching seat's label. This PR neither hangs it, removes it, nor waits on it; its presence and the --pair exit code are reported to the seat as readings.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/core/PHASE2_IMPLEMENTATION.md), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/core/PHASE2_IMPLEMENTATION.md) — pages documenting those are invisible to this run
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 24 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 51297e9ee17db23f50d38c1431f5a4dcc47632ff → packageMentionDocs.