docs(coherence): record the dead reporting channel and #161's slice
Rides this PR per COHERENCE.md §25 ("when a PR changes any audited claim
here, updating this file rides that PR").
§0 and §7: multi-root LSP affinity moves from in-flight-branch to PR
#161, and §7 gains the rule the slice actually establishes — a
*fallback* root is deliberately NOT an identity, so markerless files
keep sharing one server per language. That is the part a reader would
otherwise assume went the other way.
§1.2 gains the finding this PR turned up, which sharpens the audit
rather than restating it. The section recorded that background failures
produce "no `*errors*` entry"; the sharper fact is that **the channel
does not exist**. Fifteen call sites — `async.lua` (5), `syntax.lua`
(4), and one each in `lsp.lua`, `mcp.lua`, `fs.lua`, `editops.lua`,
`autosave.lua`, `commands/default.lua` — report through `pmacs.error`,
each guarded `if pmacs.error then ...`. It is defined nowhere in
production; the only assignment in the tree is a test stub
(`src/editor.rs:9881`), and `type(pmacs.error)` is nil in a fresh
`EditorState` (probed, not inferred). `pmacs.errors` plural in
compile.lua is an unrelated namespace. All fifteen are dead, and the
guard is what kept it unnoticed — it makes the silence read as
deliberate.
Hence the corollary now recorded beside the rule: report through a
channel with a **test that observes it**, or the guard is
indistinguishable from the silence it was meant to fix.
Also a frequency note: per-root affinity makes the
preconfigured-but-missing-server failure fire once per project root
rather than once per language per session. Unchanged in kind, strictly
more frequent. Surfacing it stays Priority 1 work needing its own
framing — it is user-visible product behavior (what message, where,
with what guidance), not a substrate fix to smuggle into an affinity PR.
Line-number citations in the touched sections re-verified per §25;
symbols are authoritative where they drifted.
This commit is contained in:
parent
3952db9657
commit
b5bea3b2f5
49
COHERENCE.md
49
COHERENCE.md
|
|
@ -120,9 +120,8 @@ asymmetry**, and **per-arc coherence debt**.
|
|||
|
||||
Coherence-shaped work already in flight at audit time: find-file /
|
||||
dired Stage 0 (`C-x C-f`, PR #162, `docs/dired-framing.md`), bottom
|
||||
panel Stage 1 (merged #155), multi-root LSP affinity (branch
|
||||
`lsp-multi-root-affinity`), the config registry foundation (merged
|
||||
#127).
|
||||
panel Stage 1 (merged #155), multi-root LSP affinity (PR #161), the
|
||||
config registry foundation (merged #127).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -230,9 +229,37 @@ This directly contradicts the product thesis (§23): the "without
|
|||
freezing" half is delivered; the "without becoming opaque" half is
|
||||
currently false for exactly the failures a new user will hit first.
|
||||
|
||||
**The reporting channel the runtime believes it has does not exist.**
|
||||
Fifteen call sites — `async.lua` (5), `syntax.lua` (4), and one each in
|
||||
`lsp.lua`, `mcp.lua`, `fs.lua`, `editops.lua`, `autosave.lua`, and
|
||||
`commands/default.lua` — report background failures through
|
||||
`pmacs.error`, each guarded as `if pmacs.error then pmacs.error(...)`.
|
||||
**`pmacs.error` is never defined in production** — the only assignment
|
||||
in the tree is a test stub (`src/editor.rs:9881`), and
|
||||
`type(pmacs.error)` is `nil` in a fresh `EditorState`. So every one of
|
||||
those fifteen reports is dead: the guard makes the silence look
|
||||
deliberate and keeps it from ever being noticed. `pmacs.errors` (plural,
|
||||
`builtin/runtime/compile.lua:45`) is an unrelated namespace and is not
|
||||
it. This is the silence asymmetry one level deeper than §1.2 first
|
||||
recorded — not "the failure isn't surfaced" but "the surface was
|
||||
written, guarded, and never built." Found while landing PR #161, which
|
||||
nearly added a sixteenth; that one reports via
|
||||
`pmacs.editor.set_status` (which exists) with the `pmacs.error` arm
|
||||
riding along for when the channel is built.
|
||||
|
||||
**Rule to adopt:** anything that fails automatically must leave a
|
||||
user-visible trace with a named owner. A `pcall` around background
|
||||
wiring must log attributed failure, never discard it.
|
||||
wiring must log attributed failure, never discard it. Corollary from the
|
||||
above: report through a channel with a **test that observes it**, or the
|
||||
guard is indistinguishable from the silence it was meant to fix.
|
||||
|
||||
**Frequency note (PR #161):** per-root server affinity means the
|
||||
preconfigured-but-missing-server failure now fires **once per project
|
||||
root** rather than once per language per session. The silence is
|
||||
unchanged in kind; it is strictly more frequent. Surfacing it stays
|
||||
Priority 1 work with its own framing — it is a user-visible product
|
||||
behavior (what message, where, with what guidance), not a substrate fix
|
||||
to smuggle into an affinity PR.
|
||||
|
||||
### 1.3 Ground truth: coherence debt compounds per-arc
|
||||
|
||||
|
|
@ -726,12 +753,14 @@ per-subsystem conventions.**
|
|||
nil/`"."`. Nothing owns the set {roots, servers, terminals, tasks,
|
||||
layout} — which is why desktop-save under a daemon had nothing
|
||||
principled to attach to (Q#DS9, §2 step 12).
|
||||
- **First slice in flight**: the multi-root LSP server-affinity work
|
||||
(branch `lsp-multi-root-affinity`) makes *(language, found-root)* the
|
||||
server identity — the first time a root functions as an identity key
|
||||
rather than a spawn parameter. Note it is again per-subsystem: LSP
|
||||
learns roots; compile, search, index, and trust do not share the
|
||||
object.
|
||||
- **First slice landed (PR #161)**: the multi-root LSP server-affinity
|
||||
work makes *(language, found-root)* the server identity — the first
|
||||
time a root functions as an identity key rather than a spawn
|
||||
parameter. It also establishes the rule that a *fallback* root (the
|
||||
file's own directory, when no marker was found) is deliberately **not**
|
||||
an identity, so markerless files keep sharing one server per language.
|
||||
Note it is again per-subsystem: LSP learns roots; compile, search,
|
||||
index, and trust do not share the object.
|
||||
|
||||
A workspace entity is a **model gap** (real arc), not wiring. It is also
|
||||
the prerequisite that keeps §8 (locations), §9 (task ownership), §11
|
||||
|
|
|
|||
Loading…
Reference in New Issue