Chapter 56. Project State, Ledgers, and the Event System#

56.1 Stable identity, fact events, and state machines#

A chat log is not a database.

Project truth has to live in structured ledgers. Chat can explain a decision; it cannot be the only source for a character's wardrobe, a shot's state, or a release version.

Stable IDs.

Projects, characters, wardrobe, locations, props, audio, episodes, beats, shots, generations, edits, QC, ads and metrics all use stable IDs. Moving files or changing versions never changes identity.

Fact, decision, event.

A fact records the currently valid value. A decision records why it was chosen. An event records how the value changed. Current state is derived by replaying approved events, which is what makes it auditable and reversible.

event:
  id: EVT_00421
  type: asset_version_promoted
  entity: CH_LINYUN_FACE
  from: v02
  to: v03
  reason: profile structure corrected
  approved_by: ART_DIRECTOR_01
  affects: [38_keyframes, 21_motion_clips]

The dependency graph.

A shot depends on an episode beat, characters, wardrobe, location and props. A generation depends on the shot and its keyframes. An edit depends on generations and audio. A release depends on the edit, subtitles, rights and QC.

Figure 56-1 After identity is promoted from v02 to v03, the event is appended to the log and the current state updates. The dependency graph finds the affected keyframes, motion, edits and release candidates and invalidates them. Once repair tasks complete, a new snapshot is produced while historical versions remain.

The key sequence is: record the event, propagate invalidation, then schedule repair. The system must not overwrite a character file first and rely on the team remembering which shots used the old version. A new snapshot represents the new current state without rewriting the production facts of an older RC as though they never happened.

When one asset changes, query direct and downstream impact along the graph rather than searching the project by hand.

State machines.

Each artifact type has legal transitions. A keyframe moves from needed to candidate, review, approved, locked; it cannot go from needed straight to exported. Illegal transitions are refused and recorded.

56.2 Concurrency, task triggers, rollback, and diagnosis#

Optimistic concurrency and conflict.

When two agents modify the same episode pack simultaneously, use version checks. The later submitter must re-read the difference; silent overwriting is not permitted. Human resolutions enter the decision log.

Event-driven tasks.

episode_pack_approved triggers asset resolution and shot design tasks. asset_changed triggers impact analysis. picture_locked triggers final subtitles, mixing and export. P1_opened blocks a gate.

Events schedule tasks; they never bypass approval.

Snapshots and rollback.

Save a project snapshot at important gates. A rollback creates a new event pointing at an older version rather than deleting history. A published version must always be rebuildable.

SOP.

First, define entities and stable IDs. Second, assign an owner per ledger. Third, write state transitions. Fourth, build dependency edges. Fifth, record modifications as events. Sixth, handle concurrent conflict. Seventh, snapshot at gates. Eighth, test impact analysis and rollback.

Fault tree.

Symptom: departments hold different truths. State is scattered across files. Establish an authoritative ledger with versions.

Symptom: shots are missed after an asset change. There is no dependency graph. Reference everything by stable ID.

Symptom: rollback loses later work. Files were overwritten instead of versioned events. Keep immutable history.

56.3 Entity relationships, event sourcing, and a conflict case#

Checklist, exercises and deliverables.

Check that all entities have IDs; that facts, decisions and events are separated; that state transitions are legal; that dependencies are complete; that concurrency prevents overwriting; and that released versions can be rebuilt.

Exercise one: draw the dependency graph for E001_S09. Exercise two: simulate impact analysis for a wardrobe update. Exercise three: roll back from picture lock to the previous version.

Deliverables for this chapter: the entity model, the event log, the dependency graph, state machines, snapshots, and the rollback report.

Entity relationships in the running case.

MD_BOOK_001 contains E001. E001 contains B01–B06. B04 is realized by E001_S08–S12. S09 references Lin Yun's identity, the grey suit, the boardroom, the authorization, the authorization graphic, a lighting state and an audio cue. Its motion result is referenced by the edit timeline and by ad creatives.

So changing a signature date on the authorization is not swapping one image. It affects the graphic asset, the S09 keyframe, the motion composite, the episode, the ads, the date in subtitles or dialogue, and every exported RC. The dependency graph produces that list.

An event-sourcing example.

- id: EVT_101
  type: fact_changed
  entity: GRAPHIC_AUTHORIZATION
  field: signature_date
  from: 2026-07-02
  to: 2026-07-03
  cause: SCRIPT_FIX_018
- id: EVT_102
  type: dependencies_invalidated
  entities: [KF_E001_S09, GEN_E001_S09_004, EDIT_E001_V12]
- id: EVT_103
  type: regeneration_approved
  scope: graphic_and_composite_only

The system did not delete the old date; it recorded when the old fact ceased to be valid. Past released versions can still be rebuilt as they stood.

Materialized views.

An event log suits auditing, and replaying from the beginning each time can be slow. The system periodically produces snapshots: current asset versions, current character state, currently open issues and task status. A snapshot is a rebuildable view of the log, not a second independent truth.

Write order is: validate the event, append to the log, then update the view. A failed view update can be recovered from the log. Never edit a JSON file first and add the log entry when there is time.

A concurrency conflict.

A writer changes the father's account amount in v09 while a designer, working from v08, produces a ledger graphic with the old figure. On submission, the designer's parent version is stale and the task enters conflict. The interface shows the field difference and the designer regenerates. Last-writer-wins is not permitted.

Non-conflicting fields can merge automatically — a writer editing dialogue while the audio director adds a pronunciation — and any merge still produces a new version with a list of parent versions.

