@indigoai-us/hq-cloud 6.14.50 → 6.15.1

package/dist/sync/scope-inventory-client.test.js

@@ -0,0 +1,94 @@
+import * as crypto 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 { ScopeInventoryClient, disposeLocalMaterial, parseLocalMaterialPolicy, } from "./scope-inventory-client.js";
+const roots = [];
+function root() {
+    const value = fs.mkdtempSync(path.join(os.tmpdir(), "scope-inventory-"));
+    roots.push(value);
+    return value;
+}
+function sha256(value) {
+    return `sha256:${crypto.createHash("sha256").update(value).digest("hex")}`;
+}
+function inventoryClient(inventories) {
+    return {
+        inventory: vi.fn(async () => inventories.shift()),
+    };
+}
+function request() {
+    return {
+        bearer: "access-token",
+        deviceId: "device-1",
+        capabilityVector: { hqCloud: "6.0.0", hqDesktop: "none", protocol: 2, journal: 3, durableApply: 2 },
+        configurationFingerprint: "configuration-a",
+        scopeFingerprint: "scope-a",
+    };
+}
+afterEach(() => {
+    for (const directory of roots.splice(0))
+        fs.rmSync(directory, { recursive: true, force: true });
+});
+describe("ScopeInventoryClient", () => {
+    it("stops network work on reset, then permits legacy only after a fresh returning-device inventory", async () => {
+        const client = inventoryClient([
+            { scopes: [{ scopeUid: "prs_1", scopeHandle: "h1", scopeRevision: "r1", state: "reset-required", resetId: "reset-1", snapshotDescriptorId: "snap-1" }] },
+            { scopes: [{ scopeUid: "prs_1", scopeHandle: "h2", scopeRevision: "r2", state: "legacy", v1Allowed: true }] },
+        ]);
+        const gate = new ScopeInventoryClient({ inventory: client, request: request() });
+        await expect(gate.refresh("prs_1")).resolves.toMatchObject({ network: "stop", state: "reset-required", reason: "reset-required" });
+        await expect(gate.refresh("prs_1")).resolves.toMatchObject({ network: "allow-legacy", state: "legacy", grant: { scopeRevision: "r2" } });
+        expect(client.inventory).toHaveBeenCalledTimes(2);
+    });
+    it("fails closed for a revoked or absent scope and retains unknown local policy", async () => {
+        const client = inventoryClient([
+            { scopes: [{ scopeUid: "cmp_1", scopeHandle: "h", scopeRevision: "r", state: "revoked", localMaterialPolicy: "future-policy" }] },
+            { scopes: [] },
+        ]);
+        const gate = new ScopeInventoryClient({ inventory: client, request: request() });
+        await expect(gate.refresh("cmp_1")).resolves.toEqual(expect.objectContaining({
+            network: "stop", state: "revoked", reason: "scope-revoked", localMaterialPolicy: "retain",
+        }));
+        await expect(gate.refresh("cmp_1")).resolves.toEqual({ network: "stop", state: "absent", reason: "scope-absent" });
+        expect(parseLocalMaterialPolicy("not-yet-defined")).toBe("retain");
+    });
+});
+describe("disposeLocalMaterial", () => {
+    it("deletes only a hash-matching file and fsyncs its parent", () => {
+        const local = root();
+        const file = path.join(local, "notes/a.md");
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, "baseline");
+        expect(disposeLocalMaterial({
+            rootDir: local,
+            relativePath: "notes/a.md",
+            synchronizedSha256: sha256("baseline"),
+            policy: "delete-if-hash-matches",
+        })).toEqual({ outcome: "deleted", sha256: sha256("baseline") });
+        expect(fs.existsSync(file)).toBe(false);
+    });
+    it("never deletes divergent bytes: it hash-verifies and fsyncs a quarantine copy first", () => {
+        const local = root();
+        const quarantineRoot = root();
+        const file = path.join(local, "notes/a.md");
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, "divergent local bytes");
+        const result = disposeLocalMaterial({
+            rootDir: local,
+            relativePath: "notes/a.md",
+            synchronizedSha256: sha256("baseline"),
+            policy: "delete-if-hash-matches",
+            quarantineRoot,
+        });
+        expect(result).toEqual({
+            outcome: "quarantined",
+            sha256: sha256("divergent local bytes"),
+            quarantinePath: path.join(quarantineRoot, "notes/a.md"),
+        });
+        expect(fs.existsSync(file)).toBe(false);
+        expect(fs.readFileSync(path.join(quarantineRoot, "notes/a.md"), "utf8")).toBe("divergent local bytes");
+    });
+});
+//# sourceMappingURL=scope-inventory-client.test.js.map

package/dist/sync/scope-inventory-client.test.js.map

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

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

@@ -0,0 +1,98 @@
+import { type CandidateFetch, type CandidateTransportAuthorization } from "./candidate-uploader.js";
+import { type DeltaDrainResult } from "./delta-client.js";
+import { DurableApplyEngine } from "./durable-apply.js";
+type SnapshotSource = {
+    kind: "regular" | "symlink";
+    mode: number;
+};
+export interface SnapshotDescriptor {
+    descriptorId: string;
+    projectionDigest: `sha256:${string}`;
+    checksum: `sha256:${string}`;
+    barrier: {
+        epoch: string;
+        sequence: string;
+    };
+    /** Recipient-bound opaque cursor minted at this descriptor's barrier H. */
+    cursor: string;
+    url: string;
+    expiresAt: string;
+    versionId: string;
+}
+export interface SnapshotManifestEntry {
+    canonicalPath: string;
+    headState: "present" | "deleted";
+    versionId: string | null;
+    /** Server-authorized exact-version content identity; never an S3 coordinate. */
+    deltaId: string;
+    source?: SnapshotSource;
+    sha256?: `sha256:${string}`;
+    size?: number;
+}
+interface PersistedDescriptor {
+    descriptorId: string;
+    projectionDigest: `sha256:${string}`;
+    checksum: `sha256:${string}`;
+    barrier: {
+        epoch: string;
+        sequence: string;
+    };
+    cursor: string;
+    versionId: string;
+    resetId: string | null;
+}
+export interface SnapshotState {
+    descriptor: PersistedDescriptor | null;
+    manifestApplied: boolean;
+    resetAcknowledged: boolean;
+}
+export interface SnapshotClientOptions {
+    apiUrl: string;
+    stateRootDir: string;
+    scopeId: string;
+    fetchImpl?: CandidateFetch;
+    now?: () => number;
+    authorizationTimeoutMs?: number;
+}
+export interface SnapshotReconcileRequest {
+    authorization: CandidateTransportAuthorization;
+    scopeHandle: string;
+    scopeRevision: string;
+    descriptorId: string;
+    /** Required for reset-required; omit only for a bootstrap snapshot. */
+    resetId?: string;
+    durableApply: DurableApplyEngine;
+    deltaLimit?: number;
+}
+export interface SnapshotReconcileResult {
+    descriptorId: string;
+    cursor: string;
+    manifestEntries: number;
+    resetAcknowledged: boolean;
+    postSnapshotDrain: DeltaDrainResult;
+}
+export declare class SnapshotClientError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class SnapshotClient {
+    private readonly apiUrl;
+    private readonly scopeId;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly timeoutMs;
+    private readonly store;
+    private readonly content;
+    private readonly delta;
+    constructor(options: SnapshotClientOptions);
+    getState(): SnapshotState;
+    reconcile(request: SnapshotReconcileRequest): Promise<SnapshotReconcileResult>;
+    private fetchDescriptor;
+    private fetchManifest;
+    private fetchContent;
+    private fetchDeltaContent;
+    private acknowledgeReset;
+    private controlRequest;
+    private request;
+}
+export {};
+//# sourceMappingURL=snapshot-client.d.ts.map

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

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

package/dist/sync/snapshot-client.js

