alkblobs/tasks/store-pg-lo-construction.md

---
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** — the supported non-default configurations
  are `cargo check/test --no-default-features --features "pg-lo,mem"`
  (the one-window-host topology's build; the mem-pglo constructor
  constructible) and `cargo check --no-default-features --features
  "postgres,pg-lo"` (ADR-013 §4's pg-pure consolidation build); verify
  both compile clean. **The literal kv-less config
  (`--no-default-features --features pg-lo`) is not a gate and cannot
  compile the whole crate** — do not burn time on it: with no kv
  feature enabled, `KvEngine`/`KvCursor` go empty (E0004) and the
  facade's by-reference dispatch matches are non-exhaustive
  (references are always considered inhabited, so an empty enum behind
  `&` still requires arms). This is structural, not a bug: per ADR-011
  §4 every constructor mode pairs a kv engine, so a build with zero kv
  engines is not a supported configuration (ADR-013 §4's supported
  non-default configurations all include one). The shared pieces
  themselves (pg_common, the engines) compile in the literal config —
  only store.rs errors. The finding is the wave-5 engine task's
  (d69d9a3, recorded in its Notes); this task's verification uses the
  two meaningful builds above.

## 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,mem"` and `--features "postgres,pg-lo"`) compile clean
      (the literal kv-less config is not a gate — see the Description
      bullet)
- [ ] `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