@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/dist/sync/candidate-uploader.js

@@ -0,0 +1,212 @@
+/**
+ * Small-object candidate and exact-version read transport for sync protocol v2.
+ *
+ * This module deliberately knows no bucket, object key, or S3 client. The
+ * control-plane routes resolve those coordinates server-side and issue a
+ * short-lived URL.  A candidate PUT returns the immutable S3 VersionId from
+ * S3's response; exact reads verify that same response header before exposing
+ * an unbuffered body to the caller.  Consequently this seam cannot fall back
+ * to a latest-object read or materialize candidate bytes locally.
+ */
+import { createHash } from "node:crypto";
+import { REALTIME_SYNC_CONTRACT_VERSION, } from "./realtime-rollout.js";
+export const MAX_SMALL_CANDIDATE_BYTES = 8 * 1024 * 1024;
+export const MAX_SYNC_DESCRIPTOR_LIFETIME_MS = 60_000;
+const OPAQUE_ID = /^[A-Za-z0-9._~-]{1,512}$/;
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireOpaqueId(value, label) {
+    if (!OPAQUE_ID.test(value))
+        throw new Error(`realtime candidate: ${label} is invalid`);
+    return value;
+}
+function requireNonEmptyString(value, field) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`realtime candidate: ${field} must be a non-empty string`);
+    }
+    return value;
+}
+function requireExactKeys(record, allowed, label) {
+    if (Object.keys(record).some((key) => !allowed.includes(key))) {
+        throw new Error(`realtime candidate: ${label} contains an unknown field`);
+    }
+}
+function parseHeaders(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isRecord(value))
+        throw new Error("realtime candidate: descriptor headers are invalid");
+    const headers = {};
+    for (const [name, entry] of Object.entries(value)) {
+        if (!name || typeof entry !== "string") {
+            throw new Error("realtime candidate: descriptor headers are invalid");
+        }
+        headers[name] = entry;
+    }
+    return headers;
+}
+function parseCandidatePutDescriptor(value) {
+    if (!isRecord(value))
+        throw new Error("realtime candidate: PUT descriptor is not an object");
+    requireExactKeys(value, ["url", "expiresAt", "headers"], "PUT descriptor");
+    return {
+        url: requireNonEmptyString(value.url, "PUT descriptor url"),
+        expiresAt: requireNonEmptyString(value.expiresAt, "PUT descriptor expiresAt"),
+        ...(value.headers === undefined ? {} : { headers: parseHeaders(value.headers) }),
+    };
+}
+function parseExactVersionDescriptor(value) {
+    if (!isRecord(value))
+        throw new Error("realtime candidate: exact GET descriptor is not an object");
+    requireExactKeys(value, ["url", "expiresAt", "versionId", "sha256", "size"], "exact GET descriptor");
+    const sha256 = requireNonEmptyString(value.sha256, "exact GET descriptor sha256");
+    const size = value.size;
+    if (!SHA256.test(sha256) || typeof size !== "number" || !Number.isSafeInteger(size) || size < 0) {
+        throw new Error("realtime candidate: exact GET descriptor metadata is invalid");
+    }
+    return {
+        url: requireNonEmptyString(value.url, "exact GET descriptor url"),
+        expiresAt: requireNonEmptyString(value.expiresAt, "exact GET descriptor expiresAt"),
+        versionId: requireNonEmptyString(value.versionId, "exact GET descriptor versionId"),
+        sha256: sha256,
+        size,
+    };
+}
+function parseJson(text, label) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`realtime candidate: ${label} response is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function responseDetail(response, label) {
+    return response.text().catch((error) => `unable to read error response: ${error instanceof Error ? error.message : String(error)}`).then((detail) => `realtime candidate: ${label} failed (${response.status}): ${detail.slice(0, 300)}`);
+}
+/**
+ * A bounded, fail-closed V2 transport. Its operations intentionally do not
+ * retry a presigned byte request: retrying a possibly-completed PUT could
+ * create a different S3 VersionId. Recovery is status-driven in later units.
+ */
+export class CandidateUploader {
+    apiUrl;
+    fetchImpl;
+    now;
+    authorizationTimeoutMs;
+    constructor(options) {
+        if (!options.apiUrl.trim())
+            throw new Error("realtime candidate: apiUrl is required");
+        this.apiUrl = options.apiUrl.replace(/\/+$/, "");
+        this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+        this.now = options.now ?? Date.now;
+        this.authorizationTimeoutMs = options.authorizationTimeoutMs ?? 15_000;
+        if (!Number.isSafeInteger(this.authorizationTimeoutMs) || this.authorizationTimeoutMs <= 0) {
+            throw new Error("realtime candidate: authorizationTimeoutMs must be a positive integer");
+        }
+    }
+    /** Authorize a small candidate PUT and return S3's exact immutable VersionId. */
+    async uploadSmall(input) {
+        const attemptId = requireOpaqueId(input.attemptId, "attemptId");
+        if (input.bytes.byteLength > MAX_SMALL_CANDIDATE_BYTES) {
+            throw new Error(`realtime candidate: small candidate exceeds ${MAX_SMALL_CANDIDATE_BYTES} bytes`);
+        }
+        const sha256 = `sha256:${createHash("sha256").update(input.bytes).digest("hex")}`;
+        const descriptor = parseCandidatePutDescriptor(await this.controlJson(input.authorization, "POST", `/v2/sync/mutations/${encodeURIComponent(attemptId)}/single/authorize`, { size: input.bytes.byteLength, sha256 }, "single authorize"));
+        this.assertDescriptorLifetime(descriptor.expiresAt, input.authorization.lease);
+        const response = await this.requestPresigned(descriptor.url, { method: "PUT", headers: descriptor.headers ?? {}, body: input.bytes }, "candidate PUT");
+        if (!response.ok)
+            throw new Error(await responseDetail(response, "candidate PUT"));
+        const candidateVersionId = response.headers.get("x-amz-version-id");
+        if (!candidateVersionId || candidateVersionId.trim() === "") {
+            throw new Error("realtime candidate: candidate PUT did not return an exact VersionId");
+        }
+        return { candidateVersionId, sha256, size: input.bytes.byteLength };
+    }
+    /** Open a server-resolved committed delta; never accepts S3 coordinates. */
+    async openCommittedContent(authorization, deltaId) {
+        return this.openExactVersion(authorization, requireOpaqueId(deltaId, "deltaId"), `/v2/sync/content/${encodeURIComponent(deltaId)}`, "committed content");
+    }
+    /** Open a creator-authorized candidate recovery object at its exact VersionId. */
+    async openCandidate(authorization, attemptId) {
+        return this.openExactVersion(authorization, requireOpaqueId(attemptId, "attemptId"), `/v2/sync/mutations/${encodeURIComponent(attemptId)}/candidate`, "candidate GET");
+    }
+    async openExactVersion(authorization, _id, path, label) {
+        const descriptor = parseExactVersionDescriptor(await this.controlJson(authorization, "GET", path, undefined, label));
+        this.assertDescriptorLifetime(descriptor.expiresAt, authorization.lease);
+        const response = await this.requestPresigned(descriptor.url, { method: "GET" }, label);
+        if (!response.ok)
+            throw new Error(await responseDetail(response, label));
+        const returnedVersionId = response.headers.get("x-amz-version-id");
+        if (returnedVersionId !== descriptor.versionId) {
+            throw new Error("realtime candidate: exact GET VersionId does not match its descriptor");
+        }
+        return { ...descriptor, body: response.body };
+    }
+    async controlJson(authorization, method, path, body, label) {
+        this.assertAuthorization(authorization);
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.authorizationTimeoutMs);
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.apiUrl}${path}`, {
+                method,
+                headers: {
+                    ...this.controlHeaders(authorization),
+                    ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+                },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            throw new Error(`realtime candidate: ${label} request failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+        const text = await response.text().catch((error) => {
+            throw new Error(`realtime candidate: unable to read ${label} response: ${error instanceof Error ? error.message : String(error)}`);
+        });
+        if (!response.ok)
+            throw new Error(`realtime candidate: ${label} failed (${response.status}): ${text.slice(0, 300)}`);
+        return parseJson(text, label);
+    }
+    controlHeaders(authorization) {
+        return {
+            Authorization: `Bearer ${requireNonEmptyString(authorization.bearer, "bearer")}`,
+            Accept: "application/json",
+            "X-HQ-Sync-Contract": String(REALTIME_SYNC_CONTRACT_VERSION),
+            "X-HQ-Device-ID": requireNonEmptyString(authorization.deviceId, "deviceId"),
+            "X-HQ-Cloud-Version": requireNonEmptyString(authorization.capabilityVector.hqCloud, "hqCloud version"),
+            "X-HQ-Desktop-Version": requireNonEmptyString(authorization.capabilityVector.hqDesktop, "hqDesktop version"),
+            "X-HQ-Sync-Lease": requireNonEmptyString(authorization.lease.lease, "lease"),
+        };
+    }
+    assertAuthorization(authorization) {
+        const leaseExpiry = Date.parse(authorization.lease.expiresAt);
+        if (!Number.isFinite(leaseExpiry) || leaseExpiry <= this.now()) {
+            throw new Error("realtime candidate: lease expired before guarded I/O");
+        }
+    }
+    assertDescriptorLifetime(expiresAt, lease) {
+        const now = this.now();
+        const descriptorExpiry = Date.parse(expiresAt);
+        const leaseExpiry = Date.parse(lease.expiresAt);
+        if (!Number.isFinite(descriptorExpiry) || !Number.isFinite(leaseExpiry) ||
+            descriptorExpiry <= now || descriptorExpiry > now + MAX_SYNC_DESCRIPTOR_LIFETIME_MS ||
+            descriptorExpiry > leaseExpiry) {
+            throw new Error("realtime candidate: descriptor lifetime exceeds its authorization bound");
+        }
+    }
+    async requestPresigned(url, init, label) {
+        try {
+            return await this.fetchImpl(url, init);
+        }
+        catch (error) {
+            throw new Error(`realtime candidate: ${label} request failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+//# sourceMappingURL=candidate-uploader.js.map

package/dist/sync/candidate-uploader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-uploader.js","sourceRoot":"","sources":["../../src/sync/candidate-uploader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EACL,8BAA8B,GAE/B,MAAM,uBAAuB,CAAC;AAE/B,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AACzD,MAAM,CAAC,MAAM,+BAA+B,GAAG,MAAM,CAAC;AAEtD,MAAM,SAAS,GAAG,0BAA0B,CAAC;AAC7C,MAAM,MAAM,GAAG,uBAAuB,CAAC;AAkEvC,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,eAAe,CAAC,KAAa,EAAE,KAAa;IACnD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,KAAK,aAAa,CAAC,CAAC;IACvF,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAc,EAAE,KAAa;IAC1D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,uBAAuB,KAAK,6BAA6B,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,gBAAgB,CAAC,MAA+B,EAAE,OAA0B,EAAE,KAAa;IAClG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CAAC,uBAAuB,KAAK,4BAA4B,CAAC,CAAC;IAC5E,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IAC5F,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAClD,IAAI,CAAC,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACxB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,2BAA2B,CAAC,KAAc;IACjD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IAC7F,gBAAgB,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,gBAAgB,CAAC,CAAC;IAC3E,OAAO;QACL,GAAG,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAAG,EAAE,oBAAoB,CAAC;QAC3D,SAAS,EAAE,qBAAqB,CAAC,KAAK,CAAC,SAAS,EAAE,0BAA0B,CAAC;QAC7E,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;KACjF,CAAC;AACJ,CAAC;AAED,SAAS,2BAA2B,CAAC,KAAc;IACjD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;IACnG,gBAAgB,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,sBAAsB,CAAC,CAAC;IACrG,MAAM,MAAM,GAAG,qBAAqB,CAAC,KAAK,CAAC,MAAM,EAAE,6BAA6B,CAAC,CAAC;IAClF,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IACxB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;QAChG,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;IAClF,CAAC;IACD,OAAO;QACL,GAAG,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAAG,EAAE,0BAA0B,CAAC;QACjE,SAAS,EAAE,qBAAqB,CAAC,KAAK,CAAC,SAAS,EAAE,gCAAgC,CAAC;QACnF,SAAS,EAAE,qBAAqB,CAAC,KAAK,CAAC,SAAS,EAAE,gCAAgC,CAAC;QACnF,MAAM,EAAE,MAA4B;QACpC,IAAI;KACL,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,IAAY,EAAE,KAAa;IAC5C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,uBAAuB,KAAK,0BAA0B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAC/G,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,QAAgC,EAAE,KAAa;IACrE,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE,CAC9C,kCAAkC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAC3F,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,uBAAuB,KAAK,YAAY,QAAQ,CAAC,MAAM,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;AAC1G,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,iBAAiB;IACX,MAAM,CAAS;IACf,SAAS,CAAiB;IAC1B,GAAG,CAAe;IAClB,sBAAsB,CAAS;IAEhD,YAAY,OAAiC;QAC3C,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;QACtF,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACjD,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAK,UAAU,CAAC,KAAmC,CAAC;QACtF,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;QACnC,IAAI,CAAC,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,IAAI,MAAM,CAAC;QACvE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,sBAAsB,CAAC,IAAI,IAAI,CAAC,sBAAsB,IAAI,CAAC,EAAE,CAAC;YAC3F,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;QAC3F,CAAC;IACH,CAAC;IAED,iFAAiF;IACjF,KAAK,CAAC,WAAW,CAAC,KAAgC;QAChD,MAAM,SAAS,GAAG,eAAe,CAAC,KAAK,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;QAChE,IAAI,KAAK,CAAC,KAAK,CAAC,UAAU,GAAG,yBAAyB,EAAE,CAAC;YACvD,MAAM,IAAI,KAAK,CAAC,+CAA+C,yBAAyB,QAAQ,CAAC,CAAC;QACpG,CAAC;QACD,MAAM,MAAM,GAAG,UAAU,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAwB,CAAC;QACxG,MAAM,UAAU,GAAG,2BAA2B,CAAC,MAAM,IAAI,CAAC,WAAW,CACnE,KAAK,CAAC,aAAa,EACnB,MAAM,EACN,sBAAsB,kBAAkB,CAAC,SAAS,CAAC,mBAAmB,EACtE,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,EACxC,kBAAkB,CACnB,CAAC,CAAC;QACH,IAAI,CAAC,wBAAwB,CAAC,UAAU,CAAC,SAAS,EAAE,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAE/E,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAC1C,UAAU,CAAC,GAAG,EACd,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,EAAE,EACvE,eAAe,CAChB,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,MAAM,cAAc,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC;QACnF,MAAM,kBAAkB,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QACpE,IAAI,CAAC,kBAAkB,IAAI,kBAAkB,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YAC5D,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;QACzF,CAAC;QACD,OAAO,EAAE,kBAAkB,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;IACtE,CAAC;IAED,4EAA4E;IAC5E,KAAK,CAAC,oBAAoB,CACxB,aAA8C,EAC9C,OAAe;QAEf,OAAO,IAAI,CAAC,gBAAgB,CAC1B,aAAa,EACb,eAAe,CAAC,OAAO,EAAE,SAAS,CAAC,EACnC,oBAAoB,kBAAkB,CAAC,OAAO,CAAC,EAAE,EACjD,mBAAmB,CACpB,CAAC;IACJ,CAAC;IAED,kFAAkF;IAClF,KAAK,CAAC,aAAa,CACjB,aAA8C,EAC9C,SAAiB;QAEjB,OAAO,IAAI,CAAC,gBAAgB,CAC1B,aAAa,EACb,eAAe,CAAC,SAAS,EAAE,WAAW,CAAC,EACvC,sBAAsB,kBAAkB,CAAC,SAAS,CAAC,YAAY,EAC/D,eAAe,CAChB,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,gBAAgB,CAC5B,aAA8C,EAC9C,GAAW,EACX,IAAY,EACZ,KAAa;QAEb,MAAM,UAAU,GAAG,2BAA2B,CAAC,MAAM,IAAI,CAAC,WAAW,CACnE,aAAa,EACb,KAAK,EACL,IAAI,EACJ,SAAS,EACT,KAAK,CACN,CAAC,CAAC;QACH,IAAI,CAAC,wBAAwB,CAAC,UAAU,CAAC,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;QACzE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,KAAK,CAAC,CAAC;QACvF,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,MAAM,cAAc,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;QACzE,MAAM,iBAAiB,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QACnE,IAAI,iBAAiB,KAAK,UAAU,CAAC,SAAS,EAAE,CAAC;YAC/C,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;QAC3F,CAAC;QACD,OAAO,EAAE,GAAG,UAAU,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;IAChD,CAAC;IAEO,KAAK,CAAC,WAAW,CACvB,aAA8C,EAC9C,MAAsB,EACtB,IAAY,EACZ,IAAyB,EACzB,KAAa;QAEb,IAAI,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC;QACxC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,sBAAsB,CAAC,CAAC;QAClF,IAAI,QAAgC,CAAC;QACrC,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,EAAE;gBACvD,MAAM;gBACN,OAAO,EAAE;oBACP,GAAG,IAAI,CAAC,cAAc,CAAC,aAAa,CAAC;oBACrC,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC;iBACtE;gBACD,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC7D,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,uBAAuB,KAAK,oBAAoB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC5H,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YAC1D,MAAM,IAAI,KAAK,CAAC,sCAAsC,KAAK,cAAc,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACrI,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,KAAK,YAAY,QAAQ,CAAC,MAAM,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QACrH,OAAO,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAChC,CAAC;IAEO,cAAc,CAAC,aAA8C;QACnE,OAAO;YACL,aAAa,EAAE,UAAU,qBAAqB,CAAC,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE;YAChF,MAAM,EAAE,kBAAkB;YAC1B,oBAAoB,EAAE,MAAM,CAAC,8BAA8B,CAAC;YAC5D,gBAAgB,EAAE,qBAAqB,CAAC,aAAa,CAAC,QAAQ,EAAE,UAAU,CAAC;YAC3E,oBAAoB,EAAE,qBAAqB,CAAC,aAAa,CAAC,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,CAAC;YACtG,sBAAsB,EAAE,qBAAqB,CAAC,aAAa,CAAC,gBAAgB,CAAC,SAAS,EAAE,mBAAmB,CAAC;YAC5G,iBAAiB,EAAE,qBAAqB,CAAC,aAAa,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC;SAC7E,CAAC;IACJ,CAAC;IAEO,mBAAmB,CAAC,aAA8C;QACxE,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC9D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,WAAW,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;YAC/D,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;IAEO,wBAAwB,CAAC,SAAiB,EAAE,KAAoB;QACtE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC/C,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAChD,IACE,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC;YACnE,gBAAgB,IAAI,GAAG,IAAI,gBAAgB,GAAG,GAAG,GAAG,+BAA+B;YACnF,gBAAgB,GAAG,WAAW,EAC9B,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,yEAAyE,CAAC,CAAC;QAC7F,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,gBAAgB,CAC5B,GAAW,EACX,IAAmC,EACnC,KAAa;QAEb,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,uBAAuB,KAAK,oBAAoB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC5H,CAAC;IACH,CAAC;CACF"}

package/dist/sync/candidate-uploader.test.d.ts

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

package/dist/sync/candidate-uploader.test.d.ts.map

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

package/dist/sync/candidate-uploader.test.js

@@ -0,0 +1,132 @@
+import { describe, expect, it, vi } from "vitest";
+import { CandidateUploader, MAX_SMALL_CANDIDATE_BYTES, } from "./candidate-uploader.js";
+const now = Date.parse("2026-08-13T00:00:00.000Z");
+const sha256 = `sha256:${"a".repeat(64)}`;
+const authorization = {
+    bearer: "access-token",
+    deviceId: "device_a",
+    capabilityVector: {
+        hqCloud: "6.14.50",
+        hqDesktop: "none",
+        protocol: 2,
+        journal: 3,
+        durableApply: 2,
+    },
+    lease: {
+        lease: "lease_1",
+        issuedAt: "2026-08-13T00:00:00.000Z",
+        expiresAt: "2026-08-13T00:01:00.000Z",
+        authorizationEpoch: "epoch_1",
+    },
+};
+function response(status, body = "", headers = {}, stream = null) {
+    const lowered = new Map(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]));
+    return {
+        ok: status >= 200 && status < 300,
+        status,
+        headers: { get: (name) => lowered.get(name.toLowerCase()) ?? null },
+        body: stream,
+        text: async () => typeof body === "string" ? body : JSON.stringify(body),
+    };
+}
+function uploader(fetchImpl) {
+    return new CandidateUploader({ apiUrl: "https://api.example.test/", fetchImpl, now: () => now });
+}
+describe("CandidateUploader", () => {
+    it("authorizes a small candidate PUT then returns S3's exact VersionId without a latest read", async () => {
+        const fetchImpl = vi.fn()
+            .mockResolvedValueOnce(response(200, {
+            url: "https://s3.example.test/candidate-put",
+            expiresAt: "2026-08-13T00:00:45.000Z",
+            headers: { "content-type": "application/octet-stream", "x-amz-checksum-sha256": "signed" },
+        }))
+            .mockResolvedValueOnce(response(200, "", { "x-amz-version-id": "candidate-version-7" }));
+        await expect(uploader(fetchImpl).uploadSmall({
+            authorization,
+            attemptId: "attempt_7",
+            bytes: Buffer.from("candidate bytes"),
+        })).resolves.toEqual({
+            candidateVersionId: "candidate-version-7",
+            sha256: "sha256:732d058fadd90c70f22429227ab5d9c74919217099efe737aa46835ce3a60856",
+            size: 15,
+        });
+        expect(fetchImpl).toHaveBeenCalledTimes(2);
+        const [authorizeUrl, authorizeInit] = fetchImpl.mock.calls[0];
+        expect(authorizeUrl).toBe("https://api.example.test/v2/sync/mutations/attempt_7/single/authorize");
+        expect(authorizeInit).toMatchObject({
+            method: "POST",
+            headers: expect.objectContaining({
+                Authorization: "Bearer access-token",
+                "X-HQ-Sync-Contract": "2",
+                "X-HQ-Sync-Lease": "lease_1",
+            }),
+        });
+        expect(JSON.parse(authorizeInit?.body)).toEqual({
+            size: 15,
+            sha256: "sha256:732d058fadd90c70f22429227ab5d9c74919217099efe737aa46835ce3a60856",
+        });
+        expect(fetchImpl.mock.calls[1]).toEqual([
+            "https://s3.example.test/candidate-put",
+            expect.objectContaining({ method: "PUT", body: Buffer.from("candidate bytes") }),
+        ]);
+    });
+    it("refuses an oversize candidate before authorizing or transferring bytes", async () => {
+        const fetchImpl = vi.fn();
+        await expect(uploader(fetchImpl).uploadSmall({
+            authorization,
+            attemptId: "attempt_7",
+            bytes: Buffer.alloc(MAX_SMALL_CANDIDATE_BYTES + 1),
+        })).rejects.toThrow("small candidate exceeds");
+        expect(fetchImpl).not.toHaveBeenCalled();
+    });
+    it("fails closed when the candidate PUT lacks S3's immutable VersionId", async () => {
+        const fetchImpl = vi.fn()
+            .mockResolvedValueOnce(response(200, { url: "https://s3.example.test/candidate-put", expiresAt: "2026-08-13T00:00:45.000Z" }))
+            .mockResolvedValueOnce(response(200));
+        await expect(uploader(fetchImpl).uploadSmall({ authorization, attemptId: "attempt_7", bytes: Buffer.from("x") }))
+            .rejects.toThrow("did not return an exact VersionId");
+    });
+    it("opens only the server-resolved exact committed VersionId and leaves its body unmaterialized", async () => {
+        async function* bytes() { yield Buffer.from("exact bytes"); }
+        const stream = bytes();
+        const fetchImpl = vi.fn()
+            .mockResolvedValueOnce(response(200, {
+            url: "https://s3.example.test/exact-get",
+            expiresAt: "2026-08-13T00:00:45.000Z",
+            versionId: "canonical-version-9",
+            sha256,
+            size: 11,
+        }))
+            .mockResolvedValueOnce(response(200, "", { "x-amz-version-id": "canonical-version-9" }, stream));
+        const exact = await uploader(fetchImpl).openCommittedContent(authorization, "delta_9");
+        expect(exact).toMatchObject({ versionId: "canonical-version-9", sha256, size: 11, body: stream });
+        expect(fetchImpl.mock.calls[0]?.[0]).toBe("https://api.example.test/v2/sync/content/delta_9");
+        expect(fetchImpl.mock.calls[1]?.[0]).toBe("https://s3.example.test/exact-get");
+        expect(fetchImpl.mock.calls[1]?.[1]).toMatchObject({ method: "GET" });
+        expect(fetchImpl.mock.calls[1]?.[1]).not.toHaveProperty("body");
+    });
+    it("rejects an overlong descriptor and a GET whose S3 VersionId differs from the descriptor", async () => {
+        const overlong = vi.fn().mockResolvedValueOnce(response(200, {
+            url: "https://s3.example.test/exact-get",
+            expiresAt: "2026-08-13T00:01:01.000Z",
+            versionId: "candidate-version-7",
+            sha256,
+            size: 1,
+        }));
+        await expect(uploader(overlong).openCandidate(authorization, "attempt_7"))
+            .rejects.toThrow("descriptor lifetime exceeds");
+        expect(overlong).toHaveBeenCalledTimes(1);
+        const mismatch = vi.fn()
+            .mockResolvedValueOnce(response(200, {
+            url: "https://s3.example.test/exact-get",
+            expiresAt: "2026-08-13T00:00:45.000Z",
+            versionId: "candidate-version-7",
+            sha256,
+            size: 1,
+        }))
+            .mockResolvedValueOnce(response(200, "", { "x-amz-version-id": "latest-version-8" }));
+        await expect(uploader(mismatch).openCandidate(authorization, "attempt_7"))
+            .rejects.toThrow("VersionId does not match");
+    });
+});
+//# sourceMappingURL=candidate-uploader.test.js.map

