@opendatalabs/personal-server-ts-core 0.0.1-canary.00328bf

package/dist/sync/workers/download.js

@@ -0,0 +1,731 @@
+import { DataFileEnvelopeSchema, decryptWithPassword, deriveScopeKey, } from "@opendatalabs/vana-sdk/browser";
+import { feedFromGatewayClient } from "../data-point-feed.js";
+import { deletionTimestamp, isEntryCoveredByTombstone, tombstoneVersion, } from "../scope-deletions.js";
+import { buildDataBlocksAsync } from "../../storage/blocks/build.js";
+import { classifySyncFailure, inferPayloadKind, } from "../issues.js";
+import { downloadRetryKey } from "../retry-memory.js";
+import { readStoredLineage } from "../../lineage/lineage.js";
+import { isPermanentRejection } from "../pdpp-import.js";
+/**
+ * Hydrate exact owner scopes without listing the registry or changing the
+ * incremental cursor. This is the cold-start fast path; downloadAll remains
+ * responsible for the complete registry reconciliation.
+ */
+export async function downloadScopes(deps, scopes, options = {}) {
+    const feed = deps.dataPointFeed ?? feedFromGatewayClient(deps.gateway);
+    const results = [];
+    for (const scope of scopes) {
+        const dataPoint = await feed.getDataPoint({
+            ownerAddress: deps.serverOwner,
+            scope,
+        });
+        if (!dataPoint) {
+            continue;
+        }
+        const deletedAt = deletionTimestamp(dataPoint);
+        if (deletedAt !== null) {
+            deps.scopeDeletions?.markDeleted(scope, {
+                deletedAt,
+                version: tombstoneVersion(dataPoint),
+            });
+            await reconcileDeletedDataPoint(deps, dataPoint, deletedAt);
+            continue;
+        }
+        deps.scopeDeletions?.markLive(scope);
+        const retryKey = downloadRetryKey(dataPoint);
+        const decision = options.retryMemory?.decide(retryKey) ?? "attempt";
+        if (decision !== "attempt") {
+            continue;
+        }
+        try {
+            const result = await downloadOne(deps, dataPoint);
+            options.retryMemory?.recordSuccess(retryKey);
+            if (result) {
+                results.push(result);
+            }
+        }
+        catch (err) {
+            const metadata = getSyncFailureMetadata(err);
+            const classified = classifySyncFailure({
+                error: err,
+                fileId: dataPoint.id,
+                syncRunId: "scope-hydration",
+                stage: metadata.stage,
+                scope: metadata.scope ?? dataPoint.scope,
+                payloadKind: metadata.payloadKind,
+                encryptedSizeBytes: metadata.encryptedSizeBytes,
+            });
+            options.retryMemory?.recordFailure(retryKey, classified.issue.retryable);
+            if (classified.issue.retryable) {
+                throw err;
+            }
+            deps.logger.warn({
+                dataPointId: dataPoint.id,
+                scope: classified.issue.scope,
+                stage: classified.issue.stage,
+                payloadKind: classified.issue.payloadKind,
+                encryptedSizeBytes: classified.issue.encryptedSizeBytes,
+                errorClass: classified.issue.errorClass,
+                message: classified.issue.message,
+            }, "Quarantined corrupt synced data point");
+        }
+    }
+    return results;
+}
+/**
+ * Download and process a single DPv2 data point from the storage backend:
+ * 1. Check dedup: skip if dataPointId already in local index
+ * 2. Reconstruct the blob URL from (scope, expectedVersion) — DataPointRecords
+ *    carry no URL, so we rebuild the version-keyed `{scope}/{version}` key the
+ *    upload worker wrote under and resolve it via storageAdapter.urlForKey
+ * 3. Download the OpenPGP encrypted binary from storage
+ * 4. Derive scope key from master key → hex-encode as OpenPGP password
+ *    (scope comes straight off the record — no schema lookup needed)
+ * 5. Decrypt with OpenPGP password-based decryption → plaintext JSON
+ * 6. Parse as DataFileEnvelope (validate)
+ * 7. Write to local filesystem + bounded block sidecars
+ * 8. Insert into local index (with dataPointId + version)
+ */
+export async function downloadOne(deps, record) {
+    const { storage, storageAdapter, masterKey, logger, diagnostics } = deps;
+    const ctx = { dataPointId: record.id, schemaId: null };
+    // 1. Check dedup: skip if dataPointId already in local index
+    const existing = storage.findByDataPointId(record.id);
+    if (existing) {
+        const repairResult = await repairMissingBlockSidecars(storage, logger, { dataPointId: record.id, schemaId: existing.schemaId }, existing, diagnostics);
+        if (repairResult === "missing-envelope") {
+            logger.warn({
+                dataPointId: record.id,
+                scope: existing.scope,
+                collectedAt: existing.collectedAt,
+            }, "Local index entry was missing its envelope; re-downloading data point");
+        }
+        else {
+            // Already indexed by a previous cycle. The legacy path is done, but the
+            // PDPP import may not be: it runs after indexing, so it can have failed,
+            // or PDPP may not have been mounted yet when this point first arrived.
+            // Because the local index is itself the dedup key, returning here
+            // without retrying is what strands such an envelope permanently — no
+            // later sync would ever look at it again.
+            await retryPdppImportFromLocal(deps, existing);
+            logger.debug({ dataPointId: record.id }, "Data point already in index, skipping");
+            return null;
+        }
+    }
+    // 2. Reconstruct the version-keyed storage URL.
+    const storageKey = `${record.scope}/${record.expectedVersion}`;
+    const url = storageAdapter.urlForKey(storageKey);
+    // 3. Download OpenPGP encrypted binary from storage backend. A download
+    // failure throws and blocks the cursor (correct: a transient error retries
+    // next cycle rather than risk a silent gap). Stamp the stage so the
+    // classifier can tell a deterministic 404 (quarantine, never retry) from a
+    // transient storage error — without it the failure infers stage "unknown"
+    // and every 404 is retried forever.
+    diagnostics?.onDownloadStart(record.id);
+    let encrypted;
+    try {
+        encrypted = await storageAdapter.download(url);
+    }
+    catch (err) {
+        const detail = err.message;
+        diagnostics?.onDownloadError(record.id, detail);
+        throw withSyncFailureMetadata(err, {
+            stage: "download",
+            scope: record.scope,
+        });
+    }
+    diagnostics?.onDownloadEnd(record.id, record.scope);
+    // 4. Derive scope key → hex-encode as OpenPGP password (scope off the record)
+    const scopeKey = deriveScopeKey(masterKey, record.scope);
+    const scopeKeyHex = uint8ToHex(scopeKey);
+    // 5. Decrypt with OpenPGP password-based decryption
+    diagnostics?.onDecryptStart(record.id, record.scope);
+    let plaintext;
+    try {
+        plaintext = await decryptWithPassword(encrypted, scopeKeyHex);
+    }
+    catch (err) {
+        const payloadKind = inferPayloadKind(encrypted);
+        const encryptedSizeBytes = encrypted.byteLength;
+        const detail = [
+            err.message,
+            `payloadKind=${payloadKind}`,
+            `encryptedSizeBytes=${encryptedSizeBytes}`,
+        ].join("; ");
+        diagnostics?.onDecryptError(record.id, record.scope, detail);
+        throw withSyncFailureMetadata(err, {
+            scope: record.scope,
+            payloadKind,
+            encryptedSizeBytes,
+        });
+    }
+    finally {
+        // Decrypt returns an independent plaintext buffer. Clear the encrypted
+        // payload immediately instead of retaining a second large record until
+        // the rest of indexing completes or the next garbage collection.
+        encrypted.fill(0);
+    }
+    // 6. Parse as DataFileEnvelope (validate)
+    let envelope;
+    try {
+        const raw = JSON.parse(new TextDecoder().decode(plaintext));
+        envelope = DataFileEnvelopeSchema.parse(raw);
+    }
+    catch (err) {
+        const detail = err.message;
+        diagnostics?.onDecryptError(record.id, record.scope, detail);
+        throw err;
+    }
+    ctx.schemaId = envelope.schemaId ?? null;
+    diagnostics?.onDecryptEnd(record.id, envelope.scope);
+    const existingByVersion = storage.findEntry({
+        scope: envelope.scope,
+        at: envelope.collectedAt,
+    });
+    if (existingByVersion !== undefined &&
+        existingByVersion.collectedAt === envelope.collectedAt) {
+        if (existingByVersion.dataPointId !== record.id) {
+            await storage.updateDataPointId(existingByVersion.path, record.id);
+        }
+        const repairResult = await repairMissingBlockSidecars(storage, logger, {
+            dataPointId: record.id,
+            schemaId: existingByVersion.schemaId ?? ctx.schemaId,
+        }, existingByVersion, diagnostics);
+        if (repairResult !== "missing-envelope") {
+            // Same version already stored locally. The envelope is decrypted and in
+            // hand, so offer it to the importer directly — no local re-read needed.
+            // Same stranding risk as the dataPointId dedup above.
+            importIntoPdpp(deps, envelope, record.id);
+            logger.debug({
+                dataPointId: record.id,
+                scope: envelope.scope,
+                collectedAt: envelope.collectedAt,
+            }, "Data version already exists locally, skipping");
+            return null;
+        }
+        logger.warn({
+            dataPointId: record.id,
+            scope: envelope.scope,
+            collectedAt: envelope.collectedAt,
+        }, "Local version entry was missing its envelope; rewriting downloaded file");
+    }
+    // 7. Write to local storage + bounded block sidecars
+    diagnostics?.onIndexStart(record.id, envelope.scope);
+    let relativePath;
+    let sizeBytes;
+    try {
+        ({ relativePath, sizeBytes } = await storage.writeEnvelope(envelope));
+        await writeBlockSidecars(storage, envelope, logger, ctx, relativePath, diagnostics);
+    }
+    catch (err) {
+        const detail = err.message;
+        diagnostics?.onIndexError(record.id, envelope.scope, detail);
+        throw err;
+    }
+    // 8. Insert into local index (with dataPointId + version)
+    try {
+        await storage.insertEntry({
+            fileId: null,
+            schemaId: ctx.schemaId,
+            path: relativePath,
+            scope: envelope.scope,
+            collectedAt: envelope.collectedAt,
+            sizeBytes,
+            version: Number(record.expectedVersion),
+            dataPointId: record.id,
+        });
+    }
+    catch (err) {
+        const detail = err.message;
+        diagnostics?.onIndexError(record.id, envelope.scope, detail);
+        throw err;
+    }
+    diagnostics?.onIndexEnd(record.id, envelope.scope);
+    logger.info({ dataPointId: record.id, scope: envelope.scope, path: relativePath }, "Downloaded and indexed data point");
+    importIntoPdpp(deps, envelope, record.id);
+    if (deps.onDataPointIndexed) {
+        try {
+            let lineageSources;
+            try {
+                lineageSources = readStoredLineage(envelope.data)?.sources;
+            }
+            catch {
+                // A malformed $lineage is the upload worker's problem; the hook
+                // still learns about the new version.
+            }
+            deps.onDataPointIndexed({
+                scope: envelope.scope,
+                dataPointId: record.id,
+                version: Number(record.expectedVersion),
+                collectedAt: envelope.collectedAt,
+                lineageSources,
+            });
+        }
+        catch (err) {
+            logger.warn({ scope: envelope.scope, error: err.message }, "onDataPointIndexed hook failed; data point already indexed");
+        }
+    }
+    return {
+        dataPointId: record.id,
+        scope: envelope.scope,
+        collectedAt: envelope.collectedAt,
+        path: relativePath,
+    };
+}
+/**
+ * Poll Gateway for the owner's data points since the stored cursor, download
+ * each, and advance the cursor only when the page fully succeeds.
+ */
+export async function downloadAll(deps, options = {}) {
+    const { gateway, cursor, serverOwner, logger } = deps;
+    const syncRunId = createSyncRunId();
+    const repairSummary = await repairLocalMissingBlockSidecars(deps);
+    // 1. Read cursor (opaque pagination cursor persisted across runs)
+    const lastCursor = options.fullReconcile || repairSummary.missingEnvelopeEntries > 0
+        ? null
+        : await cursor.read();
+    if (options.fullReconcile) {
+        logger.info("Running full registry reconciliation to repair any missing local scope records");
+    }
+    if (repairSummary.missingEnvelopeEntries > 0) {
+        logger.warn({ missingEnvelopeEntries: repairSummary.missingEnvelopeEntries }, "Resetting this sync listing to repair stale local index entries");
+    }
+    if (options.fullReconcile || repairSummary.missingEnvelopeEntries > 0) {
+        // An EXPLICIT listing restart (full reconcile, or the repair path above)
+        // exists to re-fetch — give transient failures a fresh attempt budget so
+        // it can; 404s stay dead. Note `lastCursor === null` alone is NOT a
+        // reset signal: single-page listings never advance the cursor, so null
+        // is their steady state and clearing on it would erase the backoff
+        // memory every cycle.
+        options.retryMemory?.onListingReset();
+    }
+    // 2. Poll gateway for the owner's data points, tombstones included: a
+    // deletion made on another replica must reach this one or its local copy
+    // would be re-uploaded and resurrect the point.
+    const feed = deps.dataPointFeed ?? feedFromGatewayClient(gateway);
+    const { dataPoints, cursor: nextCursor } = await feed.listDataPointsByOwner(serverOwner, lastCursor, { includeDeleted: true });
+    // Feed the read-side deletion memory before any per-record work so a
+    // tombstone is refused by reads even if its local reconcile below fails.
+    // Only a listing with no further pages proves the memory complete: a
+    // multi-page backlog leaves it "stale" and reads fall back to lookups. A
+    // listing from no cursor covered the whole registry (`full`), which is
+    // what re-validates remembered tombstones; an incremental pass does not.
+    if (deps.scopeDeletions) {
+        for (const dataPoint of dataPoints) {
+            const deletedAt = deletionTimestamp(dataPoint);
+            if (deletedAt !== null) {
+                deps.scopeDeletions.markDeleted(dataPoint.scope, {
+                    deletedAt,
+                    version: tombstoneVersion(dataPoint),
+                });
+            }
+            else {
+                deps.scopeDeletions.markLive(dataPoint.scope);
+            }
+        }
+        if (nextCursor === null) {
+            deps.scopeDeletions.noteFeedSynced(undefined, {
+                full: lastCursor === null,
+            });
+        }
+    }
+    const results = [];
+    let failed = false;
+    // 3. Process each data point record
+    for (const dataPoint of dataPoints) {
+        const deletedAt = deletionTimestamp(dataPoint);
+        if (deletedAt !== null) {
+            // Tombstone: never download; drop what the deletion covers locally.
+            // A failure here blocks the cursor so the tombstone is re-listed and
+            // the reconcile retried next cycle.
+            try {
+                await reconcileDeletedDataPoint(deps, dataPoint, deletedAt);
+            }
+            catch (err) {
+                logger.error({
+                    dataPointId: dataPoint.id,
+                    scope: dataPoint.scope,
+                    error: err.message,
+                }, "Failed to reconcile deleted data point locally");
+                failed = true;
+            }
+            continue;
+        }
+        const retryKey = downloadRetryKey(dataPoint);
+        const decision = options.retryMemory?.decide(retryKey) ?? "attempt";
+        if (decision === "give-up") {
+            // Non-retryable failure (e.g. blob 404) or exhausted transient
+            // retries — skip without blocking the cursor so one dead record
+            // can't wedge the rest of the listing. A new registered version
+            // (different retry key) starts fresh.
+            logger.debug({ dataPointId: dataPoint.id, scope: dataPoint.scope }, "Skipping data point after exhausted download retries");
+            continue;
+        }
+        if (decision === "backoff") {
+            // Waiting out the backoff window. Block the cursor so the record is
+            // still listed when the window expires.
+            failed = true;
+            continue;
+        }
+        try {
+            const result = await downloadOne(deps, dataPoint);
+            options.retryMemory?.recordSuccess(retryKey);
+            if (result) {
+                results.push(result);
+            }
+        }
+        catch (err) {
+            const metadata = getSyncFailureMetadata(err);
+            const classified = classifySyncFailure({
+                error: err,
+                fileId: dataPoint.id,
+                syncRunId,
+                stage: metadata.stage,
+                scope: metadata.scope ?? dataPoint.scope,
+                payloadKind: metadata.payloadKind,
+                encryptedSizeBytes: metadata.encryptedSizeBytes,
+            });
+            options.retryMemory?.recordFailure(retryKey, classified.issue.retryable);
+            if (!classified.issue.retryable) {
+                logger.warn({
+                    dataPointId: dataPoint.id,
+                    scope: classified.issue.scope,
+                    stage: classified.issue.stage,
+                    payloadKind: classified.issue.payloadKind,
+                    encryptedSizeBytes: classified.issue.encryptedSizeBytes,
+                    errorClass: classified.issue.errorClass,
+                    message: classified.issue.message,
+                }, "Quarantined corrupt synced data point");
+                continue;
+            }
+            logger.error({
+                dataPointId: dataPoint.id,
+                scope: dataPoint.scope,
+                error: err.message,
+            }, "Failed to download data point");
+            failed = true;
+        }
+    }
+    // 4. Advance cursor only when every record in the page was handled.
+    if (nextCursor !== null && !failed) {
+        await cursor.write(nextCursor);
+    }
+    else if (failed) {
+        logger.warn({ nextCursor }, "Download cursor not advanced because one or more data points failed");
+    }
+    return results;
+}
+/**
+ * Apply a gateway tombstone to the local index: remove every local version
+ * the tombstone covers (synced rows at or below its version, and unsynced
+ * rows ingested without knowledge of it), keep unsynced rows ingested on top
+ * of it (a legitimate re-add that the upload worker registers after the
+ * tombstone version). See `isEntryCoveredByTombstone`.
+ */
+export async function reconcileDeletedDataPoint(deps, record, deletedAt) {
+    const tombstone = { version: tombstoneVersion(record) };
+    const tombstoned = tombstone.version === null ? null : BigInt(tombstone.version);
+    // Unsynced covered entries above the tombstone version: the deleting
+    // replica's exact-key pass only enumerates registry versions, so any
+    // ciphertext this replica uploaded under a higher, never-registered key is
+    // ours to clean up.
+    const orphanKeys = [];
+    const { storage, logger } = deps;
+    const PAGE_SIZE = 500;
+    const stale = [];
+    let kept = 0;
+    for (let offset = 0;; offset += PAGE_SIZE) {
+        const entries = storage.listVersions(record.scope, {
+            limit: PAGE_SIZE,
+            offset,
+        });
+        for (const entry of entries) {
+            if (isEntryCoveredByTombstone(entry, tombstone)) {
+                stale.push({ scope: entry.scope, collectedAt: entry.collectedAt });
+                if (entry.dataPointId === null &&
+                    (tombstoned === null || BigInt(entry.version) > tombstoned)) {
+                    orphanKeys.push({
+                        scope: entry.scope,
+                        version: String(entry.version),
+                    });
+                }
+            }
+            else {
+                kept += 1;
+            }
+        }
+        if (entries.length < PAGE_SIZE)
+            break;
+    }
+    let removed = 0;
+    for (const version of stale) {
+        if (await storage.deleteVersion(version.scope, version.collectedAt)) {
+            removed += 1;
+        }
+    }
+    if (orphanKeys.length > 0 && deps.pendingBlobDeletions) {
+        await deps.pendingBlobDeletions.add(orphanKeys);
+    }
+    if (removed > 0 || kept > 0) {
+        logger.info({ dataPointId: record.id, scope: record.scope, deletedAt, removed, kept }, "Reconciled gateway deletion against local index");
+    }
+    return { scope: record.scope, deletedAt, removed, kept };
+}
+export async function repairLocalMissingBlockSidecars(deps) {
+    const { storage, logger, diagnostics } = deps;
+    if (!storage.writeBlockManifest || !storage.hasScopeBlocks) {
+        return { repaired: 0, missingEnvelopeEntries: 0 };
+    }
+    let repaired = 0;
+    let missingEnvelopeEntries = 0;
+    let offset = 0;
+    const limit = 100;
+    while (true) {
+        const page = storage.listScopes({ limit, offset });
+        let deletedEntryInPage = false;
+        for (const scopeSummary of page.scopes) {
+            const entry = storage.findEntry({
+                scope: scopeSummary.scope,
+                at: scopeSummary.latestCollectedAt,
+            });
+            if (!entry)
+                continue;
+            const repairResult = await repairMissingBlockSidecars(storage, logger, {
+                dataPointId: entry.dataPointId ?? entry.path,
+                schemaId: entry.schemaId,
+            }, entry, diagnostics);
+            if (repairResult === "repaired")
+                repaired += 1;
+            if (repairResult === "missing-envelope") {
+                missingEnvelopeEntries += 1;
+                deletedEntryInPage = true;
+            }
+        }
+        if (!deletedEntryInPage) {
+            offset += page.scopes.length;
+        }
+        if (offset >= page.total || page.scopes.length === 0)
+            break;
+    }
+    if (repaired > 0) {
+        logger.info({ repaired }, "Repaired missing bounded block sidecars for local indexed data");
+    }
+    if (missingEnvelopeEntries > 0) {
+        logger.warn({ missingEnvelopeEntries }, "Removed stale local index entries missing local envelopes");
+    }
+    return { repaired, missingEnvelopeEntries };
+}
+/**
+ * Offer a freshly indexed envelope to the PDPP importer.
+ *
+ * Deliberately total: every outcome is handled and none escapes. A rejection
+ * is a WARNING rather than an error because it means the producer sent
+ * something this deployment could not verify — actionable, but not a fault of
+ * this sync cycle, and not a reason to re-download a blob that arrived
+ * intact. `skipped` is the ordinary legacy case and stays silent.
+ */
+function importIntoPdpp(deps, envelope, dataPointId) {
+    if (!deps.pdppImporter)
+        return;
+    try {
+        const outcome = deps.pdppImporter.importEnvelope({
+            scope: envelope.scope,
+            collectedAt: envelope.collectedAt,
+            data: envelope.data,
+        });
+        if (outcome.status === "rejected") {
+            // Both are visible, but they mean different things and an operator
+            // needs to tell them apart: a permanent verdict is about the producer's
+            // bytes and will never change, while a transient one is about this
+            // deployment and clears on a later cycle.
+            const permanent = isPermanentRejection(outcome.rejection);
+            deps.logger.warn({
+                dataPointId,
+                scope: envelope.scope,
+                code: outcome.rejection.code,
+                message: outcome.rejection.message,
+                permanent,
+            }, permanent
+                ? "Synced data point was refused by the PDPP importer and will not be retried"
+                : "PDPP import unavailable for this data point; a later sync will retry it");
+        }
+    }
+    catch (err) {
+        // A throwing importer is infrastructure failing, not the envelope being
+        // wrong, so this is retryable by construction — and the retry path above
+        // is what makes that statement true rather than aspirational.
+        deps.logger.warn({ dataPointId, scope: envelope.scope, error: err.message }, "PDPP import threw; data point stays indexed and a later sync will retry it");
+    }
+}
+/**
+ * Re-offer an already-indexed data point to the PDPP importer, reading the
+ * envelope back from local storage.
+ *
+ * This exists because legacy indexing and PDPP import are two separate
+ * writes with no shared transaction. Anything that interrupts between them —
+ * a throwing importer, an unmounted PDPP, a store that is briefly unhealthy
+ * — leaves an envelope that is indexed but not imported, and the index entry
+ * then suppresses every future attempt.
+ *
+ * Reads the cached local envelope rather than re-downloading: the plaintext
+ * is already on disk, so re-fetching and re-decrypting the blob would burn
+ * network and CPU on every cycle for no new information. The importer's own
+ * idempotency (compare-before-write) is what keeps a repeated offer from
+ * producing a duplicate revision, so this cannot inflate `changes_since`.
+ *
+ * Best-effort throughout. The data point is durably stored and indexed
+ * already; a failure here must never fail the sync cycle or block its cursor.
+ */
+async function retryPdppImportFromLocal(deps, entry) {
+    if (!deps.pdppImporter)
+        return;
+    // Nothing a re-read could change: already imported, verified unchanged,
+    // permanently refused, or carrying no `$pdpp` at all. Without this gate the
+    // retry would re-read and re-verify every legacy data point on every cycle,
+    // forever, to reach the same answer.
+    if (!deps.pdppImporter.needsRetry(entry.scope, entry.collectedAt))
+        return;
+    let envelope;
+    try {
+        envelope = await deps.storage.readEnvelope(entry.scope, entry.collectedAt);
+    }
+    catch (err) {
+        // No local payload to retry from. The sidecar repair path above already
+        // handles a missing envelope by re-downloading, so this is not the place
+        // to fix it — just don't pretend an import was attempted.
+        deps.logger.debug({
+            scope: entry.scope,
+            collectedAt: entry.collectedAt,
+            error: err.message,
+        }, "Skipped PDPP import retry: no local envelope to read");
+        return;
+    }
+    importIntoPdpp(deps, envelope, `${entry.scope}@${entry.collectedAt}`);
+}
+function createSyncRunId() {
+    return typeof crypto !== "undefined" &&
+        typeof crypto.randomUUID === "function"
+        ? crypto.randomUUID()
+        : `download-${Date.now().toString(36)}`;
+}
+function uint8ToHex(bytes) {
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function withSyncFailureMetadata(error, metadata) {
+    if (error instanceof Error) {
+        Object.assign(error, { syncFailureMetadata: metadata });
+        return error;
+    }
+    return { error, syncFailureMetadata: metadata };
+}
+function getSyncFailureMetadata(error) {
+    if (typeof error !== "object" || error === null)
+        return {};
+    const metadata = error
+        .syncFailureMetadata;
+    if (typeof metadata !== "object" || metadata === null)
+        return {};
+    return metadata;
+}
+async function writeBlockSidecars(storage, envelope, logger, ctx, relativePath, diagnostics) {
+    if (!storage.writeBlockManifest)
+        return;
+    diagnostics?.onManifestBuildStart(ctx.dataPointId, envelope.scope);
+    try {
+        const built = await buildDataBlocksAsync({
+            scope: envelope.scope,
+            collectedAt: envelope.collectedAt,
+            schemaId: ctx.schemaId ?? undefined,
+            content: envelope,
+        });
+        await storage.writeBlockManifest(envelope.scope, envelope.collectedAt, built.manifest, built.blocks);
+        diagnostics?.onManifestBuildEnd(ctx.dataPointId, envelope.scope);
+    }
+    catch (error) {
+        const classified = classifySyncFailure({
+            error,
+            fileId: ctx.dataPointId,
+            syncRunId: "download",
+            stage: "block_build",
+            schemaId: ctx.schemaId ?? undefined,
+            scope: envelope.scope,
+        });
+        diagnostics?.onManifestBuildError(ctx.dataPointId, envelope.scope, classified.issue.message);
+        logger.warn({
+            dataPointId: ctx.dataPointId,
+            scope: envelope.scope,
+            collectedAt: envelope.collectedAt,
+            path: relativePath,
+            stage: classified.issue.stage,
+            errorClass: classified.issue.errorClass,
+            message: classified.issue.message,
+        }, "Bounded block sidecar write failed after raw envelope write");
+    }
+}
+async function repairMissingBlockSidecars(storage, logger, ctx, entry, diagnostics) {
+    if (!storage.writeBlockManifest || !storage.hasScopeBlocks) {
+        return "not-repaired";
+    }
+    let hasBlocks = false;
+    try {
+        hasBlocks = await storage.hasScopeBlocks(entry.scope, entry.collectedAt);
+    }
+    catch (error) {
+        logger.warn({
+            dataPointId: ctx.dataPointId,
+            scope: entry.scope,
+            collectedAt: entry.collectedAt,
+            error: error.message,
+        }, "Bounded block sidecar repair skipped after readiness check failed");
+        return "not-repaired";
+    }
+    if (hasBlocks)
+        return "already-ready";
+    diagnostics?.onRepair(entry.scope, "indexed entry missing block manifest; rebuilding from local envelope");
+    let envelope;
+    try {
+        envelope = await storage.readEnvelope(entry.scope, entry.collectedAt);
+    }
+    catch (error) {
+        logger.warn({
+            dataPointId: ctx.dataPointId,
+            scope: entry.scope,
+            collectedAt: entry.collectedAt,
+            error: error.message,
+        }, "Bounded block sidecar repair skipped because local envelope is unavailable");
+        // Remove the stale index entry whose payload is gone. We can only target
+        // it by gateway fileId; DataPoint-only entries (fileId === null) are left
+        // in place (no path-keyed delete on the port) and self-heal on re-download.
+        if (entry.fileId) {
+            diagnostics?.onRepair(entry.scope, "index exists without local payload; removing stale local index entry");
+            const removed = await storage.deleteByFileId(entry.fileId);
+            logger.warn({
+                dataPointId: ctx.dataPointId,
+                scope: entry.scope,
+                collectedAt: entry.collectedAt,
+                removed,
+            }, "Removed stale local index entry missing local envelope");
+            return removed ? "missing-envelope" : "not-repaired";
+        }
+        return "not-repaired";
+    }
+    await writeBlockSidecars(storage, envelope, logger, {
+        dataPointId: ctx.dataPointId,
+        schemaId: entry.schemaId ?? ctx.schemaId,
+    }, entry.path, diagnostics);
+    try {
+        return (await storage.hasScopeBlocks(entry.scope, entry.collectedAt))
+            ? "repaired"
+            : "not-repaired";
+    }
+    catch (error) {
+        logger.warn({
+            dataPointId: ctx.dataPointId,
+            scope: entry.scope,
+            collectedAt: entry.collectedAt,
+            error: error.message,
+        }, "Bounded block sidecar repair completed but readiness could not be verified");
+        return "not-repaired";
+    }
+}
+//# sourceMappingURL=download.js.map