agentwrangler 0.1.1-next.8be2eb0 → 0.1.1-next.bca85ea

package/dist/apply/jobs.js

@@ -302,7 +302,10 @@ function completeApplyPhase(db, job, rec, result, rt) {
     let runId = null;
     const completedAt = rt.now();
     try {
-        adoptRecommendation(job.rec_id, completedAt.getTime());
+        adoptRecommendation(job.rec_id, completedAt.getTime(), {
+            machineConfirmed: true,
+            actionRevision: job.job_id,
+        });
         runId = randomUUID();
         const evidencePackHash = createHash("sha256")
             .update(JSON.stringify(rec.evidence))
@@ -417,6 +420,9 @@ export function rollbackApplyJob(jobId) {
     if (row.status !== "APPLIED" && row.status !== "CONFIRMING") {
         throw new Error("job cannot be rolled back from this state");
     }
+    if (db.prepare("SELECT 1 FROM effect_cycles WHERE rec_id=? LIMIT 1").get(row.rec_id)) {
+        throw new Error("Whole-file backup rollback is not a supported effect inverse. Revert manually and attest the rollback in the effect ledger.");
+    }
     if (row.backup_path === null)
         throw new Error("no backup available");
     fs.copyFileSync(row.backup_path, row.file_ref);

package/dist/daemon/effect-pass.js

@@ -0,0 +1,24 @@
+import { runMeasurementPass } from "../detector/measurement.js";
+import { ESF_EFFECT_WRITER_ENABLED } from "../effects/gate.js";
+import { effectEngineForDb } from "../query/api/effect-service.js";
+const INTERVAL_MS = 60 * 60 * 1000;
+const lastPass = new WeakMap();
+/** Probe-clock scheduling; restarting can safely replay the bounded, idempotent engine pass. */
+export function runEffectMeasurementPass(db, now) {
+    if (!ESF_EFFECT_WRITER_ENABLED) {
+        runMeasurementPass(db, now);
+        return;
+    }
+    const previous = lastPass.get(db);
+    const current = now.getTime();
+    if (previous !== undefined && current >= previous && current - previous < INTERVAL_MS)
+        return;
+    lastPass.set(db, current);
+    try {
+        effectEngineForDb(db).runPass(now);
+    }
+    catch {
+        // Never expose source identities or DB contents in a background error.
+        console.warn("Effect measurement pass failed; retrying on the next scheduled pass.");
+    }
+}

package/dist/daemon/http.js

@@ -138,6 +138,8 @@ function requiresSessionToken(pathname) {
         return true;
     if (/^\/api\/recommendations\/jobs\/[^/]+\/(confirm|rollback)$/.test(pathname))
         return true;
+    if (/^\/api\/esf\/effects\/(track|stop|close|rollback|attest-rollback)$/.test(pathname))
+        return true;
     return false;
 }
 /**

package/dist/daemon/index.js

@@ -22,7 +22,6 @@ import { openDb } from "../db/open.js";
 import { configGet as bptConfigGet, calibrateBytesPerToken } from "../detector/calibration.js";
 import { runContextProbe } from "../detector/context-probe.js";
 import { runDetectors } from "../detector/index.js";
-import { runMeasurementPass } from "../detector/measurement.js";
 import { installHook, uninstallHook } from "../hook/install.js";
 import { collectSessionChurn } from "../ingest/churn-collector.js";
 import { runPostProbeHook, setPostIngestHook, setPostProbeHook } from "../ingest/detector-hook.js";
@@ -37,6 +36,7 @@ import { generateWeeklyReport } from "../query/api/reports.js";
 import { setQueryDb } from "../query/db-context.js";
 import { getSettingsData, setHealthInstance, setRuntimeResetHook, } from "../query/settings-store.js";
 import { loadConfig } from "./config.js";
+import { runEffectMeasurementPass } from "./effect-pass.js";
 import { createServer } from "./http.js";
 import { createOutcomesPassRunner } from "./outcomes-pass.js";
 import { setReady, setScanRoots, setScanState } from "./readiness.js";
@@ -107,6 +107,10 @@ if (isSmoke) {
         "review_findings",
         "recommendations",
         "recommendation_effects",
+        "effect_cycles",
+        "effect_guardrail_results",
+        "effect_rollback_operations",
+        "effect_mutation_keys",
         "apply_jobs",
         "analysis_runs",
         "ingest_quarantine",
@@ -150,18 +154,16 @@ function runProbePass(label) {
         const now = new Date();
         const { rows } = runContextProbe(db, now);
         console.log(`ContextProbe[${label}]: ${rows} row(s) upserted`);
-        // W4: measurement pass after each probe (best-effort; the seam never throws
-        // through, and runMeasurementPass itself is guarded/log-not-throw).
+        // Best-effort measurement after each probe, using the same observation clock.
         runPostProbeHook(db, now);
     }
     catch (e) {
         console.log(`ContextProbe[${label}]: skipped — ${e instanceof Error ? e.message : String(e)}`);
     }
 }
-// Wire the W4 Impact Ledger measurement pass onto the post-probe seam. The pass
-// receives the probe's clock (deterministic; NFR-107), is throttled internally.
+// Versioned measurement owns new cycles; W4 history stays read-only under the code gate.
 setPostProbeHook((probeDb, now) => {
-    runMeasurementPass(probeDb, now);
+    runEffectMeasurementPass(probeDb, now);
 });
 runProbePass("boot");
 // ── Outcomes bootstrap (WP5 — best-effort, never crash daemon) ────────────────

package/dist/daemon/router.js

@@ -14,6 +14,7 @@ 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 { getHeadroomTrend } from "../query/api/headroom-trend.js";
@@ -35,10 +36,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);
     });
@@ -128,6 +138,47 @@ export function handleApiRequest(_db, req, res, method, url) {
     // Strip query string for routing.
     const pathname = url.split("?")[0] ?? url;
     try {
+        // 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;
+        }
         // GET /api/overview
         if (method === "GET" && pathname === "/api/overview") {
             sendJson(res, 200, getGlobalOverview(parseWindowFilter(url)));
@@ -264,7 +315,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 +557,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 +802,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)
+);

package/dist/detector/context-history-retention.js

@@ -1,4 +1,6 @@
+import { createHash } from "node:crypto";
 import { performance } from "node:perf_hooks";
+import { cycleFromRow } from "../effects/store.js";
 import { GLOBAL_WORKSPACE_ID } from "./context-probe.js";
 import { isD1SourceBackedRecommendation, parseD1SourceIdentity } from "./d1-source-identity.js";
 import { AFTER_WINDOW_DAYS } from "./measurement.js";
@@ -78,10 +80,15 @@ function validateHistoryRows(db) {
     });
 }
 function readOpenEffects(db) {
+    const hasVersioned = db.prepare("SELECT 1 FROM sqlite_master WHERE name='effect_cycles'").get();
+    const versionedExclusion = hasVersioned
+        ? "AND NOT EXISTS (SELECT 1 FROM effect_cycles c WHERE c.rec_id=recommendations.rec_id)"
+        : "";
     const recs = db
         .prepare(`SELECT rec_id, detector_id, scope_workspace_id, evidence_json, target_metric, adopted_at
          FROM recommendations
         WHERE state IN ('ADOPTED', 'MEASURING')
+          ${versionedExclusion}
         ORDER BY rec_id ASC`)
         .all();
     const sourceBacked = recs.filter(isD1SourceBackedRecommendation);
@@ -140,6 +147,48 @@ function readOpenEffects(db) {
     }
     if (malformedN > 0)
         throw new RetentionPlanError("invalid_open_effect", malformedN);
+    if (hasVersioned) {
+        const rows = db
+            .prepare(`SELECT c.*,r.evidence_json,r.scope_workspace_id
+      FROM effect_cycles c JOIN recommendations r ON r.rec_id=c.rec_id
+      WHERE c.detector_id='D1' AND c.state IN ('OPEN_SETTLING','OPEN_MEASURING')`)
+            .all();
+        for (const row of rows) {
+            const cycle = cycleFromRow(row);
+            const identity = parseD1SourceIdentity(String(row.evidence_json));
+            const workspaceId = row.scope_workspace_id === null ? GLOBAL_WORKSPACE_ID : String(row.scope_workspace_id);
+            const beforeToMs = canonicalTimestamp(cycle.baselineTo);
+            const afterFromMs = canonicalTimestamp(cycle.observationFrom);
+            const afterToMs = canonicalTimestamp(cycle.scheduledObservationTo);
+            if (!identity ||
+                !COMPONENTS.has(identity.component) ||
+                !identity.fileRef ||
+                cycle.versionStatus !== "SUPPORTED" ||
+                beforeToMs === null ||
+                afterFromMs === null ||
+                afterToMs === null ||
+                beforeToMs !== afterFromMs ||
+                afterToMs < afterFromMs) {
+                throw new RetentionPlanError("invalid_open_effect", 1);
+            }
+            // Same opaque tuple encoding as the service; a moved/reassigned source is not reinterpreted.
+            const digest = createHash("sha256")
+                .update(JSON.stringify({
+                workspaceId,
+                component: identity.component,
+                fileRef: identity.fileRef,
+            }))
+                .digest("hex");
+            if (digest !== cycle.scope.sourceIdentity)
+                throw new RetentionPlanError("invalid_open_effect", 1);
+            effects.push({
+                sourceKey: sourceKey(workspaceId, identity.component, identity.fileRef),
+                beforeToMs,
+                afterFromMs,
+                afterToMs,
+            });
+        }
+    }
     return effects;
 }
 function emptySummary(mode, startedAt, failureClass, malformedOpenEffectN = 0) {

package/dist/detector/measurement.js

@@ -20,6 +20,7 @@
  *
  * Injected `now: Date` everywhere — never call new Date() in this module.
  */
+import { ESF_EFFECT_WRITER_ENABLED } from "../effects/gate.js";
 import { PREMIUM_MODEL_SQL } from "../ingest/pricing.js";
 import { GLOBAL_WORKSPACE_ID } from "./context-probe.js";
 import { isD1SourceBackedRecommendation, parseD1SourceIdentity } from "./d1-source-identity.js";
@@ -135,7 +136,8 @@ function handlerFor(rec) {
 }
 /** Warning-class recs (D5 / LIMIT / explicit NONE) skip the lifecycle entirely (design §2d). */
 export function isWarningClass(rec) {
-    return (rec.category === "LIMIT" ||
+    return (rec.detector_id === "D5" ||
+        rec.category === "LIMIT" ||
         rec.target_metric === "NONE" ||
         rec.target_metric === "forecast_margin");
 }
@@ -364,6 +366,9 @@ function closeMeasurement(db, rec, now, result) {
  */
 export function runMeasurementPass(db, now, opts) {
     const result = { to_measuring: 0, verdicts: 0, skipped: 0 };
+    // The versioned writer leaves every historical W4 row unchanged, including open rows.
+    if (ESF_EFFECT_WRITER_ENABLED)
+        return result;
     if (!tableExists(db, "context_inventory_history")) {
         console.warn("W4: context_inventory_history not available; measurement pass skipped");
         return result;
@@ -381,11 +386,16 @@ export function runMeasurementPass(db, now, opts) {
         }
     }
     try {
+        // A code-gate rollback must not let W4 take over an already-versioned recommendation.
+        const versionedExclusion = tableExists(db, "effect_cycles")
+            ? "AND NOT EXISTS (SELECT 1 FROM effect_cycles c WHERE c.rec_id=recommendations.rec_id)"
+            : "";
         const rows = db
             .prepare(`SELECT rec_id, detector_id, category, scope_workspace_id, evidence_json,
                 target_metric, state, adopted_at
            FROM recommendations
           WHERE state IN ('ADOPTED', 'MEASURING') AND adopted_at IS NOT NULL
+          ${versionedExclusion}
           ORDER BY adopted_at ASC, rec_id ASC`)
             .all();
         for (const rec of rows) {

package/dist/effects/api-contract.js

@@ -0,0 +1 @@
+export {};