@meetless/mla 0.1.4 → 0.1.6

package/dist/lib/agent-memory-capture/containment.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_FILE_BYTES = void 0;
+exports.enumerateEligibleFiles = enumerateEligibleFiles;
+// src/lib/agent-memory-capture/containment.ts
+//
+// Enumerate the eligible memory files under a binding's directory (§4 step 3),
+// with realpath containment so a symlink can never point the collector at a file
+// outside the consented directory (CONTAINMENT-1). MVP scans DIRECT `.md`
+// children only (the corpus is flat); nesting support is deferred until topic
+// files actually nest.
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// Fixed max byte size (a constant, not user-configurable yet, per SECRET-1 /
+// §4). Real memory topic files are 1-6 KB; the 188 KB MEMORY.md index is
+// denylisted. A file above this is a processing failure (oversized), never a
+// silent truncate-and-send.
+exports.MAX_FILE_BYTES = 256 * 1024;
+// Never a capture source even if it somehow carried a project type: the index
+// is one-line pointers, not durable claims. Type-filtering already excludes it
+// (it has no frontmatter), but the explicit denylist is belt-and-suspenders.
+const DENYLIST = new Set(["memory.md"]);
+function isContained(child, parentReal) {
+    return child === parentReal || child.startsWith(parentReal + node_path_1.sep);
+}
+// Enumerate direct `.md` children that are regular files, realpath-contained,
+// not denylisted, with their byte size. Returns complete=false on ANY iteration
+// error so a partial scan never drives deletions.
+function enumerateEligibleFiles(memoryDir) {
+    let memoryReal;
+    try {
+        memoryReal = (0, node_fs_1.realpathSync)(memoryDir);
+    }
+    catch {
+        return { files: [], complete: false };
+    }
+    let names;
+    try {
+        names = (0, node_fs_1.readdirSync)(memoryReal);
+    }
+    catch {
+        return { files: [], complete: false };
+    }
+    const files = [];
+    let complete = true;
+    for (const name of names) {
+        if (!name.toLowerCase().endsWith(".md"))
+            continue;
+        if (DENYLIST.has(name.toLowerCase()))
+            continue;
+        const absPath = (0, node_path_1.join)(memoryReal, name);
+        let realPath;
+        let bytes;
+        try {
+            realPath = (0, node_fs_1.realpathSync)(absPath);
+            const st = (0, node_fs_1.statSync)(realPath);
+            if (!st.isFile())
+                continue; // directories, fifos, etc.
+            bytes = st.size;
+        }
+        catch {
+            // A single entry that vanished/raced mid-scan makes THIS pass incomplete,
+            // so we do not mistake other present files' absence for deletions.
+            complete = false;
+            continue;
+        }
+        // Symlink escape guard: the resolved target must stay inside the consented
+        // directory. A symlink pointing outside is silently excluded.
+        if (!isContained(realPath, memoryReal))
+            continue;
+        files.push({ relativePath: name, absPath, realPath, bytes });
+    }
+    return { files, complete };
+}

package/dist/lib/agent-memory-capture/ledger.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readLedger = readLedger;
+exports.writeLedger = writeLedger;
+// src/lib/agent-memory-capture/ledger.ts
+//
+// The thin per-binding dry-run ledger (§4). It stores only what the COLLECTOR
+// needs to avoid re-emitting events for unchanged content; it deliberately does
+// NOT mirror server processing/extraction state (two state machines would
+// diverge). Keyed by a file's path relative to memoryDir.
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const config_1 = require("../config");
+const paths_1 = require("./paths");
+function emptyLedger() {
+    return { version: 1, entries: {} };
+}
+function readLedger(bindingId, home = config_1.HOME) {
+    let raw;
+    try {
+        raw = (0, node_fs_1.readFileSync)((0, paths_1.ledgerPath)(bindingId, home), "utf8");
+    }
+    catch {
+        return emptyLedger();
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed.entries !== "object" || parsed.entries === null) {
+            return emptyLedger();
+        }
+        return { version: 1, entries: parsed.entries };
+    }
+    catch {
+        return emptyLedger();
+    }
+}
+function writeLedger(bindingId, ledger, home = config_1.HOME) {
+    const dest = (0, paths_1.ledgerPath)(bindingId, home);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(dest), { recursive: true });
+    const tmp = `${dest}.${process.pid}.tmp`;
+    (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(ledger, null, 2) + "\n", { mode: 0o600 });
+    (0, node_fs_1.renameSync)(tmp, dest);
+}

package/dist/lib/agent-memory-capture/live-collector.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_UPLOADS_PER_PASS = void 0;
+exports.liveCaptureEnabled = liveCaptureEnabled;
+exports.appendLiveDecisions = appendLiveDecisions;
+exports.runLiveCollector = runLiveCollector;
+// src/lib/agent-memory-capture/live-collector.ts
+//
+// Orchestrates one LIVE collection + upload pass across all enabled bindings
+// (proposal §4 lifecycle + §6 Phase 2A). Mirrors the dry-run collector.ts shape
+// exactly (per-binding lock, fail-soft per binding, append only the actionable
+// outcomes to a metadata-only JSONL), but the per-file engine is
+// collectAndUploadOnce, which ACTUALLY uploads/withdraws against intel.
+//
+// GATING (default OFF, fail-closed): live capture never runs unless it is
+// explicitly turned on (liveCaptureEnabled). The proposal wires this into the
+// existing Stop auto-index worker (NOT a new hook), so an operator opts in once
+// via MEETLESS_AGENT_MEMORY_LIVE; with the flag unset the worker calls nothing.
+// The flag is necessary but NOT sufficient: there must also be at least one
+// consented binding (CONSENT-1) and a resolvable actor identity, or the pass is
+// a no-op. We never upload anonymously.
+//
+// SECRET-1: the per-file engine runs the credential denylist fail-closed before
+// any byte leaves the machine. This orchestrator adds a second guard, the
+// no-backfill per-pass upload cap (§6), so the FIRST live pass cannot dump the
+// whole backlog at once; the cap drains over successive passes.
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const config_1 = require("../config");
+const lock_1 = require("./lock");
+const binding_1 = require("./binding");
+const live_pipeline_1 = require("./live-pipeline");
+const paths_1 = require("./paths");
+const upsert_client_1 = require("./upsert-client");
+// Default per-pass upload cap (no-backfill, §6). Conservative on purpose: the
+// first live pass over a backlog uploads at most this many revisions, the rest
+// defer and drain over later Stops. Override with MEETLESS_AGENT_MEMORY_MAX_UPLOADS.
+exports.DEFAULT_MAX_UPLOADS_PER_PASS = 25;
+// Live capture is DEFAULT OFF. Returns true only when the flag is explicitly an
+// affirmative value; unset / "0" / "false" / anything else is OFF (fail-closed).
+// Pure predicate so the worker and the CLI can share one gate and a test can
+// assert it without side effects.
+function liveCaptureEnabled(env = process.env) {
+    const v = (env.MEETLESS_AGENT_MEMORY_LIVE ?? "").trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes" || v === "on";
+}
+function resolveMaxUploads(env = process.env) {
+    const raw = (env.MEETLESS_AGENT_MEMORY_MAX_UPLOADS ?? "").trim();
+    if (!raw)
+        return exports.DEFAULT_MAX_UPLOADS_PER_PASS;
+    const n = Number(raw);
+    return Number.isInteger(n) && n > 0 ? n : exports.DEFAULT_MAX_UPLOADS_PER_PASS;
+}
+// Append the actionable live outcomes for one binding to its JSONL. Metadata
+// only (the LiveRecord shape: sourceId, relativePath, hash, bytes, outcome,
+// reason, secretRuleIds, revisionId, serverOutcome, observedAt). NEVER raw
+// content. unchanged/skipped no-ops are dropped so the log stays bounded.
+function appendLiveDecisions(bindingId, records, home = config_1.HOME) {
+    const actionable = records.filter((r) => (0, live_pipeline_1.isLiveActionable)(r.outcome));
+    if (actionable.length === 0)
+        return 0;
+    const dest = (0, paths_1.liveDecisionLogPath)(bindingId, home);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(dest), { recursive: true });
+    const lines = actionable.map((r) => JSON.stringify(r)).join("\n") + "\n";
+    (0, node_fs_1.appendFileSync)(dest, lines, { mode: 0o600 });
+    return actionable.length;
+}
+async function runForBindingLive(binding, deps) {
+    const home = deps.home ?? config_1.HOME;
+    // Same per-binding lock as the dry-run collector: dry-run and live passes are
+    // mutually exclusive on a binding (they share the lock namespace), so they can
+    // never interleave and corrupt either ledger.
+    const lock = (0, lock_1.acquireBindingLock)(binding.bindingId, deps.nowIso, home);
+    if (!lock) {
+        return { bindingId: binding.bindingId, summary: null, locked: false, appended: 0 };
+    }
+    try {
+        const summary = await (0, live_pipeline_1.collectAndUploadOnce)(binding, deps);
+        const appended = appendLiveDecisions(binding.bindingId, summary.records, home);
+        return { bindingId: binding.bindingId, summary, locked: true, appended };
+    }
+    finally {
+        lock.release();
+    }
+}
+// Build the real UpsertClient + actor from config, or fail-closed. Returns null
+// when there is no resolvable actor identity (never upload anonymously) or the
+// config cannot be read. Skipped entirely when a client is injected (tests).
+function resolveClientAndActor(opts) {
+    if (opts.client) {
+        // An injected client with no actor is a test misconfiguration; require both.
+        if (!opts.actor)
+            return null;
+        return { client: opts.client, actor: opts.actor };
+    }
+    let cfg;
+    try {
+        cfg = opts.cfg ?? (0, config_1.readConfig)();
+    }
+    catch {
+        return null;
+    }
+    const actor = (opts.actor ?? cfg.actorUserId ?? "").trim();
+    if (!actor)
+        return null; // not logged in -> never upload anonymously.
+    return { client: (0, upsert_client_1.createIntelUpsertClient)(cfg), actor };
+}
+// Run a LIVE pass over every enabled binding. Fail-soft per binding: one
+// binding's error never aborts the others. Returns [] WITHOUT touching the
+// network when live capture is gated off, when there is no resolvable actor, or
+// when there are no enabled bindings. Async because the per-file engine awaits
+// the network.
+async function runLiveCollector(opts) {
+    const env = opts.env ?? process.env;
+    // Gate 1: the explicit opt-in flag (default off). The worker also checks this
+    // before calling, but re-check here so a direct call can never bypass it.
+    if (!liveCaptureEnabled(env))
+        return [];
+    // Gate 2: a resolvable client + actor (never upload anonymously).
+    const resolved = resolveClientAndActor(opts);
+    if (!resolved)
+        return [];
+    const home = opts.home ?? config_1.HOME;
+    // Gate 3: at least one consented binding (CONSENT-1).
+    const bindings = (0, binding_1.listEnabledBindings)(home);
+    if (bindings.length === 0)
+        return [];
+    const deps = {
+        client: resolved.client,
+        actor: resolved.actor,
+        nowIso: opts.nowIso,
+        home,
+        maxUploadsPerPass: opts.maxUploadsPerPass ?? resolveMaxUploads(env),
+        ...(opts.scan ? { scan: opts.scan } : {}),
+        ...(opts.scannerVersion ? { scannerVersion: opts.scannerVersion } : {}),
+        ...(opts.scannerMode ? { scannerMode: opts.scannerMode } : {}),
+    };
+    const out = [];
+    for (const b of bindings) {
+        try {
+            out.push(await runForBindingLive(b, deps));
+        }
+        catch {
+            out.push({ bindingId: b.bindingId, summary: null, locked: false, appended: 0 });
+        }
+    }
+    return out;
+}

package/dist/lib/agent-memory-capture/live-ledger.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readLiveLedger = readLiveLedger;
+exports.writeLiveLedger = writeLiveLedger;
+// src/lib/agent-memory-capture/live-ledger.ts
+//
+// The per-binding LIVE ledger (§4 "Live"). Unlike the dry-run ledger, this one
+// tracks what the SERVER acknowledged, not what we observed: `lastUploadedHash`
+// advances ONLY on a hash-matched ack (COMMIT-1), so a failed or unverified
+// upload leaves the entry "unsettled" and the next pass re-attempts (RETRY-2).
+// Kept in its own file (liveLedgerPath) so it can never collide with the dry-run
+// ledger on the same binding. Keyed by a file's path relative to memoryDir.
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const config_1 = require("../config");
+const paths_1 = require("./paths");
+function emptyLiveLedger() {
+    return { version: 1, entries: {} };
+}
+function readLiveLedger(bindingId, home = config_1.HOME) {
+    let raw;
+    try {
+        raw = (0, node_fs_1.readFileSync)((0, paths_1.liveLedgerPath)(bindingId, home), "utf8");
+    }
+    catch {
+        return emptyLiveLedger();
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed.entries !== "object" || parsed.entries === null) {
+            return emptyLiveLedger();
+        }
+        return { version: 1, entries: parsed.entries };
+    }
+    catch {
+        return emptyLiveLedger();
+    }
+}
+function writeLiveLedger(bindingId, ledger, home = config_1.HOME) {
+    const dest = (0, paths_1.liveLedgerPath)(bindingId, home);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(dest), { recursive: true });
+    const tmp = `${dest}.${process.pid}.tmp`;
+    (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(ledger, null, 2) + "\n", { mode: 0o600 });
+    (0, node_fs_1.renameSync)(tmp, dest);
+}

package/dist/lib/agent-memory-capture/live-pipeline.js

@@ -0,0 +1,344 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLiveActionable = isLiveActionable;
+exports.collectAndUploadOnce = collectAndUploadOnce;
+// src/lib/agent-memory-capture/live-pipeline.ts
+//
+// The LIVE collection pass (Phase 2A+). Mirrors the dry-run §4 lifecycle router
+// in pipeline.ts but ACTUALLY performs the network ops: it uploads eligible
+// revisions (UPSERT_SOURCE_REVISION) and withdraws reclassified/deleted sources
+// (WITHDRAW_SOURCE), against the injectable `UpsertClient`. It commits the LIVE
+// ledger only on a verified server ack:
+//
+//   COMMIT-1: `lastUploadedHash` advances ONLY after a successful ack whose
+//             server-echoed content hash equals the local hash (or, on older
+//             intel that omits the echo, on a success outcome alone). A failed,
+//             rejected, or hash-mismatched upload leaves the entry unsettled.
+//   RETRY-2:  Because a failed upload never advances `lastUploadedHash`, the next
+//             pass sees the file as still-changed and re-attempts it. A blocked
+//             file is re-evaluated when the scanner version moves.
+//
+// SECRET-1: the credential denylist (`scanForCredentials`, NOT the entropy
+// scanner) runs FAIL-CLOSED before any upload. A credential-format hit withholds
+// the file; a scanner outage withholds the file. Nothing credential-bearing is
+// handed to the client.
+//
+// One immutable byte buffer per file (the dry-run's TOCTOU guard): the bytes
+// hashed, classified, scanned, and uploaded are provably the same bytes.
+const node_fs_1 = require("node:fs");
+const config_1 = require("../config");
+const redactor_1 = require("../redactor");
+const classify_1 = require("./classify");
+const containment_1 = require("./containment");
+const live_ledger_1 = require("./live-ledger");
+const pipeline_1 = require("./pipeline");
+// Only outcomes that represent an actual event are worth persisting to the live
+// JSONL. "unchanged" and "skipped" are emitted every pass; persisting them would
+// grow the log without bound.
+function isLiveActionable(outcome) {
+    return outcome !== "unchanged" && outcome !== "skipped";
+}
+// Run one LIVE collection + upload pass for a single binding. Reads the real
+// directory, performs network ops via the client, and mutates the LIVE ledger.
+// Returns every file's outcome (the collector persists only the actionable ones).
+async function collectAndUploadOnce(binding, deps) {
+    const home = deps.home ?? config_1.HOME;
+    const scan = deps.scan ?? redactor_1.scanForCredentials;
+    const scannerVersion = deps.scannerVersion ?? redactor_1.SECRET_SCANNER_VERSION;
+    // Live is fail-closed by default; "off" is a test-only escape hatch.
+    const scannerMode = deps.scannerMode ?? "block";
+    const now = deps.nowIso;
+    // No-backfill cap (§6). undefined = uncapped; otherwise stop attempting uploads
+    // once this many have been attempted this pass and defer the rest.
+    const cap = deps.maxUploadsPerPass;
+    let uploadAttempts = 0;
+    const ledger = (0, live_ledger_1.readLiveLedger)(binding.bindingId, home);
+    const { files, complete } = (0, containment_1.enumerateEligibleFiles)(binding.memoryDir);
+    const records = [];
+    const present = new Set();
+    let mutated = false;
+    const base = (relativePath, bytes) => ({
+        sourceId: (0, pipeline_1.syntheticSourceId)(binding.bindingId, relativePath),
+        relativePath,
+        bytes,
+        secretRuleIds: [],
+        observedAt: now,
+    });
+    for (const f of files) {
+        present.add(f.relativePath);
+        const sourceId = (0, pipeline_1.syntheticSourceId)(binding.bindingId, f.relativePath);
+        // Oversized: known from stat; never read, never upload, never withdraw.
+        if (f.bytes > containment_1.MAX_FILE_BYTES) {
+            records.push({ ...base(f.relativePath, f.bytes), hash: null, outcome: "failed", reason: "oversized" });
+            continue;
+        }
+        let buf;
+        try {
+            buf = (0, node_fs_1.readFileSync)(f.realPath);
+        }
+        catch {
+            records.push({ ...base(f.relativePath, f.bytes), hash: null, outcome: "failed", reason: "unreadable" });
+            continue;
+        }
+        if (buf.length > containment_1.MAX_FILE_BYTES) {
+            records.push({ ...base(f.relativePath, buf.length), hash: null, outcome: "failed", reason: "oversized" });
+            continue;
+        }
+        const hash = (0, pipeline_1.sha256Hex)(buf);
+        const text = buf.toString("utf8");
+        const cls = (0, classify_1.classifyMemory)(text);
+        const prior = ledger.entries[f.relativePath];
+        if (cls.malformed) {
+            records.push({ ...base(f.relativePath, buf.length), hash, outcome: "failed", reason: "malformed_frontmatter" });
+            continue;
+        }
+        if (cls.type !== "project") {
+            // A previously-tracked project file became non-project: WITHDRAW it. A file
+            // never tracked is simply skipped (it was never uploaded).
+            if (prior) {
+                const res = await deps.client.withdraw({
+                    workspaceId: binding.workspaceId,
+                    actor: deps.actor,
+                    relPath: sourceId,
+                    reason: "reclassified",
+                });
+                if (res.ok) {
+                    delete ledger.entries[f.relativePath];
+                    mutated = true;
+                    records.push({
+                        ...base(f.relativePath, buf.length),
+                        hash,
+                        outcome: "reclassified",
+                        reason: `reclassified project -> ${cls.type ?? "none"}`,
+                    });
+                }
+                else {
+                    // Leave the entry so the next pass retries the withdraw (RETRY-2).
+                    ledger.entries[f.relativePath] = { ...prior, lastAttemptAt: now };
+                    mutated = true;
+                    records.push({
+                        ...base(f.relativePath, buf.length),
+                        hash,
+                        outcome: "failed",
+                        reason: `withdraw_failed (reclassified): ${res.reason}`,
+                    });
+                }
+            }
+            else {
+                records.push({
+                    ...base(f.relativePath, buf.length),
+                    hash,
+                    outcome: "skipped",
+                    reason: cls.type ? `type ${cls.type}` : "no project type",
+                });
+            }
+            continue;
+        }
+        // type === project. If the exact bytes already match what the server acked,
+        // it is settled and clean by construction (we never upload a credential-
+        // bearing file), so short-circuit WITHOUT re-scanning. Clear any stale block
+        // marker (content reverted to the uploaded version).
+        //
+        // LIMITATION (documented, not a bug): this does NOT retroactively re-scan or
+        // withdraw already-uploaded content when the scanner version bumps. RETRY-2's
+        // re-evaluation applies to BLOCKED files, not settled uploads. Once content
+        // is acked it is governed by the KB review rail, not the local scanner.
+        if (prior?.lastUploadedHash === hash) {
+            if (prior.blockedHash || prior.blockedScannerVersion) {
+                const cleared = { ...prior, lastAttemptAt: now };
+                delete cleared.blockedHash;
+                delete cleared.blockedScannerVersion;
+                ledger.entries[f.relativePath] = cleared;
+                mutated = true;
+            }
+            records.push({
+                ...base(f.relativePath, buf.length),
+                hash,
+                outcome: "unchanged",
+                reason: "content identical to last upload",
+            });
+            continue;
+        }
+        // Credential denylist, FAIL-CLOSED (SECRET-1). "off" is the test-only path.
+        let secretRuleIds = [];
+        if (scannerMode !== "off") {
+            try {
+                secretRuleIds = scan(text);
+            }
+            catch {
+                // Scanner outage withholds the file: we cannot prove it is clean.
+                records.push({
+                    ...base(f.relativePath, buf.length),
+                    hash,
+                    outcome: "failed",
+                    reason: "scanner_unavailable",
+                });
+                continue;
+            }
+        }
+        if (scannerMode !== "off" && secretRuleIds.length > 0) {
+            const alreadyBlocked = prior?.blockedHash === hash && prior?.blockedScannerVersion === scannerVersion;
+            if (alreadyBlocked) {
+                records.push({
+                    ...base(f.relativePath, buf.length),
+                    hash,
+                    outcome: "unchanged",
+                    reason: "blocked (unchanged, same scanner)",
+                    secretRuleIds,
+                });
+            }
+            else {
+                // Set the block marker but PRESERVE any prior upload settle (a file can
+                // be blocked at a new revision while an older clean revision is on the
+                // server). Never advance lastUploadedHash here.
+                ledger.entries[f.relativePath] = {
+                    ...(prior ?? {}),
+                    blockedHash: hash,
+                    blockedScannerVersion: scannerVersion,
+                    lastAttemptAt: now,
+                };
+                mutated = true;
+                records.push({
+                    ...base(f.relativePath, buf.length),
+                    hash,
+                    outcome: "blocked",
+                    reason: "credential format matched",
+                    secretRuleIds,
+                });
+            }
+            continue;
+        }
+        // No-backfill cap (§6): once the per-pass upload budget is exhausted, DEFER
+        // the remaining changed+clean files rather than uploading the whole backlog
+        // in one burst. A deferred file is left UNSETTLED (the ledger is untouched),
+        // so the next pass re-attempts it; the backlog drains `cap` files per pass.
+        // Surfaced as a visible `deferred` count, never silently dropped.
+        if (cap !== undefined && uploadAttempts >= cap) {
+            records.push({
+                ...base(f.relativePath, buf.length),
+                hash,
+                outcome: "deferred",
+                reason: "per-pass upload cap reached",
+                secretRuleIds,
+            });
+            continue;
+        }
+        uploadAttempts++;
+        // project + clean + changed/new -> UPLOAD.
+        const res = await deps.client.upsert({
+            workspaceId: binding.workspaceId,
+            actor: deps.actor,
+            relPath: sourceId,
+            content: text,
+            contentHash: hash,
+            bindingId: binding.bindingId,
+            consentedAt: binding.consentedAt,
+        });
+        if (!res.ok || res.outcome === "failed") {
+            // RETRY-2: do NOT advance lastUploadedHash; only stamp an attempt on an
+            // existing entry (never create a bare entry for a never-settled file, so
+            // deletion reconciliation cannot later withdraw something never uploaded).
+            if (prior) {
+                ledger.entries[f.relativePath] = { ...prior, lastAttemptAt: now };
+                mutated = true;
+            }
+            records.push({
+                ...base(f.relativePath, buf.length),
+                hash,
+                outcome: "failed",
+                reason: res.ok ? `server_rejected: ${res.reason}` : res.reason,
+                secretRuleIds,
+            });
+            continue;
+        }
+        // COMMIT-1: if the server echoed its content hash, it MUST equal ours.
+        if (res.serverContentHash !== null && res.serverContentHash !== hash) {
+            if (prior) {
+                ledger.entries[f.relativePath] = { ...prior, lastAttemptAt: now };
+                mutated = true;
+            }
+            records.push({
+                ...base(f.relativePath, buf.length),
+                hash,
+                outcome: "failed",
+                reason: "hash_mismatch",
+                secretRuleIds,
+            });
+            continue;
+        }
+        // COMMIT-1 satisfied. Settle the ledger to this hash; clear any block marker.
+        ledger.entries[f.relativePath] = {
+            lastUploadedHash: hash,
+            lastUploadedRevisionId: res.revisionId ?? undefined,
+            lastLogicalSourceId: res.logicalSourceId ?? undefined,
+            lastSourceId: sourceId,
+            lastAttemptAt: now,
+        };
+        mutated = true;
+        records.push({
+            ...base(f.relativePath, buf.length),
+            hash,
+            outcome: "uploaded",
+            reason: prior?.lastUploadedHash ? "changed" : "new",
+            secretRuleIds,
+            revisionId: res.revisionId,
+            // Map the upsert vocabulary ("created"|"unchanged") onto the record's
+            // create/dedup vocabulary; "unchanged" here means the server already held
+            // these exact bytes under this path (a benign dedup), recorded as such.
+            serverOutcome: res.outcome === "created" ? "created" : "already_exists",
+        });
+    }
+    // Deletions: only when the scan completed (a partial scan must never mistake an
+    // un-enumerated file for a deletion). WITHDRAW each absent tracked source; keep
+    // the entry on a failed withdraw so the next complete pass retries it.
+    if (complete) {
+        for (const rel of Object.keys(ledger.entries)) {
+            if (present.has(rel))
+                continue;
+            const sourceId = (0, pipeline_1.syntheticSourceId)(binding.bindingId, rel);
+            const res = await deps.client.withdraw({
+                workspaceId: binding.workspaceId,
+                actor: deps.actor,
+                relPath: sourceId,
+                reason: "deleted",
+            });
+            if (res.ok) {
+                delete ledger.entries[rel];
+                mutated = true;
+                records.push({
+                    sourceId,
+                    relativePath: rel,
+                    bytes: 0,
+                    hash: null,
+                    outcome: "deleted",
+                    reason: "absent after complete scan",
+                    secretRuleIds: [],
+                    observedAt: now,
+                });
+            }
+            else {
+                ledger.entries[rel] = { ...ledger.entries[rel], lastAttemptAt: now };
+                mutated = true;
+                records.push({
+                    sourceId,
+                    relativePath: rel,
+                    bytes: 0,
+                    hash: null,
+                    outcome: "failed",
+                    reason: `withdraw_failed (deleted): ${res.reason}`,
+                    secretRuleIds: [],
+                    observedAt: now,
+                });
+            }
+        }
+    }
+    if (mutated)
+        (0, live_ledger_1.writeLiveLedger)(binding.bindingId, ledger, home);
+    return {
+        bindingId: binding.bindingId,
+        memoryDir: binding.memoryDir,
+        workspaceId: binding.workspaceId,
+        scanComplete: complete,
+        records,
+    };
+}