package/dist/sync/candidate-uploader.test.js.map

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

package/dist/sync/delta-client.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Fixed-ceiling delta reader for realtime vault sync v2.
+ *
+ * A drain deliberately has two request shapes: its first request has the
+ * recipient cursor and later requests have only the opaque page token.  This
+ * makes it impossible for the client to accidentally turn a fixed-H drain
+ * into a new high-water request while it is following a page chain.  Applying
+ * a page (and making its cursor durable) belongs to U54; this module does not
+ * persist or advance a cursor itself.
+ */
+import type { CandidateFetch, CandidateTransportAuthorization } from "./candidate-uploader.js";
+export type DeltaOperation = "upsert" | "delete";
+export interface DeltaRecord {
+    deltaId: string;
+    canonicalPath: string;
+    operation: DeltaOperation;
+    versionId: string | null;
+    /** Source facts decide regular-file versus symlink application in U54. */
+    source: {
+        kind: "regular" | "symlink";
+        mode: number;
+    } | null;
+}
+export interface DeltaPage {
+    /** Immutable recipient-bound high-water cursor for every page in a drain. */
+    untilCursor: string;
+    /** A hidden projection page is valid: `deltas` may be empty while this exists. */
+    nextPageToken: string | null;
+    deltas: readonly DeltaRecord[];
+}
+export interface DeltaClientOptions {
+    apiUrl: string;
+    fetchImpl?: CandidateFetch;
+    now?: () => number;
+    authorizationTimeoutMs?: number;
+}
+export interface DeltaDrainRequest {
+    authorization: CandidateTransportAuthorization;
+    scopeHandle: string;
+    scopeRevision: string;
+    cursor: string;
+    /** The server chooses the effective page size; this is merely its bounded request limit. */
+    limit: number;
+}
+export interface DeltaDrainResult {
+    untilCursor: string;
+    pages: number;
+    deltas: number;
+}
+export declare class DeltaGapError extends Error {
+    constructor(message?: string);
+}
+export declare class CursorRetiredError extends Error {
+    constructor(message?: string);
+}
+/**
+ * The V2 reader has no LIST capability or dependency.  Its callback is
+ * awaited before another page is requested, so a future durable applier can
+ * make every page's effects and cursor durable before the next page arrives.
+ */
+export declare class DeltaClient {
+    private readonly apiUrl;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly timeoutMs;
+    constructor(options: DeltaClientOptions);
+    drain(request: DeltaDrainRequest, consume: (page: DeltaPage) => Promise<void>): Promise<DeltaDrainResult>;
+    private assertRequest;
+    private getPage;
+    private assertLease;
+    private request;
+}
+//# sourceMappingURL=delta-client.d.ts.map

package/dist/sync/delta-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta-client.d.ts","sourceRoot":"","sources":["../../src/sync/delta-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,cAAc,EAA0B,+BAA+B,EAAE,MAAM,yBAAyB,CAAC;AAGvH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,cAAc,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,0EAA0E;IAC1E,MAAM,EAAE;QAAE,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC9D;AAED,MAAM,WAAW,SAAS;IACxB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,+BAA+B,CAAC;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,SAAuD;CAI3E;AAED,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,SAA4D;CAIhF;AAqED;;;;GAIG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;IAC3C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,OAAO,EAAE,kBAAkB;IASjC,KAAK,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA6B/G,OAAO,CAAC,aAAa;YAQP,OAAO;IAkBrB,OAAO,CAAC,WAAW;YAKL,OAAO;CA2BtB"}