panoma 0.1.8 → 0.9.0

package/app/node_modules/@panoma/db/dist/index.d.ts

@@ -1,8 +1,66 @@
-import { D as Database } from './client-C6AHYVoa.js';
-export { s as schema } from './client-C6AHYVoa.js';
+import { a as appJobs, b as appWorkspaces, c as apps, D as Database } from './client-B1_3MF0o.js';
+export { s as schema } from './client-B1_3MF0o.js';
 import { ProjectAnalysis, OriginEvidence, WorkState } from '@panoma/core';
 import 'drizzle-orm/pg-core';
 
+type InstalledAppRow = typeof apps.$inferSelect;
+type AppJob = typeof appJobs.$inferSelect;
+type AppJobStatus = AppJob["status"];
+type AppWorkspace = typeof appWorkspaces.$inferSelect;
+declare const LIVE_APP_JOBS: AppJobStatus[];
+/** No app reports this many model calls for one job; above it a receipt is nonsense, not usage. */
+declare const MAX_APP_SPEND_CALLS = 1000;
+declare function appJobTransition(from: AppJobStatus, to: AppJobStatus): boolean;
+declare function canonicalAppInput(value: unknown): string;
+declare function appDedupeKey(appId: string, identity: string, tool: string, input: unknown): string;
+declare function ensureApp(db: Database, id: string, pkg: string): Promise<void>;
+declare function listApps(db: Database): Promise<InstalledAppRow[]>;
+declare function getApp(db: Database, id: string): Promise<InstalledAppRow | undefined>;
+declare function updateApp(db: Database, id: string, patch: Partial<Omit<typeof apps.$inferInsert, "id" | "pkg">>): Promise<void>;
+declare function getAppJob(db: Database, id: string): Promise<AppJob | undefined>;
+declare function listAppJobs(db: Database, options?: {
+    appId?: string;
+    identity?: string;
+    statuses?: AppJobStatus[];
+    limit?: number;
+}): Promise<AppJob[]>;
+declare function enqueueAppJobRow(db: Database, input: {
+    appId: string;
+    identity: string;
+    workspaceId?: string;
+    tool: string;
+    input: Record<string, unknown>;
+    appVersion: string;
+    paid?: boolean;
+    cap?: number;
+}): Promise<{
+    job: AppJob;
+    duplicate: boolean;
+}>;
+declare function hasPendingAppJob(db: Database): Promise<boolean>;
+/** The claim and global concurrency limit are one short transaction. */
+declare function claimAppJob(db: Database): Promise<AppJob | undefined>;
+declare function transitionAppJob(db: Database, id: string, from: AppJobStatus, to: AppJobStatus, patch?: Partial<Pick<AppJob, "result" | "error" | "pid" | "progress" | "workspaceId">>): Promise<boolean>;
+declare function updateAppJobProgress(db: Database, id: string, progress: NonNullable<AppJob["progress"]>, pid?: number): Promise<void>;
+declare function getAppWorkspace(db: Database, appId: string, identity: string): Promise<AppWorkspace | undefined>;
+declare function saveAppWorkspace(db: Database, row: typeof appWorkspaces.$inferInsert): Promise<void>;
+declare function forgetAppWorkspaces(db: Database, appId: string): Promise<void>;
+declare function appProject(db: Database, identity: string, projectId?: string): Promise<{
+    id: string;
+    identity: string | null;
+    root: string;
+    slug: string;
+    name: string;
+}>;
+/** Recheck a queued reservation against today's cap immediately before granting credentials. */
+declare function revalidateAppBudget(db: Database, job: AppJob, cap: number): Promise<AppJob>;
+/** Unknown usage retains a budget hold until tomorrow; it never invents calls in the ledger. */
+declare function recordAppSpend(db: Database, job: AppJob, receipt?: {
+    calls: number;
+    provider?: string;
+    model?: string;
+}): Promise<void>;
+
 declare function idFor(value: string): string;
 /**
  * How many analyses are kept per project.
@@ -214,6 +272,7 @@ declare const IDLE_DAYS = 60;
 type ProjectState = "active" | "paused" | "dormant" | "no-git";
 declare function stateOf(lastCommitAt: Date | null | undefined): ProjectState;
 interface ProjectCard {
+    identity?: string | null;
     id: string;
     name: string;
     slug: string;
@@ -341,12 +400,14 @@ declare function getProject(db: Database, slug: string): Promise<{
         aiSummaryModel: string | null;
         aiSummaryAt: Date | null;
         aiSummaryLang: string | null;
+        aiSummaryHash: string | null;
         mdReview: string | null;
         mdReviewModel: string | null;
         mdReviewAt: Date | null;
         mdReviewHash: string | null;
         mdReviewLang: string | null;
         accounts: unknown;
+        openPlan: unknown;
         buildCheck: unknown;
         north: string | null;
         lastName: string | null;
@@ -569,8 +630,12 @@ declare function getProjectLocation(db: Database, id: string): Promise<{
  * In its own column and with the model that wrote it next to it, because it is the only text in
  * the catalog that does not come from a verifiable fact and one must be able to distinguish it
  * from the rest at a glance — and delete it without touching anything else.
+ *
+ * `hash` is the fingerprint of the material the text was written from, and it is required: it is
+ * what lets the route answer a second press on an unchanged project with the saved text instead
+ * of a second paid call. See `decisions.aiSummaryHash`.
  */
