@opendatalabs/personal-server-ts-core 0.0.1-canary.01ca694 → 0.0.1-canary.052d47e

package/dist/api/index.js

@@ -1,10 +1,34 @@
-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, } 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 { WRITER_ATTRIBUTION_KEY, } from "../write/attribution.js";
+import { extractLineageField, LINEAGE_KEY, 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) {
     const headers = new Headers(init?.headers);
     headers.set("Content-Type", "application/json");
     return new Response(JSON.stringify(body), { ...init, headers });
 }
+// X402 spec convention: payment responses are JSON, base64-encoded into a
+// single header value. Returns undefined on encode failure so callers can
+// just omit the header rather than fail the read. Uses btoa + TextEncoder
+// to stay portable across Node and web runtimes.
+function encodePaymentResponseHeader(body) {
+    try {
+        const json = JSON.stringify(body ?? null);
+        const bytes = new TextEncoder().encode(json);
+        let binary = "";
+        for (const b of bytes)
+            binary += String.fromCharCode(b);
+        return btoa(binary);
+    }
+    catch {
+        return undefined;
+    }
+}
 function contractResponse(result) {
     return jsonResponse(result.body, { status: result.status });
 }
@@ -59,97 +83,277 @@ function stripBasePath(pathname, basePath) {
 function decodePathPart(value) {
     return decodeURIComponent(value ?? "");
 }
-function selectedGrantId(request, url) {
+/**
+ * The grant the caller nominates for a read: `?grantId=` or the
+ * `x-ps-grant-id` header, the SDK's shape on every read route. Exported so
+ * the derivatives status route authorizes with exactly the same inputs as
+ * a data read — a credential that reads /v1/data/<scope> must not be
+ * refused by /v1/derivatives/status.
+ */
+export function selectedGrantId(request, url) {
     return (url.searchParams.get("grantId") ??
         request.headers.get("x-ps-grant-id") ??
         undefined);
 }
-function collectedAt(now) {
-    return now()
-        .toISOString()
-        .replace(/\.\d{3}Z$/, "Z");
-}
-async function resolveSchema(deps, scope) {
-    if (!deps.schemaResolver) {
+/**
+ * Run the X402 dispatch for one read:
+ *
+ *   X-PAYMENT absent / malformed / fails local validation
+ *     → challenge: fresh 402 with current fee + accessRecord
+ *   X-PAYMENT valid, forward to gateway succeeds
+ *     → ok: caller proceeds to read the data
+ *   X-PAYMENT valid, gateway returns 4xx/5xx
+ *     → gateway-error: relay the gateway's body verbatim so the builder
+ *       can dispatch (insufficient balance vs. replay vs. race etc.)
+ *
+ * The gateway POST goes through `fetch` directly (not `gateway.payForOperation`)
+ * because the SDK client throws plain Errors and loses the body — which is
+ * exactly what we need to distinguish gateway 402 (insufficient balance) from
+ * 409 (replay) from 400 (amount mismatch).
+ */
+export async function handleX402Cycle(input) {
+    const { deps, gateway, gatewayConfig, gatewayUrl, builder, scope } = input;
+    // The gateway lowercases opId before EIP-712 recovery — we must do the
+    // same in the challenge so the builder signs over the canonical form.
+    const opIdLower = input.grantId.toLowerCase();
+    // Live grant — re-fetched every cycle. The fee.totalDue is a snapshot
+    // (SDK comment: "clients shouldn't cache"); paymentStatus may have just
+    // flipped if a concurrent payer paid the registration fee.
+    const grant = await gateway.getGrant(opIdLower);
+    if (!grant) {
         return {
-            ok: false,
-            response: errorResponse(500, "SERVER_NOT_CONFIGURED", "Gateway is not configured"),
+            kind: "challenge",
+            body: {
+                x402Version: 1,
+                error: "PAYMENT_REQUIRED",
+                accepts: [],
+            },
         };
     }
-    try {
-        const schema = await deps.schemaResolver.getSchemaForScope(scope);
-        if (!schema) {
-            return {
-                ok: false,
-                response: jsonResponse({
-                    error: "NO_SCHEMA",
-                    message: `No schema registered for scope: ${scope}`,
-                }, { status: 400 }),
-            };
+    // Bind the accessRecord to the entry being served, if it exists and has
+    // been registered with DPv2 yet.
+    const entryRow = deps.storage.findEntry({
+        scope,
+        fileId: input.fileIdParam,
+        at: input.atParam,
+    });
+    const entryForChallenge = entryRow
+        ? {
+            dataPointId: entryRow.dataPointId,
+            scope,
+            version: entryRow.version,
         }
-        return {
-            ok: true,
-            schemaUrl: schema.definitionUrl,
-            schemaId: schema.id,
-        };
+        : undefined;
+    // `grant` is narrowed to non-null above, but that narrowing is not carried
+    // into this closure (vana-sdk 3.14.0 made getGrant return `... | null`), so
+    // capture the guaranteed-present value via a typed alias for the closure.
+    const liveGrant = grant;
+    async function buildFreshChallenge() {
+        return buildChallenge({
+            builder,
+            grantId: opIdLower,
+            grant: liveGrant,
+            network: deps.network ?? `vana:${gatewayConfig.chainId}`,
+            gatewayConfig,
+            serverSigner: deps.serverSigner,
+            serverOwner: deps.serverOwner,
+            entry: entryForChallenge,
+            generateNonce: deps.generatePaymentNonce,
+            generateRecordIdFn: deps.generateRecordId,
+            now: deps.now,
+        });
+    }
+    const headerValue = input.request.headers.get("x-payment");
+    const parsed = parsePaymentHeader(headerValue);
+    if (!parsed) {
+        return { kind: "challenge", body: await buildFreshChallenge() };
+    }
+    if (!deps.serverAddress) {
+        // Can't validate accessRecord recovery without our own address; fail
+        // closed by reissuing a challenge.
+        deps.logger?.error?.({ scope, grantId: opIdLower }, "X402 enabled but serverAddress is not configured — cannot verify accessRecord");
+        return { kind: "challenge", body: await buildFreshChallenge() };
+    }
+    const verify = await verifyPayment({
+        builder,
+        grantId: opIdLower,
+        grant,
+        entry: entryForChallenge,
+        serverAddress: deps.serverAddress,
+        gatewayConfig,
+        serverOwner: deps.serverOwner,
+        payment: parsed,
+    });
+    if (!verify.ok) {
+        deps.logger?.info?.({ scope, grantId: opIdLower, reason: verify.reason }, "X402 payment verification failed; reissuing challenge");
+        return { kind: "challenge", body: await buildFreshChallenge() };
+    }
+    // Forward to gateway via direct fetch (preserves error body). The SDK
+    // client wraps the same endpoint but throws away the structured response
+    // on non-2xx, which is exactly the info we need to distinguish gateway
+    // 402 (insufficient balance) from 409 (replay / race) from 400 (mismatch).
+    const doFetch = deps.paymentFetch ?? fetch;
+    const body = {
+        payerAddress: verify.payment.payload.message.payerAddress,
+        opType: verify.payment.payload.message.opType,
+        opId: verify.payment.payload.message.opId,
+        asset: verify.payment.payload.message.asset,
+        amount: verify.payment.payload.message.amount,
+        paymentNonce: verify.payment.payload.message.paymentNonce,
+    };
+    if (verify.payment.payload.accessRecord) {
+        body["accessRecord"] = verify.payment.payload.accessRecord;
+    }
+    let gatewayRes;
+    try {
+        gatewayRes = await doFetch(`${gatewayUrl.replace(/\/+$/, "")}/v1/escrow/pay`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Web3Signed ${verify.payment.payload.signature}`,
+            },
+            body: JSON.stringify(body),
+        });
     }
     catch (err) {
-        deps.logger?.error?.({ err, scope }, "Gateway schema lookup failed");
-        return {
-            ok: false,
-            response: jsonResponse({
-                error: "GATEWAY_ERROR",
-                message: "Failed to look up schema for scope",
-            }, { status: 502 }),
-        };
+        deps.logger?.error?.({
+            scope,
+            grantId: opIdLower,
+            error: err.message,
+        }, "X402 gateway forward threw; reissuing challenge");
+        return { kind: "challenge", body: await buildFreshChallenge() };
+    }
+    if (gatewayRes.ok) {
+        // Preserve the gateway's structured success body so the request
+        // handler can echo it back via the X-PAYMENT-RESPONSE header (canonical
+        // X402 convention). Empty/malformed body → propagate as null; the
+        // header still gets set so builders can tell payment succeeded.
+        let payResponseBody = null;
+        try {
+            payResponseBody = await gatewayRes.json();
+        }
+        catch {
+            // Body unreadable but status was 2xx — treat as success with no payload.
+        }
+        return { kind: "ok", payResponse: payResponseBody };
     }
+    // Read the gateway's structured error body if there is one.
+    let errorBody;
+    try {
+        errorBody = await gatewayRes.json();
+    }
+    catch {
+        errorBody = { error: gatewayRes.statusText };
+    }
+    // 409 (replay or race) and 400 (amount mismatch / shape error) are
+    // recoverable with a fresh challenge — the builder re-signs with the
+    // new state and retries. 402 (insufficient balance) is relayed verbatim
+    // because the builder needs to fix their escrow, not their signature.
+    // 5xx is treated like 402-relayed since the personal server can't
+    // distinguish "transient" from "permanent" without more info.
+    if (gatewayRes.status === 409 || gatewayRes.status === 400) {
+        deps.logger?.info?.({ scope, grantId: opIdLower, status: gatewayRes.status, errorBody }, "Gateway rejected X-PAYMENT; reissuing X402 challenge");
+        return { kind: "challenge", body: await buildFreshChallenge() };
+    }
+    return { kind: "gateway-error", status: gatewayRes.status, body: errorBody };
 }
-/** True when the request body should be treated as a JSON object (the legacy
- * path). Missing/blank Content-Type is treated as JSON for backward compat. */
-function isJsonContentType(request) {
-    const ct = request.headers.get("content-type");
-    if (!ct)
-        return true;
-    return ct.toLowerCase().includes("application/json");
-}
-function binaryMimeType(request) {
-    const ct = request.headers.get("content-type");
-    if (!ct)
-        return "application/octet-stream";
-    // Strip any "; charset=..." / boundary parameters.
-    return ct.split(";")[0].trim() || "application/octet-stream";
-}
-/** Extract a filename from X-Filename or a Content-Disposition header. */
-function binaryFilename(request) {
-    const explicit = request.headers.get("x-filename");
-    if (explicit)
-        return explicit;
-    const disposition = request.headers.get("content-disposition");
-    const match = disposition?.match(/filename\*?=(?:UTF-8'')?"?([^";]+)"?/i);
-    return match ? decodeURIComponent(match[1]) : undefined;
+function collectedAt(now) {
+    return now()
+        .toISOString()
+        .replace(/\.\d{3}Z$/, "Z");
 }
 /**
- * Resolve a schema for a binary scope, registering a permissive "no-schema"
- * schema when none exists. Unlike the JSON path this never hard-fails on a
- * missing schema: if there is no registrar, ingestion proceeds with no schemaId
- * (the entry is registered against the gateway's resolved schema later).
+ * 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.
  */
-async function resolveBinarySchema(deps, scope) {
-    if (deps.schemaResolver) {
-        const schema = await deps.schemaResolver.getSchemaForScope(scope);
-        if (schema) {
-            return { schemaId: schema.id, schemaUrl: schema.definitionUrl };
-        }
+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;
     }
-    if (deps.schemaRegistrar) {
-        const registered = await deps.schemaRegistrar.registerNoSchema(scope);
-        deps.logger?.info?.({ scope, schemaId: registered.schemaId }, "Registered no-schema schema for binary scope");
-        return {
-            schemaId: registered.schemaId,
-            schemaUrl: registered.definitionUrl,
-        };
+    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 notifyDataWritten(deps, event) {
+    if (!deps.onDataWritten)
+        return;
+    try {
+        deps.onDataWritten(event);
+    }
+    catch (err) {
+        deps.logger?.warn?.({
+            scope: event.scope,
+            error: err instanceof Error ? err.message : String(err),
+        }, "onDataWritten hook failed; record already stored");
     }
-    return {};
 }
 function notifyNewData(syncManager) {
     if (!syncManager)
@@ -160,6 +364,125 @@ function notifyNewData(syncManager) {
     }
     void syncManager.trigger().catch(() => undefined);
 }
+function shouldReportReadFulfillment(grantId) {
+    return (grantId !== "unknown" && grantId !== "owner" && grantId !== "policy-bypass");
+}
+function warnReadFulfillmentReporterFailed(deps, event, err) {
+    deps.logger?.warn?.({
+        builder: event.builder,
+        error: err instanceof Error ? err.message : String(err),
+        grantId: event.grantId,
+        logId: event.logId,
+        scope: event.scope,
+    }, "Read fulfillment reporter failed");
+}
+export function reportPersonalServerReadFulfillment(deps, event) {
+    if (!deps.readFulfillmentReporter ||
+        !shouldReportReadFulfillment(event.grantId)) {
+        return;
+    }
+    try {
+        void Promise.resolve(deps.readFulfillmentReporter.report(event)).catch((err) => warnReadFulfillmentReporterFailed(deps, event, err));
+    }
+    catch (err) {
+        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 };
+}
+/**
+ * True when a read auth result entitles the caller to the owner's view of a
+ * record — the same convention as resolveLineageGrantView: no result, or the
+ * "owner" / "policy-bypass" sentinels. Everything else is a grantee.
+ */
+export function isOwnerView(authResult) {
+    return (authResult === undefined ||
+        authResult.grantId === "owner" ||
+        authResult.grantId === "policy-bypass");
+}
+/**
+ * The envelope view a grantee read is entitled to. The server-stamped
+ * `$writtenBy` (writing builder's address, grantId, signature) and
+ * `$lineage` (the owner's source data-point ids, dictionary-attackable back
+ * to scopes since dataPointId = keccak(owner, scope)) never leave the server
+ * on a grantee read: the owner reads them from storage, and grantees get the
+ * graph only through the grant-redacted lineage endpoint. When `$lineage` is
+ * present, the caller-supplied lineage field it mirrors (top-level `lineage`
+ * on a JSON record, `metadata.lineage` on a binary one) carries the same ids
+ * and is dropped with it; without the stamp such a field is ordinary user
+ * data and stays. Redaction is at serve time only — the stored envelope, its
+ * dataHash commitment, and the owner's view are unchanged.
+ */
+export function redactEnvelopeForGrantee(envelope) {
+    const { [WRITER_ATTRIBUTION_KEY]: attribution, [LINEAGE_KEY]: storedLineage, ...rest } = envelope.data;
+    if (attribution === undefined && storedLineage === undefined) {
+        return envelope;
+    }
+    let data = rest;
+    if (storedLineage !== undefined) {
+        if (isBinaryEnvelope(envelope)) {
+            const metadata = data["metadata"];
+            if (metadata !== null &&
+                typeof metadata === "object" &&
+                !Array.isArray(metadata)) {
+                const { lineage: _consumed, ...metadataRest } = metadata;
+                if (Object.keys(metadataRest).length === 0) {
+                    // The lineage was the whole metadata object; leaving `{}` behind
+                    // would still disclose that a metadata object existed.
+                    const { metadata: _emptied, ...dataRest } = data;
+                    data = dataRest;
+                }
+                else {
+                    data = { ...data, metadata: metadataRest };
+                }
+            }
+        }
+        else {
+            const { lineage: _consumed, ...dataRest } = data;
+            data = dataRest;
+        }
+    }
+    return { ...envelope, data };
+}
 export async function handlePersonalServerDataRequest(request, deps, options = {}) {
     return withApiErrors(async () => {
         const url = new URL(request.url);
@@ -173,6 +496,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);
         }
@@ -181,16 +505,107 @@ 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,
+                });
+            }
+            // A lineage view discloses the derivation graph, so a served view is
+            // logged like a data read (refusals above return without an entry).
+            await deps.accessLogWriter.write({
+                logId: deps.createLogId?.() ?? crypto.randomUUID(),
+                grantId: authResult?.grantId ?? "owner",
+                builder: authResult?.builder ?? "unknown",
+                action: "lineage",
+                scope: scopeResult.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",
+            });
+            return jsonResponse({ data: result.data, proof: result.proof });
+        }
         if (parts.length !== 1)
             return notFound();
         const scopeParam = decodePathPart(parts[0]);
@@ -203,42 +618,180 @@ export async function handlePersonalServerDataRequest(request, deps, options = {
                 fileId: url.searchParams.get("fileId") ?? undefined,
                 at: url.searchParams.get("at") ?? undefined,
             });
+            // Holds the base64-encoded gateway payForOperation response body when
+            // X402 succeeds — emitted on the final read response as X-PAYMENT-RESPONSE.
+            let paymentResponseHeader;
             const grantId = selectedGrantId(request, url);
             const authResult = await deps.auth.authorizeBuilderRead({
                 request,
                 scope: scopeResult.scope,
                 grantId,
                 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.
+            //
+            // The grantId we pay against is the one verifyDataReadPolicy resolved
+            // from the Web3Signed payload (authoritative source) — not the URL /
+            // header hint, which may be absent when the payload carries it.
+            const isOwnerSignal = authResult?.grantId === "owner" ||
+                authResult?.grantId === "policy-bypass";
+            const builder = authResult?.builder;
+            const resolvedGrantId = !isOwnerSignal && authResult?.grantId ? authResult.grantId : undefined;
+            const willCharge = Boolean(deps.paymentEnabled &&
+                !isOwnerSignal &&
+                typeof builder === "string" &&
+                builder.startsWith("0x") &&
+                resolvedGrantId &&
+                deps.gateway &&
+                deps.gatewayConfig &&
+                deps.gatewayUrl);
+            // Diagnostic: makes it explicit why a read is/isn't charged. x402 has
+            // many "served free" branches (owner read, payment disabled, missing
+            // gateway deps); this surfaces the deciding inputs.
+            //
+            // Routing: when a logger is wired (the Node server always provides one),
+            // log the full detail through it at debug level so the operator's level
+            // controls + redaction apply and access metadata (scope/grantId/builder)
+            // doesn't unconditionally hit stdout. The browser PS-Lite runtime wires
+            // no logger; there we fall back to console but log ONLY the non-identifying
+            // decision booleans — never scope/grantId/builder.
+            if (deps.logger?.debug) {
+                deps.logger.debug({
+                    scope: scopeResult.scope,
+                    grantId: authResult?.grantId,
+                    isOwnerSignal,
+                    builder,
+                    resolvedGrantId,
+                    paymentEnabled: Boolean(deps.paymentEnabled),
+                    hasGateway: Boolean(deps.gateway),
+                    hasGatewayConfig: Boolean(deps.gatewayConfig),
+                    hasGatewayUrl: Boolean(deps.gatewayUrl),
+                    willCharge,
+                }, "[x402-gate] read");
+            }
+            else {
+                console.info("[x402-gate] read", {
+                    isOwnerSignal,
+                    paymentEnabled: Boolean(deps.paymentEnabled),
+                    hasGateway: Boolean(deps.gateway),
+                    hasGatewayConfig: Boolean(deps.gatewayConfig),
+                    hasGatewayUrl: Boolean(deps.gatewayUrl),
+                    willCharge,
+                });
+            }
+            // Keep the full condition inline (not `if (willCharge)`) so TS narrows
+            // deps.gateway/gatewayConfig/gatewayUrl to non-undefined in the block.
+            if (deps.paymentEnabled &&
+                !isOwnerSignal &&
+                typeof builder === "string" &&
+                builder.startsWith("0x") &&
+                resolvedGrantId &&
+                deps.gateway &&
+                deps.gatewayConfig &&
+                deps.gatewayUrl) {
+                const x402Result = await handleX402Cycle({
+                    deps,
+                    request,
+                    scope: scopeResult.scope,
+                    fileIdParam: url.searchParams.get("fileId") ?? undefined,
+                    atParam: url.searchParams.get("at") ?? undefined,
+                    grantId: resolvedGrantId,
+                    builder: builder,
+                    gateway: deps.gateway,
+                    gatewayConfig: deps.gatewayConfig,
+                    gatewayUrl: deps.gatewayUrl,
+                });
+                if (x402Result.kind === "challenge") {
+                    return jsonResponse(x402Result.body, { status: 402 });
+                }
+                if (x402Result.kind === "gateway-error") {
+                    // Relay the gateway's structured body verbatim so the builder can
+                    // dispatch on it (insufficient balance vs. replay vs. race etc.).
+                    return jsonResponse(x402Result.body, { status: x402Result.status });
+                }
+                // x402Result.kind === "ok" — payment accepted, proceed to read.
+                // The gateway's success body is forwarded back to the builder via
+                // X-PAYMENT-RESPONSE (canonical X402 convention) so callers can see
+                // breakdown / paidAt / paymentNonce without a second gateway round-trip.
+                paymentResponseHeader = encodePaymentResponseHeader(x402Result.payResponse);
+            }
             const result = await readDataContract({
                 storage: deps.storage,
                 scopeParam: scopeResult.scope,
                 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 servedEnvelope = isOwnerView(authResult)
+                ? result.envelope
+                : redactEnvelopeForGrantee(result.envelope);
+            const logId = deps.createLogId?.() ?? crypto.randomUUID();
+            const timestamp = (deps.now ?? (() => new Date()))().toISOString();
+            const ipAddress = request.headers.get("x-forwarded-for") ??
+                request.headers.get("x-real-ip") ??
+                "unknown";
+            const userAgent = request.headers.get("user-agent") ?? "unknown";
+            const loggedGrantId = authResult?.grantId ?? grantId ?? "unknown";
+            const loggedBuilder = authResult?.builder ?? "unknown";
             await deps.accessLogWriter.write({
-                logId: deps.createLogId?.() ?? crypto.randomUUID(),
-                grantId: authResult?.grantId ?? grantId ?? "unknown",
-                builder: authResult?.builder ?? "unknown",
+                logId,
+                grantId: loggedGrantId,
+                builder: loggedBuilder,
                 action: "read",
                 scope: scopeResult.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",
+                timestamp,
+                ipAddress,
+                userAgent,
             });
+            const reportReadFulfillment = () => {
+                if (!authResult?.grantId || !authResult.builder)
+                    return;
+                reportPersonalServerReadFulfillment(deps, {
+                    builder: authResult.builder,
+                    fileId: url.searchParams.get("fileId") ??
+                        selectedEntry?.fileId ??
+                        undefined,
+                    grantId: authResult.grantId,
+                    ipAddress,
+                    logId,
+                    scope: scopeResult.scope,
+                    servedAt: timestamp,
+                    userAgent,
+                });
+            };
+            const headers = {};
+            if (paymentResponseHeader) {
+                headers["X-PAYMENT-RESPONSE"] = paymentResponseHeader;
+            }
+            const wantsRawContent = url.searchParams.get("content") === "raw";
             // `?content=raw` streams the decoded bytes of a binary envelope with its
-            // original media type, so a builder can download the file directly.
-            if (url.searchParams.get("content") === "raw" &&
-                isBinaryEnvelope(result.envelope)) {
-                const decoded = decodeBinaryEnvelope(result.envelope);
-                const headers = {
-                    "Content-Type": decoded.mimeType,
-                    "Content-Length": String(decoded.bytes.length),
-                };
+            // original media type, so a builder can download the file directly. The
+            // X-PAYMENT-RESPONSE header (if any) rides along on the raw response too.
+            if (wantsRawContent) {
+                if (!isBinaryEnvelope(servedEnvelope)) {
+                    return jsonResponse({
+                        error: "NOT_BINARY_SCOPE",
+                        message: `Scope "${scopeResult.scope}" does not expose raw binary content.`,
+                    }, { status: 400, headers });
+                }
+                const decoded = decodeBinaryEnvelope(servedEnvelope);
+                headers["Content-Type"] = decoded.mimeType;
+                headers["Content-Length"] = String(decoded.bytes.length);
                 if (decoded.filename) {
                     headers["Content-Disposition"] =
                         `attachment; filename="${decoded.filename}"`;
@@ -246,98 +799,248 @@ export async function handlePersonalServerDataRequest(request, deps, options = {
                 if (decoded.metadata !== undefined) {
                     headers["X-Vana-Metadata"] = stringifyMetadataHeader(decoded.metadata);
                 }
-                return new Response(decoded.bytes, {
+                const response = new Response(decoded.bytes, {
                     status: 200,
                     headers,
                 });
+                return response;
             }
-            return jsonResponse(result.envelope);
+            const response = jsonResponse(servedEnvelope, { headers });
+            reportReadFulfillment();
+            return response;
         }
         if (request.method === "POST") {
-            await deps.auth.authorizeOwner(request);
-            const scopeResult = parseDataScopeContract(scopeParam);
-            if (!scopeResult.ok)
-                return contractErrorResponse(scopeResult);
-            const collectedAtValue = collectedAt(deps.now ?? (() => new Date()));
-            const status = deps.syncManager ? "syncing" : "stored";
-            // Binary / unstructured data (e.g. a PDF): the body is raw bytes and the
-            // scope may not have a registered schema — auto-register a no-schema one.
-            if (!isJsonContentType(request)) {
-                const { schemaId, schemaUrl } = await resolveBinarySchema(deps, scopeResult.scope);
-                const bytes = new Uint8Array(await request.arrayBuffer());
-                const result = await ingestBinaryDataContract({
+            // Delegated writes: an auth port that supports write sessions handles
+            // both paths in authorizeWrite (builder session token -> write policy +
+            // attribution; anything else -> owner path). Ports without it keep
+            // today's owner-only gate.
+            let writeAuth;
+            if (deps.auth.authorizeWrite) {
+                writeAuth =
+                    (await deps.auth.authorizeWrite({ request, scope: scopeParam })) ??
+                        undefined;
+            }
+            else {
+                await deps.auth.authorizeOwner(request);
+            }
+            // A write that fails before commit hands the proof back (replay guard)
+            // so the builder's retry with the same still-valid proof is accepted;
+            // after commit the proof stays consumed (a retry would be a duplicate).
+            let committed = false;
+            const failWrite = async (response) => {
+                await writeAuth?.releaseProof?.();
+                return response;
+            };
+            try {
+                const scopeResult = parseDataScopeContract(scopeParam);
+                if (!scopeResult.ok)
+                    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
+                // must not turn a successful write into a 500 (the builder would retry
+                // and store a duplicate). The ingest log line above still names the
+                // builder; the failure itself is logged for the owner.
+                const logBuilderWrite = async () => {
+                    if (!writeAuth)
+                        return;
+                    try {
+                        await deps.accessLogWriter.write({
+                            logId: deps.createLogId?.() ?? crypto.randomUUID(),
+                            grantId: writeAuth.grantId,
+                            builder: writeAuth.builder,
+                            action: "write",
+                            scope: scopeResult.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: scopeResult.scope,
+                            builder: writeAuth.builder,
+                            grantId: writeAuth.grantId,
+                            error: err instanceof Error ? err.message : String(err),
+                        }, "Builder write access-log entry failed; record already stored");
+                    }
+                };
+                // Binary / unstructured data (e.g. a PDF): the body is raw bytes. DPv2
+                // data points are scope-addressed and carry no schemaId, so unstructured
+                // data needs no schema at all — we ingest it schemaless. (Structured JSON
+                // 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,
+                        collectedAt: collectedAtValue,
+                        status,
+                        attribution: writeAuth?.attribution,
+                        lineage,
+                        afterTombstoneVersion,
+                    });
+                    if (!result.ok)
+                        return failWrite(contractErrorResponse(result));
+                    committed = true;
+                    deps.logger?.info?.({
+                        scope: scopeResult.scope,
+                        collectedAt: collectedAtValue,
+                        path: result.writeResult.relativePath,
+                        mimeType: binaryMimeType(request),
+                        sizeBytes: bytes.length,
+                        ...(writeAuth ? { builder: writeAuth.builder } : {}),
+                    }, "Binary data file ingested");
+                    await logBuilderWrite();
+                    notifyNewData(deps.syncManager);
+                    notifyDataWritten(deps, {
+                        scope: scopeResult.scope,
+                        collectedAt: collectedAtValue,
+                        lineageSources: lineage?.sources,
+                    });
+                    return jsonResponse(result.response, { status: 201 });
+                }
+                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({
                     storage: deps.storage,
                     scopeParam: scopeResult.scope,
-                    bytes,
-                    mimeType: binaryMimeType(request),
-                    filename: binaryFilename(request),
-                    metadata: parseMetadataHeader(request.headers.get("x-vana-metadata")),
+                    body: parsed.body,
                     collectedAt: collectedAtValue,
                     status,
-                    schemaUrl,
-                    schemaId,
+                    attribution: writeAuth?.attribution,
+                    lineage,
+                    afterTombstoneVersion,
                 });
                 if (!result.ok)
-                    return contractErrorResponse(result);
+                    return failWrite(contractErrorResponse(result));
+                committed = true;
                 deps.logger?.info?.({
                     scope: scopeResult.scope,
                     collectedAt: collectedAtValue,
                     path: result.writeResult.relativePath,
-                    mimeType: binaryMimeType(request),
-                    sizeBytes: bytes.length,
-                }, "Binary data file ingested");
+                    ...(writeAuth ? { builder: writeAuth.builder } : {}),
+                }, "Data file ingested");
+                await logBuilderWrite();
                 notifyNewData(deps.syncManager);
+                notifyDataWritten(deps, {
+                    scope: scopeResult.scope,
+                    collectedAt: collectedAtValue,
+                    lineageSources: lineage?.sources,
+                });
                 return jsonResponse(result.response, { status: 201 });
             }
-            const parsed = await parseJsonObjectBody(request, "Request body must be valid JSON");
-            if (!parsed.ok)
-                return contractResponse(parsed.result);
-            const schema = await resolveSchema(deps, scopeResult.scope);
-            if (!schema.ok)
-                return schema.response;
-            const result = await ingestDataContract({
-                storage: deps.storage,
-                scopeParam: scopeResult.scope,
-                body: parsed.body,
-                collectedAt: collectedAtValue,
-                status,
-                schemaUrl: schema.schemaUrl,
-                schemaId: schema.schemaId,
-            });
-            if (!result.ok)
-                return contractErrorResponse(result);
-            deps.logger?.info?.({
-                scope: scopeResult.scope,
-                collectedAt: collectedAtValue,
-                path: result.writeResult.relativePath,
-            }, "Data file ingested");
-            notifyNewData(deps.syncManager);
-            return jsonResponse(result.response, { status: 201 });
+            catch (err) {
+                // An envelope that reached storage before indexing failed is
+                // persisted (a re-index surfaces it): keep the proof consumed so a
+                // retry cannot store it twice; the builder needs a fresh proof.
+                if (err instanceof IngestPersistedError) {
+                    deps.logger?.error?.({
+                        scope: scopeParam,
+                        path: err.relativePath,
+                        error: err.cause instanceof Error
+                            ? err.cause.message
+                            : String(err.cause),
+                    }, "Envelope written but indexing failed; record persisted unindexed");
+                }
+                else if (!committed) {
+                    await writeAuth?.releaseProof?.();
+                }
+                throw err;
+            }
         }
         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();
     });
@@ -407,12 +1110,13 @@ export async function handlePersonalServerGrantsRequest(request, deps, options =
                 const parsed = await parseJsonObjectBody(request);
                 if (!parsed.ok)
                     return contractResponse(parsed.result);
+                // Canary createGrant doesn't need a clock — grantVersion defaults
+                // to "1" and callers re-registering pass a strictly higher value.
                 return contractResponse(await createGrantContract({
                     gateway: deps.gateway,
                     serverOwner: deps.serverOwner,
                     serverSigner: deps.serverSigner,
                     body: parsed.body,
-                    now: () => deps.now?.().getTime() ?? Date.now(),
                 }));
             }
             return methodNotAllowed();