Skip to content

3C-B1: pure CurationSession + boundary event minting - #145

Merged
PhysShell merged 4 commits into
mainfrom
claude/curation-session-3c-b1
Jul 25, 2026
Merged

PhysShell merged 4 commits into
mainfrom
claude/curation-session-3c-b1

Conversation

@PhysShell

Copy link
Copy Markdown
Owner

What

The renderer-agnostic curation session over the merged curation_store
domain model — step 3C-B1. New module ui-core/src/curation_session.rs. No
I/O, no UI: it holds the append-only store for one editing session, assembles a
CurationEvent from a decision plus the corpus, and projects/reconciles through
core. A frontend supplies the opaque event_id / canonical occurred_at and
persists session.store() through the OPFS/native adapter (3C-B2).

Surface

  • CurationSession::bootstrap(Option<store>, corpus) — a loaded store, or a
    fresh empty store pinned to the current corpus (typed empty bootstrap).
  • record(RecordRequest, corpus) — looks the chunk up, computes its
    chunk_fingerprint + the corpus_fingerprint, snapshots the dedup cluster via
    build_clusters, and appends a new CurationEvent. Never mutates. Unknown
    or unpinned chunk → typed RecordError.
  • projected() / reconcile(corpus) — delegate to core project / reconcile.
  • mint_event_id([u8; 16]) — a canonical RFC-4122 v4 UUID from boundary bytes.
  • canonical_timestamp(epoch_secs) — second-precision YYYY-MM-DDTHH:MM:SSZ
    (civil-from-days), so a minted timestamp passes the store's validator (which
    rejects fractional seconds).

Which acceptance points this covers (at the pure/session level)

  • 1 typed empty bootstrap; 4 a repeat decision is a new event, never a
    mutation; 5 equal timestamp breaks by event_id; 6 a regrouped cluster
    does not move a decision (reconcile keeps it active while the chunk's material
    is unchanged); 7 a deleted/changed chunk is orphaned. Plus cluster context
    is snapshotted as audit-only, and the minting primitives.

The impure random/clock sources stay at the cockpit boundary (getrandom, JS
Date) — 3C-B2. This slice is the pure engine, native-tested.

Validation

  • cargo test -p griff-ui-core --lib — 157/157 (10 new curation_session).
  • cargo clippy --workspace --all-targets + cargo fmt --check — clean.
  • Pre-existing local-only griff-cli::missing_file_golden (RU-locale OS string)
    is unrelated.

Next: 3C-B2 wires this into the cockpit (accept/reject UI, event minting from
getrandom + Date, persist via the 3C-A adapter with a save-state), then 3C-B3
the Playwright accept→persist→reload end-to-end — now runnable locally via the
3C-B0 flake.

🤖 Generated with Claude Code

PhysShell and others added 2 commits July 19, 2026 08:07
…C-B1)

The renderer-agnostic curation session over the merged curation_store model, as
failing tests against stub bodies:

- bootstrap(None) pins an empty store to the current corpus (a typed empty
  bootstrap), bootstrap(Some) keeps the loaded store;
- record appends a new CurationEvent and never mutates an existing one; a repeat
  decision is a second event, and the projection takes the later one;
