@tinycloud/sdk-services 3.8.0-beta.18 → 3.8.0-beta.22

package/dist/feed/index.cjs

@@ -31,7 +31,9 @@ __export(feed_exports, {
   getFeedHandoff: () => getFeedHandoff,
   initializeFeedDatabases: () => initializeFeedDatabases,
   initializeFeedHandoff: () => initializeFeedHandoff,
+  listFeedCardHistory: () => listFeedCardHistory,
   listFeedCards: () => listFeedCards,
+  listFeedResponseDeliveries: () => listFeedResponseDeliveries,
   listFeedResponses: () => listFeedResponses,
   listenFeedResponses: () => listenFeedResponses,
   newFeedMessageSchema: () => newFeedMessageSchema,
@@ -41,7 +43,8 @@ __export(feed_exports, {
   readFeedResponseHandling: () => readFeedResponseHandling,
   readFeedResponsePayload: () => readFeedResponsePayload,
   recordFeedHandling: () => recordFeedHandling,
-  resolveFeedCard: () => resolveFeedCard
+  resolveFeedCard: () => resolveFeedCard,
+  restoreFeedRecords: () => restoreFeedRecords
 });
 module.exports = __toCommonJS(feed_exports);
 
@@ -184,6 +187,23 @@ var feedHandlingSchema = import_zod.z.object({
   detail: import_zod.z.record(import_zod.z.unknown()).optional()
 });
 
+// src/feed/dispatch.ts
+var import_zod2 = require("zod");
+var timestamp = import_zod2.z.string().datetime({ offset: true });
+function validDispatchBefore(value) {
+  return value === null || typeof value === "string" && timestamp.safeParse(value).success && Number.isFinite(Date.parse(value));
+}
+function dispatchDeadlineDenied(response) {
+  const cutoff = response.dispatchBefore;
+  return cutoff !== void 0 && (!validDispatchBefore(cutoff) || typeof cutoff === "string" && Date.now() >= Date.parse(cutoff));
+}
+function dispatchDeadlineFailure() {
+  return err({ code: ErrorCodes.PERMISSION_DENIED, service: "feed", message: "The response dispatch deadline does not permit a new handoff.", meta: { reason: "dispatch_deadline" } });
+}
+function isDispatchDeadlineFailure(error) {
+  return error.service === "feed" && error.code === ErrorCodes.PERMISSION_DENIED && error.meta?.reason === "dispatch_deadline";
+}
+
 // src/feed/notification.ts
 var projectFeedResponseNotification = (response) => {
   const notification = {
@@ -200,6 +220,7 @@ var projectFeedResponseNotification = (response) => {
   if (response.kind !== "message" && response.supersedesResponseId !== void 0) notification.supersedesResponseId = response.supersedesResponseId;
   if (response.payloadType !== void 0) notification.payloadType = response.payloadType;
   if (response.payloadVersion !== void 0) notification.payloadVersion = response.payloadVersion;
+  if (validDispatchBefore(response.dispatchBefore)) notification.dispatchBefore = response.dispatchBefore;
   return notification;
 };
 
@@ -254,18 +275,18 @@ function responseFromHeader(row, header) {
   }
   return projectFeedResponseNotification(response);
 }
-async function storedResponse(db, responseId) {
+async function storedResponse(db, responseId, options = PRIVATE_RESPONSE_OPTIONS) {
   try {
     const result = await db.query(`SELECT r.sequence, r.response_json, p.payload_type, p.payload_version, p.payload_json
       FROM feed_responses r LEFT JOIN feed_response_payloads p ON p.response_id = r.response_id
-      WHERE r.response_id = ?`, [responseId], PRIVATE_RESPONSE_OPTIONS);
+      WHERE r.response_id = ?`, [responseId], options);
     if (!result.ok) return responseDataFailure("Could not read the saved feed response", result.error);
     const row = result.data.rows[0];
     if (!row) return ok(void 0);
     const header = feedResponseHeaderSchema.parse(JSON.parse(String(row[1])));
     const response = responseFromHeader(row, header);
     const payload = row[2] === null || row[2] === void 0 ? void 0 : feedResponsePayloadSchema.parse({ type: row[2], version: Number(row[3]), data: JSON.parse(String(row[4])) });
-    return ok({ response, headerJson: feedJson(header), payload });
+    return ok({ response, rawHeaderJson: String(row[1]), headerJson: feedJson(header), payload });
   } catch (error) {
     return responseDataFailure("Could not read the saved feed response", error);
   }
@@ -295,30 +316,44 @@ var initializeFeedDatabases = async ({ output, responses }) => {
     { sql: "CREATE INDEX IF NOT EXISTS feed_responses_card ON feed_responses (card_id, revision, issuance_id, sequence)" },
     { sql: `CREATE TABLE IF NOT EXISTS feed_response_payloads (
       response_id TEXT PRIMARY KEY, payload_type TEXT NOT NULL, payload_version INTEGER NOT NULL, payload_json TEXT NOT NULL
+    )` },
+    { sql: `CREATE TABLE IF NOT EXISTS feed_response_imports (
+      response_id TEXT PRIMARY KEY, card_id TEXT NOT NULL, revision INTEGER NOT NULL, issuance_id TEXT NOT NULL,
+      content_sha256 TEXT NOT NULL
+    )` },
+    { sql: `CREATE TABLE IF NOT EXISTS feed_response_origins (
+      response_id TEXT NOT NULL, source_json TEXT NOT NULL, PRIMARY KEY (response_id, source_json)
+    )` },
+    { sql: `CREATE TABLE IF NOT EXISTS feed_response_delivery_policies (
+      response_id TEXT NOT NULL, recipient TEXT NOT NULL, policy_json TEXT NOT NULL,
+      PRIMARY KEY (response_id, recipient, policy_json)
     )` }
   ]);
   return responseSchema.ok ? ok(void 0) : responseSchema;
 };
-var publishFeedCard = async (output, card) => {
+var publishFeedCard = (output, card) => storeFeedCard(output, card);
+async function storeFeedCard(output, card, options) {
   if (!validIdentity(card)) return feedError("INVALID_INPUT", "A card requires its full ID, positive revision and issuance ID");
   const encoded = feedJson(card);
   const inserted = await output.execute(
     `INSERT INTO feed_cards (card_id, revision, issuance_id, card_json) VALUES (?, ?, ?, ?)
      ON CONFLICT (card_id, revision, issuance_id) DO NOTHING`,
-    [card.cardId, card.revision, card.issuanceId, encoded]
+    [card.cardId, card.revision, card.issuanceId, encoded],
+    options
   );
   if (!inserted.ok) return inserted;
   const stored = await jsonRows(
     output,
     "SELECT card_json FROM feed_cards WHERE card_id = ? AND revision = ? AND issuance_id = ?",
-    [card.cardId, card.revision, card.issuanceId]
+    [card.cardId, card.revision, card.issuanceId],
+    options
   );
   if (!stored.ok) return stored;
   if (!stored.data[0] || feedJson(stored.data[0]) !== encoded) {
     return feedError("INVALID_INPUT", "A published card identity cannot be silently changed");
   }
   return ok(stored.data[0]);
-};
+}
 var listFeedCards = async (output) => {
   return jsonRows(output, `SELECT card_json FROM feed_cards
     WHERE sequence IN (SELECT MAX(sequence) FROM feed_cards GROUP BY card_id) ORDER BY sequence DESC`);
@@ -618,14 +653,20 @@ var getFeedHandoff = async (handoff, responseId, recipient) => {
   const row = result.data.rows[0];
   if (!row) return ok(null);
   try {
-    return ok({ responseId, recipient, response: projectFeedResponseNotification(JSON.parse(row[0])), state: row[1] });
+    const parsed = JSON.parse(row[0]);
+    if (parsed.dispatchBefore !== void 0 && !validDispatchBefore(parsed.dispatchBefore)) {
+      return feedError("INVALID_INPUT", "Handoff contains invalid dispatch metadata");
+    }
+    return ok({ responseId, recipient, response: projectFeedResponseNotification(parsed), state: row[1] });
   } catch {
     return feedError("INVALID_INPUT", "Handoff contains invalid response JSON");
   }
 };
 var deliverFeedResponse = async ({ handoff, recipient, response: input, deliver }) => {
+  if (dispatchDeadlineDenied(input)) return dispatchDeadlineFailure();
   const response = projectFeedResponseNotification(input);
   if (!recipient || !response.responseId) return feedError("INVALID_INPUT", "Handoff requires a recipient and full response ID");
+  if (dispatchDeadlineDenied(response)) return dispatchDeadlineFailure();
   const inserted = await handoff.execute(
     `INSERT INTO feed_handoffs (response_id, recipient, response_json, state) VALUES (?, ?, ?, 'prepared')
      ON CONFLICT (response_id, recipient) DO NOTHING`,
@@ -638,6 +679,7 @@ var deliverFeedResponse = async ({ handoff, recipient, response: input, deliver
     return feedError("INVALID_INPUT", "A response handoff identity cannot change its payload");
   }
   if (existing.data.state !== "prepared") return ok(existing.data);
+  if (dispatchDeadlineDenied(response)) return dispatchDeadlineFailure();
   const claimed = await handoff.execute(
     "UPDATE feed_handoffs SET state = 'unconfirmed' WHERE response_id = ? AND recipient = ? AND state = 'prepared'",
     [response.responseId, recipient]
@@ -647,6 +689,7 @@ var deliverFeedResponse = async ({ handoff, recipient, response: input, deliver
     const current = await getFeedHandoff(handoff, response.responseId, recipient);
     return current.ok && current.data ? ok(current.data) : current.ok ? feedError("NOT_FOUND", "Handoff disappeared before delivery") : current;
   }
+  if (dispatchDeadlineDenied(response)) return dispatchDeadlineFailure();
   let state = "unconfirmed";
   try {
     const delivered = await deliver(response);
@@ -663,6 +706,202 @@ var deliverFeedResponse = async ({ handoff, recipient, response: input, deliver
   return ok({ ...existing.data, state });
 };
 
+// src/feed/restore-metadata.ts
+var import_zod3 = require("zod");
+var restoreOriginSchema = import_zod3.z.object({
+  sourceSpaceId: import_zod3.z.string().min(1),
+  namespace: import_zod3.z.string().min(1),
+  snapshotId: import_zod3.z.string().min(1),
+  sourceKey: import_zod3.z.string().min(1),
+  eventKey: import_zod3.z.string().min(1).optional()
+}).strict();
+var restorePolicySchema = import_zod3.z.object({
+  recipient: import_zod3.z.string().min(1),
+  state: import_zod3.z.enum(["pending", "held", "delivered", "unconfirmed", "refused", "unknown"]),
+  dispatch: import_zod3.z.enum(["never", "resolved-pending", "held"]),
+  resolvedOwnerMapping: import_zod3.z.boolean(),
+  dispatchBefore: import_zod3.z.custom(validDispatchBefore),
+  source: restoreOriginSchema
+}).strict();
+function restoreContent(input, inputPayload) {
+  const response = feedResponseHeaderSchema.parse(input);
+  const headerJson = feedJson(response);
+  if (feedJson(input) !== headerJson) throw new Error("Invalid restored response header fields");
+  const payload = inputPayload === void 0 ? void 0 : feedResponsePayloadSchema.parse(inputPayload);
+  const payloadJson = payload === void 0 ? void 0 : feedJson(payload.data);
+  const envelope = payload === void 0 ? "null" : `{"data":${payloadJson},"type":${JSON.stringify(payload.type)},"version":${payload.version}}`;
+  return { response, headerJson, payload, payloadJson, canonical: `{"payload":${envelope},"response":${headerJson}}` };
+}
+async function contentSha256(content) {
+  const digest = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(content)));
+  let hex = "";
+  for (const byte of digest) hex += byte.toString(16).padStart(2, "0");
+  return hex;
+}
+function sameOriginBinding(a, b) {
+  return a.sourceSpaceId === b.sourceSpaceId && a.namespace === b.namespace && a.sourceKey === b.sourceKey && a.eventKey === b.eventKey;
+}
+function restoreCancelled(signal) {
+  return signal?.aborted ? feedError(ErrorCodes.ABORTED, "Feed restore or policy read was aborted") : void 0;
+}
+function baselinePolicy(source) {
+  return { recipient: "*", state: "unknown", dispatch: "never", resolvedOwnerMapping: false, dispatchBefore: null, source };
+}
+async function readRestoreMetadata(responses, responseIds, options) {
+  const cancelled = restoreCancelled(options.signal);
+  if (cancelled) return cancelled;
+  const metadata = /* @__PURE__ */ new Map();
+  for (const id of responseIds) metadata.set(id, { origins: /* @__PURE__ */ new Map(), policies: [] });
+  const selected = responseIds.length ? `VALUES ${responseIds.map(() => "(?)").join(",")}` : "SELECT CAST(NULL AS TEXT) WHERE 0";
+  try {
+    const result = await responses.query(`WITH selected(response_id) AS (${selected})
+      SELECT response_id, 'import', card_id, revision, issuance_id, content_sha256
+        FROM feed_response_imports WHERE response_id IN (SELECT response_id FROM selected)
+      UNION ALL SELECT response_id, 'origin', source_json, NULL, NULL, NULL
+        FROM feed_response_origins WHERE response_id IN (SELECT response_id FROM selected)
+      UNION ALL SELECT response_id, 'policy', recipient, policy_json, NULL, NULL
+        FROM feed_response_delivery_policies WHERE response_id IN (SELECT response_id FROM selected)`, responseIds, options);
+    if (!result.ok) return responseDataFailure("Could not read feed restore policy metadata", result.error);
+    const aborted = restoreCancelled(options.signal);
+    if (aborted) return aborted;
+    for (const row of result.data.rows) {
+      const target = metadata.get(String(row[0]));
+      if (!target) throw new Error("Policy metadata does not belong to its response page");
+      if (row[1] === "import") {
+        if (target.marker || typeof row[2] !== "string" || !row[2] || !Number.isSafeInteger(row[3]) || Number(row[3]) < 1 || typeof row[4] !== "string" || !row[4] || typeof row[5] !== "string" || !/^[a-f0-9]{64}$/.test(row[5])) {
+          throw new Error("Invalid import marker");
+        }
+        target.marker = { cardId: row[2], revision: Number(row[3]), issuanceId: row[4], contentSha256: row[5] };
+      } else if (row[1] === "origin") {
+        const source = restoreOriginSchema.parse(JSON.parse(String(row[2])));
+        target.origins.set(feedJson(source), source);
+      } else if (row[1] === "policy") {
+        const policy = restorePolicySchema.parse(JSON.parse(String(row[3])));
+        if (row[2] !== policy.recipient) throw new Error("Policy recipient does not match its stored key");
+        target.policies.push(policy);
+      } else throw new Error("Unknown restore metadata row");
+    }
+    return ok(metadata);
+  } catch (error) {
+    return responseDataFailure("Could not verify feed restore policy metadata", error);
+  }
+}
+function verifyRestoreMetadata(metadata, response, contentHash) {
+  if (!metadata.marker) {
+    if (metadata.origins.size || metadata.policies.length) throw new Error("Orphan restore metadata");
+    return false;
+  }
+  if (!sameFeedIdentity(metadata.marker, response) || contentHash !== void 0 && metadata.marker.contentSha256 !== contentHash || !metadata.origins.size) {
+    throw new Error("Import identity, content or source reference is unverified");
+  }
+  let binding;
+  const defaults = /* @__PURE__ */ new Set();
+  for (const source of metadata.origins.values()) {
+    if (binding && !sameOriginBinding(binding, source)) throw new Error("Conflicting import source bindings");
+    binding = source;
+  }
+  for (const policy of metadata.policies) {
+    const source = feedJson(policy.source);
+    if (!metadata.origins.has(source)) throw new Error("Policy references an unregistered import origin");
+    if (policy.recipient === "*") {
+      if (feedJson(policy) !== feedJson(baselinePolicy(policy.source))) throw new Error("Invalid default import policy");
+      defaults.add(source);
+    }
+  }
+  for (const source of metadata.origins.keys()) if (!defaults.has(source)) throw new Error("Missing default import policy");
+  return true;
+}
+
+// src/feed/delivery-policy.ts
+function permittedDeadline(metadata, recipient) {
+  const evidence = /* @__PURE__ */ new Map();
+  for (const policy of metadata.policies) {
+    if (policy.recipient !== recipient) continue;
+    const source = feedJson(policy.source);
+    const rows = evidence.get(source);
+    if (rows) rows.push(policy);
+    else evidence.set(source, [policy]);
+  }
+  let cutoff;
+  for (const source of metadata.origins.keys()) {
+    const rows = evidence.get(source);
+    if (!rows?.length) return { allowed: false };
+    for (const policy of rows) {
+      if (policy.state !== "pending" || policy.dispatch !== "resolved-pending" || !policy.resolvedOwnerMapping) return { allowed: false };
+      if (cutoff === void 0) cutoff = policy.dispatchBefore;
+      else if (cutoff !== policy.dispatchBefore) return { allowed: false };
+      if (typeof policy.dispatchBefore === "string" && Date.now() >= Date.parse(policy.dispatchBefore)) return { allowed: false };
+    }
+  }
+  return cutoff === void 0 ? { allowed: false } : { allowed: true, cutoff };
+}
+var listFeedResponseDeliveries = async (responses, options) => {
+  try {
+    const after = options.afterSequence ?? 0;
+    const limit = options.limit ?? 100;
+    if (!options.recipient || options.recipient === "*" || !Number.isSafeInteger(after) || after < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > 1e3) {
+      return feedError("INVALID_INPUT", "Delivery pages require an exact recipient and valid sequence pagination");
+    }
+    const privateOptions = { redactErrors: true, signal: options.signal };
+    const cancelled = restoreCancelled(options.signal);
+    if (cancelled) return cancelled;
+    const result = await responses.query(`SELECT r.sequence, r.response_json, p.payload_type, p.payload_version,
+      p.payload_json, r.card_id, r.revision, r.issuance_id, r.response_id
+      FROM feed_responses r LEFT JOIN feed_response_payloads p ON p.response_id = r.response_id
+      WHERE r.sequence > ? ORDER BY r.sequence LIMIT ?`, [after, limit + 1], privateOptions);
+    if (!result.ok) return responseDataFailure("Could not read feed response delivery headers", result.error);
+    const stopped = restoreCancelled(options.signal);
+    if (stopped) return stopped;
+    const rows = result.data.rows.slice(0, limit);
+    const headers = [];
+    const ids = [];
+    const seen = /* @__PURE__ */ new Set();
+    let nextSequence = after;
+    for (const row of rows) {
+      const response = responseFromRow(row);
+      if (!Number.isSafeInteger(response.sequence) || response.sequence <= nextSequence || seen.has(response.responseId) || row[8] !== response.responseId || !sameFeedIdentity(response, { cardId: String(row[5]), revision: Number(row[6]), issuanceId: String(row[7]) })) {
+        throw new Error("Response page identity or ordering is unverified");
+      }
+      seen.add(response.responseId);
+      nextSequence = response.sequence;
+      headers.push(response);
+      ids.push(response.responseId);
+    }
+    const metadataResult = await readRestoreMetadata(responses, ids, privateOptions);
+    if (!metadataResult.ok) return metadataResult;
+    const deliveries = [];
+    for (let index = 0; index < headers.length; index += 1) {
+      const response = headers[index];
+      const metadata = metadataResult.data.get(response.responseId);
+      if (!verifyRestoreMetadata(metadata, response)) {
+        deliveries.push(response);
+        continue;
+      }
+      const row = rows[index];
+      let payload;
+      if (row[2] !== null && row[2] !== void 0) {
+        payload = feedResponsePayloadSchema.parse({ type: row[2], version: row[3], data: JSON.parse(String(row[4])) });
+      } else if (row[3] !== null && row[3] !== void 0 || row[4] !== null && row[4] !== void 0) {
+        throw new Error("Imported payload presence is unverified");
+      }
+      const content = restoreContent(JSON.parse(String(row[1])), payload);
+      const hash = await contentSha256(content.canonical);
+      const aborted2 = restoreCancelled(options.signal);
+      if (aborted2) return aborted2;
+      verifyRestoreMetadata(metadata, response, hash);
+      const permission = permittedDeadline(metadata, options.recipient);
+      if (permission.allowed) {
+        deliveries.push(projectFeedResponseNotification({ ...response, dispatchBefore: permission.cutoff }));
+      }
+    }
+    const aborted = restoreCancelled(options.signal);
+    if (aborted) return aborted;
+    return ok({ responses: deliveries, nextSequence, hasMore: result.data.rows.length > limit });
+  } catch (error) {
+    return responseDataFailure("Could not verify feed response delivery policy", error);
+  }
+};
+
 // src/feed/listener.ts
 var listenFeedResponses = async (options) => {
   const { signal } = options;
@@ -687,12 +926,12 @@ var listenFeedResponses = async (options) => {
       dirty = false;
       let afterSequence = 0;
       while (!signal.aborted) {
-        const page = await listFeedResponses(options.responses, { afterSequence, limit: 100, signal });
+        const page = await listFeedResponseDeliveries(options.responses, { recipient: options.recipient, afterSequence, limit: 100, signal });
         if (!page.ok) {
           if (signal.aborted && page.error.code === ErrorCodes.ABORTED) return;
           throw page.error;
         }
-        for (const response of page.data) {
+        for (const response of page.data.responses) {
           if (signal.aborted) return;
           const handoff = await deliverFeedResponse({
             handoff: options.handoff,
@@ -700,10 +939,11 @@ var listenFeedResponses = async (options) => {
             response,
             deliver: options.deliver
           });
-          if (!handoff.ok) throw handoff.error;
-          afterSequence = response.sequence;
+          if (!handoff.ok && !isDispatchDeadlineFailure(handoff.error)) throw handoff.error;
         }
-        if (page.data.length < 100) break;
+        if (page.data.hasMore && page.data.nextSequence <= afterSequence) throw new Error("Delivery page did not advance a verified cursor");
+        afterSequence = page.data.nextSequence;
+        if (!page.data.hasMore) break;
       }
     } while (dirty && !signal.aborted);
   };
@@ -759,6 +999,285 @@ var feedResourceNames = (prefix, stableToken) => {
     responseResource: `${prefix}/feed_responses_${stableToken}`
   });
 };
+
+// src/feed/restore.ts
+var import_zod4 = require("zod");
+var envelopeSchema = import_zod4.z.object({
+  response: import_zod4.z.unknown(),
+  payload: import_zod4.z.unknown().optional(),
+  origin: restoreOriginSchema,
+  deliveries: import_zod4.z.array(restorePolicySchema).optional()
+}).strict();
+var recordsSchema = import_zod4.z.object({ cards: import_zod4.z.array(import_zod4.z.unknown()), responses: import_zod4.z.array(envelopeSchema) }).strict();
+function markerGuard(content, hash) {
+  const response = content.response;
+  return {
+    sql: `EXISTS (SELECT 1 FROM feed_response_imports WHERE response_id = ? AND card_id = ?
+    AND revision = ? AND issuance_id = ? AND content_sha256 = ?)`,
+    params: [response.responseId, response.cardId, response.revision, response.issuanceId, hash]
+  };
+}
+function bindingGuard(responseId, source) {
+  return {
+    sql: `NOT EXISTS (SELECT 1 FROM feed_response_origins WHERE response_id = ? AND (
+    json_extract(source_json, '$.sourceSpaceId') IS NOT ? OR json_extract(source_json, '$.namespace') IS NOT ?
+    OR json_extract(source_json, '$.sourceKey') IS NOT ? OR json_extract(source_json, '$.eventKey') IS NOT ?))`,
+    params: [responseId, source.sourceSpaceId, source.namespace, source.sourceKey, source.eventKey ?? null]
+  };
+}
+function headerGuard(content) {
+  const response = content.response;
+  return {
+    sql: `EXISTS (SELECT 1 FROM feed_responses r WHERE r.response_id = ? AND r.card_id = ? AND r.revision = ?
+    AND r.issuance_id = ? AND r.response_json = ?)`,
+    params: [response.responseId, response.cardId, response.revision, response.issuanceId, content.headerJson]
+  };
+}
+function payloadGuard(content) {
+  const responseId = content.response.responseId;
+  return content.payload === void 0 ? { sql: "NOT EXISTS (SELECT 1 FROM feed_response_payloads WHERE response_id = ?)", params: [responseId] } : {
+    sql: `EXISTS (SELECT 1 FROM feed_response_payloads WHERE response_id = ? AND payload_type = ?
+        AND payload_version = ? AND payload_json = ?)`,
+    params: [responseId, content.payload.type, content.payload.version, content.payloadJson]
+  };
+}
+function combined(...guards) {
+  return { sql: guards.map((guard) => `(${guard.sql})`).join(" AND "), params: guards.flatMap((guard) => guard.params) };
+}
+function restoreStatements(group, hash) {
+  const { content } = group;
+  const response = content.response;
+  const first = group.origins.values().next().value;
+  const claim = combined(markerGuard(content, hash), bindingGuard(response.responseId, first.origin));
+  const header = headerGuard(content);
+  const complete = combined(claim, header, payloadGuard(content));
+  const committed = [complete];
+  const statements = [{
+    // Claim precedes the header under the same transaction. A committed live header cannot be reclassified.
+    sql: `INSERT INTO feed_response_imports (response_id, card_id, revision, issuance_id, content_sha256)
+      SELECT ?, ?, ?, ?, ? WHERE NOT EXISTS (SELECT 1 FROM feed_responses WHERE response_id = ?)
+        AND NOT EXISTS (SELECT 1 FROM feed_response_payloads WHERE response_id = ?)
+        AND NOT EXISTS (SELECT 1 FROM feed_response_origins WHERE response_id = ?)
+        AND NOT EXISTS (SELECT 1 FROM feed_response_delivery_policies WHERE response_id = ?)
+      ON CONFLICT (response_id) DO NOTHING`,
+    params: [
+      response.responseId,
+      response.cardId,
+      response.revision,
+      response.issuanceId,
+      hash,
+      response.responseId,
+      response.responseId,
+      response.responseId,
+      response.responseId
+    ]
+  }, {
+    sql: `INSERT INTO feed_responses (response_id, card_id, revision, issuance_id, response_json)
+      SELECT ?, ?, ?, ?, ? WHERE ${claim.sql} ON CONFLICT (response_id) DO NOTHING`,
+    params: [response.responseId, response.cardId, response.revision, response.issuanceId, content.headerJson, ...claim.params]
+  }];
+  if (content.payload !== void 0) statements.push({
+    sql: `INSERT INTO feed_response_payloads (response_id, payload_type, payload_version, payload_json)
+      SELECT ?, ?, ?, ? WHERE ${combined(claim, header).sql} ON CONFLICT (response_id) DO NOTHING`,
+    params: [response.responseId, content.payload.type, content.payload.version, content.payloadJson, ...claim.params, ...header.params]
+  });
+  for (const [sourceJson, evidence] of group.origins) {
+    statements.push({
+      sql: `INSERT INTO feed_response_origins (response_id, source_json)
+      SELECT ?, ? WHERE ${complete.sql} ON CONFLICT (response_id, source_json) DO NOTHING`,
+      params: [response.responseId, sourceJson, ...complete.params]
+    });
+    committed.push({
+      sql: "EXISTS (SELECT 1 FROM feed_response_origins WHERE response_id = ? AND source_json = ?)",
+      params: [response.responseId, sourceJson]
+    });
+    for (const policy of [baselinePolicy(evidence.origin), ...evidence.policies.values()]) {
+      statements.push({
+        sql: `INSERT INTO feed_response_delivery_policies (response_id, recipient, policy_json)
+        SELECT ?, ?, ? WHERE ${complete.sql} AND EXISTS (
+          SELECT 1 FROM feed_response_origins WHERE response_id = ? AND source_json = ?)
+        ON CONFLICT (response_id, recipient, policy_json) DO NOTHING`,
+        params: [response.responseId, policy.recipient, feedJson(policy), ...complete.params, response.responseId, sourceJson]
+      });
+      committed.push({
+        sql: "EXISTS (SELECT 1 FROM feed_response_delivery_policies WHERE response_id = ? AND recipient = ? AND policy_json = ?)",
+        params: [response.responseId, policy.recipient, feedJson(policy)]
+      });
+    }
+  }
+  const proof = combined(...committed);
+  statements.push({
+    sql: `INSERT INTO feed_response_imports (response_id, card_id, revision, issuance_id, content_sha256)
+      SELECT ?, NULL, NULL, NULL, NULL WHERE NOT (${proof.sql})`,
+    params: [response.responseId, ...proof.params]
+  });
+  return statements;
+}
+async function restoreGroup(output, responses, group, options) {
+  const { content } = group;
+  const response = content.response;
+  const card = await output.query(
+    "SELECT card_json FROM feed_cards WHERE card_id = ? AND revision = ? AND issuance_id = ?",
+    [response.cardId, response.revision, response.issuanceId],
+    options
+  );
+  if (!card.ok) return responseDataFailure("Could not verify a restored response card issuance", card.error);
+  const cardReadCancelled = restoreCancelled(options.signal);
+  if (cardReadCancelled) return cardReadCancelled;
+  if (!card.data.rows[0] || !sameFeedIdentity(feedCardSchema.parse(JSON.parse(card.data.rows[0][0])), response)) {
+    return feedError("INVALID_INPUT", "Restored response requires a published full card issuance");
+  }
+  const hash = await contentSha256(content.canonical);
+  const cancelled = restoreCancelled(options.signal);
+  if (cancelled) return cancelled;
+  const previous = await storedResponse(responses, response.responseId, options);
+  if (!previous.ok) return previous;
+  const previousMetadata = await readRestoreMetadata(responses, [response.responseId], options);
+  if (!previousMetadata.ok) return previousMetadata;
+  const before = previousMetadata.data.get(response.responseId);
+  if (previous.data) {
+    if (!verifyRestoreMetadata(before, response, hash)) return feedError("INVALID_INPUT", "A live response ID cannot be restored or reclassified");
+    if (restoreContent(JSON.parse(previous.data.rawHeaderJson), previous.data.payload).canonical !== content.canonical) {
+      return feedError("INVALID_INPUT", "A restored response ID cannot change header or private payload");
+    }
+    const known = before.origins.values().next().value;
+    for (const evidence of group.origins.values()) if (!sameOriginBinding(known, evidence.origin)) {
+      return feedError("INVALID_INPUT", "A restored response cannot alias its source binding");
+    }
+  } else if (before.marker || before.origins.size || before.policies.length) {
+    return feedError("INVALID_INPUT", "Orphan restore metadata cannot authorize a new header");
+  }
+  const aborted = restoreCancelled(options.signal);
+  if (aborted) return aborted;
+  let failure;
+  let failed = false;
+  try {
+    const saved = await responses.batch(restoreStatements(group, hash), options);
+    if (!saved.ok) {
+      failed = true;
+      failure = saved.error;
+    }
+  } catch (error) {
+    failed = true;
+    failure = error;
+  }
+  const stopped = restoreCancelled(options.signal);
+  if (stopped) return failed ? responseDataFailure("Could not restore response and atomic import policy", failure) : stopped;
+  const stored = await storedResponse(responses, response.responseId, options);
+  if (!stored.ok) return failed && options.signal?.aborted && stored.error.code === ErrorCodes.ABORTED ? responseDataFailure("Could not restore response and atomic import policy", failure) : stored;
+  const metadata = await readRestoreMetadata(responses, [response.responseId], options);
+  if (!metadata.ok) return failed && options.signal?.aborted && metadata.error.code === ErrorCodes.ABORTED ? responseDataFailure("Could not restore response and atomic import policy", failure) : metadata;
+  const actual = metadata.data.get(response.responseId);
+  if (!stored.data) return responseDataFailure("Could not restore response and atomic import policy", failure);
+  if (!verifyRestoreMetadata(actual, response, hash) || restoreContent(JSON.parse(stored.data.rawHeaderJson), stored.data.payload).canonical !== content.canonical) {
+    return feedError("INVALID_INPUT", "Restore conflicts with an existing live or different response");
+  }
+  const policies = new Set(actual.policies.map(feedJson));
+  for (const [sourceJson, evidence] of group.origins) {
+    if (!actual.origins.has(sourceJson) || !policies.has(feedJson(baselinePolicy(evidence.origin)))) {
+      return failed ? responseDataFailure("Could not restore atomic provenance and default policy", failure) : feedError("INVALID_INPUT", "Restore source binding conflicts with existing provenance");
+    }
+    for (const policy of evidence.policies.keys()) if (!policies.has(policy)) {
+      return responseDataFailure("Could not retain requested immutable delivery evidence", failure);
+    }
+  }
+  const readbackCancelled = restoreCancelled(options.signal);
+  if (readbackCancelled) return failed ? responseDataFailure("Could not restore response and atomic import policy", failure) : readbackCancelled;
+  return ok(void 0);
+}
+var restoreFeedRecords = async (ownerPair, input, options = {}) => {
+  const privateOptions = { redactErrors: true, signal: options.signal };
+  try {
+    const cancelled = restoreCancelled(options.signal);
+    if (cancelled) return cancelled;
+    const parsed = recordsSchema.parse(input);
+    const cards = parsed.cards.map((card) => {
+      const valid = feedCardSchema.parse(card);
+      if (valid.payload !== void 0) valid.payload = card.payload;
+      if (feedJson(valid) !== feedJson(card)) throw new Error("Invalid restored card fields");
+      return valid;
+    });
+    const groups = /* @__PURE__ */ new Map();
+    for (const record of parsed.responses) {
+      const content = restoreContent(record.response, record.payload);
+      const id = content.response.responseId;
+      let group = groups.get(id);
+      if (group && group.content.canonical !== content.canonical) throw new Error("Conflicting restored response content");
+      if (!group) {
+        group = { content, origins: /* @__PURE__ */ new Map() };
+        groups.set(id, group);
+      }
+      const first = group.origins.values().next().value;
+      if (first && !sameOriginBinding(first.origin, record.origin)) throw new Error("Conflicting restored response binding");
+      const sourceJson = feedJson(record.origin);
+      let evidence = group.origins.get(sourceJson);
+      if (!evidence) {
+        evidence = { origin: record.origin, policies: /* @__PURE__ */ new Map() };
+        group.origins.set(sourceJson, evidence);
+      }
+      for (const policy of record.deliveries ?? []) {
+        if (policy.recipient === "*" || feedJson(policy.source) !== sourceJson) throw new Error("Policy must belong to its exact origin and recipient");
+        evidence.policies.set(feedJson(policy), policy);
+      }
+    }
+    for (const card of cards) {
+      const stopped = restoreCancelled(options.signal);
+      if (stopped) return stopped;
+      const saved = await storeFeedCard(ownerPair.output, card, privateOptions);
+      if (!saved.ok) return responseDataFailure("Could not publish a restored card", saved.error);
+    }
+    for (const group of groups.values()) {
+      const stopped = restoreCancelled(options.signal);
+      if (stopped) return stopped;
+      const saved = await restoreGroup(ownerPair.output, ownerPair.responses, group, privateOptions);
+      if (!saved.ok) return saved;
+    }
+    return restoreCancelled(options.signal) ?? ok(void 0);
+  } catch (error) {
+    return responseDataFailure("Could not validate or restore generic feed records", error);
+  }
+};
+
+// src/feed/history.ts
+function validIdentity2(value) {
+  return value !== null && typeof value === "object" && typeof value.cardId === "string" && value.cardId.length > 0 && Number.isSafeInteger(value.revision) && value.revision > 0 && typeof value.issuanceId === "string" && value.issuanceId.length > 0;
+}
+var listFeedCardHistory = async (output, options = {}) => {
+  try {
+    const { afterIdentity, signal } = options;
+    const limit = options.limit === void 0 ? 100 : options.limit;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1e3 || afterIdentity !== void 0 && !validIdentity2(afterIdentity)) {
+      return feedError(ErrorCodes.INVALID_INPUT, "Card history requires a full identity cursor and valid page limit");
+    }
+    if (signal?.aborted) return feedError(ErrorCodes.ABORTED, "Card history read was cancelled");
+    const params = afterIdentity ? [afterIdentity.cardId, afterIdentity.revision, afterIdentity.issuanceId, limit + 1] : [limit + 1];
+    const result = await output.query(`SELECT card_id, revision, issuance_id, card_json FROM feed_cards
+      ${afterIdentity ? "WHERE (card_id COLLATE BINARY, revision, issuance_id COLLATE BINARY) > (?, ?, ?)" : ""}
+      ORDER BY card_id COLLATE BINARY, revision, issuance_id COLLATE BINARY LIMIT ?`, params, { redactErrors: true, signal });
+    if (!result.ok) return responseDataFailure("Could not read feed card history", result.error);
+    if (signal?.aborted) return feedError(ErrorCodes.ABORTED, "Card history read was cancelled");
+    const cards = [];
+    const count = Math.min(limit, result.data.rows.length);
+    for (let index = 0; index < count; index += 1) {
+      const row = result.data.rows[index];
+      if (typeof row[3] !== "string") throw new Error("Stored card envelope is invalid");
+      const card = JSON.parse(row[3]);
+      feedCardSchema.parse(card);
+      if (!validIdentity2(card) || row[0] !== card.cardId || row[1] !== card.revision || row[2] !== card.issuanceId) {
+        throw new Error("Stored card identity does not match its key");
+      }
+      cards.push(card);
+    }
+    const last = cards[cards.length - 1];
+    return ok({
+      cards,
+      nextIdentity: last ? { cardId: last.cardId, revision: last.revision, issuanceId: last.issuanceId } : null,
+      hasMore: result.data.rows.length > limit
+    });
+  } catch (error) {
+    return responseDataFailure("Could not verify feed card history", error);
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   appendFeedMessage,
@@ -772,7 +1291,9 @@ var feedResourceNames = (prefix, stableToken) => {
   getFeedHandoff,
   initializeFeedDatabases,
   initializeFeedHandoff,
+  listFeedCardHistory,
   listFeedCards,
+  listFeedResponseDeliveries,
   listFeedResponses,
   listenFeedResponses,
   newFeedMessageSchema,
@@ -782,6 +1303,7 @@ var feedResourceNames = (prefix, stableToken) => {
   readFeedResponseHandling,
   readFeedResponsePayload,
   recordFeedHandling,
-  resolveFeedCard
+  resolveFeedCard,
+  restoreFeedRecords
 });
 //# sourceMappingURL=index.cjs.map