Repository navigation
Commit 02e19a7
docs(core): repair four copy-fails in PHASE2_IMPLEMENTATION.md (#18712)
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 #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](https://claude.ai/code/session_01CqmCgU5RGDoJYhHUMVp2af)_
Co-authored-by: Claude <noreply@anthropic.com>1 parent df1b275 commit 02e19a7
1 file changed
Lines changed: 19 additions & 13 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
10 | 10 | | |
11 | 11 | | |
12 | 12 | | |
13 | | - | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
14 | 16 | | |
15 | 17 | | |
16 | 18 | | |
17 | 19 | | |
18 | | - | |
| 20 | + | |
19 | 21 | | |
20 | 22 | | |
21 | 23 | | |
| |||
52 | 54 | | |
53 | 55 | | |
54 | 56 | | |
55 | | - | |
56 | | - | |
| 57 | + | |
57 | 58 | | |
58 | 59 | | |
59 | 60 | | |
| |||
213 | 214 | | |
214 | 215 | | |
215 | 216 | | |
216 | | - | |
| 217 | + | |
217 | 218 | | |
218 | 219 | | |
219 | 220 | | |
| |||
238 | 239 | | |
239 | 240 | | |
240 | 241 | | |
241 | | - | |
| 242 | + | |
242 | 243 | | |
243 | 244 | | |
244 | 245 | | |
| |||
312 | 313 | | |
313 | 314 | | |
314 | 315 | | |
| 316 | + | |
315 | 317 | | |
316 | 318 | | |
317 | 319 | | |
| |||
321 | 323 | | |
322 | 324 | | |
323 | 325 | | |
| 326 | + | |
| 327 | + | |
| 328 | + | |
| 329 | + | |
| 330 | + | |
324 | 331 | | |
325 | | - | |
326 | | - | |
327 | | - | |
328 | | - | |
329 | | - | |
| 332 | + | |
| 333 | + | |
| 334 | + | |
| 335 | + | |
| 336 | + | |
330 | 337 | | |
331 | 338 | | |
332 | 339 | | |
| |||
346 | 353 | | |
347 | 354 | | |
348 | 355 | | |
349 | | - | |
| 356 | + | |
350 | 357 | | |
351 | 358 | | |
352 | 359 | | |
| |||
376 | 383 | | |
377 | 384 | | |
378 | 385 | | |
379 | | - | |
380 | 386 | | |
381 | 387 | | |
0 commit comments