- an equal timestamp breaks by event_id;
- record snapshots the chunk's dedup cluster as audit context;
- a regrouped cluster does NOT move a decision (reconcile keeps it active while
  the chunk's material is unchanged);
- a deleted/changed chunk is orphaned;
- record rejects an unknown chunk;
- mint_event_id is a canonical v4 UUID from 16 boundary bytes;
- canonical_timestamp is second-precision UTC (no fractional part, which the
  store rejects) and round-trips through decode.

No I/O, no UI: the frontend supplies the opaque event_id / occurred_at and
persists session.store() through the OPFS/native adapter (3C-B2). Stubs make all
ten tests fail.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NkqJUU6d1sW1RAfvyHrqVM
…(3C-B1)

Implement the session so all ten tests pass:

- bootstrap: Loaded wraps the store; Missing mints a fresh empty store pinned to
  the corpus via core::corpus_fingerprint (a typed empty bootstrap).
- record: looks the chunk up in the corpus, computes its chunk_fingerprint and
  the corpus_fingerprint, snapshots the dedup cluster via build_clusters, and
  APPENDS a new CurationEvent — never mutates. Unknown chunk / unpinned chunk are
  typed errors.
- projected / reconcile delegate to core::project / core::reconcile, so a repeat
  decision is resolved by (occurred_at, event_id) and a regrouped cluster never
  moves a live decision.
- mint_event_id: a canonical RFC-4122 v4 UUID from 16 boundary bytes (version 4,
  variant 10, hyphenated hex).
- canonical_timestamp: second-precision YYYY-MM-DDTHH:MM:SSZ from epoch seconds
  (civil-from-days), so a minted timestamp is accepted by the store — no
  fractional part, which curation_store rejects.

Pure and native-tested; the impure random/clock sources stay at the cockpit
boundary (3C-B2). Scoped arithmetic-lint allow on the bounded civil-from-days math.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NkqJUU6d1sW1RAfvyHrqVM
@coderabbitai

coderabbitai Bot commented Jul 19, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

@PhysShell, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 29 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 904313eb-e24b-433c-aadc-46e651639a30

📥 Commits

Reviewing files that changed from the base of the PR and between fcac6b8 and 224ea92.

📒 Files selected for processing (2)
  • ui-core/src/curation_session.rs
  • ui-core/src/lib.rs
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch claude/curation-session-3c-b1

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0f0e1a3524

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread ui-core/src/curation_session.rs Outdated
/// this only stamps the version (4) and variant (10) bits and the canonical
/// hyphenated hex layout, so the id is opaque, unique, and stable.
#[must_use]
pub fn mint_event_id(bytes: [u8; 16]) -> CurationEventId {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Preserve same-second decision order

When a curator changes the same chunk twice within one wall-clock second, both events get the same occurred_at from the second-precision timestamp helper and core projection falls back to event_id; because this helper mints a random v4 UUID, the later click only wins if its random UUID sorts higher. That makes rapid accept/reject corrections project and persist the wrong decision about half the time, so the tie-breaker needs to be monotonic for events sharing a timestamp or the timestamp source needs an ordered sub-second/counter component.

Useful? React with 👍 / 👎.

/// Its dedup cluster's representative and all members (itself when it is a
/// singleton). Never part of the decision's identity — a navigation/audit fact.
fn cluster_context(chunk_id: &ChunkId, corpus: &[ChunkMeta]) -> CurationContext {
let (clusters, _diagnostics) = build_clusters(corpus);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Surface malformed duplicate links instead of singleton context

For a selected chunk with a malformed duplicate link, build_clusters returns a diagnostic and omits that chunk from the cluster set; discarding _diagnostics here makes the miss fall through to a clean singleton context. That records audit data saying the chunk was alone instead of surfacing the provenance defect, contrary to the cluster builder's contract that broken links must not silently masquerade as singletons.

Useful? React with 👍 / 👎.


/// The append-only curation store for one editing session.
#[derive(Debug, Clone)]
pub struct CurationSession {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Split the red tests from implementation

AGENTS.md requires the red/green sequence per commit and specifically says new public pub fn / pub struct implementations must not be committed together with the tests that cover them; this single commit adds the public CurationSession surface and its covering tests in one diff. Please split this into a failing-test commit followed by the implementation commit so the reviewed commit sequence satisfies the repository's mandatory TDD workflow.

Useful? React with 👍 / 👎.

PhysShell and others added 2 commits July 19, 2026 08:43
…C-B1)

Corrective for the PR #145 review. Two contract violations, as failing tests:

1. A random UUIDv4 does not order events. The store picks the latest decision by
   (occurred_at, event_id), so within one canonical second the event_id must
   decide — a bare UUID can invert two same-second clicks. Replace mint_event_id
   with a stateful EventIdMinter minting web-{ms:016x}-{seq:08x}-{uuid}: a
   Lamport-monotonic ordering prefix (UUID only the uniqueness tail), seeded from
   the loaded store. Tests: a later same-second mint sorts higher; a reload mints
   above the highest saved id; a clock rollback never lowers the id; mints are
   unique; the seed is order-independent.

2. canonical_timestamp silently clamped a bad clock to 1970 (max(0)). It now
   returns Result<String, TimestampError>: a negative or out-of-range time is a
   typed refusal, never a normalised epoch lie.

Also drops the false ADR-0030 §8 citation (that ADR is reduced-state DP, not
curation identity). Stubs keep the old behavior, so the four causal tests fail.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NkqJUU6d1sW1RAfvyHrqVM
…(3C-B1)

Resolve the two PR #145 correctives; all 15 curation_session tests pass.

- EventIdMinter mints web-{ms:016x}-{seq:08x}-{uuid}. from_store seeds the
  high-water from the max (ms, seq) parsed over the store's ids (order-
  independent). mint is a Lamport clock: it advances the millisecond when the
  boundary clock moves forward, otherwise bumps the sub-counter — so a later
  same-second click, a reload, and even a rolled-back clock all sort strictly
  higher, while the UUID tail keeps ids unique. The projection's (occurred_at,
  event_id) tie-break is now causal, not a coin flip.

- canonical_timestamp returns Result: a negative time is BeforeEpoch and a year
  outside 0000..=9999 is OutOfRange — a bad clock is a typed refusal, never a
  normalised 1970 lie.

EventIdMinter is intentionally not Copy (a mutable accumulator); TimestampError
is a plain Copy value. The false ADR-0030 citation is gone.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NkqJUU6d1sW1RAfvyHrqVM
@PhysShell

Copy link
Copy Markdown
Owner Author

Corrective for all three (RED c1f422b → GREEN 224ea92)

1. Random UUID → Lamport-ordered EventIdMinter

mint_event_id is replaced by a stateful EventIdMinter that mints
web-{ms:016x}-{seq:08x}-{uuid} — a monotonic ordering prefix with the UUID as
the uniqueness tail, so the projection's (occurred_at, event_id) tie-break
is now causal:

  • from_store seeds the high-water from the max (ms, seq) parsed over
    the store's ids — order-independent (property 4).
  • mint is a Lamport clock: it advances the millisecond when the boundary
    clock moves forward, otherwise bumps the sub-counter. So a later same-second
    click sorts higher (1), a reload continues above every saved id (2), and a
    clock rollback never lowers the id (5). The UUID tail keeps ids unique (3).

Tests: a_later_mint_in_the_same_second_sorts_higher (the second seed's UUID
sorts below the first's, so a random-only id would invert — the prefix wins),
a_reload_mints_above_the_highest_saved_id, a_clock_rollback_does_not_lower_the_id,
mints_are_unique, from_store_is_independent_of_event_order.

EventIdMinter is intentionally not Copy — a silent copy would fork the
high-water counter.

2. canonical_timestamp is fallible

It returns Result<String, TimestampError>: a negative time is BeforeEpoch, a
year outside 0000..=9999 is OutOfRange. A bad clock is a typed refusal, never
a normalised 1970-01-01T00:00:00Z. Test a_bad_clock_is_a_typed_error_not_a_1970_lie.

3. False ADR reference removed

The (ADR-0030 §8) citation on the cluster-context invariant is gone (that ADR
is reduced-state layered DP, not curation identity); the module doc now states
the invariant as curation_store::reconcile's.

Scope unchanged otherwise — CurationSession not expanded, no UI/OPFS pulled in.

Validation

  • cargo test -p griff-ui-core --lib — 162/162 (15 curation_session).
  • cargo clippy --workspace --all-targets + cargo fmt --check — clean.

Still HOLD — not merging.

@PhysShell
PhysShell merged commit 17afe07 into main Jul 25, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant