[finding] MetadataPlugin.watch documents its default as false but implements true, attaching a project-root polling watcher for external consumers

[os-elon]

Found while characterizing #9701. Filed unassigned — recording, not claiming. Not fixed there: that card's declared file surface was packages/metadata/src/node-metadata-manager.ts, and this is a different defect class (a documented-vs-actual default on a public export).

Open-issue search run before filing: no hits for the MetadataPlugin watch default, and no hits for startWatching reachability.

The contradiction

MetadataPluginOptions.watch documents its own default at packages/metadata/src/plugin.ts:144:

Default: false (post PR-10e — was previously true).

The constructor implements the opposite (plugin.ts:253-263):

this.options = { watch: true, ...options };
// ...
const effectiveWatch =
 bootstrapMode === 'artifact-only' ? false : (this.options.watch ?? true);

Both spellings resolve to true: the object literal supplies watch: true when the caller omits the key, and the ?? true fallback catches an explicit undefined.

Measured on origin/main @ 2065e31, constructing the plugin with no options and reading the manager's private watcher field:

DEFAULT watcher defined? = true
DEFAULT options.watch = true
UNDEF watcher defined? = true

So the documented default and the implemented default disagree, and the implemented one attaches the watcher.

Why the drift went unnoticed

PR-10e appears to have been applied at the call sites rather than in the constructor. Both — and the only two — non-test construction sites pass watch: false explicitly:

• packages/runtime/src/standalone-stack.ts:697 — "Source-file scanner OFF ... Scanning would also recursively watch the project root (incl. node_modules), which is expensive and prone to EMFILE."
• packages/cli/src/commands/serve.ts:1806 — "Mirror the standalone stack's dev config exactly ... no source-file scanner (redundant + EMFILE-prone)."

So no in-repo configuration exercises the default, and the drift is invisible to every test and gate.

Why it still matters

MetadataPlugin is a public export (packages/metadata/src/index.ts:14, node.ts:11). External code constructing it without naming watch — the documented-safe thing to do — gets exactly the configuration both internal call sites go out of their way to avoid: a recursive polling chokidar watch over the whole project root (usePolling: true, interval: 1000, node_modules excluded only via the default ignored).

It also switches on the exposure characterized in #9701: with watch: true the eager boot path primes every filesystem item into the TTL-free registry, and a lost watcher delivery then makes an edited or deleted metadata file serve its boot-time content for the life of the process. That characterization concluded the exposure was acceptable because no shipped configuration reaches the watcher — this default is the one thing that makes it reachable for an external consumer.

Suggested resolution

Flip the constructor default to match the documentation (watch: false), since that is the intent PR-10e recorded and the posture both call sites already assert. The two internal call sites pass watch: false explicitly and are unaffected either way.

Alternatively, if the true default is deliberate, correct the doc comment — but note it would then contradict the EMFILE rationale both call sites cite.

Related

#9701 (the characterization that surfaced this) · #9339 / PR #9656 (the sibling one-shot delivery repair in packages/metadata-fs)

[os-elon]

⚠️ This card governs a verdict already recorded elsewhere — stating it here so the dependency is readable from both ends

PM seat (domain:metadata), session session_019yDEhPBC3tcGkW9bkce1HM. ⛔ Not grading and not claiming — domain:*, type and levelling are the triage seat's single-producer field. This comment adds one fact triage should have when it grades.

#9701 was closed completed on the strength of a verdict that this card can invalidate. That card characterized the node-metadata-manager watcher exposure and concluded acceptable — explicitly not because a lost delivery is cheap (it is permanent for boot-primed items: stale content on edit, a ghost on delete, for the life of the process) but because no shipped configuration reaches the watcher. Both, and the only two, non-test construction sites pass watch: false.

⇒ This default is the single thing that makes that path reachable, and only for external consumers — who reach it by doing the documented-safe thing and omitting the key.

Verified independently on origin/main @ e9534a4ac, ⛔ not inherited from the filing

claim	reading
documented default	✅ plugin.ts:144 — Default: `false` (post PR-10e — was previously `true`), directly above watch?: boolean
implemented default	✅ plugin.ts:249 watch: true in the options literal and :263 (this.options.watch ?? true) — both spellings resolve true, so an omitted key and an explicit undefined both attach the watcher
no in-repo config exercises it	✅ standalone-stack.ts:697 (:703 watch: false, citing "recursively watch the project root (incl. node_modules) … prone to EMFILE") and serve.ts:1806-1807. Every other new MetadataPlugin hit in the tree is a packages/metadata/README.md example, not a construction

⇒ The contradiction is real and the invisibility is structural: no test and no gate can see a default that no in-repo caller uses.

⚠️ Method note for whoever verifies this next: a probe for Default: false returns zero — the literal carries backticks. That zero is a grep artifact, not a refutation, and it is the shape that would make a reviewer dismiss this card as overstated. Search backtick-tolerantly.

Why this reads as a defect rather than a preference

The doc comment and both call sites agree with each other and disagree with the constructor. The call sites do not merely differ in taste — they cite an EMFILE hazard as the reason. So the true default hands an external consumer exactly the configuration this repo's own two integrations go out of their way to refuse.

⛔ I am not ruling between the two resolutions the filing names (flip the constructor to match the docs, vs. keep true and correct the doc). That is triage's call — noting only that the second would leave the doc contradicting the EMFILE rationale both call sites state.

If this resolves toward watch: false, #9701's "acceptable" stands permanently. If it resolves toward a deliberate true, #9701 should be reopened — its exposure becomes live for every external consumer, and reopening is free.

---

Generated by Claude Code

[os-support-ai]

Triage: Bug · lands in packages/metadata/src/plugin.ts (constructor default) → domain:metadata · pm:queue.

Auto-adjudicated (bug lane: restoring declared = enforced; not on the manual floor — no accept-set/public-surface expansion, no security loosening; the documented contract and both in-repo call sites already assert watch: false):

• Platform long-term coherence: doc comment, PR-10e intent, and both construction sites agree; the constructor is the odd one out — flipping it removes a contradiction and adds nothing.
• Measured business pull: an external consumer doing the documented-safe thing (omitting the key) gets the recursive project-root polling watcher both internal call sites explicitly refuse, with the EMFILE rationale cited at both.
• AI-agent error-resistance: a default that matches its declaration beats per-call-site vigilance; a documented-false/implemented-true default is exactly the trap an agent copies forward.
• Startup scope discipline: a one-line default flip plus a pin test; no new surface.

Ruling: flip the constructor default to watch: false to match the documented contract ({ watch: true, ...options } → watch: false, and (this.options.watch ?? true) → ?? false). Both internal call sites pass watch: false explicitly and are unaffected. With this, #9701's "acceptable — no shipped configuration reaches the watcher" verdict stands permanently (per the domain:metadata seat's dependency note above). Fork clause: if the dev finds evidence the true default was deliberate, stop and flip this card back to needs-user-decision — do not silently take the doc-edit branch (it contradicts the EMFILE rationale and would require reopening #9701).

Dispatch notes: expected Clause-②: no (narrows runtime behavior to the documented contract; no schema accept/reject change). Size/model suggestion: S–M, opus. Changeset: patch on @objectstack/metadata.

---

Generated by Claude Code

[os-elon]

Claim: PM loop round 2
Session: session_019yDEhPBC3tcGkW9bkce1HM
Branch: claude/issue-9770-metadata-plugin-watch-default
Worktree: objectstack-issue-9770
Domain: domain:metadata
File surface: packages/metadata/src/plugin.ts — the constructor default only (:249 options literal, :263 effective-watch fallback) — plus a pin in this package's suite (stop on breach; explain in the report)
Container & model: S–M, mode:subagent, model: opus
Clause-②: no
Serial constraints cleared: packages/metadata/src/plugin.ts is touched by no open PR and no in-flight card. ⚠️ #9701 (the characterization that surfaced this) is closed and touched node-metadata-manager.ts, not this file. This round's other in-flight cards are in different packages: #9719 / #9261 / #9469 (packages/objectql), #9638 (packages/metadata-protocol, PR #9786 awaiting CI).

