@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/dist/cli/conflict-recovery.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=conflict-recovery.test.d.ts.map

package/dist/cli/conflict-recovery.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflict-recovery.test.d.ts","sourceRoot":"","sources":["../../src/cli/conflict-recovery.test.ts"],"names":[],"mappings":""}

package/dist/cli/conflict-recovery.test.js

@@ -0,0 +1,201 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { preserveRealtimeConflict, realtimeConflictSiblingPath, } from "./conflict.js";
+const directories = [];
+afterEach(() => {
+    for (const directory of directories.splice(0)) {
+        fs.rmSync(directory, { recursive: true, force: true });
+    }
+});
+function root() {
+    const directory = fs.mkdtempSync(path.join(os.tmpdir(), "hq-u55-conflict-"));
+    directories.push(directory);
+    return directory;
+}
+function digest(bytes) {
+    return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+function authorization() {
+    return {
+        bearer: "bearer",
+        deviceId: "device-a",
+        capabilityVector: { hqCloud: "1.0.0", hqDesktop: "1.0.0", protocol: 2, journal: 3, durableApply: 1 },
+        lease: { lease: "lease", issuedAt: "2030-01-01T00:00:00.000Z", expiresAt: "2030-01-01T00:01:00.000Z", authorizationEpoch: "epoch-1" },
+    };
+}
+function ackFetch(status, duringAck) {
+    return vi.fn(async () => {
+        duringAck?.();
+        return {
+            ok: status >= 200 && status < 300,
+            status,
+            headers: { get: () => null },
+            body: null,
+            text: async () => "ack response",
+        };
+    });
+}
+describe("realtime conflict sibling vectors", () => {
+    it("uses NFC plus the protocol's lower-case RFC4648 suffix golden", () => {
+        expect(realtimeConflictSiblingPath({
+            scopeUid: "prs_demo",
+            canonicalPath: "notes/cafe\u0301.md",
+            attemptId: "attempt-01",
+        })).toBe("notes/café.conflict-gh3wpjyej2j7lqaz3bo5xfgsbu.md");
+    });
+    it("keeps leading-dot and trailing-dot filenames extensionless", () => {
+        expect(realtimeConflictSiblingPath({ scopeUid: "prs_demo", canonicalPath: ".env", attemptId: "attempt-01" }))
+            .toBe(".env.conflict-ctwymj4ik6slm4yebxhtmykqjg");
+        expect(realtimeConflictSiblingPath({ scopeUid: "prs_demo", canonicalPath: "report.", attemptId: "attempt-01" }))
+            .toBe("report..conflict-7bkmwiyxxbpvkbnplv6vplbkue");
+    });
+    it("truncates only at a complete UTF-8 code point and preserves the extension", () => {
+        const sibling = realtimeConflictSiblingPath({
+            scopeUid: "prs_demo",
+            canonicalPath: `${"😀".repeat(54)}.md`,
+            attemptId: "attempt-01",
+        });
+        const component = sibling.split("/").at(-1);
+        expect(Buffer.byteLength(component, "utf8")).toBe(255);
+        expect(component).toMatch(/\.conflict-[a-z2-7]{26}\.md$/);
+        expect(component.startsWith("😀")).toBe(true);
+        expect(component.includes("\ufffd")).toBe(false);
+    });
+});
+describe("creator-candidate conflict recovery", () => {
+    it("preserves exact fsynced spool bytes before sending conflict-sibling acknowledgement", async () => {
+        const directory = root();
+        const bytes = Buffer.from([0, 255, 1, 2, 3]);
+        const expectedSha256 = digest(bytes);
+        const spool = path.join(directory, "attempt.spool");
+        fs.writeFileSync(spool, bytes);
+        const expectedSibling = realtimeConflictSiblingPath({ scopeUid: "prs_demo", canonicalPath: "notes/lost.bin", attemptId: "attempt-01" });
+        const order = [];
+        const fetchImpl = ackFetch(204, () => {
+            expect(order).toEqual(["recorded"]);
+            expect(fs.readFileSync(path.join(directory, expectedSibling))).toEqual(bytes);
+        });
+        const result = await preserveRealtimeConflict({
+            root: directory,
+            scopeUid: "prs_demo",
+            canonicalPath: "notes/lost.bin",
+            attemptId: "attempt-01",
+            expectedSha256,
+            expectedSize: bytes.byteLength,
+            spoolPath: spool,
+            caseInsensitiveFilesystem: false,
+            recordConflictPreserved: async () => { order.push("recorded"); },
+            creatorCandidate: { apiUrl: "https://sync.example.test", authorization: authorization(), fetchImpl },
+        });
+        expect(result.source).toBe("local-attempt-spool");
+        expect(fs.readFileSync(path.join(directory, result.siblingPath))).toEqual(bytes);
+        expect(fetchImpl).toHaveBeenCalledWith("https://sync.example.test/v2/sync/mutations/attempt-01/candidate-ack", expect.objectContaining({
+            method: "POST",
+            body: JSON.stringify({ evidence: { kind: "conflict-sibling", sha256: expectedSha256 } }),
+        }));
+    });
+    it("recovers exact bytes from the creator-only exact candidate when the spool is absent", async () => {
+        const directory = root();
+        const bytes = Buffer.from("candidate-only bytes\u0000", "utf8");
+        const expectedSha256 = digest(bytes);
+        const candidateReader = {
+            openCandidate: vi.fn(async () => ({
+                url: "https://s3.example.test/exact-version",
+                expiresAt: "2030-01-01T00:01:00.000Z",
+                versionId: "candidate-v7",
+                sha256: expectedSha256,
+                size: bytes.byteLength,
+                body: (async function* () { yield bytes; })(),
+            })),
+        };
+        const fetchImpl = ackFetch(204);
+        const result = await preserveRealtimeConflict({
+            root: directory,
+            scopeUid: "prs_demo",
+            canonicalPath: "notes/lost.bin",
+            attemptId: "attempt-02",
+            expectedSha256,
+            expectedSize: bytes.byteLength,
+            spoolPath: path.join(directory, "missing.spool"),
+            caseInsensitiveFilesystem: false,
+            recordConflictPreserved: async () => undefined,
+            creatorCandidate: {
+                apiUrl: "https://sync.example.test",
+                authorization: authorization(),
+                fetchImpl,
+                candidateReader,
+            },
+        });
+        expect(result.source).toBe("creator-candidate");
+        expect(candidateReader.openCandidate).toHaveBeenCalledTimes(1);
+        expect(fs.readFileSync(path.join(directory, result.siblingPath))).toEqual(bytes);
+    });
+    it("refuses a case-fold collision without acknowledging or overwriting either path", async () => {
+        const directory = root();
+        fs.mkdirSync(path.join(directory, "Notes"));
+        const bytes = Buffer.from("losing bytes");
+        const fetchImpl = ackFetch(204);
+        await expect(preserveRealtimeConflict({
+            root: directory,
+            scopeUid: "prs_demo",
+            canonicalPath: "notes/lost.txt",
+            attemptId: "attempt-03",
+            expectedSha256: digest(bytes),
+            expectedSize: bytes.byteLength,
+            spoolPath: (() => { const spool = path.join(directory, "attempt.spool"); fs.writeFileSync(spool, bytes); return spool; })(),
+            caseInsensitiveFilesystem: true,
+            recordConflictPreserved: async () => undefined,
+            creatorCandidate: { apiUrl: "https://sync.example.test", authorization: authorization(), fetchImpl },
+        })).rejects.toMatchObject({ code: "CASE_COLLISION" });
+        expect(fs.existsSync(path.join(directory, "Notes"))).toBe(true);
+        expect(fetchImpl).not.toHaveBeenCalled();
+    });
+    it("retains the durable sibling when acknowledgement fails, so candidate cleanup remains blocked", async () => {
+        const directory = root();
+        const bytes = Buffer.from("must survive failed acknowledgement");
+        const expectedSha256 = digest(bytes);
+        const spool = path.join(directory, "attempt.spool");
+        fs.writeFileSync(spool, bytes);
+        const sibling = realtimeConflictSiblingPath({ scopeUid: "prs_demo", canonicalPath: "notes/lost.txt", attemptId: "attempt-04" });
+        await expect(preserveRealtimeConflict({
+            root: directory,
+            scopeUid: "prs_demo",
+            canonicalPath: "notes/lost.txt",
+            attemptId: "attempt-04",
+            expectedSha256,
+            expectedSize: bytes.byteLength,
+            spoolPath: spool,
+            caseInsensitiveFilesystem: false,
+            recordConflictPreserved: async () => undefined,
+            creatorCandidate: { apiUrl: "https://sync.example.test", authorization: authorization(), fetchImpl: ackFetch(503) },
+        })).rejects.toMatchObject({ code: "CANDIDATE_UNAVAILABLE" });
+        expect(fs.readFileSync(path.join(directory, sibling))).toEqual(bytes);
+    });
+    it("withholds acknowledgement when the conflict-preserved record is not durable", async () => {
+        const directory = root();
+        const bytes = Buffer.from("record failure must retain recovery material");
+        const expectedSha256 = digest(bytes);
+        const spool = path.join(directory, "attempt.spool");
+        fs.writeFileSync(spool, bytes);
+        const fetchImpl = ackFetch(204);
+        const sibling = realtimeConflictSiblingPath({ scopeUid: "prs_demo", canonicalPath: "notes/record.txt", attemptId: "attempt-05" });
+        await expect(preserveRealtimeConflict({
+            root: directory,
+            scopeUid: "prs_demo",
+            canonicalPath: "notes/record.txt",
+            attemptId: "attempt-05",
+            expectedSha256,
+            expectedSize: bytes.byteLength,
+            spoolPath: spool,
+            caseInsensitiveFilesystem: false,
+            recordConflictPreserved: async () => { throw new Error("WAL unavailable"); },
+            creatorCandidate: { apiUrl: "https://sync.example.test", authorization: authorization(), fetchImpl },
+        })).rejects.toThrow("WAL unavailable");
+        expect(fetchImpl).not.toHaveBeenCalled();
+        expect(fs.readFileSync(path.join(directory, sibling))).toEqual(bytes);
+    });
+});
+//# sourceMappingURL=conflict-recovery.test.js.map

package/dist/cli/conflict-recovery.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflict-recovery.test.js","sourceRoot":"","sources":["../../src/cli/conflict-recovery.test.ts"],"names":[],"mappings":"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"}

package/dist/cli/conflict.d.ts

@@ -4,6 +4,66 @@
  * Interactive prompts in terminal mode; deterministic resolution via
  * --on-conflict flag for worker/skill callers.
  */
+import { CandidateUploader, type CandidateFetch, type CandidateTransportAuthorization } from "../sync/candidate-uploader.js";
+export declare class RealtimeConflictError extends Error {
+    readonly code: "INVALID_PATH" | "CASE_COLLISION" | "CONFLICT_NAME_COLLISION" | "CANDIDATE_UNAVAILABLE";
+    constructor(code: "INVALID_PATH" | "CASE_COLLISION" | "CONFLICT_NAME_COLLISION" | "CANDIDATE_UNAVAILABLE", message?: string, options?: ErrorOptions);
+}
+export interface RealtimeConflictPathInput {
+    scopeUid: string;
+    canonicalPath: string;
+    attemptId: string;
+}
+export interface CreatorCandidateRecovery {
+    apiUrl: string;
+    authorization: CandidateTransportAuthorization;
+    fetchImpl?: CandidateFetch;
+    /** Injectable only so recovery can share the already-bound candidate reader. */
+    candidateReader?: Pick<CandidateUploader, "openCandidate">;
+}
+export interface PreserveRealtimeConflictInput extends RealtimeConflictPathInput {
+    /** Root of the scope; the conflict sibling is always contained beneath it. */
+    root: string;
+    /** SHA-256 from the immutable attempt request, never a best-effort local hash. */
+    expectedSha256: `sha256:${string}`;
+    expectedSize: number;
+    /** Preferred exact source: the fsynced immutable local attempt spool. */
+    spoolPath?: string;
+    /** Used only when the local spool is unavailable or fails exact verification. */
+    creatorCandidate?: CreatorCandidateRecovery;
+    /** Must be set by a caller operating on a case-insensitive filesystem. */
+    caseInsensitiveFilesystem: boolean;
+    /** Mirrors the platform's actual folding rule and makes that rule testable. */
+    caseFold?: (value: string) => string;
+    /**
+     * Appends the `conflict-preserved` WAL/state-store fact. It must not resolve
+     * until that fact is durable; acknowledgement is intentionally after it.
+     */
+    recordConflictPreserved(record: PreservedRealtimeConflict): Promise<void>;
+}
+export interface PreservedRealtimeConflict {
+    canonicalPath: string;
+    siblingPath: string;
+    sha256: `sha256:${string}`;
+    source: "local-attempt-spool" | "creator-candidate";
+}
+/** Exact V2 canonical path contract, duplicated here so recovery has no V1 path dependency. */
+export declare function canonicalizeRealtimeConflictPath(rawPath: string): string;
+/** RFC 4648 lower-case Base32 without padding, as frozen by protocol v2. */
+export declare function lowercaseBase32NoPadding(bytes: Uint8Array): string;
+/**
+ * The stable sibling name for a losing V2 mutation. It deliberately includes
+ * no clock, hostname, ETag, or local filesystem fact.
+ */
+export declare function realtimeConflictSiblingPath(input: RealtimeConflictPathInput): string;
+/** Acknowledgement is sent only after sibling bytes and its containing directory are fsynced. */
+export declare function acknowledgeCreatorCandidate(recovery: CreatorCandidateRecovery, attemptId: string, checksum: `sha256:${string}`): Promise<void>;
+/**
+ * Recovers a losing mutation from the immutable spool or creator-only exact
+ * candidate, publishes its deterministic sibling, then releases server-side
+ * candidate retention with a monotonic acknowledgement.
+ */
+export declare function preserveRealtimeConflict(input: PreserveRealtimeConflictInput): Promise<PreservedRealtimeConflict>;
 export type ConflictStrategy = "overwrite" | "keep" | "abort";
 export interface ConflictInfo {
     path: string;

package/dist/cli/conflict.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conflict.d.ts","sourceRoot":"","sources":["../../src/cli/conflict.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,IAAI,CAAC;IACrB,cAAc,CAAC,EAAE,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAElF;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,YAAY,EACtB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,OAAO,CAAC,kBAAkB,CAAC,CAM7B;AAuDD;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,IAAI,CAcN"}
+{"version":3,"file":"conflict.d.ts","sourceRoot":"","sources":["../../src/cli/conflict.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,+BAA+B,EAErC,MAAM,+BAA+B,CAAC;AAMvC,qBAAa,qBAAsB,SAAQ,KAAK;IAE5C,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,gBAAgB,GAAG,yBAAyB,GAAG,uBAAuB;gBAA7F,IAAI,EAAE,cAAc,GAAG,gBAAgB,GAAG,yBAAyB,GAAG,uBAAuB,EACtG,OAAO,GAAE,MAAa,EACtB,OAAO,CAAC,EAAE,YAAY;CAKzB;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,+BAA+B,CAAC;IAC/C,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,gFAAgF;IAChF,eAAe,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,eAAe,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,6BAA8B,SAAQ,yBAAyB;IAC9E,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,cAAc,EAAE,UAAU,MAAM,EAAE,CAAC;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,wBAAwB,CAAC;IAC5C,0EAA0E;IAC1E,yBAAyB,EAAE,OAAO,CAAC;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACrC;;;OAGG;IACH,uBAAuB,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3E;AAED,MAAM,WAAW,yBAAyB;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,UAAU,MAAM,EAAE,CAAC;IAC3B,MAAM,EAAE,qBAAqB,GAAG,mBAAmB,CAAC;CACrD;AA4BD,+FAA+F;AAC/F,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAcxE;AAED,4EAA4E;AAC5E,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAclE;AAoBD;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,yBAAyB,GAAG,MAAM,CAmBpF;AAuID,iGAAiG;AACjG,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,wBAAwB,EAClC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,UAAU,MAAM,EAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAkCf;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,6BAA6B,GAAG,OAAO,CAAC,yBAAyB,CAAC,CA+CvH;AAED,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,IAAI,CAAC;IACrB,cAAc,CAAC,EAAE,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAElF;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,YAAY,EACtB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,OAAO,CAAC,kBAAkB,CAAC,CAM7B;AAuDD;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,IAAI,CAcN"}

package/dist/cli/conflict.js

@@ -5,7 +5,340 @@
  * --on-conflict flag for worker/skill callers.
  */
 import * as fs from "fs";
+import { createHash } from "node:crypto";
+import * as pathModule from "node:path";
 import * as readline from "readline";
+import { CandidateUploader, } from "../sync/candidate-uploader.js";
+const REALTIME_OPAQUE_ID = /^[A-Za-z0-9._~-]{1,512}$/;
+const REALTIME_SHA256 = /^sha256:[a-f0-9]{64}$/;
+const BASE32_LOWER = "abcdefghijklmnopqrstuvwxyz234567";
+export class RealtimeConflictError extends Error {
+    code;
+    constructor(code, message = code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "RealtimeConflictError";
+    }
+}
+function assertScalarUnicode(value, label) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (next < 0xdc00 || next > 0xdfff) {
+                throw new RealtimeConflictError("INVALID_PATH", `${label} contains an unpaired surrogate`);
+            }
+            index += 1;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff) {
+            throw new RealtimeConflictError("INVALID_PATH", `${label} contains an unpaired surrogate`);
+        }
+    }
+}
+function containsControlCharacter(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const codePoint = value.codePointAt(index);
+        if (codePoint !== undefined && ((codePoint >= 0x00 && codePoint <= 0x1f) ||
+            (codePoint >= 0x7f && codePoint <= 0x9f)))
+            return true;
+    }
+    return false;
+}
+/** Exact V2 canonical path contract, duplicated here so recovery has no V1 path dependency. */
+export function canonicalizeRealtimeConflictPath(rawPath) {
+    assertScalarUnicode(rawPath, "path");
+    const canonicalPath = rawPath.normalize("NFC");
+    if (!canonicalPath || containsControlCharacter(canonicalPath) || canonicalPath.startsWith("/") ||
+        canonicalPath.endsWith("/") || canonicalPath.startsWith(".hq-control/") ||
+        Buffer.byteLength(canonicalPath, "utf8") > 1024)
+        throw new RealtimeConflictError("INVALID_PATH");
+    for (const component of canonicalPath.split("/")) {
+        if (!component || component === "." || component === ".." || Buffer.byteLength(component, "utf8") > 255) {
+            throw new RealtimeConflictError("INVALID_PATH");
+        }
+    }
+    return canonicalPath;
+}
+/** RFC 4648 lower-case Base32 without padding, as frozen by protocol v2. */
+export function lowercaseBase32NoPadding(bytes) {
+    let result = "";
+    let buffer = 0;
+    let bits = 0;
+    for (const byte of bytes) {
+        buffer = (buffer << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            result += BASE32_LOWER[(buffer >>> (bits - 5)) & 31];
+            bits -= 5;
+        }
+    }
+    if (bits > 0)
+        result += BASE32_LOWER[(buffer << (5 - bits)) & 31];
+    return result;
+}
+function splitStemAndExtension(fileName) {
+    if (fileName.startsWith(".") || fileName.endsWith("."))
+        return { stem: fileName, extension: "" };
+    const lastDot = fileName.lastIndexOf(".");
+    return lastDot === -1
+        ? { stem: fileName, extension: "" }
+        : { stem: fileName.slice(0, lastDot), extension: fileName.slice(lastDot) };
+}
+function truncateUtf8(value, maxBytes) {
+    let end = value.length;
+    while (end > 0 && Buffer.byteLength(value.slice(0, end), "utf8") > maxBytes) {
+        end -= 1;
+        const code = value.charCodeAt(end);
+        if (code >= 0xdc00 && code <= 0xdfff)
+            end -= 1;
+    }
+    return value.slice(0, end);
+}
+/**
+ * The stable sibling name for a losing V2 mutation. It deliberately includes
+ * no clock, hostname, ETag, or local filesystem fact.
+ */
+export function realtimeConflictSiblingPath(input) {
+    if (!REALTIME_OPAQUE_ID.test(input.scopeUid) || !REALTIME_OPAQUE_ID.test(input.attemptId)) {
+        throw new RealtimeConflictError("INVALID_PATH", "scopeUid or attemptId is invalid");
+    }
+    const canonicalPath = canonicalizeRealtimeConflictPath(input.canonicalPath);
+    const slash = canonicalPath.lastIndexOf("/");
+    const directory = slash === -1 ? "" : canonicalPath.slice(0, slash + 1);
+    const fileName = canonicalPath.slice(slash + 1);
+    const suffix = lowercaseBase32NoPadding(createHash("sha256").update(`${input.scopeUid}\0${canonicalPath}\0${input.attemptId}`, "utf8").digest()).slice(0, 26);
+    const { stem, extension } = splitStemAndExtension(fileName);
+    const fixed = `.conflict-${suffix}${extension}`;
+    if (Buffer.byteLength(fixed, "utf8") > 255) {
+        throw new RealtimeConflictError("CONFLICT_NAME_COLLISION", "conflict suffix and extension exceed one component");
+    }
+    return canonicalizeRealtimeConflictPath(`${directory}${truncateUtf8(stem, 255 - Buffer.byteLength(fixed, "utf8"))}${fixed}`);
+}
+function sha256(bytes) {
+    return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+function fsyncDirectory(directory) {
+    const descriptor = fs.openSync(directory, "r");
+    try {
+        fs.fsyncSync(descriptor);
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+function containedPath(root, canonicalPath) {
+    const resolvedRoot = pathModule.resolve(root);
+    const target = pathModule.resolve(resolvedRoot, ...canonicalPath.split("/"));
+    if (target !== resolvedRoot && !target.startsWith(`${resolvedRoot}${pathModule.sep}`)) {
+        throw new RealtimeConflictError("INVALID_PATH", "conflict path escapes its scope root");
+    }
+    return target;
+}
+function assertNoCaseCollision(root, canonicalPath, caseFold) {
+    let parent = pathModule.resolve(root);
+    for (const component of canonicalPath.split("/")) {
+        if (!fs.existsSync(parent))
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(parent, { withFileTypes: true });
+        }
+        catch (error) {
+            throw new RealtimeConflictError("CANDIDATE_UNAVAILABLE", `cannot inspect conflict parent ${parent}`, { cause: error });
+        }
+        const colliding = entries.find((entry) => entry.name !== component && caseFold(entry.name.normalize("NFC")) === caseFold(component));
+        if (colliding) {
+            throw new RealtimeConflictError("CASE_COLLISION", `case collision between ${component} and ${colliding.name}`);
+        }
+        parent = pathModule.join(parent, component);
+    }
+}
+function ensureSafeSiblingParent(root, siblingPath) {
+    let current = pathModule.resolve(root);
+    const rootStat = fs.lstatSync(current);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+        throw new RealtimeConflictError("CANDIDATE_UNAVAILABLE", "conflict scope root is not a directory");
+    }
+    const parentComponents = siblingPath.split("/").slice(0, -1);
+    for (const component of parentComponents) {
+        current = pathModule.join(current, component);
+        if (!fs.existsSync(current)) {
+            fs.mkdirSync(current, { mode: 0o700 });
+            fsyncDirectory(pathModule.dirname(current));
+        }
+        const stat = fs.lstatSync(current);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            throw new RealtimeConflictError("CANDIDATE_UNAVAILABLE", `conflict parent ${current} is not a real directory`);
+        }
+    }
+}
+function writeSiblingExactly(destination, bytes, expectedSha256) {
+    const directory = pathModule.dirname(destination);
+    const temporary = pathModule.join(directory, `.${pathModule.basename(destination)}.${process.pid}.${cryptoRandomSuffix()}.tmp`);
+    let descriptor;
+    try {
+        fsyncDirectory(directory);
+        descriptor = fs.openSync(temporary, "wx", 0o600);
+        let offset = 0;
+        while (offset < bytes.byteLength)
+            offset += fs.writeSync(descriptor, bytes, offset, bytes.byteLength - offset);
+        fs.fsyncSync(descriptor);
+        fs.closeSync(descriptor);
+        descriptor = undefined;
+        try {
+            // link is publication without rename's replacement semantics.
+            fs.linkSync(temporary, destination);
+            fs.unlinkSync(temporary);
+            fsyncDirectory(directory);
+            return;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const existing = fs.readFileSync(destination);
+            if (sha256(existing) !== expectedSha256) {
+                throw new RealtimeConflictError("CONFLICT_NAME_COLLISION", `different bytes already occupy ${destination}`);
+            }
+            fs.unlinkSync(temporary);
+            // The existing sibling is the durable idempotent publication.
+            fsyncDirectory(directory);
+            return;
+        }
+    }
+    catch (error) {
+        if (descriptor !== undefined)
+            fs.closeSync(descriptor);
+        if (fs.existsSync(temporary))
+            fs.unlinkSync(temporary);
+        if (error instanceof RealtimeConflictError)
+            throw error;
+        throw new RealtimeConflictError("CANDIDATE_UNAVAILABLE", `unable to durably preserve conflict sibling`, { cause: error });
+    }
+}
+function cryptoRandomSuffix() {
+    return createHash("sha256").update(`${process.pid}:${Date.now()}:${Math.random()}`).digest("hex").slice(0, 16);
+}
+async function readExactCandidate(reader, authorization, attemptId, expectedSha256, expectedSize) {
+    const candidate = await reader.openCandidate(authorization, attemptId);
+    if (candidate.sha256 !== expectedSha256 || candidate.size !== expectedSize || !candidate.body) {
+        throw new RealtimeConflictError("CANDIDATE_UNAVAILABLE", "creator candidate does not match the immutable losing attempt");
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of candidate.body) {
+        size += chunk.byteLength;
+        if (size > expectedSize)
+            throw new RealtimeConflictError("CANDIDATE_UNAVAILABLE", "creator candidate exceeded its declared size");
+        chunks.push(chunk);
+    }
+    const bytes = Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)), size);
+    if (bytes.byteLength !== expectedSize || sha256(bytes) !== expectedSha256) {
+        throw new RealtimeConflictError("CANDIDATE_UNAVAILABLE", "creator candidate bytes do not match the losing attempt");
+    }
+    return bytes;
+}
+function controlHeaders(authorization) {
+    return {
+        Authorization: `Bearer ${authorization.bearer}`,
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        "X-HQ-Sync-Contract": "2",
+        "X-HQ-Device-ID": authorization.deviceId,
+        "X-HQ-Cloud-Version": authorization.capabilityVector.hqCloud,
+        "X-HQ-Desktop-Version": authorization.capabilityVector.hqDesktop,
+        "X-HQ-Sync-Lease": authorization.lease.lease,
+    };
+}
+/** Acknowledgement is sent only after sibling bytes and its containing directory are fsynced. */
+export async function acknowledgeCreatorCandidate(recovery, attemptId, checksum) {
+    if (!REALTIME_OPAQUE_ID.test(attemptId) || !REALTIME_SHA256.test(checksum)) {
+        throw new RealtimeConflictError("CANDIDATE_UNAVAILABLE", "candidate acknowledgement identity is invalid");
+    }
+    if (Date.parse(recovery.authorization.lease.expiresAt) <= Date.now()) {
+        throw new RealtimeConflictError("CANDIDATE_UNAVAILABLE", "lease expired before candidate acknowledgement");
+    }
+    const fetchImpl = recovery.fetchImpl ?? globalThis.fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 15_000);
+    let response;
+    try {
+        response = await fetchImpl(`${recovery.apiUrl.replace(/\/+$/, "")}/v2/sync/mutations/${encodeURIComponent(attemptId)}/candidate-ack`, {
+            method: "POST",
+            headers: controlHeaders(recovery.authorization),
+            body: JSON.stringify({ evidence: { kind: "conflict-sibling", sha256: checksum } }),
+            signal: controller.signal,
+        });
+    }
+    catch (error) {
+        throw new RealtimeConflictError("CANDIDATE_UNAVAILABLE", "candidate acknowledgement request failed", { cause: error });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (response.status === 204)
+        return;
+    let detail;
+    try {
+        detail = await response.text();
+    }
+    catch (error) {
+        throw new RealtimeConflictError("CANDIDATE_UNAVAILABLE", "candidate acknowledgement response is unreadable", { cause: error });
+    }
+    throw new RealtimeConflictError("CANDIDATE_UNAVAILABLE", `candidate acknowledgement failed (${response.status}): ${detail.slice(0, 300)}`);
+}
+/**
+ * Recovers a losing mutation from the immutable spool or creator-only exact
+ * candidate, publishes its deterministic sibling, then releases server-side
+ * candidate retention with a monotonic acknowledgement.
+ */
+export async function preserveRealtimeConflict(input) {
+    if (!REALTIME_SHA256.test(input.expectedSha256) || !Number.isSafeInteger(input.expectedSize) || input.expectedSize < 0) {
+        throw new RealtimeConflictError("CANDIDATE_UNAVAILABLE", "losing attempt metadata is invalid");
+    }
+    const canonicalPath = canonicalizeRealtimeConflictPath(input.canonicalPath);
+    const siblingPath = realtimeConflictSiblingPath({ ...input, canonicalPath });
+    const siblingAbsolutePath = containedPath(input.root, siblingPath);
+    if (input.caseInsensitiveFilesystem) {
+        assertNoCaseCollision(input.root, canonicalPath, input.caseFold ?? ((value) => value.toLowerCase()));
+        assertNoCaseCollision(input.root, siblingPath, input.caseFold ?? ((value) => value.toLowerCase()));
+    }
+    ensureSafeSiblingParent(input.root, siblingPath);
+    let bytes;
+    let source;
+    if (input.spoolPath && fs.existsSync(input.spoolPath)) {
+        try {
+            const candidate = fs.readFileSync(input.spoolPath);
+            if (candidate.byteLength === input.expectedSize && sha256(candidate) === input.expectedSha256) {
+                bytes = candidate;
+                source = "local-attempt-spool";
+            }
+        }
+        catch (error) {
+            throw new RealtimeConflictError("CANDIDATE_UNAVAILABLE", "unable to read local attempt spool", { cause: error });
+        }
+    }
+    if (!bytes) {
+        if (!input.creatorCandidate) {
+            throw new RealtimeConflictError("CANDIDATE_UNAVAILABLE", "no verified local spool or creator candidate is available");
+        }
+        const reader = input.creatorCandidate.candidateReader ?? new CandidateUploader({
+            apiUrl: input.creatorCandidate.apiUrl,
+            fetchImpl: input.creatorCandidate.fetchImpl,
+        });
+        bytes = await readExactCandidate(reader, input.creatorCandidate.authorization, input.attemptId, input.expectedSha256, input.expectedSize);
+        source = "creator-candidate";
+    }
+    if (!source) {
+        throw new RealtimeConflictError("CANDIDATE_UNAVAILABLE", "conflict source was not established");
+    }
+    writeSiblingExactly(siblingAbsolutePath, bytes, input.expectedSha256);
+    const preserved = { canonicalPath, siblingPath, sha256: input.expectedSha256, source };
+    await input.recordConflictPreserved(preserved);
+    if (input.creatorCandidate) {
+        await acknowledgeCreatorCandidate(input.creatorCandidate, input.attemptId, input.expectedSha256);
+    }
+    return preserved;
+}
 /**
  * Resolve a conflict interactively or via strategy flag.
  *