@opendatalabs/personal-server-ts-server 1.34.1 → 1.35.0

package/dist/routes/pdpp-records.js

@@ -1,27 +1,18 @@
+import { grantIsCandidate } from "@opendatalabs/personal-server-ts-core/pdpp";
+import { parseRecordQuery } from "./pdpp-record-query.js";
 import { Hono } from "hono";
 import { randomUUID } from "node:crypto";
 import { isRfc3339DateTime, PdppBindingError, } from "../storage/pdpp-records-sqlite-store.js";
 import { PdppError } from "@opendatalabs/personal-server-ts-core/errors/pdpp";
 import { PDPP_VERSION } from "@opendatalabs/personal-server-ts-core/pdpp-version";
-import { CursorExpiredError, decodeCursor, encodeCursor, InvalidCursorError, InvalidCursorSyntaxError, recordKeyWithinGrantResources, mapInactiveToError, recordWithinGrantTimeConstraint, resolveReadScope, summarizeIngest, } from "@opendatalabs/personal-server-ts-core/storage/pdpp-records";
+import { PdppAuthorizationUnavailableError } from "@opendatalabs/personal-server-ts-core/ports/pdpp-auth";
+import { REPLICA_SOURCE_MAX_BLOB_BYTES, REPLICA_SOURCE_MAX_RECORD_JSON_BYTES, } from "@opendatalabs/personal-server-ts-core/replication/limits";
+import { CursorExpiredError, InvalidCursorError, InvalidCursorSyntaxError, recordKeyWithinGrantResources, mapInactiveToError, recordWithinGrantTimeConstraint, resolveReadScope, summarizeIngest, } from "@opendatalabs/personal-server-ts-core/storage/pdpp-records";
 import { createRecordDataValidator } from "../pdpp/record-schema.js";
 import { StreamCompletionError, } from "../storage/pdpp-stream-completion.js";
-const DEFAULT_LIMIT = 25;
-const MAX_LIMIT = 100;
-export const MAX_BLOB_UPLOAD_BYTES = 512 * 1024 * 1024;
-function rebindListCursor(template, order, last) {
-    const bound = decodeCursor(template);
-    if (bound.kind !== "list")
-        throw new InvalidCursorError();
-    return encodeCursor({
-        ...bound,
-        order,
-        sortValue: last.emittedAt,
-        recordKey: last.recordKey,
-    });
-}
+export const MAX_BLOB_UPLOAD_BYTES = REPLICA_SOURCE_MAX_BLOB_BYTES;
 /** 512 MiB — max body size for PDPP record ingest and replace routes. */
-export const MAX_INGEST_BODY_BYTES = 512 * 1024 * 1024;
+export const MAX_INGEST_BODY_BYTES = REPLICA_SOURCE_MAX_RECORD_JSON_BYTES;
 /** 64 KiB of UTF-8 — max body size for the completion metadata route. */
 export const MAX_COMPLETION_BODY_BYTES = 64 * 1024;
 class CompletionBodyTooLarge extends Error {
@@ -235,6 +226,9 @@ function sendError(c, err, reqId) {
         "Request-Id": reqId,
         "PDPP-Version": PDPP_VERSION,
     };
+    if (err instanceof PdppAuthorizationUnavailableError) {
+        headers["Retry-After"] = String(err.retryAfterSeconds);
+    }
     if (err.status === 401) {
         headers["WWW-Authenticate"] =
             `Bearer error="invalid_token", resource_metadata="${resourceMetadataUrlFor(c)}"`;
@@ -262,99 +256,6 @@ function unauthorized(c, reqId, resourceMetadataUrl) {
         "WWW-Authenticate": `Bearer error="invalid_token", resource_metadata="${resourceMetadataUrl}"`,
     });
 }
