Keep old network operation names and allow connection-specific overrides #375

Overview

The old Network<Stage>Operation names stay available as deprecated, network-only classes, and the default settings use the new Peer* operations. This work is part of milestone M4.

Background & Motivation

Hosts such as Kolibri list operations by name in their settings, and some hosts make subclasses of them. After #374, the shared logic has new names. The old names must keep their current behavior, so that host code does not change behavior without a decision.

A clear order for the operations in each stage also lets a host change the behavior for one connection type only.

Design: spec. Plan: implementation plan, Task 14.

User Story

As a Kolibri developer,
I want the old operation names to keep working with a clear warning,
So that I can move to the new names on my own schedule.

Description & Expected Outcomes

Each old name stays as a subclass of the matching Peer* operation. These subclasses handle network connections only. Each one gives a DeprecationWarning when it is created, and its docstring names the replacement.

The default settings list the operations of each stage in this order:

1. Local operations.
2. Operations for one connection type, which includes the LegacyNetwork* operations.
3. The shared Peer* operation, as the last fallback.

An operation for one connection type can handle a stage, or it can decline with MorangoSkipOperation. If it declines, the shared operation handles the stage.

Deliverables & Contracts

The change delivers these capabilities:

• Eight deprecated classes: Network{Initialize,Serialize,Queue,PushTransfer,PullTransfer,Dequeue,Deserialize,Cleanup}Operation.
• Each deprecated class handles NetworkSessionContext and does not handle DiskSessionContext.
• The default settings give no deprecation warnings.

Acceptance Criteria

• Creating each Network<Stage>Operation gives a DeprecationWarning.
• Each deprecated class handles a NetworkSessionContext and returns False for a DiskSessionContext.
• Middleware built from the default settings gives no DeprecationWarning.
• A test operation for disk only, listed before PeerInitializeOperation, handles a disk context and does not handle a network context.
• If that test operation raises MorangoSkipOperation, PeerInitializeOperation handles the stage.
• The characterization suite passes without edits on SQLite and with tox -e postgres.

Technical Pointers & Architecture

• Target Components / Context: morango/sync/operations.py, morango/constants/settings.py:8-47.
• Related Patterns: The middleware stops at the first operation that handles a stage (SessionMiddlewareOperations.__call__ in morango/registry.py).
• Data Model & Schema Considerations: None.
• Resilience & Failure Modes: If a host lists only the old names, a disk sync fails with the registry error "no applicable middleware". The failure is loud, not silent.

Notes & Tradeoffs

• Dependencies: Blocked by: Sync stage operations work with any peer connection #374 (shared peer operations). Blocks: Store archive metadata in a morango table #376, Prove that an exported archive matches a network server #386.
• Testing Requirements: This is a refactor task. The characterization suite from Tests that pin today's async network push and pull behavior #363 and Tests that pin today's legacy network sync behavior #364 must pass without edits.
• Tradeoffs & Alternatives Considered: Plain aliases to the Peer* classes are simpler. But host subclasses of an alias then start to run for disk without a decision. The spec rejects this.
• Compatibility & Migrations: Kolibri must list the Peer* operations in its settings before it can use disk export. The release that removes the old names is an open question in the spec.

Metadata

• Complexity: Medium
• Target Branch: release-v0.9.x

AI Usage

Drafted with Claude (Claude Code) from the approved design spec and implementation plan. The author reviewed the requirements, and the code references were checked against the release-v0.9.x codebase.