@tinycloud/sdk-services 3.8.0-beta.9 → 3.8.0

package/dist/feed/index.cjs

@@ -0,0 +1,1309 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/feed/index.ts
+var feed_exports = {};
+__export(feed_exports, {
+  appendFeedMessage: () => appendFeedMessage,
+  appendFeedResponse: () => appendFeedResponse,
+  deliverFeedResponse: () => deliverFeedResponse,
+  feedCardSchema: () => feedCardSchema,
+  feedHandlingSchema: () => feedHandlingSchema,
+  feedResourceNames: () => feedResourceNames,
+  feedResponsePayloadSchema: () => feedResponsePayloadSchema,
+  getFeedCardState: () => getFeedCardState,
+  getFeedHandoff: () => getFeedHandoff,
+  initializeFeedDatabases: () => initializeFeedDatabases,
+  initializeFeedHandoff: () => initializeFeedHandoff,
+  listFeedCardHistory: () => listFeedCardHistory,
+  listFeedCards: () => listFeedCards,
+  listFeedResponseDeliveries: () => listFeedResponseDeliveries,
+  listFeedResponses: () => listFeedResponses,
+  listenFeedResponses: () => listenFeedResponses,
+  newFeedMessageSchema: () => newFeedMessageSchema,
+  newFeedResponseSchema: () => newFeedResponseSchema,
+  projectFeedResponseNotification: () => projectFeedResponseNotification,
+  publishFeedCard: () => publishFeedCard,
+  readFeedResponseHandling: () => readFeedResponseHandling,
+  readFeedResponsePayload: () => readFeedResponsePayload,
+  recordFeedHandling: () => recordFeedHandling,
+  resolveFeedCard: () => resolveFeedCard,
+  restoreFeedRecords: () => restoreFeedRecords
+});
+module.exports = __toCommonJS(feed_exports);
+
+// src/types.ts
+var ErrorCodes = {
+  // Common errors
+  NOT_FOUND: "NOT_FOUND",
+  AUTH_EXPIRED: "AUTH_EXPIRED",
+  AUTH_REQUIRED: "AUTH_REQUIRED",
+  AUTH_UNAUTHORIZED: "AUTH_UNAUTHORIZED",
+  /** HTTP 401: the delegation the invocation cites was revoked. */
+  AUTH_DELEGATION_REVOKED: "AUTH_DELEGATION_REVOKED",
+  /** HTTP 401: a delegation the cited one rests on was revoked. */
+  AUTH_DELEGATION_ANCESTOR_REVOKED: "AUTH_DELEGATION_ANCESTOR_REVOKED",
+  NETWORK_ERROR: "NETWORK_ERROR",
+  TIMEOUT: "TIMEOUT",
+  ABORTED: "ABORTED",
+  INVALID_INPUT: "INVALID_INPUT",
+  PERMISSION_DENIED: "PERMISSION_DENIED",
+  // Node retry signals (tinycloud-node #347). `meta.retryable` says whether a
+  // retry is safe; `meta.retryAfterMs` carries the node's Retry-After.
+  /** HTTP 503 `sql_busy:<stage>` / `unavailable_retryable`/`read_audit_busy`: nothing was applied; retry after `meta.retryAfterMs`. */
+  NODE_BUSY: "NODE_BUSY",
+  /** HTTP 503 `request_timeout`: the node's deadline passed before any write began; nothing was applied. */
+  REQUEST_TIMEOUT: "REQUEST_TIMEOUT",
+  /** HTTP 500 `outcome_unknown`: a write may have been applied; read back before retrying a non-idempotent operation. */
+  OUTCOME_UNKNOWN: "OUTCOME_UNKNOWN",
+  // KV-specific errors
+  KV_NOT_FOUND: "KV_NOT_FOUND",
+  KV_WRITE_FAILED: "KV_WRITE_FAILED",
+  KV_PRECONDITION_FAILED: "KV_PRECONDITION_FAILED",
+  KV_CONFLICT: "KV_CONFLICT",
+  KV_RESPONSE_TOO_LARGE: "KV_RESPONSE_TOO_LARGE",
+  /** HTTP 410 from the change feed: discard sync state and restart without a cursor; `meta.reason` says why. */
+  KV_SYNC_RESET_REQUIRED: "KV_SYNC_RESET_REQUIRED",
+  /** HTTP 403 from the change feed: the retention grant was refused; `meta.reason` says why. */
+  KV_RETENTION_GRANT_REFUSED: "KV_RETENTION_GRANT_REFUSED",
+  // SQL-specific errors
+  SQL_ERROR: "SQL_ERROR",
+  SQL_PERMISSION_DENIED: "SQL_PERMISSION_DENIED",
+  SQL_DATABASE_NOT_FOUND: "SQL_DATABASE_NOT_FOUND",
+  SQL_RESPONSE_TOO_LARGE: "SQL_RESPONSE_TOO_LARGE",
+  SQL_QUOTA_EXCEEDED: "SQL_QUOTA_EXCEEDED",
+  SQL_INVALID_STATEMENT: "SQL_INVALID_STATEMENT",
+  SQL_SCHEMA_ERROR: "SQL_SCHEMA_ERROR",
+  SQL_READONLY_VIOLATION: "SQL_READONLY_VIOLATION",
+  // Storage quota errors
+  STORAGE_QUOTA_EXCEEDED: "STORAGE_QUOTA_EXCEEDED",
+  STORAGE_LIMIT_REACHED: "STORAGE_LIMIT_REACHED",
+  /** The node answered the usage read without usage numbers (it predates the read). */
+  STORAGE_STATUS_UNAVAILABLE: "STORAGE_STATUS_UNAVAILABLE",
+  // DuckDB-specific errors
+  DUCKDB_ERROR: "DUCKDB_ERROR",
+  DUCKDB_PERMISSION_DENIED: "DUCKDB_PERMISSION_DENIED",
+  DUCKDB_DATABASE_NOT_FOUND: "DUCKDB_DATABASE_NOT_FOUND",
+  DUCKDB_RESPONSE_TOO_LARGE: "DUCKDB_RESPONSE_TOO_LARGE",
+  DUCKDB_QUOTA_EXCEEDED: "DUCKDB_QUOTA_EXCEEDED",
+  DUCKDB_INVALID_STATEMENT: "DUCKDB_INVALID_STATEMENT",
+  DUCKDB_SCHEMA_ERROR: "DUCKDB_SCHEMA_ERROR",
+  DUCKDB_READONLY_VIOLATION: "DUCKDB_READONLY_VIOLATION"
+};
+var defaultRetryPolicy = {
+  maxAttempts: 4,
+  backoff: "exponential",
+  baseDelayMs: 250,
+  maxDelayMs: 4e3,
+  retryableErrors: [ErrorCodes.NODE_BUSY, ErrorCodes.REQUEST_TIMEOUT],
+  maxTotalMs: 12e3
+};
+function ok(data) {
+  return { ok: true, data };
+}
+function err(error) {
+  return { ok: false, error };
+}
+
+// src/feed/schemas.ts
+var import_zod = require("zod");
+function isJSONValue(value, active = /* @__PURE__ */ new Set()) {
+  if (value === null || typeof value === "boolean" || typeof value === "string") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (typeof value !== "object" || active.has(value)) return false;
+  if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) return false;
+  active.add(value);
+  let valid = true;
+  for (const child of Array.isArray(value) ? value : Object.values(value)) {
+    if (!isJSONValue(child, active)) {
+      valid = false;
+      break;
+    }
+  }
+  active.delete(value);
+  return valid;
+}
+var jsonValueSchema = import_zod.z.custom((value) => isJSONValue(value));
+var feedResponsePayloadSchema = import_zod.z.object({
+  type: import_zod.z.string().min(1),
+  version: import_zod.z.number().int().positive(),
+  data: jsonValueSchema
+}).strict();
+var identity = {
+  cardId: import_zod.z.string().min(1),
+  revision: import_zod.z.number().int().positive(),
+  issuanceId: import_zod.z.string().min(1)
+};
+var feedCardSchema = import_zod.z.object({
+  ...identity,
+  kind: import_zod.z.string().min(1),
+  needsResponse: import_zod.z.boolean(),
+  title: import_zod.z.string(),
+  body: import_zod.z.string(),
+  choices: import_zod.z.array(import_zod.z.object({ id: import_zod.z.string().min(1), label: import_zod.z.string() })).optional(),
+  urgency: import_zod.z.number().finite(),
+  createdAt: import_zod.z.string().min(1),
+  payload: import_zod.z.record(import_zod.z.unknown()).optional()
+});
+var newFeedResponseSchema = import_zod.z.object({
+  ...identity,
+  responseId: import_zod.z.string().min(1),
+  kind: import_zod.z.enum(["answer", "followup"]),
+  choiceId: import_zod.z.string().min(1).optional(),
+  text: import_zod.z.string().optional(),
+  supersedesResponseId: import_zod.z.string().min(1).optional(),
+  createdAt: import_zod.z.string().min(1)
+});
+var newFeedMessageSchema = import_zod.z.object({
+  ...identity,
+  responseId: import_zod.z.string().min(1),
+  kind: import_zod.z.literal("message"),
+  text: import_zod.z.string(),
+  createdAt: import_zod.z.string().min(1)
+}).strict();
+var feedResponseHeaderSchema = import_zod.z.union([newFeedResponseSchema, newFeedMessageSchema]);
+var feedHandlingSchema = import_zod.z.object({
+  ...identity,
+  handlingId: import_zod.z.string().min(1),
+  responseId: import_zod.z.string().min(1),
+  phase: import_zod.z.enum(["acknowledged", "succeeded", "failed"]),
+  createdAt: import_zod.z.string().min(1),
+  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 = {
+    responseId: response.responseId,
+    cardId: response.cardId,
+    revision: response.revision,
+    issuanceId: response.issuanceId,
+    kind: response.kind,
+    createdAt: response.createdAt,
+    sequence: response.sequence
+  };
+  if (response.kind !== "message" && response.choiceId !== void 0) notification.choiceId = response.choiceId;
+  if (response.text !== void 0) notification.text = response.text;
+  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;
+};
+
+// src/feed/store.ts
+var PRIVATE_RESPONSE_OPTIONS = { redactErrors: true };
+function feedError(code, message) {
+  return err({ code, message, service: "feed" });
+}
+function feedJson(value) {
+  return JSON.stringify(value, (_key, item) => {
+    if (item && typeof item === "object" && !Array.isArray(item)) {
+      const sorted = /* @__PURE__ */ Object.create(null);
+      for (const key of Object.keys(item).sort()) sorted[key] = item[key];
+      return sorted;
+    }
+    return item;
+  });
+}
+function validIdentity(identity2) {
+  return typeof identity2.cardId === "string" && identity2.cardId.length > 0 && Number.isSafeInteger(identity2.revision) && identity2.revision > 0 && typeof identity2.issuanceId === "string" && identity2.issuanceId.length > 0;
+}
+function sameFeedIdentity(a, b) {
+  return a.cardId === b.cardId && a.revision === b.revision && a.issuanceId === b.issuanceId;
+}
+async function jsonRows(db, sql, params = [], options) {
+  const result = await db.query(sql, params, options);
+  if (!result.ok) return result;
+  try {
+    return ok(result.data.rows.map((row) => JSON.parse(row[0])));
+  } catch {
+    return feedError("INVALID_INPUT", "Feed record contains invalid JSON");
+  }
+}
+var RESPONSE_HEADER_SELECT = `SELECT r.sequence, r.response_json, p.payload_type, p.payload_version
+  FROM feed_responses r LEFT JOIN feed_response_payloads p ON p.response_id = r.response_id`;
+function responseDataFailure(message, error) {
+  let code = ErrorCodes.SQL_ERROR;
+  if (error !== null && typeof error === "object" && "code" in error) {
+    const candidate = error.code;
+    if (typeof candidate === "string" && Object.values(ErrorCodes).some((known) => known === candidate)) code = candidate;
+  }
+  return feedError(code, message);
+}
+function responseFromRow(row) {
+  return responseFromHeader(row, feedResponseHeaderSchema.parse(JSON.parse(String(row[1]))));
+}
+function responseFromHeader(row, header) {
+  const response = { ...header, sequence: Number(row[0]) };
+  if (row[2] !== null && row[2] !== void 0) {
+    response.payloadType = String(row[2]);
+    response.payloadVersion = Number(row[3]);
+  }
+  return projectFeedResponseNotification(response);
+}
+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], 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, rawHeaderJson: String(row[1]), headerJson: feedJson(header), payload });
+  } catch (error) {
+    return responseDataFailure("Could not read the saved feed response", error);
+  }
+}
+var initializeFeedDatabases = async ({ output, responses }) => {
+  const initialized = await output.batch([
+    { sql: `CREATE TABLE IF NOT EXISTS feed_cards (
+      sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+      card_id TEXT NOT NULL, revision INTEGER NOT NULL CHECK (revision > 0), issuance_id TEXT NOT NULL,
+      card_json TEXT NOT NULL, UNIQUE (card_id, revision, issuance_id)
+    )` },
+    { sql: `CREATE TABLE IF NOT EXISTS feed_handling (
+      sequence INTEGER PRIMARY KEY AUTOINCREMENT, handling_id TEXT NOT NULL UNIQUE,
+      response_id TEXT NOT NULL, card_id TEXT NOT NULL, revision INTEGER NOT NULL, issuance_id TEXT NOT NULL,
+      phase TEXT NOT NULL CHECK (phase IN ('acknowledged', 'succeeded', 'failed')),
+      handling_json TEXT NOT NULL
+    )` },
+    { sql: "CREATE INDEX IF NOT EXISTS feed_handling_response ON feed_handling (response_id, sequence)" }
+  ]);
+  if (!initialized.ok) return initialized;
+  const responseSchema = await responses.batch([
+    { sql: `CREATE TABLE IF NOT EXISTS feed_responses (
+      sequence INTEGER PRIMARY KEY AUTOINCREMENT, response_id TEXT NOT NULL UNIQUE,
+      card_id TEXT NOT NULL, revision INTEGER NOT NULL, issuance_id TEXT NOT NULL,
+      response_json TEXT NOT NULL
+    )` },
+    { 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 = (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],
+    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],
+    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`);
+};
+var appendFeedResponse = async (output, responses, input, payload) => {
+  try {
+    const header = newFeedResponseSchema.safeParse(input);
+    if (!header.success) return feedError("INVALID_INPUT", "Invalid feed response header");
+    return appendResponse(output, responses, header.data, payload);
+  } catch {
+    return feedError("INVALID_INPUT", "Invalid feed response header");
+  }
+};
+var appendFeedMessage = async (output, responses, input, payload) => {
+  try {
+    const header = newFeedMessageSchema.safeParse(input);
+    if (!header.success) return feedError("INVALID_INPUT", "Invalid feed message header");
+    return appendResponse(output, responses, header.data, payload);
+  } catch {
+    return feedError("INVALID_INPUT", "Invalid feed message header");
+  }
+};
+async function appendResponse(output, responses, response, inputPayload) {
+  let payload;
+  try {
+    if (inputPayload !== void 0) {
+      const parsed = feedResponsePayloadSchema.safeParse(inputPayload);
+      if (!parsed.success) return feedError("INVALID_INPUT", "Invalid private feed response payload");
+      payload = parsed.data;
+    }
+  } catch {
+    return feedError("INVALID_INPUT", "Invalid feed response or private payload");
+  }
+  try {
+    const cards = await jsonRows(
+      output,
+      "SELECT card_json FROM feed_cards WHERE card_id = ? AND revision = ? AND issuance_id = ?",
+      [response.cardId, response.revision, response.issuanceId],
+      PRIVATE_RESPONSE_OPTIONS
+    );
+    if (!cards.ok) return responseDataFailure("Could not verify the response card issuance", cards.error);
+    const card = cards.data[0];
+    if (!card || !sameFeedIdentity(card, response)) {
+      return feedError("INVALID_INPUT", "The response does not identify a published card issuance");
+    }
+    if (response.kind !== "message") {
+      if (!card.needsResponse) {
+        return feedError("INVALID_INPUT", "The response does not identify a published actionable card issuance");
+      }
+      if (response.choiceId !== void 0 && !card.choices?.some((choice) => choice.id === response.choiceId)) {
+        return feedError("INVALID_INPUT", "The response choice is not part of this card issuance");
+      }
+      if (response.supersedesResponseId) {
+        const previous = await jsonRows(
+          responses,
+          "SELECT response_json FROM feed_responses WHERE response_id = ?",
+          [response.supersedesResponseId],
+          PRIVATE_RESPONSE_OPTIONS
+        );
+        if (!previous.ok) return responseDataFailure("Could not verify the corrected response", previous.error);
+        if (!previous.data[0] || !sameFeedIdentity(previous.data[0], response)) {
+          return feedError("INVALID_INPUT", "A correction must reference a response to the same card issuance");
+        }
+      }
+    }
+    const encoded = feedJson(response);
+    const match = (stored) => {
+      const samePayload = payload === void 0 ? stored.payload === void 0 : stored.payload !== void 0 && feedJson(stored.payload) === feedJson(payload);
+      return stored.headerJson === encoded && samePayload ? ok(stored.response) : feedError("INVALID_INPUT", "A response ID cannot be reused for different header or private payload content");
+    };
+    const existing = await storedResponse(responses, response.responseId);
+    if (!existing.ok) return existing;
+    if (existing.data) return match(existing.data);
+    const statements = [{
+      sql: "INSERT INTO feed_responses (response_id, card_id, revision, issuance_id, response_json) VALUES (?, ?, ?, ?, ?)",
+      params: [response.responseId, response.cardId, response.revision, response.issuanceId, encoded]
+    }];
+    if (payload !== void 0) statements.push({
+      sql: "INSERT INTO feed_response_payloads (response_id, payload_type, payload_version, payload_json) VALUES (?, ?, ?, ?)",
+      params: [response.responseId, payload.type, payload.version, feedJson(payload.data)]
+    });
+    let failed = false;
+    let failure;
+    try {
+      const saved = await responses.batch(statements, PRIVATE_RESPONSE_OPTIONS);
+      if (!saved.ok) {
+        failed = true;
+        failure = saved.error;
+      }
+    } catch (error) {
+      failed = true;
+      failure = error;
+    }
+    const committed = await storedResponse(responses, response.responseId);
+    if (!committed.ok) return failed ? responseDataFailure("Could not save the feed response and private payload", failure) : committed;
+    if (!committed.data) return responseDataFailure("Could not save the feed response and private payload", failure);
+    return match(committed.data);
+  } catch (error) {
+    return responseDataFailure("Could not save the feed response and private payload", error);
+  }
+}
+var readFeedResponsePayload = async (responses, identity2) => {
+  if (!validIdentity(identity2) || typeof identity2.responseId !== "string" || !identity2.responseId) {
+    return feedError("INVALID_INPUT", "A private payload read requires the full response and card identity");
+  }
+  try {
+    const result = await responses.query(
+      `SELECT 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 = ? AND r.card_id = ? AND r.revision = ? AND r.issuance_id = ?`,
+      [identity2.responseId, identity2.cardId, identity2.revision, identity2.issuanceId],
+      PRIVATE_RESPONSE_OPTIONS
+    );
+    if (!result.ok) return responseDataFailure("Could not read the private feed response payload", result.error);
+    const row = result.data.rows[0];
+    if (!row) return feedError("NOT_FOUND", "The response identity does not match a saved response");
+    if (row[0] === null || row[0] === void 0) return ok(void 0);
+    const parsed = feedResponsePayloadSchema.safeParse({ type: row[0], version: Number(row[1]), data: JSON.parse(String(row[2])) });
+    return parsed.success ? ok(parsed.data) : feedError("INVALID_INPUT", "The saved private response payload is invalid");
+  } catch (error) {
+    return responseDataFailure("Could not read the private feed response payload", error);
+  }
+};
+var listFeedResponses = async (responses, options = {}) => {
+  const after = options.afterSequence ?? 0;
+  const limit = options.limit ?? 100;
+  if (!Number.isSafeInteger(after) || after < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > 1e3) {
+    return feedError("INVALID_INPUT", "Response pagination requires a nonnegative sequence and limit between 1 and 1000");
+  }
+  try {
+    const result = await responses.query(
+      `${RESPONSE_HEADER_SELECT} WHERE r.sequence > ? ORDER BY r.sequence LIMIT ?`,
+      [after, limit],
+      { ...PRIVATE_RESPONSE_OPTIONS, signal: options.signal }
+    );
+    if (!result.ok) return responseDataFailure("Could not list feed responses", result.error);
+    return ok(result.data.rows.map(responseFromRow));
+  } catch (error) {
+    return responseDataFailure("Could not list feed responses", error);
+  }
+};
+var recordFeedHandling = async (output, handling) => {
+  if (!validIdentity(handling) || !handling.handlingId || !handling.responseId || !["acknowledged", "succeeded", "failed"].includes(handling.phase)) {
+    return feedError("INVALID_INPUT", "Handling requires full response and card identities and a known phase");
+  }
+  const previous = await jsonRows(
+    output,
+    "SELECT handling_json FROM feed_handling WHERE response_id = ? ORDER BY sequence",
+    [handling.responseId]
+  );
+  if (!previous.ok) return previous;
+  if (previous.data.some((item) => !sameFeedIdentity(item, handling))) {
+    return feedError("INVALID_INPUT", "Handling cannot move a response to another card issuance");
+  }
+  const encoded = feedJson(handling);
+  const duplicate = previous.data.find((item) => item.handlingId === handling.handlingId);
+  if (duplicate) {
+    return feedJson(duplicate) === encoded ? ok(duplicate) : feedError("INVALID_INPUT", "A handling ID cannot change content");
+  }
+  const knownOutcome = previous.data.find((item) => item.phase !== "acknowledged");
+  if (knownOutcome && handling.phase !== "acknowledged") {
+    return feedError("INVALID_INPUT", "An existing outcome requires an explicit follow-up response, not a replacement");
+  }
+  const inserted = await output.execute(
+    `INSERT INTO feed_handling (handling_id, response_id, card_id, revision, issuance_id, phase, handling_json)
+     SELECT ?, ?, ?, ?, ?, ?, ?
+     WHERE NOT EXISTS (
+       SELECT 1 FROM feed_handling WHERE response_id = ? AND (card_id <> ? OR revision <> ? OR issuance_id <> ?)
+     ) AND (? = 'acknowledged' OR NOT EXISTS (
+       SELECT 1 FROM feed_handling WHERE response_id = ? AND phase IN ('succeeded', 'failed')
+     )) ON CONFLICT (handling_id) DO NOTHING`,
+    [
+      handling.handlingId,
+      handling.responseId,
+      handling.cardId,
+      handling.revision,
+      handling.issuanceId,
+      handling.phase,
+      encoded,
+      handling.responseId,
+      handling.cardId,
+      handling.revision,
+      handling.issuanceId,
+      handling.phase,
+      handling.responseId
+    ]
+  );
+  if (!inserted.ok) return inserted;
+  const stored = await jsonRows(
+    output,
+    "SELECT handling_json FROM feed_handling WHERE handling_id = ?",
+    [handling.handlingId]
+  );
+  if (!stored.ok) return stored;
+  if (!stored.data[0]) return feedError("INVALID_INPUT", "Handling conflicts with an existing outcome or response issuance");
+  return feedJson(stored.data[0]) === encoded ? ok(stored.data[0]) : feedError("INVALID_INPUT", "A handling ID cannot change content");
+};
+async function selectResponseHandling(output, identity2) {
+  const records = await jsonRows(
+    output,
+    `SELECT handling_json FROM feed_handling WHERE response_id = ? AND card_id = ? AND revision = ? AND issuance_id = ?
+     ORDER BY sequence`,
+    [identity2.responseId, identity2.cardId, identity2.revision, identity2.issuanceId]
+  );
+  if (!records.ok) return records;
+  if (records.data.length === 0) return ok(void 0);
+  const handling = { acknowledgement: null, outcome: null };
+  for (const item of records.data) {
+    if (item.responseId !== identity2.responseId || !sameFeedIdentity(item, identity2)) {
+      return feedError("INVALID_INPUT", "Stored handling does not match the response identity");
+    }
+    if (item.phase === "acknowledged") handling.acknowledgement = item;
+    else if (item.phase === "succeeded" || item.phase === "failed") handling.outcome = item;
+    else return feedError("INVALID_INPUT", "Stored handling has an unknown phase");
+  }
+  return ok(handling);
+}
+var readFeedResponseHandling = async (output, identity2) => {
+  if (!validIdentity(identity2) || typeof identity2.responseId !== "string" || !identity2.responseId) {
+    return feedError("INVALID_INPUT", "Handling reads require full response and card identities");
+  }
+  const handling = await selectResponseHandling(output, identity2);
+  if (!handling.ok) return handling;
+  return handling.data ? ok(handling.data) : feedError("NOT_FOUND", "Matching response handling not found");
+};
+var getFeedCardState = async (output, responses, identity2) => {
+  const params = [identity2.cardId, identity2.revision, identity2.issuanceId];
+  const cards = await jsonRows(
+    output,
+    "SELECT card_json FROM feed_cards WHERE card_id = ? AND revision = ? AND issuance_id = ?",
+    params
+  );
+  if (!cards.ok) return cards;
+  if (!cards.data[0]) return feedError("NOT_FOUND", "Card issuance not found");
+  const saved = await responses.query(
+    `${RESPONSE_HEADER_SELECT} WHERE r.card_id = ? AND r.revision = ? AND r.issuance_id = ?
+       AND json_extract(r.response_json, '$.kind') IN ('answer', 'followup')
+     ORDER BY r.sequence DESC LIMIT 1`,
+    params,
+    PRIVATE_RESPONSE_OPTIONS
+  );
+  if (!saved.ok) return responseDataFailure("Could not read the card's saved response", saved.error);
+  const row = saved.data.rows[0];
+  let response;
+  try {
+    response = row ? responseFromRow(row) : null;
+  } catch (error) {
+    return responseDataFailure("Could not read the card's saved response", error);
+  }
+  const handling = response ? await selectResponseHandling(output, response) : ok(void 0);
+  if (!handling.ok) return handling;
+  return ok({
+    card: cards.data[0],
+    response,
+    acknowledgement: handling.data?.acknowledgement ?? null,
+    outcome: handling.data?.outcome ?? null
+  });
+};
+var resolveFeedCard = async (output, reference) => {
+  if (!reference) return feedError("INVALID_INPUT", "A card reference is required");
+  const rows = await output.query(
+    `SELECT card_id, revision, issuance_id FROM feed_cards
+     WHERE card_id = ? ORDER BY sequence DESC LIMIT 1`,
+    [reference]
+  );
+  if (!rows.ok) return rows;
+  let row = rows.data.rows[0];
+  if (!row) {
+    const matches = await output.query(
+      `SELECT card_id, revision, issuance_id FROM feed_cards
+       WHERE substr(card_id, 1, length(?)) = ? AND sequence IN
+       (SELECT MAX(sequence) FROM feed_cards GROUP BY card_id) LIMIT 2`,
+      [reference, reference]
+    );
+    if (!matches.ok) return matches;
+    if (matches.data.rows.length !== 1) return feedError("NOT_FOUND", "Card reference is absent or ambiguous; use its full ID");
+    row = matches.data.rows[0];
+  }
+  return ok({ cardId: String(row[0]), revision: Number(row[1]), issuanceId: String(row[2]) });
+};
+
+// src/feed/handoff.ts
+var initializeFeedHandoff = async (handoff) => {
+  const result = await handoff.execute(`CREATE TABLE IF NOT EXISTS feed_handoffs (
+    response_id TEXT NOT NULL, recipient TEXT NOT NULL, response_json TEXT NOT NULL,
+    state TEXT NOT NULL CHECK (state IN ('prepared', 'unconfirmed', 'delivered')),
+    PRIMARY KEY (response_id, recipient)
+  )`);
+  return result.ok ? ok(void 0) : result;
+};
+var getFeedHandoff = async (handoff, responseId, recipient) => {
+  const result = await handoff.query(
+    "SELECT response_json, state FROM feed_handoffs WHERE response_id = ? AND recipient = ?",
+    [responseId, recipient]
+  );
+  if (!result.ok) return result;
+  const row = result.data.rows[0];
+  if (!row) return ok(null);
+  try {
+    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`,
+    [response.responseId, recipient, feedJson(response)]
+  );
+  if (!inserted.ok) return inserted;
+  const existing = await getFeedHandoff(handoff, response.responseId, recipient);
+  if (!existing.ok) return existing;
+  if (!existing.data || feedJson(existing.data.response) !== feedJson(response)) {
+    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]
+  );
+  if (!claimed.ok) return claimed;
+  if (claimed.data.changes === 0) {
+    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);
+    if (delivered === "delivered") state = "delivered";
+  } catch {
+  }
+  if (state === "delivered") {
+    const saved = await handoff.execute(
+      "UPDATE feed_handoffs SET state = 'delivered' WHERE response_id = ? AND recipient = ? AND state = 'unconfirmed'",
+      [response.responseId, recipient]
+    );
+    if (!saved.ok) return saved;
+  }
+  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;
+  const renewalSeconds = options.renewalSeconds ?? 300;
+  if (!Number.isInteger(renewalSeconds) || renewalSeconds < 60 || renewalSeconds > 300) {
+    throw new Error("Feed renewal must be between 60 and 300 seconds");
+  }
+  if (options.subscription.service !== "sql" || !options.subscription.pathPrefix) {
+    throw new Error("Feed listener requires the exact response SQL resource subscription");
+  }
+  if (signal.aborted) return;
+  const initialized = await initializeFeedHandoff(options.handoff);
+  if (!initialized.ok) throw initialized.error;
+  let ready = false;
+  let dirty = false;
+  let draining;
+  let failed = false;
+  let failure;
+  let current;
+  const drain = async () => {
+    do {
+      dirty = false;
+      let afterSequence = 0;
+      while (!signal.aborted) {
+        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.responses) {
+          if (signal.aborted) return;
+          const handoff = await deliverFeedResponse({
+            handoff: options.handoff,
+            recipient: options.recipient,
+            response,
+            deliver: options.deliver
+          });
+          if (!handoff.ok && !isDispatchDeadlineFailure(handoff.error)) throw handoff.error;
+        }
+        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);
+  };
+  const schedule = () => {
+    if (!ready || signal.aborted || failed) return;
+    dirty = true;
+    if (draining) return;
+    draining = drain().catch((error) => {
+      failed = true;
+      failure = error;
+      current?.abort();
+    }).finally(() => {
+      draining = void 0;
+      if (dirty && !failed) schedule();
+    });
+  };
+  while (!signal.aborted && !failed) {
+    const connection = new AbortController();
+    current = connection;
+    const stop = () => connection.abort();
+    signal.addEventListener("abort", stop, { once: true });
+    const renewal = setTimeout(stop, renewalSeconds * 1e3);
+    renewal.unref?.();
+    try {
+      for await (const _event of options.hooks.subscribe([options.subscription], {
+        signal: connection.signal,
+        ttlSeconds: renewalSeconds,
+        onReady: () => {
+          if (current !== connection || connection.signal.aborted || signal.aborted) return;
+          ready = true;
+          schedule();
+        }
+      })) schedule();
+    } finally {
+      ready = false;
+      clearTimeout(renewal);
+      signal.removeEventListener("abort", stop);
+      await draining;
+    }
+    if (failed) throw failure;
+    if (!connection.signal.aborted) return;
+  }
+  if (failed) throw failure;
+};
+
+// src/feed/resources.ts
+var feedResourceNames = (prefix, stableToken) => {
+  if (!/^[A-Za-z0-9_-]+$/.test(stableToken) || !prefix || prefix.endsWith("/") || prefix.split("/").some((part) => !part || part === "." || part === ".." || !/^[A-Za-z0-9._-]+$/.test(part))) {
+    return feedError("INVALID_INPUT", "Feed resources require a canonical prefix and a stable alphanumeric, underscore or hyphen agent token");
+  }
+  return ok({
+    outputResource: `${prefix}/feed_output_${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,
+  appendFeedResponse,
+  deliverFeedResponse,
+  feedCardSchema,
+  feedHandlingSchema,
+  feedResourceNames,
+  feedResponsePayloadSchema,
+  getFeedCardState,
+  getFeedHandoff,
+  initializeFeedDatabases,
+  initializeFeedHandoff,
+  listFeedCardHistory,
+  listFeedCards,
+  listFeedResponseDeliveries,
+  listFeedResponses,
+  listenFeedResponses,
+  newFeedMessageSchema,
+  newFeedResponseSchema,
+  projectFeedResponseNotification,
+  publishFeedCard,
+  readFeedResponseHandling,
+  readFeedResponsePayload,
+  recordFeedHandling,
+  resolveFeedCard,
+  restoreFeedRecords
+});
+//# sourceMappingURL=index.cjs.map