`symfonic.capabilities.memory.positional_migration`¶

positional_migration ¶

Plan, apply, roll back and clean up a CORE-171 positional row migration.

Explicit and adopter-invoked: no read path calls this, and nothing here dual-reads a positional key as native. plan mutates no row. apply re-plans inside the backend's write/forget serialization and refuses unless the result matches the reviewed plan's digest, then re-keys every owner copy of every row it re-read -- never the caller's rows -- in that same transaction: all or none. A plan whose rows do not hash to its digest refuses before any read, so an edited plan authorizes nothing. A row whose target a recorded native forget already erased is quarantined, never migrated. A backend that cannot prove which owners a forget erased refuses any plan that would move a row: PostgreSQL keeps no record of a forget that ran before memory_erase_generations existed, so there only quarantine-only plans run. rollback restores quarantined rows only, each to the v0 owner its quarantine key records, and refuses a plan that moved any row to a native owner (ROLLBACK_UNPROVABLE): no store or audit record proves a row there is the one apply moved rather than one written since. It refuses a row no plan could have quarantined (NOT_RESTORABLE), a restore the store cannot prove came after no forget of its origin (every PostgreSQL and Mongo rollback; on the in-process store, any forget or delete in the tenant since apply), and refuses while any of them holds a staged (unflushed) write. delete_quarantined_rows is the only way a quarantined row leaves the store, because no scoped read or forget in either version matches its key. Apply, rollback and deletion each record their rows through an audit logger before any row changes, or refuse (:mod:symfonic.capabilities.memory.positional_audit).

A migrated row leaves every positional route -- v0 HTTP, explicit v0 composition and the legacy engine's reads -- in exchange for its complete native owner; no supported step undoes that. A restored quarantined row is served by every positional route again and leaves list_quarantined_rows. Which stores are admitted, and how each serializes, is :mod:symfonic.capabilities.memory.positional_store.

PlannedRow `dataclass` ¶

PlannedRow(kind: str, row_id: str, source: str | bool | int | float | None, target: str | None, disposition: RowDisposition, reason: str)

One row's audited move; owner keys only, never memory content.

PositionalMigrationPlan `dataclass` ¶

PositionalMigrationPlan(tenant_id: str, rows: tuple[PlannedRow, ...], digest: str)

A reviewable migration of one tenant, bound to the rows it read.

counts ¶

counts() -> dict[str, int]

Rows per disposition, for an operator's review.

Source code in src/symfonic/capabilities/memory/positional_plan.py

def counts(self) -> dict[str, int]:
    """Rows per disposition, for an operator's review."""
    return dict(Counter(row.disposition.value for row in self.rows))

moved ¶

moved() -> tuple[PlannedRow, ...]

The rows apply re-keys and rollback restores.

Source code in src/symfonic/capabilities/memory/positional_plan.py

def moved(self) -> tuple[PlannedRow, ...]:
    """The rows apply re-keys and rollback restores."""
    return tuple(row for row in self.rows if row.disposition is not RowDisposition.UNTOUCHED)

apply_positional_migration `async` ¶

apply_positional_migration(store: Any, plan: PositionalMigrationPlan, declaration: PositionalOwnerDeclaration, *, audit: Any = None, actor: str | None = None, delete_quarantined_edges: tuple[str, ...] = ()) -> PositionalMigrationPlan

Re-key exactly the reviewed plan, atomically, or refuse.

Every moved row -- migrated or quarantined -- is recorded with its prior owner and reason before the re-key; see positional_audit. delete_quarantined_edges names edges this plan quarantines that the operator approves deleting in the same transaction, after the re-key: an edge not yet quarantined is outside delete_quarantined_rows, and on Mongo apply refuses while one would touch a node a native forget erases.