From fe6b78fa59657449be2e888402e3a0197b5c0621 Mon Sep 17 00:00:00 2001 From: soryu Date: Thu, 30 Apr 2026 17:08:30 +0100 Subject: feat(directives): per-PR revision snapshots + sidebar history (#112) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Stage 3 of the doc-mode revamp. Builds the foundation for treating contracts as living specifications by freezing their content into a revision every time a PR is raised. ## directive_revisions table (new migration) (id, directive_id, content, pr_url, pr_branch, pr_state, version, frozen_at) with UNIQUE(directive_id, version) and a partial index on pr_state='open' so the next reconciler iteration can poll only what's still in flight. pr_state is constrained to 'open' | 'merged' | 'closed' to mirror GitHub's PR lifecycle. For Stage 3 we only freeze on PR creation; pr_state poll is deferred to a follow-up. ## Repository helpers - create_directive_revision: idempotent on (directive_id, pr_url) so a re-run of the orchestrator's completion task can't double-snapshot. Auto-assigns version = MAX(existing) + 1 per directive. - list_directive_revisions_for_owner: scoped through the directive join so users can only read their own contract history. - update_directive_revision_pr_state: stub for the upcoming poller. - get_latest_merged_revision: returns the most recent merged revision — this is what Stage 4 will diff against on amendments. ## Snapshot trigger update_directive handler now reads the BEFORE pr_url before the update. If pr_url transitions None → Some, it snapshots the directive's current goal as a revision tied to the new pr_url. Failures log and continue — the directive update itself is unaffected. ## API + OpenAPI GET /api/v1/directives/{id}/revisions returns DirectiveRevisionListResponse (revisions newest-first). Schemas registered in OpenAPI. ## Frontend: revisions/ subfolder + read-only viewer Each contract folder now has a third subfolder ("revisions/") that lazily fetches and lists past revisions when the parent directive folder is open. Empty contracts skip the subfolder entirely so brand-new ones aren't cluttered. Each row shows v.md plus a small pill ('open'/'merged'/ 'closed'). Selecting a revision encodes itself into the existing ?task= param as "revision:", so EditorShell can route between the live task stream (realTaskId), the read-only RevisionViewer (revisionId), or the editor itself (neither). The viewer renders the frozen markdown verbatim with a deep-link to the PR — these are immutable historical records, not edit surfaces. Co-authored-by: Claude Opus 4.7 (1M context) --- makima/src/db/models.rs | 16 ++++++ makima/src/db/repository.rs | 118 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 134 insertions(+) (limited to 'makima/src/db') diff --git a/makima/src/db/models.rs b/makima/src/db/models.rs index 97657dc..1fe6e35 100644 --- a/makima/src/db/models.rs +++ b/makima/src/db/models.rs @@ -2733,6 +2733,22 @@ pub struct DirectiveGoalHistory { pub created_at: DateTime, } +/// Per-PR snapshot of a directive's goal — the immutable record of what the +/// contract said at the moment a PR was raised. Frozen at PR-creation time; +/// `pr_state` mirrors the PR's GitHub lifecycle ('open' | 'merged' | 'closed'). +#[derive(Debug, Clone, FromRow, Serialize, Deserialize, ToSchema)] +#[serde(rename_all = "camelCase")] +pub struct DirectiveRevision { + pub id: Uuid, + pub directive_id: Uuid, + pub content: String, + pub pr_url: String, + pub pr_branch: Option, + pub pr_state: String, + pub version: i32, + pub frozen_at: DateTime, +} + /// A step in a directive's DAG. #[derive(Debug, Clone, FromRow, Serialize, Deserialize, ToSchema)] #[serde(rename_all = "camelCase")] diff --git a/makima/src/db/repository.rs b/makima/src/db/repository.rs index cec9a82..1021c35 100644 --- a/makima/src/db/repository.rs +++ b/makima/src/db/repository.rs @@ -5691,6 +5691,124 @@ pub async fn update_directive_goal_keep_orchestrator( .await } +// ============================================================================= +// Directive Revisions — per-PR snapshots of the contract content. +// ============================================================================= + +/// Snapshot the directive's current goal as a revision attached to the given +/// PR URL. The version is auto-assigned as MAX(existing) + 1 per directive. +/// Idempotent on (directive_id, pr_url): if a revision already exists for +/// this directive+pr_url combo, returns the existing row instead of creating +/// a duplicate. +pub async fn create_directive_revision( + pool: &PgPool, + directive_id: Uuid, + content: &str, + pr_url: &str, + pr_branch: Option<&str>, +) -> Result { + // Idempotency: don't double-snapshot if the orchestrator's completion task + // re-runs and re-sets the same pr_url. + if let Some(existing) = sqlx::query_as::<_, crate::db::models::DirectiveRevision>( + r#" + SELECT * FROM directive_revisions + WHERE directive_id = $1 AND pr_url = $2 + ORDER BY frozen_at DESC LIMIT 1 + "#, + ) + .bind(directive_id) + .bind(pr_url) + .fetch_optional(pool) + .await? + { + return Ok(existing); + } + + sqlx::query_as::<_, crate::db::models::DirectiveRevision>( + r#" + INSERT INTO directive_revisions + (directive_id, content, pr_url, pr_branch, pr_state, version, frozen_at) + SELECT + $1, + $2, + $3, + $4, + 'open', + COALESCE(MAX(version), 0) + 1, + NOW() + FROM directive_revisions + WHERE directive_id = $1 + RETURNING * + "#, + ) + .bind(directive_id) + .bind(content) + .bind(pr_url) + .bind(pr_branch) + .fetch_one(pool) + .await +} + +/// List all revisions for a directive, newest first. Scoped by owner via the +/// directive join so callers don't accidentally surface other users' history. +pub async fn list_directive_revisions_for_owner( + pool: &PgPool, + owner_id: Uuid, + directive_id: Uuid, +) -> Result, sqlx::Error> { + sqlx::query_as::<_, crate::db::models::DirectiveRevision>( + r#" + SELECT r.* + FROM directive_revisions r + JOIN directives d ON d.id = r.directive_id + WHERE r.directive_id = $1 AND d.owner_id = $2 + ORDER BY r.frozen_at DESC + "#, + ) + .bind(directive_id) + .bind(owner_id) + .fetch_all(pool) + .await +} + +/// Update the pr_state on a revision (called by the reconciler when it +/// detects a PR transitioned to merged/closed). New state must be one of +/// 'open' | 'merged' | 'closed' to satisfy the table's CHECK constraint. +pub async fn update_directive_revision_pr_state( + pool: &PgPool, + revision_id: Uuid, + new_state: &str, +) -> Result<(), sqlx::Error> { + sqlx::query( + r#"UPDATE directive_revisions SET pr_state = $2 WHERE id = $1"#, + ) + .bind(revision_id) + .bind(new_state) + .execute(pool) + .await?; + Ok(()) +} + +/// Find the most recent merged revision for a directive — used when planning +/// an amendment to know what the previous "frozen" content was so the diff +/// can be passed to the orchestrator. +pub async fn get_latest_merged_revision( + pool: &PgPool, + directive_id: Uuid, +) -> Result, sqlx::Error> { + sqlx::query_as::<_, crate::db::models::DirectiveRevision>( + r#" + SELECT * FROM directive_revisions + WHERE directive_id = $1 AND pr_state = 'merged' + ORDER BY frozen_at DESC + LIMIT 1 + "#, + ) + .bind(directive_id) + .fetch_optional(pool) + .await +} + /// Save a goal to the directive goal history. pub async fn save_directive_goal_history( pool: &PgPool, -- cgit v1.2.3