@adonis-agora/agent 0.76.3 → 0.77.0

package/dist/src/poppy/store.d.ts

@@ -0,0 +1,207 @@
+import type { LucidClientLike, LucidRawRunner } from '../stores/lucid.js';
+import type { Actor } from '../types.js';
+import type { PoppyContext, PoppyEvent, PoppyEventBody, PoppyResponder, PoppyStatus } from './protocol.js';
+/**
+ * A Poppy conversation as this surface keeps it. It belongs to a Personal Agent (`clientId`) and
+ * one of its Users (`userId`); once it used an account here, to that account too (`accountRef`,
+ * §7.2). The agent side of it is an agent thread (`threadId`) — a Direct Conversation shares its
+ * parent's thread, which is how the Company Agent knows what was said in either (§7.10).
+ */
+export interface PoppyConversationRecord {
+    id: string;
+    clientId: string;
+    userId: string;
+    accountRef: string | null;
+    agentName: string;
+    threadId: string | null;
+    /** Set on a Direct Conversation: the conversation it was opened from. */
+    parentId: string | null;
+    /** On a parent: its open Direct Conversation. */
+    openDirectId: string | null;
+    status: PoppyStatus;
+    responder: PoppyResponder;
+    /** The User's context as last shared — fields a message leaves out keep their value (§7.4). */
+    context: PoppyContext;
+    /** The run whose reply is being written, while there is one. */
+    activeRunId: string | null;
+    /**
+     * The position of the last message event a turn has taken up. The event log IS the turn queue:
+     * user messages after it are what the next turn answers — on whichever replica picks it up.
+     */
+    turnSeq: number;
+    /** Who the latest request came as — what the next turn runs as. */
+    grant: PoppyGrant | null;
+    /** Events at or below this sequence number were pruned: a cursor there is `cursor_expired`. */
+    prunedSeq: number;
+    createdAt: number;
+    updatedAt: number;
+}
+/** The identity a conversation's turns run as: that of its latest request (§7.11). */
+export interface PoppyGrant {
+    actor: Actor;
+    /** The token's account scopes; empty when signed out. */
+    scopes: string[];
+    signedIn: boolean;
+}
+export type PoppyConversationPatch = Partial<Pick<PoppyConversationRecord, 'accountRef' | 'threadId' | 'openDirectId' | 'status' | 'responder' | 'context' | 'activeRunId' | 'turnSeq' | 'grant' | 'prunedSeq'>>;
+/** An event with its position in the conversation. */
+export interface StoredPoppyEvent {
+    seq: number;
+    event: PoppyEvent;
+}
+/** What an accepted message keeps for its retries (§7.3). */
+export interface PoppyMessageReceipt {
+    fingerprint: string;
+    conversationId: string;
+    /** The HTTP status and body the first delivery got. */
+    response: {
+        status: number;
+        body: Record<string, unknown>;
+    };
+}
+export type PoppyMessageClaim = {
+    status: 'claimed';
+} | ({
+    status: 'existing';
+} & PoppyMessageReceipt);
+/**
+ * Where conversations, their events and message receipts live. Events are append-only and read by
+ * position, so a cursor replays exactly what came after it, on any replica.
+ *
+ * @experimental Tracks Personal Agent Protocol Draft 0.1 (https://personalagentprotocol.org/docs/spec),
+ * a spec still in development: this API WILL change as the spec evolves — possibly in breaking
+ * ways, outside semver majors while it is a draft.
+ */
+export interface PoppyStore {
+    createConversation(record: PoppyConversationRecord): Promise<void>;
+    getConversation(id: string): Promise<PoppyConversationRecord | null>;
+    updateConversation(id: string, patch: PoppyConversationPatch): Promise<void>;
+    /**
+     * Append an event, numbered after the conversation's last. With `key`, at most one event per key
+     * is ever appended: a second append answers the first event with `created: false` — what keeps a
+     * re-read turn from writing its reply twice.
+     */
+    appendEvent(conversationId: string, body: PoppyEventBody, options?: {
+        key?: string;
+    }): Promise<{
+        event: StoredPoppyEvent;
+        created: boolean;
+    }>;
+    /** Events after `afterSeq`, in order, at most `limit`. */
+    listEvents(conversationId: string, afterSeq: number, limit: number): Promise<StoredPoppyEvent[]>;
+    /** The position of an event, `null` when the conversation has no such event (any more). */
+    findEventSeq(conversationId: string, eventId: string): Promise<number | null>;
+    /** Drop the events created before `before` (epoch ms), keeping at least the last one. */
+    pruneEvents(conversationId: string, before: number): Promise<void>;
+    /** Claim `messageId` for `owner` — atomically, so two deliveries of one message are one. */
+    claimMessage(owner: string, messageId: string, receipt: PoppyMessageReceipt): Promise<PoppyMessageClaim>;
+    /** Drop a claim whose message could not be taken, so its retry is processed afresh. */
+    releaseMessage(owner: string, messageId: string): Promise<void>;
+    /**
+     * Take (or renew) the right to write the reply of the conversation's active run for `ttlMs` —
+     * `false` while another holder's lease is live. What lets any replica pick up a reply whose
+     * writer died, without two writing it at once.
+     */
+    leaseReader(conversationId: string, holder: string, ttlMs: number): Promise<boolean>;
+    releaseReader(conversationId: string, holder: string): Promise<void>;
+}
+/** `evt_<seq in base 36>_<random>`: unique, and its position survives the event being pruned. */
+export declare function newEventId(seq: number): string;
+/** The position an event id was minted at, or `null` for an id this surface never minted. */
+export declare function eventIdSeq(id: string): number | null;
+/** Process-local {@link PoppyStore} — tests and single-instance dev. */
+export declare class InMemoryPoppyStore implements PoppyStore {
+    #private;
+    createConversation(record: PoppyConversationRecord): Promise<void>;
+    getConversation(id: string): Promise<PoppyConversationRecord | null>;
+    updateConversation(id: string, patch: PoppyConversationPatch): Promise<void>;
+    appendEvent(conversationId: string, body: PoppyEventBody, options?: {
+        key?: string;
+    }): Promise<{
+        event: {
+            seq: number;
+            event: PoppyEvent;
+        };
+        created: boolean;
+    }>;
+    listEvents(conversationId: string, afterSeq: number, limit: number): Promise<{
+        seq: number;
+        event: PoppyEvent;
+    }[]>;
+    findEventSeq(conversationId: string, eventId: string): Promise<number | null>;
+    pruneEvents(conversationId: string, before: number): Promise<void>;
+    claimMessage(owner: string, messageId: string, receipt: PoppyMessageReceipt): Promise<{
+        fingerprint: string;
+        conversationId: string;
+        /** The HTTP status and body the first delivery got. */
+        response: {
+            status: number;
+            body: Record<string, unknown>;
+        };
+        status: 'existing';
+    } | {
+        status: 'claimed';
+    }>;
+    releaseMessage(owner: string, messageId: string): Promise<void>;
+    leaseReader(conversationId: string, holder: string, ttlMs: number): Promise<boolean>;
+    releaseReader(conversationId: string, holder: string): Promise<void>;
+}
+export declare const POPPY_TABLES: {
+    readonly conversations: 'agent_poppy_conversation';
+    readonly events: 'agent_poppy_event';
+    readonly messages: 'agent_poppy_message';
+};
+/**
+ * `CREATE TABLE IF NOT EXISTS` DDL for the Poppy tables — the agent tables' portable dialect
+ * (quoted identifiers, epoch-ms `BIGINT`, `TEXT` JSON; `forDialect` adapts it to MySQL). An event's
+ * primary key is its position, so two appends racing for one position cannot both win; a message's
+ * is its (owner, id), the idempotency lock of §7.3.
+ */
+export declare function poppyTableStatements(): string[];
+/** Create the Poppy tables if missing. Idempotent. */
+export declare function ensurePoppyTables(db: LucidRawRunner): Promise<void>;
+export interface LucidPoppyStoreOptions {
+    /** Create the tables on first use (`CREATE TABLE IF NOT EXISTS`). Default `true`. */
+    autoCreateTables?: boolean;
+}
+/** {@link PoppyStore} over Lucid (any of SQLite / Postgres / MySQL). */
+export declare class LucidPoppyStore implements PoppyStore {
+    #private;
+    private readonly db;
+    constructor(db: LucidClientLike & LucidRawRunner, options?: LucidPoppyStoreOptions);
+    /** Provision the tables (once). A failure is retried on the next call. */
+    ready(): Promise<void>;
+    createConversation(record: PoppyConversationRecord): Promise<void>;
+    getConversation(id: string): Promise<PoppyConversationRecord | null>;
+    updateConversation(id: string, patch: PoppyConversationPatch): Promise<void>;
+    appendEvent(conversationId: string, body: PoppyEventBody, options?: {
+        key?: string;
+    }): Promise<{
+        event: {
+            seq: number;
+            event: PoppyEvent;
+        };
+        created: boolean;
+    }>;
+    listEvents(conversationId: string, afterSeq: number, limit: number): Promise<{
+        seq: number;
+        event: PoppyEvent;
+    }[]>;
+    findEventSeq(conversationId: string, eventId: string): Promise<number | null>;
+    pruneEvents(conversationId: string, before: number): Promise<void>;
+    claimMessage(owner: string, messageId: string, receipt: PoppyMessageReceipt): Promise<{
+        status: 'claimed';
+        fingerprint?: never;
+        conversationId?: never;
+        response?: never;
+    } | {
+        status: 'existing';
+        fingerprint: string;
+        conversationId: string;
+        response: PoppyMessageReceipt['response'];
+    }>;
+    releaseMessage(owner: string, messageId: string): Promise<void>;
+    leaseReader(conversationId: string, holder: string, ttlMs: number): Promise<boolean>;
+    releaseReader(conversationId: string, holder: string): Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/src/poppy/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/poppy/store.ts"],"names":[],"mappings":"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"}

package/dist/src/poppy/store.js

@@ -0,0 +1,444 @@
+import { randomBytes } from 'node:crypto';
+import { forDialect } from '../stores/lucid-schema.js';
+import { isMySql } from '../stores/sql-dialect.js';
+/** `evt_<seq in base 36>_<random>`: unique, and its position survives the event being pruned. */
+export function newEventId(seq) {
+    return `evt_${seq.toString(36)}_${randomBytes(6).toString('base64url')}`;
+}
+/** The position an event id was minted at, or `null` for an id this surface never minted. */
+export function eventIdSeq(id) {
+    const match = /^evt_([0-9a-z]{1,11})_[A-Za-z0-9_-]+$/.exec(id);
+    if (!match?.[1])
+        return null;
+    const seq = Number.parseInt(match[1], 36);
+    return Number.isSafeInteger(seq) && seq > 0 ? seq : null;
+}
+function toEvent(seq, body, now) {
+    return {
+        seq,
+        event: { id: newEventId(seq), created_at: new Date(now).toISOString(), ...body },
+    };
+}
+// ── In memory ─────────────────────────────────────────────────────────────────
+/** Process-local {@link PoppyStore} — tests and single-instance dev. */
+export class InMemoryPoppyStore {
+    #conversations = new Map();
+    #events = new Map();
+    #messages = new Map();
+    #leases = new Map();
+    async createConversation(record) {
+        this.#conversations.set(record.id, structuredClone(record));
+    }
+    async getConversation(id) {
+        const found = this.#conversations.get(id);
+        return found ? structuredClone(found) : null;
+    }
+    async updateConversation(id, patch) {
+        const found = this.#conversations.get(id);
+        if (!found)
+            return;
+        Object.assign(found, structuredClone(patch), { updatedAt: Date.now() });
+    }
+    async appendEvent(conversationId, body, options = {}) {
+        const list = this.#events.get(conversationId) ?? [];
+        this.#events.set(conversationId, list);
+        if (options.key !== undefined) {
+            const existing = list.find((entry) => entry.key === options.key);
+            if (existing) {
+                return { event: { seq: existing.seq, event: existing.event }, created: false };
+            }
+        }
+        const conversation = this.#conversations.get(conversationId);
+        const last = list.at(-1)?.seq ?? conversation?.prunedSeq ?? 0;
+        const stored = toEvent(last + 1, body, Date.now());
+        list.push({ ...stored, key: options.key ?? null });
+        return { event: structuredClone(stored), created: true };
+    }
+    async listEvents(conversationId, afterSeq, limit) {
+        return (this.#events.get(conversationId) ?? [])
+            .filter((entry) => entry.seq > afterSeq)
+            .slice(0, limit)
+            .map((entry) => structuredClone({ seq: entry.seq, event: entry.event }));
+    }
+    async findEventSeq(conversationId, eventId) {
+        return ((this.#events.get(conversationId) ?? []).find((entry) => entry.event.id === eventId)?.seq ??
+            null);
+    }
+    async pruneEvents(conversationId, before) {
+        const list = this.#events.get(conversationId) ?? [];
+        const cutoff = new Date(before).toISOString();
+        const last = list.at(-1);
+        const keep = list.filter((entry) => entry === last || entry.event.created_at >= cutoff);
+        const dropped = list.filter((entry) => !keep.includes(entry));
+        if (dropped.length === 0)
+            return;
+        this.#events.set(conversationId, keep);
+        const conversation = this.#conversations.get(conversationId);
+        if (conversation) {
+            conversation.prunedSeq = Math.max(conversation.prunedSeq, ...dropped.map((e) => e.seq));
+        }
+    }
+    async claimMessage(owner, messageId, receipt) {
+        const key = `${owner}\n${messageId}`;
+        const found = this.#messages.get(key);
+        if (found)
+            return { status: 'existing', ...structuredClone(found) };
+        this.#messages.set(key, structuredClone(receipt));
+        return { status: 'claimed' };
+    }
+    async releaseMessage(owner, messageId) {
+        this.#messages.delete(`${owner}\n${messageId}`);
+    }
+    async leaseReader(conversationId, holder, ttlMs) {
+        const now = Date.now();
+        const lease = this.#leases.get(conversationId);
+        if (lease && lease.holder !== holder && lease.until > now)
+            return false;
+        this.#leases.set(conversationId, { holder, until: now + ttlMs });
+        return true;
+    }
+    async releaseReader(conversationId, holder) {
+        if (this.#leases.get(conversationId)?.holder === holder)
+            this.#leases.delete(conversationId);
+    }
+}
+// ── Lucid ─────────────────────────────────────────────────────────────────────
+export const POPPY_TABLES = {
+    conversations: 'agent_poppy_conversation',
+    events: 'agent_poppy_event',
+    messages: 'agent_poppy_message',
+};
+/**
+ * `CREATE TABLE IF NOT EXISTS` DDL for the Poppy tables — the agent tables' portable dialect
+ * (quoted identifiers, epoch-ms `BIGINT`, `TEXT` JSON; `forDialect` adapts it to MySQL). An event's
+ * primary key is its position, so two appends racing for one position cannot both win; a message's
+ * is its (owner, id), the idempotency lock of §7.3.
+ */
+export function poppyTableStatements() {
+    const t = POPPY_TABLES;
+    return [
+        `CREATE TABLE IF NOT EXISTS "${t.conversations}" (
+      "id" VARCHAR(255) PRIMARY KEY NOT NULL,
+      "client_id" VARCHAR(2048) NOT NULL,
+      "user_id" VARCHAR(255) NOT NULL,
+      "account_ref" VARCHAR(255) NULL,
+      "agent_name" VARCHAR(255) NOT NULL,
+      "thread_id" VARCHAR(255) NULL,
+      "parent_id" VARCHAR(255) NULL,
+      "open_direct_id" VARCHAR(255) NULL,
+      "status" VARCHAR(16) NOT NULL,
+      "responder" VARCHAR(16) NOT NULL,
+      "context" TEXT NULL,
+      "active_run_id" VARCHAR(255) NULL,
+      "turn_seq" BIGINT NOT NULL,
+      "grant_info" TEXT NULL,
+      "reader_holder" VARCHAR(255) NULL,
+      "reader_until" BIGINT NULL,
+      "pruned_seq" BIGINT NOT NULL,
+      "created_at" BIGINT NOT NULL,
+      "updated_at" BIGINT NOT NULL
+    )`,
+        `CREATE TABLE IF NOT EXISTS "${t.events}" (
+      "conversation_id" VARCHAR(255) NOT NULL,
+      "seq" BIGINT NOT NULL,
+      "id" VARCHAR(64) NOT NULL,
+      "type" VARCHAR(64) NOT NULL,
+      "event" TEXT NOT NULL,
+      "event_key" VARCHAR(255) NULL,
+      "created_at" BIGINT NOT NULL,
+      PRIMARY KEY ("conversation_id", "seq")
+    )`,
+        `CREATE TABLE IF NOT EXISTS "${t.messages}" (
+      "owner" VARCHAR(64) NOT NULL,
+      "message_id" VARCHAR(256) NOT NULL,
+      "fingerprint" VARCHAR(64) NOT NULL,
+      "conversation_id" VARCHAR(255) NOT NULL,
+      "response" TEXT NOT NULL,
+      "created_at" BIGINT NOT NULL,
+      PRIMARY KEY ("owner", "message_id")
+    )`,
+    ];
+}
+/** Create the Poppy tables if missing. Idempotent. */
+export async function ensurePoppyTables(db) {
+    const mysql = isMySql(db);
+    for (const statement of poppyTableStatements()) {
+        await db.rawQuery(forDialect(statement, mysql));
+    }
+}
+function toInt(value) {
+    if (typeof value === 'number')
+        return value;
+    if (typeof value === 'bigint')
+        return Number(value);
+    if (typeof value === 'string')
+        return Number.parseInt(value, 10) || 0;
+    return 0;
+}
+const nullable = (value) => (value == null ? null : String(value));
+const PATCH_COLUMNS = {
+    accountRef: 'account_ref',
+    threadId: 'thread_id',
+    openDirectId: 'open_direct_id',
+    status: 'status',
+    responder: 'responder',
+    context: 'context',
+    activeRunId: 'active_run_id',
+    turnSeq: 'turn_seq',
+    grant: 'grant_info',
+    prunedSeq: 'pruned_seq',
+};
+/** {@link PoppyStore} over Lucid (any of SQLite / Postgres / MySQL). */
+export class LucidPoppyStore {
+    db;
+    #ready = null;
+    #autoCreate;
+    constructor(db, options = {}) {
+        this.db = db;
+        this.#autoCreate = options.autoCreateTables ?? true;
+    }
+    /** Provision the tables (once). A failure is retried on the next call. */
+    ready() {
+        if (!this.#autoCreate)
+            return Promise.resolve();
+        if (this.#ready === null) {
+            this.#ready = ensurePoppyTables(this.db);
+            this.#ready.catch(() => {
+                this.#ready = null;
+            });
+        }
+        return this.#ready;
+    }
+    async createConversation(record) {
+        await this.ready();
+        await this.db.table(POPPY_TABLES.conversations).insert({
+            id: record.id,
+            client_id: record.clientId,
+            user_id: record.userId,
+            account_ref: record.accountRef,
+            agent_name: record.agentName,
+            thread_id: record.threadId,
+            parent_id: record.parentId,
+            open_direct_id: record.openDirectId,
+            status: record.status,
+            responder: record.responder,
+            context: JSON.stringify(record.context),
+            active_run_id: record.activeRunId,
+            turn_seq: record.turnSeq,
+            grant_info: record.grant === null ? null : JSON.stringify(record.grant),
+            reader_holder: null,
+            reader_until: null,
+            pruned_seq: record.prunedSeq,
+            created_at: record.createdAt,
+            updated_at: record.updatedAt,
+        });
+    }
+    async getConversation(id) {
+        await this.ready();
+        const row = await this.db.from(POPPY_TABLES.conversations).where('id', id).first();
+        if (!row)
+            return null;
+        return {
+            id: String(row.id),
+            clientId: String(row.client_id),
+            userId: String(row.user_id),
+            accountRef: nullable(row.account_ref),
+            agentName: String(row.agent_name),
+            threadId: nullable(row.thread_id),
+            parentId: nullable(row.parent_id),
+            openDirectId: nullable(row.open_direct_id),
+            status: String(row.status),
+            responder: String(row.responder),
+            context: row.context == null ? {} : JSON.parse(String(row.context)),
+            activeRunId: nullable(row.active_run_id),
+            turnSeq: toInt(row.turn_seq),
+            grant: row.grant_info == null ? null : JSON.parse(String(row.grant_info)),
+            prunedSeq: toInt(row.pruned_seq),
+            createdAt: toInt(row.created_at),
+            updatedAt: toInt(row.updated_at),
+        };
+    }
+    async updateConversation(id, patch) {
+        await this.ready();
+        const row = { updated_at: Date.now() };
+        for (const [key, column] of Object.entries(PATCH_COLUMNS)) {
+            const value = patch[key];
+            if (value === undefined)
+                continue;
+            row[column] =
+                key === 'context' || (key === 'grant' && value !== null) ? JSON.stringify(value) : value;
+        }
+        await this.db.from(POPPY_TABLES.conversations).where('id', id).update(row);
+    }
+    async appendEvent(conversationId, body, options = {}) {
+        await this.ready();
+        for (let attempt = 0;; attempt++) {
+            if (options.key !== undefined) {
+                const existing = await this.db
+                    .from(POPPY_TABLES.events)
+                    .where('conversation_id', conversationId)
+                    .where('event_key', options.key)
+                    .first();
+                if (existing) {
+                    return {
+                        event: {
+                            seq: toInt(existing.seq),
+                            event: JSON.parse(String(existing.event)),
+                        },
+                        created: false,
+                    };
+                }
+            }
+            const last = await this.db
+                .from(POPPY_TABLES.events)
+                .where('conversation_id', conversationId)
+                .orderBy('seq', 'desc')
+                .limit(1)
+                .first();
+            const floor = last === null
+                ? ((await this.getConversation(conversationId))?.prunedSeq ?? 0)
+                : toInt(last.seq);
+            const now = Date.now();
+            const stored = toEvent(floor + 1, body, now);
+            try {
+                await this.db.table(POPPY_TABLES.events).insert({
+                    conversation_id: conversationId,
+                    seq: stored.seq,
+                    id: stored.event.id,
+                    type: body.type,
+                    event: JSON.stringify(stored.event),
+                    event_key: options.key ?? null,
+                    created_at: now,
+                });
+                return { event: stored, created: true };
+            }
+            catch (error) {
+                // Another append took this position first: number this one after it.
+                if (attempt >= 20)
+                    throw error;
+            }
+        }
+    }
+    async listEvents(conversationId, afterSeq, limit) {
+        await this.ready();
+        const rows = await this.db
+            .from(POPPY_TABLES.events)
+            .where('conversation_id', conversationId)
+            .where('seq', '>', afterSeq)
+            .orderBy('seq', 'asc')
+            .limit(limit)
+            .select('seq', 'event');
+        return rows.map((row) => ({
+            seq: toInt(row.seq),
+            event: JSON.parse(String(row.event)),
+        }));
+    }
+    async findEventSeq(conversationId, eventId) {
+        await this.ready();
+        const row = await this.db
+            .from(POPPY_TABLES.events)
+            .where('conversation_id', conversationId)
+            .where('id', eventId)
+            .first();
+        return row ? toInt(row.seq) : null;
+    }
+    async pruneEvents(conversationId, before) {
+        await this.ready();
+        const last = await this.db
+            .from(POPPY_TABLES.events)
+            .where('conversation_id', conversationId)
+            .orderBy('seq', 'desc')
+            .limit(1)
+            .first();
+        if (!last)
+            return;
+        const dropped = await this.db
+            .from(POPPY_TABLES.events)
+            .where('conversation_id', conversationId)
+            .where('created_at', '<', before)
+            .where('seq', '<', toInt(last.seq))
+            .orderBy('seq', 'desc')
+            .limit(1)
+            .first();
+        if (!dropped)
+            return;
+        const upTo = toInt(dropped.seq);
+        await this.db
+            .from(POPPY_TABLES.events)
+            .where('conversation_id', conversationId)
+            .where('seq', '<=', upTo)
+            .delete();
+        const conversation = await this.getConversation(conversationId);
+        if (conversation && conversation.prunedSeq < upTo) {
+            await this.updateConversation(conversationId, { prunedSeq: upTo });
+        }
+    }
+    async claimMessage(owner, messageId, receipt) {
+        await this.ready();
+        try {
+            await this.db.table(POPPY_TABLES.messages).insert({
+                owner,
+                message_id: messageId,
+                fingerprint: receipt.fingerprint,
+                conversation_id: receipt.conversationId,
+                response: JSON.stringify(receipt.response),
+                created_at: Date.now(),
+            });
+            return { status: 'claimed' };
+        }
+        catch (error) {
+            const row = await this.db
+                .from(POPPY_TABLES.messages)
+                .where('owner', owner)
+                .where('message_id', messageId)
+                .first();
+            if (!row)
+                throw error;
+            return {
+                status: 'existing',
+                fingerprint: String(row.fingerprint),
+                conversationId: String(row.conversation_id),
+                response: JSON.parse(String(row.response)),
+            };
+        }
+    }
+    async releaseMessage(owner, messageId) {
+        await this.ready();
+        await this.db
+            .from(POPPY_TABLES.messages)
+            .where('owner', owner)
+            .where('message_id', messageId)
+            .delete();
+    }
+    async leaseReader(conversationId, holder, ttlMs) {
+        await this.ready();
+        const now = Date.now();
+        const row = await this.db.from(POPPY_TABLES.conversations).where('id', conversationId).first();
+        if (!row)
+            return false;
+        const current = nullable(row.reader_holder);
+        if (current !== null && current !== holder && toInt(row.reader_until) > now)
+            return false;
+        // Compare-and-set on what was read: of two takers, the second matches nothing.
+        let query = this.db.from(POPPY_TABLES.conversations).where('id', conversationId);
+        query =
+            current === null
+                ? query.whereNull('reader_holder')
+                : query.where('reader_holder', current).where('reader_until', toInt(row.reader_until));
+        await query.update({ reader_holder: holder, reader_until: now + ttlMs });
+        const after = await this.db
+            .from(POPPY_TABLES.conversations)
+            .where('id', conversationId)
+            .first();
+        return nullable(after?.reader_holder) === holder;
+    }
+    async releaseReader(conversationId, holder) {
+        await this.ready();
+        await this.db
+            .from(POPPY_TABLES.conversations)
+            .where('id', conversationId)
+            .where('reader_holder', holder)
+            .update({ reader_holder: null, reader_until: null });
+    }
+}
+//# sourceMappingURL=store.js.map