docs(tasks): decompose wave 5 — the pg-lo large engine, the window host's large-tier arm, the LO-medium SKIP-posture column
- engine-pg-lo: the Backend impl behind feature pg-lo (default-off) — companion-table authority, one-tx staged put at the 512 KiB knee, descriptorless lo_get windows, the orphan-recovery sweep, the posture deltas recorded; the shared-helper/PgOpts/LO-isolation design points named (LOs are database-level — the C7 lesson cited so it is not rediscovered) - engine-pg-lo-window: the EngineWindowState impl per ADR-012 §5's pg-lo row — gc_window only, no fleet family anywhere - store-pg-lo-construction: LargeEngine::PgLo slotting (the large sub-enum design point), the consolidation + mem-pglo constructors (the fleet-valid set completed, implicitly non-fleet), and the one-window-host rule's store-core completion (dormancy + the large-host sweep arm) - suite-column-pg-lo: the second SKIP-posture column, two factories spanning feature pairs, the dormancy row, zero LO residue in teardown - review-wave-5: the engine-wave gate; amendment A2 (janitor adoption) verified here Harness server cited in every server-touching task: dockerized pglo-poc (postgres:16-alpine) on :15432, db blobs, postgres/poc (verified live 2026-10-12); env-driven ALKBLOBS_PG_* settings, clean server-less skips, acceptance requires green against the server. Verification: cargo test 69/19/3 ok, clippy --all-targets -D warnings green, fmt --check green (docs-only change).
This commit is contained in:
glm-5.3-flash committed
1 parent
f3e8a88e2e
commit
5a217f7bc7
6 files changed
+785
-2
No files matched your search
@@ -0,0 +1,166 @@
|
||||
---
|
||||
id: store-pg-lo-construction
|
||||
name: pg-lo constructor wiring — the consolidation shape and the window-host completion
|
||||
status: pending
|
||||
depends_on: [engine-pg-lo, engine-pg-lo-window]
|
||||
scope: moderate
|
||||
risk: medium
|
||||
impact: component
|
||||
level: implementation
|
||||
tags: [wave-5, store, pg-lo, construction]
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Slot pg-lo into the facade's engine representation — the slotting-in
|
||||
pattern `src/store.rs`'s module doc pinned ("adding an enum variant and
|
||||
a named constructor is slotting in"). This task also completes the
|
||||
one-window-host rule's store-core wiring, which is more than slotting:
|
||||
the durable window gains its large-engine host arm.
|
||||
|
||||
- **`LargeEngine::PgLo`** variant behind `#[cfg(feature = "pg-lo")]` +
|
||||
the six large-op dispatch arms (`put_staged`/`get`/`has`/`size`/
|
||||
`delete`/`list`).
|
||||
- **The large cursor bodies slot in** — `AnyCursor::Large` and
|
||||
`AnyStaging::Large` are currently **concrete over the local
|
||||
bodies** (`LocalCursor`/`LocalStaging`). **Named design point (the
|
||||
recorded `KvCursor` sub-enum pattern's large-tier twin)**: grow a
|
||||
`LargeCursor`/`LargeStaging` sub-enum behind `AnyCursor`/`AnyStaging`'s
|
||||
one large arm (local + pg-lo variants) rather than one `AnyCursor`
|
||||
variant per large engine — the same bounded-memory argument as the
|
||||
kv side, recorded for the review gate, with the store.rs design-point
|
||||
notes updated to the landed state.
|
||||
- **Named constructors**, feature-gated on `pg-lo` (default-off):
|
||||
- **`dual_tier_postgres_pglo`** — kv = postgres + large = pg-lo: the
|
||||
**consolidation posture** (ADR-009's "one engine to operate"); its
|
||||
landing **completes the fleet-valid engine set** (the store.rs
|
||||
module doc's recorded forward reference — pg-lo's wave-5
|
||||
constructor is the last fleet-valid engine). **Implicitly
|
||||
`fleet: false`** (ADR-012 §3): the ADR-005 in-process protocol
|
||||
applies verbatim; the `fleet: true` declaration is wave 6 (the
|
||||
composite fleet-validity predicate + constructor declarations)
|
||||
slotting in without reshaping — no fleet parameter carried;
|
||||
recorded in the constructor doc. **Connection-settings design
|
||||
point**: two DSN + opts parameter pairs (kv and large) —
|
||||
cross-instance kv=postgres + large=pg-lo is valid non-fleet
|
||||
(ADR-012 §4), and the consolidation shape passes the same
|
||||
DSN/opts to both; the suite factory's schema-sharing corollary
|
||||
(one minted schema passed to both engines vs two schemas) is
|
||||
recorded with it.
|
||||
- **`dual_tier_mem_pglo`** — kv = mem + large = pg-lo (features
|
||||
`mem` + `pg-lo`): **the one-window-host rule's named test
|
||||
topology** (ADR-012 §5: the durable window hosts on the large
|
||||
engine when the kv engine is not SQL-backed). Non-fleet (mem is
|
||||
never fleet-valid).
|
||||
- **No `kv_only(pg-lo)`** — pg-lo is a large engine; kv-only modes
|
||||
take kv engines only. **No sqlite+pg-lo constructor this wave** —
|
||||
valid non-fleet per ADR-012 §5 but not named by the plan; added on
|
||||
demand (recorded).
|
||||
- Both take the **delete-window delay** parameter (the
|
||||
`DEFAULT_DELETE_WINDOW_DELAY` signature shape; `0` the legal
|
||||
degenerate tuning) — the durable form's cadence knob on either
|
||||
host.
|
||||
- **The one-window-host rule's store-core completion** (the substance
|
||||
of this task):
|
||||
- **`ensure_gc_schema` at construction** — the call currently
|
||||
dispatches on the kv-engine enum only. It must follow the host
|
||||
rule: kv SQL-backed (sqlite/postgres) → the kv host's call (pg-lo's
|
||||
window clauses dormant — the consolidation shape's pg-lo schema
|
||||
carries **no `gc_window`**); kv = mem + large = pg-lo → the
|
||||
**pg-lo host's call** (`gc_window` in the pg-lo schema). The
|
||||
dispatch consults the large engine only when the kv engine is not
|
||||
SQL-backed; it keys off the engine representation, never a flag.
|
||||
- **The sweep form branch** — currently `KvEngine::Mem` runs the
|
||||
inline form unconditionally. It gains the large-host arm: mem kv +
|
||||
`LargeEngine::PgLo` runs the **durable form on the pg-lo host**
|
||||
(`sweep_window_durable` is already generic over
|
||||
`W: EngineWindowState` — the pg-lo arm slots in); mem kv +
|
||||
`LargeEngine::Local` (or no large tier) stays inline. The
|
||||
sqlite/postgres arms are untouched (their hosts win the window per
|
||||
the rule). The module doc's recorded "pg-lo dormancy slots in
|
||||
without reshaping" note is updated to the landed state (dormancy
|
||||
did; the large-host arm is the reshaping the rule always named).
|
||||
- **Stale scope notes / forward references updated** — the store.rs
|
||||
module doc's wave-5 mentions (the engine-representation note, the
|
||||
fleet-valid-set note, the one-window-host paragraph, the
|
||||
`LargeEngine` doc's "pg-lo slots in at wave 5"), the `PUT_CHUNK` doc
|
||||
note ("pg-lo's measured 512 KiB `lowrite` knee is that engine wave's
|
||||
concern" — now landed; the engine's constant is the authority), and
|
||||
any `#![allow(dead_code)]` scope notes whose scope changes (the
|
||||
batch-delete helper's wave-6 note stays).
|
||||
- **Constructor unit tests**: the modes construct and introspect
|
||||
correctly (`mode()`/`threshold()`); `ensure_gc_schema` ran on the
|
||||
**right host** in both shapes (consolidation: `gc_pins` + `gc_window`
|
||||
on the kv schema, **no `gc_window` on the pg-lo schema** — the
|
||||
dormancy assertion; mem-pglo: `gc_window` on the pg-lo schema); the
|
||||
window-delay default is the pinned constant, tunable, `0` legal; the
|
||||
dual-tier shapes round-trip end-to-end (a smoke put/get through both
|
||||
tiers with LO placement asserted — the companion row + LO present,
|
||||
kv entries not in pg); a mem-pglo durable-form sweep smoke
|
||||
(zero-delay: first sweep stages into the pg-lo schema's `gc_window`
|
||||
and executes nothing, second sweep executes the overdue set
|
||||
re-arbitrated at execution time — the form-branch-is-large-host
|
||||
proof). Env-driven (`ALKBLOBS_PG_*`), skipping cleanly server-less
|
||||
(the engine tests' convention); the janitor discipline rides from
|
||||
the start (amendment A2).
|
||||
- **The pg-lo-pure builds** — `cargo check --no-default-features
|
||||
--features pg-lo` (engine + window family compile, constructors
|
||||
cfg'd out where `mem` is absent) and
|
||||
`cargo test --no-default-features --features "pg-lo,mem"` (the
|
||||
mem-pglo constructor constructible): ADR-013 §4's supported
|
||||
non-default configurations; verify both compile clean.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `LargeEngine::PgLo` slots in; all six large ops dispatch; the
|
||||
large cursor/staging bodies slot through the recorded sub-enum
|
||||
design point (the store.rs notes updated to the landed state)
|
||||
- [ ] `dual_tier_postgres_pglo` + `dual_tier_mem_pglo` constructors
|
||||
exist behind feature `pg-lo`, take connection settings + opts +
|
||||
threshold + window delay, fallible where I/O is fallible; the
|
||||
consolidation constructor's doc records the implicitly-non-fleet
|
||||
posture and the fleet-valid-set completion
|
||||
- [ ] `ensure_gc_schema` follows the one-window-host rule at
|
||||
construction (kv host on dual-SQL — pg-lo schema carries no
|
||||
`gc_window`; pg-lo host on kv=mem — contract-tested both shapes)
|
||||
- [ ] The sweep form branch runs the durable form on the pg-lo host
|
||||
for kv=mem + large=pg-lo and the inline form otherwise; the
|
||||
branch keys off the engine representation, never a flag
|
||||
- [ ] The connection-settings design point (two DSN+opts pairs; the
|
||||
consolidation corollary) decided and recorded
|
||||
- [ ] The pg-lo-pure builds (`--no-default-features --features pg-lo`
|
||||
and `--features "pg-lo,mem"`) compile clean
|
||||
- [ ] `cargo test` (default) green; `cargo test --features pg-lo` and
|
||||
`--features "pg-lo,mem"` green server-less (skipping);
|
||||
`cargo clippy --all-targets -- -D warnings` and `cargo fmt
|
||||
--check` green (default + the pg-lo feature variants)
|
||||
|
||||
## References
|
||||
|
||||
- src/store.rs (the engine-representation design point; the
|
||||
constructor modes; the slotting-in pattern; the `KvCursor` sub-enum
|
||||
design point; the sweep form branch; the one-window-host paragraph)
|
||||
- docs/architecture/decisions/011-vocabulary-tiers-engines-and-fleet-state.md
|
||||
§4 (the constructor table; the consolidation posture's mode reading)
|
||||
- docs/architecture/decisions/012-pre-decomposition-consistency-rulings.md
|
||||
§3 (fleet activation is a declaration — wave 6), §4 (the GC-state
|
||||
host; cross-instance valid non-fleet), §5 (the one-window-host rule
|
||||
and the pg-lo dormancy), §6.3 (dual-tier shapes)
|
||||
- docs/architecture/decisions/008-trait-size-probe-fleet-gc-and-large-engines.md
|
||||
§2 (the window delay, default 5 min)
|
||||
- docs/architecture/decisions/009-pg-lo-large-tier-engine.md (the
|
||||
consolidation posture this constructor ships)
|
||||
- docs/architecture/decisions/013-family-composition-reactive-boundary-and-feature-graph.md
|
||||
§4 (the feature graph; the pg-lo-pure builds)
|
||||
- tasks/engine-pg-lo.md, tasks/engine-pg-lo-window.md (the engine +
|
||||
seam bodies this wires)
|
||||
- tasks/store-postgres-construction.md (the structural twin's recorded
|
||||
design points)
|
||||
|
||||
## Notes
|
||||
|
||||
> To be filled by implementation agent
|
||||
|
||||
## Summary
|
||||
|
||||
> To be filled on completion
|
||||
Reference in new issue
Block a user