@@ -0,0 +1,402 @@
+/**
+ * Projection snapshot and reset receiver for realtime sync v2.
+ *
+ * Snapshots are a fixed manifest at a server FIFO barrier H.  This client
+ * persists the descriptor before touching the manifest, applies every entry
+ * through the ordinary durable applier, acknowledges a reset with H's opaque
+ * recipient cursor, and then starts the normal fixed-H delta drain at H.
+ * It deliberately has no S3 coordinates or LIST operation in its surface.
+ */
+import { createHash } from "node:crypto";
+import { CandidateUploader, } from "./candidate-uploader.js";
+import { DeltaClient } from "./delta-client.js";
+import { StateStore } from "./state-store.js";
+const SNAPSHOT_DESCRIPTOR = 601;
+const SNAPSHOT_MANIFEST_APPLIED = 602;
+const SNAPSHOT_RESET_ACKNOWLEDGED = 603;
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+const OPAQUE = /^[A-Za-z0-9._~-]{1,4096}$/;
+export class SnapshotClientError extends Error {
+    constructor(message, options) {
+        super(`realtime snapshot: ${message}`, options);
+        this.name = "SnapshotClientError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function exactKeys(value, keys, label) {
+    if (Object.keys(value).length !== keys.length || Object.keys(value).some((key) => !keys.includes(key))) {
+        throw new SnapshotClientError(`${label} contains unknown or missing fields`);
+    }
+}
+function nonEmpty(value, label) {
+    if (typeof value !== "string" || value.trim() === "")
+        throw new SnapshotClientError(`${label} must be a non-empty string`);
+    return value;
+}
+function opaque(value, label) {
+    const result = nonEmpty(value, label);
+    if (!OPAQUE.test(result))
+        throw new SnapshotClientError(`${label} is invalid`);
+    return result;
+}
+function digest(value, label) {
+    const result = nonEmpty(value, label);
+    if (!SHA256.test(result))
+        throw new SnapshotClientError(`${label} is invalid`);
+    return result;
+}
+function position(value, label) {
+    const result = nonEmpty(value, label);
+    if (!/^(0|[1-9][0-9]*)$/.test(result))
+        throw new SnapshotClientError(`${label} is invalid`);
+    return result;
+}
+function canonicalPath(value) {
+    const result = nonEmpty(value, "snapshot canonicalPath");
+    if (result.includes("\\") || result.startsWith("/") || result.startsWith(".hq-control/") || result.endsWith("/") || result.split("/").some((part) => !part || part === "." || part === "..")) {
+        throw new SnapshotClientError("snapshot canonicalPath is invalid");
+    }
+    return result;
+}
+function parseSource(value) {
+    if (!isRecord(value))
+        throw new SnapshotClientError("snapshot source is invalid");
+    exactKeys(value, ["kind", "mode"], "snapshot source");
+    if ((value.kind !== "regular" && value.kind !== "symlink") || typeof value.mode !== "number" || !Number.isSafeInteger(value.mode) || value.mode < 0 || value.mode > 0o7777) {
+        throw new SnapshotClientError("snapshot source is invalid");
+    }
+    return { kind: value.kind, mode: value.mode };
+}
+function parseDescriptor(value, now, leaseExpiresAt) {
+    if (!isRecord(value))
+        throw new SnapshotClientError("descriptor response is not an object");
+    exactKeys(value, ["descriptorId", "projectionDigest", "checksum", "barrier", "cursor", "url", "expiresAt", "versionId"], "descriptor response");
+    if (!isRecord(value.barrier))
+        throw new SnapshotClientError("descriptor barrier is invalid");
+    exactKeys(value.barrier, ["epoch", "sequence"], "descriptor barrier");
+    const expiresAt = nonEmpty(value.expiresAt, "descriptor expiresAt");
+    const expiry = Date.parse(expiresAt);
+    const leaseExpiry = Date.parse(leaseExpiresAt);
+    if (!Number.isFinite(expiry) || !Number.isFinite(leaseExpiry) || expiry <= now || expiry > now + 60_000 || expiry > leaseExpiry) {
+        throw new SnapshotClientError("descriptor lifetime exceeds its authorization bound");
+    }
+    return {
+        descriptorId: opaque(value.descriptorId, "descriptorId"),
+        projectionDigest: digest(value.projectionDigest, "projectionDigest"),
+        checksum: digest(value.checksum, "checksum"),
+        barrier: { epoch: position(value.barrier.epoch, "barrier epoch"), sequence: position(value.barrier.sequence, "barrier sequence") },
+        cursor: opaque(value.cursor, "descriptor cursor"),
+        url: nonEmpty(value.url, "descriptor url"),
+        expiresAt,
+        versionId: nonEmpty(value.versionId, "descriptor versionId"),
+    };
+}
+function parseEntry(value) {
+    if (!isRecord(value))
+        throw new SnapshotClientError("snapshot entry is not an object");
+    const headState = value.headState;
+    const presentKeys = ["canonicalPath", "headState", "versionId", "deltaId", "source", "sha256", "size"];
+    const deletedKeys = ["canonicalPath", "headState", "versionId", "deltaId"];
+    if (headState !== "present" && headState !== "deleted")
+        throw new SnapshotClientError("snapshot entry headState is invalid");
+    exactKeys(value, headState === "present" ? presentKeys : deletedKeys, "snapshot entry");
+    const entry = {
+        canonicalPath: canonicalPath(value.canonicalPath),
+        headState,
+        versionId: value.versionId === null ? null : nonEmpty(value.versionId, "snapshot versionId"),
+        deltaId: opaque(value.deltaId, "snapshot deltaId"),
+    };
+    if (headState === "present") {
+        if (entry.versionId === null || typeof value.size !== "number" || !Number.isSafeInteger(value.size) || value.size < 0) {
+            throw new SnapshotClientError("present snapshot entry lacks immutable content metadata");
+        }
+        entry.source = parseSource(value.source);
+        entry.sha256 = digest(value.sha256, "snapshot sha256");
+        entry.size = value.size;
+    }
+    else if (entry.versionId !== null) {
+        throw new SnapshotClientError("deleted snapshot entry carries a versionId");
+    }
+    return entry;
+}
+function parseManifest(value) {
+    if (!isRecord(value))
+        throw new SnapshotClientError("manifest is not an object");
+    exactKeys(value, ["contractVersion", "scopeUid", "projectionDigest", "authorizationContextDigest", "barrier", "entries"], "manifest");
+    if (value.contractVersion !== 3 || !isRecord(value.barrier) || !Array.isArray(value.entries))
+        throw new SnapshotClientError("manifest shape is invalid");
+    exactKeys(value.barrier, ["epoch", "sequence"], "manifest barrier");
+    const entries = value.entries.map(parseEntry);
+    const paths = new Set(entries.map((entry) => entry.canonicalPath));
+    if (paths.size !== entries.length)
+        throw new SnapshotClientError("manifest repeats a canonical path");
+    return {
+        contractVersion: 3,
+        scopeUid: opaque(value.scopeUid, "manifest scopeUid"),
+        projectionDigest: digest(value.projectionDigest, "manifest projectionDigest"),
+        authorizationContextDigest: digest(value.authorizationContextDigest, "manifest authorizationContextDigest"),
+        barrier: { epoch: position(value.barrier.epoch, "manifest barrier epoch"), sequence: position(value.barrier.sequence, "manifest barrier sequence") },
+        entries,
+    };
+}
+/** RFC 8785's object-key sorting is enough here because wire values are strings, integers, arrays and objects. */
+function canonicalJson(value) {
+    if (value === null || typeof value === "boolean")
+        return JSON.stringify(value);
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new SnapshotClientError("manifest contains a non-finite number");
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (!isRecord(value))
+        throw new SnapshotClientError("manifest contains an unsupported value");
+    return `{${Object.entries(value).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([key, entry]) => `${canonicalJson(key)}:${canonicalJson(entry)}`).join(",")}}`;
+}
+function checksum(value) {
+    return `sha256:${createHash("sha256").update(canonicalJson(value), "utf8").digest("hex")}`;
+}
+function descriptorForStore(descriptor, resetId) {
+    return {
+        descriptorId: descriptor.descriptorId,
+        projectionDigest: descriptor.projectionDigest,
+        checksum: descriptor.checksum,
+        barrier: descriptor.barrier,
+        cursor: descriptor.cursor,
+        versionId: descriptor.versionId,
+        resetId: resetId === undefined ? null : opaque(resetId, "resetId"),
+    };
+}
+function parsePersistedDescriptor(value) {
+    if (!isRecord(value))
+        throw new SnapshotClientError("snapshot descriptor WAL record is invalid");
+    exactKeys(value, ["descriptorId", "projectionDigest", "checksum", "barrier", "cursor", "versionId", "resetId"], "snapshot descriptor WAL record");
+    if (!isRecord(value.barrier))
+        throw new SnapshotClientError("snapshot descriptor WAL barrier is invalid");
+    exactKeys(value.barrier, ["epoch", "sequence"], "snapshot descriptor WAL barrier");
+    if (value.resetId !== null && typeof value.resetId !== "string")
+        throw new SnapshotClientError("snapshot descriptor WAL resetId is invalid");
+    return {
+        descriptorId: opaque(value.descriptorId, "descriptorId"),
+        projectionDigest: digest(value.projectionDigest, "projectionDigest"),
+        checksum: digest(value.checksum, "checksum"),
+        barrier: { epoch: position(value.barrier.epoch, "barrier epoch"), sequence: position(value.barrier.sequence, "barrier sequence") },
+        cursor: opaque(value.cursor, "descriptor cursor"),
+        versionId: nonEmpty(value.versionId, "descriptor versionId"),
+        resetId: value.resetId === null ? null : opaque(value.resetId, "resetId"),
+    };
+}
+function sameDescriptor(left, right) {
+    return left.descriptorId === right.descriptorId && left.projectionDigest === right.projectionDigest && left.checksum === right.checksum &&
+        left.barrier.epoch === right.barrier.epoch && left.barrier.sequence === right.barrier.sequence && left.cursor === right.cursor &&
+        left.versionId === right.versionId && left.resetId === right.resetId;
+}
+function snapshotReducer(state, record) {
+    if (record.type === SNAPSHOT_DESCRIPTOR) {
+        const descriptor = parsePersistedDescriptor(record.payload);
+        return { descriptor, manifestApplied: false, resetAcknowledged: descriptor.resetId === null };
+    }
+    if (record.type === SNAPSHOT_MANIFEST_APPLIED) {
+        if (!isRecord(record.payload) || record.payload.descriptorId !== state.descriptor?.descriptorId)
+            throw new SnapshotClientError("snapshot applied WAL record is invalid");
+        return { ...state, manifestApplied: true };
+    }
+    if (record.type === SNAPSHOT_RESET_ACKNOWLEDGED) {
+        if (!isRecord(record.payload) || record.payload.descriptorId !== state.descriptor?.descriptorId)
+            throw new SnapshotClientError("snapshot reset acknowledgement WAL record is invalid");
+        return { ...state, resetAcknowledged: true };
+    }
+    throw new SnapshotClientError(`unknown snapshot WAL record type ${record.type}`);
+}
+function snapshotDeleteId(descriptorId, canonicalPath) {
+    return `snapshot_${createHash("sha256").update(`${descriptorId}\0${canonicalPath}`, "utf8").digest("hex")}`;
+}
+function snapshotDeltas(entries, apply, descriptorId) {
+    const mentioned = new Set(entries.map((entry) => entry.canonicalPath));
+    const stale = Object.keys(apply.getState().paths)
+        .filter((canonicalPath) => !mentioned.has(canonicalPath))
+        .sort()
+        .map((canonicalPath) => ({ deltaId: snapshotDeleteId(descriptorId, canonicalPath), canonicalPath, operation: "delete", versionId: null, source: null }));
+    const deletes = entries.filter((entry) => entry.headState === "deleted")
+        .map((entry) => ({ deltaId: entry.deltaId, canonicalPath: entry.canonicalPath, operation: "delete", versionId: null, source: null }));
+    const upserts = entries.filter((entry) => entry.headState === "present")
+        .map((entry) => ({ deltaId: entry.deltaId, canonicalPath: entry.canonicalPath, operation: "upsert", versionId: entry.versionId, source: entry.source }));
+    // A deleted file can be an ancestor of a new child path, so every delete must
+    // become durable before an upsert is allowed to create its parent directory.
+    return [...deletes, ...stale, ...upserts];
+}
+async function readAll(body, expectedSize) {
+    if (body === null)
+        throw new SnapshotClientError("exact content body is missing");
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of body) {
+        size += chunk.byteLength;
+        if (size > expectedSize)
+            throw new SnapshotClientError("exact content exceeds its descriptor size");
+        chunks.push(Buffer.from(chunk));
+    }
+    if (size !== expectedSize)
+        throw new SnapshotClientError("exact content size disagrees with its descriptor");
+    return Buffer.concat(chunks);
+}
+export class SnapshotClient {
+    apiUrl;
+    scopeId;
+    fetchImpl;
+    now;
+    timeoutMs;
+    store;
+    content;
+    delta;
+    constructor(options) {
+        if (!options.apiUrl.trim())
+            throw new SnapshotClientError("apiUrl is required");
+        if (!options.scopeId)
+            throw new SnapshotClientError("scopeId is required");
+        this.apiUrl = options.apiUrl.replace(/\/+$/, "");
+        this.scopeId = opaque(options.scopeId, "scopeId");
+        this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+        this.now = options.now ?? Date.now;
+        this.timeoutMs = options.authorizationTimeoutMs ?? 15_000;
+        if (!Number.isSafeInteger(this.timeoutMs) || this.timeoutMs < 1)
+            throw new SnapshotClientError("authorizationTimeoutMs must be positive");
+        this.store = StateStore.open({ rootDir: options.stateRootDir, scopeId: `${this.scopeId}:snapshot`, initialState: { descriptor: null, manifestApplied: false, resetAcknowledged: false }, reduce: snapshotReducer });
+        const transport = { apiUrl: this.apiUrl, fetchImpl: this.fetchImpl, now: this.now, authorizationTimeoutMs: this.timeoutMs };
+        this.content = new CandidateUploader(transport);
+        this.delta = new DeltaClient(transport);
+    }
+    getState() {
+        return this.store.getState();
+    }
+    async reconcile(request) {
+        const descriptor = await this.fetchDescriptor(request.authorization, request.descriptorId);
+        const persisted = descriptorForStore(descriptor, request.resetId);
+        const current = this.store.getState();
+        if (current.descriptor === null || current.descriptor.descriptorId !== persisted.descriptorId) {
+            if (current.descriptor !== null && !current.resetAcknowledged)
+                throw new SnapshotClientError("a different snapshot is pending reset acknowledgement");
+            this.store.append(SNAPSHOT_DESCRIPTOR, persisted);
+        }
+        else if (!sameDescriptor(current.descriptor, persisted)) {
+            throw new SnapshotClientError("descriptor changed after durable persistence");
+        }
+        let manifestEntries = 0;
+        if (!this.store.getState().manifestApplied) {
+            const manifestRaw = await this.fetchManifest(descriptor);
+            const manifest = parseManifest(manifestRaw);
+            if (manifest.projectionDigest !== descriptor.projectionDigest || manifest.barrier.epoch !== descriptor.barrier.epoch || manifest.barrier.sequence !== descriptor.barrier.sequence || checksum(manifestRaw) !== descriptor.checksum) {
+                throw new SnapshotClientError("manifest does not match its immutable descriptor");
+            }
+            if (manifest.scopeUid !== this.scopeId)
+                throw new SnapshotClientError("manifest scope does not match this client");
+            manifestEntries = manifest.entries.length;
+            const byDeltaId = new Map(manifest.entries.filter((entry) => entry.headState === "present").map((entry) => [entry.deltaId, entry]));
+            await request.durableApply.applyPage({ untilCursor: descriptor.cursor, nextPageToken: null, deltas: snapshotDeltas(manifest.entries, request.durableApply, descriptor.descriptorId) }, async (delta) => this.fetchContent(request.authorization, delta, byDeltaId));
+            if (request.durableApply.getState().cursor !== descriptor.cursor)
+                throw new SnapshotClientError("snapshot filesystem effects were not durably joined to cursor H");
+            this.store.append(SNAPSHOT_MANIFEST_APPLIED, { descriptorId: descriptor.descriptorId });
+        }
+        const state = this.store.getState();
+        const storedDescriptor = state.descriptor;
+        if (storedDescriptor !== null && storedDescriptor.resetId !== null && !state.resetAcknowledged) {
+            await this.acknowledgeReset(request.authorization, storedDescriptor.resetId, descriptor.checksum, descriptor.cursor);
+            this.store.append(SNAPSHOT_RESET_ACKNOWLEDGED, { descriptorId: descriptor.descriptorId });
+        }
+        const cursor = request.durableApply.getState().cursor;
+        if (!cursor)
+            throw new SnapshotClientError("snapshot did not leave a durable cursor");
+        const postSnapshotDrain = await this.delta.drain({ authorization: request.authorization, scopeHandle: request.scopeHandle, scopeRevision: request.scopeRevision, cursor, limit: request.deltaLimit ?? 100 }, async (page) => request.durableApply.applyPage(page, async (delta) => this.fetchDeltaContent(request.authorization, delta)));
+        return { descriptorId: descriptor.descriptorId, cursor: descriptor.cursor, manifestEntries, resetAcknowledged: this.store.getState().resetAcknowledged || this.store.getState().descriptor?.resetId === null, postSnapshotDrain };
+    }
+    async fetchDescriptor(authorization, descriptorId) {
+        const { response, text } = await this.controlRequest(authorization, "GET", `/v2/sync/snapshots/${encodeURIComponent(opaque(descriptorId, "descriptorId"))}`);
+        if (!response.ok)
+            throw new SnapshotClientError(`descriptor request failed (${response.status}): ${text.slice(0, 300)}`);
+        try {
+            return parseDescriptor(JSON.parse(text), this.now(), authorization.lease.expiresAt);
+        }
+        catch (error) {
+            throw error instanceof SnapshotClientError ? error : new SnapshotClientError("descriptor response is invalid", { cause: error });
+        }
+    }
+    async fetchManifest(descriptor) {
+        const response = await this.request(descriptor.url, { method: "GET" }, "manifest GET");
+        if (!response.ok)
+            throw new SnapshotClientError(`manifest GET failed (${response.status})`);
+        if (response.headers.get("x-amz-version-id") !== descriptor.versionId)
+            throw new SnapshotClientError("manifest GET did not return its exact VersionId");
+        try {
+            const value = JSON.parse(await response.text());
+            if (!isRecord(value))
+                throw new SnapshotClientError("manifest is not an object");
+            return value;
+        }
+        catch (error) {
+            throw error instanceof SnapshotClientError ? error : new SnapshotClientError("manifest response is not JSON", { cause: error });
+        }
+    }
+    async fetchContent(authorization, delta, entries) {
+        const entry = entries.get(delta.deltaId);
+        if (!entry || entry.headState !== "present" || entry.source === undefined || entry.sha256 === undefined || entry.size === undefined || entry.versionId !== delta.versionId) {
+            throw new SnapshotClientError(`snapshot delta ${delta.deltaId} lacks immutable content metadata`);
+        }
+        const exact = await this.content.openCommittedContent(authorization, delta.deltaId);
+        if (exact.versionId !== entry.versionId || exact.sha256 !== entry.sha256 || exact.size !== entry.size)
+            throw new SnapshotClientError(`snapshot delta ${delta.deltaId} exact descriptor disagrees with manifest`);
+        return { kind: entry.source.kind, bytes: await readAll(exact.body, exact.size), sha256: exact.sha256.slice("sha256:".length) };
+    }
+    async fetchDeltaContent(authorization, delta) {
+        if (delta.operation !== "upsert" || delta.source === null || delta.versionId === null)
+            throw new SnapshotClientError(`delta ${delta.deltaId} lacks immutable content metadata`);
+        const exact = await this.content.openCommittedContent(authorization, delta.deltaId);
+        if (exact.versionId !== delta.versionId)
+            throw new SnapshotClientError(`delta ${delta.deltaId} exact descriptor disagrees with the feed`);
+        return { kind: delta.source.kind, bytes: await readAll(exact.body, exact.size), sha256: exact.sha256.slice("sha256:".length) };
+    }
+    async acknowledgeReset(authorization, resetId, checksumValue, cursor) {
+        const { response, text } = await this.controlRequest(authorization, "POST", `/v2/sync/resets/${encodeURIComponent(opaque(resetId, "resetId"))}/ack`, { checksum: digest(checksumValue, "checksum"), cursor: opaque(cursor, "cursor") });
+        if (response.status !== 204)
+            throw new SnapshotClientError(`reset acknowledgement failed (${response.status}): ${text.slice(0, 300)}`);
+    }
+    async controlRequest(authorization, method, route, body) {
+        const leaseExpiry = Date.parse(authorization.lease.expiresAt);
+        if (!Number.isFinite(leaseExpiry) || leaseExpiry <= this.now()) {
+            throw new SnapshotClientError("lease expired before guarded I/O");
+        }
+        const response = await this.request(`${this.apiUrl}${route}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${nonEmpty(authorization.bearer, "bearer")}`,
+                Accept: "application/json",
+                "X-HQ-Sync-Contract": "2",
+                "X-HQ-Device-ID": nonEmpty(authorization.deviceId, "deviceId"),
+                "X-HQ-Cloud-Version": nonEmpty(authorization.capabilityVector.hqCloud, "hqCloud version"),
+                "X-HQ-Desktop-Version": nonEmpty(authorization.capabilityVector.hqDesktop, "hqDesktop version"),
+                "X-HQ-Sync-Lease": nonEmpty(authorization.lease.lease, "lease"),
+                ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+            },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        }, `control ${method}`);
+        return { response, text: await response.text() };
+    }
+    async request(input, init, label) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            return await this.fetchImpl(input, { ...init, signal: controller.signal });
+        }
+        catch (error) {
+            throw new SnapshotClientError(`${label} failed`, { cause: error });
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}
+//# sourceMappingURL=snapshot-client.js.map