@aexol/spectral 0.9.221 → 0.9.222

package/dist/extensions/logic-trace.js

@@ -0,0 +1,1098 @@
+/**
+ * Logic trace extension.
+ *
+ * Maintains EXACTLY ONE cloud-hosted file, `logic.aexol`, inside the Aexol
+ * Studio project the current directory is bound to (`.aexol/aexol.jsonc`).
+ * The file mirrors the project's business logic (types / enums / roles /
+ * workflows / agents) as a valid Aexol specification.
+ *
+ * Automatic refresh works the same way observational memory refreshes
+ * observations (see `../memory/hooks/observer-trigger.ts`):
+ *   - `turn_end` hook fires the refresh attempt,
+ *   - a token threshold gates how much new material must exist before a run,
+ *   - an in-flight singleton prevents concurrent runs,
+ *   - a passive flag (`PI_LOGIC_TRACE_PASSIVE`) disables it entirely.
+ *
+ * A `session_before_compact` hook additionally forces one flush attempt with
+ * the accumulated delta before the context is compacted away (mirroring the
+ * flush-before-compact semantics of `../memory/hooks/compaction-hook.ts`).
+ *
+ * Each refresh fetches the CURRENT remote `logic.aexol` and lets the model
+ * return the FULL updated spec (merge, never append-only) through a single
+ * `submit_logic_trace` tool call. Pushes are skipped when the model reports
+ * no change or when the content hash is unchanged (hashId).
+ *
+ * This is a SEPARATE mechanism from memory/observations — it only reuses
+ * generic helpers from `../memory/` and never writes any memory state.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { Type } from "../sdk/ai/index.js";
+import { agentLoop, uuidv7, } from "../sdk/agent-core/index.js";
+import { getAgentDir, } from "../sdk/coding-agent/index.js";
+import { readStudioBinding } from "../studio-binding.js";
+import { createAexolBackendClient, } from "./aexol-backend-client.js";
+import { createBackendRefineDraftRunner, } from "./logic-trace-backend-draft.js";
+// Re-used (read-only) helpers from the observational-memory package so the
+// recent-turn delta collection stays in lockstep with how the observer
+// serializes conversation tails. Nothing here modifies memory state.
+import { firstRawIdAfter, lastObservationCoverEndIdx, rawTailEntriesBetween, rawTokensSinceLastBound, } from "../memory/branch.js";
+import { serializeSourceAddressedBranchEntries } from "../memory/serialize.js";
+import { hashId } from "../memory/ids.js";
+import { AGENT_LOOP_MAX_TOKENS, boundedMaxTokens } from "../memory/model-budget.js";
+import { formatSpecErrors, validateLogicTraceSpec } from "./logic-trace-validate.js";
+// ---------------------------------------------------------------------------
+// Constants & config
+// ---------------------------------------------------------------------------
+/** The single remote file this extension maintains. */
+export const LOGIC_TRACE_REMOTE_PATH = "logic.aexol";
+const LOGIC_TRACE_SETTINGS_KEY = "logic-trace";
+const LOGIC_TRACE_PASSIVE_ENV = "PI_LOGIC_TRACE_PASSIVE";
+const LOGIC_TRACE_DEBUG_ENV = "PI_LOGIC_TRACE_DEBUG";
+/** Default token amount of new material required before an automatic sync. */
+export const DEFAULT_THRESHOLD_TOKENS = 800;
+/** Default cadence between backend refine task polls (draftBackend path). */
+export const DEFAULT_DRAFT_BACKEND_POLL_INTERVAL_MS = 2_000;
+/** Default total wait for a backend refine task to reach a terminal status. */
+export const DEFAULT_DRAFT_BACKEND_TIMEOUT_MS = 120_000;
+/** Serialized recent-turn delta cap so one huge turn cannot overflow the draft call. */
+const MAX_DELTA_CHARS = 20_000;
+function normalizeModelRef(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const raw = value;
+    if (typeof raw.provider !== "string" || typeof raw.id !== "string")
+        return undefined;
+    return { provider: raw.provider, id: raw.id };
+}
+function readSettingsFile(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf-8"));
+        const nested = raw[LOGIC_TRACE_SETTINGS_KEY];
+        return nested && typeof nested === "object" ? nested : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Resolve settings from `~/.spectral/settings.json` and `<cwd>/.spectral/settings.json`
+ * (project wins), then apply the `PI_LOGIC_TRACE_PASSIVE` env override — the
+ * same layered scheme as `../memory/config.ts` under its own namespaced key.
+ */
+export function loadLogicTraceConfig(cwd, env = process.env) {
+    const merged = {
+        ...readSettingsFile(join(getAgentDir(), "settings.json")),
+        ...readSettingsFile(join(cwd, ".spectral", "settings.json")),
+    };
+    let passive = merged.passive === true;
+    const envRaw = env[LOGIC_TRACE_PASSIVE_ENV]?.trim().toLowerCase();
+    if (envRaw !== undefined) {
+        if (["1", "true", "yes", "on"].includes(envRaw))
+            passive = true;
+        if (["0", "false", "no", "off"].includes(envRaw))
+            passive = false;
+    }
+    let thresholdTokens = DEFAULT_THRESHOLD_TOKENS;
+    if (typeof merged.thresholdTokens === "number" &&
+        Number.isInteger(merged.thresholdTokens) &&
+        merged.thresholdTokens > 0) {
+        thresholdTokens = merged.thresholdTokens;
+    }
+    const draftBackend = merged.draftBackend === true;
+    let draftBackendPollIntervalMs = DEFAULT_DRAFT_BACKEND_POLL_INTERVAL_MS;
+    if (typeof merged.draftBackendPollIntervalMs === "number" &&
+        Number.isInteger(merged.draftBackendPollIntervalMs) &&
+        merged.draftBackendPollIntervalMs > 0) {
+        draftBackendPollIntervalMs = merged.draftBackendPollIntervalMs;
+    }
+    let draftBackendTimeoutMs = DEFAULT_DRAFT_BACKEND_TIMEOUT_MS;
+    if (typeof merged.draftBackendTimeoutMs === "number" &&
+        Number.isInteger(merged.draftBackendTimeoutMs) &&
+        merged.draftBackendTimeoutMs > 0) {
+        draftBackendTimeoutMs = merged.draftBackendTimeoutMs;
+    }
+    const draftBackendMaxRetries = typeof merged.draftBackendMaxRetries === "number" &&
+        Number.isInteger(merged.draftBackendMaxRetries) &&
+        merged.draftBackendMaxRetries > 0
+        ? merged.draftBackendMaxRetries
+        : undefined;
+    const model = normalizeModelRef(merged.model);
+    return {
+        passive,
+        thresholdTokens,
+        draftBackend,
+        draftBackendPollIntervalMs,
+        draftBackendTimeoutMs,
+        ...(draftBackendMaxRetries !== undefined ? { draftBackendMaxRetries } : {}),
+        ...(model ? { model } : {}),
+    };
+}
+function debugEnabled() {
+    const v = process.env[LOGIC_TRACE_DEBUG_ENV]?.trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes" || v === "on";
+}
+function debug(line, extra) {
+    if (!debugEnabled())
+        return;
+    process.stderr.write(`[logic-trace] ${line}${extra !== undefined ? ` ${JSON.stringify(extra)}` : ""}\n`);
+}
+// ---------------------------------------------------------------------------
+// Grammar summary & starter template embedded into the draft prompt
+// ---------------------------------------------------------------------------
+/** Exported: also embedded into the backend-refine prompt (draftBackend path). */
+export const LOGIC_TRACE_GRAMMAR = `.aexol quick grammar (one file, top-level blocks in any order, '#' lines are comments):
+- type Name { fieldName: Type ... } — one field per line. Scalar types: string, number, boolean, datetime.
+  A capitalized identifier references another type or enum; a trailing [] marks a list (e.g. items: Task[]).
+- enum Name { values, one per line, then '}' on its own line }.
+- role Name { permission resource { actions } } — actions from: create, read, update, delete.
+- workflow Name { a single 'initial stateA' line, then one 'state X -> Y, Z' line per transition }.
+- agent Name: BaseRole { can ..., must ..., should ... } — ' : BaseRole' is optional.
+- visitor { can ... } — optional.
+- Reserved grammar words (visitor, type, enum, role, workflow, agent, permission, action, state, transition, …) must NOT appear as identifiers: e.g. do not name a visitor/test step 'state' — write 'can inspect sync status', never 'can inspect sync state'.`;
+const LOGIC_TRACE_TEMPLATE = `# Project Logic
+
+type ChecklistItem {
+    id: string
+    title: string
+    done: boolean
+    createdAt: datetime
+    assignee: string
+    status: ItemState
+}
+
+enum ItemState {
+    planned
+    started
+    done
+    archived
+}
+
+workflow ItemLifecycle {
+    initial planned
+    state planned -> started, archived
+    state started -> done, planned
+    state done -> done
+    state archived -> archived
+}
+
+role DomainAdmin {
+    permission checklist { create, read, update, delete }
+}
+
+agent ChecklistAgent: DomainAdmin {
+    can plan items
+    must validate titles
+}
+
+visitor {
+    can view items
+}`;
+/**
+ * Leak-rule bullet list shared by LOGIC_TRACE_SYSTEM (local draft) and the
+ * backend refine adapter's MERGE_INSTRUCTIONS — defined once so the two
+ * prompts cannot drift apart.
+ */
+export const LOGIC_TRACE_LEAK_RULES = `- NEVER include secrets: no API keys or tokens (sk-…, xox…, ghp_…, AKIA…, JWTs), no Bearer/Authorization headers, and no KEY=value environment-variable-style assignments.
+- NEVER include absolute filesystem paths (/home/…, /Users/…, /root/…, C:\\Users\\…) or localhost URLs; refer to resources by project-relative names. Redact or omit anything sensitive.`;
+export const LOGIC_TRACE_SYSTEM = `You maintain the ONE logic.aexol file of the current Aexol Studio project: a valid, human-readable Aexol specification that mirrors the project's business logic (domain types, enums, roles, workflows, agents). It is always a FULL spec, never a changelog.
+
+${LOGIC_TRACE_GRAMMAR}
+
+Reference template (shape only — not content you must reproduce):
+"""
+${LOGIC_TRACE_TEMPLATE}
+"""
+
+Rules:
+- Return the COMPLETE updated file every time. Merge new facts into the existing structure ("merge, never append-only"): extend or reorganize existing types/agents/workflows instead of duplicating them.
+- HARD CONSTRAINT: the submitted file MUST parse with the Aexol parser (types, enums, workflows, roles, agents, visitors). Invalid syntax is rejected with parser errors you must fix and resubmit.
+- Keep the existing correct definitions; remove one only when it is clearly superseded by the new information.
+- Keep the file compact and grammar-valid. Validity beats exhaustiveness; do not invent facts beyond the recent activity.
+${LOGIC_TRACE_LEAK_RULES}
+- If the recent activity does not change business logic meaningfully (docs, prose, file paths, UI cosmetics), submit changed=false.
+- Call submit_logic_trace exactly once with the full content, then reply with a short plain-text confirmation to end the run.`;
+async function resolveLogicModel(config, sessionModel, modelRegistry) {
+    let model = sessionModel;
+    if (config.model && modelRegistry) {
+        const configured = modelRegistry.find?.(config.model.provider, config.model.id);
+        if (configured)
+            model = configured;
+    }
+    if (!model) {
+        return { ok: false, reason: "no model available (session has no model and no logic-trace model configured)" };
+    }
+    const registry = modelRegistry;
+    const auth = await registry?.getApiKeyAndHeaders?.(model);
+    if (!auth || !auth.ok || !auth.apiKey) {
+        const provider = model.provider ?? "unknown";
+        return { ok: false, reason: `no API key for provider "${provider}"` };
+    }
+    return { ok: true, model, apiKey: auth.apiKey, headers: auth.headers };
+}
+function firstJson(content) {
+    const first = content[0];
+    if (first && first.json !== undefined && typeof first.json === "object") {
+        return first.json;
+    }
+    return undefined;
+}
+function normalizeRemotePath(value) {
+    if (typeof value !== "string")
+        return "";
+    return value.replace(/^\.\//, "").replace(/^\//, "");
+}
+/** Tolerantly pull the file array out of a list_project_files JSON payload. */
+function extractFileArray(json) {
+    if (!json)
+        return [];
+    if (Array.isArray(json))
+        return json;
+    for (const key of ["files", "projectFiles", "items", "data"]) {
+        const value = json[key];
+        if (Array.isArray(value))
+            return value;
+    }
+    return [];
+}
+/**
+ * List-then-find the current remote `logic.aexol`.
+ *
+ * The project-file listing is MANDATORY on every sync: the backend's
+ * `remote_create_project_file` is a SILENT NO-OP when the file already
+ * exists, so create-vs-update can never be decided from a local cache alone.
+ */
+async function fetchRemoteLogicFile(client, projectId, teamId) {
+    // Inject the binding teamId on EVERY remote_* call: with user-JWT auth the
+    // backend otherwise falls back to the user's FIRST team membership
+    // (backend/src/routes/mcp/index.ts), which can differ from the team of the
+    // bound project.
+    const teamArg = teamId ? { teamId } : {};
+    const listing = await client.callTool("remote_list_project_files", { projectId, ...teamArg });
+    if (listing.isError) {
+        throw new Error("remote_list_project_files reported an error");
+    }
+    const files = extractFileArray(firstJson(listing.content));
+    for (const file of files) {
+        const path = normalizeRemotePath(file.path ?? file.name);
+        if (path !== LOGIC_TRACE_REMOTE_PATH)
+            continue;
+        const id = typeof file.id === "string" ? file.id : undefined;
+        let content = typeof file.content === "string" ? file.content : undefined;
+        if (content === undefined && id) {
+            const got = await client.callTool("remote_get_project_file", { id, projectId, ...teamArg });
+            if (!got.isError) {
+                const record = ((firstJson(got.content)?.file ?? firstJson(got.content)) ?? {});
+                if (typeof record.content === "string")
+                    content = record.content;
+            }
+        }
+        return { id: id ?? null, content, found: true };
+    }
+    return { id: null, content: undefined, found: false };
+}
+function extractCreatedFileId(content) {
+    const json = firstJson(content);
+    if (!json)
+        return undefined;
+    if (typeof json.id === "string")
+        return json.id;
+    const file = json.file;
+    if (file && typeof file === "object" && typeof file.id === "string") {
+        return file.id;
+    }
+    return undefined;
+}
+function toolResultText(res) {
+    const first = res.content[0];
+    if (first?.json !== undefined) {
+        try {
+            return JSON.stringify(first.json).slice(0, 300);
+        }
+        catch {
+            return "tool error";
+        }
+    }
+    return typeof first?.text === "string" ? first.text.slice(0, 300) : "tool error";
+}
+function capDelta(text) {
+    if (text.length <= MAX_DELTA_CHARS)
+        return text;
+    return `[... older serialized entries truncated ...]\n${text.slice(-MAX_DELTA_CHARS)}`;
+}
+// ---------------------------------------------------------------------------
+// Leak guard (mechanical pre-push pass; the prompt rules live in
+// LOGIC_TRACE_SYSTEM and this catches whatever the model leaks anyway)
+// ---------------------------------------------------------------------------
+const SECRET_REDACTED = "[REDACTED]";
+const PATH_REDACTED = "[REDACTED-PATH]";
+const URL_REDACTED = "[REDACTED-URL]";
+/**
+ * Strip secret/host-specific material from spec content before it is sent to
+ * remote_update_project_file / remote_create_project_file. Best-effort,
+ * format-preserving token pass: anything that looks like an API key
+ * (sk-…, xox*-, ghp…) a Bearer token, a JWT, an AWS access key, a
+ * `KEY=value` environment assignment, an absolute filesystem path, or a
+ * localhost URL is replaced in place with a redaction marker.
+ */
+export function sanitizeLogicTraceContent(content) {
+    return content
+        .replace(/\bsk-[A-Za-z0-9_-]{8,}/g, SECRET_REDACTED)
+        .replace(/\bxox[baprs]-[A-Za-z0-9-]{10,}/g, SECRET_REDACTED)
+        .replace(/\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}/g, SECRET_REDACTED)
+        .replace(/\bAKIA[0-9A-Z]{16}\b/g, SECRET_REDACTED)
+        .replace(/\bBearer[ \t]+[A-Za-z0-9._~+/=-]{16,}/gi, `Bearer ${SECRET_REDACTED}`)
+        .replace(/\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]+/g, SECRET_REDACTED)
+        .replace(
+    // Line-based `KEY=value` assignment: snake/SCREAMING_CASE env-style
+    // keys plus explicit secret names in any casing (password/passwd,
+    // api_key/apiKey/API-KEY, secret, token, credential). Colon-style
+    // .aexol field lines are never touched.
+    /^([ \t]*(?:export[ \t]+)?(?:[A-Za-z][A-Za-z0-9_]*(?:_[A-Za-z0-9_]+)+|[A-Z][A-Z0-9_]{2,}|[Aa][Pp][Ii][_-]?[Kk][Ee][Yy]|[Pp]ass(?:word|wd)|[Ss]ecret|[Tt]oken|[Cc]redential)[ \t]*=)[ \t]*\S.*$/gm, `$1${SECRET_REDACTED}`)
+        .replace(/\/(?:home|Users|root|private|workspace|tmp|var|etc|opt|mnt)\/[^\s"'`,;:\)\]}]*/g, PATH_REDACTED)
+        .replace(/[A-Za-z]:\\(?:Users|Documents(?: and Settings)?|Windows|Program Files)\\[^\s"'`,;:\)\]}]*/g, PATH_REDACTED)
+        .replace(/https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0|::1|\[::1\])(?::\d+)?(?:\/[^\s"'`,;:\)\]}]*)?/gi, URL_REDACTED)
+        .replace(/\b(?:localhost|127\.0\.0\.1|0\.0\.0\.0):\d+(?:\/[^\s"'`,;:\)\]}]*)?/g, URL_REDACTED);
+}
+const SUBMIT_TOOL_NAME = "submit_logic_trace";
+const SubmitLogicTraceSchema = Type.Object({
+    content: Type.String({
+        minLength: 1,
+        description: "The COMPLETE updated .aexol specification (full file contents, not a diff).",
+    }),
+    changed: Type.Boolean({
+        description: "true when the recent activity changed business logic and the CURRENT SPEC must be updated; false otherwise.",
+    }),
+});
+/**
+ * Build the draft-loop `submit_logic_trace` tool. Exported (like the internal
+ * `buildReadTool` / `buildWriteTool` builders, but visible to tests) so the
+ * parser-backed gate is unit-testable without an LLM: `collect` fires exactly
+ * once per VALID submission; invalid ones are rejected with parser diagnostics
+ * and never collected. Runtime wiring in `runLogicTraceDraft` is unchanged.
+ */
+export function buildSubmitTool(collect) {
+    const submitTool = {
+        name: SUBMIT_TOOL_NAME,
+        label: "Submit logic trace",
+        description: "Submit the COMPLETE updated logic.aexol specification. The content MUST parse as an .aexol spec: " +
+            "invalid syntax is returned as an error with parser diagnostics to fix, and the corrected FULL file must be resubmitted. " +
+            "Call this tool exactly once with the final valid spec; then reply with a short plain-text confirmation to end the run.",
+        parameters: SubmitLogicTraceSchema,
+        execute: async (_id, params) => {
+            // Parser-backed gate INSIDE the draft loop: an invalid submission is
+            // returned as an error with diagnostics (and NOT collected), so the
+            // model fixes them and resubmits within the same loop.
+            const sanitized = sanitizeLogicTraceContent((params.content ?? "").trim());
+            const validation = validateLogicTraceSpec(sanitized);
+            if (!validation.ok) {
+                debug("submit_logic_trace rejected: spec does not parse", { errors: validation.errors });
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Error: the submitted spec does not parse. Fix the issues and submit the FULL corrected file.\n" +
+                                formatSpecErrors(validation),
+                        }],
+                    details: { isError: true },
+                };
+            }
+            collect({ content: params.content, changed: params.changed === true });
+            return {
+                content: [{ type: "text", text: "Received. Reply with a short plain-text confirmation to finish." }],
+                details: {},
+            };
+        },
+    };
+    return submitTool;
+}
+/**
+ * Default draft runner: ONE agentLoop call with a single submit tool.
+ * Structurally mirrors `../memory/observer.ts` (drain events, await result,
+ * collect via the tool's execute) but accumulates exactly one submission.
+ */
+export async function runLogicTraceDraft(input) {
+    const submissions = [];
+    const submitTool = buildSubmitTool((submission) => submissions.push(submission));
+    const userText = `CURRENT SPEC (${input.currentContent === undefined ? "not created yet" : "current logic.aexol"}):
+${input.currentContent ?? "(the file does not exist yet — author a starting spec)"}
+
+RECENT AGENT ACTIVITY:
+${input.delta}
+
+return the FULL updated spec with the recent changes merged in ("merge, never append-only"). If the activity does not change business logic meaningfully, call submit_logic_trace with changed=false and the current spec unchanged.`;
+    const prompts = [
+        {
+            role: "user",
+            content: [{ type: "text", text: userText }],
+            timestamp: Date.now(),
+        },
+    ];
+    const context = {
+        systemPrompt: LOGIC_TRACE_SYSTEM,
+        messages: [],
+        tools: [submitTool],
+    };
+    const model = input.model;
+    const reasoning = model.reasoning;
+    const config = {
+        model,
+        apiKey: input.apiKey,
+        headers: input.headers,
+        maxTokens: boundedMaxTokens(model, AGENT_LOOP_MAX_TOKENS),
+        convertToLlm: (msgs) => msgs,
+        toolExecution: "sequential",
+        cacheRetention: "none",
+        sessionId: uuidv7(),
+        ...(reasoning ? { reasoning: "high" } : {}),
+    };
+    const stream = agentLoop(prompts, context, config, input.signal);
+    for await (const _event of stream) {
+        // Drain events; the tool's execute already collected the submission.
+    }
+    await stream.result();
+    const last = submissions[submissions.length - 1];
+    return last ? { submitted: last } : {};
+}
+const serverStateByCwd = new Map();
+function stateFor(cwd) {
+    let state = serverStateByCwd.get(cwd);
+    if (!state) {
+        state = {
+            binding: null,
+            bindingMtimeMs: null,
+            remote: null,
+            syncedTokens: 0,
+            syncInFlight: false,
+            syncPromise: null,
+        };
+        serverStateByCwd.set(cwd, state);
+    }
+    return state;
+}
+/**
+ * Await/diagnose the in-flight sync for a cwd (null when idle). Exposed for
+ * deterministic tests and diagnostics; production hooks stay fire-and-forget.
+ */
+export function pendingLogicTraceSync(cwd) {
+    return stateFor(cwd).syncPromise;
+}
+/**
+ * Threshold evaluation WITHOUT mutating per-cwd state (used by cheap pre-gates
+ * that must not consume material). Equals the delta computed inside
+ * attemptLogicTraceSync after its re-baseline step.
+ */
+function unsyncedTokens(state, tokens) {
+    return Math.max(0, tokens - state.syncedTokens);
+}
+/** Per-cwd binding reader — same mtime-cache pattern as aexol-mcp.ts. */
+async function refreshBindingForCwd(cwd) {
+    const state = stateFor(cwd);
+    const bindingFile = join(cwd, ".aexol", "aexol.jsonc");
+    let mtimeMs;
+    try {
+        mtimeMs = statSync(bindingFile).mtimeMs;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT" || code === "ENOTDIR") {
+            state.binding = null;
+            state.bindingMtimeMs = null;
+            return null;
+        }
+        return state.binding;
+    }
+    if (mtimeMs === state.bindingMtimeMs)
+        return state.binding;
+    try {
+        state.binding = await readStudioBinding(cwd);
+        state.bindingMtimeMs = mtimeMs;
+    }
+    catch {
+        debug("binding file parse failed", { cwd });
+        state.bindingMtimeMs = null;
+    }
+    return state.binding;
+}
+const SKIPPED = (reason) => ({ pushed: false, ok: true, reason });
+const FAILED = (reason) => ({ pushed: false, ok: false, reason });
+function notifyWith(ui, message, type = "info") {
+    debug(`notify: ${message}`);
+    if (ui.hasUI && ui.ui)
+        ui.ui.notify(`Logic trace: ${message}`, type);
+}
+/**
+ * Run one guarded sync attempt. The in-flight singleton guard is checked AND
+ * set synchronously so two back-to-back hook invocations can never race into
+ * a second concurrent run. The returned promise never rejects; concurrent
+ * callers while a run is in flight get `null` instead.
+ */
+export function runLogicTraceSync(deps) {
+    const { state } = deps;
+    if (state.syncInFlight) {
+        debug("sync skipped: already in flight");
+        return null;
+    }
+    state.syncInFlight = true;
+    let promise;
+    promise = (async () => {
+        try {
+            return await attemptLogicTraceSync(deps);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            debug("sync failed", { errorMessage: msg });
+            return FAILED(msg);
+        }
+        finally {
+            state.syncInFlight = false;
+            if (state.syncPromise === promise)
+                state.syncPromise = null;
+        }
+    })();
+    state.syncPromise = promise;
+    return promise;
+}
+async function attemptLogicTraceSync(deps) {
+    const { cwd, config, state, draftRunner, signal, ui, model, modelRegistry, entries, leafId } = deps;
+    const binding = await refreshBindingForCwd(cwd);
+    if (!binding) {
+        debug("sync skipped: not bound to a Studio project");
+        return SKIPPED("not-bound");
+    }
+    // Serialize the recent-turn delta — mirrors ../memory/hooks/observer-trigger.ts:
+    // bound-relative token estimate → bound-relative raw tail → source-addressed
+    // serialization.
+    const tokens = rawTokensSinceLastBound(entries);
+    if (tokens < state.syncedTokens)
+        state.syncedTokens = tokens; // bound moved backward → re-baseline
+    if (!deps.force) {
+        const deltaTokens = unsyncedTokens(state, tokens);
+        if (deltaTokens < config.thresholdTokens) {
+            debug("sync skipped: threshold not reached", { deltaTokens, thresholdTokens: config.thresholdTokens });
+            return SKIPPED("threshold-not-reached");
+        }
+    }
+    // The skip-gate watermark is consumed ONLY when this attempt's draft+push
+    // cycle completes (the `consume()` call sites below). A failed draft, a
+    // failed push, or an unavailable backend must leave it untouched so the
+    // next turn_end re-attempts the same material even without fresh tokens;
+    // the MAX_DELTA_CHARS cap bounds how much of it is re-serialized. Nested
+    // one-shot decisions that DID process the material (draft ran, nothing to
+    // push) consume like the memory observer advancing its bound on empty.
+    const consume = () => {
+        state.syncedTokens = tokens;
+    };
+    // Backend bootstrap only AFTER the cheap gates above: bootstrapping opens
+    // the OAuth browser flow when the token is expired, so it must never run
+    // for turns that fail the binding or threshold gate. Real 401/403s from
+    // live calls keep their client-side re-auth recovery in
+    // aexol-backend-client.ts (untouched).
+    const bootstrap = await deps.getBootstrap(cwd);
+    if (!bootstrap.ok) {
+        debug("sync skipped: backend unavailable", { reason: bootstrap.reason });
+        return FAILED("backend-unavailable");
+    }
+    const client = bootstrap.client;
+    const coversFromId = firstRawIdAfter(entries, lastObservationCoverEndIdx(entries));
+    if (!coversFromId)
+        return SKIPPED("no-source-entries");
+    const tail = rawTailEntriesBetween(entries, coversFromId, leafId ?? coversFromId);
+    if (tail.length === 0)
+        return SKIPPED("empty-tail");
+    const serialized = serializeSourceAddressedBranchEntries(tail);
+    if (!serialized.text.trim())
+        return SKIPPED("empty-tail");
+    const delta = capDelta(serialized.text);
+    const resolved = await resolveLogicModel(config, model, modelRegistry);
+    if (!resolved.ok) {
+        debug("sync skipped: model unavailable", { reason: resolved.reason });
+        return SKIPPED(resolved.reason);
+    }
+    const projectId = binding.projectId;
+    const teamArg = binding.teamId ? { teamId: binding.teamId } : {};
+    let remote;
+    try {
+        remote = await fetchRemoteLogicFile(client, projectId, binding.teamId);
+    }
+    catch (err) {
+        debug("remote list/get failed", { errorMessage: err instanceof Error ? err.message : String(err) });
+        return FAILED("remote-list-failed");
+    }
+    // Refresh the per-cwd remote cache from the (mandatory) listing.
+    state.remote = {
+        id: remote.id,
+        contentHash: remote.content !== undefined ? hashId(remote.content) : undefined,
+    };
+    if (remote.found && (remote.content === undefined || remote.content.trim() === "")) {
+        // The file EXISTS remotely but its content could not be read (fetch
+        // swallows get failures) or is empty (e.g. externally truncated). Do
+        // NOT let the draft author a spec from scratch here — that would
+        // clobber externally-edited content; a plain
+        // remote_create_project_file would be a silent no-op anyway.
+        debug("sync skipped: remote file found but content unreadable");
+        return SKIPPED("remote-content-unreadable");
+    }
+    let draft;
+    try {
+        const draftInput = {
+            model: resolved.model,
+            apiKey: resolved.apiKey,
+            headers: resolved.headers,
+            currentContent: remote.content,
+            delta,
+            signal,
+        };
+        // Opt-in backend draft: delegate the .aexol authoring step to the
+        // backend from/refine pipeline. The adapter never throws past the seam
+        // and returns {} on FAILED/CANCELLED/timeout — an empty outcome (or a
+        // throw, defensively) falls back to the local draft runner below, so
+        // the downstream sanitize → parser gate → dedupe → push flow is shared
+        // by both paths. With draftBackend=false this is exactly the previous
+        // behavior (local runner only).
+        const runLocalDraft = () => draftRunner(draftInput);
+        // A forced/compaction flush must never block compaction on the backend
+        // refine pipeline: the adapter polls up to draftBackendTimeoutMs
+        // (default 120s) and session_before_compact awaits this sync, so a
+        // stuck refine task would stall compaction for minutes. Forced flushes
+        // (force: true — the threshold bypass above) go straight to the local
+        // draft runner; the pre-compact material is still flushed, just without
+        // the backend round-trip.
+        if (config.draftBackend && !deps.force) {
+            let backendDraft = {};
+            try {
+                backendDraft = await deps.backendDraftFactory({
+                    client,
+                    projectId,
+                    ...(binding.teamId ? { teamId: binding.teamId } : {}),
+                    pollIntervalMs: config.draftBackendPollIntervalMs,
+                    pollTimeoutMs: config.draftBackendTimeoutMs,
+                    ...(config.draftBackendMaxRetries !== undefined
+                        ? { maxRetries: config.draftBackendMaxRetries }
+                        : {}),
+                    promptRules: LOGIC_TRACE_GRAMMAR,
+                })(draftInput);
+            }
+            catch (err) {
+                debug("backend draft runner threw (falling back)", { errorMessage: err instanceof Error ? err.message : String(err) });
+            }
+            if (backendDraft.submitted) {
+                draft = backendDraft;
+            }
+            else {
+                debug("backend draft empty → local draft fallback");
+                draft = await runLocalDraft();
+            }
+        }
+        else {
+            draft = await runLocalDraft();
+        }
+    }
+    catch (err) {
+        debug("draft runner failed", { errorMessage: err instanceof Error ? err.message : String(err) });
+        return FAILED("draft-failed");
+    }
+    const submitted = draft.submitted;
+    if (!submitted) {
+        consume(); // draft cycle completed → don't re-run the same material next turn
+        return SKIPPED("draft-no-submission");
+    }
+    if (!submitted.changed) {
+        debug("draft says unchanged → skip push");
+        consume();
+        return SKIPPED("draft-unchanged");
+    }
+    const content = sanitizeLogicTraceContent(submitted.content.trim());
+    if (!content) {
+        consume();
+        return SKIPPED("draft-empty-content");
+    }
+    // Parser-backed gate before any hash/dedupe/push: content the Aexol
+    // parser rejects must never reach the remote file. Mirrors the
+    // 'draft-failed' FAILED pattern; FAILED('draft-invalid') deliberately
+    // leaves the skip-gate watermark unconsumed so the next turn_end
+    // re-attempts the same material.
+    const validation = validateLogicTraceSpec(content);
+    if (!validation.ok) {
+        debug("draft rejected: content does not parse", { errors: formatSpecErrors(validation) });
+        return FAILED("draft-invalid");
+    }
+    const nextHash = hashId(content);
+    const currentHash = remote.content !== undefined ? hashId(remote.content) : state.remote?.contentHash;
+    if (currentHash && nextHash === currentHash) {
+        debug("hash unchanged → skip push", { nextHash });
+        consume();
+        return SKIPPED("hash-unchanged");
+    }
+    let pushedId;
+    let pushError = false;
+    if (remote.id) {
+        const res = await client.callTool("remote_update_project_file", {
+            id: remote.id,
+            content,
+            projectId,
+            ...teamArg,
+        });
+        if (res.isError) {
+            notifyWith(ui, `failed to update logic.aexol: ${toolResultText(res)}`, "warning");
+            pushError = true;
+        }
+        else {
+            pushedId = remote.id;
+        }
+    }
+    else {
+        // The listing ran before this push, so "not found" + create is safe:
+        // remote_create_project_file is a silent no-op only when the path exists.
+        const res = await client.callTool("remote_create_project_file", {
+            path: LOGIC_TRACE_REMOTE_PATH,
+            content,
+            projectId,
+            ...teamArg,
+        });
+        if (res.isError) {
+            notifyWith(ui, `failed to create logic.aexol: ${toolResultText(res)}`, "warning");
+            pushError = true;
+        }
+        else {
+            pushedId = extractCreatedFileId(res.content);
+        }
+    }
+    if (pushError) {
+        // A stale cached id is the most likely cause; clear the cache to force a
+        // clean re-list next time.
+        state.remote = null;
+        return FAILED("push-failed");
+    }
+    // On success refresh BOTH cached id and hash so the next sync dedupes.
+    state.remote = { id: pushedId ?? remote.id ?? null, contentHash: nextHash };
+    consume(); // completed draft+push cycle → the watermark advances
+    notifyWith(ui, `logic.aexol updated in project ${binding.name ?? binding.projectId}`);
+    return { pushed: true, ok: true };
+}
+// ---------------------------------------------------------------------------
+// Agent tools
+// ---------------------------------------------------------------------------
+const LOGIC_TRACE_READ_TOOL_NAME = "remote_logic_trace_read";
+const LOGIC_TRACE_WRITE_TOOL_NAME = "remote_logic_trace_write";
+const UNBOUND_TEXT = "No Aexol Studio project binding found in this directory.\n" +
+    "Use local_bind_project to link this directory to a Studio project (then read/write logic.aexol), " +
+    "or `spectral bind <project-id>` from the terminal.";
+const NOT_CREATED_TEXT = `"${LOGIC_TRACE_REMOTE_PATH}" has not been created in this Studio project yet.\n` +
+    `It is auto-refreshed by the logic trace mechanism after meaningful business-logic work; ` +
+    `you can also create it with ${LOGIC_TRACE_WRITE_TOOL_NAME}.`;
+function textResult(text, isError = false) {
+    return {
+        content: [{ type: "text", text }],
+        details: { isError },
+    };
+}
+const ReadParamsSchema = Type.Object({});
+function buildReadTool(ensureBackend) {
+    return {
+        name: LOGIC_TRACE_READ_TOOL_NAME,
+        label: "Read Logic Trace",
+        description: `Read the current ${LOGIC_TRACE_REMOTE_PATH} file from the bound Aexol Studio project. ` +
+            `It mirrors the project's business logic as a compact .aexol specification (types, enums, roles, workflows, agents). ` +
+            `Call this BEFORE writing to it, to see what already exists.`,
+        promptSnippet: `Use ${LOGIC_TRACE_READ_TOOL_NAME}() to see the current one-file business-logic spec (${LOGIC_TRACE_REMOTE_PATH}) in the bound Studio project.`,
+        promptGuidelines: [
+            `There is EXACTLY ONE logic file per project: ${LOGIC_TRACE_REMOTE_PATH}. Never create extra spec files.`,
+            "Read it before writing; the automatic refresh keeps it current at the end of each turn.",
+        ],
+        parameters: Type.Object({}),
+        async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+            // An explicit agent action: retry the bootstrap (may re-run the OAuth
+            // re-auth) even when the automatic path is blocked by a memoized
+            // bootstrap failure; success here unlocks the session memo.
+            const backend = await ensureBackend(ctx.cwd, { retry: true });
+            if (!backend.ok) {
+                return textResult(`Aexol backend unavailable: ${backend.message}`, true);
+            }
+            const binding = await refreshBindingForCwd(ctx.cwd);
+            if (!binding)
+                return textResult(UNBOUND_TEXT, true);
+            try {
+                const remote = await fetchRemoteLogicFile(backend.client, binding.projectId, binding.teamId);
+                if (!remote.found)
+                    return textResult(NOT_CREATED_TEXT);
+                return textResult(remote.content ?? "(empty file)");
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return textResult(`Failed to read ${LOGIC_TRACE_REMOTE_PATH}: ${msg}`, true);
+            }
+        },
+    };
+}
+function buildWriteTool(ensureBackend) {
+    const WriteSchema = Type.Object({
+        content: Type.String({
+            minLength: 1,
+            description: "The COMPLETE .aexol spec to store as the ONE project logic file (full contents).",
+        }),
+        reason: Type.String({
+            minLength: 1,
+            description: "Why this full-spec update is needed (echoed in the ack).",
+        }),
+    });
+    return {
+        name: LOGIC_TRACE_WRITE_TOOL_NAME,
+        label: "Write Logic Trace",
+        description: `Manually upsert the ONE ${LOGIC_TRACE_REMOTE_PATH} file in the bound Aexol Studio project with a COMPLETE .aexol spec. ` +
+            `Merge, never append-only: read it first, then write the full updated file. Refresh it after meaningful business-logic changes.`,
+        promptSnippet: `Use ${LOGIC_TRACE_WRITE_TOOL_NAME}(content, reason) to fully regenerate ${LOGIC_TRACE_REMOTE_PATH} (the ONE business-logic spec in the bound Studio project) after meaningful business-logic changes.`,
+        promptGuidelines: [
+            `There is EXACTLY ONE logic file per project: ${LOGIC_TRACE_REMOTE_PATH}. Never create extra spec files; never append changelogs into it.`,
+            `Always ${LOGIC_TRACE_READ_TOOL_NAME} before writing, and write the FULL merged spec — not a diff, not an appendix.`,
+            "Only full-spec writes; this tool upserts (updates the existing file or creates it when missing) and never deletes it.",
+            "Use it after meaningful business-logic changes (new/changed types, enums, roles, workflows, agents); automatic refresh handles the rest.",
+            "The tool returns ✓ when the complete spec parses, and an Error with parser diagnostics when it does not.",
+        ],
+        parameters: WriteSchema,
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            // Same explicit retry semantics as remote_logic_trace_read: this is
+            // the agent deliberately acting, so a memoized bootstrap failure may
+            // be re-attempted (and is unlocked on success).
+            const backend = await ensureBackend(ctx.cwd, { retry: true });
+            if (!backend.ok) {
+                return textResult(`Aexol backend unavailable: ${backend.message}`, true);
+            }
+            const binding = await refreshBindingForCwd(ctx.cwd);
+            if (!binding)
+                return textResult(UNBOUND_TEXT, true);
+            // EXPLICIT agent action: the content the agent deliberately wrote is
+            // stored verbatim (trim only) — the redaction pass is reserved for
+            // automatically drafted sync content, not for the agent's own
+            // deliberate full-spec write.
+            const content = (params.content ?? "").trim();
+            if (!content) {
+                return textResult("Error: content (the complete .aexol spec) is required.", true);
+            }
+            // Parser-backed gate BEFORE any remote call: invalid content must
+            // neither mutate the cloud file nor even probe the project-file
+            // listing, so writes fail fast with parser diagnostics instead of
+            // storing a spec the Aexol toolchain cannot read.
+            const validation = validateLogicTraceSpec(content);
+            if (!validation.ok) {
+                return textResult("Error: content is not a valid .aexol spec.\n" + formatSpecErrors(validation), true);
+            }
+            try {
+                // Manual upsert: list (mandatory — create silently no-ops when the
+                // path already exists) then update-or-create. No LLM, no dedupe.
+                const remote = await fetchRemoteLogicFile(backend.client, binding.projectId, binding.teamId);
+                const state = stateFor(ctx.cwd);
+                state.remote = {
+                    id: remote.id,
+                    contentHash: remote.content !== undefined ? hashId(remote.content) : undefined,
+                };
+                // Every remote_* call carries the binding ids (projectId + teamId
+                // when present) so team access resolves to the BOUND project, not
+                // to the first team membership of the user token.
+                const teamArg = binding.teamId ? { teamId: binding.teamId } : {};
+                let id;
+                if (remote.id) {
+                    const res = await backend.client.callTool("remote_update_project_file", {
+                        id: remote.id,
+                        content,
+                        projectId: binding.projectId,
+                        ...teamArg,
+                    });
+                    if (res.isError)
+                        return textResult(`Failed to update ${LOGIC_TRACE_REMOTE_PATH}: ${toolResultText(res)}`, true);
+                    id = remote.id;
+                }
+                else {
+                    const res = await backend.client.callTool("remote_create_project_file", {
+                        path: LOGIC_TRACE_REMOTE_PATH,
+                        content,
+                        projectId: binding.projectId,
+                        ...teamArg,
+                    });
+                    if (res.isError)
+                        return textResult(`Failed to create ${LOGIC_TRACE_REMOTE_PATH}: ${toolResultText(res)}`, true);
+                    id = extractCreatedFileId(res.content);
+                }
+                const contentHash = hashId(content);
+                state.remote = { id: id ?? null, contentHash };
+                notifyWith({ hasUI: ctx.hasUI, ui: ctx.ui }, `logic.aexol updated in project ${binding.name ?? binding.projectId}`);
+                return textResult(`✓ ${LOGIC_TRACE_REMOTE_PATH} ${remote.id ? "updated" : "created"} ` +
+                    `(project ${binding.name ?? binding.projectId}, reason: ${params.reason.trim()}).`);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return textResult(`Failed to write ${LOGIC_TRACE_REMOTE_PATH}: ${msg}`, true);
+            }
+        },
+    };
+}
+/**
+ * Logic trace extension entry point: automatic refresh hooks
+ * (`turn_end`, `session_before_compact`) plus the two agent tools.
+ */
+export function logicTraceExtension(ext, options = {}) {
+    const draftRunner = options.draftRunner ?? runLogicTraceDraft;
+    const backendDraftFactory = options.backendDraftFactory ?? createBackendRefineDraftRunner;
+    const clientFactory = options.clientFactory ?? createAexolBackendClient;
+    let cachedBootstrap = null;
+    let bootstrapPromise = null;
+    // Memoized bootstrap FAILURE, held for the REST OF THE SESSION (per cwd):
+    // bootstrap performs the OAuth browser flow when the stored token is
+    // expired, so re-attempting it from the automatic turn hooks would reopen
+    // a browser on every turn_end. The memo is replayed by the sync path
+    // only and never expires mid-session; it unlocks when an explicit agent
+    // action re-bootstraps successfully — the remote_logic_trace_read/write
+    // tools call ensureBackend with `{ retry: true }`, and that retry runs
+    // the explicit OAuth re-auth. Real 401/403s from live calls keep their
+    // existing client-side re-auth recovery in aexol-backend-client.ts
+    // (untouched).
+    let failureMemo = null;
+    async function ensureBackend(cwd, options = {}) {
+        if (cachedBootstrap)
+            return { ok: true, ...cachedBootstrap };
+        if (!options.retry && failureMemo && failureMemo.cwd === cwd) {
+            debug("bootstrap skipped: memoized failure (unlock via an explicit agent tool call)");
+            return failureMemo.outcome;
+        }
+        bootstrapPromise ??= clientFactory({
+            warn: (line) => process.stderr.write(`[logic-trace] ${line}\n`),
+        });
+        let result;
+        try {
+            result = await bootstrapPromise;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            result = { ok: false, reason: "catalog-failed", message: msg };
+        }
+        if (result.ok) {
+            // Memoize success for the session; a failure memo is cleared (unlock).
+            cachedBootstrap = result;
+            failureMemo = null;
+        }
+        else {
+            failureMemo = { cwd, outcome: { ...result } };
+        }
+        bootstrapPromise = null;
+        return result;
+    }
+    function makeNotifier(hasUI, ui) {
+        return { hasUI, ui };
+    }
+    try {
+        ext.registerTool(buildReadTool(ensureBackend));
+    }
+    catch (err) {
+        process.stderr.write(`[logic-trace] Failed to register ${LOGIC_TRACE_READ_TOOL_NAME}: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    try {
+        ext.registerTool(buildWriteTool(ensureBackend));
+    }
+    catch (err) {
+        process.stderr.write(`[logic-trace] Failed to register ${LOGIC_TRACE_WRITE_TOOL_NAME}: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    ext.on("session_start", async (_event, ctx) => {
+        const config = loadLogicTraceConfig(ctx.cwd);
+        if (config.passive)
+            return;
+        try {
+            const binding = await refreshBindingForCwd(ctx.cwd);
+            if (binding) {
+                debug("session_start: project binding found", { projectId: binding.projectId });
+            }
+        }
+        catch (err) {
+            debug("session_start binding read failed", { errorMessage: err instanceof Error ? err.message : String(err) });
+        }
+    });
+    ext.on("turn_end", async (_event, ctx) => {
+        const config = loadLogicTraceConfig(ctx.cwd);
+        if (config.passive) {
+            debug("turn_end skipped: passive");
+            return;
+        }
+        // Snapshot ctx synchronously — the async work below may outlive it.
+        const ui = makeNotifier(ctx.hasUI, ctx.ui);
+        const model = ctx.model;
+        const modelRegistry = ctx.modelRegistry;
+        const entries = ctx.sessionManager.getBranch();
+        const leafId = ctx.sessionManager.getLeafId?.();
+        // Fire-and-forget: the outcome is never thrown; failures surface via
+        // debug logs / notify inside runLogicTraceSync. The binding check and
+        // the token-threshold gate run INSIDE the sync before it touches the
+        // backend, so no turn bootstrap()s a backend without passing them.
+        void runLogicTraceSync({
+            cwd: ctx.cwd,
+            config,
+            state: stateFor(ctx.cwd),
+            getBootstrap: ensureBackend,
+            draftRunner,
+            backendDraftFactory,
+            ui,
+            model,
+            modelRegistry,
+            entries,
+            leafId,
+        });
+    });
+    ext.on("session_before_compact", async (event, ctx) => {
+        const config = loadLogicTraceConfig(ctx.cwd);
+        if (config.passive)
+            return undefined;
+        try {
+            const state = stateFor(ctx.cwd);
+            // A fire-and-forget sync may still be mid-flight; WAIT for it instead
+            // of skipping so the pre-compact delta is flushed before the raw
+            // material is compacted away.
+            const pending = pendingLogicTraceSync(ctx.cwd);
+            if (pending) {
+                debug("compaction flush: awaiting in-flight sync first");
+                await pending.catch(() => undefined);
+            }
+            // Flush the entries that are about to be summarized away (everything
+            // before the compaction's firstKeptEntryId keeps its material alive in
+            // logic.aexol before the raw tail disappears from context).
+            const branchEntries = (event.branchEntries ?? []);
+            let entriesToFlush = branchEntries;
+            const firstKeptEntryId = event.preparation?.firstKeptEntryId;
+            if (typeof firstKeptEntryId === "string") {
+                const idx = branchEntries.findIndex((e) => e.id === firstKeptEntryId);
+                if (idx > 0)
+                    entriesToFlush = branchEntries.slice(0, idx);
+            }
+            if (entriesToFlush.length === 0)
+                return undefined;
+            const ui = makeNotifier(ctx.hasUI, ctx.ui);
+            await runLogicTraceSync({
+                cwd: ctx.cwd,
+                config,
+                state,
+                getBootstrap: ensureBackend,
+                draftRunner,
+                backendDraftFactory,
+                ui,
+                model: ctx.model,
+                modelRegistry: ctx.modelRegistry,
+                entries: entriesToFlush,
+                leafId: lastSourceEntryId(entriesToFlush),
+                force: true, // compaction may destroy the material — flush regardless of threshold
+            });
+        }
+        catch (err) {
+            // Never influence the compaction result; failures are diagnostic only.
+            debug("compaction flush failed", { errorMessage: err instanceof Error ? err.message : String(err) });
+        }
+        return undefined;
+    });
+}
+function lastSourceEntryId(entries) {
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const type = entries[i].type;
+        if (type === "message" || type === "custom_message" || type === "branch_summary") {
+            return entries[i].id;
+        }
+    }
+    return undefined;
+}
+export default logicTraceExtension;