56.4 Retention on deletion, invariants, auditing, and migration#

Deletion is also an event.

Deleting a shot must not simply erase it. Record shot_deprecated, cancel tasks that have not started, retain historical references to material already generated, and check whether music, subtitles and numbering need re-sequencing. Published material may still reference the old shot; new versions must not retrieve it automatically.

Retention tiers.

Keep approved facts, rights, events, masters and key generation parameters permanently. Keep all candidates and intermediate files for the life of the project. Bulk rejected material can be cleaned under policy while retaining thumbnails, hashes and failure tags. No cleanup may break the rebuildability of a released version.

State invariants.

Beyond schema, define cross-entity invariants: an approved shot may reference only approved or locked assets; one character has exactly one valid base costume at a given time; a release candidate's file hashes must match its QC evidence; can_advance=false while P0/P1 are open; expired rights automatically invalidate the related RC.

Check invariants before an event commits. If an authorization asset is retired, the system permits historical versions to remain while blocking new RCs from using it, and creates a withdrawal or re-licensing task.

Audit queries.

The system should at minimum answer: who promoted a character from v02 to v03 and when; which files a wrong amount entered; which model and music licence E001 shipped with; how much rework one client change added; and why a particular P2 was waived. If it cannot answer, the log is an accumulation rather than production memory.

Schema migration.

A structural upgrade must not rewrite old projects in place. The migration script preserves original values, emits migration events, and verifies that released versions can still be rebuilt; fields that cannot be mapped enter a human queue. Snapshot before migrating, and afterwards compare entity counts, referential integrity and key hashes. During the transition, old and new agents must declare the schema versions they support.

The migration report is itself a permanent audit record.

The three-layer truth model.

The system manages canonical truth, production truth and release truth simultaneously. Canonical truth is the currently approved characters, story, assets and rights. Production truth is the input versions and results one task actually used. Release truth is the files a given RC genuinely contained at a given time. One "current version" field cannot merge all three.

Lin Yun's identity having moved from v02 to v03 does not mean an old RC never used v02. Changing the canonical amount does not rewrite the history of a withdrawn test build that displayed the old one. Auditing must be able to reconstruct all three layers at any point in time.

56.5 Business events, storage architecture, and the boundary of determinism#

Invalidation is not deletion.

When something upstream changes, downstream artifacts enter stale or invalidated rather than being deleted. stale means an input changed and the result may still pass re-review — a slight costume texture update, for instance. invalidated means a key fact, identity or right changed and the result may not advance.

An invalidation event carries the reason, the changed fields, the propagation path and a recommended action. The scheduler pauses affected tasks; a published RC enters risk assessment; a human decides between re-verification, recomputation, waiver or withdrawal. Automatically regenerating every dependency is expensive and can destroy an already-approved performance.

Events should express business semantics.

"A file was modified" is not a useful event. The system needs character_identity_promoted, episode_pack_approved, rights_expired, picture_lock_revoked and similar, because different events carry different propagation and permissions. A successful upload to object storage is a technical event and cannot automatically equal asset approval.

An event carries at minimum the actor, time, entity, before and after versions, reason, evidence, permission context and an idempotency key. When the same request arrives twice, the key prevents two approval events being written.

A minimum workable storage architecture.

A small team does not need to build a complex platform first, and should still separate four stores: a relational or document database for entities and state; an append-only event log for changes; object storage for images, audio, video and project files; and a search index for text and similarity retrieval. The database holds object URIs and hashes; large media never lives inside a chat history.

All layers share stable IDs. Backup strategy protects facts, rights, approval events and RCs first; regenerable rejected candidates can be cleaned under retention policy. Once a month, pick a published version at random and rehearse rebuilding it, to verify that traceability is not a claim on paper.

Idempotency, ordering, and duplicate events.

External retries, network timeouts and message queues can deliver the same event several times. Each business action carries an idempotency key and checks before writing; a duplicate asset_approved must not trigger budget, notifications and downstream tasks again. Event consumers store their processing position and resume from the last acknowledged point after a crash.

Cross-entity events can arrive out of order. If motion_generated arrives before keyframe_approved, the system must not pretend the prior gate passed — it holds, refuses, or marks the event as orphaned. Dependency conditions are validated by the state machine; a message timestamp cannot substitute for business order.

Replay and the boundary of determinism.

Replaying events from a snapshot should reconstruct identical structured state without re-invoking stochastic generation models. The event records which candidate was approved and its content hash — it does not ask the replay to generate a similar image again. Determinism belongs to state recovery; media results live in object storage.

Replay tests pick random projects and points in time and compare entity counts, key fields, dependency edges, RC manifests and hashes. When differences appear, look first at non-deterministic migrations, implicit side effects and missing events. Any field that depends on the current database and cannot be explained from history is an audit gap.

Handling the conflict between deletion, privacy, and audit.

When a rights holder or a data subject requests deletion, the system needs a controlled process balancing legal obligation, contract and audit. Sensitive originals or biometric material can be deleted or isolated, while the event log retains an irreversible anonymized identifier, the deletion time, the basis and the affected artifacts — demonstrating that deletion was performed without continuing to expose the content.

Deletion propagates to caches, search indexes, training sets, backup restore policy and third-party vendors. Deleting only the primary database while an old backup restores the content again is not completion. A real project should take professional legal advice on the specific retention and deletion boundaries; this book supplies only the engineering control framework.

A note on sources#

Production memory is what separates a system from a folder of files. Stable identity, business events and explicit invalidation are what let a team answer, months later, what was true, what shipped, and why.