docs: destination-capture revision 3 --- decide Q#DC-4, pin the gate line
Q#DC-4 contradicted Q#DC-2, and on the primary panel API. Q#DC-2 concluded a panel profile depends only on a live frontend, so it can commit with no document window at all; Q#DC-4 still voted to return nil in exactly that case and told git to fall back to ambient behaviour. Those cannot both hold, and the fallback advice was independently wrong: falling back to ambient IS the P1a bug this lane exists to remove. Decided rather than voted on, since it is the primary API. The destination document pair is optional; capture_destination() is profile-blind and argument-free, because making capture profile-aware would force a caller to know at capture time what it will do at commit time, which is the opposite of why capture exists. The profile is declared at commit_to, where Q#DC-2 parameterization already lives, and a document-profile commit with no document pair is refused alongside the other four preflight refusals. Capture never returns nil while a frame exists. Section 4 outline and Q#DC-1 were updated to match rather than left to disagree --- Q#DC-1 no-arguments answer is now load-bearing rather than incidental, because no arguments is what keeps capture profile-blind. The ledger gate line said "new suite plus dired". --acceptance is repeatable, so it now carries the executable command including journey_acceptance and dired_acceptance, both named as preservation suites and a stop signal. A volatile ledger that understates required coverage is how a recovering machine runs a weaker gate than the lane agreed to. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016bqGA6s9tTUFzYpbeW3tai
This commit is contained in:
parent
91e4e514a1
commit
6b8e07c730
|
|
@ -275,7 +275,7 @@ from #171 and #215.
|
|||
authoritative tip** — the ref, not a SHA. Recover with
|
||||
`git fetch githubsucks && git checkout destination-capture`.
|
||||
|
||||
- **Framing `docs/destination-capture-framing.md`, revision 2**, in
|
||||
- **Framing `docs/destination-capture-framing.md`, revision 3**, in
|
||||
review. Revision 2 took three findings: Q#DC-2's parameterization was
|
||||
incomplete (a panel depends on **none** of checks 2–4, not just check
|
||||
3, so the question now carries a full preflight matrix with every
|
||||
|
|
@ -314,8 +314,22 @@ authoritative tip** — the ref, not a SHA. Recover with
|
|||
- **Stop signal recorded in the framing:** if any existing dired test
|
||||
needs editing, the generalization changed Journey Stage 1a's
|
||||
semantics, and that is cause to stop rather than to adjust the test.
|
||||
- **Gates:** `scripts/gate --acceptance <the new suite>` plus dired's.
|
||||
No `--protocol` — core and Lua bindings only.
|
||||
- **Gates, as the executable line rather than a description:**
|
||||
|
||||
```
|
||||
scripts/gate --acceptance <the new suite> \
|
||||
--acceptance journey_acceptance \
|
||||
--acceptance dired_acceptance
|
||||
```
|
||||
|
||||
`--acceptance` is repeatable, so there is no reason for this ledger
|
||||
to say "plus dired's" and leave the reader to reconstruct it.
|
||||
**`journey_acceptance` and `dired_acceptance` are preservation suites
|
||||
and a STOP SIGNAL**: they carry the `commit_to` scope,
|
||||
forged-userdata, preflight and restoration pins this lane
|
||||
generalizes, and if either needs editing, the change altered Journey
|
||||
Stage 1a's semantics rather than closing a gap in them. No
|
||||
`--protocol` — core and Lua bindings only.
|
||||
|
||||
## LSP LaTeX coverage — IMPLEMENTED, gates green, no PR yet
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,18 @@
|
|||
# A destination capture any async continuation can use
|
||||
|
||||
**Status: framing pass, revision 2. Pre-implementation. Awaiting
|
||||
**Status: framing pass, revision 3. Pre-implementation. Awaiting
|
||||
approval.**
|
||||
|
||||
**Revision 3 decides Q#DC-4, which revision 2 left contradicting
|
||||
Q#DC-2 — on the primary panel API.** Q#DC-2 concluded a panel needs
|
||||
only a live frontend; Q#DC-4 still returned `nil` without a document
|
||||
window and told git to fall back to ambient behaviour, which is the
|
||||
very bug this lane removes. Resolved: the destination's document pair
|
||||
is **optional**, `capture_destination()` is **profile-blind and
|
||||
argument-free**, the profile is declared at `commit_to`, and a
|
||||
document-profile commit without a document pair is refused. §4 and
|
||||
Q#DC-1 were updated to match rather than left to disagree.
|
||||
|
||||
**Revision 2 takes three review findings.** Q#DC-2's parameterization
|
||||
was **incomplete** — a panel result does not depend on the captured
|
||||
document window being live or non-dedicated either, not just on its
|
||||
|
|
@ -109,7 +119,10 @@ decided, and it is the substance of this lane.
|
|||
## 4. The change, in outline
|
||||
|
||||
- **A Lua-reachable capture**, returning the same nonconstructible
|
||||
userdata for the *current* frontend and its document window.
|
||||
userdata for the *current* frontend, **with** its document window and
|
||||
buffer when it has one and without them when it does not (Q#DC-4).
|
||||
The capture takes no arguments and is profile-blind; the profile is
|
||||
declared at `commit_to`.
|
||||
- **Generic naming.** `DirectoryDestination` becomes something that
|
||||
does not lie about a git panel; `capture_directory_destination` and
|
||||
the userdata type follow. 8 references (§2).
|
||||
|
|
@ -237,14 +250,45 @@ buffer kind.
|
|||
The Q#JR14 doc comments should keep their references intact; a rename
|
||||
that orphans the rationale is worse than a slightly stale name.
|
||||
|
||||
### Q#DC-4 — is the capture refused when there is no document window?
|
||||
### Q#DC-4 — what happens when there is no document window? **(DECIDED in rev 3)**
|
||||
|
||||
`capture_directory_destination` already returns `None` when the
|
||||
frontend has no document window (`src/editor.rs:1236`). *My vote:
|
||||
**return `nil`, and require every adopter to handle it***, rather than
|
||||
inventing a fallback destination. A continuation with nowhere to land
|
||||
should say so, and #227's adopter should degrade to today's ambient
|
||||
behaviour with a status message rather than silently guessing.
|
||||
**Revision 2 left this contradicting Q#DC-2 and it is the primary panel
|
||||
API, so it is decided here rather than voted on.** Q#DC-2 concluded a
|
||||
panel profile depends only on a live frontend — so it can commit with
|
||||
no document window at all — while this question still said the capture
|
||||
returns `nil` in exactly that case, and told git to fall back to
|
||||
ambient behaviour. Those cannot both hold, and the fallback advice was
|
||||
independently wrong: falling back to ambient **is** the P1a bug this
|
||||
lane exists to remove.
|
||||
|
||||
**The decision:**
|
||||
|
||||
- **`ViewDestination { frontend, window: Option<WindowId>, buffer:
|
||||
Option<BufferId> }`.** The frontend is always present; the document
|
||||
pair is optional and absent exactly when the frontend has no document
|
||||
window.
|
||||
- **`capture_destination()` is NOT profile-aware and takes no
|
||||
arguments.** It records what is there. Making capture profile-aware
|
||||
would force the caller to know at *capture* time what it will do at
|
||||
*commit* time, which is the opposite of why capture exists — the
|
||||
whole point is to freeze the truth early and decide later.
|
||||
- **The profile is declared at `commit_to`**, which is where Q#DC-2's
|
||||
parameterization already lives. One place makes the decision, and it
|
||||
is the place that knows.
|
||||
- **A document-profile commit on a destination with no document pair is
|
||||
REFUSED**, with a reason naming that, joining the four preflight
|
||||
refusals rather than being a separate failure mode.
|
||||
- **Capture therefore never returns `nil`** while a frontend exists,
|
||||
and the "adopter degrades to ambient" advice is **withdrawn**. An
|
||||
adopter with nowhere to land gets a refusal it can report; it does
|
||||
not get permission to guess.
|
||||
|
||||
**What this changes elsewhere, so the decision does not sit alone:**
|
||||
§4's outline says the capture returns userdata "for the *current*
|
||||
frontend and its document window" — it returns one for the current
|
||||
frontend, **with** its document window when there is one. Q#DC-1's "no
|
||||
arguments" answer is unchanged and now load-bearing rather than
|
||||
incidental: no arguments is what keeps capture profile-blind.
|
||||
|
||||
## 7. Verification
|
||||
|
||||
|
|
@ -263,10 +307,13 @@ behaviour with a status message rather than silently guessing.
|
|||
asserted to **NOT refuse** under the panel profile. A deliberately
|
||||
omitted check that has no test is indistinguishable from a check
|
||||
someone forgot, and the next reader will restore it.
|
||||
- **`nil` when the frontend has no document window** (Q#DC-4) — for
|
||||
the **document** profile. Whether the panel profile can capture
|
||||
without one follows from Q#DC-2 and is asserted whichever way it is
|
||||
answered.
|
||||
- **Capture SUCCEEDS with no document window** (Q#DC-4), returning a
|
||||
destination whose document pair is absent — asserted as a successful
|
||||
capture, not as `nil`.
|
||||
- **A panel-profile commit on that destination SUCCEEDS**, and a
|
||||
**document-profile commit on it is REFUSED** with a reason naming the
|
||||
missing document window. Both halves, because asserting only the
|
||||
refusal would pass on a capture that refuses everything.
|
||||
- **The directory path is unchanged** — dired's existing acceptance
|
||||
coverage passes untouched.
|
||||
- **`tests/journey_acceptance.rs` passes UNCHANGED**, as a named
|
||||
|
|
|
|||
Loading…
Reference in New Issue