studiograph 1.3.48-next.26 → 1.3.48-next.261

package/dist/server/asset-index-queue.js

@@ -0,0 +1,193 @@
+/**
+ * Asset Index Service — the live, in-process drain for image captioning and
+ * document-sidecar extraction.
+ *
+ * P3b shipped the derive/persist/migration logic (`sweepAssetIndex`) but wired
+ * it only to a one-shot boot pass. On a long-lived server (Railway tenants run
+ * for days/weeks) that meant a freshly-uploaded image stayed filename-only —
+ * not content-searchable — until the next restart. This service closes that gap
+ * the same way `SessionManager` closes the commit-batching gap: a long-lived
+ * object with a periodic timer, an `enqueue()` the upload paths call, a
+ * crash-resilient persisted queue, and a `recoverOnBoot()` that drains anything
+ * left unfinished.
+ *
+ * Shape (mirrors SessionManager deliberately so the lifecycle is familiar):
+ *  - `enqueue(assetId)` — fired by VectorService.onAssetPending the moment an
+ *    indexable IMAGE assets.db row is seeded `pending` (every image-upload path
+ *    funnels through ensureInitialAssetIndexState). Just records the assetId.
+ *  - periodic `setInterval` tick — drains the queued ids through
+ *    `sweepAssetIndex({ onlyAssets })`, bounded + gated exactly as the boot pass.
+ *    Idle when the queue is empty, so an idle server does zero vision work.
+ *  - persisted queue (`pending-asset-index.json`, atomic tmp+rename) — survives
+ *    a crash; `recoverOnBoot()` replays it AND runs the full unfiltered sweep
+ *    (which re-derives anything missing/stale in LanceDB regardless of the
+ *    queue), so nothing is lost even if the process died mid-drain.
+ *  - `shutdown()` — drains what's queued, then tears down the timer.
+ *
+ * Config (caption model, the `captioning.enabled` gate, the repo list) is
+ * resolved FRESH each tick via the injected `resolveConfig` thunk, so flipping
+ * the model or the gate in Settings takes effect without a restart — the same
+ * live-resolution property VectorService already has for the Voyage key.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { sweepAssetIndex, } from '../services/asset-index-sweep.js';
+const DEFAULT_INTERVAL_MS = 15_000;
+export class AssetIndexQueue {
+    deps;
+    queue = new Set();
+    timer = null;
+    draining = false;
+    pendingPath;
+    intervalMs;
+    log;
+    constructor(deps) {
+        this.deps = deps;
+        this.intervalMs = deps.intervalMs ?? DEFAULT_INTERVAL_MS;
+        this.log = deps.log ?? (() => { });
+        this.pendingPath = join(deps.workspaceManager.getWorkspacePath(), '.studiograph', 'pending-asset-index.json');
+    }
+    /** Start the periodic drain. Idempotent. */
+    start() {
+        if (this.timer)
+            return;
+        // Load anything a prior process queued but never drained.
+        const persisted = this.loadPersisted();
+        if (persisted)
+            for (const k of persisted.pending)
+                this.queue.add(k);
+        this.timer = setInterval(() => { void this.drainTick(); }, this.intervalMs);
+        // Node: don't keep the event loop alive solely for this timer.
+        this.timer.unref?.();
+    }
+    /**
+     * Record that an image asset needs caption/OCR indexing, keyed by its
+     * immutable assetId. Fired by VectorService.onAssetPending once the
+     * assets.db image row is written (covers import, manager/editor upload, and
+     * presign finalize). Cheap + synchronous; the derive happens on the next tick.
+     */
+    enqueue(assetId) {
+        this.queue.add(assetId);
+        this.persist();
+    }
+    /** Current queue depth — exposed for the health endpoint / tests. */
+    get queueDepth() {
+        return this.queue.size;
+    }
+    /**
+     * Boot recovery: replay the persisted queue, then run the FULL unfiltered
+     * sweep so anything missing/stale in LanceDB (legacy assets, a drain that
+     * died mid-flight) is re-derived regardless of whether it's still queued.
+     * Fire-and-forget at boot — it can take minutes and must not block listen().
+     *
+     * Holds the same `draining` guard a tick uses, so the (slow) boot sweep can't
+     * run concurrently with a periodic drain and conflict on the LanceDB writer.
+     * Only the ids that were queued WHEN THE SWEEP STARTED are removed afterward —
+     * uploads that arrive during the minutes-long sweep stay queued for the next
+     * tick rather than being silently dropped.
+     */
+    async recoverOnBoot() {
+        const persisted = this.loadPersisted();
+        if (persisted)
+            for (const k of persisted.pending)
+                this.queue.add(k);
+        // Wait out any in-flight tick, then claim the guard for the boot sweep.
+        while (this.draining)
+            await new Promise((r) => setTimeout(r, 50));
+        this.draining = true;
+        const handled = new Set(this.queue); // snapshot: what the full sweep covers
+        try {
+            const res = await this.runSweep(undefined);
+            // Remove only the snapshot — newer enqueues survive for the next tick.
+            for (const k of handled)
+                this.queue.delete(k);
+            this.persist();
+            return res;
+        }
+        finally {
+            this.draining = false;
+        }
+    }
+    /** Drain the currently-queued ids. Re-entrancy guarded. */
+    async drainTick() {
+        if (this.draining)
+            return;
+        if (this.queue.size === 0)
+            return;
+        this.draining = true;
+        // Snapshot + clear up-front: ids enqueued DURING the drain land in the next
+        // tick rather than being dropped. On failure we re-add the snapshot.
+        const batch = new Set(this.queue);
+        this.queue.clear();
+        this.persist();
+        try {
+            await this.runSweep(batch);
+        }
+        catch (err) {
+            // Re-queue the batch so a transient failure retries next tick.
+            for (const k of batch)
+                this.queue.add(k);
+            this.persist();
+            this.log(`drain failed (re-queued ${batch.size}): ${err instanceof Error ? err.message : err}`);
+        }
+        finally {
+            this.draining = false;
+        }
+    }
+    /** Resolve live config and run the sweep over `onlyAssets` (undefined = all). */
+    async runSweep(onlyAssets) {
+        const cfg = this.deps.resolveConfig();
+        const res = await sweepAssetIndex({
+            workspaceManager: this.deps.workspaceManager,
+            repos: cfg.repos,
+            workspacePath: this.deps.workspaceManager.getWorkspacePath(),
+            captionConfig: cfg.captionConfig,
+            captioningEnabled: cfg.captioningEnabled,
+        }, { onlyAssets, concurrency: this.deps.concurrency, log: this.log, completeFn: this.deps.completeFn });
+        if (res.derived > 0 || res.failed > 0 || res.leftPending > 0) {
+            this.log(`assets: ${res.derived} indexed, ${res.failed} failed, ${res.leftPending} pending, ${res.skippedUpToDate} up-to-date`);
+        }
+        return res;
+    }
+    /** Graceful shutdown — drain what's queued, then stop the timer. */
+    async shutdown() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        if (this.queue.size > 0) {
+            await this.drainTick();
+        }
+    }
+    persist() {
+        const state = {
+            version: 1,
+            savedAt: new Date().toISOString(),
+            pending: Array.from(this.queue),
+        };
+        try {
+            mkdirSync(join(this.deps.workspaceManager.getWorkspacePath(), '.studiograph'), { recursive: true });
+            const tmp = `${this.pendingPath}.tmp`;
+            writeFileSync(tmp, JSON.stringify(state, null, 2), 'utf-8');
+            renameSync(tmp, this.pendingPath);
+        }
+        catch (err) {
+            this.log(`failed to persist asset-index queue: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    loadPersisted() {
+        try {
+            if (!existsSync(this.pendingPath))
+                return null;
+            const parsed = JSON.parse(readFileSync(this.pendingPath, 'utf-8'));
+            if (parsed.version !== 1 || !Array.isArray(parsed.pending))
+                return null;
+            return parsed;
+        }
+        catch (err) {
+            this.log(`failed to load asset-index queue: ${err instanceof Error ? err.message : err}`);
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=asset-index-queue.js.map

package/dist/server/asset-index-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-index-queue.js","sourceRoot":"","sources":["../../src/server/asset-index-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AACpF,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EACL,eAAe,GAGhB,MAAM,kCAAkC,CAAC;AA8B1C,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEnC,MAAM,OAAO,eAAe;IAClB,IAAI,CAAsB;IAC1B,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAC1B,KAAK,GAA0C,IAAI,CAAC;IACpD,QAAQ,GAAG,KAAK,CAAC;IACjB,WAAW,CAAS;IACpB,UAAU,CAAS;IACnB,GAAG,CAAwB;IAEnC,YAAY,IAAyB;QACnC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,mBAAmB,CAAC;QACzD,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAClC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,gBAAgB,EAAE,EAAE,cAAc,EAAE,0BAA0B,CAAC,CAAC;IAChH,CAAC;IAED,4CAA4C;IAC5C,KAAK;QACH,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO;QACvB,0DAA0D;QAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QACvC,IAAI,SAAS;YAAE,KAAK,MAAM,CAAC,IAAI,SAAS,CAAC,OAAO;gBAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACpE,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QAC5E,+DAA+D;QAC9D,IAAI,CAAC,KAAa,CAAC,KAAK,EAAE,EAAE,CAAC;IAChC,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,OAAe;QACrB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;IAED,qEAAqE;IACrE,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,aAAa;QACjB,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QACvC,IAAI,SAAS;YAAE,KAAK,MAAM,CAAC,IAAI,SAAS,CAAC,OAAO;gBAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACpE,wEAAwE;QACxE,OAAO,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QAClE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,uCAAuC;QAC5E,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;YAC3C,uEAAuE;YACvE,KAAK,MAAM,CAAC,IAAI,OAAO;gBAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YAC9C,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,OAAO,GAAG,CAAC;QACb,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACxB,CAAC;IACH,CAAC;IAED,2DAA2D;IACnD,KAAK,CAAC,SAAS;QACrB,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO;QAClC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,4EAA4E;QAC5E,qEAAqE;QACrE,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,+DAA+D;YAC/D,KAAK,MAAM,CAAC,IAAI,KAAK;gBAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACzC,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,IAAI,CAAC,GAAG,CAAC,2BAA2B,KAAK,CAAC,IAAI,MAAM,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;QAClG,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACxB,CAAC;IACH,CAAC;IAED,iFAAiF;IACzE,KAAK,CAAC,QAAQ,CAAC,UAA2C;QAChE,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;QACtC,MAAM,GAAG,GAAG,MAAM,eAAe,CAC/B;YACE,gBAAgB,EAAE,IAAI,CAAC,IAAI,CAAC,gBAAgB;YAC5C,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,aAAa,EAAE,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,gBAAgB,EAAE;YAC5D,aAAa,EAAE,GAAG,CAAC,aAAa;YAChC,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;SACzC,EACD,EAAE,UAAU,EAAE,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CACpG,CAAC;QACF,IAAI,GAAG,CAAC,OAAO,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,WAAW,GAAG,CAAC,EAAE,CAAC;YAC7D,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,CAAC,OAAO,aAAa,GAAG,CAAC,MAAM,YAAY,GAAG,CAAC,WAAW,aAAa,GAAG,CAAC,eAAe,aAAa,CAAC,CAAC;QAClI,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,oEAAoE;IACpE,KAAK,CAAC,QAAQ;QACZ,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;QACD,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;QACzB,CAAC;IACH,CAAC;IAEO,OAAO;QACb,MAAM,KAAK,GAAmB;YAC5B,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACjC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;SAChC,CAAC;QACF,IAAI,CAAC;YACH,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,gBAAgB,EAAE,EAAE,cAAc,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACpG,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,WAAW,MAAM,CAAC;YACtC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YAC5D,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,GAAG,CAAC,wCAAwC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;QAC/F,CAAC;IACH,CAAC;IAEO,aAAa;QACnB,IAAI,CAAC;YACH,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAmB,CAAC;YACrF,IAAI,MAAM,CAAC,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;gBAAE,OAAO,IAAI,CAAC;YACxE,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,GAAG,CAAC,qCAAqC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;YAC1F,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;CACF"}

package/dist/server/body-write-coordinator.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Body-write coordinator — single critical section for entity markdown body writes.
+ *
+ * Owns the safe path that every server-side surface (autosave PUT, MCP
+ * update_entity, agent tools, event processor) shares. The contract:
+ *
+ *   1. assertWritable gate (server-write only — autosave is the client's
+ *      own write and must not be refused). Folded into lock acquisition so
+ *      a throwing gate releases the lock cleanly.
+ *   2. Per-doc lock — serializes server-side body writes for the same doc.
+ *      Inbound client MSG_SYNC frames queue while held (see
+ *      yjsManager.withDocLock + msgSyncQueue).
+ *   3. Base-hash precondition (autosave 412 path). Read inside the lock so
+ *      we see prior locked writes before deciding.
+ *   4. Atomic disk write via MarkdownService (tmp-write + fsync + rename).
+ *   5. mdRevisionHash bookkeeping (yjsManager.recordDiskBody) so the next
+ *      persistence flush captures the post-write state.
+ *   6. Git commit. On failure, register the dirty file with SessionManager
+ *      (if wired) and surface `CommitFailedDirtyError` to the caller.
+ *   7. Server-write only: post-commit `applyAgentContent` broadcast to the
+ *      live Y.Doc. Autosave skips this — its content originated in the
+ *      live Y.Doc; re-applying would race in-flight keystrokes.
+ *
+ * Scope boundary: body writes only. Structural ops (rename, delete,
+ * changeType, move, folder ops) keep their own paths on graph.ts using
+ * the existing transaction — they have a different concurrency profile
+ * (no per-doc lock, no base-hash precondition) and routing them through
+ * here would create a god-class.
+ *
+ * Also exposes `reconcileFromDisk` — the explicit external-disk-change
+ * primitive callable from startup boot, git-pull event handlers, and
+ * dev-tools "reload from disk". Not called from the normal write path.
+ */
+import type { GitUser } from '../services/git.js';
+import type { EntityData } from '../core/validation.js';
+/**
+ * Minimal surface the coordinator needs from YjsManager. Defined as an
+ * interface (rather than importing the concrete class) so unit tests can
+ * inject a fake without spinning up the real Y.Doc machinery.
+ */
+export interface BodyWriteYjsHooks {
+    assertWritable(docName: string): void;
+    withDocLock<T>(docName: string, fn: () => Promise<T>): Promise<T>;
+    applyAgentContent(docName: string, target: string): {
+        applied: 'no-doc' | 'unseeded' | 'ok';
+    };
+    recordDiskBody(docName: string, body: string): void;
+    reconcileFromDisk(docName: string): void;
+    /** Live body for a seeded Y.Doc, or null when no trustworthy live state
+     *  exists (no doc loaded / unseeded). Read side of the live-vs-disk gap.
+     *  Optional so coordinator-less / fake-hook test setups need not implement
+     *  it — `peekLiveBody` then reports null (disk is authoritative). */
+    peekLiveBody?(docName: string): string | null;
+    /** docNames of every currently-loaded Y.Doc. Optional so fake-hook test
+     *  setups need not implement it — `activeDocNames` then reports []. */
+    getActiveDocNames?(): string[];
+}
+/** Minimal SessionManager surface used by the coordinator. */
+export interface BodyWriteSessionHook {
+    markDirty(repo: string, user: GitUser, entityType: string, entityId: string, filePath: string): void;
+}
+/**
+ * Narrow commit surface, injected so the coordinator never reaches back
+ * through WorkspaceManager → getGraph → getGitService (which made a
+ * Graph → Coordinator → WorkspaceManager → Graph triangle). The composition
+ * root owns how a body write becomes a git commit.
+ *
+ * Contract: resolve when the commit lands (or is intentionally a no-op,
+ * e.g. a repo with no GitService). Throw to signal commit failure — the
+ * coordinator then registers the dirty file and surfaces
+ * {@link CommitFailedDirtyError}.
+ */
+export interface BodyWriteCommitHook {
+    commit(coords: EntityCoords, actor: GitUser, message: string): Promise<void>;
+}
+export interface EntityCoords {
+    repo: string;
+    entityType: string;
+    entityId: string;
+    /** Absolute path on disk where the markdown lives. */
+    entityPath: string;
+}
+export type BodyWriteSource = 'autosave' | 'server-write';
+export interface BodyWriteOptions {
+    /**
+     * Produce the frontmatter to persist, given the CURRENT on-disk
+     * frontmatter. Invoked INSIDE the per-doc lock so the merge happens
+     * against fresh disk state — a content-only autosave that waited on the
+     * lock won't clobber a metadata-only edit that committed during the wait.
+     */
+    prepareFrontmatter: (currentDiskFrontmatter: EntityData) => EntityData;
+    /** Optional precondition: SHA-256 hex of expected current body. */
+    baseHash?: string;
+    /** Required provenance — gates broadcast + assertWritable. */
+    source: BodyWriteSource;
+    /** Commit author. */
+    actor: GitUser;
+    /** Skip git commit (caller will commit later, e.g. import flow). */
+    skipCommit?: boolean;
+    /** Override commit message. */
+    commitMessage?: string;
+}
+export interface BodyWriteResult {
+    /**
+     * Post-commit broadcast disposition:
+     *  - 'ok'              applied to the live Y.Doc.
+     *  - 'no-doc'          no live editor open — disk write is the only effect.
+     *  - 'unseeded'        Y.Doc exists but hadn't synced; nothing to apply to.
+     *  - 'skipped'         autosave path — content originated in the live
+     *                      Y.Doc, so re-applying would race in-flight keystrokes.
+     *  - 'broadcast-failed' disk + git landed, but applyAgentContent threw.
+     *                      Clients were notified via a doc_conflict frame; the
+     *                      write itself succeeded. Distinct from 'ok' so
+     *                      observability can tell a clean apply from a recovered
+     *                      one rather than the failure hiding behind a success.
+     */
+    broadcast: 'ok' | 'no-doc' | 'unseeded' | 'skipped' | 'broadcast-failed';
+}
+export declare class BodyWriteCoordinator {
+    private commitHook;
+    private yjs;
+    private sessionManager?;
+    private markdownService;
+    constructor(commitHook: BodyWriteCommitHook, yjs: BodyWriteYjsHooks, sessionManager?: BodyWriteSessionHook | undefined);
+    /**
+     * Atomically write a body+frontmatter to disk, commit, and (for
+     * server-write) broadcast to live editors. The single body-write
+     * critical section shared by autosave + MCP + agent + event processor.
+     */
+    writeBody(coords: EntityCoords, body: string, opts: BodyWriteOptions): Promise<BodyWriteResult>;
+    /**
+     * Reconcile a live Y.Doc against the latest .md file on disk. EXPLICIT
+     * external-disk-change primitive — call this from startup boot, git-pull
+     * event handlers, and dev-tools "reload from disk" only. NOT called from
+     * the normal write path; server-side body writes route through
+     * {@link writeBody}, which broadcasts via `applyAgentContent` under the
+     * per-doc lock.
+     *
+     * Acquires the per-doc lock so a reconcile mid-write composes with the
+     * Phase 2 MSG_SYNC queue + write serialization.
+     */
+    reconcileFromDisk(coords: EntityCoords): Promise<void>;
+    /**
+     * Live body for an entity if a seeded editor doc is open, else null.
+     * Synchronous and lock-free — a point-in-time peek used by lossless reads
+     * (get_entity) and the asset-drop guard so they see the body the user is
+     * actually editing, not just the last-persisted disk state.
+     */
+    peekLiveBody(coords: {
+        repo: string;
+        entityType: string;
+        entityId: string;
+    }): string | null;
+    /**
+     * docNames of every Y.Doc the editor layer currently has loaded. Empty when
+     * no editor layer is wired (CLI/tests). Lets callers (e.g.
+     * `graph.pullAndReconcile`) cheaply decide whether any open editor needs a
+     * disk reconcile before doing per-file work.
+     */
+    activeDocNames(): string[];
+}

package/dist/server/body-write-coordinator.js

@@ -0,0 +1,182 @@
+/**
+ * Body-write coordinator — single critical section for entity markdown body writes.
+ *
+ * Owns the safe path that every server-side surface (autosave PUT, MCP
+ * update_entity, agent tools, event processor) shares. The contract:
+ *
+ *   1. assertWritable gate (server-write only — autosave is the client's
+ *      own write and must not be refused). Folded into lock acquisition so
+ *      a throwing gate releases the lock cleanly.
+ *   2. Per-doc lock — serializes server-side body writes for the same doc.
+ *      Inbound client MSG_SYNC frames queue while held (see
+ *      yjsManager.withDocLock + msgSyncQueue).
+ *   3. Base-hash precondition (autosave 412 path). Read inside the lock so
+ *      we see prior locked writes before deciding.
+ *   4. Atomic disk write via MarkdownService (tmp-write + fsync + rename).
+ *   5. mdRevisionHash bookkeeping (yjsManager.recordDiskBody) so the next
+ *      persistence flush captures the post-write state.
+ *   6. Git commit. On failure, register the dirty file with SessionManager
+ *      (if wired) and surface `CommitFailedDirtyError` to the caller.
+ *   7. Server-write only: post-commit `applyAgentContent` broadcast to the
+ *      live Y.Doc. Autosave skips this — its content originated in the
+ *      live Y.Doc; re-applying would race in-flight keystrokes.
+ *
+ * Scope boundary: body writes only. Structural ops (rename, delete,
+ * changeType, move, folder ops) keep their own paths on graph.ts using
+ * the existing transaction — they have a different concurrency profile
+ * (no per-doc lock, no base-hash precondition) and routing them through
+ * here would create a god-class.
+ *
+ * Also exposes `reconcileFromDisk` — the explicit external-disk-change
+ * primitive callable from startup boot, git-pull event handlers, and
+ * dev-tools "reload from disk". Not called from the normal write path.
+ */
+import { createHash } from 'node:crypto';
+import { MarkdownService } from '../services/markdown.js';
+import { CommitFailedDirtyError, StaleBaseRevisionError } from '../core/graph.js';
+function sha256OfBody(body) {
+    return createHash('sha256').update(body, 'utf-8').digest('hex');
+}
+export class BodyWriteCoordinator {
+    commitHook;
+    yjs;
+    sessionManager;
+    markdownService = new MarkdownService();
+    constructor(commitHook, yjs, sessionManager) {
+        this.commitHook = commitHook;
+        this.yjs = yjs;
+        this.sessionManager = sessionManager;
+    }
+    /**
+     * Atomically write a body+frontmatter to disk, commit, and (for
+     * server-write) broadcast to live editors. The single body-write
+     * critical section shared by autosave + MCP + agent + event processor.
+     */
+    async writeBody(coords, body, opts) {
+        const docName = `${coords.repo}/${coords.entityType}/${coords.entityId}`;
+        return this.yjs.withDocLock(docName, async () => {
+            // assertWritable for server-write (autosave is the client's own write
+            // and never refused). Inside the lock so a throwing gate releases via
+            // withDocLock's try/finally — without that, a future change could
+            // deadlock the write path.
+            if (opts.source === 'server-write') {
+                this.yjs.assertWritable(docName);
+            }
+            // Single parse inside the lock: yields the current body (for the
+            // base-hash precondition) AND the current frontmatter (to merge
+            // against). Both must reflect any prior locked write before we decide.
+            const current = this.markdownService.parseFile(coords.entityPath);
+            // Optimistic-concurrency check.
+            if (opts.baseHash !== undefined) {
+                const currentHash = sha256OfBody(current.content);
+                if (currentHash !== opts.baseHash) {
+                    throw new StaleBaseRevisionError(coords.entityType, coords.entityId, opts.baseHash, currentHash);
+                }
+            }
+            // Merge frontmatter against fresh on-disk state, inside the lock.
+            const frontmatter = opts.prepareFrontmatter(current.frontmatter);
+            this.markdownService.writeFile(coords.entityPath, {
+                frontmatter,
+                content: body,
+                wikilinks: this.markdownService.extractWikilinks(body, frontmatter),
+            });
+            // Pin the live entry.mdRevisionHash to disk state. No-op when no
+            // Y.Doc is loaded for this entity.
+            try {
+                this.yjs.recordDiskBody(docName, body);
+            }
+            catch (err) {
+                console.warn(`[coordinator] recordDiskBody failed for ${coords.entityType}/${coords.entityId}:`, err);
+            }
+            if (!opts.skipCommit) {
+                const message = opts.commitMessage ?? `Update ${coords.entityType}: ${coords.entityId}`;
+                try {
+                    await this.commitHook.commit(coords, opts.actor, message);
+                }
+                catch (err) {
+                    // Disk write already landed; commit failed. Register the
+                    // dirty file with sessionManager (if wired) so the existing
+                    // dirty-flush retry has a chance to recover. Then surface a
+                    // typed error so the caller knows the repo is dirty.
+                    try {
+                        this.sessionManager?.markDirty(coords.repo, opts.actor, coords.entityType, coords.entityId, coords.entityPath);
+                    }
+                    catch (registerErr) {
+                        console.warn(`[coordinator] markDirty failed for ${coords.entityType}/${coords.entityId}:`, registerErr);
+                    }
+                    throw new CommitFailedDirtyError(coords.entityType, coords.entityId, coords.entityPath, err);
+                }
+            }
+            // Server-write body updates apply to the live Y.Doc AFTER commit.
+            // Returns 'no-doc' / 'unseeded' when there's no live editor — the
+            // disk write is the only side effect, which is correct.
+            // Autosave does NOT re-apply: its content originated in the live
+            // Y.Doc and re-applying would race in-flight keystrokes typed
+            // during the PUT round-trip.
+            if (opts.source === 'server-write') {
+                // Only propagate to the live Y.Doc when the body actually CHANGED on
+                // disk (`current.content` is the pre-write disk body, read above inside
+                // this lock). A server-write whose body equals disk — e.g. an agent
+                // that meant to change only frontmatter but echoed back the unchanged
+                // body — must NOT applyAgentContent: `applyTextDiff(ytext, body)` would
+                // wipe a live editor's un-autosaved edits to a body this write never
+                // touched. (The retired LiveEditorPendingError gate refused the whole
+                // write here; this narrower guard preserves the no-op-body case while
+                // still merging real body changes.)
+                if (body === current.content) {
+                    return { broadcast: 'skipped' };
+                }
+                try {
+                    const { applied } = this.yjs.applyAgentContent(docName, body);
+                    return { broadcast: applied };
+                }
+                catch (err) {
+                    // applyAgentContent already sent a doc_conflict frame to live
+                    // clients. Log but do not rethrow — disk + git are
+                    // authoritative; surfacing the error to the caller would
+                    // suggest the write failed when in fact only the Y.Doc broadcast
+                    // did.
+                    console.warn(`[coordinator] applyAgentContent failed post-commit for ${coords.entityType}/${coords.entityId} — clients notified via doc_conflict`, err);
+                    return { broadcast: 'broadcast-failed' };
+                }
+            }
+            return { broadcast: 'skipped' };
+        });
+    }
+    /**
+     * Reconcile a live Y.Doc against the latest .md file on disk. EXPLICIT
+     * external-disk-change primitive — call this from startup boot, git-pull
+     * event handlers, and dev-tools "reload from disk" only. NOT called from
+     * the normal write path; server-side body writes route through
+     * {@link writeBody}, which broadcasts via `applyAgentContent` under the
+     * per-doc lock.
+     *
+     * Acquires the per-doc lock so a reconcile mid-write composes with the
+     * Phase 2 MSG_SYNC queue + write serialization.
+     */
+    async reconcileFromDisk(coords) {
+        const docName = `${coords.repo}/${coords.entityType}/${coords.entityId}`;
+        await this.yjs.withDocLock(docName, async () => {
+            this.yjs.reconcileFromDisk(docName);
+        });
+    }
+    /**
+     * Live body for an entity if a seeded editor doc is open, else null.
+     * Synchronous and lock-free — a point-in-time peek used by lossless reads
+     * (get_entity) and the asset-drop guard so they see the body the user is
+     * actually editing, not just the last-persisted disk state.
+     */
+    peekLiveBody(coords) {
+        return this.yjs.peekLiveBody?.(`${coords.repo}/${coords.entityType}/${coords.entityId}`) ?? null;
+    }
+    /**
+     * docNames of every Y.Doc the editor layer currently has loaded. Empty when
+     * no editor layer is wired (CLI/tests). Lets callers (e.g.
+     * `graph.pullAndReconcile`) cheaply decide whether any open editor needs a
+     * disk reconcile before doing per-file work.
+     */
+    activeDocNames() {
+        return this.yjs.getActiveDocNames?.() ?? [];
+    }
+}
+//# sourceMappingURL=body-write-coordinator.js.map

package/dist/server/body-write-coordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"body-write-coordinator.js","sourceRoot":"","sources":["../../src/server/body-write-coordinator.ts"],"names":[],"mappings":"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"}

package/dist/server/cloud-billing-flow.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Cloud-inference billing flow helpers.
+ *
+ * Wrap a single hosted-inference run in the Studiograph Cloud
+ * reserve → settle/release lifecycle. Shared by every server route that
+ * drives the agent (chat + quick capture + the import pipeline that calls
+ * capture), so hosted inference is metered consistently — not just on chat.
+ *
+ * Semantics (unchanged from the original chat.ts implementation):
+ *  - reserve: on failure, throw only when billing is REQUIRED; otherwise log
+ *    and proceed unmetered (best-effort).
+ *  - settle: report actual usage; release the reservation when there was no
+ *    billable usage.
+ *  - release: return an unsettled reservation (error/abort path).
+ *
+ * When Cloud billing isn't configured (self-hosted / non-managed), the client
+ * is not configured: reserve() returns null and settle/release no-op, so local
+ * behavior is unchanged.
+ */
+import { createCloudInferenceBillingClient, type CloudInferenceReservation, type InferenceUsageSummary } from '../services/cloud-inference-billing.js';
+type CloudBillingClient = ReturnType<typeof createCloudInferenceBillingClient>;
+/** Minimal structural view of the orchestrator — avoids a circular import. */
+interface ModelSelector {
+    getModelSelection(): {
+        provider: string;
+        modelId: string;
+    };
+}
+export declare function reserveCloudInference(cloudBilling: CloudBillingClient, agent: ModelSelector, description: string): Promise<CloudInferenceReservation | null>;
+export declare function settleCloudInference(cloudBilling: CloudBillingClient, reservation: CloudInferenceReservation | null, usage: InferenceUsageSummary | undefined): Promise<void>;
+export declare function releaseCloudInference(cloudBilling: CloudBillingClient, reservation: CloudInferenceReservation | null, reason: string): Promise<void>;
+export {};

package/dist/server/cloud-billing-flow.js

@@ -0,0 +1,75 @@
+/**
+ * Cloud-inference billing flow helpers.
+ *
+ * Wrap a single hosted-inference run in the Studiograph Cloud
+ * reserve → settle/release lifecycle. Shared by every server route that
+ * drives the agent (chat + quick capture + the import pipeline that calls
+ * capture), so hosted inference is metered consistently — not just on chat.
+ *
+ * Semantics (unchanged from the original chat.ts implementation):
+ *  - reserve: on failure, throw only when billing is REQUIRED; otherwise log
+ *    and proceed unmetered (best-effort).
+ *  - settle: report actual usage; release the reservation when there was no
+ *    billable usage.
+ *  - release: return an unsettled reservation (error/abort path).
+ *
+ * When Cloud billing isn't configured (self-hosted / non-managed), the client
+ * is not configured: reserve() returns null and settle/release no-op, so local
+ * behavior is unchanged.
+ */
+import { createInferenceUsageSummary, inferenceUsageToBillableCents, } from '../services/cloud-inference-billing.js';
+import { log } from '../utils/log.js';
+export async function reserveCloudInference(cloudBilling, agent, description) {
+    try {
+        const model = agent.getModelSelection();
+        return await cloudBilling.reserve({
+            estimatedCents: cloudBilling.estimateCents(),
+            provider: model.provider,
+            model: model.modelId,
+            requestId: cloudBilling.nextRequestId('chat'),
+            description,
+        });
+    }
+    catch (err) {
+        if (cloudBilling.isRequired())
+            throw err;
+        log.warn(`[cloud-billing] reservation skipped: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+export async function settleCloudInference(cloudBilling, reservation, usage) {
+    if (!reservation)
+        return;
+    const summary = usage ?? createInferenceUsageSummary();
+    const actualCents = inferenceUsageToBillableCents(summary);
+    try {
+        if (actualCents === null) {
+            await cloudBilling.release(reservation, 'No billable model usage was reported.');
+            return;
+        }
+        await cloudBilling.settle(reservation, {
+            actualCents,
+            inputTokens: summary.inputTokens,
+            outputTokens: summary.outputTokens,
+            description: 'Settled hosted Studiograph inference.',
+        });
+    }
+    catch (err) {
+        if (cloudBilling.isRequired())
+            throw err;
+        log.warn(`[cloud-billing] settlement skipped: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export async function releaseCloudInference(cloudBilling, reservation, reason) {
+    if (!reservation)
+        return;
+    try {
+        await cloudBilling.release(reservation, reason);
+    }
+    catch (err) {
+        if (cloudBilling.isRequired())
+            throw err;
+        log.warn(`[cloud-billing] release skipped: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+//# sourceMappingURL=cloud-billing-flow.js.map