agentwrangler 0.1.1-next.fbbbe7f → 0.1.1-next.fbffef0

package/dist/daemon/lifecycle.js

@@ -0,0 +1,122 @@
+/**
+ * src/daemon/lifecycle.ts — daemon timer registration and graceful shutdown.
+ *
+ * Extracted from daemon/index.ts (PERF5) so the boot-kick guard, the three
+ * daemon-owned intervals (calibration / outcomes / weekly reports), and the
+ * shutdown ordering are deterministically unit-testable without booting the
+ * daemon. The signal handlers in index.ts stay thin: both call shutdown().
+ *
+ * Shutdown contract:
+ *   - idempotent — a second signal is a no-op
+ *   - clears the boot-fallback timeout so a shutdown during the 3 s window
+ *     cannot start a scan afterwards
+ *   - a pending boot-kick setImmediate checks the flag and never starts the
+ *     scan after shutdown
+ *   - when shutdown lands while the boot scan is still in flight, the timers
+ *     are never armed and the tail handle is stopped as soon as the scan
+ *     resolves (previously both leaked past db.close())
+ *   - stopping the tail does NOT drain a suspended tail pass; the Ingestor's
+ *     stopped flag makes it quit at the next file boundary (its contract)
+ */
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+export function createDaemonLifecycle(deps) {
+    const error = deps.error ?? ((msg) => console.error(msg));
+    const calibrationIntervalMs = deps.calibrationIntervalMs ?? WEEK_MS;
+    const outcomesIntervalMs = deps.outcomesIntervalMs ?? 10 * 60 * 1000;
+    const reportsIntervalMs = deps.reportsIntervalMs ?? WEEK_MS;
+    const bootFallbackMs = deps.bootFallbackMs ?? 3000;
+    let scanKicked = false;
+    let shutDown = false;
+    let handle = null;
+    let calibrationTimer = null;
+    let outcomesTimer = null;
+    let reportsTimer = null;
+    let fallbackTimer = null;
+    let reportsRunning = false;
+    function armTimers() {
+        calibrationTimer = setInterval(() => {
+            try {
+                deps.calibrationTick();
+            }
+            catch (e) {
+                error(`Bytes-per-token calibration poll failed (non-fatal): ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }, calibrationIntervalMs);
+        outcomesTimer = setInterval(() => {
+            try {
+                deps.outcomesTick();
+            }
+            catch (e) {
+                error(`Outcomes poll failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }, outcomesIntervalMs);
+        reportsTimer = setInterval(() => {
+            if (reportsRunning)
+                return;
+            reportsRunning = true;
+            Promise.resolve()
+                .then(() => deps.reportsTick())
+                .catch((e) => {
+                error(`Weekly report poll failed: ${e instanceof Error ? e.message : String(e)}`);
+            })
+                .finally(() => {
+                reportsRunning = false;
+            });
+        }, reportsIntervalMs);
+    }
+    function kickBootScan() {
+        if (scanKicked || shutDown)
+            return;
+        scanKicked = true;
+        // setImmediate so the triggering HTTP response flushes before boot work
+        // starts. The scan itself also yields between bounded batches.
+        setImmediate(() => {
+            if (shutDown)
+                return;
+            deps
+                .bootScan()
+                .then((h) => {
+                handle = h;
+                if (shutDown) {
+                    // Shutdown landed mid-scan: never arm timers; stop the tail now.
+                    handle?.stop();
+                    handle = null;
+                    return;
+                }
+                armTimers();
+            })
+                .catch((e) => {
+                error(`Boot scan failed: ${e instanceof Error ? e.message : String(e)}`);
+            });
+        });
+    }
+    function shutdown() {
+        if (shutDown)
+            return;
+        shutDown = true;
+        if (fallbackTimer !== null)
+            clearTimeout(fallbackTimer);
+        handle?.stop();
+        handle = null;
+        if (calibrationTimer !== null)
+            clearInterval(calibrationTimer);
+        if (outcomesTimer !== null)
+            clearInterval(outcomesTimer);
+        if (reportsTimer !== null)
+            clearInterval(reportsTimer);
+        deps.closeServer(() => {
+            deps.closeDb();
+            deps.onClosed?.();
+        });
+    }
+    return {
+        kickBootScan,
+        armBootFallback() {
+            fallbackTimer = setTimeout(kickBootScan, bootFallbackMs);
+        },
+        shutdown,
+        get isShutDown() {
+            return shutDown;
+        },
+    };
+}

package/dist/daemon/router.js

@@ -1,11 +1,4 @@
-/**
- * src/daemon/router.ts — minimal API route dispatcher.
- *
- * Routes /api/* requests to the LocalQueryAPI stubs.
- * WP2 and WP4 replace the stub calls with real implementations.
- *
- * All responses are JSON with no permissive CORS headers.
- */
+import { getReportedWork } from "../query/api/reported-work.js";
 import { getPractices } from "../detector/practice-registry.js";
 import { getOAuthStatus } from "../oauth/credentials.js";
 import { getGithubTokenStatus } from "../outcomes/github/credential.js";
@@ -14,8 +7,10 @@ import { endSession, getAgentsLiveness } from "../query/api/agents-liveness.js";
 import { getBurnStatus } from "../query/api/burn-status.js";
 import { getCostPerSuccess } from "../query/api/cost-per-success.js";
 import { getDeliveryMetrics } from "../query/api/delivery.js";
+import { EffectRequestError, listEffectEvidence, mutateEffectCycle, trackCompletedChange, } from "../query/api/effect-service.js";
 import { getClosureProxy } from "../query/api/effectiveness.js";
 import { getEfficiencyHeadroom } from "../query/api/efficiency-headroom.js";
+import { getEsfObservations, getSessionEsfObservations } from "../query/api/esf-observations.js";
 import { getHeadroomTrend } from "../query/api/headroom-trend.js";
 import { getHotSessions } from "../query/api/hot-sessions.js";
 import { adoptRecommendation, calibrateBytesPerToken, calibrateLimit, confirmApplyJob, dismissRecommendation, getApplyJob, getContextBudget, getContextComposition, getGlobalOverview, getHookConfig, getIdleSessions, getLinkageRate, getLoopGuard, getSession, getSessionDrivers, getSettings, getSuccessRate, getTurnTimeline, getWorkspaceOutcomeDetail, installHookRoute, listLedger, listLiveSessions, listRecommendations, listSessions, listWorkspaceOutcomes, listWorkspaces, openTerminalForRec, resetDatabase, rollbackApplyJob, startApplyJob, uninstallHookRoute, updateHookConfig, updateSettings, } from "../query/api/index.js";
@@ -25,6 +20,7 @@ import { getSelfChurn } from "../query/api/self-churn.js";
 import { getSessionSpendPercentile, getWeeklySelfPercentile, } from "../query/api/self-percentiles.js";
 import { getFlavorDecomposition } from "../query/api/spend-flavor.js";
 import { getCacheWriteTrend, getTrends } from "../query/api/trends.js";
+import { WorkRecordError, attachWorkRecordContextRoute, attachWorkRecordSessionRoute, closeoutWorkRecordRoute, createWorkRecordRoute, deleteWorkRecordRoute, detachWorkRecordContextRoute, detachWorkRecordSessionRoute, editWorkRecordRoute, getWorkAllocation, getWorkAllocationClaimKinds, getWorkRecord, issueWorkRecordId, listWorkRecords, recomputeWorkAllocationRoute, setWorkRecordArchivedRoute, workRecordResponse, } from "../query/api/work-records.js";
 import { getSettingsData } from "../query/settings-store.js";
 import { getScanStatus, isReady } from "./readiness.js";
 function sendJson(res, status, body) {
@@ -35,10 +31,19 @@ function sendJson(res, status, body) {
     });
     res.end(payload);
 }
-function readBody(req) {
+function readBody(req, maxBytes) {
     return new Promise((resolve, reject) => {
         const chunks = [];
-        req.on("data", (chunk) => chunks.push(chunk));
+        let size = 0;
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (maxBytes !== undefined && size > maxBytes) {
+                reject(new EffectRequestError(400, "Request body is too large."));
+                req.resume();
+                return;
+            }
+            chunks.push(chunk);
+        });
         req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
         req.on("error", reject);
     });
@@ -124,10 +129,281 @@ function jobRoute(pathname) {
     const action = m[2] === "confirm" || m[2] === "rollback" ? m[2] : "get";
     return { jobId: decodeURIComponent(m[1]), action };
 }
+function workRecordId(pathname) {
+    const match = pathname.match(/^\/api\/work-records\/([^/]+)$/);
+    return match?.[1] === undefined ? null : decodeURIComponent(match[1]);
+}
+function workRecordAction(pathname) {
+    const match = pathname.match(/^\/api\/work-records\/([^/]+)\/(edit|closeout|archive|reopen|sessions|contexts|delete)(?:\/([^/]+)\/detach)?$/);
+    if (match?.[1] === undefined || match[2] === undefined)
+        return null;
+    const result = { recordId: decodeURIComponent(match[1]), action: match[2] };
+    return match[3] === undefined ? result : { ...result, relatedId: decodeURIComponent(match[3]) };
+}
+function workRecordBody(raw, recordId, related) {
+    let body;
+    try {
+        body = JSON.parse(raw);
+    }
+    catch {
+        throw new WorkRecordError(400, "INVALID_REQUEST", "Invalid JSON body");
+    }
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        throw new WorkRecordError(400, "INVALID_REQUEST", "request body must be an object");
+    }
+    const result = { ...body };
+    if (recordId !== undefined) {
+        if (result.work_record_id !== undefined && result.work_record_id !== recordId) {
+            throw new WorkRecordError(400, "INVALID_REQUEST", "work_record_id must match the route");
+        }
+        result.work_record_id = recordId;
+    }
+    if (related !== undefined) {
+        if (result[related.key] !== undefined && result[related.key] !== related.value) {
+            throw new WorkRecordError(400, "INVALID_REQUEST", `${related.key} must match the route`);
+        }
+        result[related.key] = related.value;
+    }
+    return result;
+}
+function sendWorkRecordError(res, error) {
+    if (error instanceof EffectRequestError) {
+        sendJson(res, error.status, { error: error.message, code: "INVALID_REQUEST" });
+        return;
+    }
+    if (error instanceof WorkRecordError) {
+        sendJson(res, error.status, { error: error.message, code: error.code });
+        return;
+    }
+    sendJson(res, 500, { error: "Internal error" });
+}
 export function handleApiRequest(_db, req, res, method, url) {
     // Strip query string for routing.
     const pathname = url.split("?")[0] ?? url;
     try {
+        if (method === "GET" && pathname === "/api/work-records/summary") {
+            const params = new URLSearchParams(url.split("?")[1] ?? "");
+            sendJson(res, 200, getReportedWork(_db, params.get("workspace_id") || null));
+            return;
+        }
+        // GET /api/esf/observations — complete selected-turn accounting cohort.
+        if (method === "GET" && pathname === "/api/esf/observations") {
+            const params = new URLSearchParams(url.split("?")[1] ?? "");
+            const window = resolveWindow(parseWindowFilter(url));
+            if (Date.parse(window.from) >= Date.parse(window.to)) {
+                sendJson(res, 400, { error: "from must precede to" });
+                return;
+            }
+            sendJson(res, 200, getEsfObservations(_db, {
+                workspaceId: params.get("workspace_id") || null,
+                ...window,
+            }));
+            return;
+        }
+        // Full-session aggregate: never derive this from a paginated timeline.
+        const sessionObservationId = pathname.match(/^\/api\/esf\/session-observations\/([^/]+)$/)?.[1];
+        if (method === "GET" && sessionObservationId !== undefined) {
+            const evidence = getSessionEsfObservations(_db, decodeURIComponent(sessionObservationId));
+            sendJson(res, evidence.data === null ? 404 : 200, evidence);
+            return;
+        }
+        // GET /api/esf/effects — independently keyset-paged versioned and legacy evidence.
+        if (method === "GET" && pathname === "/api/esf/effects") {
+            const params = new URLSearchParams(url.split("?")[1] ?? "");
+            const workspaceId = params.get("workspace_id");
+            sendJson(res, 200, listEffectEvidence(_db, workspaceId, params.get("rec_id") ?? undefined, params.get("limit") ?? undefined, params.get("cycle_cursor") ?? undefined, params.get("legacy_cursor") ?? undefined));
+            return;
+        }
+        const effectAction = pathname.match(/^\/api\/esf\/effects\/(track|stop|close|rollback|attest-rollback)$/)?.[1];
+        if (method === "POST" && effectAction !== undefined) {
+            readBody(req, 4096)
+                .then((raw) => {
+                let body;
+                try {
+                    body = JSON.parse(raw);
+                }
+                catch {
+                    sendJson(res, 400, { error: "Invalid JSON body." });
+                    return;
+                }
+                try {
+                    const result = effectAction === "track"
+                        ? trackCompletedChange(_db, body)
+                        : mutateEffectCycle(_db, effectAction, body);
+                    sendJson(res, 200, result);
+                }
+                catch (error) {
+                    const status = error instanceof EffectRequestError ? error.status : 409;
+                    sendJson(res, status, {
+                        error: error instanceof EffectRequestError
+                            ? error.message
+                            : "Effect request conflicts with the current cycle.",
+                    });
+                }
+            })
+                .catch((error) => sendJson(res, error instanceof EffectRequestError ? error.status : 500, {
+                error: error instanceof EffectRequestError
+                    ? error.message
+                    : "Internal error reading request body",
+            }));
+            return;
+        }
+        // ESF3 work records are local-only, structured records.  The HTTP token gate
+        // in http.ts covers every mutation and ID issuance route below.
+        if (method === "GET" && pathname === "/api/work-records") {
+            const params = new URLSearchParams(url.split("?")[1] ?? "");
+            const workspaceId = params.get("workspace_id");
+            const includeArchived = params.get("include_archived");
+            if (workspaceId === null ||
+                workspaceId.length === 0 ||
+                (includeArchived !== null && includeArchived !== "true" && includeArchived !== "false")) {
+                sendJson(res, 400, { error: "workspace_id and include_archived are invalid" });
+                return;
+            }
+            const records = listWorkRecords(_db, workspaceId, includeArchived === "true");
+            sendJson(res, 200, workRecordResponse(records, { n: records.length, workspaceId }));
+            return;
+        }
+        if (method === "GET" && pathname.startsWith("/api/work-records/allocations/")) {
+            const allocationId = pathname.slice("/api/work-records/allocations/".length);
+            if (allocationId.length === 0 || allocationId.includes("/")) {
+                sendJson(res, 404, { error: "Not found" });
+                return;
+            }
+            try {
+                const allocation = getWorkAllocation(_db, decodeURIComponent(allocationId));
+                sendJson(res, 200, workRecordResponse(allocation, {
+                    n: allocation.eligible_session_count,
+                    workspaceId: allocation.workspace_id,
+                    claimKind: "EXPERIMENTAL",
+                    meta: {
+                        window: { from: allocation.cohort_from, to: allocation.cohort_to },
+                        qualification: {
+                            provisional_excluded: true,
+                            unpriced_turns: allocation.unpriced_turn_count,
+                            claim_kinds_count: getWorkAllocationClaimKinds(_db, allocation.allocation_revision_id),
+                            note: "Frozen ESF3 allocation; unpriced turns are not zero cost.",
+                        },
+                    },
+                }));
+            }
+            catch (error) {
+                sendWorkRecordError(res, error);
+            }
+            return;
+        }
+        const recordId = workRecordId(pathname);
+        if (method === "GET" && recordId !== null) {
+            try {
+                const record = getWorkRecord(_db, recordId);
+                sendJson(res, 200, workRecordResponse(record, { workspaceId: record.workspace_id }));
+            }
+            catch (error) {
+                sendWorkRecordError(res, error);
+            }
+            return;
+        }
+        if (method === "POST" && pathname === "/api/work-records/ids") {
+            readBody(req, 1024)
+                .then((raw) => {
+                try {
+                    sendJson(res, 200, workRecordResponse(issueWorkRecordId(_db, workRecordBody(raw))));
+                }
+                catch (error) {
+                    sendWorkRecordError(res, error);
+                }
+            })
+                .catch((error) => sendWorkRecordError(res, error));
+            return;
+        }
+        if (method === "POST" && pathname === "/api/work-records") {
+            readBody(req, 4096)
+                .then((raw) => {
+                try {
+                    const result = createWorkRecordRoute(_db, workRecordBody(raw));
+                    sendJson(res, 200, workRecordResponse(result, { workspaceId: result.record.workspace_id }));
+                }
+                catch (error) {
+                    sendWorkRecordError(res, error);
+                }
+            })
+                .catch((error) => sendWorkRecordError(res, error));
+            return;
+        }
+        if (method === "POST" && pathname === "/api/work-records/allocations/recompute") {
+            readBody(req, 4096)
+                .then((raw) => {
+                try {
+                    const result = recomputeWorkAllocationRoute(_db, workRecordBody(raw));
+                    sendJson(res, 200, workRecordResponse(result, {
+                        n: result.allocation.eligible_session_count,
+                        workspaceId: result.allocation.workspace_id,
+                        claimKind: "EXPERIMENTAL",
+                        meta: {
+                            window: {
+                                from: result.allocation.cohort_from,
+                                to: result.allocation.cohort_to,
+                            },
+                            qualification: {
+                                provisional_excluded: true,
+                                unpriced_turns: result.allocation.unpriced_turn_count,
+                                claim_kinds_count: getWorkAllocationClaimKinds(_db, result.allocation.allocation_revision_id),
+                                note: "Frozen ESF3 allocation; unpriced turns are not zero cost.",
+                            },
+                        },
+                    }));
+                }
+                catch (error) {
+                    sendWorkRecordError(res, error);
+                }
+            })
+                .catch((error) => sendWorkRecordError(res, error));
+            return;
+        }
+        const recordAction = workRecordAction(pathname);
+        if (recordAction !== null &&
+            ((method === "POST" && recordAction.action !== "delete") ||
+                (method === "DELETE" && recordAction.action === "delete"))) {
+            readBody(req, 4096)
+                .then((raw) => {
+                try {
+                    const related = recordAction.relatedId === undefined
+                        ? undefined
+                        : {
+                            key: recordAction.action === "contexts" ? "context_ref_id" : "session_id",
+                            value: recordAction.relatedId,
+                        };
+                    const body = workRecordBody(raw, recordAction.recordId, related);
+                    const result = recordAction.action === "edit"
+                        ? editWorkRecordRoute(_db, body)
+                        : recordAction.action === "closeout"
+                            ? closeoutWorkRecordRoute(_db, body)
+                            : recordAction.action === "archive"
+                                ? setWorkRecordArchivedRoute(_db, body, true)
+                                : recordAction.action === "reopen"
+                                    ? setWorkRecordArchivedRoute(_db, body, false)
+                                    : recordAction.action === "sessions" && recordAction.relatedId === undefined
+                                        ? attachWorkRecordSessionRoute(_db, body)
+                                        : recordAction.action === "sessions"
+                                            ? detachWorkRecordSessionRoute(_db, body)
+                                            : recordAction.action === "contexts" &&
+                                                recordAction.relatedId === undefined
+                                                ? attachWorkRecordContextRoute(_db, body)
+                                                : recordAction.action === "contexts"
+                                                    ? detachWorkRecordContextRoute(_db, body)
+                                                    : deleteWorkRecordRoute(_db, body);
+                    const workspaceId = "record" in result ? result.record.workspace_id : undefined;
+                    sendJson(res, 200, workspaceId === undefined
+                        ? workRecordResponse(result)
+                        : workRecordResponse(result, { workspaceId }));
+                }
+                catch (error) {
+                    sendWorkRecordError(res, error);
+                }
+            })
+                .catch((error) => sendWorkRecordError(res, error));
+            return;
+        }
         // GET /api/overview
         if (method === "GET" && pathname === "/api/overview") {
             sendJson(res, 200, getGlobalOverview(parseWindowFilter(url)));
@@ -264,7 +540,7 @@ export function handleApiRequest(_db, req, res, method, url) {
             sendJson(res, 200, getPractices(_db, { from, to }));
             return;
         }
-        // GET /api/efficiency-headroom (BM2 modeled savings vs trailing-window spend)
+        // GET /api/efficiency-headroom (individual weekly estimates; separate selected-window spend)
         if (method === "GET" && pathname === "/api/efficiency-headroom") {
             const { from, to } = resolveWindow(parseWindowFilter(url));
             sendJson(res, 200, getEfficiencyHeadroom(_db, { from, to }));
@@ -506,13 +782,15 @@ export function handleApiRequest(_db, req, res, method, url) {
                     sendJson(res, 400, { error: "Invalid JSON body" });
                     return;
                 }
-                const { rec_id } = body;
+                const { rec_id, completed_change } = body;
                 if (typeof rec_id !== "string" || rec_id.length === 0) {
                     sendJson(res, 400, { error: "rec_id is required" });
                     return;
                 }
                 try {
-                    sendJson(res, 200, adoptRecommendation(rec_id));
+                    sendJson(res, 200, adoptRecommendation(rec_id, Date.now(), {
+                        completedChange: completed_change === true,
+                    }));
                 }
                 catch (e) {
                     sendJson(res, 400, { error: e instanceof Error ? e.message : "Adopt failed" });
@@ -749,7 +1027,11 @@ export function handleApiRequest(_db, req, res, method, url) {
         // 404 for everything else.
         sendJson(res, 404, { error: "Not found", path: pathname });
     }
-    catch {
+    catch (error) {
+        if (error instanceof EffectRequestError) {
+            sendJson(res, error.status, { error: error.message });
+            return;
+        }
         // Do not leak internal exception text into a cross-origin-readable 500 body
         // (GET routes are not CSRF-gated). Validation errors on POST routes still
         // return their message via the 400 paths above.

package/dist/db/migrations/018_effect_cycles.sql

@@ -0,0 +1,109 @@
+-- ESF2 versioned recommendation-effect cycles. Additive: legacy W4 rows remain untouched.
+
+CREATE TABLE effect_cycles (
+  cycle_id TEXT PRIMARY KEY,
+  rec_id TEXT NOT NULL REFERENCES recommendations(rec_id),
+  cycle_no INTEGER NOT NULL CHECK (cycle_no > 0),
+  contract_version TEXT NOT NULL,
+  query_definition_version TEXT NOT NULL,
+  detector_id TEXT NOT NULL,
+  metric_id TEXT NOT NULL,
+  method_version TEXT NOT NULL,
+  state TEXT NOT NULL CHECK (state IN
+    ('OPEN_SETTLING','OPEN_MEASURING','STOPPED','FINALIZED','UNSUPPORTED')),
+  created_at TEXT NOT NULL,
+  tracking_requested_at TEXT NOT NULL,
+  applied_at TEXT NOT NULL,
+  application_source TEXT NOT NULL CHECK (application_source IN
+    ('MACHINE_CONFIRMED','USER_ATTESTED')),
+  action_revision TEXT,
+  track_idempotency_key TEXT NOT NULL,
+  scope_json TEXT NOT NULL CHECK (json_valid(scope_json)),
+  cohort_json TEXT NOT NULL CHECK (json_valid(cohort_json)),
+  target_definition_json TEXT NOT NULL CHECK (json_valid(target_definition_json)),
+  guardrail_definitions_json TEXT NOT NULL CHECK (json_valid(guardrail_definitions_json)),
+  baseline_from TEXT NOT NULL,
+  baseline_to TEXT NOT NULL,
+  observation_from TEXT NOT NULL,
+  scheduled_observation_to TEXT NOT NULL,
+  observation_to TEXT,
+  baseline_evidence_json TEXT NOT NULL CHECK (json_valid(baseline_evidence_json)),
+  provisional_evidence_json TEXT CHECK (provisional_evidence_json IS NULL OR json_valid(provisional_evidence_json)),
+  final_evidence_json TEXT CHECK (final_evidence_json IS NULL OR json_valid(final_evidence_json)),
+  target_direction TEXT CHECK (target_direction IS NULL OR target_direction IN
+    ('IMPROVED','UNCHANGED','WORSENED','INSUFFICIENT_DATA')),
+  comparison_status TEXT CHECK (comparison_status IS NULL OR comparison_status IN
+    ('DESCRIPTIVE','COMPARABLE','CONFOUNDED')),
+  comparison_reasons_json TEXT CHECK (comparison_reasons_json IS NULL OR json_valid(comparison_reasons_json)),
+  terminal_at TEXT,
+  terminal_reason TEXT,
+  stop_idempotency_key TEXT,
+  stop_reason TEXT,
+  attribution_closed_at TEXT,
+  attribution_close_reason TEXT,
+  closure_idempotency_key TEXT,
+  finalizer_revision TEXT,
+  concurrent_change_json TEXT CHECK (concurrent_change_json IS NULL OR json_valid(concurrent_change_json)),
+  rollback_status TEXT CHECK (rollback_status IS NULL OR rollback_status IN
+    ('PENDING','SUCCEEDED','CONFLICT','FAILED','USER_ATTESTED','MANUAL','UNSUPPORTED')),
+  rollback_at TEXT,
+  rollback_attestation_source TEXT,
+  UNIQUE (rec_id, cycle_no),
+  UNIQUE (rec_id, track_idempotency_key)
+);
+
+CREATE UNIQUE INDEX idx_effect_cycles_one_open_rec
+  ON effect_cycles(rec_id)
+  WHERE state IN ('OPEN_SETTLING','OPEN_MEASURING');
+CREATE INDEX idx_effect_cycles_pass
+  ON effect_cycles(state, scheduled_observation_to, applied_at);
+CREATE INDEX idx_effect_cycles_rec
+  ON effect_cycles(rec_id, cycle_no DESC);
+CREATE INDEX idx_effect_cycles_overlap
+  ON effect_cycles(contract_version, query_definition_version, observation_from);
+
+CREATE TABLE effect_guardrail_results (
+  cycle_id TEXT NOT NULL REFERENCES effect_cycles(cycle_id) ON DELETE CASCADE,
+  guardrail_id TEXT NOT NULL,
+  method_version TEXT NOT NULL,
+  availability TEXT NOT NULL CHECK (availability IN ('SUPPORTED','UNSUPPORTED')),
+  unit TEXT NOT NULL,
+  before_value REAL,
+  after_value REAL,
+  before_denominator REAL,
+  after_denominator REAL,
+  before_eligible_n INTEGER,
+  after_eligible_n INTEGER,
+  direction TEXT NOT NULL CHECK (direction IN
+    ('IMPROVED','STABLE','ADVERSE','INSUFFICIENT_DATA')),
+  reason_codes_json TEXT NOT NULL CHECK (json_valid(reason_codes_json)),
+  evidence_json TEXT NOT NULL CHECK (json_valid(evidence_json)),
+  PRIMARY KEY (cycle_id, guardrail_id)
+);
+
+CREATE TABLE effect_rollback_operations (
+  operation_id TEXT PRIMARY KEY,
+  cycle_id TEXT NOT NULL REFERENCES effect_cycles(cycle_id) ON DELETE CASCADE,
+  idempotency_key TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN
+    ('PENDING','SUCCEEDED','CONFLICT','FAILED','USER_ATTESTED','MANUAL','UNSUPPORTED')),
+  requested_at TEXT NOT NULL,
+  completed_at TEXT,
+  inverse_kind TEXT NOT NULL,
+  expected_revision TEXT,
+  restoration_revision TEXT,
+  failure_class TEXT,
+  attestation_source TEXT,
+  actual_rollback_at TEXT,
+  UNIQUE (cycle_id, idempotency_key)
+);
+CREATE UNIQUE INDEX idx_effect_rollbacks_one_pending
+  ON effect_rollback_operations(cycle_id) WHERE status = 'PENDING';
+
+CREATE TABLE effect_mutation_keys (
+  cycle_id TEXT NOT NULL REFERENCES effect_cycles(cycle_id) ON DELETE CASCADE,
+  mutation_kind TEXT NOT NULL,
+  idempotency_key TEXT NOT NULL,
+  recorded_at TEXT NOT NULL,
+  PRIMARY KEY (cycle_id, mutation_kind, idempotency_key)
+);