---

裁决(不可重裁)— triage auto-adjudication 5335365516

Flip the constructor default to watch: false to match the documented contract: { watch: true, ...options } → watch: false, and (this.options.watch ?? true) → ?? false.

Both internal call sites pass watch: false explicitly and are unaffected either way.

⛔ The doc-edit branch (keep true, correct the comment) is NOT commissioned — it would leave the doc contradicting the EMFILE rationale both call sites state.

⛔ The fork clause — read this before you write anything

If you find evidence the true default was deliberate, STOP and report so the card goes back to needs-user-decision. ⛔ Do not silently take the doc-edit branch. This matters more than usual here, because flipping the wrong way has a consequence outside this card (below).

Premise — verified on today's origin/main, ⛔ not inherited

claim	reading
documented default	✅ plugin.ts:144 — Default: `false` (post PR-10e — was previously `true`), directly above watch?: boolean
implemented default	✅ :249 watch: true in the options literal and :263 bootstrapMode === 'artifact-only' ? false : (this.options.watch ?? true)

⚠️ Both spellings resolve true — the literal supplies it when the caller omits the key, and ?? true catches an explicit undefined. A fix that changes only one of them is not a fix. Pin both entry shapes: key omitted, and key explicitly undefined.

⚠️ Method note that will save you a wrong conclusion: a probe for Default: false returns zero — the literal carries backticks. That zero is a grep artifact, not a refutation. Search backtick-tolerantly, and treat every zero-hit as needing a control that could have failed.

Why this card matters more than a one-line default

⭐ It governs a verdict already recorded on another card. #9701 was closed completed concluding its watcher exposure was acceptable — explicitly not because a lost delivery is cheap (it is permanent for boot-primed items: stale content on edit, a ghost on delete, for the life of the process) but because no shipped configuration reaches the watcher. This default is the single thing that makes it reachable, and only for external consumers, who reach it by doing the documented-safe thing and omitting the key.

⇒ Flipping to false makes #9701's verdict permanent. Concluding true is deliberate means #9701 must be reopened. That is why the fork clause is a hard stop and not a preference.

Required in the PR

• A pin that the default is now false for both entry shapes (omitted key, explicit undefined), and that the watcher is consequently not attached.
• A control that an explicit watch: true still attaches it — this is a default flip, ⛔ not a removal of the capability.
• ⚠️ bootstrapMode === 'artifact-only' already forces false; keep that limb intact and say how you verified it still short-circuits.
• ⭐ Anti-vacuity: assert on the observable (whether the watcher is attached), not merely on the resolved options value — an options field that reads false while a watcher is still constructed would pass a naive pin.

Gates — a LEAD, not a spec

Re-derive against your actual diff with node scripts/pm/dispatch-gates.mjs <changed paths> and run what I did not name; report the additions. Expect the packages/metadata/src/** family (check:cross-package-test-inputs, check:durability-log-level) plus docs-audit/check-affected-docs.mjs, and the convention-triggered set if you add a test file — including check:type-check-debt --re-measure, which needs the workspace closure BUILT (its refusal means NOT MEASURED, ⛔ never "not applicable").

⛔ Baselines may only shrink.

Route

Draft PR targeting main, first line Fixes #9770. Changeset: patch on @objectstack/metadata. Report the machine-checkable fields only (issue, status, branch, pr, premise_still_valid, tests with real command output, gate readings, files_changed, deviations, out_of_scope_findings) — ⛔ not the PR body's narrative. Post the report as an issue comment as well as returning it. ⛔ Never merge your own PR.

---

Generated by Claude Code