@nurix/nustack 0.23.4 → 0.23.5

package/dist/lib/local_store/migrations.js

@@ -235,6 +235,80 @@ const MIGRATION_V8 = {
         `CREATE UNIQUE INDEX record_store_idempotency_key_unique ON record_store (idempotency_key)`,
     ],
 };
+const V9_LEGACY_BOOKKEEPING_ORIGIN = "'session:legacy-bookkeeping'";
+const V9_BOOKKEEPING_ORIGIN = `(CASE WHEN json_type(row_json, '$.planAnchor') = 'text'
+    THEN 'plan:' || json_extract(row_json, '$.planAnchor') ELSE ${V9_LEGACY_BOOKKEEPING_ORIGIN} END)`;
+const V9_NEW_KIND = `(CASE kind WHEN 'backlog.remove' THEN 'backlog' WHEN 'bookkeeping' THEN 'obligation' ELSE kind END)`;
+const V9_NATURAL_KEY = `COALESCE(CASE kind
+    WHEN 'bookkeeping' THEN ${V9_BOOKKEEPING_ORIGIN} || '#documentation:' || json_extract(row_json, '$.anchor')
+    ELSE json_extract(row_json, '$.anchor') END, '')`;
+const V9_PAYLOAD = `(CASE kind
+    WHEN 'backlog' THEN json_remove(row_json, '$.idempotencyKey', '$.planAnchor')
+    WHEN 'backlog.remove' THEN json_set(json_remove(row_json, '$.idempotencyKey', '$.planAnchor'), '$.state', 'removed')
+    WHEN 'bookkeeping' THEN (CASE WHEN json_type(row_json, '$.text') = 'text'
+        THEN json_object('origin', ${V9_BOOKKEEPING_ORIGIN}, 'type', 'documentation',
+            'subject', json_extract(row_json, '$.anchor'), 'claim', json_extract(row_json, '$.text'), 'state', 'open')
+        ELSE json_object('origin', ${V9_BOOKKEEPING_ORIGIN}, 'type', 'documentation',
+            'subject', json_extract(row_json, '$.anchor'), 'state', 'open') END)
+    ELSE json_remove(row_json, '$.idempotencyKey') END)`;
+const V9_SOURCE = `(
+    SELECT id, project_id, repository_root, NULL AS door_url, 0 AS attempts, NULL AS next_attempt_at,
+        NULL AS last_error, created_at_ms, updated_at_ms, json_extract(row_json, '$.planAnchor') AS plan_anchor,
+        ${V9_NEW_KIND} AS new_kind, ${V9_NATURAL_KEY} AS natural_key, ${V9_PAYLOAD} AS payload_json
+    FROM record_store
+    UNION ALL
+    SELECT id, project_id, NULL AS repository_root, NULLIF(door_url, '') AS door_url, attempts,
+        next_retry_at_ms AS next_attempt_at, last_error, created_at_ms, updated_at_ms,
+        json_extract(row_json, '$.planAnchor') AS plan_anchor,
+        ${V9_NEW_KIND} AS new_kind, ${V9_NATURAL_KEY} AS natural_key, ${V9_PAYLOAD} AS payload_json
+    FROM record_outbox
+)`;
+const V9_KEY = `COALESCE(project_id, repository_root) || ':' || new_kind || ':' || natural_key`;
+const MIGRATION_V9 = {
+    version: 9,
+    statements: [
+        `CREATE TABLE records (
+            id TEXT PRIMARY KEY,
+            kind TEXT NOT NULL,
+            schema_version INTEGER NOT NULL,
+            project_id TEXT,
+            session_id TEXT,
+            plan_anchor TEXT,
+            natural_key TEXT NOT NULL,
+            idempotency_key TEXT NOT NULL,
+            payload_json TEXT NOT NULL CHECK (json_valid(payload_json)),
+            sync_state TEXT NOT NULL,
+            attempts INTEGER NOT NULL DEFAULT 0,
+            next_attempt_at INTEGER,
+            last_error TEXT,
+            created_at INTEGER NOT NULL,
+            repository_root TEXT,
+            door_url TEXT,
+            placement TEXT,
+            credential TEXT
+        )`,
+        `CREATE UNIQUE INDEX records_idempotency_key_unique ON records (idempotency_key)`,
+        `CREATE INDEX records_sync_state_next_attempt_idx ON records (sync_state, next_attempt_at)`,
+        `INSERT OR REPLACE INTO records (id, kind, schema_version, project_id, session_id, plan_anchor, natural_key,
+            idempotency_key, payload_json, sync_state, attempts, next_attempt_at, last_error, created_at,
+            repository_root, door_url, placement, credential)
+         SELECT id, new_kind, 1, project_id, NULL, plan_anchor, natural_key, ${V9_KEY}, payload_json, 'pending',
+            attempts, next_attempt_at, last_error, created_at_ms, repository_root, door_url, NULL, NULL
+         FROM ${V9_SOURCE}
+         ORDER BY created_at_ms, updated_at_ms`,
+        `CREATE TEMP TABLE records_v9_guard (shortfall INTEGER NOT NULL CONSTRAINT records_v9_guard CHECK (shortfall = 0))`,
+        `INSERT INTO records_v9_guard SELECT count(*) FROM records
+            WHERE kind = 'backlog' AND json_extract(payload_json, '$.anchor') IS NULL`,
+        `INSERT INTO records_v9_guard SELECT count(*) FROM records
+            WHERE kind = 'obligation' AND (json_extract(payload_json, '$.origin') IS NULL
+                OR json_extract(payload_json, '$.subject') IS NULL OR json_extract(payload_json, '$.state') IS NULL)`,
+        `INSERT INTO records_v9_guard SELECT
+            (SELECT count(DISTINCT ${V9_KEY}) FROM ${V9_SOURCE}) - (SELECT count(*) FROM records)`,
+        `DROP TABLE records_v9_guard`,
+        `DROP TABLE record_outbox`,
+        `DROP TABLE record_store`,
+    ],
+};
 export const MIGRATIONS = [
     MIGRATION_V1,
     MIGRATION_V2,
@@ -244,6 +318,7 @@ export const MIGRATIONS = [
     MIGRATION_V6,
     MIGRATION_V7,
     MIGRATION_V8,
+    MIGRATION_V9,
 ];
 export const LATEST_SCHEMA_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;
 export class LocalSchemaTooNewError extends Error {
@@ -269,6 +344,10 @@ export function migrateToLatest(db) {
         if (migration.version <= current)
             continue;
         db.exec("BEGIN IMMEDIATE");
+        if (readUserVersion(db) >= migration.version) {
+            db.exec("COMMIT");
+            continue;
+        }
         try {
             for (const statement of migration.statements) {
                 db.exec(statement);

package/dist/lib/local_store/paths.js

@@ -10,6 +10,12 @@ export function stateDbPath() {
 export function locksDir() {
     return path.join(nustackHomeDir(), "locks");
 }
+export function recordsDrainLockPath() {
+    return path.join(locksDir(), "records-drain.lock");
+}
+export function desktopSettingsPath() {
+    return path.join(nustackHomeDir(), "desktop-settings.json");
+}
 export function cacheDir() {
     return path.join(nustackHomeDir(), "cache");
 }

package/dist/lib/records/door.js

@@ -1,22 +1,28 @@
-import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { ensureAccessToken } from "../auth_grant.js";
 import { resolveNuStackUrl } from "../nustack_client.js";
 import { resolveProjectId } from "../project_context.js";
-export const RECORD_KINDS = ["backlog", "backlog.remove", "bookkeeping", "gate_event"];
+export const RECORD_KINDS = ["obligation", "gate_event", "changelog", "memory", "backlog", "proposal", "triage"];
+export const LEGACY_KIND_TRANSLATION = { "backlog.remove": "backlog", bookkeeping: "obligation" };
 export const RECORDS_BATCH_CAP = 200;
+export const RECORD_SCHEMA_VERSION = 1;
 const REQUEST_TIMEOUT_MS = 10_000;
 const RETRY_BASE_MS = 30_000;
 const RETRY_CEILING_MS = 60 * 60 * 1000;
 export function isRecordKind(value) {
     return typeof value === "string" && RECORD_KINDS.includes(value);
 }
-export function idempotencyKeyOf(project, kind, anchor) {
-    return `${project}:${kind}:${anchor}`;
+export function isLegacyKind(value) {
+    return typeof value === "string" && Object.hasOwn(LEGACY_KIND_TRANSLATION, value);
 }
-async function readMountDoor(root) {
+export function isEmitKind(value) {
+    return isRecordKind(value) || isLegacyKind(value);
+}
+export function translatedKindOf(kind) {
+    return isLegacyKind(kind) ? LEGACY_KIND_TRANSLATION[kind] : kind;
+}
+export async function readMountDoor(root) {
     const manifest = path.join(root, ".claude", "harness.json");
     if (!existsSync(manifest))
         return undefined;
@@ -40,184 +46,27 @@ export async function resolveDoor(root, globals, projectFlag) {
         return { kind: "store", projectId: project.projectId, root, reason: "the harness manifest configures no door" };
     return { kind: "door", projectId: project.projectId, doorUrl: door ?? resolveNuStackUrl(globals), isPlatformDefault: door === undefined, root };
 }
-export class DoorRefusedError extends Error {
+export function retryDelayMs(attempts) {
+    return Math.min(RETRY_BASE_MS * 2 ** Math.max(0, attempts - 1), RETRY_CEILING_MS);
 }
-export async function postRecords(doorUrl, projectId, kind, rows) {
-    const auth = await ensureAccessToken().catch(() => null);
-    if (!auth)
-        throw new DoorRefusedError("this device is signed out");
+export async function postRecords(doorUrl, projectId, request, bearer) {
     let response;
     try {
         response = await fetch(`${doorUrl}/api/v2/projects/${encodeURIComponent(projectId)}/records`, {
             method: "POST",
-            headers: { "content-type": "application/json", authorization: `Bearer ${auth.accessToken}` },
-            body: JSON.stringify({ kind, rows }),
+            headers: { "content-type": "application/json", authorization: `Bearer ${bearer}` },
+            body: JSON.stringify(request),
             signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
         });
     }
     catch (error) {
-        throw new DoorRefusedError(`the door did not answer: ${error instanceof Error ? error.message : String(error)}`);
+        return { ok: false, status: 0, code: null, message: `the door did not answer: ${error instanceof Error ? error.message : String(error)}` };
     }
-    const payload = (await response.json().catch(() => null));
+    const body = (await response.json().catch(() => null));
     if (!response.ok) {
-        const detail = payload?.error?.message ?? `HTTP ${response.status}`;
-        throw new DoorRefusedError(`${payload?.error?.code ?? `HTTP ${response.status}`}: ${detail}`);
-    }
-    return { landed: payload?.data?.landed ?? 0, skipped: payload?.data?.skipped ?? 0 };
-}
-function outboxOf(row) {
-    return {
-        id: row.id,
-        projectId: row.project_id,
-        kind: row.kind,
-        idempotencyKey: row.idempotency_key,
-        doorUrl: row.door_url,
-        row: JSON.parse(row.row_json),
-        attempts: row.attempts,
-        nextRetryAtMs: row.next_retry_at_ms ?? null,
-        lastError: row.last_error ?? null,
-        createdAtMs: row.created_at_ms,
-    };
-}
-function storedOf(row) {
-    return {
-        id: row.id,
-        projectId: row.project_id ?? null,
-        repositoryRoot: row.repository_root,
-        kind: row.kind,
-        idempotencyKey: row.idempotency_key,
-        row: JSON.parse(row.row_json),
-        createdAtMs: row.created_at_ms,
-    };
-}
-export function retryDelayMs(attempts) {
-    return Math.min(RETRY_BASE_MS * 2 ** Math.max(0, attempts - 1), RETRY_CEILING_MS);
-}
-export function enqueueOutbox(store, input) {
-    const now = Date.now();
-    const key = idempotencyKeyOf(input.projectId, input.kind, input.row.anchor);
-    store.db
-        .prepare(`INSERT INTO record_outbox (id, project_id, kind, idempotency_key, door_url, row_json, attempts,
-                next_retry_at_ms, last_error, created_at_ms, updated_at_ms)
-             VALUES (:id, :project_id, :kind, :key, :door_url, :row_json, 1, :next_retry_at_ms, :last_error, :now, :now)
-             ON CONFLICT(idempotency_key) DO UPDATE SET
-                row_json = excluded.row_json, door_url = excluded.door_url, attempts = 1,
-                next_retry_at_ms = excluded.next_retry_at_ms, last_error = excluded.last_error,
-                created_at_ms = excluded.created_at_ms, updated_at_ms = excluded.updated_at_ms`)
-        .run({
-        id: randomUUID(),
-        project_id: input.projectId,
-        kind: input.kind,
-        key,
-        door_url: input.doorUrl,
-        row_json: JSON.stringify({ ...input.row, idempotencyKey: key }),
-        next_retry_at_ms: now + retryDelayMs(1),
-        last_error: input.error,
-        now,
-    });
-    return outboxOf(store.db.prepare("SELECT * FROM record_outbox WHERE idempotency_key = ?").get(key));
-}
-export function keepInStore(store, input) {
-    const now = Date.now();
-    const key = idempotencyKeyOf(input.projectId ?? input.root, input.kind, input.row.anchor);
-    store.db
-        .prepare(`INSERT INTO record_store (id, project_id, repository_root, kind, idempotency_key, row_json, created_at_ms, updated_at_ms)
-             VALUES (:id, :project_id, :root, :kind, :key, :row_json, :now, :now)
-             ON CONFLICT(idempotency_key) DO UPDATE SET row_json = excluded.row_json, created_at_ms = excluded.created_at_ms,
-                updated_at_ms = excluded.updated_at_ms`)
-        .run({
-        id: randomUUID(),
-        project_id: input.projectId,
-        root: input.root,
-        kind: input.kind,
-        key,
-        row_json: JSON.stringify({ ...input.row, idempotencyKey: key }),
-        now,
-    });
-    return storedOf(store.db.prepare("SELECT * FROM record_store WHERE idempotency_key = ?").get(key));
-}
-export function listOutbox(store, projectId) {
-    const rows = projectId
-        ? store.db.prepare("SELECT * FROM record_outbox WHERE project_id = ? ORDER BY created_at_ms ASC, rowid ASC").all(projectId)
-        : store.db.prepare("SELECT * FROM record_outbox ORDER BY created_at_ms ASC, rowid ASC").all();
-    return rows.map(outboxOf);
-}
-export function listStored(store, filter = {}) {
-    const rows = store.db.prepare("SELECT * FROM record_store ORDER BY created_at_ms ASC, rowid ASC").all();
-    return rows
-        .map(storedOf)
-        .filter((row) => (!filter.projectId || row.projectId === filter.projectId) && (!filter.root || row.repositoryRoot === filter.root));
-}
-export async function emitRecords(store, resolution, kind, rows) {
-    if (resolution.kind === "store") {
-        const kept = rows.map((row) => keepInStore(store, { projectId: resolution.projectId, root: resolution.root, kind, row }));
-        return { rung: 3, projectId: resolution.projectId, keys: kept.map((row) => row.idempotencyKey), reason: resolution.reason };
-    }
-    const { projectId, doorUrl } = resolution;
-    const parkedDoor = resolution.isPlatformDefault ? "" : doorUrl;
-    const keyed = rows.map((row) => ({ ...row, idempotencyKey: idempotencyKeyOf(projectId, kind, row.anchor) }));
-    const keys = keyed.map((row) => row.idempotencyKey);
-    try {
-        const result = await postRecords(doorUrl, projectId, kind, keyed);
-        return { rung: 1, projectId, keys, ...result };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        for (const row of rows)
-            enqueueOutbox(store, { projectId, kind, doorUrl: parkedDoor, row, error: message });
-        return { rung: 2, projectId, keys, error: message };
-    }
-}
-export async function drainOutbox(store, globals, options = {}) {
-    const now = Date.now();
-    let rows = listOutbox(store);
-    if (options.dueOnly)
-        rows = rows.filter((row) => row.nextRetryAtMs === null || row.nextRetryAtMs <= now);
-    if (options.limit !== undefined)
-        rows = rows.slice(0, options.limit);
-    let sent = 0;
-    let kept = 0;
-    let lastError = null;
-    for (const row of rows) {
-        try {
-            await postRecords(row.doorUrl || resolveNuStackUrl(globals), row.projectId, row.kind, [row.row]);
-            store.db.prepare("DELETE FROM record_outbox WHERE id = ?").run(row.id);
-            sent += 1;
-        }
-        catch (error) {
-            lastError = error instanceof Error ? error.message : String(error);
-            store.db
-                .prepare(`UPDATE record_outbox SET attempts = attempts + 1, next_retry_at_ms = ?, last_error = ?, updated_at_ms = ? WHERE id = ?`)
-                .run(Date.now() + retryDelayMs(row.attempts + 1), lastError, Date.now(), row.id);
-            kept += 1;
-        }
-    }
-    return { sent, kept, lastError };
-}
-export async function drainStore(store, globals) {
-    let sent = 0;
-    let kept = 0;
-    let lastError = null;
-    for (const row of listStored(store)) {
-        if (!existsSync(row.repositoryRoot)) {
-            kept += 1;
-            continue;
-        }
-        const door = await resolveDoor(row.repositoryRoot, globals);
-        if (door.kind !== "door") {
-            kept += 1;
-            continue;
-        }
-        const keyed = { ...row.row, idempotencyKey: idempotencyKeyOf(door.projectId, row.kind, row.row.anchor) };
-        try {
-            await postRecords(door.doorUrl, door.projectId, row.kind, [keyed]);
-            store.db.prepare("DELETE FROM record_store WHERE id = ?").run(row.id);
-            sent += 1;
-        }
-        catch (error) {
-            lastError = error instanceof Error ? error.message : String(error);
-            kept += 1;
-        }
+        const code = typeof body?.error?.code === "string" ? body.error.code : null;
+        const detail = typeof body?.error?.message === "string" ? body.error.message : `HTTP ${response.status}`;
+        return { ok: false, status: response.status, code, message: `${code ?? `HTTP ${response.status}`}: ${detail}` };
     }
-    return { sent, kept, lastError };
+    return { ok: true, landed: body?.data?.landed ?? 0, skipped: body?.data?.skipped ?? 0 };
 }

package/dist/lib/records/drain.js

@@ -0,0 +1,219 @@
+import { spawn } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, utimesSync, writeSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensureAccessToken } from "../auth_grant.js";
+import { recordsDrainLockPath } from "../local_store/paths.js";
+import { resolveNuStackUrl } from "../nustack_client.js";
+import { RECORDS_BATCH_CAP, postRecords, resolveDoor, retryDelayMs } from "./door.js";
+import { DEVICE_TOKEN_VARIABLE, DRAIN_CHILD_VARIABLE, NO_DETACHED_DRAIN_VARIABLE, isFlagSet, readVariable } from "./environment.js";
+import { envelopeOfStored } from "./recordInput.js";
+import { validateEnvelope } from "./recordValidator.js";
+import { OBLIGATION_AGENT_OWNED, markBackoff, markDeferred, markRefused, markSynced, pruneSynced, rekeyRecord, selectDueRecords, } from "./recordsTable.js";
+export const DRAIN_LOCK_STALE_MS = 120_000;
+const MAX_PASSES = 50;
+const DEVICE_PROJECTION_FIELDS = ["origin", "type", "subject", "state", "outcome", "ownerAgentDefinitionId"];
+function payloadToSend(row) {
+    const payload = JSON.parse(row.payloadJson);
+    if (row.placement !== "device" || row.kind !== "obligation")
+        return payload;
+    const projection = {};
+    for (const field of DEVICE_PROJECTION_FIELDS)
+        if (payload[field] !== undefined)
+            projection[field] = payload[field];
+    return projection;
+}
+async function targetOf(store, row, globals, doors) {
+    if (row.doorUrl !== null && row.projectId !== null)
+        return { row, doorUrl: row.doorUrl, projectId: row.projectId };
+    if (row.repositoryRoot !== null && existsSync(row.repositoryRoot)) {
+        let door = doors.get(row.repositoryRoot);
+        if (!door) {
+            door = await resolveDoor(row.repositoryRoot, globals);
+            doors.set(row.repositoryRoot, door);
+        }
+        if (door.kind !== "door")
+            return null;
+        if (row.projectId !== null)
+            return { row, doorUrl: door.doorUrl, projectId: row.projectId };
+        const rekeyed = rekeyRecord(store, row, door.projectId);
+        return rekeyed ? { row: rekeyed, doorUrl: door.doorUrl, projectId: door.projectId } : "gone";
+    }
+    if (row.projectId !== null)
+        return { row, doorUrl: resolveNuStackUrl(globals), projectId: row.projectId };
+    return null;
+}
+function isRowRefusal(outcome) {
+    return outcome.status === 400 || (outcome.status === 403 && outcome.code === OBLIGATION_AGENT_OWNED);
+}
+async function drainPass(store, globals, result, shouldIgnoreBackoff) {
+    const now = Date.now();
+    const deviceToken = readVariable(DEVICE_TOKEN_VARIABLE);
+    const due = selectDueRecords(store, shouldIgnoreBackoff ? Number.MAX_SAFE_INTEGER : now, deviceToken !== null);
+    if (due.length === 0)
+        return 0;
+    const doors = new Map();
+    const groups = new Map();
+    for (const selected of due) {
+        const target = await targetOf(store, selected, globals, doors);
+        if (target === "gone")
+            continue;
+        if (target === null) {
+            markDeferred(store, selected, now + retryDelayMs(Math.max(1, selected.attempts)));
+            continue;
+        }
+        const envelope = envelopeOfStored(target.row, target.projectId, payloadToSend(target.row));
+        const verdict = validateEnvelope(envelope);
+        if (!verdict.isValid) {
+            const error = `VALIDATION_FAILED: ${verdict.errors[0] ?? "the row fails the records schema"}`;
+            if (markRefused(store, target.row, error)) {
+                result.refused += 1;
+                result.lastError = error;
+            }
+            continue;
+        }
+        const group = `${target.row.credential ?? ""}\u0000${target.doorUrl}\u0000${target.projectId}\u0000${target.row.kind}`;
+        const list = groups.get(group) ?? [];
+        list.push({ row: target.row, envelope, doorUrl: target.doorUrl, projectId: target.projectId });
+        groups.set(group, list);
+    }
+    let personToken;
+    for (const list of groups.values()) {
+        const first = list[0];
+        let bearer;
+        if (first.row.credential === "device")
+            bearer = deviceToken;
+        else {
+            if (personToken === undefined)
+                personToken = (await ensureAccessToken().catch(() => null))?.accessToken ?? null;
+            bearer = personToken;
+        }
+        for (let start = 0; start < list.length; start += RECORDS_BATCH_CAP) {
+            const batch = list.slice(start, start + RECORDS_BATCH_CAP);
+            if (bearer === null) {
+                backoffAll(store, batch, "this device is signed out", result);
+                continue;
+            }
+            await sendBatch(store, batch, first.row.kind, bearer, result);
+        }
+    }
+    return due.length;
+}
+function backoffAll(store, batch, error, result) {
+    const now = Date.now();
+    for (const item of batch)
+        markBackoff(store, item.row, error, now + retryDelayMs(item.row.attempts + 1));
+    result.lastError = error;
+}
+async function sendBatch(store, batch, kind, bearer, result) {
+    const { doorUrl, projectId } = batch[0];
+    const outcome = await postRecords(doorUrl, projectId, { kind, rows: batch.map((item) => item.envelope) }, bearer);
+    if (outcome.ok) {
+        for (const item of batch)
+            markSynced(store, item.row);
+        result.sent += batch.length;
+        return;
+    }
+    if (!isRowRefusal(outcome)) {
+        backoffAll(store, batch, outcome.message, result);
+        return;
+    }
+    if (batch.length === 1) {
+        if (markRefused(store, batch[0].row, outcome.message))
+            result.refused += 1;
+        result.lastError = outcome.message;
+        return;
+    }
+    for (const item of batch) {
+        const alone = await postRecords(doorUrl, projectId, { kind, rows: [item.envelope] }, bearer);
+        if (alone.ok) {
+            markSynced(store, item.row);
+            result.sent += 1;
+        }
+        else if (isRowRefusal(alone)) {
+            if (markRefused(store, item.row, alone.message))
+                result.refused += 1;
+            result.lastError = alone.message;
+        }
+        else
+            backoffAll(store, [item], alone.message, result);
+    }
+}
+export async function drainRecords(store, globals, options = {}) {
+    const result = { sent: 0, refused: 0, lastError: null };
+    pruneSynced(store, Date.now());
+    for (let pass = 0; pass < MAX_PASSES; pass += 1) {
+        options.onPass?.();
+        if ((await drainPass(store, globals, result, pass === 0 && options.isForeground === true)) === 0)
+            break;
+    }
+    return result;
+}
+function tryCreateLock(lockPath) {
+    try {
+        const fd = openSync(lockPath, "wx", 0o600);
+        try {
+            writeSync(fd, String(process.pid));
+        }
+        finally {
+            closeSync(fd);
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function acquireDrainLock(lockPath = recordsDrainLockPath()) {
+    try {
+        mkdirSync(path.dirname(lockPath), { recursive: true, mode: 0o700 });
+    }
+    catch {
+        return false;
+    }
+    if (tryCreateLock(lockPath))
+        return true;
+    try {
+        if (Date.now() - statSync(lockPath).mtimeMs < DRAIN_LOCK_STALE_MS)
+            return false;
+        unlinkSync(lockPath);
+    }
+    catch {
+    }
+    return tryCreateLock(lockPath);
+}
+export function refreshDrainLock(lockPath = recordsDrainLockPath()) {
+    try {
+        const now = new Date();
+        utimesSync(lockPath, now, now);
+    }
+    catch {
+    }
+}
+export function releaseDrainLock(lockPath = recordsDrainLockPath()) {
+    try {
+        if (readFileSync(lockPath, "utf8") === String(process.pid))
+            unlinkSync(lockPath);
+    }
+    catch {
+    }
+}
+function cliEntryPath() {
+    return fileURLToPath(new URL("../../index.js", import.meta.url));
+}
+export function startDetachedDrain(options = {}) {
+    try {
+        if (isFlagSet(NO_DETACHED_DRAIN_VARIABLE) || isFlagSet(DRAIN_CHILD_VARIABLE))
+            return;
+        const args = [cliEntryPath(), ...(options.nustackUrl ? ["--nustack-url", options.nustackUrl] : []), "records", "sync", "--quiet"];
+        const child = spawn(process.execPath, args, {
+            detached: true,
+            stdio: "ignore",
+            env: { ...process.env, [DRAIN_CHILD_VARIABLE]: "1" },
+        });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+    }
+}

package/dist/lib/records/environment.js

@@ -0,0 +1,25 @@
+export const SESSION_ID_VARIABLE = "NUSTACK_SESSION_ID";
+export const AGENT_DEFINITION_ID_VARIABLE = "NUSTACK_AGENT_DEFINITION_ID";
+export const DRAIN_CHILD_VARIABLE = "NUSTACK_DRAIN_CHILD";
+export const NO_DETACHED_DRAIN_VARIABLE = "NUSTACK_NO_DETACHED_DRAIN";
+export const RECORD_CREDENTIAL_VARIABLE = "NUSTACK_RECORD_CREDENTIAL";
+export const DEVICE_TOKEN_VARIABLE = "NUSTACK_DEVICE_TOKEN";
+export const RECORDS_ENVIRONMENT_VARIABLES = [
+    SESSION_ID_VARIABLE,
+    AGENT_DEFINITION_ID_VARIABLE,
+    DRAIN_CHILD_VARIABLE,
+    NO_DETACHED_DRAIN_VARIABLE,
+    RECORD_CREDENTIAL_VARIABLE,
+    DEVICE_TOKEN_VARIABLE,
+];
+export function readVariable(name, env = process.env) {
+    const value = env[name]?.trim();
+    return value ? value : null;
+}
+export function isFlagSet(name, env = process.env) {
+    const value = readVariable(name, env);
+    return value !== null && value !== "0" && value.toLowerCase() !== "false";
+}
+export function recordCredentialOf(env = process.env) {
+    return readVariable(RECORD_CREDENTIAL_VARIABLE, env) === "device" ? "device" : null;
+}

package/dist/lib/records/naturalKey.js

@@ -0,0 +1,33 @@
+const field = (payload, name) => String(payload[name]);
+export function naturalKeyOf(kind, payload) {
+    switch (kind) {
+        case "obligation":
+            return `${field(payload, "origin")}#${field(payload, "type")}:${field(payload, "subject")}`;
+        case "gate_event":
+            return `event:${field(payload, "eventId")}`;
+        case "changelog":
+            return field(payload, "origin");
+        case "memory":
+            return `path:${field(payload, "path")}`;
+        case "backlog":
+            return field(payload, "anchor");
+        case "proposal":
+            return `${field(payload, "origin")}#${field(payload, "targetKind")}:${field(payload, "targetPath")}`;
+        case "triage":
+            return `${field(payload, "tracker")}:${field(payload, "itemRef")}`;
+    }
+    throw new Error(`unknown record kind: ${String(kind)}`);
+}
+export function idempotencyKeyOf(projectId, kind, naturalKey) {
+    return `${projectId}:${kind}:${naturalKey}`;
+}
+export function splitObligationKey(naturalKey) {
+    const hash = naturalKey.indexOf("#");
+    if (hash <= 0)
+        return null;
+    const rest = naturalKey.slice(hash + 1);
+    const colon = rest.indexOf(":");
+    if (colon <= 0 || colon === rest.length - 1)
+        return null;
+    return { origin: naturalKey.slice(0, hash), type: rest.slice(0, colon), subject: rest.slice(colon + 1) };
+}