feat(review): producer runtime — generations, bounded resource serving, intent completion (Phase 2)

[benvinegar]

Phase 2 of the browser-review rebuild (docs/browser-review-rebuild.md). Stacked on Phase 1 PR 3 (#720).

What

The producer runtime: the terminal session now publishes the semantic review document — generation-versioned, digest-verified, chunk-addressable — serving the existing hunk session agent surface only (no HTTP, no browser). Five commits: core primitives → intent completion → producer runtime → conformance → audit records.

• Ordering contract (core/review/generationOrder.ts): one named module answering "is this publication acceptable given what I have" — classifyReviewPublication → accepted | stale | gap plus the producer's self-check assertReviewPublicationAdvance. The prototype had five inconsistent implementations of this rule (finding C1); the broker and browser sides will consume this same module in Phase 3/5.
• Resource serving (core/review/resources.ts + src/app/review/): derived resource ids stable across generations, descriptors that start unmeasured, single-flight materialization with an explicit concurrency bound — the unbounded-Promise.all-with-double-reads bug from the original PR 707 review is now structurally impossible. Distinct error codes; integrity failures can never collapse into unknown-resource.
• Intent completion: expansion/toggle (validated via reviewGapAddress) and notes/start-draft landed; SEMANTIC_COMMANDS_WITHOUT_REVIEW_EFFECT is now empty — every semantic command has a declared, wire-lowerable review effect (closes F2).
• Validation single-sourcing (D1/D4/D5 producer sites): reviewNoteWithinBounds measured one way; assertCanonicalFileMatchesManifest comparing by value with no field list (it reuses the manifest projection — a fourth field list can't drift because there is nothing to drift); one canonical digest spelling with hashing injected as ReviewDigestFn. The node-debt map is now empty.
• Conformance: the producer registered as a harness consumer; 10 hand-written ordering-classification fixtures (non-contiguous revisions, generation swap with lower revision, retired-generation replay, foreign producer) plus note-bounds adversarial cases.

How publication works now

flowchart LR
    subgraph terminal["Terminal session"]
        STORE["review store<br/>(controller-owned)"]
        PROD["ReviewProducer<br/>src/app/review/producer.ts"]
        RES["resourceStore<br/>single-flight · concurrency 4<br/>digest-verified chunks"]
        STORE -- "attachStore" --> PROD
        PROD --- RES
    end
    subgraph core["core/review (renderer-free)"]
        GEN["generationOrder<br/>accepted | stale | gap"]
        DOC["document + contentManifest<br/>(now carries patch)"]
    end
    PROD -- "publishes ReviewPublication<br/>generation:producerId:sequence" --> SESSION["session layer<br/>(existing hunk session surface)"]
    PROD -- "self-checks every emission" --> GEN
    SESSION -- "hunk session review --include-patch<br/>bounded materializeResources()" --> AGENT["agents"]
    BROKER["broker mirror — Phase 3"] -.->|"same classify()"| GEN
    WEB["browser — Phase 5"] -.->|"same classify()"| GEN

Loading

sequenceDiagram
    participant A as agent (hunk session)
    participant P as producer
    participant S as resourceStore
    A->>P: read resource {generation, resourceId, offset, length}
    P->>P: classify against current generation
    alt stale generation
        P-->>A: stale-generation + currentGeneration (resync without a round trip)
    else current
        P->>S: materialize (single-flight, bounded)
        S-->>P: verified chunk (whole-resource digest, eof flag)
        P-->>A: chunk — or a DISTINCT error code<br/>(integrity ≠ unknown-resource, by construction)
    end

Loading

Design decisions worth review

• Publication is layered, not merged: ReviewDocumentV1 gained no generation/resource/digest fields — those live in ReviewPublication at the producer tier. The document stays a document.
• Resource ids are derived (resource:kind[:side]:fileKey), so the same file keeps its id across generations and cross-generation caching stays expressible — the prototype's per-generation ids made that impossible.
• Width-only republication is a replay decision at the emitter, not a loosened comparison — Phase 3's broker must not reintroduce the prototype's "equal revision allowed sometimes" special case into classifyReviewPublication.
• The producer attaches to the controller-owned store rather than taking ownership — relocating state ownership is a behavior change, flagged for Phase 3 instead of smuggled in.
• One deliberately removed conformance consumer, reported honestly: producer-side navigation fixtures would have required a store.replace API invented purely for tests; requirement met structurally instead (the annotation index moved into core — producer and terminal call the same function) plus a unit test through producer.applyIntent.

Behavior

hunk session output is byte-identical (registration/snapshot project from the publication; existing assertions pass unchanged). test/session/ and test/pty/ untouched — verified empty diff. One deliberate tightening: expansion/toggle now rejects gap ids the file's geometry doesn't address (unreachable through the UI; two unit-test fixtures that toggled nonexistent gaps were corrected and the change disclosed).

Gates

• bun run typecheck, bun run lint (0/0), bun run format — clean; empty changeset.
• bun test: 2555 pass / 4 fail — failures a subset of baseline's known set (dev-dep ×2 aside, each verified against a parent-branch worktree, incl. repeated PTY runs on both branches to confirm flake parity).
• bun run test:integration (PTY): 105/106, the one failure reproducing on base.
• bun test test/session/: 11/11, files untouched.
• Boundary suite green; node-debt map empty; real render smoke of bun run src/main.tsx -- diff verified.

Repays: C1/C2 producer sides, D1/D4/D5 producer sites, F2 closed (recorded inline in docs/browser-review-seam-audit.md). Phase 3 handoff (ordering contract shape, chunking constants, error-code vocabulary, intent coverage) is recorded in the audit and this stack's task notes.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hunk-web	Ignored	Preview	Aug 13, 2026 12:49am

[greptile-apps]

Greptile Summary

This pull request adds the producer-side browser-review runtime, including ordered generations, bounded and digest-verified resources, semantic intent completion, and session registration integration.

• Adds generation ordering and publication primitives shared by future producer, broker, and browser layers.
• Adds single-flight resource materialization, chunked reads, digest verification, cache bounds, and typed failures.
• Adds draft-start and gap-expansion intents plus shared note, canonical-file, and digest validation.
• Integrates producer publications into initial session registration and reload handling, with conformance coverage.

Confidence Score: 4/5

The pull request appears safe to merge, with only a non-blocking repository style inconsistency across the changed TypeScript files.

The producer, resource, ordering, intent, and reload paths have no established reachable functional failure, but the changed code systematically violates the required single-quote convention.

Files Needing Attention: src/app/review/digest.ts and the other changed TypeScript/TSX files

Important Files Changed

Filename	Overview
src/app/review/producer.ts	Introduces publication generation ownership, resource serving, and semantic-intent application; no blocking defect was established.
src/app/review/resourceStore.ts	Adds single-flight production, bounded bulk loading, digest verification, and cache eviction; direct reads do not use the bulk concurrency gate, but that path currently lacks a production caller.
src/core/review/generationOrder.ts	Centralizes publication ordering and producer advance validation with comprehensive boundary tests.
src/core/review/intents.ts	Adds draft-start and expansion-toggle intents; explicit draft targets are trusted, but currently reachable UI callers derive them from valid rendered geometry.
src/ui/AppHost.tsx	Publishes a new producer generation before replacing session registration during reload and preserves existing soft/full reload behavior.
src/session/app/registration.ts	Projects producer publications into the existing session registration and snapshot shapes without an established compatibility regression.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Diff[Diff files] --> Producer[ReviewProducer]
  Producer --> Publication[Generation-versioned publication]
  Producer --> Store[ReviewResourceStore]
  Store --> Resources[Digest-verified resource chunks]
  Publication --> Session[Session registration and snapshot]
  Resources --> Session
  Intent[Semantic review intent] --> Producer
  Producer -. requires attached ReviewStore .-> ReviewState[Controller-owned review state]
  Reload[AppHost reload] --> Producer
  Reload --> Publication

Loading

Prompt To Fix All With AI

### Issue 1
src/app/review/digest.ts:10-11
**Double-quoted strings violate style**

The newly added TypeScript and TSX code uses double-quoted imports and literals throughout the producer, core review, session, UI, and test files, contrary to the repository's required single-quote convention. This establishes a conflicting formatting pattern and creates avoidable maintenance churn.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "docs(rebuild): record the Phase 2 repaym..." | Re-trigger Greptile}

[greptile-apps]

Double-quoted strings violate style

The newly added TypeScript and TSX code uses double-quoted imports and literals throughout the producer, core review, session, UI, and test files, contrary to the repository's required single-quote convention. This establishes a conflicting formatting pattern and creates avoidable maintenance churn.

Context Used: guidelines.mdc Cursor rule (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/app/review/digest.ts
Line: 10-11

Comment:
**Double-quoted strings violate style**

The newly added TypeScript and TSX code uses double-quoted imports and literals throughout the producer, core review, session, UI, and test files, contrary to the repository's required single-quote convention. This establishes a conflicting formatting pattern and creates avoidable maintenance churn.

**Context Used:** guidelines.mdc Cursor rule ([source](https://github.com/modem-dev/modem/blob/main/.cursor/rules/guidelines.mdc))

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!