__schema_columns`
A Benchling-managed table also carries a fifth name: the **manifest**. It is a
sheet-scoped name whose `refers_to` is a *string formula* listing the canonical
warehouse column names:
```
assay_x__schema_columns refers_to: ="sample,batch,result"
```
The manifest is the engine's record of *which columns Benchling owns*. It is
read by `_read_schema_manifest` and written at the end of every `_write_fresh`
and every `_reinit` (`_write_schema_manifest`). Its job is to let `_reinit`
distinguish **schema-owned columns** (which it may rename/purge when Benchling
drops them) from **manual named ranges a developer added inside the band**
(which it must leave alone β the "M.2.1" protection). It is also the ownership
key for `cleanup_stale_table_names`: no manifest β `ManifestNotFoundError`,
because this package only manages tables it created.
> Warehouse names containing a comma or `"` would break the round-trip parse, so
> `_write_schema_manifest` raises eagerly. Benchling warehouse names are
> snake_case by convention, so this never fires in practice.
### 1.5 Putting it together
A two-table stacked Benchling sheet, fully scaffolded:
A
B
C
1
Assay X (title, merged)
2
anchor assay_x = $A$2:$C$2
3
S1
B1
10start
4
S2
B1
20end
assay_x_table_start $A$3 Β· assay_x_table_end $C$4
(gap)
7
Assay Y (title, merged)
8
well
conc
odanchor
anchor assay_y = $A$8:$C$8
9
A1
5
0.2start
10
A2
5
0.3end
assay_y_table_start $A$9 Β· assay_y_table_end $C$10
Names on this sheet: `assay_x`, `assay_x_table_start`, `assay_x_table_end`,
`assay_x__schema_columns`, the per-column tokens (`sample`, `batch`, `result`),
and the same family for `assay_y`. The two tables share columns AβC, placing
them in the **same lane**, and occupy **disjoint rows** (2β4 vs 8β10). Within a
lane, row disjointness is required β see Β§2.
---
## 2. The lane model and the row-overlap invariant
A **lane** is the column-connected group of managed tables returned by
`_cluster_for_operating_table` β tables stacked vertically so that members are
**row-disjoint within the lane**. The lane's column band runs from the leftmost
column of any member to the rightmost (`min(member lefts)` β¦ `max(member rights)`).
Every row-grow and row-shrink is bounded to that band, so tables in other lanes β
**column-disjoint by construction** β are never touched.
Side-by-side, L-shaped, and T-shaped layouts are simply **several lanes in
separate column bands that happen to share rows**. Because each operation is
bounded to its own lane's columns, the lanes are independently safe:
```
A B C E F G H J+ (free)
2 [Xh Xh Xh] [Yh Yh Yh Yh]
3 [ x x x] [ y y y y]
4 [ x x x] [ y y y y]
5 [ x x x] <- Y grows/shrinks in E-H;
6 A-C is never touched
7 [ x x x] <- X grows down freely
LANE 1 (A-C) LANE 2 (E-H)
danger zone A-C danger zone E-H disjoint columns => independent forever
```
`SideBySideNotSupportedError` is raised only for **row overlap within a single
lane** (column-overlapping tables). Two tables in disjoint column bands sharing
rows is not an error β they are different lanes.
### 2.1 What counts as row overlap
The check in `_assert_stacked_only` operates on **row intervals within the
operating table's lane** only. For two managed tables with extents taken from
their bookmark unions via `_iter_managed_table_extents`:
- Table P spans rows `[Pr_min, Pr_max]`.
- Table Q spans rows `[Qr_min, Qr_max]`.
A table is part of the operating lane iff it shares at least one column with
the transitive cluster anchored at the operating table (Β§3.2). A table whose
columns are entirely disjoint is a **different lane** and is skipped.
Within a lane they **overlap** iff `not (Pr_max < Qr_min or Qr_min > Pr_max)`.
**Valid vertical stack** β rows disjoint, columns identical (same lane, fine):
A
B
C
2
β Table X rows 2β4 (Lane A-C)
3
S1
B1
10
4
S2
B1
20
(gap)
6
well
conc
od
β Table Y rows 6β8 (same lane)
7
A1
5
0.2
8
A2
5
0.3
X rows [2,4] β© Y rows [6,8] = β
β ACCEPTED
**Also valid β disjoint-column side-by-side (two lanes sharing rows):**
A
B
C
D
E
F
2
Y_h
Y_h
β Lane 1 (AβC) and Lane 2 (EβF) share row 2
3
x1
x1
x1
y1
y1
4
x2
x2
x2
y2
y2
Column-disjoint: different lanes. X rows [2,4] β© Y rows [2,4] = [2,4] but ACCEPTED β different lanes
**Also valid β side-by-side in truly disjoint columns (two lanes sharing rows):**
```
A B C E F G β col D is empty gap
[Left ] [Right ] Two separate lanes β paste into either succeeds
```
The key criterion is **column disjointness**: Left (A-C) and Right (E-G) share no
column, so they are independent lanes regardless of which rows they occupy.
**Edge case β wide bridging table merges two groups into one lane:**
A table whose column span *bridges* two otherwise-disjoint groups merges them
transitively into one lane. If Wide covers A-G, it overlaps both Left (A-C) and
Right (E-G) β none of A-C, E-G are disjoint from A-G β so all three are in the
same lane. Right's rows then overlap Left's rows **within that merged lane**, and
any paste into Right raises `SideBySideNotSupportedError`.
```
A B C E F G β before Wide is added: two independent lanes
[Left ] [Right ]
A B C D E F G β after Wide (A-G) straddles both:
[Left ] [Right ] Right is now part of Left's lane;
[ Wide (A-G) ] paste into Right β SideBySideNotSupportedError
```
Fix: move Right past Wide's right edge (e.g. cols I-K) so it is column-disjoint
from A-G. It then becomes its own independent lane again.
**Invalid β row overlap within the same lane:**
A
B
C
D
E
F
2
Y_h
Y_h
Y_h
β X (AβC) and Y (DβF) share a column cluster via C/D overlap β same lane, BOTH at rows 2β4 β
3
x1
x1
x1
y1
y1
y1
4
x2
x2
x2
y2
y2
y2
Column-overlapping tables, same lane, rows [2,4] = [2,4] β REJECTED β SideBySideNotSupportedError
### 2.2 Why row overlap within a lane is rejected
The engine resizes a table by **inserting or deleting whole worksheet rows**
across its lane's column band (Β§4). An Insert/Delete in that band moves every
cell in those columns. If a second table in the **same lane** (overlapping
columns) shared even one of the operating table's rows, the row-shift would tear
it β its left columns shifted, its right columns not, or vice versa.
Column overlap is the criterion because the row-shift only touches rows
**strictly below** the operating table's old bottom row (`_shift_band_below`,
Β§4.2). A stacked neighbor below shifts down or up **as a whole unit** β all its
columns move by the same delta β so it stays intact. Tables in a different lane
(disjoint columns) are in a different Insert/Delete band entirely and are never
touched.
### 2.3 The projection: when does the check fire?
`_assert_stacked_only` does not just compare *current* rows. It compares the
operating table's **post-operation** row range against every other **same-lane**
table's **projected** post-operation row range, because the shift the engine is
about to perform will move some lane-mates:
- It computes the **lane band** β the transitive column-overlap closure
anchored at the operating table's columns (see Β§3.2 / `_cluster_for_operating_table`).
- A neighbor that (a) overlaps the lane's columns **and** (b) currently sits
**below** `op_old_end` is projected to shift by `delta` rows:
`(R_min + delta, R_max + delta)`.
- A neighbor in a **different lane** (column-disjoint) is skipped entirely.
- The invariant fires iff **any** projected same-lane range intersects the
operating table's post-operation range `[op_top, op_bottom_post]`.
So the check is *forward-looking*: it rejects layouts that would overlap **after
the shift completes** within the lane, not merely ones that overlap now.
### 2.4 Exactly where it fires
| Call site | When | `op_top` / `op_bottom_post` | `delta` |
|---|---|---|---|
| `initialise_table_named_ranges` (manual init) | after computing the footprint, **before** writing bookmarks | header_row / footprint bottom | `0` |
| `initialise_table_benchling` β `_write_fresh` path | via the same init machinery for fresh tables | header / footprint | `0` |
| `paste_df_to_named_range` | **before** any destructive op | header_row / `header_row + n_new` | the computed shift amount |
| `create_plate_layout` | before the plate paste | plate extent | plate row delta |
In every case the check runs **before** anything destructive, so a rejection
leaves the sheet exactly as it was β no half-written bookmarks, no cleared
cells. At init the check runs *before* the bookmarks are even written, so a
rejected init leaves no stale names behind.
---
## 3. The danger zone & safe placement
### 3.1 What the danger zone is
A lane **owns the band directly below its stack, within its column range,
indefinitely** β because that's the space its data grows into. That band is the
**danger zone**. Loose content (a stray note, a summary formula, a label) placed
there will be shifted or destroyed when the table grows or shrinks. Floating
shapes (images, text boxes) anchored in the band are also detected and raise
before any shift occurs (see Β§3.4).
A
B
C
D
2
3
S1
B1
10
4
S2
B1
20end
βΌ danger zone β Lane AβC; col D is outside this lane, SAFE
5
βΌ
βΌ
βΌ
SAFE
6
owned by
the lane
below β
SAFE
7
βΌ
βΌ
βΌ
SAFE
Three regions are **always safe** (see [../safe-placement.md](../safe-placement.md)):
1. **Above the title row.** The shift only ever inserts/deletes *downward*.
2. **In columns outside the lane's band.** Content in a different lane (disjoint
column band) is never in any lane's shift band. A second managed table in a
disjoint column band sharing the same rows is a different lane β it is
accepted, not rejected (Β§2).
3. **Cells you protect with their own named range.** Both the danger-zone scan
and the widen-claim scan exempt any cell covered by a named range other than
the operating table's own bookmarks. Shapes cannot be exempted this way β a
shape anchored in the zone always raises.
### 3.2 The lane band β how wide is "the lane's columns"?
The danger zone covers the **full column extent of the operating table's lane**
(`_cluster_for_operating_table`, used by `_managed_band_for_sheet`). A managed
table joins the lane if its columns share β₯1 column with **any table already
in the lane** β a BFS closure, not a first-degree test:
```
operating table cols 1β3
T_A cols 2β5 β overlaps operating β in lane
T_B cols 4β8 β overlaps T_A (not operating) β in lane (transitive)
T_C cols 20β25 β disjoint from all β different lane, excluded
β lane band = cols 1β8. The Insert/Delete spans cols 1β8 so the whole
chain shifts as one unit; T_C is in a different lane and is never touched.
```
The danger-zone scan (`_check_danger_zone`) and the row-shift
(`_shift_band_below`) use **the same band**, so anything that *would* be shifted
is also *inspected* first. That's the safety guarantee.
### 3.3 Grow that pushes a neighbor down β SAFE
The neighbor below is itself a managed table (covered by its bookmark extent),
so the danger-zone scan treats it as "safe to shift as a unit" and the grow
proceeds. Before β operating table X (rows 2β4) with stacked neighbor Y (rows
6β8); paste a 4-row DataFrame into X:
BEFORE β X: n_old = 2
A
B
C
2
3
d1
d1
d1
4
d2
d2
d2end
(gap)
6
Y_h
Y_h
Y_h
7
b1
b1
b1
8
b2
b2
b2
β
AFTER β X: n_new = 4, delta = +2
A
B
C
2
3
D1
D1
D1
4
D2
D2
D2
5
D3
D3
D3
6
D4
D4
D4end
(gap β preserved)
8
Y_h
Y_h
Y_h
9
b1
b1
b1
10
b2
b2
b2
A
B
C
2
3
d1
d1
d1
4
d2
d2
d2end
βΌ danger zone β lane X (cols AβC); attempt: paste 4 rows
5
6
NOTE: QA
```text
_check_danger_zone scans rows 5..(old_end+100) across the lane band (AβC),
finds "NOTE: QA" at B6 β not covered by any managed table, not protected by a
named range β and raises BEFORE any cell is cleared or shifted.
```
> `TableSpaceOccupiedError` β *"Raised when a write would shift or destroy
> non-table content in the target band β either the danger zone below a managed
> table or the cells a fresh header would land on. Distinct from the
> width-mismatch case (DataFrame wider than the declared header), which raises
> plain `ValueError` because it is caller-side input validation, not a
> sheet-state conflict."*
**Fix options** (all in the message): move the note above the title row; move it
to a column outside the lane band; or give B6 its own named range to mark it
intentional (the scan then exempts it).
**Shapes are also detected.** `_check_danger_zone` enumerates `sheet.shapes`
and checks each shape's anchor cells (`TopLeftCell` / `BottomRightCell`) against
the affected region. A floating image or text box anchored inside the lane band
raises `TableSpaceOccupiedError` with the shape's name and a **move instruction**
computed as: "move it at least N rows down (away from the table), or above the
title row." Shapes cannot be exempted by a named range; any shape anchored in
the zone raises. After moving the shape and re-running, the scan re-checks and
proceeds. No persistent state is stored between attempts.
For button-driven macros: the caller catches the exception and passes
`str(exc)` to `display_message_and_exit` (`ui.py`). The engine itself never
calls `display_message_and_exit` β keeping the core testable and context-free.
### 3.5 The claim zone β widening
When a paste's DataFrame is **wider** than the current header, the engine
auto-widens the header into new columns to the right (Β§4.4). Those new columns
were never part of the table, so before touching them `_check_widen_claim_zone`
runs **two** scans β both raising `TableSpaceOccupiedError` on loose content or
shapes:
1. **New-column extension in the operating rows.** Cells in
`(op_top..scan_bottom, old_header_end+1 .. new_header_end)` would be
overwritten by the new header / data write.
A
B
C
D
2
(new)
β col D about to become header (df has 4 cols; header is AβC)
3
d1
d1
d1
LEFTOVER
β claim-zone scan finds this β refuses
4
d2
d2
d2
2. **Post-widen lane extension below the table.** If the new columns *bridge*
the operating table into a previously-disjoint stacked table (widening the
lane band), any loose content in those *newly-in-lane* columns inside the
danger zone would now be caught by the band-Insert. The pre-widen
`_check_danger_zone` couldn't have seen those columns, so this second scan
covers them.
Both scans check cells **and** floating shapes (`_shapes_in_region`). A shape
anchored in the claim zone raises with a **column move instruction** computed by
`_column_move_hint`: "move it at least N columns to the right (away from the
table)." Cells covered by a named range or another managed table are exempt;
shapes are never exempt.
Both scans exempt cells covered by a named range or another managed table.
---
## 4. The paste shift mechanism β clear β shift β write
`paste_df_to_named_range` resizes a table with a **three-step multi-pass shift**.
This is the precise mechanism, in execution order, exactly as implemented.
### 4.0 Pre-flight (before any destructive step)
In order, *all before anything is cleared or moved*:
1. **Sanitize the DataFrame** (`_sanitize_df_for_excel`): `Β±inf β NaN`; truncate
strings over Excel's 32,767-char cell limit (with one `UserWarning`); and β
because **`sanitize_formulas=True` by default** β apostrophe-escape text cells
starting with `=` `+` `-` `@` so external data can't inject a live formula.
Numbers and numeric-looking strings are left alone. The caller's DataFrame is
never mutated.
2. **Resolve the target** (`_resolve_paste_target`): header range, start column,
current header width, first data row.
3. **Column-order check** (`_check_df_columns_match_headers`): every existing
header position must match the DataFrame column at that position β see Β§6.5.
Raises `ColumnOrderMismatchError` if not.
4. **Read the old extent** (`_read_op_extent`): `old_start` / `old_end` from the
live bookmarks, with auto-heal (Β§5.1) when they're missing/corrupt/inverted.
5. **Compute the shift amount** (Β§4.3) and **assert the stacked-only invariant**
(Β§2) on the projected post-paste rows.
6. **Run the widen-claim scan** (Β§3.5) if the DataFrame is wider than the header.
Only after all of the above passes does the destructive sequence begin.
### 4.1 Step 1 β ClearContents
`_clear_old_data_rows` runs the danger-zone scan (Β§3.4) and then
`ClearContents` on the operating table's *own* data cells β
`(old_start, start_col)` through `(old_end, header_end_col)` β **in place, no row
shift**. On a first paste (`old_end < old_start`) this is a no-op.
### 4.2 Step 2 β Shift (Insert / Delete whole rows)
`_shift_band_below` opens or closes row slots **strictly below `old_end`**,
across the cluster band `[band_left, band_right]` (Β§3.2). Let
`delta = n_new - n_old_effective`:
- `delta > 0` (**grow**): `Range.Insert(Shift=xlShiftDown)` for `delta` rows at
`old_end + 1`. Everything in the band below `old_end` slides **down** by
`delta`.
- `delta < 0` (**shrink**): `Range.Delete(Shift=xlShiftUp)` of the bottom
`|delta|` rows of the old extent. Everything below slides **up** by `|delta|`.
- `delta == 0`: nothing.
Because the shift only ever touches rows **below `old_end`**, cells at or above
`old_end` β including the header itself and any loose content sharing the
operating rows but above `old_end` β are never moved by this step. Content in
a different lane (disjoint columns) is also untouched because the Insert/Delete
spans only the current lane's column band. (Row overlap within the same lane is
already rejected by Β§2 before this step runs.)
### 4.3 Step 2 (cont.) β how the gap to the neighbor below is preserved
The shift amount differs between first and subsequent pastes, and that
difference is exactly what preserves the user's chosen gap.
**Subsequent paste (`n_old > 0`)** β pure delta:
```
shift_amount = n_new - n_old # (excel_io.py)
```
The neighbor below is pushed down by `+delta` on grow, pulled up by `|delta|` on
shrink. Whatever gap existed between this table and the next stacked table is
mechanically preserved, because both the table's new bottom and the neighbor's
top move by the *same* delta.
**First paste (`n_old == 0`)** β gap-aware:
```
gap_below = _nearest_neighbor_gap_below(...) # empty rows below header to nearest neighbor
shift_amount = max(0, n_new - gap_below)
```
On the very first paste there are no data rows yet, but the *user* has already
laid out a gap between this table's header and the next table (`table_gap`, 2 by
default). The engine **consumes that gap first** and only pushes the neighbor by
the **deficit** (`n_new - gap`) when the data is taller than the gap. Data that
fits in the existing gap is written into it without displacing the neighbor at
all.
`_nearest_neighbor_gap_below` scans by **cell content** (not by bookmark),
because a header-only neighbor that's never been pasted into has only its anchor
named range β no `_table_start`/`_table_end` bookmarks yet β so it's invisible
to `_iter_managed_table_extents`. Scanning cell content catches the neighbor's
header cells the way the user sees them. (When no neighbor is found within the
scan window, it returns a large sentinel = "unlimited room below".)
**First-paste grid β data fits the gap (no neighbor displacement):**
BEFORE β X header only, gap = 2
A
B
2
(gap)
(gap)
5
Y_h
Y_h
β
AFTER β paste 2 rows; n_new = 2 β€ gap
A
B
2
3
D1
D1
β written into the gap
4
D2
D2
5
Y_h
Y_h
β UNMOVED (shift = max(0, 2β2) = 0)
BEFORE β gap = 2
A
B
2
(gap)
(gap)
5
Y_h
Y_h
β
AFTER β paste 3 rows; shift = max(0, 3β2) = 1
A
B
2
3
D1
D1
4
D2
D2
5
D3
D3
β consumed gap + 1 new row
6
Y_h
Y_h
β shifted down by 1 only
WIDEN β header AβC, df has 4 cols
A
B
C
D
2
NEW
β header extended
3
D1
D1
D1
D1
4
D2
D2
D2
D2end
_table_end β (4, D)
NARROW β header AβD, df has 3 cols
A
B
C
D
2
β header KEPT wide
3
D1
D1
D1end
β
β D cleared
4
D2
D2
D2
β
_table_end β (4, C) (data extent)
BROKEN β user deleted _table_end
A
B
2
β header anchor OK
3
???
???
_table_start present, _table_end #REF!
4
???
???
β drop both fragments, first-paste path
β
HEALED β next paste, n_old treated as 0
A
B
2
3
D1
D1
β rewritten from header+1
4
D2
D2
β both bookmarks rewritten fresh
A
B
C
D
1
Assay X (title)
2
β anchor assay_x $A$2:$C$2
3
S1
B1
10start
4
S2
B1
20end
assay_x_table_end = $C$4
(gap β 2 rows)
7
Assay Y (title)
8
well
conc
odanchor
β anchor assay_y $A$8:$C$8
9
A1
5
0.2start
10
A2
5
0.3end
assay_y_table_end = $C$10
manifests: assay_x__schema_columns = "sample,batch,result" Β· assay_y__schema_columns = "well,conc,od"
### 6.1 The upstream schema gains a column
In Benchling, `Assay X` adds a new result field **`qc`** at the **end** of its
schema. The schema is now `[sample, batch, result, qc]`.
### 6.2 The reinit call (runnable)
Reinit is automatic: `initialise_table_benchling` detects that `assay_x` already
exists on the sheet (`_find_table` finds the anchor name) and routes to
`_reinit` instead of `_write_fresh`. You call it **exactly the same way you did
the first time**:
```python
from mgtx_benchling_wrapper.context.benchling_context import BenchlingContext
from xlwings_package import initialise_table_benchling
# You build the context yourself β credentials are mgtx-benchling-wrapper's job.
ctx = BenchlingContext(
client_id=...,
client_secret=..., # plaintext β resolve from your store
base_url="https://yourorg.benchling.com",
token_url="https://yourorg.benchling.com/api/v2/token",
)
# Same two schemas, same sheet, same column. assay_x's schema now has `qc`.
results = initialise_table_benchling(
wb,
{
"Results": ["assaysch_assayx", "assaysch_assayy"],
},
ctx=ctx,
column="A", # autopaste; both stack in column A
table_gap=2, # the gap that's preserved across reinits/pastes
)
# Each result dict carries action + a diff when reinitialised:
for r in results:
print(r["display_name"], r["action"], r.get("diff"))
# Assay X reinitialised {'added': ['qc'], 'updated': [], 'removed': [], ...}
# Assay Y reinitialised {'added': [], ...} # unchanged
```
### 6.3 What `_reinit` does, step by step
`_reinit` is the in-place updater. For `assay_x` gaining `qc`:
1. **Locate the table** β `_find_table` returns `(header_row=2, start_col=1,
end_col=3)`.
2. **Re-sync display names + title** β column headers and the title cell are
rewritten from the schema on every call (Benchling is the source of truth for
text).
3. **Diff against the manifest** β `cur_map_schema_only` is `cur_map` filtered to
the manifest `{sample, batch, result}`, so any manual range a dev added in the
band is excluded (M.2.1). `qc` is in the new schema but not in `cur_map` β it's
a **new column**.
4. **Append the new column.** New columns are appended at the right edge of the
current band (`end_col + 1`, col D). `_check_band_empty` confirms D2 is free
first (raises `TableSpaceOccupiedError` if not). The header cell gets the
display name + bold + fill, and a fresh sheet-scoped range `qc` binds to `$D$2`.
**No `Insert columns` is emitted** β the reorder/repack pass (step 5) places
every column in schema order via a clear-and-rewrite, so appending then
repacking yields the same final layout without a propagating column shift.
5. **Reorder pass** β the active band is snapshotted, cleared, and rewritten in
schema order. Named ranges are rebound in place. Because this operates only on
the lane's own columns (clear-and-rewrite, no Insert/Delete), no other lane is
affected.
6. **Extend the table extent** β the schema anchor grows to `$A$2:$D$2`, the
title merge re-merges across AβD, and `assay_x_table_end` extends to col D.
7. **Rewrite the manifest** β `assay_x__schema_columns = "sample,batch,result,qc"`.
### 6.4 BEFORE / AFTER β the widen, with the neighbor protected
BEFORE β assay_x = [sample, batch, result]
A
B
C
D
2
β anchor $A$2:$C$2
3
S1
B1
10
4
S2
B1
20end
assay_x_table_end $C$4
(gap β 2 rows)
7
Assay Y (title)
8
well
conc
od
9
A1
5
0.2
10
A2
5
0.3
manifest: assay_x__schema_columns = "sample,batch,result"
β
AFTER β assay_x = [sample, batch, result, qc]
A
B
C
D
2
qcanchor
β anchor NOW $A$2:$D$2, qc β $D$2
3
S1
B1
10
(empty)
β existing data INTACT
4
S2
B1
20
(empty)end
assay_x_table_end NOW $D$4
(gap β 2-row gap PRESERVED)
7
Assay Y (title)
β Y UNMOVED β still rows 7β10
8
well
conc
od
9
A1
5
0.2
10
A2
5
0.3
manifest now: assay_x__schema_columns = "sample,batch,result,qc"
sheet
df
sample
result
batch
qc
β positions 1 & 2 swapped (batch/result) β ColumnOrderMismatchError
```text
Fix A: reorder the DataFrame to [sample, batch, result, qc] before pasting.
Fix B: if Benchling itself reordered, re-run initialise_table_benchling first
(the reorder pass rebinds the sheet to the new order), THEN paste.
```
Only **existing** header positions are checked; columns past the current header
are handled by the auto-widen path (and pre-scanned by the claim zone, Β§3.5). A
freshly-anchored, empty-header position has no identity to match against and is
accepted (this is what lets a first paste into a brand-new table go through).
### 6.6 The mirror case β Benchling DROPS a column
When a column is removed from the Benchling schema, `_reinit` **purges it
outright**: clears every cell in the column from the header through `_table_end`,
deletes its named range, **closes the horizontal gap** so the remaining schema
columns are contiguous (the repack pass), and **shrinks the table extent** β
schema anchor width, title merge, and `_table_end` β to the new rightmost column.
The stacked neighbor below is untouched: the purge operates on **columns**, not
rows, so no vertical shift reaches `assay_y`.
BEFORE β schema [sample, batch, result]; Benchling drops batch
A
B
C
D
2
batch
β batch dropped upstream
3
S1
B1
10
4
S2
B1
20end
assay_x_table_end $C$4
β
AFTER β batch purged; result closes up into B, table shrinks to AβB
A
B
C
D
2
result
(empty)
β anchor NOW $A$2:$B$2
3
S1
10
(empty)
4
S2
20end
(empty)
assay_x_table_end NOW $B$4