-function parseLimit(raw) {
-    if (!raw)
-        return { limit: DEFAULT_LIMIT, clamped: false };
-    const parsed = Number.parseInt(raw, 10);
-    if (!Number.isFinite(parsed) || parsed <= 0) {
-        throw new PdppError("invalid_request", "limit must be a positive integer", {
-            param: "limit",
-        });
-    }
-    if (parsed > MAX_LIMIT)
-        return { limit: MAX_LIMIT, clamped: true };
-    return { limit: parsed, clamped: false };
-}
-function parseOrder(raw) {
-    if (raw === undefined)
-        return "desc";
-    if (raw === "asc" || raw === "desc")
-        return raw;
-    throw new PdppError("invalid_request", "order must be 'asc' or 'desc'", {
-        param: "order",
-    });
-}
-/** Query parameters implemented by each endpoint. Unsupported shapes must fail. */
-const KNOWN_QUERY_PARAMS = {
-    listStreams: [],
-    streamMetadata: [],
-    listRecords: ["limit", "order", "cursor", "fields", "changes_since"],
-    getRecord: ["fields"],
-    deleteRecord: [],
-};
-/** Validate exact parameter names before consulting serving metadata. */
-function rejectUnknownParams(c, endpoint, tokenKind) {
-    const allowed = KNOWN_QUERY_PARAMS[endpoint];
-    const recordRead = endpoint === "listRecords" || endpoint === "getRecord";
-    for (const key of new URL(c.req.url).searchParams.keys()) {
-        if (allowed.includes(key))
-            continue;
-        const base = key.replace(/\[.*$/, "");
-        // Current serving metadata declares no expandable relations. Client
-        // requests must still receive invalid_request, before metadata lookup.
-        if (recordRead &&
-            tokenKind === "owner" &&
-            (base === "expand" || base === "expand_limit")) {
-            throw new PdppError("invalid_expand", "No expandable relation is declared", {
-                param: key,
-            });
-        }
-        throw new PdppError("invalid_request", `Unsupported query parameter '${key}'`, {
-            param: key,
-        });
-    }
-}
-/**
- * Narrow a client's requested `fields` within what its grant already allows.
- *
- * Three rules, in order:
- *   - a field outside the grant is a 400, not a silent drop. A client asking
- *     for something it was never granted has made an error it needs to see;
- *     quietly returning less would let it believe it received that field.
- *   - the result is the intersection, so a request can only ever narrow.
- *   - under a v0.1 grant ONLY, the declaration's required fields are re-added,
- *     because v0.1 §8 keeps schema-required fields in every projection
- *     regardless of the request. A v0.2 grant gets the bare intersection:
- *     `v0.2-4-2` builds disclosed `data` from only the members permitted by
- *     the grant AND the request-time selection, and `v0.2-4-1` forbids adding
- *     one back because the schema requires it. Re-widening a sparse v0.2
- *     request would disclose more than both the owner and the client asked
- *     for, which is the one direction this function must never move.
- *
- * Returns the full granted set when no `fields` was requested, preserving the
- * existing default.
- */
-function narrowClientFields(requested, granted, declaration, schemaRequiredFloor) {
-    if (!requested || requested.length === 0)
-        return granted;
-    if (!granted)
-        return requested;
-    const grantedSet = new Set(granted);
-    for (const field of requested) {
-        if (!grantedSet.has(field)) {
-            throw new PdppError("invalid_request", `Field '${field}' is not in this grant's authorized fields for the stream`, { param: "fields" });
-        }
-    }
-    const narrowed = new Set(requested.filter((f) => grantedSet.has(f)));
-    if (schemaRequiredFloor) {
-        // v0.1 only: the consent floor survives a sparse request.
-        for (const required of declaration?.requiredFields ?? []) {
-            if (grantedSet.has(required))
-                narrowed.add(required);
-        }
-    }
-    return Array.from(narrowed);
-}
 /**
  * Project a declared JSON Schema down to exactly the granted fields.
  *
@@ -383,6 +284,11 @@ function projectSchemaToFields(schema, fields) {
 export function pdppRecordsRoutes(deps) {
     const app = new Hono();
     const validateData = createRecordDataValidator(deps.declarations);
+    const readsFor = deps.reads ?? (() => deps.store);
+    /** The token class selects the reader; request input never does. */
+    function reads(context) {
+        return readsFor(context.tokenKind === "owner" ? "owner" : "grant");
+    }
     /**
      * Append one PDPP read to the owner access feed.
      *
@@ -424,6 +330,8 @@ export function pdppRecordsRoutes(deps) {
     app.use("*", async (c, next) => {
         const reqId = requestId();
         c.set("reqId", reqId);
+        // Record responses carry personal data: no shared or stored copies.
+        c.header("Cache-Control", "private, no-store");
         await next();
     });
     async function authenticate(c, reqId) {
@@ -432,7 +340,16 @@ export function pdppRecordsRoutes(deps) {
         if (!token) {
             return { error: unauthorized(c, reqId, resourceMetadataUrlFor(c)) };
         }
-        const context = await deps.auth.resolveToken(token);
+        let context;
+        try {
+            context = await deps.auth.resolveToken(token);
+        }
+        catch (error) {
+            if (!(error instanceof PdppAuthorizationUnavailableError))
+                throw error;
+            logApiError(deps, "authorization", reqId, error);
+            return { error: sendError(c, error, reqId) };
+        }
         // Chain enforcement, when the deployment configures it. Placed here so
         // EVERY endpoint is covered by one gate: a check added per-route is a
         // check that a later route forgets, and an unenforced read path is
@@ -543,7 +460,7 @@ export function pdppRecordsRoutes(deps) {
         if (error)
             return error;
         try {
-            rejectUnknownParams(c, "listStreams");
+            parseRecordQuery(c.req.url, "listStreams");
         }
         catch (err) {
             return sendError(c, mapAndLog(deps, "GET /v1/streams", reqId, err), reqId);
@@ -563,7 +480,7 @@ export function pdppRecordsRoutes(deps) {
         if (context.tokenKind === "owner" && instanceIds.length === 0) {
             return sendError(c, mapAndLog(deps, "GET /v1/streams", reqId, new PdppError("grant_stream_not_allowed", "Owner token is not scoped to a currently owned instance")), reqId);
         }
-        const streams = deps.store.listStreams(instanceIds);
+        const streams = reads(context).listStreams(instanceIds);
         // A client token gets a closed projection: only the streams its grant
         // names, and counts/recency computed over only the records the grant
         // actually exposes. The store's raw listing counts every record in the
@@ -572,6 +489,9 @@ export function pdppRecordsRoutes(deps) {
         const visibleStreams = context.tokenKind === "owner"
             ? streams.map((s) => ({
                 name: s.stream,
+                confirmation: s.confirmation,
+                visibility: s.visibility,
+                status: s.status,
                 recordCount: s.recordCount,
                 lastUpdated: s.lastUpdated,
                 budgetExhausted: false,
@@ -582,7 +502,10 @@ export function pdppRecordsRoutes(deps) {
                 const streamGrant = context.grant?.streams.find((g) => g.name === s.stream);
                 return {
                     name: s.stream,
-                    ...summarizeGrantVisible(deps.store, s.stream, streamGrant?.instance_ids ?? [], streamGrant),
+                    confirmation: undefined,
+                    visibility: undefined,
+                    status: undefined,
+                    ...summarizeGrantVisible(reads(context), s.stream, streamGrant?.instance_ids ?? [], streamGrant),
                 };
             });
         // Report truncation explicitly rather than letting a capped count read as
@@ -598,6 +521,8 @@ export function pdppRecordsRoutes(deps) {
                 name: s.name,
                 record_count: s.recordCount,
                 last_updated: s.lastUpdated,
+                ...(s.confirmation && { confirmation: s.confirmation }),
+                ...(s.status && { visibility: s.visibility, status: s.status }),
             })),
             ...(cappedStreams.length > 0 && {
                 meta: {
@@ -620,7 +545,7 @@ export function pdppRecordsRoutes(deps) {
         if (error)
             return error;
         try {
-            rejectUnknownParams(c, "streamMetadata");
+            parseRecordQuery(c.req.url, "streamMetadata");
             const stream = c.req.param("stream");
             const { declaration, ownerInstanceIds } = readDeclaration(context, stream);
             const scope = resolveReadScope(context, stream, declaration);
@@ -673,10 +598,10 @@ export function pdppRecordsRoutes(deps) {
         if (error)
             return error;
         try {
-            rejectUnknownParams(c, "listRecords", context.tokenKind);
+            const query = parseRecordQuery(c.req.url, "listRecords", context.tokenKind);
             const stream = c.req.param("stream");
             const { declaration, ownerInstanceIds } = readDeclaration(context, stream);
-            const scope = resolveReadScope(context, stream, declaration);
+            const scope = resolveReadScope(context, stream, declaration, query.fields);
             const effectiveInstanceIds = context.tokenKind === "owner" ? ownerInstanceIds : scope.instanceIds;
             if (context.tokenKind === "client") {
                 requireRegisteredConnections(effectiveInstanceIds);
@@ -684,29 +609,13 @@ export function pdppRecordsRoutes(deps) {
             if (context.tokenKind === "owner" && effectiveInstanceIds.length === 0) {
                 throw new PdppError("grant_stream_not_allowed", "Owner token is not scoped to a currently owned instance");
             }
-            const { limit, clamped } = parseLimit(c.req.query("limit"));
-            const order = parseOrder(c.req.query("order"));
-            const requestedFields = c.req
-                .query("fields")
-                ?.split(",")
-                .map((f) => f.trim());
-            // §8: `fields` is a sparse fieldset on the durable client surface, and
-            // an unsupported shape must not be silently ignored. A client token
-            // previously had its `fields` parsed and then discarded, so
-            // `?fields=id` returned every granted field — the response did
-            // something other than what was asked, with a 200.
-            //
-            // A client may only NARROW within its grant; it can never widen. So the
-            // request is validated against the granted set, then intersected with
-            // it, then the schema-required floor is re-added.
-            const fields = context.tokenKind === "client"
-                ? narrowClientFields(requestedFields, scope.fields, declaration, scope.schemaRequiredFloor)
-                : requestedFields
-                    ? [...requestedFields]
-                    : undefined;
-            const cursor = c.req.query("cursor");
-            if (c.req.query("changes_since") !== undefined) {
-                // `fields` is passed here for ELIGIBILITY narrowing only (spec §4:
+            const { limit, clamped, order, cursor } = query;
+            const fields = scope.fields;
+            if (query.changesSince !== undefined) {
+                // Eligibility compares the frozen candidate grant projection; sparse
+                // request fields shape only the response. Legacy profiles retain their
+                // existing request-field eligibility. The store returns raw rows.
+                // (spec §4:
                 // a record whose only change was to an unauthorized field must not
                 // appear as "changed" at all). The store returns each row's RAW,
                 // unprojected data regardless of `fields` — response-shaping
@@ -715,14 +624,26 @@ export function pdppRecordsRoutes(deps) {
                 // field value. This split matters: if the store projected the
                 // returned data too, a grant whose fields exclude the
                 // time_constraint field would silently break that filter.
-                const page = deps.store.changesSince(stream, {
+                const page = reads(context).changesSince(stream, {
                     instanceIds: effectiveInstanceIds,
-                    changesSince: c.req.query("changes_since"),
-                    cursor: c.req.query("cursor"),
+                    changesSince: grantIsCandidate(context.grant) &&
+                        query.changesSince === "beginning"
+                        ? undefined
+                        : query.changesSince,
+                    cursor,
                     limit,
-                    fields,
+                    fields: grantIsCandidate(context.grant)
+                        ? scope.streamGrant.fields
+                        : fields,
+                    ...(grantIsCandidate(context.grant) && {
+                        expireOnErasure: true,
+                        isVisible: (row) => recordKeyWithinGrantResources(row.recordKey, scope.streamGrant) &&
+                            recordWithinGrantTimeConstraint(row.data, scope.streamGrant),
+                    }),
                 });
                 const visible = page.data.filter((row) => {
+                    if (grantIsCandidate(context.grant))
+                        return true; // store compared both authorized historical states
                     if (row.deleted) {
                         return recordKeyWithinGrantResources(row.recordKey, scope.streamGrant);
                     }
@@ -743,56 +664,22 @@ export function pdppRecordsRoutes(deps) {
                     ...(page.nextChangesSince && {
                         next_changes_since: page.nextChangesSince,
                     }),
-                    data: visible.map((row) => toRecordJson(stream, row, fields)),
+                    data: visible.map((row) => toRecordJson(stream, row, fields, grantIsCandidate(context.grant))),
                     ...(clamped && { meta }),
                 }, 200, { "Request-Id": reqId, "PDPP-Version": PDPP_VERSION });
             }
-            // Same ordering requirement as the changes_since branch above: fetch
-            // unprojected, filter by time_constraint against the real value, then
-            // project fields only in toRecordJson.
-            // Grant filtering happens after the store pages, so a page of `limit`
-            // stored rows can yield fewer than `limit` visible rows. Returning that
-            // short page directly would make `limit` mean "at most N stored rows"
-            // rather than "at most N records you may see", and would report
-            // has_more/next_cursor for a position in the unfiltered sequence.
-            // Accumulate visible rows across store pages instead, then derive
-            // paging state from the filtered view.
-            const visible = [];
-            let pageCursor = cursor;
-            let storeHasMore = false;
-            let cursorTemplate;
-            do {
-                const requestCursor = pageCursor;
-                const page = deps.store.listRecords(stream, {
-                    instanceIds: effectiveInstanceIds,
-                    // Fetch at most one client page from the store at a time. The route
-                    // may need several store pages to collect enough grant-visible rows,
-                    // but keeping this page size at the client limit means the store
-                    // usually gives us a bound cursor exactly at the visible boundary.
-                    limit,
-                    order,
-                    cursor: requestCursor,
-                });
-                for (const row of page.data) {
-                    if (recordKeyWithinGrantResources(row.recordKey, scope.streamGrant) &&
-                        recordWithinGrantTimeConstraint(row.data, scope.streamGrant)) {
-                        visible.push(row);
-                    }
-                    if (visible.length > limit)
-                        break;
-                }
-                pageCursor = page.nextCursor ?? undefined;
-                cursorTemplate = pageCursor ?? requestCursor;
-                storeHasMore = page.hasMore;
-            } while (visible.length <= limit && storeHasMore && pageCursor);
-            // limit + 1 visible rows means at least one more record the caller may
-            // see; trim it and report has_more from the filtered view.
-            const moreVisible = visible.length > limit;
-            const data = moreVisible ? visible.slice(0, limit) : visible;
-            const last = data[data.length - 1];
-            if (moreVisible && last && !cursorTemplate) {
-                throw new Error("Filtered list has more rows but no bound store cursor");
-            }
+            const page = reads(context).listRecords(stream, {
+                instanceIds: effectiveInstanceIds,
+                limit,
+                order,
+                cursor,
+                // Only a replica preview reader returns removal rows; only the owner
+                // may see one.
+                isVisible: (row) => recordKeyWithinGrantResources(row.recordKey, scope.streamGrant) &&
+                    (row.deleted
+                        ? context.tokenKind === "owner"
+                        : recordWithinGrantTimeConstraint(row.data, scope.streamGrant)),
+            });
             const meta = clamped
                 ? {
                     warnings: [
@@ -802,13 +689,9 @@ export function pdppRecordsRoutes(deps) {
                 : undefined;
             const response = c.json({
                 object: "list",
-                has_more: moreVisible,
-                ...(moreVisible &&
-                    last &&
-                    cursorTemplate && {
-                    next_cursor: rebindListCursor(cursorTemplate, order, last),
-                }),
-                data: data.map((row) => toRecordJson(stream, row, fields)),
+                has_more: page.hasMore,
+                ...(page.nextCursor && { next_cursor: page.nextCursor }),
+                data: page.data.map((row) => toRecordJson(stream, row, fields, grantIsCandidate(context?.grant))),
                 ...(meta && { meta }),
             }, 200, { "Request-Id": reqId, "PDPP-Version": PDPP_VERSION });
             await logClientRead(c, context, stream, "completed", reqId);
@@ -829,7 +712,7 @@ export function pdppRecordsRoutes(deps) {
         if (error)
             return error;
         try {
-            rejectUnknownParams(c, "getRecord", context.tokenKind);
+            const query = parseRecordQuery(c.req.url, "getRecord", context.tokenKind);
             // §8 requires client-token `expand[]` to be REJECTED before the
             // declaration is consulted, on single-record reads as well as lists.
             // Silently ignoring it told a client its request was honored when a
@@ -837,7 +720,7 @@ export function pdppRecordsRoutes(deps) {
             const stream = c.req.param("stream");
             const recordKey = decodeURIComponent(c.req.param("id"));
             const { declaration, ownerInstanceIds } = readDeclaration(context, stream);
-            const scope = resolveReadScope(context, stream, declaration);
+            const scope = resolveReadScope(context, stream, declaration, query.fields);
             const effectiveInstanceIds = context.tokenKind === "owner" ? ownerInstanceIds : scope.instanceIds;
             if (context.tokenKind === "client") {
                 requireRegisteredConnections(effectiveInstanceIds);
@@ -847,36 +730,21 @@ export function pdppRecordsRoutes(deps) {
             }
             let found;
             for (const instance of effectiveInstanceIds) {
-                const record = deps.store.getRecord(instance, stream, recordKey);
+                const record = reads(context).getRecord(instance, stream, recordKey);
                 if (record) {
                     found = record;
                     break;
                 }
             }
             if (!found ||
-                !recordWithinGrantTimeConstraint(found.data, scope.streamGrant)) {
+                (!(found.deleted && context.tokenKind === "owner") &&
+                    !recordWithinGrantTimeConstraint(found.data, scope.streamGrant))) {
                 throw new PdppError("not_found", "Record not found");
             }
-            // `fields` is a declared parameter of this endpoint, and `v0.2-4-2`
-            // builds disclosed `data` from the grant AND the request-time
-            // selection. It was parsed nowhere, so `?fields=date` returned every
-            // granted field with a 200 — the response did something other than what
-            // was asked, and a client narrowing its own exposure did not get it.
-            const requestedFields = c.req
-                .query("fields")
-                ?.split(",")
-                .map((f) => f.trim());
-            const fields = context.tokenKind === "client"
-                ? narrowClientFields(requestedFields, scope.fields, declaration, scope.schemaRequiredFloor)
-                : (requestedFields ?? scope.fields);
-            const data = projectFields(found.data, fields);
-            const response = c.json({
-                object: "record",
-                id: recordKey,
-                stream,
-                data,
-                emitted_at: found.emittedAt,
-            }, 200, { "Request-Id": reqId, "PDPP-Version": PDPP_VERSION });
+            const fields = scope.fields;
+            const response = c.json(toRecordJson(stream, found.deleted
+                ? found
+                : { ...found, data: projectFields(found.data, fields) }, undefined, grantIsCandidate(context?.grant)), 200, { "Request-Id": reqId, "PDPP-Version": PDPP_VERSION });
             await logClientRead(c, context, stream, "completed", reqId);
             return response;
         }
@@ -892,7 +760,7 @@ export function pdppRecordsRoutes(deps) {
         if (error)
             return error;
         try {
-            rejectUnknownParams(c, "deleteRecord");
+            parseRecordQuery(c.req.url, "deleteRecord");
             if (context.tokenKind !== "owner") {
                 throw new PdppError("authentication_error", "Delete requires an owner token");
             }
@@ -919,6 +787,12 @@ export function pdppRecordsRoutes(deps) {
             });
         }
         catch (err) {
+            if (err instanceof PdppBindingError) {
+                return c.json({
+                    error: { code: err.reason, message: err.reason },
+                    request_id: reqId,
+                }, 409, { "Request-Id": reqId, "PDPP-Version": PDPP_VERSION });
+            }
             return sendError(c, mapAndLog(deps, "DELETE /v1/streams/:stream/records/:id", reqId, err), reqId);
         }
     });
@@ -1443,8 +1317,7 @@ const STREAM_SCAN_ROW_BUDGET = 10_000;
  * against the record's real value, not a projected one.
  */
 function summarizeGrantVisible(store, stream, instanceIds, streamGrant) {
-    // `listRecords` already excludes tombstones, so a deleted row should not
-    // appear here; the guard keeps the narrowing honest rather than asserting.
+    // A pending removal has no current grant-visible value to summarize.
     const visible = (row) => !row.deleted &&
         recordKeyWithinGrantResources(row.recordKey, streamGrant) &&
         recordWithinGrantTimeConstraint(row.data, streamGrant);
@@ -1457,7 +1330,7 @@ function summarizeGrantVisible(store, stream, instanceIds, streamGrant) {
     outer: while (scanned < STREAM_SCAN_ROW_BUDGET) {
         const page = store.listRecords(stream, {
             instanceIds,
-            limit: MAX_LIMIT,
+            limit: 100,
             order: "desc",
             cursor,
         });
@@ -1486,7 +1359,7 @@ function summarizeGrantVisible(store, stream, instanceIds, streamGrant) {
     for (;;) {
         const page = store.listRecords(stream, {
             instanceIds,
-            limit: MAX_LIMIT,
+            limit: 100,
             order: "asc",
             cursor,
         });
@@ -1515,23 +1388,37 @@ function summarizeGrantVisible(store, stream, instanceIds, streamGrant) {
         budgetExhausted: incomplete,
     };
 }
-function toRecordJson(stream, row, fields) {
+/**
+ * One response record or tombstone. The candidate names a record by its
+ * instance and key together, so it adds `instance_id` (the grant's handle,
+ * which is the stored instance) and serves the minimal client tombstone. The
+ * current contract's shape is unchanged.
+ */
+function toRecordJson(stream, row, fields, candidate = false) {
+    const identity = {
+        object: "record",
+        id: row.recordKey,
+        ...(candidate && { instance_id: row.instance }),
+        stream,
+    };
     if (row.deleted) {
+        if (candidate)
+            return { ...identity, deleted: true };
         return {
-            object: "record",
-            id: row.recordKey,
-            stream,
+            ...identity,
             deleted: true,
             deleted_at: row.deletedAt,
             emitted_at: row.emittedAt,
+            ...(row.confirmation && { confirmation: row.confirmation }),
+            ...(row.status && { visibility: row.visibility, status: row.status }),
         };
     }
     return {
-        object: "record",
-        id: row.recordKey,
-        stream,
+        ...identity,
         data: projectFields(row.data, fields),
         emitted_at: row.emittedAt,
+        ...(row.confirmation && { confirmation: row.confirmation }),
+        ...(row.status && { visibility: row.visibility, status: row.status }),
     };
 }
 //# sourceMappingURL=pdpp-records.js.map