Skip to content

Commit f6782c4

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
authored
docs: session handoff 2026-05-27 — borrow deferred-items roundup (humans + machines) (#401)
## Summary Documents the entire round of work across **six open PRs** that together cover the four entries in the \`lib/borrow.ml\` deferred-items comment at lines 1483-1505. Two artefacts, one for each audience. ### For humans — \`docs/history/SESSION-HANDOFF-2026-05-27.adoc\` \`.adoc\` per the repo's DOC-FORMAT rule. Sections: - What this session actually did - **Parallel-implementation map** — which of my PRs paired with which existing PR - PR state table (draft? auto-merge? mergeability?) - **Audit findings** — the load-bearing deltas: self-assign hole + return-escape gap (#395), sub-place soundness divergence (#396), Cmd-typed-param tracking gap (#397) - **Safe-to-close conditions per PR** — the matrix the next agent needs - Cleanup performed - Guidance for the next agent ### For machines — \`.machine_readable/sessions/2026-05-27-borrow-deferred-items.a2ml\` New \`sessions/\` subdirectory (the existing \`.machine_readable/6a2/\` is the canonical state-snapshot dir; sessions are per-event records). Schema declared as \`a2ml/session-record/v1\`. Structured records: - One \`[[deferred-item]]\` per entry in the comment block - One \`[[open-pr]]\` per the six PRs - One \`[[close-condition]]\` per PR with fallback paths - \`[cleanup]\`, \`[lessons]\` blocks ### Cleanup landed alongside - \`.git/gc.log\` removed after \`git prune\` (the persistent \"unreachable loose objects\" warning is gone). - Two stale parallel-Claude untracked dirs (\`affinescript-vite/\`, \`editors/vscode/node_modules/\`) **not touched** — they're not this session's work. ## What's NOT in this PR - No \`lib/\` changes. No \`test/\` changes. - No closes/state-changes on the six open PRs (#395/#396/#397/#398/#399/#400). Per maintainer direction \"keep both PR sets open\", parallel implementations stay parallel. - No edits to \`STATE.a2ml\` or other \`6a2/\` files — those are flagged STALE and updating them is a separate disciplined task. ## Safe-to-close ledger (also in the docs) | PR | Close condition | Fallback | |---|---|---| | **#395** | auto-merge fires once CI clears | n/a | | **#396** | auto-merge fires once CI clears | if merges without sub-place fix, **#399** stays open as follow-up | | **#397** | auto-merge fires once CI clears | audit posted a must-fix; owner can incorporate or file follow-up | | **#398** | owner ratifies ADR-022 via the posted one-liner | do-not-close — only deferred-item that needs an architectural change | | **#399** | **#396** merges with sub-place fix | rebase as sub-place soundness correction | | **#400** | **#395** merges with self-assign-guard + return-escape test | rebase as follow-up adding the two missing pieces | | **this PR** | safe to close once merged | n/a — pure docs | ## Test plan - [ ] CI green (this PR only touches \`docs/\` and \`.machine_readable/\` — no test-relevant code). - [ ] \`asciidoctor docs/history/SESSION-HANDOFF-2026-05-27.adoc\` renders without errors (if you have asciidoctor installed; CI doesn't enforce). - [ ] The \`docs/history/SESSION-HANDOFF-2026-05-27.adoc\` cross-references in the body resolve to actual PR numbers / file paths in the repo. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 1efc3f3 commit f6782c4

2 files changed

Lines changed: 382 additions & 0 deletions

File tree

‎.machine_readable/sessions/2026-05-27-borrow-deferred-items.a2ml‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# SPDX-License-Identifier: MPL-2.0
2+
# SPDX-FileCopyrightText: 2026 hyperpolymath
3+
#
4+
# Session record — 2026-05-27 — lib/borrow.ml deferred-items roundup
5+
#
6+
# Human-readable companion: docs/history/SESSION-HANDOFF-2026-05-27.adoc
7+
# Canonical comment in code: lib/borrow.ml:1483-1505
8+
9+
[metadata]
10+
schema = "a2ml/session-record/v1"
11+
session-date = "2026-05-27"
12+
session-topic = "lib/borrow.ml CORE-01 #177 deferred-items roundup"
13+
repo = "hyperpolymath/affinescript"
14+
canonical-code-anchor = "lib/borrow.ml:1483-1505"
15+
human-companion = "docs/history/SESSION-HANDOFF-2026-05-27.adoc"
16+
parallel-sessions-detected = true
17+
parallel-detection-method = "PR title cross-reference after PR creation"
18+
19+
# ── The four deferred-items entries ────────────────────────────────────
20+
# Each entry tracks: which PR(s) address it, parallel-implementation
21+
# overlap, and any audit findings.
22+
23+
[[deferred-item]]
24+
id = "reborrow-through-indirection"
25+
description = "let r2 = r1 / r2 = r1 where RHS is itself a ref-binder"
26+
parallel-claude-pr = 395
27+
my-pr = 400
28+
overlap = "equivalent"
29+
multi-binder-gate-byte-identical = true
30+
my-pr-extra-coverage = ["self-assign-guard", "return-escape-fixture"]
31+
audit-comment = "https://github.com/hyperpolymath/affinescript/pull/395#issuecomment-4550230871"
32+
33+
[[deferred-item]]
34+
id = "loop-soundness-and-clear-on-rewrite"
35+
description = "StmtAssign treats LHS as a use; loops need 2-iter convergence"
36+
parallel-claude-pr = 396
37+
my-pr = 399
38+
overlap = "parallel-pr-is-superset"
39+
parallel-pr-extra = ["loop-soundness-2-iteration"]
40+
my-pr-extra = ["sub-place-write-soundness-fix"]
41+
audit-finding-severity = "real-bug"
42+
audit-finding-summary = "places_overlap is root-coarse, so x.f = e after move x silently clears the move-record on x"
43+
audit-comment = "https://github.com/hyperpolymath/affinescript/pull/396#issuecomment-4550232584"
44+
recommended-fix = "rebase #396 to incorporate is_whole_place_write predicate from #399"
45+
46+
[[deferred-item]]
47+
id = "captured-linears-slice-d"
48+
description = "reject @linear bindings captured by closures at borrow check"
49+
parallel-claude-pr = 397
50+
my-pr = ""
51+
overlap = "none — I had no parallel PR"
52+
audit-finding-severity = "real-bug"
53+
audit-finding-summary = "param-path tracks only explicit @linear; misses Cmd[T]-typed params that let_is_linear would catch"
54+
audit-hygiene-findings = [
55+
"linear_bindings not snapshot/restored at block exit",
56+
"linear_bindings not unified in merge_arm_results",
57+
"borrow_quantity_of_ty's Cmd-inference branch unreached by any fixture"
58+
]
59+
audit-comment = "https://github.com/hyperpolymath/affinescript/pull/397#issuecomment-4550278071"
60+
61+
[[deferred-item]]
62+
id = "origin-variables-polonius"
63+
description = "true Polonius surface — region vars on TyRef/TyMut with datalog loan solver"
64+
parallel-claude-pr = ""
65+
my-pr = 398
66+
overlap = "ADR-only — architectural; multi-week"
67+
adr = "ADR-022"
68+
adr-doc = "docs/decisions/0022-polonius-origin-variables.adoc"
69+
m1-sketch-branch = "core-01/polonius-m1-sketch"
70+
m1-sketch-commit = "b28757c"
71+
m1-pushed = false
72+
owner-ratify-one-liner = "gh pr ready 398 && gh pr merge 398 --auto --squash --delete-branch"
73+
74+
# ── Open-PR state at handoff ───────────────────────────────────────────
75+
76+
[[open-pr]]
77+
number = 395
78+
title = "feat(borrow): CORE-01 ref-to-ref binding (#177 pt3) — let r2 = r / r = s alias the borrow-graph"
79+
draft = false
80+
auto-merge = "SQUASH"
81+
state = "BLOCKED on CI queue"
82+
owner = "hyperpolymath"
83+
parallel-pair-mine = 400
84+
my-review = "https://github.com/hyperpolymath/affinescript/pull/395#issuecomment-4550230871"
85+
86+
[[open-pr]]
87+
number = 396
88+
title = "feat(borrow): CORE-01 Slice C' (#177 pt3) — loop soundness via 2-iteration + StmtAssign clear-on-rewrite"
89+
draft = false
90+
auto-merge = "SQUASH"
91+
state = "BLOCKED on CI queue"
92+
owner = "hyperpolymath"
93+
parallel-pair-mine = 399
94+
my-review = "https://github.com/hyperpolymath/affinescript/pull/396#issuecomment-4550232584"
95+
96+
[[open-pr]]
97+
number = 397
98+
title = "feat(borrow): CORE-01 Slice D (#177 pt3) — reject @linear capture by closure at borrow check"
99+
draft = false
100+
auto-merge = "SQUASH"
101+
state = "BLOCKED on CI queue"
102+
owner = "hyperpolymath"
103+
parallel-pair-mine = ""
104+
my-review = "https://github.com/hyperpolymath/affinescript/pull/397#issuecomment-4550278071"
105+
106+
[[open-pr]]
107+
number = 398
108+
title = "docs(adr): ADR-022 — origin variables + Polonius-style loan solver (Refs #177)"
109+
draft = true
110+
auto-merge = "OFF (drafts cannot arm)"
111+
state = "BLOCKED on CI queue"
112+
owner = "hyperpolymath"
113+
ratify-one-liner = "gh pr ready 398 && gh pr merge 398 --auto --squash --delete-branch"
114+
115+
[[open-pr]]
116+
number = 399
117+
title = "fix(borrow): whole-place assignment clears move-record (Refs #177)"
118+
draft = true
119+
auto-merge = "OFF (drafts cannot arm)"
120+
state = "BLOCKED on CI queue"
121+
owner = "hyperpolymath"
122+
parallel-pair-theirs = 396
123+
close-condition = "#396 merges with sub-place soundness fix incorporated"
124+
125+
[[open-pr]]
126+
number = 400
127+
title = "fix(borrow): propagate ref-binding through reborrow indirection (Refs #177)"
128+
draft = true
129+
auto-merge = "OFF (drafts cannot arm)"
130+
state = "BLOCKED on CI queue"
131+
owner = "hyperpolymath"
132+
parallel-pair-theirs = 395
133+
close-condition = "#395 merges with self-assign-guard + return-escape-test incorporated"
134+
135+
# ── Safe-to-close ledger ──────────────────────────────────────────────
136+
137+
[[close-condition]]
138+
pr = 400
139+
condition = "#395 merges with self-assign-guard + return-escape-test"
140+
fallback = "rebase onto main as follow-up adding the two missing pieces"
141+
142+
[[close-condition]]
143+
pr = 399
144+
condition = "#396 merges with sub-place soundness fix (is_whole_place_write predicate)"
145+
fallback = "rebase onto main as sub-place soundness correction"
146+
147+
[[close-condition]]
148+
pr = 398
149+
condition = "owner ratifies ADR-022 via posted one-liner"
150+
fallback = "do-not-close — only deferred-item that needs an architectural change"
151+
152+
[[close-condition]]
153+
pr = 395
154+
condition = "auto-merge fires once CI clears"
155+
note = "owner-side; review comment is informational, not blocking"
156+
157+
[[close-condition]]
158+
pr = 396
159+
condition = "auto-merge fires once CI clears (with or without sub-place fix)"
160+
followup-needed = "if-merges-without-fix"
161+
followup-pr = 399
162+
163+
[[close-condition]]
164+
pr = 397
165+
condition = "auto-merge fires once CI clears"
166+
note = "audit posted real-bug for Cmd-typed params; owner can incorporate or file follow-up"
167+
168+
# ── Cleanup performed this session ────────────────────────────────────
169+
170+
[cleanup]
171+
git-gc-log-removed = true
172+
git-prune-run = true
173+
local-branches-kept = ["core-01/polonius-m1-sketch (b28757c, M1 sketch for ADR-022)"]
174+
175+
# ── Lessons for the next agent ────────────────────────────────────────
176+
177+
[lessons]
178+
root-cause-of-duplicate-work = "previous-session-summary listed PRs only by status (MERGEABLE/BLOCKED), not by title; treated them as opaque siblings and re-did work"
179+
mitigation = "before starting work on any open issue/area, gh pr list --state open and gh pr view <n> on every open PR in the touched area"
180+
disambiguation-reminder = "AffineScript ≠ Ephapax; see feedback_affinescript_ephapax_siblings_not_impl_proof.md in user auto-memory"

‎docs/history/SESSION-HANDOFF-2026-05-27.adoc‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
// SPDX-License-Identifier: MPL-2.0
2+
// SPDX-FileCopyrightText: 2026 hyperpolymath
3+
= Session handoff — 2026-05-27 — `lib/borrow.ml` deferred-items roundup
4+
:toc:
5+
:toclevels: 2
6+
7+
[NOTE]
8+
====
9+
This session worked the four deferred-items entries at `lib/borrow.ml:1483-1505`
10+
(the comment block beginning "Still deferred:") across multiple parallel Claude
11+
sessions. The result is **six open PRs** that together cover the entire
12+
deferred-items surface except origin-variables/Polonius, plus three formal
13+
review comments documenting overlaps and audit findings. **Nothing is merged
14+
yet** — everything is owner-gated either on draft-status or on the GitHub
15+
Actions queue drain.
16+
====
17+
18+
== What this session actually did
19+
20+
1. Drafted **ADR-022** at `docs/decisions/0022-polonius-origin-variables.adoc`
21+
+ a structured `[[adr]]` block in `.machine_readable/6a2/META.a2ml`,
22+
shipped as draft PR **#398**.
23+
2. Cut a minimal **M1 sketch** for ADR-022 (`origin_var option` on
24+
`TyRef`/`TyMut` + a `lib/borrow_polonius/` sublibrary skeleton) — kept
25+
local on branch `core-01/polonius-m1-sketch` (commit `b28757c`), not
26+
pushed pending ADR ratification.
27+
3. Filed two more PRs landing scoped fixes for two of the four deferred-items
28+
entries:
29+
* **#399** — `fix(borrow): whole-place assignment clears move-record`
30+
(the StmtAssign half of Slice C').
31+
* **#400** — `fix(borrow): propagate ref-binding through reborrow indirection`
32+
(the "reborrow through indirection" item).
33+
4. Discovered three pre-existing PRs (**#395 / #396 / #397**) from a parallel
34+
Claude session covering the same items. Per maintainer direction
35+
("keep both PR sets open"), did not close mine; instead posted formal
36+
audit comments on the parallel-Claude PRs documenting deltas and one
37+
real soundness gap (see below).
38+
39+
== Parallel-implementation map
40+
41+
[cols="1,1,3,1", options="header"]
42+
|===
43+
| Deferred-item entry | Parallel-Claude PR | My PR | Same scope?
44+
| Reborrow through indirection | #395 | #400 | Yes — equivalent
45+
| Loop soundness + clear-on-rewrite | #396 | #399 | #396 is superset, but has a soundness gap
46+
| Captured linears (Slice D) | #397 | _none_ | I had no parallel; only an audit comment
47+
| Origin/region variables (Polonius) | #398 (mine) | #398 | ADR-only; M1 sketch local
48+
|===
49+
50+
== PR state at handoff
51+
52+
[cols="1,1,1,1,3", options="header"]
53+
|===
54+
| PR | Draft? | Auto-merge | Mergeability | Notes
55+
| #395 | non-draft | SQUASH ON | BLOCKED on CI | Owner-side; review comment posted
56+
| #396 | non-draft | SQUASH ON | BLOCKED on CI | Owner-side; review comment flags one soundness gap
57+
| #397 | non-draft | SQUASH ON | BLOCKED on CI | Owner-side; audit comment posted (must-fix flagged)
58+
| #398 | **draft** | OFF (drafts can't arm) | BLOCKED on CI | Mine; owner-ratify one-liner posted in thread
59+
| #399 | **draft** | OFF (drafts can't arm) | BLOCKED on CI | Mine; parallel-equivalent of #396
60+
| #400 | **draft** | OFF (drafts can't arm) | BLOCKED on CI | Mine; parallel-equivalent of #395
61+
|===
62+
63+
CI for every one of these PRs sat in the GitHub Actions runner queue at
64+
session close (`QUEUED: 17, IN_PROGRESS: 0`). That is a GitHub-side backlog,
65+
not a per-PR issue.
66+
67+
== Audit findings (the load-bearing deltas)
68+
69+
These are paraphrased; the full text lives on the GitHub PRs.
70+
71+
=== #395 vs #400 (reborrow through indirection)
72+
73+
Both PRs do the same three things:
74+
75+
* Recognise `let r2 = r1` / `r2 = r1` where the RHS is itself a ref-binder.
76+
* Multi-binder gate in `expire_dead_ref_bindings` so a shared borrow only
77+
ends when no live binder still aliases it — the `b'.b_id = b.b_id`
78+
check (**byte-identical between the two PRs**).
79+
* Symmetric handling on the `StmtAssign` reborrow path.
80+
81+
Two deltas only #400 has:
82+
83+
* Self-assign guard for `r = r`. Without it, the pre_release path ends `r`'s
84+
borrow and the post-rebind never re-attaches, silently unbinding `r` from
85+
the borrow-graph. Both PRs have the bug; only #400 guards it.
86+
* `return r2` where `r2 = r1 = &local` is exercised by
87+
`borrow_reborrow_indir_escape.affine`. #395's three fixtures (`let_aliases`,
88+
`protects_owner`, `assign_aliases`) don't cover the return-escape path,
89+
which is historically the most-leaked surface for this class of bug.
90+
91+
=== #396 vs #399 (clear-on-rewrite + loop soundness)
92+
93+
#396 is a **superset of #399 feature-wise** (it also does the 2-iteration
94+
loop check that #399 doesn't). One real soundness divergence in the
95+
StmtAssign half:
96+
97+
[source,affine]
98+
----
99+
fn unsound() -> Point {
100+
let x = Point { ... };
101+
drop_point(x); // move x
102+
x.f = 5; // expected: UseAfterMove
103+
// #399: rejects (is_whole_place_write predicate)
104+
// #396: SILENTLY ACCEPTS — places_overlap is root-coarse,
105+
// so this clears the move-record on x
106+
x
107+
}
108+
----
109+
110+
#399 gates both the `find_move` skip and the move-record clearing on an
111+
`is_whole_place_write` predicate (`place is PlaceVar _`). #396 unconditionally
112+
skips the check and clears overlapping move-records, which is correct for
113+
whole-place writes but unsound for sub-place writes (`x.f = …`, `x[i] = …`)
114+
because the root-coarse `places_overlap` reports a sub-place as overlapping
115+
its parent's move-record.
116+
117+
None of #396's three fixtures exercise sub-place writes after moves, so CI
118+
does not catch this.
119+
120+
=== #397 audit (Slice D captured linears)
121+
122+
I had no parallel PR for this item; posted an audit-only review.
123+
124+
**One real bug:** Param-path tracking checks only `p.p_quantity = Some QOne`
125+
and misses the `Cmd[T]`-typed param (no explicit `@linear`) case that the
126+
let-statement path correctly catches via the `let_is_linear` helper. So
127+
`fn f(c: Cmd[Int]) { let g = fn() => use(c); }` silently slips through
128+
borrow-side rejection, falling back to the downstream quantity-checker
129+
diagnostic (which is the regression Slice D's existence is meant to fix).
130+
131+
**Hygiene:** `linear_bindings` is not snapshot/restored at block exit (unlike
132+
`borrows`, `block_local_syms`, `ref_bindings`) and is not unified in
133+
`merge_arm_results`. Benign in practice (`sym_id`s don't recycle) but
134+
inconsistent.
135+
136+
**Coverage gap:** The inference helper `borrow_quantity_of_ty` (the
137+
`Cmd _ → QOne` branch) is unreached by any fixture. All three current
138+
fixtures use explicit `@linear`. If somebody renames "Cmd", the inference
139+
silently breaks.
140+
141+
== Safe-to-close conditions
142+
143+
Use this matrix when triaging the open PRs:
144+
145+
#400 (mine, reborrow indirection)::
146+
**Safe to close once #395 merges**, provided #395 incorporates the two deltas
147+
from the audit (self-assign guard + return-escape test). If #395 merges
148+
without them, #400 stays open and is rebased onto main as a follow-up that
149+
adds just the missing pieces.
150+
151+
#399 (mine, assign-clears-move)::
152+
**Safe to close once #396 merges with the sub-place fix.** If #396 merges
153+
without the `is_whole_place_write` predicate, #399 stays open and is rebased
154+
onto main as a sub-place soundness correction.
155+
156+
#398 (mine, ADR-022 Polonius)::
157+
Stays open as draft pending owner ratification. The one-liner
158+
`gh pr ready 398 && gh pr merge 398 --auto --squash --delete-branch` is
159+
posted in the thread; safe to close in a "won't-do" sense only if the
160+
owner decides not to pursue origin-variables at all (unlikely — it's the
161+
only deferred-item that genuinely needs an architectural change).
162+
163+
#395 / #396 / #397::
164+
Owner-merge gated. Auto-merge SQUASH is armed; once the GH Actions runner
165+
backlog drains and CI clears, they land. The review comments are
166+
informational and don't block merge.
167+
168+
This documentation PR::
169+
**Safe to close once merged.** Once on `main`, this doc serves as the
170+
canonical handoff for the next session that touches `lib/borrow.ml`
171+
deferred-items work.
172+
173+
== Cleanup performed this session
174+
175+
* `.git/gc.log` removed; `git prune` run to clear the warning that was
176+
attached to every previous git operation.
177+
* Two local-only branches kept for staged follow-ups:
178+
* `core-01/polonius-m1-sketch` (commit `b28757c`) — M1 of ADR-022.
179+
* (none others as of handoff time)
180+
181+
== For the next agent reading this
182+
183+
Before doing any more `lib/borrow.ml` work:
184+
185+
1. `gh pr list --state open` and confirm none of #395/#396/#397/#398/#399/#400
186+
are already-merged. If they are, the deferred-items comment in
187+
`lib/borrow.ml` will reflect which items have been crossed off.
188+
2. If picking up a new deferred item, **`gh pr view` every open PR's title
189+
first** to avoid re-doing parallel work. The previous-session summary
190+
listing PRs only by status (MERGEABLE/BLOCKED) without titles was the
191+
root cause of this session's duplicate work.
192+
3. Cross-reference `feedback_affinescript_ephapax_siblings_not_impl_proof.md`
193+
in user auto-memory — AffineScript ≠ Ephapax, the two share zero
194+
borrow-checker code despite being substructural-logic siblings.
195+
196+
== References
197+
198+
* `lib/borrow.ml:1483-1505` — the canonical deferred-items list, updated
199+
in-place by #395/#396/#397 to cross off completed items.
200+
* `docs/decisions/0022-polonius-origin-variables.adoc` — ADR-022 design.
201+
* `.machine_readable/sessions/2026-05-27-borrow-deferred-items.a2ml` —
202+
machine-readable companion to this handoff.

0 commit comments

Comments
 (0)