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

package/dist/feed/index.js

@@ -0,0 +1,739 @@
+// 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
+import { z } from "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 = z.custom((value) => isJSONValue(value));
+var feedResponsePayloadSchema = z.object({
+  type: z.string().min(1),
+  version: z.number().int().positive(),
+  data: jsonValueSchema
+}).strict();
+var identity = {
+  cardId: z.string().min(1),
+  revision: z.number().int().positive(),
+  issuanceId: z.string().min(1)
+};
+var feedCardSchema = z.object({
+  ...identity,
+  kind: z.string().min(1),
+  needsResponse: z.boolean(),
+  title: z.string(),
+  body: z.string(),
+  choices: z.array(z.object({ id: z.string().min(1), label: z.string() })).optional(),
+  urgency: z.number().finite(),
+  createdAt: z.string().min(1),
+  payload: z.record(z.unknown()).optional()
+});
+var newFeedResponseSchema = z.object({
+  ...identity,
+  responseId: z.string().min(1),
+  kind: z.enum(["answer", "followup"]),
+  choiceId: z.string().min(1).optional(),
+  text: z.string().optional(),
+  supersedesResponseId: z.string().min(1).optional(),
+  createdAt: z.string().min(1)
+});
+var newFeedMessageSchema = z.object({
+  ...identity,
+  responseId: z.string().min(1),
+  kind: z.literal("message"),
+  text: z.string(),
+  createdAt: z.string().min(1)
+}).strict();
+var feedResponseHeaderSchema = z.union([newFeedResponseSchema, newFeedMessageSchema]);
+var feedHandlingSchema = z.object({
+  ...identity,
+  handlingId: z.string().min(1),
+  responseId: z.string().min(1),
+  phase: z.enum(["acknowledged", "succeeded", "failed"]),
+  createdAt: z.string().min(1),
+  detail: z.record(z.unknown()).optional()
+});
+
+// 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;
+  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) {
+  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);
+    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 });
+  } 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
+    )` }
+  ]);
+  return responseSchema.ok ? ok(void 0) : responseSchema;
+};
+var publishFeedCard = async (output, card) => {
+  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]
+  );
+  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]
+  );
+  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 {
+    return ok({ responseId, recipient, response: projectFeedResponseNotification(JSON.parse(row[0])), state: row[1] });
+  } catch {
+    return feedError("INVALID_INPUT", "Handoff contains invalid response JSON");
+  }
+};
+var deliverFeedResponse = async ({ handoff, recipient, response: input, deliver }) => {
+  const response = projectFeedResponseNotification(input);
+  if (!recipient || !response.responseId) return feedError("INVALID_INPUT", "Handoff requires a recipient and full response ID");
+  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);
+  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;
+  }
+  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/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 listFeedResponses(options.responses, { 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) {
+          if (signal.aborted) return;
+          const handoff = await deliverFeedResponse({
+            handoff: options.handoff,
+            recipient: options.recipient,
+            response,
+            deliver: options.deliver
+          });
+          if (!handoff.ok) throw handoff.error;
+          afterSequence = response.sequence;
+        }
+        if (page.data.length < 100) 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}`
+  });
+};
+export {
+  appendFeedMessage,
+  appendFeedResponse,
+  deliverFeedResponse,
+  feedCardSchema,
+  feedHandlingSchema,
+  feedResourceNames,
+  feedResponsePayloadSchema,
+  getFeedCardState,
+  getFeedHandoff,
+  initializeFeedDatabases,
+  initializeFeedHandoff,
+  listFeedCards,
+  listFeedResponses,
+  listenFeedResponses,
+  newFeedMessageSchema,
+  newFeedResponseSchema,
+  projectFeedResponseNotification,
+  publishFeedCard,
+  readFeedResponseHandling,
+  readFeedResponsePayload,
+  recordFeedHandling,
+  resolveFeedCard
+};
+//# sourceMappingURL=index.js.map