specs/012-patch-branch-refactor/data-model.md

Ref: main   Size: 2.2 KiB

# Data Model: Patch-as-Branch Refactor

## Entity Changes

### PatchCreate Action (Modified)

Current fields:
- `title: String`
- `body: String`
- `base_ref: String` — target branch for merge (e.g., "main")
- `head_commit: String` — snapshot OID of the reviewed commit
- `fixes: Option<String>` — linked issue ID

New fields:
- `title: String` — unchanged
- `body: String` — unchanged
- `base_ref: String` — unchanged
- `head_commit: String` — **kept for backward compat**, stores branch tip at creation time
- `branch: Option<String>` — **NEW**: the branch name (e.g., "feature/foo"). When present, this is the source of truth.
- `fixes: Option<String>` — unchanged

### PatchState (Modified)

Current fields remain. Add:
- `branch: Option<String>` — the branch name, populated from PatchCreate event. `None` for old-format patches.

The `head_commit` field becomes computed for branch-based patches:
- If `branch` is `Some`, resolve `refs/heads/{branch}` to get current tip
- If `branch` is `None`, use stored `head_commit` (old behavior)

### PatchRevise Action (Deprecated)

- Kept for backward compat but no longer required for branch-based patches
- Branch-based patches auto-track the branch tip
- Can still be used to record explicit revision notes in the DAG

### Staleness Info (New, Computed)

Not stored — computed on demand from git:
- `ahead: usize` — commits on branch not on base
- `behind: usize` — commits on base not on branch
- `is_merged: bool` — whether branch commits are ancestors of base tip
- `has_conflicts: bool` — whether merge would conflict (optional, expensive)

## State Transitions

```
PatchCreate (with branch) → Open
  ↓ (branch updated externally) → still Open, diff changes automatically
  ↓ PatchReview → still Open (reviews attached)
  ↓ PatchMerge → Merged (git merge performed)
  ↓ PatchClose → Closed
  ↓ (branch deleted) → Open but "branch not found" error on diff/merge
```

## Ref Structure (Unchanged)

```
refs/collab/patches/{id}  → review DAG (comments, reviews, events)
refs/heads/{branch}       → actual code (normal git branch)
```

The review DAG and the code branch are separate refs. The DAG references the branch by name (string), not by OID.