Files
aevolution/docs/engineering/M12_EXACT_BIOLOGICAL_TRANSFER.md
dingo d3a867a662
Foundation / checks (ecs) (push) Successful in 2m20s
Foundation / checks (deploy) (push) Successful in 4m7s
Foundation / checks (network) (push) Successful in 21m2s
Foundation / checks (client) (push) Successful in 22m21s
Foundation / checks (tsan) (push) Successful in 28m57s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (postgres) (push) Canceled after 38m8s
Foundation / checks (checks) (push) Canceled after 38m19s
feat(persistence): admit durable maturing wildlife migrations
2026-10-19 11:57:00 -04:00

241 lines
15 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# M12.4c exact biological transfer candidates
ADR-0144 resolves the closed-owner/accounting conflict before implementing
biological ownership transfer. The portable lifecycle layer now prepares a
detached source/destination pair at an exact compatible cut. This segment adds
owner format 7 and population envelope 2, without a live migration flag, database
schema, durable manifest bundle, dependency or deployment.
The pair transfers actual zero-account wildlife, including every member of the
selected genome group. Opening stocks remain immutable; explicit cumulative
incoming/outgoing flows explain each owner's current stock. Bodies, reserves,
age, growth/damage, ancestry, identity, coordinates and cohort tags are exact.
Departures retain nonresident archive facts instead of recording death. Complete
genome ancestry and organism revisions merge without erasing destination history,
rewinding revisions or resurrecting dead organisms. Archive known-alive counts
include nonresidents and must never be used as an owned census/extinction proof.
The primitive refuses incompatible cuts/worlds/frames/geometry, vulnerable
controlled cells, identity conflicts, missing groups, placement conflicts,
capacity exhaustion, archive conflicts and counter overflow. Both detached
candidates must validate before success; failures leave the two originals exact.
Local offspring use the destination's identity namespace, with sorted insertion
even below imported IDs. Existing regional twin randomness retains its meaning;
the migration cut does not promise identical future environments or outcomes.
The tests use real funded founders and real budding, not fabricated wildlife or
the non-biological probe. They exercise repeated no-tick return trips, exact
per-member equality and per-channel combined closure, canonical restore, imported
death/decay, lower-namespace local reproduction among imported residents,
whole-group capacity refusal, body
conflicts, malformed/truncated ledgers, overflowing cumulative counters and cohort
tag/policy/sequence preservation. Lineage tests include revision conflicts and a
maximum-depth 4,096-genome ancestry using an iterative traversal.
The first reproduction fixture exposed an existing rules-8 limitation: a bud is
created below full realization, growth is retained, and `fund_bud` requires full
realization. Additional food does not mature that bud under the current kernel.
This transfer segment does not invent growth or alter reproduction rules. Its
ordering regression uses a real fully grown local founder reproducing alongside
imported higher-namespace residents. Self-sustaining wildlife generations still
need an explicit versioned maturation contract and ecological qualification.
ADR-0157 subsequently supplies opt-in portable rules-9 maturation with a funded
multi-generation family proof. These transfer contracts and durable bundle 10
originally remained rules 8. ADR-0160 subsequently qualifies portable owner-7
transfers between equal rules-9 cuts with distinct trace 2. It preserves every
realized growth/body/reserve field without a tick and rejects mixed rules.
Real juveniles grow before and after transfer with finite declared destination
food; raw/cohort biology and recorded continuation agree. Rules-8 trace 1 retains
its bytes and meaning. Durable bundle-11/trace-2 admission, pending freeze/staging,
atomic paired publication and complete recovery remain a separate gate.
ADR-0161/schema 54 subsequently admits bundle 11/trace 2 through that existing
durable workflow and complete registered pending-handoff verification. It preserves
the bundle-10/trace-1 path, exact biological state, ordered fences and atomic paired
receipt. Mixed bundles and cross-rule replay fail. It does not select automatic
movement, linked environmental budgets, sustainable ecology or deployment.
This is not the durable escrow gate. No prepared candidate may become an active
destination owner before a future fenced transaction commits both heads and
immutable transfer evidence. The source remains the sole owner until that commit;
a staged ghost owns nothing. Durable preparation/freeze, two-owner fencing,
ambiguous outcomes, abort/restart, partition/duplicate delivery, process kills and
stock-in-transit audits remain required. Existing profile-4/5 publishers do not
admit this new owner tuple, and retained trace 1 explicitly refuses envelope 2.
Numeric coordinates are region/frame-local and current movement is clamped,
without wrap. No atlas, route, edge crossing, cross-region contact or linked
habitat field is inferred. Those need separately versioned contracts and fidelity
tests. M12.4 as a whole remains open, as do dependent M12.5–M12.9 gates.
Executed qualification is recorded in [VALIDATION](VALIDATION.md).
## M12.4d recorded paired replay
[Migration trace 1](../../schemas/cellular-migration-trace-v1.md) retains a bounded
canonical request/cut/member/flow record for both individual and cohort owners.
The portable replay API takes the separately trusted request and both predecessor
states, verifies all bindings and derives the exact pair again. A new process
restores both representations and reproduces all four source/destination output
snapshots byte-for-byte. Corruption, malformed bounds, semantic member/material
tampering, wrong predecessor/result IDs and representation confusion are refused.
This record provides reproducible evidence for the future paired publisher. It
has no freeze, fence, durable retry outcome or activation rights. Independently
establishing manifest/payload SHA-256 bindings and journal authority remains an
I/O obligation; neither a checksum nor a UUID grants ownership. The durable
escrow and linked-geometry limits above remain unchanged.
## M12.4e portable population continuation
Population batch 2 records ordinary biological intervals and whole-group no-tick
conversions for envelope 2/owner 7. Batch 1 retains its old meaning and bytes;
cross-version replay and mismatched magic/version are refused. Continued biology
retains boundary flows/nonresident history while conserving actual current stock.
The restart fixture now also records and independently replays a 64-tick interval
after cohort transfer, comparing the complete continued destination snapshot.
This closes the portable continuation format boundary needed by a future durable
adapter. It does not add a durable bundle or SQL admission: both the current C++
prepared validator and SQL checker continue to admit only population batch 1.
## M12.4f portable checkpoint upgrade boundary
[ADR-0145](../adr/0145-boundary-accounting-checkpoint-upgrade.md) declares bundle
10 for owner 7 and supplies an explicit bundle-9 no-tick upgrade candidate for
both existing profiles. The manifest advances its commit sequence and retains
the exact source digest while preserving profile, history and biological tick.
Complete payload restoration/upgrade retains biology, opening stock and cohort
policy/membership/sequence. There is no bundle-10 genesis or repeated upgrade.
Ordinary continuation and profile changes preserve the tuple; new/old payload
confusion is refused in both directions. Portable reader support does not imply
database admission: schema 45 and the population prepared validator still reject
the tuple. Dedicated upgrade publication/evidence/recovery is the next segment;
paired escrow, geometry and remaining biological gates stay open.
## M12.4g durable accounting upgrade admission
[ADR-0146](../adr/0146-durable-boundary-accounting-upgrade.md)/schema 46 extends
the existing immutable version-upgrade journal to an explicit same-profile
bundle-9 to 10 publication. Both profiles retain complete source/result manifests,
payload digests and exact version tuples under the current lease and head fence.
An unsettled population interval blocks a new upgrade. The adapter restores the
verified source, derives the exact candidate, uploads/reads back its object and
retains the same prepared bytes after ambiguity. No worker upgrades automatically.
Recovery selects the recorded no-tick operation: a version upgrade is rederived
from its full retained source; a representation change uses its separate journal.
Both require full byte equality. Matching aggregate inventory cannot admit a
different cohort policy or membership. Bundle 10 requires envelope/batch 2;
bundle 9 retains envelope/batch 1. Raw biological trace 3 and rules 8 are unchanged.
Representation changes preserve either tuple and interval/player-operation
guards remain in place.
This admits the accounting format and its ordinary continuation. Paired migration
trace 1 still has no SQL publisher, source freeze, staged ghost or activation
rights. Durable two-head escrow, abort/partition/duplicate settlement, linked
geometry and ecology remain open. No deployment, live upgrade or golden changed.
## M12.4h durable source preparation and abort
ADR-0147/schema 47 retains canonical paired preparation under the source's current
lease and exact head. A verified destination predecessor capsule in the source
namespace supports complete recovery replay. The source keeps all stock at its
unchanged head; the destination is neither staged nor activated. New source
checkpoints/profile changes and interval/player reservations are refused while
pending. A replacement owner recovers the same freeze, without a timeout-based
release. Explicit current-source abort appends its immutable outcome and removes
the pending pointer with both biological heads unchanged. Retrying an aborted
preparation never reopens it.
The owning host withholds readiness and advancement while frozen or uncertain,
retains exact requests, renews authority and polls paused work once per second.
A fixed migration-freeze gauge identifies known pauses. Missing/corrupt capsules
and canonically encoded false member/material declarations fail complete replay.
See [the contract](../../schemas/ecology/cellular-migration-freeze-v1.md).
Destination staging, atomic paired head publication, commit/abort races and
activation remain the next segment; no route or automatic migration is enabled.
## M12.4i durable read-only destination staging
ADR-0148/schema 48 freezes the destination at its exact captured head under
current destination authority and ordered endpoint locks. The adapter restores
both cuts, replays the retained trace, copies the source capsule into the
destination namespace and uploads/reads back the derived destination ghost.
Its exact digest/length is immutable retry evidence, not an ownership receipt.
Recovery uses those local objects and compares the complete rederived ghost.
Neither biological head moves, and the source still owns all outgoing stock.
Both local migration roles are exclusive and block new publication, profile
changes, intervals and player reservations. Unknown staging retains exact bytes;
the owning destination pauses readiness/advancement through worker replacement.
Source abort serializes with staging and releases both pointers atomically.
Aborted-stage retries return their old outcome and never reopen a pause.
Missing/corrupt evidence and real but semantically false objects fail closed.
See [the staging contract](../../schemas/ecology/cellular-migration-stage-v1.md).
Atomic paired publication/common receipt, commit/abort races, recovery/activation
and linked ecology remain subsequent work. The ghost cannot run biology or
contribute owned census/extinction stock. No biological format, rule, route,
automatic movement, live region or deployment changes.
## M12.4j atomic paired ownership publication
ADR-0149/schema 49 publishes both same-profile bundle-10 no-tick candidates and
their immutable common receipt in one transaction under both current fences,
captured heads and the staged destination binding. Both complete objects are
uploaded/read back first. Deferred receipt references permit evidence guards
without disabling triggers. Second-insert failure rolls back both heads, receipt
and pointer settlement. Generic publishers cannot admit a half.
Before commit the source owns outgoing stock; afterwards only the destination
owns it. Abort and commit have one exclusive outcome. Exact retries retain both
original manifests under newer current leases. Unknown replies retain the exact
prepared pair, without inferring rollback or rebasing.
Recovery verifies both predecessor/result manifests, trace and staged ghost,
replays both candidates from local capsules, checks both result digests and
compares complete local biology. Missing or false evidence fails closed. A paused
host verifies a changed head before readiness, including after replacement;
pointer absence never authorizes stale source stock or an orphan ghost. Both
representations and return transfers use real player-origin wildlife. Existing
durable biological continuation runs afterwards.
See [the paired commit contract](../../schemas/ecology/cellular-migration-commit-v1.md).
Independent network partitions, linked geometry/environment, maturation, world
census/cuts, actual elapsed-day ecology and target-host capacity remain open.
No automatic route, biological rule/format, golden or deployment changes.
## M12.4k independent TLS transport fault qualification
A test-owned opaque relay and separate disposable loopback TLS cluster exercise
the unchanged production adapter. Both representations lose real requests and
receipts; independent observation distinguishes unchanged heads from an exact
committed pair. Lost preparation/staging/abort replies retain durable work and
host pauses. Either owner's path can remain isolated through actual lease expiry
while its peer retains the same epoch/freeze. Replacement recovers the same work;
stale publication fails, explicit abort releases both pauses and healing does not
revive the old fence. Wrong-hostname TLS is refused. ASan/UBSan and TSan exercise
the matrix; the full/sanitizer CI paths include it in a separate cluster.
See [fixture and qualification limits](M12_MIGRATION_TRANSPORT_FAULTS.md). This is
application-boundary byte loss over real local TCP/TLS, not multi-host/kernel
networking, database/object-store loss or orchestration. Linked ecology and later
M12 gates remain open. No SQL, production code, biological rule/format or deployment
changes; the added relays and credential tools belong to tests/CI only.
## M12.4l local storage fault qualification
The private migration matrix now fails source/destination capsule and result
directory syncs before publication and denies actual reads after paired commit.
Current-result I/O failures pause verified recovery for retry under the same
epochs. Unavailable counterpart replay evidence quarantines; restoring access
leaves that quarantine sticky. Explicit lease retirement and replacement recover
the exact original pair under newer authority. Independent database observations
prove unchanged predecessor heads before publication and unchanged committed heads
after it; exact retries never transfer stock twice. Both representations and
outbound/return directions run these cases without changing immutable bytes.
See [the storage scope](M12_MIGRATION_STORAGE_FAULTS.md). Physical media, remote
storage-host and orchestrator failures remain separate evidence.