@opendatalabs/personal-server-ts-core 1.6.0 → 1.8.0

package/dist/api/index.d.ts

@@ -3,10 +3,14 @@ import type { AccessLogReader } from "../logging/access-reader.js";
 import { type DataStoragePort, type RuntimeAvailabilityPort } from "../ports/index.js";
 import type { DataReadPolicyPorts } from "../policy/index.js";
 import type { SyncManager } from "../sync/index.js";
+import { type ScopeDeletionTracker } from "../sync/scope-deletions.js";
+import type { IndexEntry } from "../storage/index/types.js";
+import { type DeleteScopeResult } from "../sync/workers/delete.js";
 import { type OAuthDeviceSessionLookup, type OAuthTokenStorePort } from "../contracts/index.js";
 import type { DataPortabilityGatewayConfig, GatewayClient } from "@opendatalabs/vana-sdk/browser";
 import type { ServerSigner } from "../signing/index.js";
 import type { WriterAttribution } from "../write/attribution.js";
+import type { LineageGatewayPort } from "../lineage/gateway.js";
 import { type X402Challenge } from "../payment/index.js";
 export interface PersonalServerReadAuthInput {
     request: Request;
@@ -83,8 +87,12 @@ export interface PersonalServerApiLogger {
 export interface PersonalServerIngestSyncManager {
     trigger(): Promise<void>;
     notifyNewData?(): void;
-    /** Propagate a scope deletion to R2 + the gateway before the local delete. */
-    deleteScopeRemote?(scope: string): Promise<void>;
+    /**
+     * Durable scope deletion (gateway tombstone -> storage blobs -> local).
+     * When absent the DELETE route deletes the local copy only and reports
+     * `durable: false`.
+     */
+    deleteScope?(scope: string): Promise<DeleteScopeResult>;
 }
 export interface PersonalServerDataApiDeps {
     storage: DataStoragePort;
@@ -93,6 +101,15 @@ export interface PersonalServerDataApiDeps {
     syncManager?: PersonalServerIngestSyncManager | null;
     runtimeAvailability?: RuntimeAvailabilityPort;
     readFulfillmentReporter?: PersonalServerReadFulfillmentReporter;
+    /**
+     * Read-side memory of gateway tombstones (see sync/scope-deletions.ts for
+     * the consistency window). Every read consults it before serving or
+     * charging: a scope the gateway reports deleted answers 410 DATA_DELETED
+     * whether or not a stale local copy still exists, and a local miss on a
+     * deleted scope answers 410 instead of 404 so SDK readers can tell
+     * "deleted" from "never had it". Without it reads are local-only.
+     */
+    scopeDeletions?: ScopeDeletionTracker;
     /**
      * Required when payment is on. Powers two things on GET /v1/data/:scope:
      *   - the X402 challenge generation (fee lookup, accessRecord binding)
@@ -155,6 +172,13 @@ export interface PersonalServerDataApiDeps {
     now?: () => Date;
     createLogId?: () => string;
     logger?: PersonalServerApiLogger;
+    /**
+     * Gateway access for derivative data (docs/derivative-data-api.md): source
+     * lookups for lineage validation on write and the signed lineage read
+     * behind GET /v1/data/:scope/lineage. Absent = writes with lineage can
+     * only cite local scopes and the lineage read answers 503.
+     */
+    lineageGateway?: LineageGatewayPort;
 }
 export interface PersonalServerAccessLogsApiDeps {
     auth: Pick<PersonalServerApiAuthPort, "authorizeOwner">;
@@ -229,6 +253,33 @@ export type X402CycleResult = {
  * 409 (replay) from 400 (amount mismatch).
  */
 export declare function handleX402Cycle(input: X402CycleInput): Promise<X402CycleResult>;
+/**
+ * The deletion that applies to a read of `scope`, or null when the read may
+ * be served. `entry` is the local version the read would serve (undefined
+ * on a local miss).
+ *
+ * - A local copy is refused when the gateway holds a tombstone that covers
+ *   it (see `isEntryCoveredByTombstone`: registry versions and the ingest
+ *   marker, never clocks). A local re-add on top of the tombstone is served.
+ * - A local miss asks the tracker to consult the gateway (bounded by its
+ *   per-scope verdict cache and failure back-off): the local index cannot
+ *   tell "deleted long ago" from "never had it".
+ * Gateway unreachability never fails the read: the tracker answers from its
+ * last known state, which is the documented offline behaviour.
+ */
+export declare function resolveReadDeletion(deps: Pick<PersonalServerDataApiDeps, "scopeDeletions" | "serverOwner">, scope: string, entry: ReadDeletionEntry | null | undefined): Promise<{
+    scope: string;
+    dataPointId: string | null;
+    deletedAt: string;
+} | null>;
+/**
+ * Throw 410 DATA_DELETED when `resolveReadDeletion` says the read must not be
+ * served. Call it before any payment step: a builder must never be charged
+ * for a scope the owner deleted.
+ */
+export declare function assertScopeNotDeleted(deps: Pick<PersonalServerDataApiDeps, "scopeDeletions" | "serverOwner">, scope: string, entry: ReadDeletionEntry | null | undefined): Promise<void>;
+/** The index fields the deletion gate needs from the entry a read would serve. */
+export type ReadDeletionEntry = Pick<IndexEntry, "version" | "dataPointId" | "afterTombstoneVersion">;
 export declare function reportPersonalServerReadFulfillment(deps: PersonalServerDataApiDeps, event: PersonalServerReadFulfillment): void;
 export declare function handlePersonalServerDataRequest(request: Request, deps: PersonalServerDataApiDeps, options?: PersonalServerApiDispatchOptions): Promise<Response>;
 export declare function handlePersonalServerAccessLogsRequest(request: Request, deps: PersonalServerAccessLogsApiDeps, options?: PersonalServerApiDispatchOptions): Promise<Response>;

package/dist/api/index.d.ts.map

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

package/dist/api/index.js

@@ -1,5 +1,9 @@
-import { ProtocolError } from "../errors/catalog.js";
-import { deleteDataScopeContract, ingestDataContract, ingestBinaryDataContract, listAccessLogsContract, listDataScopesContract, listDataVersionsContract, parseDataScopeContract, parseJsonObjectBody, readDataContract, syncFileContract, triggerSyncContract, getSyncStatusContract, configReadErrorContract, configWriteErrorContract, createGrantContract, listGrantsContract, oauthTokenContract, revokeGrantContract, validateServerConfigContract, verifyGrantContract, decodeBinaryEnvelope, isBinaryEnvelope, parseMetadataHeader, stringifyMetadataHeader, IngestPersistedError, } from "../contracts/index.js";
+import { DataDeletedError, DeleteTombstoneFailedError, GrantRequiredError, InvalidCascadeError, LineageCascadeUnavailableError, LineageGatewayError, LineageUnavailableError, ProtocolError, ServerNotConfiguredError, } from "../errors/catalog.js";
+import { computeDataPointId } from "../sync/data-point-id.js";
+import { isEntryCoveredByTombstone, } from "../sync/scope-deletions.js";
+import { deleteScope as deleteScopeLocally, } from "../sync/workers/delete.js";
+import { ingestDataContract, ingestBinaryDataContract, listAccessLogsContract, listDataScopesContract, listDataVersionsContract, parseDataScopeContract, parseJsonObjectBody, readDataContract, syncFileContract, triggerSyncContract, getSyncStatusContract, configReadErrorContract, configWriteErrorContract, createGrantContract, listGrantsContract, oauthTokenContract, revokeGrantContract, validateServerConfigContract, verifyGrantContract, decodeBinaryEnvelope, isBinaryEnvelope, parseMetadataHeader, stringifyMetadataHeader, IngestPersistedError, } from "../contracts/index.js";
+import { extractLineageField, prepareLineage, } from "../lineage/lineage.js";
 import { binaryFilename, binaryMimeType, isJsonContentType, } from "../contracts/binary.js";
 import { buildChallenge, parsePaymentHeader, verifyPayment, } from "../payment/index.js";
 function jsonResponse(body, init) {
@@ -250,6 +254,86 @@ function collectedAt(now) {
         .toISOString()
         .replace(/\.\d{3}Z$/, "Z");
 }
+/**
+ * The deletion that applies to a read of `scope`, or null when the read may
+ * be served. `entry` is the local version the read would serve (undefined
+ * on a local miss).
+ *
+ * - A local copy is refused when the gateway holds a tombstone that covers
+ *   it (see `isEntryCoveredByTombstone`: registry versions and the ingest
+ *   marker, never clocks). A local re-add on top of the tombstone is served.
+ * - A local miss asks the tracker to consult the gateway (bounded by its
+ *   per-scope verdict cache and failure back-off): the local index cannot
+ *   tell "deleted long ago" from "never had it".
+ * Gateway unreachability never fails the read: the tracker answers from its
+ * last known state, which is the documented offline behaviour.
+ */
+export async function resolveReadDeletion(deps, scope, entry) {
+    if (!deps.scopeDeletions)
+        return null;
+    const verdict = await deps.scopeDeletions.resolve(scope, {
+        consultGateway: entry ? "if-stale" : "always",
+    });
+    if (!verdict.deleted)
+        return null;
+    if (entry && !isEntryCoveredByTombstone(entry, verdict)) {
+        return null;
+    }
+    return {
+        scope,
+        dataPointId: deps.serverOwner
+            ? computeDataPointId(deps.serverOwner, scope)
+            : null,
+        deletedAt: verdict.deletedAt,
+    };
+}
+/**
+ * Throw 410 DATA_DELETED when `resolveReadDeletion` says the read must not be
+ * served. Call it before any payment step: a builder must never be charged
+ * for a scope the owner deleted.
+ */
+export async function assertScopeNotDeleted(deps, scope, entry) {
+    const deletion = await resolveReadDeletion(deps, scope, entry);
+    if (deletion)
+        throw new DataDeletedError(deletion);
+}
+/**
+ * Discovery filter for the scope and version listings: an entry a read would
+ * refuse with 410 is not listed either. Undefined (no filtering) when no
+ * deletion tracker is wired.
+ */
+function discoveryVisibility(deps) {
+    if (!deps.scopeDeletions)
+        return undefined;
+    return async (scope, entry) => (await resolveReadDeletion(deps, scope, entry)) === null;
+}
+/**
+ * The causal marker a fresh ingest carries: the tombstone version this
+ * replica currently knows for the scope, if any, so the new entry is a
+ * deliberate re-add that survives that deletion (and only that one). Uses
+ * the same verdict path as reads, so it costs a gateway lookup only when the
+ * tracker's view is stale. An unknown or unsafe version leaves the marker
+ * null: the entry is then covered, never resurrected on a guess.
+ */
+async function ingestTombstoneMarker(deps, scope) {
+    if (!deps.scopeDeletions)
+        return null;
+    const verdict = await deps.scopeDeletions.resolve(scope);
+    if (!verdict.deleted || verdict.version === null)
+        return null;
+    const version = Number(verdict.version);
+    return Number.isSafeInteger(version) ? version : null;
+}
+// The delete worker wants a full Logger; the API logger is all-optional.
+function apiLoggerAsLogger(logger) {
+    const noop = () => undefined;
+    return {
+        debug: (payload, message) => (logger?.debug ?? noop)(payload, message ?? ""),
+        info: (payload, message) => (logger?.info ?? noop)(payload, message ?? ""),
+        warn: (payload, message) => (logger?.warn ?? noop)(payload, message ?? ""),
+        error: (payload, message) => (logger?.error ?? noop)(payload, message ?? ""),
+    };
+}
 function notifyNewData(syncManager) {
     if (!syncManager)
         return;
@@ -283,6 +367,47 @@ export function reportPersonalServerReadFulfillment(deps, event) {
         warnReadFulfillmentReporterFailed(deps, event, err);
     }
 }
+/**
+ * Validate a write's caller-supplied `lineage` (JSON body top level, or the
+ * binary metadata object) into the `$lineage` record to stamp. `undefined`
+ * (or null) means a root record. Throws ProtocolErrors; the write handler
+ * lets them propagate before anything is stored.
+ */
+async function prepareWriteLineage(deps, scope, field) {
+    if (field === undefined || field === null)
+        return undefined;
+    return prepareLineage({
+        scope,
+        field,
+        serverOwner: deps.serverOwner,
+        storage: deps.storage,
+        gateway: deps.lineageGateway,
+        now: deps.now ?? (() => new Date()),
+    });
+}
+/**
+ * The lineage view a read auth result entitles the caller to. The auth port
+ * answers an owner read with no result or with the "owner" / "policy-bypass"
+ * sentinels (see api-auth): those get the full view. A builder read carries
+ * the grant the read policy resolved, and that grant names the view. A
+ * builder result with no resolved grant (or an "unknown" one) proves
+ * nothing and is refused: a missing grantId must never widen to the full
+ * view.
+ */
+function resolveLineageGrantView(authResult) {
+    if (authResult === undefined ||
+        authResult.grantId === "owner" ||
+        authResult.grantId === "policy-bypass") {
+        return { grantId: undefined };
+    }
+    const grantId = authResult.grantId;
+    if (typeof grantId !== "string" || grantId === "" || grantId === "unknown") {
+        throw new GrantRequiredError({
+            reason: "a lineage read by a builder needs a resolved grant",
+        });
+    }
+    return { grantId };
+}
 export async function handlePersonalServerDataRequest(request, deps, options = {}) {
     return withApiErrors(async () => {
         const url = new URL(request.url);
@@ -296,6 +421,7 @@ export async function handlePersonalServerDataRequest(request, deps, options = {
                 scopePrefix: url.searchParams.get("scopePrefix") ?? undefined,
                 limit: normalizeLimit(url.searchParams.get("limit"), 20),
                 offset: normalizeLimit(url.searchParams.get("offset"), 0),
+                isVisible: discoveryVisibility(deps),
             });
             return jsonResponse(result.response);
         }
@@ -304,16 +430,93 @@ export async function handlePersonalServerDataRequest(request, deps, options = {
             if (request.method !== "GET")
                 return methodNotAllowed();
             await deps.auth.authorizeBuilderList(request);
-            const result = listDataVersionsContract({
+            const result = await listDataVersionsContract({
                 storage: deps.storage,
                 scopeParam: decodePathPart(parts[0]),
                 limit: normalizeLimit(url.searchParams.get("limit"), 20),
                 offset: normalizeLimit(url.searchParams.get("offset"), 0),
+                isVisible: discoveryVisibility(deps),
             });
             if (!result.ok)
                 return contractErrorResponse(result);
+            if (result.response.total === 0) {
+                // Nothing visible: answer 410 rather than an empty list when that is
+                // because the scope is tombstoned, exactly as a read would.
+                await assertScopeNotDeleted(deps, result.scope, undefined);
+            }
             return jsonResponse(result.response);
         }
+        if ((parts.length === 2 || parts.length === 3) && parts[1] === "lineage") {
+            if (request.method !== "GET")
+                return methodNotAllowed();
+            const scopeResult = parseDataScopeContract(decodePathPart(parts[0]));
+            if (!scopeResult.ok)
+                return contractErrorResponse(scopeResult);
+            // The version is a PATH segment (/v1/data/:scope/lineage/:version), so
+            // it is inside the signed request uri: a builder's signature for one
+            // version cannot be replayed to read another. The grant view is the
+            // signed grantId claim the read auth already honours. Query
+            // parameters would be unsigned inputs to the view and are refused.
+            if (url.searchParams.has("version")) {
+                return errorResponse(400, "INVALID_VERSION", "version is a path segment (/v1/data/:scope/lineage/:version), not a query parameter");
+            }
+            if (url.search.length > 0) {
+                return errorResponse(400, "INVALID_QUERY", "lineage reads take no query parameters; the version is a path segment and the grant view is the signed grantId claim");
+            }
+            const version = parts.length === 3 ? decodePathPart(parts[2]) : undefined;
+            if (version !== undefined && !/^[1-9]\d*$/.test(version)) {
+                return errorResponse(400, "INVALID_VERSION", "version must be a positive decimal integer");
+            }
+            // Same gate as a read of the scope: the owner, or a builder whose grant
+            // covers it. The gateway then attests the view that grant sees, so a
+            // builder only learns the scopes of nodes its grant covers.
+            const authResult = await deps.auth.authorizeBuilderRead({
+                request,
+                scope: scopeResult.scope,
+                grantId: selectedGrantId(request, url),
+            });
+            if (!deps.serverOwner) {
+                throw new ServerNotConfiguredError({
+                    reason: "serverOwner is required to resolve the data point id",
+                });
+            }
+            if (!deps.lineageGateway)
+                throw new LineageUnavailableError();
+            const { grantId } = resolveLineageGrantView(authResult);
+            let result;
+            try {
+                result = await deps.lineageGateway.getLineage({
+                    dataPointId: computeDataPointId(deps.serverOwner, scopeResult.scope),
+                    version,
+                    grantId,
+                });
+            }
+            catch (err) {
+                // Transport failures (DNS, refused, timeout) are gateway errors to
+                // the caller, not internal ones: same 502 as a gateway error body.
+                if (err instanceof ProtocolError)
+                    throw err;
+                throw new LineageGatewayError({
+                    status: 0,
+                    body: { error: err instanceof Error ? err.message : String(err) },
+                });
+            }
+            if (!result.ok) {
+                if (result.status === 404) {
+                    return errorResponse(404, "NOT_FOUND", version
+                        ? `Scope "${scopeResult.scope}" has no registered version ${version}`
+                        : `Scope "${scopeResult.scope}" is not registered at the gateway`);
+                }
+                if (result.status === 403) {
+                    throw new ProtocolError(403, "LINEAGE_FORBIDDEN", "The gateway refused the lineage view for this grant", { gateway: result.body });
+                }
+                throw new LineageGatewayError({
+                    status: result.status,
+                    body: result.body,
+                });
+            }
+            return jsonResponse({ data: result.data, proof: result.proof });
+        }
         if (parts.length !== 1)
             return notFound();
         const scopeParam = decodePathPart(parts[0]);
@@ -337,6 +540,10 @@ export async function handlePersonalServerDataRequest(request, deps, options = {
                 fileId: url.searchParams.get("fileId") ?? selectedEntry?.fileId ?? undefined,
                 at: url.searchParams.get("at") ?? undefined,
             });
+            // Deletion gate, after auth (so unauthenticated callers learn nothing)
+            // and before payment (so nobody is charged for deleted data). Covers
+            // both a stale local copy of a tombstoned scope and a local miss.
+            await assertScopeNotDeleted(deps, scopeResult.scope, selectedEntry);
             // X402 payment dance for builder reads. Owner-exempt reads (the
             // grantId sentinels "owner" / "policy-bypass") skip payment entirely
             // since there's no payable op to attach the payment to.
@@ -432,8 +639,15 @@ export async function handlePersonalServerDataRequest(request, deps, options = {
                 fileId: url.searchParams.get("fileId") ?? undefined,
                 at: url.searchParams.get("at") ?? undefined,
             });
-            if (!result.ok)
+            if (!result.ok) {
+                if (result.status === 404) {
+                    // The entry selected above can vanish before the read (a sync
+                    // reconcile applying a tombstone concurrently); answer 410, not
+                    // 404, when that is why.
+                    await assertScopeNotDeleted(deps, scopeResult.scope, undefined);
+                }
                 return contractErrorResponse(result);
+            }
             const logId = deps.createLogId?.() ?? crypto.randomUUID();
             const timestamp = (deps.now ?? (() => new Date()))().toISOString();
             const ipAddress = request.headers.get("x-forwarded-for") ??
@@ -531,6 +745,7 @@ export async function handlePersonalServerDataRequest(request, deps, options = {
                     return failWrite(contractErrorResponse(scopeResult));
                 const collectedAtValue = collectedAt(deps.now ?? (() => new Date()));
                 const status = deps.syncManager ? "syncing" : "stored";
+                const afterTombstoneVersion = await ingestTombstoneMarker(deps, scopeResult.scope);
                 // Builder writes land in the same access log as builder reads, so the
                 // owner sees who wrote what under which grant.
                 // Best-effort: it runs AFTER the record is committed, so a log failure
@@ -569,16 +784,22 @@ export async function handlePersonalServerDataRequest(request, deps, options = {
                 // below still resolves a schema for validation/metadata.)
                 if (!isJsonContentType(request)) {
                     const bytes = new Uint8Array(await request.arrayBuffer());
+                    const metadata = parseMetadataHeader(request.headers.get("x-vana-metadata"));
+                    // A binary derivative names its sources inside the metadata
+                    // object; the validated mirror lands at the top of the record.
+                    const lineage = await prepareWriteLineage(deps, scopeResult.scope, extractLineageField(metadata));
                     const result = await ingestBinaryDataContract({
                         storage: deps.storage,
                         scopeParam: scopeResult.scope,
                         bytes,
                         mimeType: binaryMimeType(request),
                         filename: binaryFilename(request),
-                        metadata: parseMetadataHeader(request.headers.get("x-vana-metadata")),
+                        metadata,
                         collectedAt: collectedAtValue,
                         status,
                         attribution: writeAuth?.attribution,
+                        lineage,
+                        afterTombstoneVersion,
                     });
                     if (!result.ok)
                         return failWrite(contractErrorResponse(result));
@@ -598,6 +819,9 @@ export async function handlePersonalServerDataRequest(request, deps, options = {
                 const parsed = await parseJsonObjectBody(request, "Request body must be valid JSON");
                 if (!parsed.ok)
                     return failWrite(contractResponse(parsed.result));
+                // Derivative writes: validate the caller's `lineage` before anything
+                // is stored (a failure here throws, releasing the builder's proof).
+                const lineage = await prepareWriteLineage(deps, scopeResult.scope, extractLineageField(parsed.body));
                 // DPv2 is scope-addressed and the gateway records no schemas, so JSON
                 // ingest is schemaless too — no lookup, no schemaId/$schema stamped.
                 const result = await ingestDataContract({
@@ -607,6 +831,8 @@ export async function handlePersonalServerDataRequest(request, deps, options = {
                     collectedAt: collectedAtValue,
                     status,
                     attribution: writeAuth?.attribution,
+                    lineage,
+                    afterTombstoneVersion,
                 });
                 if (!result.ok)
                     return failWrite(contractErrorResponse(result));
@@ -642,28 +868,77 @@ export async function handlePersonalServerDataRequest(request, deps, options = {
         }
         if (request.method === "DELETE") {
             await deps.auth.authorizeOwner(request);
-            // Propagate the deletion to the authoritative stores (R2 blobs + gateway records) BEFORE the
-            // local delete — it reads the local index to find what to remove. Best-effort: a remote
-            // failure must not block the owner's local delete (and sync would otherwise resurrect it; the
-            // download-worker reconciliation is the backstop). Parse the scope first so an invalid scope
-            // still 400s without a wasted remote call.
+            const cascade = url.searchParams.get("cascade");
+            if (cascade !== null && cascade !== "lineage") {
+                throw new InvalidCascadeError({ cascade });
+            }
+            // Parse the scope first so an invalid scope still 400s without a
+            // wasted remote call.
             const parsed = parseDataScopeContract(scopeParam);
-            if (parsed.ok && deps.syncManager?.deleteScopeRemote) {
-                try {
-                    await deps.syncManager.deleteScopeRemote(parsed.scope);
-                }
-                catch (err) {
-                    deps.logger?.info?.({ scope: scopeParam, error: err.message }, "Remote scope deletion failed; proceeding with local delete");
-                }
+            if (!parsed.ok)
+                return contractErrorResponse(parsed);
+            if (cascade === "lineage") {
+                // Specified (docs/derivative-data-api.md, "Delete") but not
+                // implemented here. The durable per-scope delete below is what a
+                // cascade node needs; the missing part is the lineage walk itself
+                // (owner view of the gateway graph, deepest derivatives first,
+                // truncation and cross-owner handling, all-or-nothing before the
+                // first tombstone). Until that lands the only honest answer is 501.
+                throw new LineageCascadeUnavailableError({ scope: parsed.scope });
             }
-            const result = await deleteDataScopeContract({
-                storage: deps.storage,
-                scopeParam,
-            });
-            if (!result.ok)
-                return contractErrorResponse(result);
-            deps.logger?.info?.({ scope: scopeParam, deletedCount: result.deletedCount }, "Scope deleted");
-            return new Response(null, { status: 204 });
+            // Durable order: gateway tombstone -> storage blobs -> local copy. The
+            // sync manager owns the remote ports; without one (sync disabled or
+            // no owner key material) only the local copy goes and the result says
+            // so (`durable: false`) rather than pretending.
+            const result = deps.syncManager?.deleteScope
+                ? await deps.syncManager.deleteScope(parsed.scope)
+                : await deleteScopeLocally({
+                    storage: deps.storage,
+                    serverOwner: deps.serverOwner,
+                    deleteData: null,
+                    logger: apiLoggerAsLogger(deps.logger),
+                }, parsed.scope);
+            if (result.steps.gateway.status === "failed") {
+                // Nothing was deleted: the local copy is kept on purpose so sync
+                // cannot resurrect a half-deleted scope. Surface it as an upstream
+                // failure with the per-step result attached.
+                throw new DeleteTombstoneFailedError({
+                    scope: parsed.scope,
+                    result,
+                });
+            }
+            // Audit entry, best-effort: the deletion above is irreversible and
+            // already done, so a failed log write must not turn it into an error
+            // response that invites a misleading retry. The failure is logged.
+            try {
+                await deps.accessLogWriter.write({
+                    logId: deps.createLogId?.() ?? crypto.randomUUID(),
+                    grantId: "owner",
+                    builder: deps.serverOwner ?? "owner",
+                    action: "delete",
+                    scope: parsed.scope,
+                    timestamp: (deps.now ?? (() => new Date()))().toISOString(),
+                    ipAddress: request.headers.get("x-forwarded-for") ??
+                        request.headers.get("x-real-ip") ??
+                        "unknown",
+                    userAgent: request.headers.get("user-agent") ?? "unknown",
+                });
+            }
+            catch (err) {
+                deps.logger?.warn?.({
+                    scope: parsed.scope,
+                    error: err instanceof Error ? err.message : String(err),
+                }, "Delete access-log entry failed; scope already deleted");
+            }
+            deps.logger?.info?.({
+                scope: parsed.scope,
+                durable: result.durable,
+                gateway: result.steps.gateway.status,
+                storage: result.steps.storage.status,
+                local: result.steps.local.status,
+                deletedCount: result.steps.local.deletedCount,
+            }, "Scope deleted");
+            return jsonResponse(result, { status: 200 });
         }
         return methodNotAllowed();
     });