ledgerwerk

Migration APIs

Migration orchestration is semi-public and intentionally stricter than ordinary file operations. Plans, fingerprints, journals, activation ordering, and cleanup are part of the safety contract.

.. py:module:: memoryledger.migrations

Memoryledger migration handlers registry.

Provides a common protocol for migration handlers and a registry that maps migration names to their implementations.

.. py:class:: MigrationHandler(*args, **kwargs)

module:

memoryledger.migrations

Bases: :py:class:~typing.Protocol

Protocol for Memoryledger migration handlers.

.. py:method:: MigrationHandler.status(root)

module:

memoryledger.migrations

Return migration status for this handler.

type root:
sphinx_autodoc_typehints_type:

\:py\:class\:\~pathlib.Path``

param root:
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~collections.abc.Mapping\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`object\`\]`

.. py:method:: MigrationHandler.plan(root, *, output=None) :module: memoryledger.migrations

Generate a read-only migration plan.

:type root: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~pathlib.Path\``
:param root:
:type output: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~pathlib.Path\` \| \:py\:obj\:\`None\``
:param output:

:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~collections.abc.Mapping\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`object\`\]`

.. py:method:: MigrationHandler.apply(root, *, plan_file=None, dry_run=False) :module: memoryledger.migrations

Apply a migration plan.

:type root: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~pathlib.Path\``
:param root:
:type plan_file: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~pathlib.Path\` \| \:py\:obj\:\`None\``
:param plan_file:
:type dry_run: :sphinx_autodoc_typehints_type:`\:py\:class\:\`bool\``
:param dry_run:

:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~collections.abc.Mapping\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`object\`\]`

.. py:method:: MigrationHandler.recover(root, *, journal, policy=’auto’) :module: memoryledger.migrations

Recover from a migration journal.

:type root: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~pathlib.Path\``
:param root:
:type journal: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~pathlib.Path\``
:param journal:
:type policy: :sphinx_autodoc_typehints_type:`\:py\:class\:\`str\``
:param policy:

:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~collections.abc.Mapping\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`object\`\]`

.. py:method:: MigrationHandler.cleanup(root, *, dry_run=False, confirm=False) :module: memoryledger.migrations

Clean up legacy paths after successful migration.

:type root: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~pathlib.Path\``
:param root:
:type dry_run: :sphinx_autodoc_typehints_type:`\:py\:class\:\`bool\``
:param dry_run:
:type confirm: :sphinx_autodoc_typehints_type:`\:py\:class\:\`bool\``
:param confirm:

:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~collections.abc.Mapping\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`object\`\]`

.. py:class:: MigrationRegistry()

module:

memoryledger.migrations

Bases: :py:class:object

Registry of migration handlers.

.. py:method:: MigrationRegistry.register(handler)

module:

memoryledger.migrations

Register a migration handler.

type handler:
sphinx_autodoc_typehints_type:

\:py\:class\:\~memoryledger.migrations.MigrationHandler``

param handler:
:rtype: :sphinx_autodoc_typehints_type:`\:py\:obj\:\`None\``

.. py:method:: MigrationRegistry.get(name) :module: memoryledger.migrations

Get a migration handler by name.

:type name: :sphinx_autodoc_typehints_type:`\:py\:class\:\`str\``
:param name:

:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~memoryledger.migrations.MigrationHandler\``

.. py:method:: MigrationRegistry.list() :module: memoryledger.migrations

List all registered migrations.

:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`list\`\\ \\\[\:py\:class\:\`\~collections.abc.Mapping\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`object\`\]\]`

.. py:method:: MigrationRegistry.status(root) :module: memoryledger.migrations

Get status for all migrations.

:type root: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~pathlib.Path\``
:param root:

:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`list\`\\ \\\[\:py\:class\:\`\~collections.abc.Mapping\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`object\`\]\]`

.. py:module:: memoryledger.migrations.plan_io

Deterministic plan serialization for Memoryledger migrations.

Provides strict plan file reading/writing with schema validation.

.. py:exception:: PlanSerializationError(message, details=None)

module:

memoryledger.migrations.plan_io

Bases: :py:class:Exception

Raised when plan serialization/deserialization fails.

type message:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

param message:
type details:

:sphinx_autodoc_typehints_type:\:py\:class\:\dict`\ \[:py:class:`str`, :py:data:`~typing.Any`] | :py:obj:`None``

param details:

.. py:function:: serialize_plan(migration, migration_id, project_uuid, project_root, source, target, domain, ledgercore_plan=None, warnings=None)

module:

memoryledger.migrations.plan_io

Serialize a migration plan to deterministic JSON.

type migration:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

param migration:

Migration name (e.g., “storage-layout”)

type migration_id:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

param migration_id:

Unique migration identifier

type project_uuid:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

param project_uuid:

Project UUID

type project_root:
sphinx_autodoc_typehints_type:

\:py\:class\:\~pathlib.Path``

param project_root:

Absolute project root path

type source:
sphinx_autodoc_typehints_type:

\:py\:class\:\~collections.abc.Mapping`\ \[:py:class:`str`, :py:data:`~typing.Any`]`

param source:

Source state description

type target:
sphinx_autodoc_typehints_type:

\:py\:class\:\~collections.abc.Mapping`\ \[:py:class:`str`, :py:data:`~typing.Any`]`

param target:

Target state description

type domain:
sphinx_autodoc_typehints_type:

\:py\:class\:\~collections.abc.Mapping`\ \[:py:class:`str`, :py:data:`~typing.Any`]`

param domain:

Domain-specific plan data

type ledgercore_plan:
sphinx_autodoc_typehints_type:

\:py\:class\:\~collections.abc.Mapping`\ \[:py:class:`str`, :py:data:`~typing.Any`] | :py:obj:`None``

param ledgercore_plan:

Optional Ledgercore plan data

type warnings:
sphinx_autodoc_typehints_type:

\:py\:class\:\list`\ \[:py:class:`str`] | :py:obj:`None``

param warnings:

Optional list of warnings

rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

returns:

Deterministic JSON string

.. py:function:: deserialize_plan(text, *, expected_migration=None)

module:

memoryledger.migrations.plan_io

Deserialize and validate a migration plan.

type text:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

param text:

JSON string

type expected_migration:
sphinx_autodoc_typehints_type:

\:py\:class\:\str` | :py:obj:`None``

param expected_migration:

If set, validate migration name matches

rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\dict`\ \[:py:class:`str`, :py:data:`~typing.Any`]`

returns:

Validated plan dictionary

raises PlanSerializationError:

If validation fails

.. py:function:: write_plan_file(plan_text, output)

module:

memoryledger.migrations.plan_io

Write a plan file deterministically.

type plan_text:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

param plan_text:

Serialized plan JSON

type output:
sphinx_autodoc_typehints_type:

\:py\:class\:\~pathlib.Path``

param output:

Output path

rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\~pathlib.Path``

returns:

Path to written file

.. py:function:: read_plan_file(path, *, expected_migration=None)

module:

memoryledger.migrations.plan_io

Read and validate a plan file.

type path:
sphinx_autodoc_typehints_type:

\:py\:class\:\~pathlib.Path``

param path:

Path to plan file

type expected_migration:
sphinx_autodoc_typehints_type:

\:py\:class\:\str` | :py:obj:`None``

param expected_migration:

If set, validate migration name matches

rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\dict`\ \[:py:class:`str`, :py:data:`~typing.Any`]`

returns:

Validated plan dictionary

.. py:module:: memoryledger.migrations.registry

Migration registry setup.

Register all migration handlers with the global registry.

.. py:function:: register_all_migrations()

module:

memoryledger.migrations.registry

Register all migration handlers.

rtype:
sphinx_autodoc_typehints_type:

\:py\:obj\:\None``

Use the CLI migration workflow for normal operations; exceptions identify conflict, incomplete, or invalid-plan conditions.