Abstract record pause and resume — 1.2 contract#

This pause contract remains unchanged in 1.3. Current writes use archive 4, adding durable command history; archive 3 remains a supported older input. Commands do not make Pawn providers eligible for pause.

Pause(entity, expectedRevision) removes an eligible abstract record from the due queue. Resume(entity, expectedRevision) returns it to that queue. Both return true when changing the saved flag and increment revision once; repeating the same state with the current revision returns false. A stale revision is always rejected. Calls run on the game thread outside provider/native callbacks and do not invoke an abstract step.

Time policy: resume catches up#

Pausing suspends scheduled work, not the passage of logical time. Payload, schema/model, RNG, interval, logical tick and next deadline remain unchanged. Resume preserves those values too. Future ordinary game ticks process overdue fixed intervals through the normal quota and ordering; the resume call itself does no simulation. No missed time is dropped or rewritten, and a partial interval keeps its original boundary.

For example, pause at game tick 3,000 with logical tick 2,500 and next deadline 5,000. Resume at tick 12,000. The next scheduled work covers 2,500→5,000, 5,000→7,500 and 7,500→10,000, subject to the quota; the next deadline is then 12,500. Providers keep their existing absolute-time assumptions. A freeze-and-rebase policy is outside this API.

State and eligibility#

EntitySnapshot.IsPaused is the durable scheduling flag. The appended EntityStatus.Paused means a compatible, validated paused record. Missing/incompatible-provider and quarantine diagnostics take precedence over that display status while the flag remains saved. Restoring a provider or successfully retrying a paused quarantine does not resume scheduling. Retry revalidates; only Resume clears the pause flag.

Pause requires a compatible Ready or already Paused record. Resume requires a compatible Paused or already Ready record. The public facade rejects Pawn simulation providers, records with any native member/operation history, native transition locks and invalid native journals. These guards apply even when a request would otherwise be a no-op. Foreign native ownership and pending/failed/prepared transitions remain governed by native recovery. No history is removed and no entity IDs or request keys are reused.

Archive 3 adds the required Boolean scheduling flag. Archives 1 and 2 load with scheduling unpaused. Malformed flags or a paused native transition lock reject the archive and preserve its original bytes. The native journal stays at 3. Older framework versions preserve an unknown archive format as blocked; downgrading into older versions is not a supported way to resume work.

Integration and compatibility review#

This is an additive v1 API extension: append Paused = 6, expose IsPaused, and add the two facade methods. All existing metadata signatures and enum values are preserved, as are CLR identity 0.1.0.0 and provider API major 1. The previous 306-line baseline is retained and checked as a subset; the new exact baseline must contain only those reviewed additions.

Survey Relay is the first integration. It exposes pause/resume for an unfinished survey, explains catch-up, and automatically pauses completed records. Starting another survey preserves completed history. Existing compatible completed survey records are retired from scheduling once after load; their payload/RNG/time remain unchanged. The starter remains compatible with published 1.0/1.1 DLLs and demonstrates the base clock contract.

Validation covers idempotency/stale revisions, partial intervals, quota/order/catch-up, save/load, provider absence/incompatibility, quarantine/retry, overflow, thread/reentrancy, old formats and strict malformed-data preservation. Native checks cover facade eligibility and pending/faulted/prepared/retained Pawn cases, ordinary Survey UI/save flow, old consumer binaries and real archived upgrades. Pausing removes scheduled callbacks; it does not establish a whole-game performance gain.