-declare function saveAiSummary(db: Database, id: string, text: string, model: string, lang: string): Promise<void>;
+declare function saveAiSummary(db: Database, id: string, text: string, model: string, lang: string, hash: string): Promise<void>;
 /**
  * Save the model's opinion on the instruction file.
  *
@@ -1615,7 +1680,13 @@ interface BriefScore {
 declare function briefScore(db: Database): Promise<BriefScore>;
 /** What is noted from a call. See table `modelCalls`: null is not zero. */
 interface NewModelCall {
-    /** distill · look. */
+    appId?: string;
+    appJobId?: string;
+    /**
+     * Which organ spent: look · distill · classify · synthesize · memory · ask · rehearse · episodes
+     * · describe · review · probe. The list lives in `apps/web/lib/spend-settings.ts`
+     * (`FAMILY_KINDS`), and the budgets are applied per family there — not per kind, and not here.
+     */
     kind: string;
     provider: string;
     model: string;
@@ -1692,7 +1763,7 @@ declare function startOfDay(at?: Date): Date;
 declare function modelSpendToday(db: Database, kind: string | readonly string[], since?: Date): Promise<ModelSpend>;
 /** The same, separated by classes. See `modelSpendByKind`. */
 interface KindSpend extends ModelSpend {
-    /** distill · look · consolidate. */
+    /** Which organ spent. The list is `FAMILY_KINDS` in `apps/web/lib/spend-settings.ts`. */
     kind: string;
 }
 /**
@@ -1708,8 +1779,64 @@ interface KindSpend extends ModelSpend {
  * things — a glance sends an image, a distillation sends half a history — and putting them
  * together in a number would stop answering 'where did this come from?', which is the question
  * that anyone looking at an expense asks.
+ *
+ * `until` is exclusive and optional: without it the window is open-ended, which is what the
+ * brakes want — 'today so far'. The spend screen wants closed windows —'yesterday', 'last week'—
+ * and passes both cutoffs, calculated in JavaScript for the reason `startOfDay` explains.
+ */
+declare function modelSpendByKind(db: Database, since?: Date, until?: Date): Promise<KindSpend[]>;
+/** The five accounts, for one provider and one model. See `modelSpendByModel`. */
+interface ModelSpendRow extends ModelSpend {
+    provider: string;
+    model: string;
+}
+/**
+ * What was spent in a window, model by model.
+ *
+ * It exists because a price is a rate **per provider and model**, not per kind: a look through
+ * Anthropic and a look through OpenAI are the same organ and cost different money. The spend
+ * screen multiplies each row by the rate the owner wrote for that pair and sums the result; the
+ * rate lives in the web, not here, because the database does not know what a token costs and
+ * should not pretend to.
+ *
+ * Ordered by provider and then model so that the screen reads like a receipt and does not reorder
+ * itself between two refreshes.
+ */
+declare function modelSpendByModel(db: Database, since?: Date, until?: Date): Promise<ModelSpendRow[]>;
+/** One line of the ledger, as `listModelCalls` returns it. Null tokens stay null: unknown, not zero. */
+interface ModelCallRow {
+    kind: string;
+    provider: string;
+    model: string;
+    identity: string | null;
+    input: number | null;
+    output: number | null;
+    images: number;
+    createdAt: Date;
+}
+/**
+ * The raw lines of the ledger in a window, oldest first.
+ *
+ * ── It is grouped by day in JavaScript, and it is not laziness ────────────────────────────────
+ *
+ * The spend screen paints one bar per local day, and `date_trunc('day', created_at)` would cut
+ * at midnight in London: PGlite starts in UTC and nobody tells it otherwise, which is exactly the
+ * failure that froze the day's counter and that the header of `startOfDay` records. `beliefChurn`
+ * met the same wall one step higher, at the month, and solved it the same way: bring the rows and
+ * group them here, where it is known in which time zone this machine is. So this returns lines,
+ * not buckets, and the caller does the calendar.
+ *
+ * The default limit of 20,000 is a ceiling and not a page: a thirty-day window at every factory
+ * cap of `apps/web/lib/spend-settings.ts` is under 15,000 rows, so a person who never raised a
+ * quota never hits it. Anyone who did raise them gets the oldest rows of the window and a chart
+ * that stops early, which is a visible truncation and not a wrong total. Ordered by `createdAt`
+ * and then `id`, so two calls in the same millisecond keep a stable order.
  */
-declare function modelSpendByKind(db: Database, since?: Date): Promise<KindSpend[]>;
+declare function listModelCalls(db: Database, options: {
+    since: Date;
+    until?: Date;
+    limit?: number;
+}): Promise<ModelCallRow[]>;
 /** What an outstanding synthesis moved in a subject. */
 interface SynthesisPass {
     topic: string;
@@ -1719,7 +1846,11 @@ interface SynthesisPass {
     proposed: number;
     /** How much evidence the subject had in front. See the table. */
     observations: number;
+    /** Start of the evidence read, so material arriving during the model call stays pending. */
+    at?: Date;
 }
+/** Successful topic reads, independent of later signatures and edits to the portrait. */
+declare function latestSynthesisByTopic(db: Database): Promise<Map<string, number>>;
 /**
  * Note what a subject moved. It is always written whenever it has been called, even if it moved
  * nothing: zero is the sign of convergence and it must be distinguished from silence.
@@ -1878,7 +2009,17 @@ declare function tasteReach(db: Database): Promise<TasteReach>;
  * deserves another pass.
  */
 interface CorpusProgress {
-    /** Veredictos guardados en total. */
+    /**
+     * What a distillation pass can still reach, not every verdict stored.
+     *
+     * Two kinds of verdict stay in the catalog and out of this figure: the rejected ones nobody read
+     * before rejecting, and the *thin* ones — a project's only unread quote, which no batch can send
+     * because a belief needs {@link MIN_DISTILL_CITATIONS} quotes from the same project to stand.
+     * Counting them made the corpus line say "1 left" forever, and the two loops that chain passes
+     * —`twin distill --all` and the button— stop on `total - read <= 0`, so each pass paid a call
+     * for a batch that could answer nothing. The screen and the receipt take this figure from the
+     * same place so they cannot disagree about what is left.
+     */
     total: number;
     /**
      * Those who have already read: sent to a model, or quoted for some phrase.
@@ -1890,6 +2031,12 @@ interface CorpusProgress {
     read: number;
 }
 declare function corpusProgress(db: Database): Promise<CorpusProgress>;
+/**
+ * How many quotes of one project a belief must cite to stand. The distiller's `MIN_CITATIONS`
+ * in `apps/web/lib/distill.ts` is the same number, and its test compares the two: a project with
+ * fewer unread quotes than this is *thin* and no pass can send it.
+ */
+declare const MIN_DISTILL_CITATIONS = 2;
 /**
  * Reposition the evidence when its citations have changed project.
  *
@@ -2061,6 +2208,56 @@ declare function projectByIdentity(db: Database, identity: string): Promise<{
  * and the one sitting in front can no longer ask anything to be looked at.
  */
 declare function autoLooksToday(db: Database, since?: Date): Promise<number>;
+/**
+ * What "open everything" needs to know about a project, by id.
+ *
+ * By id and not by slug because the button sits next to the open menu, which already speaks in
+ * ids, and because a plan is stored and run against the same handle: the id the browser holds is
+ * the one the run route resolves, never a path. It brings the two halves the plan is built from
+ * —the links the scan resolved and the accounts the owner wrote— plus the runbook, so the
+ * configurator can offer the project's own start command, and the plan itself.
+ */
+declare function getOpenContext(db: Database, id: string): Promise<{
+    project: {
+        id: string;
+        name: string;
+        slug: string;
+        root: string;
+        identity: string | null;
+        gitRemoteUrl: string | null;
+        runbook: unknown;
+    };
+    decision: {
+        accounts: unknown;
+        openPlan: unknown;
+    } | null;
+    links: {
+        projectId: string;
+        serviceId: string;
+        service: string;
+        label: string;
+        url: string;
+        kind: string;
+        evidence: string;
+        iconSlug: string | null;
+    }[];
+    distributions: {
+        projectId: string;
+        kind: string;
+        label: string;
+        evidence: string;
+        url: string | null;
+    }[];
+} | undefined>;
+/**
+ * Save the plan of "open everything", or remove it with `null`.
+ *
+ * It hangs from the identity like the accounts, and like them it stays silent without one — but
+ * here the silence is returned, because the route has to say it: a plan that was not stored will
+ * not be there on the next click, and the button must not pretend otherwise. The value is stored
+ * as it arrives; the route has already normalized it.
+ */
+declare function saveOpenPlan(db: Database, id: string, plan: unknown | null): Promise<boolean>;
 
 /**
  * The bridge between AI agents and the catalog.
@@ -2482,26 +2679,31 @@ declare function listProjectActivity(db: Database, projectId: string): Promise<{
     agentKind: string;
     sessionId: string;
 }[]>;
-/**
- * What a session left written, in the order in which it was written.
- *
- * It is the raw material of the distiller: when a session is closed, it is read entirely —not the
- * project window, this visit— and from there come the candidates for a durable fact. In order of
- * arrival because the distiller reads a story, not a ranking.
- */
-declare function listSessionActivities(db: Database, sessionId: string): Promise<{
-    kind: string;
-    summary: string;
-    details: string | null;
-    filesTouched: unknown;
-}[]>;
 /** A finding in the archive: who wrote it, what it was, and when. */
 interface JournalHit {
+    id: string;
     agent: string;
     kind: string;
     summary: string;
     details: string | null;
     at: Date;
+    /** A bounded passage containing a search match, rather than the start of the details. */
+    excerpt: string;
+}
+interface JournalPage {
+    matches: JournalHit[];
+    nextCursor: string | null;
+}
+interface JournalEntryPage {
+    id: string;
+    agent: string;
+    kind: string;
+    summary: string;
+    at: Date;
+    text: string;
+    offset: number;
+    totalChars: number;
+    nextOffset: number | null;
 }
 /**
  * The archive reading room: search through the entire log, not in the window.
@@ -2522,6 +2724,10 @@ interface JournalHit {
  * the usual one — two identical calls, the same order.
  */
 declare function searchJournal(db: Database, projectId: string, query: string, limit?: number): Promise<JournalHit[]>;
+/** Search continuation is tied to both the project and the original query. */
+declare function searchJournalPage(db: Database, projectId: string, query: string, cursor?: string): Promise<JournalPage>;
+/** Read the original in bounded segments. An ID from another project never opens a record. */
+declare function readJournalEntry(db: Database, projectId: string, entryId: string, offset?: number): Promise<JournalEntryPage | undefined>;
 /**
  * The tasks of a project — all of them, or only the statuses that are requested.
  *
@@ -2602,6 +2808,8 @@ declare const NOTE_PENDING_MAX = 20;
  * city.
  */
 declare const NOTE_SLEEPING_MAX = 30;
+/** A bounded literal path within a project, shared by triggers and on-demand memory retrieval. */
+declare function validMemoryPath(path: string): boolean;
 declare function validTrigger(trigger: string): boolean;
 /**
  * Does this route hit this trigger? Exact, or under the prefix if the trigger ends in `/**`. The
@@ -2616,6 +2824,7 @@ interface ProjectNote {
     createdAt: Date;
     trigger: string | null;
     challenge?: unknown;
+    sentinels?: unknown;
 }
 /** The no of `proposeNote`, with the reason in data so that each surface can say it in its language. */
 type NoteRefusal = {
@@ -2648,10 +2857,13 @@ declare function proposeNote(db: Database, input: {
 declare function addHumanNote(db: Database, input: {
     projectId: string;
     body: string;
+    trigger?: string;
+    sentinels?: Sentinel[];
 }): Promise<{
     id: string;
+    body: string;
 } | NoteRefusal | {
-    refused: "overBudget";
+    refused: "overBudget" | "sleepingFull";
     used: number;
     budget: number;
 }>;
@@ -2668,7 +2880,10 @@ declare function addHumanNote(db: Database, input: {
  * alive: if two tabs decide at the same time, the second one finds out that it arrived late
  * instead of stepping silently.
  */
-declare function decideNote(db: Database, noteId: string, decision: "approved" | "discarded"): Promise<
+declare function decideNote(db: Database, noteId: string, decision: "approved" | "discarded", options?: {
+    projectId?: string;
+    sentinels?: Sentinel[];
+}): Promise<
 /**
  * Upon approval, `body` and `trigger` travel back: the anchoring customs anchor what is stored,
  * not what the customer says.
@@ -2738,12 +2953,13 @@ declare function setSentinels(db: Database, noteId: string, sentinels: Sentinel[
  * the disc has already spoken, and in the meantime serving a note whose basis has changed is worse
  * than silence. Getting out of suspicion does require the usual yes (`decideNote`).
  */
-declare function challengeNote(db: Database, noteId: string, challenge: Challenge): Promise<boolean>;
+declare function challengeNote(db: Database, noteId: string, challenge: Challenge, expectedDecidedAt?: Date | null): Promise<boolean>;
 /** What the patrolman needs: the approved ones with sentries posted, and nothing more. */
 declare function listSentinels(db: Database, projectId: string): Promise<{
     id: string;
     body: string;
     sentinels: Sentinel[];
+    decidedAt: Date | null;
 }[]>;
 /** A submission of memory, noted. The reason for the entire book is in `schema.ts` (`servings`). */
 declare function recordServing(db: Database, input: {
@@ -2752,9 +2968,12 @@ declare function recordServing(db: Database, input: {
     arm: "served" | "withheld";
     noteIds: string[];
     noteChars: number;
+    experimentId?: string | null;
 }): Promise<void>;
 interface ScaleReport {
     days: number;
+    /** Ordinary deliveries are observable traffic, never an experimental control group. */
+    observationalServings: number;
     arms: {
         arm: string;
         servings: number;
@@ -2797,7 +3016,7 @@ interface ScaleReport {
  * or a no. The day the median spikes or the queue doesn't go down, the gate is above its carrying
  * capacity — and this must be known BEFORE building more sources of proposals, not after.
  */
-declare function scaleReport(db: Database, days?: number): Promise<ScaleReport>;
+declare function scaleReport(db: Database, days?: number, experimentId?: string): Promise<ScaleReport>;
 /**
  * The counters on the bridge, in a consultation.
  *
@@ -2834,6 +3053,15 @@ declare const CONSULT_MAX = 300;
  * twenty slots forever and the route closed itself.
  */
 declare const CONSULT_PENDING_MAX = 20;
+/**
+ * How far back the sweeper reaches for a stranded draft, in days: the same window `doubleReport`
+ * reads by default, and on purpose the same constant. A draft is paid for so the person can
+ * label it and the exam can count it; a question older than the exam's window would be drafted
+ * (a full paid call) and never counted, and the project card shows only the newest few. Before
+ * this bound the sweeper had no upper age at all, so an install left alone for a season came back
+ * spending the day's budget on questions nobody would ever see.
+ */
+declare const STALE_MAX_DAYS = 30;
 interface Consultation {
     id: string;
     question: string;
@@ -2856,6 +3084,12 @@ declare function recordConsultation(db: Database, input: {
     refused: "tooLong" | "queueFull";
     max: number;
 }>;
+/**
+ * What the person can actually empty from a project's review list: the definition behind
+ * `CONSULT_PENDING_MAX`, in one place because two doors measure it — recording a question and
+ * sweeping a stranded one. A draft nobody can label is a paid call nobody needed.
+ */
+declare function pendingConsultations(db: Database, projectId: string): Promise<number>;
 /**
  * The draft of the double lands — or its abstention, which is the most common honest response and
  * counts as data. Only about `drafting`: a draft does not step on another, and it never steps on a
@@ -2873,14 +3107,20 @@ declare function draftConsultation(db: Database, id: string, draft: {
  * Only on drafted and untagged drafts — an abstention is not tagged (there is no answer to judge)
  * and a tag is not rewritten: the second click comes late, like all the decisions of this house.
  */
-declare function labelConsultation(db: Database, id: string, verdict: "backed" | "vetoed"): Promise<boolean>;
+declare function labelConsultation(db: Database, id: string, verdict: "backed" | "vetoed", projectId?: string): Promise<boolean>;
+/** Read the persisted, redacted question only while it still needs a draft. */
+declare function draftingConsultation(db: Database, id: string): Promise<{
+    question: string;
+} | undefined>;
 /**
  * The stranded drafts of a project: questions whose writer fell through or ran out of budget. Only
  * those that have been around for a while — the newly asked still has their own writer on the way,
  * and paying for a call again would be spending the same thing twice. The oldest first: they have
- * been waiting for their turn longer.
+ * been waiting for their turn longer. And only within `STALE_MAX_DAYS`: a row beyond the window
+ * stays in `drafting`, seen in the record as what it is, and stopped counting against the review
+ * queue after a day anyway (`pendingConsultations`).
  */
-declare function staleDrafting(db: Database, projectId: string, olderThanMs?: number, limit?: number): Promise<{
+declare function staleDrafting(db: Database, projectId: string, olderThanMs?: number, limit?: number, withinMs?: number): Promise<{
     id: string;
     question: string;
 }[]>;
@@ -2907,6 +3147,365 @@ interface DoubleReport {
  */
 declare function doubleReport(db: Database, days?: number): Promise<DoubleReport>;
 
+declare const EPISODE_FIELDS: readonly ["context", "goal", "constraints", "alternatives", "decision", "rationale", "outcome", "conditions", "exceptions"];
+type EpisodeFieldName = typeof EPISODE_FIELDS[number];
+type EpisodeFields = Partial<Record<EpisodeFieldName, {
+    text: string;
+    narrativeId?: string;
+}>>;
+interface NewNarrative {
+    identity: string;
+    source: string;
+    sessionId: string;
+    at: Date;
+    kind: "opening" | "reaction" | "brief";
+    text: string;
+    context: string | null;
+    truncated: boolean;
+}
+interface Narrative extends NewNarrative {
+    id: string;
+    createdAt: Date;
+    readAt?: Date | null;
+    /** Set by a pass whose output was unusable; cleared by a pass that read the record. */
+    failedAt?: Date | null;
+}
+interface NewDecisionEpisode {
+    identity: string | null;
+    supersedesId?: string | null;
+    origin: "owner" | "history";
+    fields: EpisodeFields;
+    model: string | null;
+    /**
+     * The last instant this decision applies; omitted or null for one that does not expire. The
+     * owner writes a calendar day and it arrives here as that day at 23:59:59.999 UTC: see
+     * `valid_until` in the schema for why the end of the day, and why it is a column.
+     */
+    validUntil?: Date | null;
+}
+interface DecisionEpisode extends NewDecisionEpisode {
+    id: string;
+    supersedesId: string | null;
+    status: "active" | "dismissed";
+    validUntil: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** A rejected revision leaves both the saved history and its current version untouched. */
+declare class DecisionEpisodeConflict extends Error {
+    readonly code: "activeSuccessor" | "stale";
+    constructor(code: "activeSuccessor" | "stale");
+}
+/** Caller owns the write queue and transaction; these helpers also work inside that transaction. */
+declare function saveNarratives(db: Database, rows: NewNarrative[]): Promise<{
+    inserted: number;
+}>;
+/**
+ * Newest first; an omitted limit means the complete requested corpus. Among the unread, the
+ * records no pass has failed on come before the ones one has: see `failedAt` in the schema.
+ */
+declare function listNarratives(db: Database, options?: {
+    identity?: string;
+    limit?: number;
+    unread?: boolean;
+}): Promise<Narrative[]>;
+/** Resolve provenance in bounded SQL batches, with deterministic ordering and no missing rows invented. */
+declare function narrativesByIds(db: Database, ids: string[]): Promise<Narrative[]>;
+/** `deferred` counts the pending records a pass already failed on; they are still pending. */
+declare function narrativeCount(db: Database): Promise<{
+    total: number;
+    pending: number;
+    deferred: number;
+}>;
+/**
+ * Remember that a pass over these records came back unusable, so the next pass takes other
+ * records first. Only unread records: a read one has nothing left to rotate.
+ */
+declare function markNarrativesFailed(db: Database, ids: string[]): Promise<number>;
+/** Forget source material and all extracted fields that copied it. Owner-authored episodes remain. */
+declare function deleteNarratives(db: Database, options?: {
+    source?: string;
+}): Promise<{
+    narratives: number;
+    episodes: number;
+}>;
+/** A successful empty extraction still advances. A remapped source cannot consume a stale receipt. */
+declare function markNarrativesRead(db: Database, ids: string[], expectedIdentity?: string): Promise<number>;
+/**
+ * Validate the entire batch before its first write. Only literal human text can become a history
+ * field; an agent delivery in narrative.context cannot acquire human authorship through a citation.
+ */
+declare function saveDecisionEpisodes(db: Database, rows: NewDecisionEpisode[], options?: {
+    expectedPreviousUpdatedAt?: Date;
+}): Promise<DecisionEpisode[]>;
+interface EpisodePosition {
+    createdAt: Date;
+    id: string;
+}
+/**
+ * An explicit null identity requests only portfolio-wide owner episodes. Undefined requests all.
+ * `query` is a case-insensitive substring over the texts of the searched fields, with the `LIKE`
+ * wildcards escaped so a person searching for `100%` finds that and not everything. `before` pages
+ * older rows from a position on the same order; both are ignored when absent.
+ *
+ * `activeAt` withholds the decisions that had already stopped applying at that instant, and every
+ * delivery to an agent passes it. It is not the default, and that is the whole design: an expired
+ * decision is wasted context for an agent and the owner's own history for the owner, so their
+ * screen keeps listing it, expired and visible, and only they can see it that way.
+ */
+declare function listDecisionEpisodes(db: Database, options?: {
+    identity?: string | null;
+    status?: "active" | "dismissed";
+    limit?: number;
+    ownerDecisionsOnly?: boolean;
+    unambiguousOnly?: boolean;
+    activeAt?: Date;
+    query?: string;
+    before?: EpisodePosition;
+}): Promise<DecisionEpisode[]>;
+/**
+ * The legacy conflicts, for the owner to resolve: every valid active row whose family holds
+ * another, grouped per family. Nothing here can be created any more — a revision dismisses its
+ * predecessor in the same transaction and a second active version is refused with a conflict —
+ * but families written before that rule exist, and until now the owner met them only as a card
+ * whose "Revise" was disabled. The briefing and the Lab withhold the whole family (`unambiguousOnly`)
+ * and this is the list of what they withhold.
+ *
+ * The group key is the family's own active membership, aggregated per row: the walk is symmetric,
+ * so every member of one family aggregates the same set. Families arrive newest first and members
+ * newest first, from the one ordering.
+ */
+declare function listConflictingEpisodeFamilies(db: Database): Promise<DecisionEpisode[][]>;
+declare function decisionEpisodeById(db: Database, id: string): Promise<DecisionEpisode | undefined>;
+/** The other active member of this revision family, regardless of its distance or direction. */
+declare function activeSuccessor(db: Database, id: string): Promise<DecisionEpisode | undefined>;
+/** Server-computed restore/revise state, independent of the limited recent-record view. */
+declare function activeEpisodeRevisions(db: Database, ids: string[]): Promise<Record<string, string>>;
+declare function decisionEpisodeCount(db: Database): Promise<number>;
+declare function setDecisionEpisodeStatus(db: Database, id: string, status: "active" | "dismissed", options?: {
+    expectedUpdatedAt?: Date;
+}): Promise<boolean>;
+/**
+ * Set or clear when a decision stops applying, without rewriting a word of its testimony.
+ *
+ * The same lock and the same stale guard as the status change, for the same reason: two owner
+ * screens can be open, and one of them can be showing a record another one already changed.
+ * Asking for the expiry the record already carries is a successful retry and touches nothing,
+ * which is also how a repeated dismissal behaves.
+ *
+ * Nothing here interprets the date. The caller hands over the instant that the owner's calendar
+ * day ends at in UTC; `valid_until` in the schema explains why that is the honest translation.
+ */
+declare function setDecisionEpisodeValidUntil(db: Database, id: string, validUntil: Date | null, options?: {
+    expectedUpdatedAt?: Date;
+}): Promise<boolean>;
+
+declare const MEMORY_JOB_MAX_ATTEMPTS = 3;
+declare const MEMORY_JOB_LEASE_MS: number;
+/**
+ * The newest activities of a closed session that reach the distiller. It was 50 until
+ * 6-Sep-2026, and the early part of a long session —where the goal is usually stated— fell
+ * outside it. One bigger paid call covers more of the session than several small ones would;
+ * the arithmetic of that choice is written beside the envelope these records are fitted into,
+ * `JOURNAL_LIMIT` in `apps/web/lib/memory-distill.ts`.
+ */
+declare const MEMORY_SESSION_WINDOW = 100;
+interface MemoryJobClaim {
+    sessionId: string;
+    projectId: string;
+    identity: string | null;
+    root: string;
+    attempts: number;
+    leaseToken: string;
+}
+interface MemoryJobCounts {
+    pending: number;
+    running: number;
+    deferred: number;
+    failed: number;
+    complete: number;
+}
+interface SessionMemoryActivity {
+    kind: string;
+    summary: string;
+    details: string | null;
+    filesTouched: unknown;
+}
+/** The caller may put session closure and enqueueing in the same transaction. */
+declare function enqueueMemoryJob(db: Database, sessionId: string): Promise<boolean>;
+/**
+ * A short PostgreSQL lock covers selection and lease rotation for every process. Expired leases
+ * may retry within the same attempt ceiling; exhausting it leaves an inspectable failed job.
+ */
+declare function claimMemoryJob(db: Database, options?: {
+    now?: Date;
+    leaseMs?: number;
+}): Promise<MemoryJobClaim | undefined>;
+/** Publish only while this worker owns the lease and the session still belongs to its input scope. */
+declare function withMemoryJobLease<T>(db: Database, sessionId: string, leaseToken: string, work: (tx: Database) => Promise<T>, expectedProjectId?: string): Promise<{
+    current: false;
+} | {
+    current: true;
+    value: T;
+}>;
+/**
+ * A late worker cannot replace a newer receipt. Environmental deferrals refund the claimed
+ * attempt; failed model or extraction work retries with a delay and stops at the shared ceiling.
+ *
+ * `retriesLeft` lets a failure spend attempts it did not make: the worker knows things the
+ * counter does not — that the same prompt already came back unreadable, so a third identical call
+ * would buy the same answer, or that the call was paid and only the publication failed, which is
+ * worth exactly one more try. The row's `attempts` is raised so that at most that many claims
+ * remain; it is never lowered.
+ */
+declare function finishMemoryJob(db: Database, sessionId: string, leaseToken: string, result: {
+    status: "complete" | "deferred" | "failed";
+    reason?: string;
+    runAfter?: Date;
+    receipt?: Record<string, unknown>;
+    consumeAttempt?: boolean;
+    /** Failed work only: how many further claims this job may still get, at most. */
+    retriesLeft?: number;
+}): Promise<boolean>;
+/** Counts are states, not claims about extraction quality. */
+declare function memoryJobCounts(db: Database, projectId?: string): Promise<MemoryJobCounts>;
+/** The newest queued session's state and coverage, without exposing its source text. */
+declare function latestProjectMemoryJob(db: Database, projectId: string): Promise<{
+    sessionId: string;
+    status: "pending" | "running" | "failed" | "deferred" | "complete";
+    reason: string | null;
+    attempts: number;
+    receipt: Record<string, unknown> | null;
+    availableAt: Date;
+    finishedAt: Date | null;
+} | undefined>;
+/** Preserve the resolution at the end of a long session and disclose the omitted earlier work. */
+declare function sessionMemoryWindow(db: Database, sessionId: string): Promise<{
+    activities: SessionMemoryActivity[];
+    total: number;
+    omitted: number;
+}>;
+
+/**
+ * The portable memory: everything the catalog remembers about one project, in one document.
+ *
+ * It exists because the memory audit of 6-Sep-2026 listed it as pending —"a versioned local export
+ * of records, relationships and source metadata"— and because until then the only way out of the
+ * catalog was `panoma scan --json --out`, which carries the disk analysis and not a single note.
+ * What a person approved, what they decided and what the distiller left behind lived in a PGlite
+ * directory that nothing outside this repository can open.
+ *
+ * ── What goes in, and why every state travels ──────────────────────────────────────
+ *
+ * `listProjectNotes` serves the approved notes by default, because that is what an agent may read.
+ * A person taking their memory elsewhere is not an agent: the proposals still waiting, the ones
+ * they discarded and the ones a sentinel challenged are all theirs, and dropping a state would
+ * hand them a file that says less than their own screen. The same for decisions: the dismissed
+ * episode is the history of the active one, and the export keeps the link (`supersedesId`) plus
+ * the answer the screen computes (`activeRevisionId`), so whoever reads the file can walk the
+ * revision family without this database.
+ *
+ * `evidenceValid` is the one thing here that is computed and not copied. `listDecisionEpisodes`
+ * hides an extracted episode whose cited narrative was forgotten or moved to another identity;
+ * the export shows the row and says so, because a file that silently loses a decision is worse
+ * than one that carries it flagged. It is the same predicate the briefing applies, computed in
+ * the same query that reads the rows.
+ *
+ * ── What never goes in ──────────────────────────────────────────────────────────────
+ *
+ * `memory_jobs.lease_token`. It is the worker's proof of ownership over a running job, it rotates
+ * on every claim, and it means nothing outside this process: exporting it would only teach a
+ * reader a value that can finish somebody else's attempt. The receipts travel without it, and
+ * `memory-export.test.ts` reads the serialized document to make sure it stays out.
+ *
+ * Neither the narratives nor the journal go in: the first is the private history the owner may
+ * revoke source by source, and the second has its own reader (`panoma_recall`). This is the
+ * curated memory and what was decided on top of it, which is what a person would carry over.
+ *
+ * ── The shape is versioned, and dates are strings ─────────────────────────────────
+ *
+ * `version: 1` is the promise that a reader written today keeps reading tomorrow's files or is
+ * told, in one integer, that it cannot. Dates are ISO strings and not `Date` objects because the
+ * document's life is on a disk, not in a process: what this function returns is exactly what the
+ * file contains, so a test can compare the two without a serialization step in between.
+ */
+declare const MEMORY_EXPORT_VERSION = 1;
+interface ExportedNote {
+    id: string;
+    body: string;
+    /** proposed · approved · discarded · challenged */
+    status: string;
+    createdBy: string;
+    createdAt: string;
+    decidedAt: string | null;
+    /** The note's trigger, under the name the screen uses. */
+    where: string | null;
+    /** The sentinels, under the name the screen uses. */
+    anchors: unknown;
+    challenge: unknown;
+}
+interface ExportedDecision {
+    id: string;
+    identity: string | null;
+    supersedesId: string | null;
+    /** The active member of this revision family, when it is another episode. */
+    activeRevisionId: string | null;
+    /** Whether every cited narrative still exists under this identity: what the briefing checks. */
+    evidenceValid: boolean;
+    origin: "owner" | "history";
+    fields: EpisodeFields;
+    model: string | null;
+    status: "active" | "dismissed";
+    /** When the decision stopped, or stops, applying; null for one that does not expire. */
+    validUntil: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ExportedMemoryJob {
+    sessionId: string;
+    status: "pending" | "running" | "deferred" | "failed" | "complete";
+    reason: string | null;
+    attempts: number;
+    availableAt: string;
+    startedAt: string | null;
+    finishedAt: string | null;
+    receipt: Record<string, unknown> | null;
+}
+interface MemoryExport {
+    version: typeof MEMORY_EXPORT_VERSION;
+    exportedAt: string;
+    project: {
+        id: string;
+        slug: string;
+        name: string;
+        root: string;
+        identity: string | null;
+    };
+    notes: ExportedNote[];
+    /** The decisions keyed to this project's stable identity; empty when it has none. */
+    decisions: ExportedDecision[];
+    /** The owner's portfolio-wide decisions, which the briefing also serves to this project. */
+    generalDecisions: ExportedDecision[];
+    receipts: {
+        counts: MemoryJobCounts;
+        jobs: ExportedMemoryJob[];
+    };
+}
+/**
+ * One project's memory, whole, in the versioned shape above.
+ *
+ * Every list comes back in a stable order —newest first, then by id— for the same reason the
+ * context tasks do: two exports of an unchanged catalog have to be the same bytes, or a diff
+ * between them says nothing.
+ */
+declare function exportProjectMemory(db: Database, project: {
+    id: string;
+    slug: string;
+    name: string;
+    root: string;
+    identity: string | null;
+}): Promise<MemoryExport>;
+
 /** States through which an execution passes. */
 type RunStatus = "pending" | "running" | "proposed" | "failed" | "no-changes" | "applied" | "discarded";
 declare function createRun(db: Database, input: {
@@ -3066,4 +3665,4 @@ interface SecurityTarget {
  */
 declare function listSecurityTargets(db: Database, projectId: string): Promise<SecurityTarget[]>;
 
-export { ALIVE, type AgentContext, type BeliefCitation, type BeliefRow, type BeliefState, type BeliefSupport, type BriefScore, type BuildCheckVerdict, CONSULT_MAX, CONSULT_PENDING_MAX, type Challenge, type ChurnMonth, type Consultation, type CorpusProgress, type CreatedAgent, DORMANT_DAYS, type DailyCommit, type DailyCritic, type DailyProject, type DailyProposal, type DailyReport, Database, type DesignShare, type DirectorProject, type DiskRow, type DiskTotals, type DoubleReport, type FamilyView, type HiddenView, IDLE_DAYS, type IngestPayload, type IngestResult, type JournalHit, type KindSpend, LOG_DETAILS_MAX, LOG_SUMMARY_MAX, type LookFired, type LookRow, type ModelSpend, NOTE_BUDGET, NOTE_MAX, NOTE_PENDING_MAX, NOTE_SLEEPING_MAX, type NewBelief, type NewLaunch, type NewLook, type NewModelCall, type NewObservation, type NewVerdict, type NoteRefusal, type ObservationRow, type PackageRow, type PortfolioDesign, type PortfolioStats, type ProjectAccount, type ProjectCard, type ProjectNote, type ProjectState, type PublishedLine, type ReviewRow, type RunStatus, SNAPSHOTS_PER_PROJECT, SUPPORT_FLOOR, type ScaleReport, type SecurityTarget, type Sentinel, type SerializedFamily, type StoredCritique, type StoredFinding, type SynthesisPass, type TasteCitation, type TasteReach, type TasteScore, type TopicCount, type UnsavedProject, type Verdict, type VerdictsSaved, addHumanNote, assignedCritiques, assignedFindings, authenticateAgent, autoLooksToday, beliefChurn, bridgeCounts, briefScore, challengeNote, citedVerdictIds, claimTask, closeSession, completeTask, corpusProgress, createAgent, createRun, createTask, decideNote, deleteAgent, deleteVerdicts, discardTask, discardedCritiques, discardedFindings, doubleReport, draftConsultation, esquina, excludeProject, familia, findKnownFailure, findRunningRun, findUpgradeTarget, finishRun, forgetProjectsUnder, getAgentContext, getDailyReport, getDesignFingerprint, getDiskTotals, getLook, getNorth, getProject, getProjectIcon, getProjectLocation, getReview, getRun, getRunWithProject, getStats, getTask, idFor, inTransaction, ingestPortfolio, insertBeliefs, labelConsultation, launchedTasks, listAgents, listAllActivity, listAllRuns, listBeliefs, listDiskUsage, listFamilies, listHidden, listLooks, listObservations, listPackages, listProjectActivity, listProjectConsultations, listProjectLaunches, listProjectNotes, listProjectRoots, listProjectRuns, listProjectTasks, listProjects, listSecurityTargets, listSentinels, listSessionActivities, listUnsavedWork, listVerdicts, logActivity, lookedAt, markPublished, markVerdictsDistilled, modelSpendByKind, modelSpendToday, monthOf, neverReviewed, newId, noteUsage, notesAt, observationTopics, openSession, portfolioDesign, projectByIdentity, projectNamesByIdentity, proposeNote, pruneSnapshots, queueWrite, readVerdictIds, reapStaleRuns, recordConsultation, recordLaunch, recordServing, remapObservations, resolveProject, resolveProposal, retireBeliefs, rotateAgentKey, saveAiSummary, saveBuildCheck, saveDesignFingerprint, saveDiskUsage, saveLook, saveMdReview, saveModelCall, saveNorth, saveObservations, saveProjectAccounts, saveReview, saveSynthesisPass, saveVerdicts, scaleReport, searchJournal, setBeliefScope, setBeliefTopics, setHidden, setObservationTopics, setRunStatus, setSentinels, signBelief, staleDrafting, standsUp, startOfDay, startOfMonthsAgo, stateOf, tasteReach, tasteScore, triggerMatches, unexcludeProject, updateBelief, validTrigger, vetoBelief };
+export { ALIVE, type AgentContext, type AppJob, type AppJobStatus, type AppWorkspace, type BeliefCitation, type BeliefRow, type BeliefState, type BeliefSupport, type BriefScore, type BuildCheckVerdict, CONSULT_MAX, CONSULT_PENDING_MAX, type Challenge, type ChurnMonth, type Consultation, type CorpusProgress, type CreatedAgent, DORMANT_DAYS, type DailyCommit, type DailyCritic, type DailyProject, type DailyProposal, type DailyReport, Database, type DecisionEpisode, DecisionEpisodeConflict, type DesignShare, type DirectorProject, type DiskRow, type DiskTotals, type DoubleReport, EPISODE_FIELDS, type EpisodeFieldName, type EpisodeFields, type EpisodePosition, type ExportedDecision, type ExportedMemoryJob, type ExportedNote, type FamilyView, type HiddenView, IDLE_DAYS, type IngestPayload, type IngestResult, type InstalledAppRow, type JournalEntryPage, type JournalHit, type JournalPage, type KindSpend, LIVE_APP_JOBS, LOG_DETAILS_MAX, LOG_SUMMARY_MAX, type LookFired, type LookRow, MAX_APP_SPEND_CALLS, MEMORY_EXPORT_VERSION, MEMORY_JOB_LEASE_MS, MEMORY_JOB_MAX_ATTEMPTS, MEMORY_SESSION_WINDOW, MIN_DISTILL_CITATIONS, type MemoryExport, type MemoryJobClaim, type MemoryJobCounts, type ModelCallRow, type ModelSpend, type ModelSpendRow, NOTE_BUDGET, NOTE_MAX, NOTE_PENDING_MAX, NOTE_SLEEPING_MAX, type Narrative, type NewBelief, type NewDecisionEpisode, type NewLaunch, type NewLook, type NewModelCall, type NewNarrative, type NewObservation, type NewVerdict, type NoteRefusal, type ObservationRow, type PackageRow, type PortfolioDesign, type PortfolioStats, type ProjectAccount, type ProjectCard, type ProjectNote, type ProjectState, type PublishedLine, type ReviewRow, type RunStatus, SNAPSHOTS_PER_PROJECT, STALE_MAX_DAYS, SUPPORT_FLOOR, type ScaleReport, type SecurityTarget, type Sentinel, type SerializedFamily, type SessionMemoryActivity, type StoredCritique, type StoredFinding, type SynthesisPass, type TasteCitation, type TasteReach, type TasteScore, type TopicCount, type UnsavedProject, type Verdict, type VerdictsSaved, activeEpisodeRevisions, activeSuccessor, addHumanNote, appDedupeKey, appJobTransition, appProject, assignedCritiques, assignedFindings, authenticateAgent, autoLooksToday, beliefChurn, bridgeCounts, briefScore, canonicalAppInput, challengeNote, citedVerdictIds, claimAppJob, claimMemoryJob, claimTask, closeSession, completeTask, corpusProgress, createAgent, createRun, createTask, decideNote, decisionEpisodeById, decisionEpisodeCount, deleteAgent, deleteNarratives, deleteVerdicts, discardTask, discardedCritiques, discardedFindings, doubleReport, draftConsultation, draftingConsultation, enqueueAppJobRow, enqueueMemoryJob, ensureApp, esquina, excludeProject, exportProjectMemory, familia, findKnownFailure, findRunningRun, findUpgradeTarget, finishMemoryJob, finishRun, forgetAppWorkspaces, forgetProjectsUnder, getAgentContext, getApp, getAppJob, getAppWorkspace, getDailyReport, getDesignFingerprint, getDiskTotals, getLook, getNorth, getOpenContext, getProject, getProjectIcon, getProjectLocation, getReview, getRun, getRunWithProject, getStats, getTask, hasPendingAppJob, idFor, inTransaction, ingestPortfolio, insertBeliefs, labelConsultation, latestProjectMemoryJob, latestSynthesisByTopic, launchedTasks, listAgents, listAllActivity, listAllRuns, listAppJobs, listApps, listBeliefs, listConflictingEpisodeFamilies, listDecisionEpisodes, listDiskUsage, listFamilies, listHidden, listLooks, listModelCalls, listNarratives, listObservations, listPackages, listProjectActivity, listProjectConsultations, listProjectLaunches, listProjectNotes, listProjectRoots, listProjectRuns, listProjectTasks, listProjects, listSecurityTargets, listSentinels, listUnsavedWork, listVerdicts, logActivity, lookedAt, markNarrativesFailed, markNarrativesRead, markPublished, markVerdictsDistilled, memoryJobCounts, modelSpendByKind, modelSpendByModel, modelSpendToday, monthOf, narrativeCount, narrativesByIds, neverReviewed, newId, noteUsage, notesAt, observationTopics, openSession, pendingConsultations, portfolioDesign, projectByIdentity, projectNamesByIdentity, proposeNote, pruneSnapshots, queueWrite, readJournalEntry, readVerdictIds, reapStaleRuns, recordAppSpend, recordConsultation, recordLaunch, recordServing, remapObservations, resolveProject, resolveProposal, retireBeliefs, revalidateAppBudget, rotateAgentKey, saveAiSummary, saveAppWorkspace, saveBuildCheck, saveDecisionEpisodes, saveDesignFingerprint, saveDiskUsage, saveLook, saveMdReview, saveModelCall, saveNarratives, saveNorth, saveObservations, saveOpenPlan, saveProjectAccounts, saveReview, saveSynthesisPass, saveVerdicts, scaleReport, searchJournal, searchJournalPage, sessionMemoryWindow, setBeliefScope, setBeliefTopics, setDecisionEpisodeStatus, setDecisionEpisodeValidUntil, setHidden, setObservationTopics, setRunStatus, setSentinels, signBelief, staleDrafting, standsUp, startOfDay, startOfMonthsAgo, stateOf, tasteReach, tasteScore, transitionAppJob, triggerMatches, unexcludeProject, updateApp, updateAppJobProgress, updateBelief, validMemoryPath, validTrigger, vetoBelief, withMemoryJobLease };