Skip to content

world-local: make the event log the single source of truth for hook creation #2339

@TooTallNate

Description

@TooTallNate

Follow-up from #2295 (comment) (raised by @pranaygp).

The hook_created branch in packages/world-local/src/storage/events-storage.ts now coordinates four non-atomic durable writes (token claim, recovery marker, event, hook entity). Each review round on #2295 surfaced a new crash window between two of them — entity-without-event, then claim-without-event, then event-without-entity — and each was patched with another recovery sub-branch.

The suggested refactor inverts the invariant: make the hook_created event in the event log the only source of truth, and treat the token claim, recovery marker, and hook entity as rebuildable caches. Any reader that misses the entity (or claim) rebuilds it from the persisted hook_created event. With that shape:

  • most of the dedup-recovery branching in the hook_created path collapses
  • new crash windows can no longer mint new bug classes, because partial cache state is always reconstructible from the log
  • the legacy-claim recovery-marker sidecar likely becomes unnecessary

Scope notes:

  • the same inversion may apply to other entity-creation paths (step_created, wait_created) that use claim/lock sidecar files
  • behavior must remain compatible with data directories written by current/older versions (the legacy-claim formats handled in fix(world-local,world-postgres): make duplicate hook_created idempotent #2295)
  • the existing regression tests in the concurrent entity-creation races describe block of packages/world-local/src/storage.test.ts should all keep passing and serve as the safety net for the refactor

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions