@nurix/nustack 0.10.0-dev.10

package/dist/lib/git-sync/core/watch_stream.js

@@ -0,0 +1,86 @@
+import os from "node:os";
+export const WATCH_STREAM_SCHEMA_VERSION = 1;
+const KNOWN_EVENT_TYPES = new Set([
+    "watch_started",
+    "watch_stopped",
+    "binding_status",
+    "wake",
+    "reconcile_started",
+    "reconcile_result",
+    "heartbeat",
+    "error",
+    "upload_started",
+    "upload_result",
+    "history_decision_resolved",
+    "handoff_received",
+    "handoff_evaluated",
+    "decision_required",
+    "handoff_superseded",
+    "handoff_committed",
+    "undo_result",
+    "recovery_bundle_created",
+]);
+export class WatchStreamRedactionError extends Error {
+    field;
+    reason;
+    constructor(field, reason) {
+        super(`watch-stream event withheld — ${reason} in field "${field}"`);
+        this.name = "WatchStreamRedactionError";
+        this.field = field;
+        this.reason = reason;
+    }
+}
+function unsafeReason(value) {
+    if (value.length === 0)
+        return null;
+    if (value.startsWith("/") || /^[A-Za-z]:[\\/]/.test(value))
+        return "absolute path";
+    const home = os.homedir();
+    if (home.length > 1 && value.includes(home))
+        return "home-directory prefix";
+    if (value.includes("adr_") || value.includes("adt_") || value.includes("nustack_npm_")) {
+        return "credential material";
+    }
+    return null;
+}
+export function assertWatchStreamRedacted(event, field = "$") {
+    if (typeof event === "string") {
+        const reason = unsafeReason(event);
+        if (reason)
+            throw new WatchStreamRedactionError(field, reason);
+        return;
+    }
+    if (event === null || typeof event !== "object")
+        return;
+    for (const [key, value] of Object.entries(event)) {
+        assertWatchStreamRedacted(value, `${field}.${key}`);
+    }
+}
+export function createWatchStreamEmitter(writable) {
+    return {
+        emit(input) {
+            const event = {
+                v: WATCH_STREAM_SCHEMA_VERSION,
+                at: new Date().toISOString(),
+                ...input,
+            };
+            assertWatchStreamRedacted(event);
+            writable.write(`${JSON.stringify(event)}\n`);
+            return event;
+        },
+    };
+}
+export function isWatchStreamEnvelope(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const record = value;
+    return (typeof record.v === "number" &&
+        typeof record.event === "string" &&
+        typeof record.at === "string");
+}
+export function isCompatibleWatchStreamVersion(value) {
+    return isWatchStreamEnvelope(value) && value.v === WATCH_STREAM_SCHEMA_VERSION;
+}
+export function isWatchStreamEvent(value) {
+    return isCompatibleWatchStreamVersion(value) && KNOWN_EVENT_TYPES.has(value.event);
+}

package/dist/lib/git-sync/core/watcher.js

@@ -0,0 +1,61 @@
+import { watch as fsWatch, existsSync } from "node:fs";
+import path from "node:path";
+const DEFAULT_DEBOUNCE_MS = 250;
+const REWATCH_DELAY_MS = 50;
+export function watchGitControlPaths(repo, boundBranch, onWake, options = {}) {
+    const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    const watchers = new Set();
+    let timer;
+    let closed = false;
+    const scheduleWake = () => {
+        if (closed)
+            return;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            if (!closed)
+                onWake({ source: "fs" });
+        }, debounceMs);
+    };
+    const watchTarget = (target, recursive) => {
+        if (closed || !existsSync(target))
+            return;
+        try {
+            const watcher = fsWatch(target, { recursive, persistent: false }, () => scheduleWake());
+            watcher.on("error", () => {
+                watchers.delete(watcher);
+                try {
+                    watcher.close();
+                }
+                catch {
+                }
+                if (!closed)
+                    setTimeout(() => watchTarget(target, recursive), REWATCH_DELAY_MS);
+            });
+            watchers.add(watcher);
+        }
+        catch {
+        }
+    };
+    watchTarget(repo.gitDir, false);
+    if (repo.commonDir !== repo.gitDir)
+        watchTarget(repo.commonDir, false);
+    watchTarget(path.join(repo.commonDir, "refs", "heads"), process.platform === "darwin");
+    watchTarget(path.join(repo.commonDir, "refs", "heads", boundBranch), false);
+    return {
+        close() {
+            closed = true;
+            if (timer)
+                clearTimeout(timer);
+            for (const watcher of watchers) {
+                try {
+                    watcher.close();
+                }
+                catch {
+                }
+            }
+            watchers.clear();
+        },
+    };
+}

package/dist/lib/git-sync/inbound/applier.js

@@ -0,0 +1,131 @@
+import { withReconciliationLock } from "../core/reconciliation_lock.js";
+import { resolveRepository, readHeadCommit } from "../core/repository.js";
+import { runGit } from "../core/git_runner.js";
+import { getBindingById } from "../../local_store/bindings.js";
+import { getApplication, upsertApplication, transitionApplicationState, listApplicationsForBinding, } from "../../local_store/handoff_applications.js";
+import { syncBindingEvents, advanceContiguousCursor } from "./event_sync.js";
+import { downloadHandoff } from "./download.js";
+import { evaluateRepositoryTechnicalWait } from "./technical_wait.js";
+import { decideHandoffContent } from "./content_decision.js";
+import { computeStateFingerprint } from "./state_fingerprint.js";
+import { applyCommit, finalizeCommitted } from "./apply_commit.js";
+import { toDownloadBinding, serializeDecisionEvidence } from "./approval.js";
+import { postResultReport } from "./notification.js";
+import { sweepExpiredBundles } from "../recovery/store.js";
+const RECOVERABLE_STATES = ["evaluating", "approved", "applying", "decision_required"];
+function commitLanded(repo, commitId, head) {
+    if (!head)
+        return false;
+    return runGit(repo.repositoryRoot, ["merge-base", "--is-ancestor", commitId, head], { allowFailure: true }).exitCode === 0;
+}
+function recoverInterruptedApplies(store, repo, bindingId) {
+    const head = readHeadCommit(repo);
+    for (const application of listApplicationsForBinding(store, bindingId, RECOVERABLE_STATES)) {
+        const commitId = application.generatedCommitId;
+        if (commitId && commitLanded(repo, commitId, head)) {
+            finalizeCommitted(store, bindingId, application.handoffId, commitId, application.approvedByUserId);
+        }
+    }
+}
+export async function runInboundReconciliation(store, runtime, bindingId) {
+    const binding = getBindingById(store, bindingId);
+    if (!binding)
+        return;
+    const repo = resolveRepository(binding.repositoryRoot);
+    recoverInterruptedApplies(store, repo, bindingId);
+    await sweepExpiredBundles(store, runtime.now ? runtime.now() : Date.now());
+    const eventDeps = { baseUrl: runtime.baseUrl, accessToken: runtime.accessToken, ...runtime.eventDeps };
+    await syncBindingEvents(store, eventDeps, bindingId);
+    for (const application of listApplicationsForBinding(store, bindingId, ["received", "evaluating"])) {
+        await evaluateApplication(store, runtime, binding, repo, application.handoffId);
+    }
+    await advanceContiguousCursor(store, eventDeps, bindingId);
+}
+async function evaluateApplication(store, runtime, binding, repo, handoffId) {
+    const bindingId = binding.id;
+    const current = getApplication(store, handoffId, bindingId);
+    if (!current)
+        return;
+    if (current.state === "received")
+        transitionApplicationState(store, handoffId, bindingId, "evaluating");
+    const downloadDeps = { baseUrl: runtime.baseUrl, accessToken: runtime.accessToken, ...runtime.downloadDeps };
+    const download = await downloadHandoff(downloadDeps, toDownloadBinding(binding), handoffId);
+    if (!download.ok) {
+        if (download.kind === "technical") {
+            upsertApplication(store, { handoffId, bindingId, technicalWaitReason: download.reason });
+            transitionApplicationState(store, handoffId, bindingId, "technical_wait");
+            runtime.emitter?.emit({ event: "handoff_evaluated", bindingId, handoffId, outcome: "technical_wait", waitReason: download.reason });
+        }
+        else {
+            upsertApplication(store, { handoffId, bindingId, errorCode: download.code, errorDetail: download.detail, technicalWaitReason: download.code });
+            transitionApplicationState(store, handoffId, bindingId, "technical_wait");
+        }
+        return;
+    }
+    const { manifest, targets } = download;
+    upsertApplication(store, { handoffId, bindingId, manifestSha256: manifest.manifestSha256 });
+    const repoWait = evaluateRepositoryTechnicalWait(repo, binding.boundBranch);
+    if (repoWait.wait) {
+        upsertApplication(store, { handoffId, bindingId, technicalWaitReason: repoWait.reason });
+        transitionApplicationState(store, handoffId, bindingId, "technical_wait");
+        runtime.emitter?.emit({ event: "handoff_evaluated", bindingId, handoffId, outcome: "technical_wait", waitReason: repoWait.reason });
+        return;
+    }
+    const decision = decideHandoffContent(repo, targets);
+    const targetPaths = targets.map((target) => target.path);
+    if (decision.kind === "no_op") {
+        transitionApplicationState(store, handoffId, bindingId, "no_op");
+        runtime.emitter?.emit({ event: "handoff_evaluated", bindingId, handoffId, outcome: "no_op" });
+        return;
+    }
+    if (decision.kind === "decision_required") {
+        const fingerprint = computeStateFingerprint(repo, targetPaths, manifest.manifestSha256);
+        upsertApplication(store, {
+            handoffId,
+            bindingId,
+            localStateFingerprint: fingerprint,
+            decisionState: serializeDecisionEvidence(decision.divergent, targetPaths),
+        });
+        transitionApplicationState(store, handoffId, bindingId, "decision_required");
+        runtime.emitter?.emit({ event: "handoff_evaluated", bindingId, handoffId, outcome: "decision_required" });
+        runtime.emitter?.emit({
+            event: "decision_required",
+            bindingId,
+            handoffId,
+            paths: decision.divergent.map((entry) => entry.path),
+            divergenceClasses: decision.divergent.map((entry) => entry.divergence),
+            fingerprintAt: new Date(runtime.now ? runtime.now() : Date.now()).toISOString(),
+        });
+        return;
+    }
+    runtime.emitter?.emit({ event: "handoff_evaluated", bindingId, handoffId, outcome: "automatic" });
+    const result = await applyCommit({ store, repo, binding, manifest, targets, approved: false, emitter: runtime.emitter });
+    if (result.ok) {
+        await postResultReport({ baseUrl: runtime.baseUrl, accessToken: runtime.accessToken }, binding, { handoffId, commitId: result.commitId, status: "committed", manifestHash: manifest.manifestSha256, affectedPaths: result.changedPaths });
+    }
+}
+export function reconcileInboundBinding(store, runtime, bindingId) {
+    return withReconciliationLock(bindingId, () => runInboundReconciliation(store, runtime, bindingId));
+}
+export function createInboundApplier(runtime) {
+    return (context) => runInboundReconciliation(context.store, runtime, context.binding.id);
+}
+export function registerInboundApplier(engine, runtime) {
+    engine.registerInboundApplier((context) => runInboundReconciliation(context.store, runtime, context.binding.id));
+}
+export async function retryApplication(store, runtime, bindingId, handoffId) {
+    return withReconciliationLock(bindingId, async () => {
+        const application = getApplication(store, handoffId, bindingId);
+        if (!application)
+            return { ok: false, code: "not_found" };
+        if (application.state === "technical_wait") {
+            upsertApplication(store, { handoffId, bindingId, errorCode: null, errorDetail: null, technicalWaitReason: null });
+            transitionApplicationState(store, handoffId, bindingId, "evaluating");
+        }
+        else if (application.state !== "evaluating" && application.state !== "received") {
+            return { ok: false, code: "not_retryable" };
+        }
+        await runInboundReconciliation(store, runtime, bindingId);
+        return { ok: true, state: getApplication(store, handoffId, bindingId)?.state };
+    });
+}

package/dist/lib/git-sync/inbound/apply_commit.js

@@ -0,0 +1,225 @@
+import { randomUUID } from "node:crypto";
+import { lstatSync, readFileSync, readlinkSync, renameSync, rmSync, writeFileSync, mkdirSync, symlinkSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { runGit } from "../core/git_runner.js";
+import { readHeadCommit } from "../core/repository.js";
+import { safeJoin } from "../core/path_normalizer.js";
+import { recordInboundCommit } from "../../local_store/commit_origins.js";
+import { getApplication, upsertApplication, transitionApplicationState, } from "../../local_store/handoff_applications.js";
+import { readTargetState } from "./content_decision.js";
+import { computeStateFingerprint } from "./state_fingerprint.js";
+import { persistRecoveryBundle } from "../recovery/store.js";
+export const NUSTACK_SYNC_IDENTITY = { name: "NuStack Sync", email: "sync@nustack.local" };
+export function buildCommitMessage(handoffId, workspaceId, approvedByUserId) {
+    const lines = [
+        `nustack(sync): apply cloud handoff ${handoffId.slice(0, 12)}`,
+        "",
+        `NuStack-Handoff: ${handoffId}`,
+        `NuStack-Workspace: ${workspaceId}`,
+        "NuStack-Origin: cloud",
+    ];
+    if (approvedByUserId)
+        lines.push(`NuStack-Approved-By: ${approvedByUserId}`);
+    return `${lines.join("\n")}\n`;
+}
+export function captureTarget(repo, targetPath) {
+    const state = readTargetState(repo, targetPath);
+    const indexEntries = state.index.filter((entry) => entry.stage === 0);
+    const abs = path.join(repo.repositoryRoot, targetPath);
+    let working = { type: "absent" };
+    try {
+        const stat = lstatSync(abs);
+        if (stat.isSymbolicLink())
+            working = { type: "symlink", link: readlinkSync(abs) };
+        else if (stat.isFile())
+            working = { type: "file", bytes: readFileSync(abs) };
+    }
+    catch {
+        working = { type: "absent" };
+    }
+    return { path: targetPath, indexEntries, working };
+}
+export function buildCommit(repo, oldHead, targets, bytesByPath, message, identity) {
+    const tmpIndex = path.join(os.tmpdir(), `nustack-idx-${randomUUID()}`);
+    const blobByPath = new Map();
+    try {
+        if (oldHead)
+            runGit(repo.repositoryRoot, ["read-tree", oldHead], { indexFile: tmpIndex });
+        for (const target of targets) {
+            if (target.operation === "delete") {
+                runGit(repo.repositoryRoot, ["update-index", "--force-remove", "--", target.path], { indexFile: tmpIndex });
+                continue;
+            }
+            const bytes = bytesByPath.get(target.path);
+            const blob = runGit(repo.repositoryRoot, ["hash-object", "-w", "--stdin"], { input: bytes }).stdout.trim();
+            blobByPath.set(target.path, blob);
+            runGit(repo.repositoryRoot, ["update-index", "--add", "--cacheinfo", `100644,${blob},${target.path}`], { indexFile: tmpIndex });
+        }
+        const tree = runGit(repo.repositoryRoot, ["write-tree"], { indexFile: tmpIndex }).stdout.trim();
+        const commitArgs = ["commit-tree", tree];
+        if (oldHead)
+            commitArgs.push("-p", oldHead);
+        commitArgs.push("-m", message);
+        const commitId = runGit(repo.repositoryRoot, commitArgs, { identity }).stdout.trim();
+        return { commitId, blobByPath };
+    }
+    finally {
+        rmSync(tmpIndex, { force: true });
+    }
+}
+export function atomicWrite(repo, targetPath, bytes) {
+    const joined = safeJoin(repo.repositoryRoot, targetPath);
+    if (!joined.ok)
+        throw new Error(`refusing to write outside the repository root: ${targetPath}`);
+    const dir = path.dirname(joined.path);
+    mkdirSync(dir, { recursive: true });
+    const tmp = path.join(dir, `.nustack-tmp-${randomUUID()}`);
+    writeFileSync(tmp, bytes, { mode: 0o644 });
+    renameSync(tmp, joined.path);
+}
+export function materializeTarget(repo, target, blob, bytes) {
+    if (target.operation === "delete") {
+        runGit(repo.repositoryRoot, ["update-index", "--force-remove", "--", target.path]);
+        rmSync(path.join(repo.repositoryRoot, target.path), { force: true });
+        return;
+    }
+    runGit(repo.repositoryRoot, ["update-index", "--add", "--cacheinfo", `100644,${blob},${target.path}`]);
+    atomicWrite(repo, target.path, bytes);
+}
+export function restoreTarget(repo, captured) {
+    runGit(repo.repositoryRoot, ["update-index", "--force-remove", "--", captured.path]);
+    for (const entry of captured.indexEntries) {
+        runGit(repo.repositoryRoot, ["update-index", "--add", "--cacheinfo", `${entry.mode},${entry.blobSha},${captured.path}`]);
+    }
+    const abs = path.join(repo.repositoryRoot, captured.path);
+    if (captured.working.type === "absent") {
+        rmSync(abs, { force: true });
+    }
+    else if (captured.working.type === "file") {
+        atomicWrite(repo, captured.path, captured.working.bytes);
+    }
+    else {
+        rmSync(abs, { force: true });
+        mkdirSync(path.dirname(abs), { recursive: true });
+        symlinkSync(captured.working.link, abs);
+    }
+}
+export function casBranchRef(repo, branch, newCommit, oldHead) {
+    const ref = `refs/heads/${branch}`;
+    const args = oldHead ? ["update-ref", ref, newCommit, oldHead] : ["update-ref", ref, newCommit];
+    return runGit(repo.repositoryRoot, args, { allowFailure: true }).exitCode === 0;
+}
+function toBundleContent(captured, manifestSha256, stateFingerprint, handoffId, bindingId) {
+    const targets = captured.map((entry) => ({
+        path: entry.path,
+        workingContentBase64: entry.working.type === "file"
+            ? entry.working.bytes.toString("base64")
+            : entry.working.type === "symlink"
+                ? Buffer.from(entry.working.link, "utf8").toString("base64")
+                : null,
+        workingType: entry.working.type,
+        indexEntries: entry.indexEntries.map((e) => ({ mode: e.mode, blobSha: e.blobSha, stage: e.stage })),
+    }));
+    return {
+        version: 1,
+        bindingId,
+        handoffId,
+        manifestSha256,
+        stateFingerprint,
+        capturedAtMs: Date.now(),
+        targets,
+    };
+}
+export function finalizeCommitted(store, bindingId, handoffId, commitId, approvedByUserId) {
+    const application = getApplication(store, handoffId, bindingId);
+    if (!application)
+        return;
+    upsertApplication(store, {
+        handoffId,
+        bindingId,
+        generatedCommitId: commitId,
+        notificationState: "unacknowledged",
+        ...(approvedByUserId ? { approvedByUserId } : {}),
+    });
+    if (getApplication(store, handoffId, bindingId).state === "decision_required") {
+        transitionApplicationState(store, handoffId, bindingId, "approved");
+    }
+    const beforeApplying = getApplication(store, handoffId, bindingId).state;
+    if (beforeApplying === "evaluating" || beforeApplying === "approved") {
+        transitionApplicationState(store, handoffId, bindingId, "applying");
+    }
+    recordInboundCommit(store, { bindingId, commitId, handoffId });
+    if (getApplication(store, handoffId, bindingId).state === "applying") {
+        transitionApplicationState(store, handoffId, bindingId, "committed");
+    }
+}
+export async function applyCommit(input) {
+    const { store, repo, binding, manifest, targets, approved, emitter } = input;
+    const handoffId = manifest.handoffId;
+    const oldHead = readHeadCommit(repo);
+    const captured = targets.map((target) => captureTarget(repo, target.path));
+    let recoveryBundleId = null;
+    if (approved && input.recovery) {
+        const fingerprint = computeStateFingerprint(repo, targets.map((t) => t.path), manifest.manifestSha256);
+        const content = toBundleContent(captured, manifest.manifestSha256, fingerprint, handoffId, binding.id);
+        const persisted = await persistRecoveryBundle({
+            store,
+            deviceRef: input.recovery.deviceRef,
+            bindingId: binding.id,
+            handoffId,
+            manifestSha256: manifest.manifestSha256,
+            content,
+        });
+        recoveryBundleId = persisted.bundle.id;
+        upsertApplication(store, { handoffId, bindingId: binding.id, recoveryBundleId });
+        emitter?.emit({
+            event: "recovery_bundle_created",
+            bindingId: binding.id,
+            handoffId,
+            bundleId: recoveryBundleId,
+            expiresAt: new Date(persisted.bundle.expiresAtMs).toISOString(),
+        });
+    }
+    const bytesByPath = new Map();
+    for (const target of targets) {
+        if (target.operation === "upsert" && target.blobPath)
+            bytesByPath.set(target.path, readFileSync(target.blobPath));
+    }
+    const message = buildCommitMessage(handoffId, manifest.workspaceId, approved ? (input.approvedByUserId ?? null) : null);
+    const built = buildCommit(repo, oldHead, targets, bytesByPath, message, {
+        authorName: NUSTACK_SYNC_IDENTITY.name,
+        authorEmail: NUSTACK_SYNC_IDENTITY.email,
+        committerName: NUSTACK_SYNC_IDENTITY.name,
+        committerEmail: NUSTACK_SYNC_IDENTITY.email,
+        ...(input.authorDate ? { authorDate: input.authorDate } : {}),
+        ...(input.committerDate ? { committerDate: input.committerDate } : {}),
+    });
+    upsertApplication(store, { handoffId, bindingId: binding.id, generatedCommitId: built.commitId });
+    for (const target of targets) {
+        materializeTarget(repo, target, built.blobByPath.get(target.path) ?? null, bytesByPath.get(target.path) ?? null);
+    }
+    if (!casBranchRef(repo, binding.boundBranch, built.commitId, oldHead)) {
+        for (const capture of captured)
+            restoreTarget(repo, capture);
+        upsertApplication(store, {
+            handoffId,
+            bindingId: binding.id,
+            generatedCommitId: null,
+            errorCode: "cas_conflict",
+            errorDetail: "the branch ref moved during apply",
+        });
+        return { ok: false, kind: "cas_conflict" };
+    }
+    finalizeCommitted(store, binding.id, handoffId, built.commitId, approved ? (input.approvedByUserId ?? null) : null);
+    const changedPaths = targets.map((target) => target.path);
+    emitter?.emit({
+        event: "handoff_committed",
+        bindingId: binding.id,
+        handoffId,
+        commitId: built.commitId,
+        paths: changedPaths,
+        noPush: true,
+    });
+    return { ok: true, commitId: built.commitId, changedPaths, recoveryBundleId };
+}

package/dist/lib/git-sync/inbound/approval.js

@@ -0,0 +1,117 @@
+import { withReconciliationLock } from "../core/reconciliation_lock.js";
+import { resolveRepository } from "../core/repository.js";
+import { getBindingById, } from "../../local_store/bindings.js";
+import { getApplication, upsertApplication, transitionApplicationState, } from "../../local_store/handoff_applications.js";
+import { reportApplicationDecision, } from "../../nustack_client.js";
+import { downloadHandoff } from "./download.js";
+import { decideHandoffContent } from "./content_decision.js";
+import { computeStateFingerprint } from "./state_fingerprint.js";
+import { applyCommit } from "./apply_commit.js";
+import { postResultReport } from "./notification.js";
+export const APPROVAL_RECOVERY_NOTE = "Approving overwrites the listed paths. Git Undo restores the prior committed base; the encrypted recovery bundle is the only path back to your pre-approval uncommitted content.";
+export function toDownloadBinding(binding) {
+    return {
+        id: binding.id,
+        workspaceId: binding.workspaceId,
+        boundBranch: binding.boundBranch,
+        repositoryRoot: binding.repositoryRoot,
+        etnaProfileJson: binding.etnaProfileJson,
+        whitelistManifestSha256: binding.whitelistManifestSha256,
+    };
+}
+export function serializeDecisionEvidence(divergent, targetPaths) {
+    return JSON.stringify({ divergent, targetPaths });
+}
+export async function approveHandoff(store, deps, bindingId, handoffId) {
+    return withReconciliationLock(bindingId, async () => {
+        const binding = getBindingById(store, bindingId);
+        if (!binding)
+            return { ok: false, code: "not_found" };
+        const application = getApplication(store, handoffId, bindingId);
+        if (!application)
+            return { ok: false, code: "not_found" };
+        if (application.state === "superseded")
+            return { ok: false, code: "superseded" };
+        if (application.state !== "decision_required")
+            return { ok: false, code: "not_pending" };
+        const repo = resolveRepository(binding.repositoryRoot);
+        const downloadDeps = { baseUrl: deps.baseUrl, accessToken: deps.accessToken, ...deps.downloadDeps };
+        const download = await downloadHandoff(downloadDeps, toDownloadBinding(binding), handoffId);
+        if (!download.ok) {
+            return download.kind === "technical"
+                ? { ok: false, code: "technical_wait", detail: download.reason }
+                : { ok: false, code: "download_rejected", detail: download.code };
+        }
+        const { manifest, targets } = download;
+        const targetPaths = targets.map((target) => target.path);
+        const currentFingerprint = computeStateFingerprint(repo, targetPaths, manifest.manifestSha256);
+        if (application.localStateFingerprint !== null && currentFingerprint !== application.localStateFingerprint) {
+            const decision = decideHandoffContent(repo, targets);
+            const divergent = decision.kind === "decision_required" ? decision.divergent : [];
+            upsertApplication(store, {
+                handoffId,
+                bindingId,
+                localStateFingerprint: currentFingerprint,
+                decisionState: serializeDecisionEvidence(divergent, targetPaths),
+            });
+            return {
+                ok: false,
+                code: "local_state_changed",
+                warning: { handoffId, bindingId, paths: divergent, fingerprint: currentFingerprint, recoveryNote: APPROVAL_RECOVERY_NOTE },
+            };
+        }
+        const decision = decideHandoffContent(repo, targets);
+        if (decision.kind !== "decision_required") {
+            const result = await applyCommit({ store, repo, binding, manifest, targets, approved: false, emitter: deps.emitter });
+            return finishApply(deps, binding, handoffId, manifest.manifestSha256, result);
+        }
+        const decisionReport = {
+            bindingId,
+            handoffId,
+            idempotencyKey: `decision:${bindingId}:${handoffId}`,
+            decision: "approve_overwrite",
+            localStateFingerprint: currentFingerprint,
+            affectedPaths: decision.divergent.map((entry) => entry.path),
+        };
+        const reportDecision = deps.reportDecision ?? reportApplicationDecision;
+        let queued = false;
+        try {
+            const outcome = await reportDecision(deps.baseUrl, deps.accessToken, decisionReport);
+            if (!outcome.ok) {
+                transitionApplicationState(store, handoffId, bindingId, "superseded");
+                return { ok: false, code: "superseded" };
+            }
+        }
+        catch {
+            queued = true;
+        }
+        void queued;
+        const result = await applyCommit({
+            store,
+            repo,
+            binding,
+            manifest,
+            targets,
+            approved: true,
+            approvedByUserId: deps.userId,
+            recovery: deps.deviceRef ? { deviceRef: deps.deviceRef } : null,
+            emitter: deps.emitter,
+        });
+        return finishApply(deps, binding, handoffId, manifest.manifestSha256, result);
+    });
+}
+async function finishApply(deps, binding, handoffId, manifestSha256, result) {
+    if (result.ok) {
+        await postResultReport({ baseUrl: deps.baseUrl, accessToken: deps.accessToken, reportResult: deps.reportResult }, binding, {
+            handoffId,
+            commitId: result.commitId,
+            status: "committed",
+            manifestHash: manifestSha256,
+            affectedPaths: result.changedPaths,
+        });
+        return { ok: true, commitId: result.commitId, changedPaths: result.changedPaths, recoveryBundleId: result.recoveryBundleId };
+    }
+    if (result.kind === "cas_conflict")
+        return { ok: false, code: "cas_conflict" };
+    return { ok: false, code: "download_rejected", detail: result.detail };
+}