ai-foreman 1.7.5 → 1.7.7

package/dist/tickets/setupConfig.js

@@ -1,14 +1,17 @@
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { parse, stringify } from "yaml";
 import { loadDefaults } from "special-agents";
 import { appendLegacyTicketSources, loadSourceRegistry } from "../sources/sourceRegistry.js";
+import { BUILTIN_BRANCH_PREFIX, validateBranchPrefix } from "../branch/prefix.js";
 export const RAFI_CONFIG_FILE = "rafi-config.yaml";
 const AGENT_NAMES = ["builder", "qa", "planner", "ticket-maker", "uninstaller"];
 const SKILL_NAMES = [
     "better-sqlite3-rebuild",
     "grill-me",
+    "handoff",
     "improve-codebase-architecture",
     "prd-to-issues",
     "tdd",
@@ -16,6 +19,7 @@ const SKILL_NAMES = [
 ];
 export const DEFAULT_TICKET_SETUP = {
     sources: [],
+    limits: { implementation: 500, view: 20_000 },
     populate: {
         source_handling: "saved",
         agent_preference: "configured",
@@ -33,6 +37,26 @@ export const DEFAULT_TICKET_SETUP = {
         cleanup: true,
         auto_merge_wait: false,
         auto_merge_timeout_minutes: null,
+        base_branch: "main",
+        branch_prefix: BUILTIN_BRANCH_PREFIX,
+        branch_policy: {
+            mode: "global",
+            global_strategy: "branch-per-ticket",
+            by_size: { XS: "shared", S: "shared", M: "per-ticket", L: "per-ticket", XL: "per-ticket" },
+        },
+        review: {
+            title_style: "ticket-title",
+            title_template: null,
+            description_sections: ["Summary", "Linked ticket", "Changes made", "Tests and validation performed", "Risks or rollback notes", "Checklist"],
+        },
+        validation_checklist: [
+            "Acceptance criteria satisfied",
+            "Required tests pass",
+            "Configured project checks pass",
+            "Documentation updated when needed",
+            "Database and deployment changes reviewed when present",
+            "Validation evidence attached",
+        ],
     },
 };
 export function loadRafiConfigObject(projectDir) {
@@ -75,7 +99,22 @@ export function saveTicketSetupConfig(projectDir, setup, opts = {}) {
             delete config.planning;
     }
     mkdirSync(projectDir, { recursive: true });
-    writeFileSync(join(projectDir, RAFI_CONFIG_FILE), stringify(config, { lineWidth: 100 }), "utf8");
+    const target = join(projectDir, RAFI_CONFIG_FILE);
+    const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, stringify(config, { lineWidth: 100 }), "utf8");
+    renameSync(temporary, target);
+}
+/** Synchronize pending setup limits into the tracker, once the tracker exists. */
+export function syncTicketLimits(projectDir, limits) {
+    const path = join(projectDir, ".tickets", "config.yaml");
+    if (!existsSync(path))
+        return;
+    const raw = parse(readFileSync(path, "utf8"));
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error(`${path}: expected a YAML object`);
+    raw.implementation_limit = positiveInteger(limits.implementation, 500, "tickets.limits.implementation");
+    raw.view_limit = positiveInteger(limits.view, 20_000, "tickets.limits.view");
+    writeFileSync(path, stringify(raw, { lineWidth: 100 }), "utf8");
 }
 export function ensureRafiConfigForTicketSetup(projectDir, opts = {}) {
     const existing = loadRafiConfigObject(projectDir);
@@ -95,6 +134,7 @@ export function normalizeTicketsSetupConfig(value, label = "tickets") {
     const raw = value;
     const setup = {
         sources: normalizeSources(raw.sources, `${label}.sources`),
+        limits: normalizeLimits(raw.limits, `${label}.limits`),
         populate: normalizePopulate(raw.populate, `${label}.populate`),
         build: normalizeBuild(raw.build, `${label}.build`),
     };
@@ -103,6 +143,7 @@ export function normalizeTicketsSetupConfig(value, label = "tickets") {
 export function denormalizeTicketsSetupConfig(setup) {
     return {
         sources: setup.sources.map((source) => ({ ...source })),
+        limits: { ...setup.limits },
         populate: { ...setup.populate },
         build: { ...setup.build },
     };
@@ -111,6 +152,7 @@ export function mergeTicketSetup(current, patch) {
     const base = current ? cloneTicketSetup(current) : cloneTicketSetup(DEFAULT_TICKET_SETUP);
     return normalizeTicketsSetupConfig({
         sources: patch.sources ?? base.sources,
+        limits: patch.limits ?? base.limits,
         populate: { ...base.populate, ...(patch.populate ?? {}) },
         build: { ...base.build, ...(patch.build ?? {}) },
     });
@@ -212,6 +254,22 @@ export function detectGitProvider(projectDir) {
     }
     return undefined;
 }
+export function detectDefaultBranch(projectDir) {
+    const attempts = [
+        ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"],
+        ["config", "--get", "init.defaultBranch"],
+        ["branch", "--show-current"],
+    ];
+    for (const args of attempts) {
+        try {
+            const value = execFileSync("git", args, { cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+            if (value)
+                return value.replace(/^origin\//, "");
+        }
+        catch { /* try the next safe source */ }
+    }
+    return "main";
+}
 export function recommendedBuildDefaults(projectDir) {
     const provider = detectGitProvider(projectDir);
     return {
@@ -221,6 +279,7 @@ export function recommendedBuildDefaults(projectDir) {
         pr_ready: Boolean(provider),
         merge_method: "squash",
         cleanup: true,
+        base_branch: detectDefaultBranch(projectDir),
     };
 }
 function minimalRafiConfig(projectDir, opts) {
@@ -354,6 +413,46 @@ function normalizeBuild(value, label) {
         cleanup: booleanField(raw.cleanup, DEFAULT_TICKET_SETUP.build.cleanup, `${label}.cleanup`),
         auto_merge_wait: booleanField(raw.auto_merge_wait, DEFAULT_TICKET_SETUP.build.auto_merge_wait, `${label}.auto_merge_wait`),
         auto_merge_timeout_minutes: nullablePositiveInteger(raw.auto_merge_timeout_minutes, DEFAULT_TICKET_SETUP.build.auto_merge_timeout_minutes, `${label}.auto_merge_timeout_minutes`),
+        base_branch: stringField(raw.base_branch, DEFAULT_TICKET_SETUP.build.base_branch),
+        branch_prefix: validateBranchPrefix(stringField(raw.branch_prefix, DEFAULT_TICKET_SETUP.build.branch_prefix)),
+        branch_policy: normalizeBranchPolicy(raw.branch_policy, raw.branch_strategy, `${label}.branch_policy`),
+        review: normalizeReview(raw.review, `${label}.review`),
+        validation_checklist: stringArray(raw.validation_checklist, DEFAULT_TICKET_SETUP.build.validation_checklist, `${label}.validation_checklist`),
+    };
+}
+function normalizeLimits(value, label) {
+    const raw = objectOrEmpty(value, label);
+    return {
+        implementation: positiveInteger(raw.implementation, DEFAULT_TICKET_SETUP.limits.implementation, `${label}.implementation`),
+        view: positiveInteger(raw.view, DEFAULT_TICKET_SETUP.limits.view, `${label}.view`),
+    };
+}
+function normalizeBranchPolicy(value, legacyStrategy, label) {
+    const raw = objectOrEmpty(value, label);
+    const sizes = objectOrEmpty(raw.by_size, `${label}.by_size`);
+    const globalStrategy = enumField(raw.global_strategy ?? legacyStrategy, ["current", "batch", "branch-per-ticket"], DEFAULT_TICKET_SETUP.build.branch_policy.global_strategy, `${label}.global_strategy`);
+    return {
+        mode: enumField(raw.mode, ["global", "size"], DEFAULT_TICKET_SETUP.build.branch_policy.mode, `${label}.mode`),
+        global_strategy: globalStrategy,
+        by_size: {
+            XS: enumField(sizes.XS, ["shared", "per-ticket"], "shared", `${label}.by_size.XS`),
+            S: enumField(sizes.S, ["shared", "per-ticket"], "shared", `${label}.by_size.S`),
+            M: enumField(sizes.M, ["shared", "per-ticket"], "per-ticket", `${label}.by_size.M`),
+            L: enumField(sizes.L, ["shared", "per-ticket"], "per-ticket", `${label}.by_size.L`),
+            XL: enumField(sizes.XL, ["shared", "per-ticket"], "per-ticket", `${label}.by_size.XL`),
+        },
+    };
+}
+function normalizeReview(value, label) {
+    const raw = objectOrEmpty(value, label);
+    const titleStyle = enumField(raw.title_style, ["ticket-title", "conventional", "none", "custom"], DEFAULT_TICKET_SETUP.build.review.title_style, `${label}.title_style`);
+    const titleTemplate = nullableString(raw.title_template);
+    if (titleStyle === "custom" && !titleTemplate)
+        throw new Error(`${label}.title_template: required for custom title style`);
+    return {
+        title_style: titleStyle,
+        title_template: titleTemplate,
+        description_sections: stringArray(raw.description_sections, DEFAULT_TICKET_SETUP.build.review.description_sections, `${label}.description_sections`),
     };
 }
 function objectOrEmpty(value, label) {
@@ -418,6 +517,13 @@ function nullablePositiveInteger(value, fallback, label) {
         return Number(value);
     throw new Error(`${label}: expected a positive integer or null`);
 }
+function stringArray(value, fallback, label) {
+    if (value === undefined)
+        return [...fallback];
+    if (!Array.isArray(value) || !value.every((item) => typeof item === "string" && item.trim()))
+        throw new Error(`${label}: expected non-empty strings`);
+    return [...new Set(value.map((item) => String(item).trim()))];
+}
 function normalizeTargets(value) {
     if (!Array.isArray(value))
         return [];
@@ -431,8 +537,14 @@ function normalizeTargets(value) {
 function cloneTicketSetup(setup) {
     return {
         sources: setup.sources.map((source) => ({ ...source, ...(source.type === "local" ? { paths: [...source.paths] } : {}) })),
+        limits: { ...setup.limits },
         populate: { ...setup.populate },
-        build: { ...setup.build },
+        build: {
+            ...setup.build,
+            branch_policy: { ...setup.build.branch_policy, by_size: { ...setup.build.branch_policy.by_size } },
+            review: { ...setup.build.review, description_sections: [...setup.build.review.description_sections] },
+            validation_checklist: [...setup.build.validation_checklist],
+        },
     };
 }
 function unique(values) {

package/dist/tickets/stateDb.d.ts

@@ -1,3 +1,4 @@
+import type { SavedTicketDefinitionSnapshot, TicketGroup, TicketGroupId, TicketGroupOrigin } from "rafi-spec";
 export type TicketStatus = "planned" | "next" | "in_progress" | "blocked" | "done" | "canceled" | "obsolete";
 export type ValidationResult = "passed" | "failed" | "not_run" | "not_applicable";
 export interface TicketState {
@@ -89,6 +90,14 @@ export interface OperationReceipt {
     completed_at: string;
     payload_json: string;
 }
+export interface TicketGroupValidationIssue {
+    code: "missing-membership" | "multiple-membership" | "unknown-member" | "empty-group" | "sequence-corruption" | "reused-id" | "snapshot-corruption" | "receipt-without-group";
+    message: string;
+    groupId?: TicketGroupId;
+    ticketId?: string;
+}
+/** The only valid initial/fully-reset active state for a ticket. */
+export declare function pristineTicketState(ticketId: string, now: string, actor?: string | null): TicketState;
 export declare class StateDb {
     private db;
     constructor(dbPath: string);
@@ -96,17 +105,22 @@ export declare class StateDb {
     close(): void;
     getState(ticketId: string): TicketState | undefined;
     getAllStates(): Map<string, TicketState>;
+    deleteState(ticketId: string): void;
     upsertState(ticketId: string, patch: Partial<Omit<TicketState, "ticket_id">>, now: string): void;
-    insertEvent(event: Omit<TicketEvent, "id">): void;
+    insertEvent(event: Omit<TicketEvent, "id">): number;
+    deleteEvents(ids: number[]): void;
     getRecentEvents(limit: number): TicketEvent[];
+    getTicketEvents(ticketId: string): TicketEvent[];
     insertValidationSnapshot(snap: Omit<ValidationSnapshot, "id">): void;
     getRecentValidationSnapshot(): ValidationSnapshot | undefined;
+    getValidationSnapshots(scope?: string): ValidationSnapshot[];
     insertFutureWork(item: Omit<FutureWorkItem, "id">): number;
     getFutureWork(): FutureWorkItem[];
     getFutureWorkById(id: number): FutureWorkItem | undefined;
     updateFutureWorkDisposition(id: number, disposition: string): void;
     getRecentCompleted(): RecentCompletedContext[];
     upsertRecentCompleted(row: RecentCompletedContext): void;
+    deleteRecentCompleted(ticketId: string): void;
     getArchiveIndex(): ArchiveIndexEntry[];
     insertReviewRecommendation(item: Omit<ReviewRecommendation, "id">): number;
     getReviewRecommendations(status?: ReviewRecommendationStatus): ReviewRecommendation[];
@@ -114,5 +128,32 @@ export declare class StateDb {
     updateReviewRecommendationStatus(id: number, status: ReviewRecommendationStatus, updatedAt: string): void;
     getOperationReceipt(operationId: string): OperationReceipt | undefined;
     recordOperationReceipt(receipt: OperationReceipt): boolean;
+    createTicketGroup(input: {
+        origin: TicketGroupOrigin;
+        operationId: string;
+        members: Array<{
+            ticketId: string;
+            definition: unknown;
+            validatedAt?: string;
+        }>;
+        legacy?: boolean;
+        createdAt?: string;
+    }): TicketGroup;
+    /** Update only the recoverable definition; membership and order never change. */
+    updateTicketDefinitionSnapshot(ticketId: string, definition: unknown, validatedAt?: string): SavedTicketDefinitionSnapshot;
+    getTicketGroupByOperation(operationId: string): TicketGroup | undefined;
+    getTicketGroup(groupId: string): TicketGroup | undefined;
+    getTicketGroupForTicket(ticketId: string): TicketGroup | undefined;
+    listTicketGroups(): TicketGroup[];
+    /** One-time migration for repositories whose complete ticket set predates groups. */
+    ensureSyntheticLegacyGroup(definitions: Array<{
+        id: string;
+    } & Record<string, unknown>>, now?: Date): TicketGroup | undefined;
+    ungroupedTicketIds(ticketIds: readonly string[]): string[];
+    repairTicketGroups(definitions: Array<{
+        id: string;
+    } & Record<string, unknown>>, operationId: string, now?: Date): TicketGroup | undefined;
+    validateTicketGroups(knownTicketIds?: readonly string[]): TicketGroupValidationIssue[];
+    private getTicketGroupBySequence;
     transaction<T>(fn: () => T): T;
 }

package/dist/tickets/stateDb.js

@@ -1,6 +1,32 @@
 import Database from "better-sqlite3";
 import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
+import { createHash } from "node:crypto";
+/** The only valid initial/fully-reset active state for a ticket. */
+export function pristineTicketState(ticketId, now, actor = null) {
+    return {
+        ticket_id: ticketId,
+        status: "planned",
+        owner: null,
+        current_step: null,
+        next_action: null,
+        blocked_by_json: "[]",
+        blocker_type: null,
+        blocker_notes: null,
+        first_blocked_at: null,
+        last_checked_at: null,
+        last_worked_at: null,
+        completed_at: null,
+        attempt_count: 0,
+        last_error: null,
+        evidence: null,
+        validation_result: null,
+        validation_commands: null,
+        validation_notes: null,
+        updated_at: now,
+        updated_by: actor,
+    };
+}
 const INIT_SQL = `
 PRAGMA foreign_keys = ON;
 
@@ -105,6 +131,38 @@ CREATE TABLE IF NOT EXISTS operation_receipts (
   payload_json TEXT NOT NULL DEFAULT '{}'
 );
 
+CREATE TABLE IF NOT EXISTS ticket_groups (
+  sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+  origin TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  legacy INTEGER NOT NULL DEFAULT 0,
+  operation_id TEXT NOT NULL UNIQUE
+);
+
+CREATE TABLE IF NOT EXISTS ticket_group_members (
+  group_sequence INTEGER NOT NULL REFERENCES ticket_groups(sequence) ON DELETE RESTRICT,
+  ticket_id TEXT NOT NULL UNIQUE,
+  position INTEGER NOT NULL,
+  snapshot_json TEXT NOT NULL,
+  snapshot_digest TEXT NOT NULL,
+  snapshot_validated_at TEXT NOT NULL,
+  PRIMARY KEY(group_sequence, ticket_id),
+  UNIQUE(group_sequence, position),
+  CHECK(position >= 1)
+);
+
+CREATE TABLE IF NOT EXISTS ticket_group_receipts (
+  operation_id TEXT PRIMARY KEY,
+  group_sequence INTEGER NOT NULL UNIQUE REFERENCES ticket_groups(sequence) ON DELETE RESTRICT,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS ticket_group_sequence_ledger (
+  sequence INTEGER PRIMARY KEY,
+  operation_id TEXT NOT NULL UNIQUE,
+  allocated_at TEXT NOT NULL
+);
+
 CREATE INDEX IF NOT EXISTS idx_ticket_state_status ON ticket_state(status);
 CREATE INDEX IF NOT EXISTS idx_ticket_events_ticket_id ON ticket_events(ticket_id);
 CREATE INDEX IF NOT EXISTS idx_ticket_events_timestamp ON ticket_events(timestamp);
@@ -112,6 +170,7 @@ CREATE INDEX IF NOT EXISTS idx_validation_snapshots_timestamp ON validation_snap
 CREATE INDEX IF NOT EXISTS idx_future_work_disposition ON future_work(disposition);
 CREATE INDEX IF NOT EXISTS idx_review_recommendations_status ON review_recommendations(status);
 CREATE INDEX IF NOT EXISTS idx_operation_receipts_run ON operation_receipts(run_id);
+CREATE INDEX IF NOT EXISTS idx_ticket_group_members_group ON ticket_group_members(group_sequence, position);
 `;
 export class StateDb {
     db;
@@ -120,6 +179,8 @@ export class StateDb {
         this.db = new Database(dbPath);
         this.db.pragma("journal_mode = WAL");
         this.db.exec(INIT_SQL);
+        this.db.prepare(`INSERT OR IGNORE INTO ticket_group_sequence_ledger(sequence,operation_id,allocated_at)
+      SELECT sequence,operation_id,created_at FROM ticket_groups`).run();
         this.migrateObsoleteStatus();
     }
     migrateObsoleteStatus() {
@@ -160,30 +221,12 @@ export class StateDb {
             m.set(row.ticket_id, row);
         return m;
     }
+    deleteState(ticketId) {
+        this.db.prepare("DELETE FROM ticket_state WHERE ticket_id = ?").run(ticketId);
+    }
     upsertState(ticketId, patch, now) {
         const existing = this.getState(ticketId);
-        const base = existing ?? {
-            ticket_id: ticketId,
-            status: "planned",
-            owner: null,
-            current_step: null,
-            next_action: null,
-            blocked_by_json: "[]",
-            blocker_type: null,
-            blocker_notes: null,
-            first_blocked_at: null,
-            last_checked_at: null,
-            last_worked_at: null,
-            completed_at: null,
-            attempt_count: 0,
-            last_error: null,
-            evidence: null,
-            validation_result: null,
-            validation_commands: null,
-            validation_notes: null,
-            updated_at: now,
-            updated_by: null,
-        };
+        const base = existing ?? pristineTicketState(ticketId, now);
         const merged = { ...base, ...patch, ticket_id: ticketId, updated_at: now };
         if (existing) {
             this.db.prepare(`
@@ -218,7 +261,7 @@ export class StateDb {
     }
     // ── ticket_events ─────────────────────────────────────────────────────────
     insertEvent(event) {
-        this.db.prepare(`
+        const result = this.db.prepare(`
       INSERT INTO ticket_events (
         timestamp,actor,ticket_id,event_type,old_status,new_status,
         summary,validation,evidence,payload_json
@@ -227,12 +270,23 @@ export class StateDb {
         @summary,@validation,@evidence,@payload_json
       )
     `).run(event);
+        return Number(result.lastInsertRowid);
+    }
+    deleteEvents(ids) {
+        const remove = this.db.prepare("DELETE FROM ticket_events WHERE id = ?");
+        for (const id of ids)
+            remove.run(id);
     }
     getRecentEvents(limit) {
         return this.db
             .prepare("SELECT * FROM ticket_events ORDER BY timestamp DESC, id DESC LIMIT ?")
             .all(limit);
     }
+    getTicketEvents(ticketId) {
+        return this.db
+            .prepare("SELECT * FROM ticket_events WHERE ticket_id = ? ORDER BY timestamp, id")
+            .all(ticketId);
+    }
     // ── validation_snapshots ──────────────────────────────────────────────────
     insertValidationSnapshot(snap) {
         this.db.prepare(`
@@ -245,6 +299,16 @@ export class StateDb {
             .prepare("SELECT * FROM validation_snapshots ORDER BY timestamp DESC, id DESC LIMIT 1")
             .get();
     }
+    getValidationSnapshots(scope) {
+        if (scope !== undefined) {
+            return this.db
+                .prepare("SELECT * FROM validation_snapshots WHERE scope = ? ORDER BY timestamp, id")
+                .all(scope);
+        }
+        return this.db
+            .prepare("SELECT * FROM validation_snapshots ORDER BY timestamp, id")
+            .all();
+    }
     // ── future_work ───────────────────────────────────────────────────────────
     insertFutureWork(item) {
         const r = this.db.prepare(`
@@ -287,6 +351,9 @@ export class StateDb {
         updated_at=excluded.updated_at
     `).run(row);
     }
+    deleteRecentCompleted(ticketId) {
+        this.db.prepare("DELETE FROM recent_completed_context WHERE ticket_id = ?").run(ticketId);
+    }
     // ── archive_index ─────────────────────────────────────────────────────────
     getArchiveIndex() {
         return this.db
@@ -338,8 +405,179 @@ export class StateDb {
     `).run(receipt);
         return result.changes === 1;
     }
+    // ── immutable ticket creation groups ─────────────────────────────────────
+    createTicketGroup(input) {
+        const existing = this.getTicketGroupByOperation(input.operationId);
+        if (existing) {
+            const requestedIds = input.members.map((member) => member.ticketId);
+            const existingIds = existing.members.map((member) => member.ticketId);
+            if (existing.origin !== input.origin || JSON.stringify(existingIds) !== JSON.stringify(requestedIds))
+                throw new Error(`ticket group operation ${input.operationId} was retried with different immutable membership`);
+            return existing;
+        }
+        if (!input.operationId.trim())
+            throw new Error("ticket group operation ID must not be empty");
+        if (input.members.length === 0)
+            throw new Error("ticket creation updates/no-ops must not create an empty group");
+        const ids = input.members.map((member) => member.ticketId);
+        if (new Set(ids).size !== ids.length)
+            throw new Error("ticket group members must be unique");
+        const createdAt = input.createdAt ?? new Date().toISOString();
+        return this.transaction(() => {
+            const result = this.db.prepare("INSERT INTO ticket_groups(origin,created_at,legacy,operation_id) VALUES(?,?,?,?)")
+                .run(input.origin, createdAt, input.legacy ? 1 : 0, input.operationId);
+            const sequence = Number(result.lastInsertRowid);
+            this.db.prepare("INSERT INTO ticket_group_sequence_ledger(sequence,operation_id,allocated_at) VALUES(?,?,?)").run(sequence, input.operationId, createdAt);
+            const insert = this.db.prepare(`INSERT INTO ticket_group_members(group_sequence,ticket_id,position,snapshot_json,snapshot_digest,snapshot_validated_at)
+        VALUES(?,?,?,?,?,?)`);
+            input.members.forEach((member, index) => {
+                const snapshot = makeDefinitionSnapshot(member.ticketId, member.definition, member.validatedAt ?? createdAt);
+                insert.run(sequence, member.ticketId, index + 1, JSON.stringify(snapshot.definition), snapshot.digest, snapshot.validatedAt);
+                // The creation receipt, immutable membership, recoverable definition,
+                // and initial active state are one SQLite publication. Existing state
+                // is preserved on replay or when importing an externally completed
+                // ticket.
+                if (!this.getState(member.ticketId)) {
+                    this.upsertState(member.ticketId, pristineTicketState(member.ticketId, createdAt, "rafi ticket publication"), createdAt);
+                }
+            });
+            this.db.prepare("INSERT INTO ticket_group_receipts(operation_id,group_sequence,created_at) VALUES(?,?,?)").run(input.operationId, sequence, createdAt);
+            return this.getTicketGroupBySequence(sequence);
+        });
+    }
+    /** Update only the recoverable definition; membership and order never change. */
+    updateTicketDefinitionSnapshot(ticketId, definition, validatedAt = new Date().toISOString()) {
+        const snapshot = makeDefinitionSnapshot(ticketId, definition, validatedAt);
+        const result = this.db.prepare(`UPDATE ticket_group_members SET snapshot_json=?,snapshot_digest=?,snapshot_validated_at=? WHERE ticket_id=?`)
+            .run(JSON.stringify(snapshot.definition), snapshot.digest, snapshot.validatedAt, ticketId);
+        if (result.changes !== 1)
+            throw new Error(`ticket ${ticketId} has no creation-group membership`);
+        return snapshot;
+    }
+    getTicketGroupByOperation(operationId) {
+        const row = this.db.prepare("SELECT sequence FROM ticket_groups WHERE operation_id=?").get(operationId);
+        return row ? this.getTicketGroupBySequence(row.sequence) : undefined;
+    }
+    getTicketGroup(groupId) {
+        const match = /^TG-([1-9]\d*)$/.exec(groupId);
+        return match ? this.getTicketGroupBySequence(Number(match[1])) : undefined;
+    }
+    getTicketGroupForTicket(ticketId) {
+        const row = this.db.prepare("SELECT group_sequence AS sequence FROM ticket_group_members WHERE ticket_id=?").get(ticketId);
+        return row ? this.getTicketGroupBySequence(row.sequence) : undefined;
+    }
+    listTicketGroups() {
+        const rows = this.db.prepare("SELECT sequence FROM ticket_groups ORDER BY sequence DESC").all();
+        return rows.map((row) => this.getTicketGroupBySequence(row.sequence));
+    }
+    /** One-time migration for repositories whose complete ticket set predates groups. */
+    ensureSyntheticLegacyGroup(definitions, now = new Date()) {
+        if (definitions.length === 0 || this.listTicketGroups().length > 0)
+            return undefined;
+        return this.createTicketGroup({
+            origin: "legacy",
+            operationId: "ticket-groups:synthetic-legacy:v1",
+            legacy: true,
+            createdAt: now.toISOString(),
+            members: definitions.map((definition) => ({ ticketId: definition.id, definition, validatedAt: now.toISOString() })),
+        });
+    }
+    ungroupedTicketIds(ticketIds) {
+        const grouped = new Set(this.db.prepare("SELECT ticket_id FROM ticket_group_members").all().map((row) => row.ticket_id));
+        return ticketIds.filter((ticketId) => !grouped.has(ticketId));
+    }
+    repairTicketGroups(definitions, operationId, now = new Date()) {
+        const ungrouped = new Set(this.ungroupedTicketIds(definitions.map((definition) => definition.id)));
+        if (ungrouped.size === 0)
+            return undefined;
+        return this.createTicketGroup({
+            origin: "repair", operationId, createdAt: now.toISOString(),
+            members: definitions.filter((definition) => ungrouped.has(definition.id)).map((definition) => ({ ticketId: definition.id, definition })),
+        });
+    }
+    validateTicketGroups(knownTicketIds = []) {
+        const issues = [];
+        const groups = this.listTicketGroups();
+        const known = new Set(knownTicketIds);
+        for (const group of groups) {
+            if (group.members.length === 0)
+                issues.push({ code: "empty-group", groupId: group.id, message: `${group.id} has no members` });
+            for (const member of group.members) {
+                if (known.size > 0 && !known.has(member.ticketId))
+                    issues.push({ code: "unknown-member", groupId: group.id, ticketId: member.ticketId, message: `${group.id} references unknown ticket ${member.ticketId}` });
+                if (definitionDigest(member.snapshot.definition) !== member.snapshot.digest)
+                    issues.push({ code: "snapshot-corruption", groupId: group.id, ticketId: member.ticketId, message: `${group.id} snapshot for ${member.ticketId} does not match its digest` });
+            }
+        }
+        for (const ticketId of known)
+            if (!this.getTicketGroupForTicket(ticketId))
+                issues.push({ code: "missing-membership", ticketId, message: `ticket ${ticketId} has no creation-group membership` });
+        const duplicates = this.db.prepare("SELECT ticket_id,COUNT(*) AS count FROM ticket_group_members GROUP BY ticket_id HAVING COUNT(*)<>1").all();
+        for (const row of duplicates)
+            issues.push({ code: "multiple-membership", ticketId: row.ticket_id, message: `ticket ${row.ticket_id} belongs to ${row.count} creation groups` });
+        const maximum = groups.reduce((value, group) => Math.max(value, group.sequence), 0);
+        const sequence = this.db.prepare("SELECT seq FROM sqlite_sequence WHERE name='ticket_groups'").get();
+        if (maximum > 0 && (!sequence || sequence.seq < maximum))
+            issues.push({ code: "sequence-corruption", message: `ticket group sequence is ${sequence?.seq ?? "missing"}, below allocated ${maximum}` });
+        const missingLedger = this.db.prepare("SELECT sequence FROM ticket_groups WHERE sequence NOT IN (SELECT sequence FROM ticket_group_sequence_ledger)").all();
+        for (const row of missingLedger)
+            issues.push({ code: "sequence-corruption", groupId: `TG-${row.sequence}`, message: `TG-${row.sequence} has no immutable allocation ledger entry` });
+        const reused = this.db.prepare(`SELECT g.sequence FROM ticket_groups g JOIN ticket_group_sequence_ledger l ON l.sequence=g.sequence WHERE g.operation_id<>l.operation_id`).all();
+        for (const row of reused)
+            issues.push({ code: "reused-id", groupId: `TG-${row.sequence}`, message: `TG-${row.sequence} was reused for a different creation operation` });
+        const deletedAllocations = this.db.prepare("SELECT sequence FROM ticket_group_sequence_ledger WHERE sequence NOT IN (SELECT sequence FROM ticket_groups)").all();
+        for (const row of deletedAllocations)
+            issues.push({ code: "sequence-corruption", groupId: `TG-${row.sequence}`, message: `allocated TG-${row.sequence} is missing; group IDs must never be deleted or reused` });
+        const orphanReceipts = this.db.prepare("SELECT operation_id FROM ticket_group_receipts WHERE group_sequence NOT IN (SELECT sequence FROM ticket_groups)").all();
+        for (const row of orphanReceipts)
+            issues.push({ code: "receipt-without-group", message: `creation receipt ${row.operation_id} has no group` });
+        return issues;
+    }
+    getTicketGroupBySequence(sequence) {
+        const row = this.db.prepare("SELECT * FROM ticket_groups WHERE sequence=?").get(sequence);
+        if (!row)
+            return undefined;
+        const members = this.db.prepare("SELECT * FROM ticket_group_members WHERE group_sequence=? ORDER BY position").all(sequence);
+        return {
+            id: `TG-${row.sequence}`,
+            sequence: row.sequence,
+            origin: row.origin,
+            createdAt: row.created_at,
+            legacy: Boolean(row.legacy),
+            operationId: row.operation_id,
+            members: members.map((member) => ({
+                groupId: `TG-${row.sequence}`,
+                ticketId: member.ticket_id,
+                position: member.position,
+                snapshot: { version: 1, ticketId: member.ticket_id, definition: parseSnapshot(member.snapshot_json), digest: member.snapshot_digest, validatedAt: member.snapshot_validated_at },
+            })),
+        };
+    }
     // ── transactions ──────────────────────────────────────────────────────────
     transaction(fn) {
         return this.db.transaction(fn)();
     }
 }
+function makeDefinitionSnapshot(ticketId, definition, validatedAt) {
+    const cloned = JSON.parse(JSON.stringify(definition));
+    if (cloned && typeof cloned === "object" && !Array.isArray(cloned)) {
+        const definitionId = cloned.id;
+        if (definitionId !== undefined && definitionId !== ticketId)
+            throw new Error(`ticket definition snapshot ID ${String(definitionId)} does not match group member ${ticketId}`);
+    }
+    return { version: 1, ticketId, definition: cloned, digest: definitionDigest(cloned), validatedAt };
+}
+function definitionDigest(value) { return createHash("sha256").update(stableJson(value)).digest("hex"); }
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(",")}}`;
+    return JSON.stringify(value) ?? "null";
+}
+function parseSnapshot(value) { try {
+    return JSON.parse(value);
+}
+catch {
+    return { __rafi_corrupt_snapshot: true, raw: value };
+} }

package/dist/tickets/ticketLoader.js

@@ -1,4 +1,5 @@
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { readFileSync, renameSync, writeFileSync, existsSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { parse, stringify } from "yaml";
 import { Ajv } from "ajv";
 import { TICKET_JSON_SCHEMA } from "./ticketSchema.js";
@@ -13,7 +14,9 @@ export function loadTickets(ticketsPath) {
     return raw.tickets;
 }
 export function saveTickets(ticketsPath, tickets) {
-    writeFileSync(ticketsPath, stringify({ tickets }, { lineWidth: 120 }), "utf8");
+    const temporary = `${ticketsPath}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, stringify({ tickets }, { lineWidth: 120 }), "utf8");
+    renameSync(temporary, ticketsPath);
 }
 export function validateTicketDefs(tickets) {
     const errors = [];