Reshape persist family: lnk_persist_{init, write} instead of split across pipeline + standalone #177

Context

The link R package (NewGraphEnvironment/link, v0.38.0) has two exported functions that share the word "persist":

• lnk_persist_init(conn, cfg, species, force_recreate) — creates the province-wide target tables (<persist_schema>.streams, streams_habitat_<sp> per species, barriers) if absent. DDL only.
• lnk_pipeline_persist(conn, aoi, cfg, species, schema) — INSERTs per-WSG segment data from the working schema into the persistent tables created by lnk_persist_init. The data-write step.

They share the noun "persist" but live in different families:

Result: autocomplete on lnk_persist_ shows only lnk_persist_init. The corresponding write function is hidden under lnk_pipeline_* where it's lumped with 12 phase functions.

Problem

1. Family discoverability. A user looking for "the persist write function" auto-completes lnk_persist_ and sees only init. They have to know that pipeline_persist is also a thing — and that it's actually the entry point they want for the write step (not init, which is DDL-only).
2. Naming inconsistency. lnk_pipeline_persist reads as "the persist phase of pipeline" — but it's actually the only lnk_pipeline_* function that writes to the persistent schema (every other phase writes to the working schema). Its name conflates "phase of pipeline" with "writes to persist." That semantic conflation pre-dates the v0.37.0 Decouple bcfp compare from link pipeline run — separate compare-only step #168 decouple, where lnk_pipeline_run formalized the pipeline-as-modelling-umbrella concept.

Goals

• Reshape the persist family so all "persist" functions group under lnk_persist_*:
  • lnk_persist_init — stays (DDL setup).
  • lnk_pipeline_persist → lnk_persist_write (the data-write step).
• lnk_persist_* becomes a coherent two-function family. Autocomplete shows both.
• lnk_pipeline_* family becomes purely phase functions that operate on the working schema (which is what the comment headers already claim).

Optional follow-up scope (a separate issue if appetite is low):

• lnk_persist_init(force_recreate = TRUE) is rare; consider a separate lnk_persist_drop(conn, cfg, schema) for the "wipe before re-init" path. State_clean.sh's --schemas mode (added in v0.38.0) covers this at the operator level for whole-schema wipes.

Acceptance

• Rename R/lnk_pipeline_persist.R → R/lnk_persist_write.R via git mv.
• Rename the exported function inside; devtools::document() re-emits NAMESPACE.
• Back-compat shim: lnk_pipeline_persist <- function(...) { .Deprecated("lnk_persist_write"); lnk_persist_write(...) }. One release of notice; drop in v1.0.
• Update all internal callers:
  • R/lnk_pipeline_run.R — the modelling umbrella (the only in-package caller).
  • Any data-raw script that sources lnk_pipeline_persist directly (audit via grep).
• Tests:
  • Rename tests/testthat/test-lnk_pipeline_persist.R → test-lnk_persist_write.R (if exists; otherwise the function is exercised via test-lnk_pipeline_run.R's mock composition).
  • Add a deprecation-shim test: calling lnk_pipeline_persist() triggers .Deprecated() and proxies through.
• Roxygen @seealso cross-refs updated.
• CLAUDE.md "Exported Functions" section: move lnk_persist_write next to lnk_persist_init under a "Persist family" heading.
• NEWS entry calls out the rename + deprecation.
• devtools::check() clean.
• /code-check clean per phase commit.

References

• Family-shape discussion in NEWS for v0.37.0 (NewGraphEnvironment/link NEWS.md — "persist family naming pass" is filed as an out-of-scope follow-up there).
• Current implementations:
  • R/lnk_persist_init.R (DDL)
  • R/lnk_pipeline_persist.R (data write — to be renamed)
• Both share the source-of-truth cols_streams / cols_habitat / cols_barriers named vectors at the top of R/lnk_persist_init.R.
• v0.37.0's R/lnk_pipeline_run.R:131-145 shows the only in-package caller (the modelling umbrella).

Out of scope

• The lnk_compare_wsg → lnk_compare_run rename (separate issue, lands independently).
• lnk_persist_drop helper (optional follow-up).
• Renaming the underlying persistent table DDL (no DB-side changes — table names stay).