Skip to content

feat(durable): scaffold zeph-durable crate, core newtypes, journal schema#4965

Merged
bug-ops merged 1 commit into
mainfrom
feat/m28/4944-durable-scaffold-newtypes-schema
Jun 6, 2026
Merged

feat(durable): scaffold zeph-durable crate, core newtypes, journal schema#4965
bug-ops merged 1 commit into
mainfrom
feat/m28/4944-durable-scaffold-newtypes-schema

Conversation

@bug-ops

@bug-ops bug-ops commented Jun 6, 2026

Copy link
Copy Markdown
Owner

Summary

Scaffolds the new Layer-0 zeph-durable crate (spec-064) — the foundation of the native durable
execution layer. This first slice (C1) is type-level only: it establishes the crate skeleton,
core newtypes, the journal data model, the effect contract, pure-data config, the error type, and
the persistence schema. No execution behavior exists yet — the journal writer, backends, replay
cursor, and the durable step primitive land in follow-up issues of epic #4707.

What's included

New crate crates/zeph-durable/:

  • ids.rsExecutionId / PromiseId / TimerId (UUIDv7), StepId, JournalSeq,
    IdempotencyKey, and the ExecutionKind discriminator. Private fields, smart constructors,
    serde-round-trip stable. IdempotencyKey::derive uses BLAKE3 derive_key with a domain-separation
    context string and length-delimited (injective) input.
  • journal.rs — the Journal trait (native async via RPITIT + Send, matching the
    LlmProvider/ToolExecutor convention), JournalEntry, the closed EntryKind enum, and
    ExecutionStatus.
  • effect.rsEffectClass (the bare contract needed by EntryKind; OnAmbiguous /
    EffectIntentSubClass and the construction-time policy land in C4).
  • config.rs — pure-data DurableConfig + RetentionPolicy with container-level #[serde(default)]
    mirroring [durable] TOML, and a type-safe DurableBackend enum.
  • error.rsDurableError (#[non_exhaustive], metadata-only messages, INV-5).
  • sealed.rs, lib.rs, README.md.

Schema (zeph-db): durable_executions / durable_journal / durable_promises /
durable_timers added as numbered migrations 097100 in both
zeph-db/migrations/sqlite/ and .../postgres/ (matching file counts, schema-equivalent:
BLOB→BYTEA, AUTOINCREMENT→BIGSERIAL, epoch columns INTEGER→BIGINT), including the
UNIQUE partial index idx_durable_journal_result. zeph-durable owns no .sql and no
sqlx::migrate!.

Acceptance criteria

  • INV-1 — no dependency on zeph-llm/zeph-memory/zeph-core/zeph-sanitizer or any
    business-layer crate (cargo tree -p zeph-durable → only zeph-db + zeph-common).
  • INV-14 — four durable_* files in both dialect dirs (matching counts); no .sql / no
    sqlx::migrate! inside zeph-durable.
  • IdempotencyKey::derive is domain-separated and injective; a boundary-shift test asserts
    distinct keys.
  • Newtype smart constructors expose no public field; tests cover ExecutionId::new uniqueness
    and serde round-trip of every newtype.
  • DurableConfig / RetentionPolicy serde defaults match the spec; an empty TOML table
    deserializes to every default.
  • EntryKind is a closed enum (exhaustive match compiles); control entries carry no payload.
  • cargo check/clippy -D warnings/cargo doc pass; every pub item is documented.

Verification

Check Result
cargo +nightly fmt --check clean
cargo clippy --workspace --all-targets -- -D warnings pass
RUSTFLAGS=-D warnings cargo check --workspace --all-targets --features desktop,ide,server,chat,pdf,scheduler pass
cargo nextest run --workspace --features full --lib --bins 11046 passed, 0 failed (21 new)
cargo test --doc --workspace --features desktop,ide,server,chat,pdf,scheduler pass (12 new)
RUSTDOCFLAGS="--deny rustdoc::broken_intra_doc_links" cargo doc --no-deps -p zeph-durable clean
SQLite migrations applied to fresh DB + full set via run_migrations pass (4 tables, 5 indexes)

Out of scope (later issues)

PayloadCipher (C2/#4945); JournalWriter/backends/Journal impl (C3/#4946); DurableStep /
DurableContext and the ambiguity policy (C4/#4947); CLI / root-config wiring / TUI (C6/#4949).

Part of #4707.

Closes #4944.

…hema

Add the Layer-0 zeph-durable crate (spec-064) as the foundation for the
native durable execution layer. This first slice is type-level only, with
no runtime behavior.

- ids: ExecutionId/PromiseId/TimerId (UUIDv7), StepId, JournalSeq, and
  IdempotencyKey (BLAKE3 derive_key, domain-separated, length-delimited
  injective input), plus the ExecutionKind discriminator. Private fields,
  smart constructors, serde-round-trip stable.
- journal: the Journal trait (native async via RPITIT + Send), JournalEntry,
  the closed EntryKind enum (control entries carry no payload, so illegal
  states are unrepresentable), and ExecutionStatus.
- effect: the EffectClass per-step side-effect contract.
- config: pure-data DurableConfig + RetentionPolicy with container-level
  serde defaults mirroring the [durable] TOML section.
- error: DurableError (non_exhaustive, metadata-only messages).
- sealed: Sealed token for the future backend hierarchy.

Schema: durable_executions/journal/promises/timers added as numbered
migrations 097-100 in zeph-db/migrations/{sqlite,postgres} (matching file
counts, schema-equivalent). zeph-durable owns no .sql and no sqlx::migrate!;
migrations are applied via zeph_db::run_migrations against the dedicated
durable pool.

No business-layer dependencies (INV-1). Migration ownership stays in
zeph-db (INV-14).

Part of #4707.
Closes #4944.
@github-actions github-actions Bot added documentation Improvements or additions to documentation rust Rust code changes dependencies Dependency updates enhancement New feature or request labels Jun 6, 2026
@bug-ops bug-ops added feature New functionality core zeph-core crate labels Jun 6, 2026
@bug-ops bug-ops added this to the M28 milestone Jun 6, 2026
@bug-ops bug-ops added the architecture Architecture improvements label Jun 6, 2026
@github-actions github-actions Bot added the size/XL Extra large PR (500+ lines) label Jun 6, 2026
@bug-ops bug-ops merged commit 2889532 into main Jun 6, 2026
36 checks passed
@bug-ops bug-ops deleted the feat/m28/4944-durable-scaffold-newtypes-schema branch June 6, 2026 18:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

architecture Architecture improvements core zeph-core crate dependencies Dependency updates documentation Improvements or additions to documentation enhancement New feature or request feature New functionality rust Rust code changes size/XL Extra large PR (500+ lines)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(durable): scaffold zeph-durable crate, core newtypes, journal schema

1 participant