@hypercarrier/pi-team-durable 0.0.0-stage → 0.1.0-rc.2

package/dist/authority/index.d.ts

@@ -0,0 +1,15 @@
+export { createTeamRuntime, pendingStops, confirmStop, closing, stopPlan, type RuntimeOptions, type StopPlan, type StopOutcome } from './runtime.ts';
+export { observe, ObservationDoc, observations, observationStats, openObservations, type Observations, type Page, type ObservationPortResolver } from './observation.ts';
+export { TeamDoc, GraphDoc, JournalDoc, OutboxDoc, ReceiptDoc, open, plain, type TeamState, type GraphState, type JournalState, type OutboxState, type Team, type Worker, type ModelRole, type ModelRoleCatalog, type State } from './state.ts';
+export { GraphTaskController } from './graph-control.ts';
+export { projectGraphTaskCards } from './graph-card.ts';
+export { snapshotResult, currentAlerts } from './projection.ts';
+export { abortExpectedRun, type AbortRun, type InterruptOutcome, type InterruptTarget } from './interrupt.ts';
+export { TASK_ID_MAX_LENGTH } from './limits.ts';
+export { deliveryDraft, deliveryInput, SENDER_LIMIT, type DeliveryInput, type TeamNoticeData } from './delivery.ts';
+export { pageDraft } from './notifier.ts';
+export { updates, pageEvents, UPDATE_PAGE_EVENTS, UPDATE_SCAN_ENTRIES } from './sync.ts';
+export { HeadDoc, TaskDoc, OperationDoc, ObligationDoc, AlertDoc, CallDoc, DirectCallDoc, openAuthority, taskAddress, type AuthorityHead, type TaskRecord } from './store.ts';
+export { readTeamPanel, readTeamSummary } from './panel.ts';
+export { readObservationCursor } from './observation-store.ts';
+export { taskCards } from './store.ts';

package/dist/authority/index.js

@@ -0,0 +1,15 @@
+export { createTeamRuntime, pendingStops, confirmStop, closing, stopPlan } from "./runtime.js";
+export { observe, ObservationDoc, observations, observationStats, openObservations } from "./observation.js";
+export { TeamDoc, GraphDoc, JournalDoc, OutboxDoc, ReceiptDoc, open, plain } from "./state.js";
+export { GraphTaskController } from "./graph-control.js";
+export { projectGraphTaskCards } from "./graph-card.js";
+export { snapshotResult, currentAlerts } from "./projection.js";
+export { abortExpectedRun } from "./interrupt.js";
+export { TASK_ID_MAX_LENGTH } from "./limits.js";
+export { deliveryDraft, deliveryInput, SENDER_LIMIT } from "./delivery.js";
+export { pageDraft } from "./notifier.js";
+export { updates, pageEvents, UPDATE_PAGE_EVENTS, UPDATE_SCAN_ENTRIES } from "./sync.js";
+export { HeadDoc, TaskDoc, OperationDoc, ObligationDoc, AlertDoc, CallDoc, DirectCallDoc, openAuthority, taskAddress } from "./store.js";
+export { readTeamPanel, readTeamSummary } from "./panel.js";
+export { readObservationCursor } from "./observation-store.js";
+export { taskCards } from "./store.js";

package/dist/authority/interrupt.d.ts

@@ -0,0 +1,11 @@
+import type { Context } from '@earendil-works/chord/context';
+import { type Harness, type TaskId, type ConversationId, type DocumentReader } from '@earendil-works/pi-durable';
+export interface InterruptTarget {
+    key: string;
+    conversationId: ConversationId;
+    expectedRunTaskId?: TaskId;
+}
+export type InterruptOutcome = 'interrupted' | 'ended' | 'failed' | 'retired';
+export type AbortRun = (api: Pick<DocumentReader, 'snapshot'>, target: InterruptTarget, context: Context) => Promise<InterruptOutcome>;
+/** Host primitive: exact native identity, cancellable wait, and no conversation-wide abort. */
+export declare function abortExpectedRun(harness: Harness, target: InterruptTarget, context: Context): Promise<InterruptOutcome>;

package/dist/authority/interrupt.js

@@ -0,0 +1,26 @@
+import { LiveDoc } from '@earendil-works/pi-durable';
+import { openAuthority as open, obligation } from "./store.js";
+import { eligible } from "./delivery.js";
+/** Host primitive: exact native identity, cancellable wait, and no conversation-wide abort. */
+export async function abortExpectedRun(harness, target, context) {
+    const check = await harness.commit(async (tx) => {
+        const s = await open(tx), o = await obligation(s, target.key);
+        if (!o || !await eligible(s, o) || o.conversationId !== target.conversationId || o.interruptRun !== target.expectedRunTaskId)
+            return 'retired';
+        if (target.expectedRunTaskId === undefined)
+            return 'ended';
+        const task = await tx.task(target.expectedRunTaskId), live = await tx.doc(LiveDoc, target.conversationId);
+        if (!task || task.conversationId !== target.conversationId)
+            return 'failed';
+        if (task.state.status === 'terminal')
+            return task.state.outcome.status === 'aborted' ? 'interrupted' : 'ended';
+        if (live.run?.taskId !== target.expectedRunTaskId)
+            return 'ended';
+        return 'abort';
+    }, context);
+    if (check !== 'abort')
+        return check;
+    await harness.abortTask(target.expectedRunTaskId, context);
+    const task = await harness.waitForTask(target.expectedRunTaskId, context);
+    return task.state.outcome.status === 'aborted' ? 'interrupted' : 'failed';
+}

package/dist/authority/limits.d.ts

@@ -0,0 +1,7 @@
+import { Type } from "typebox";
+/** Static card type defaults. contracts.ts applies the configured runtime goal limit. */
+export declare const TASK_CARD_GOAL_MAX_LENGTH = 1600;
+export declare const TASK_ID_MAX_LENGTH = 128;
+export declare const TASK_CARD_TITLE_MAX_LENGTH = 80;
+export declare const TASK_CARD_CONTEXT_MAX_LENGTH = 2000;
+export declare const TaskVersionRefSchema: Type.TString;

package/dist/authority/limits.js

@@ -0,0 +1,7 @@
+import { Type } from "typebox";
+/** Static card type defaults. contracts.ts applies the configured runtime goal limit. */
+export const TASK_CARD_GOAL_MAX_LENGTH = 1_600;
+export const TASK_ID_MAX_LENGTH = 128;
+export const TASK_CARD_TITLE_MAX_LENGTH = 80;
+export const TASK_CARD_CONTEXT_MAX_LENGTH = 2_000;
+export const TaskVersionRefSchema = Type.String({ pattern: "^v_[0-9a-f]{16}$", minLength: 18, maxLength: 18 });

package/dist/authority/notifier.d.ts

@@ -0,0 +1,32 @@
+import { type ConversationId, type Tx } from '@earendil-works/pi-durable';
+import { type Page } from './observation-store.ts';
+import { type ModelRoleCatalog } from './state.ts';
+import type { TeamNoticeData } from './delivery.ts';
+export declare const NOTIFY_RECHECK_MS = 1000;
+export declare const NOTIFY_DELAY_MS = 30000;
+/** The input a notifier page submits to the lead: a Team update that durable-team itself writes. */
+export declare function pageDraft(page: Page): {
+    type: "input";
+    content: string;
+    whenBusy: "followUp";
+    requestId: string;
+    entry: {
+        kind: string;
+        data: TeamNoticeData;
+    };
+};
+export declare function createNotifier(rolesOf: (tx: Tx, lead: ConversationId) => Promise<ModelRoleCatalog>): import("@earendil-works/pi-durable").Task<{
+    epoch: string;
+}, {
+    phase: "tick";
+    ordinal: number;
+    due?: number;
+} | {
+    phase: "submit";
+    pageId: string;
+    ordinal: number;
+} | {
+    phase: "settle";
+    pageId: string;
+    ordinal: number;
+}, null, object>;

package/dist/authority/notifier.js

@@ -0,0 +1,89 @@
+import { defineTask, LiveDoc } from '@earendil-works/pi-durable';
+import { openObservations, reserve, pages, page as loadPage, savePage } from "./observation-store.js";
+import { openAuthority as open } from "./store.js";
+import { snapshotResult } from "./projection.js";
+import { pageEvents, updates } from "./sync.js";
+export const NOTIFY_RECHECK_MS = 1000;
+export const NOTIFY_DELAY_MS = 30000;
+/** The input a notifier page submits to the lead: a Team update that durable-team itself writes. */
+export function pageDraft(page) {
+    const data = { source: 'team', pageId: page.id, epoch: page.epoch, delivery: 'update', sender: 'durable-team' };
+    const content = page.carrier.kind === 'input' ? page.carrier.text : page.body;
+    if (content === undefined)
+        throw new Error('PTB notifier page body is missing');
+    return { type: 'input', content, whenBusy: 'followUp', requestId: page.id, entry: { kind: 'team.notice', data } };
+}
+const draft = pageDraft;
+export function createNotifier(rolesOf) {
+    return defineTask({
+        name: 'ptb.notify', version: 1, initial: () => ({ phase: 'tick', ordinal: 1 }),
+        phases: {
+            tick: async (task, runtime, context) => {
+                await runtime.commit(async (tx) => {
+                    const s = await open(tx), team = s.team.current, o = await openObservations(tx);
+                    if (!team || team.epoch !== task.input.epoch || team.lifecycle !== 'active' || team.shutdownPending)
+                        return { status: 'terminal', outcome: { status: 'completed', result: null } };
+                    const live = await tx.doc(LiveDoc, team.lead);
+                    const pending = (await pages(o, 'openPages')).some(p => p.epoch === team.epoch);
+                    const checkpoint = task.state.checkpoint, due = checkpoint.due ?? runtime.now() + NOTIFY_DELAY_MS;
+                    if (o.head.paused || pending || live.run || s.journal.seq <= o.head.acknowledged || runtime.now() < due)
+                        return { status: 'sleeping', until: runtime.now() + NOTIFY_RECHECK_MS, checkpoint: { ...checkpoint, due } };
+                    const from = o.head.epoch === team.epoch ? o.head.acknowledged : 0;
+                    const previous = o.head.scanByEpoch[team.epoch];
+                    const change = from ? await pageEvents(tx, s, from, previous) : undefined;
+                    const roles = change ? undefined : await rolesOf(tx, team.lead);
+                    const result = change ? await updates(s, change.events) : await snapshotResult(s, roles.modelRoles, roles.defaultModelRole);
+                    const id = `${team.epoch}:notify:${runtime.taskId}:${checkpoint.ordinal}`;
+                    const text = JSON.stringify({ kind: 'team_update', page_id: id, result });
+                    const scanThrough = change?.scanThrough ?? s.journal.events.at(-1)?.entryId;
+                    await reserve(o, { id, epoch: team.epoch, lead: team.lead, run: 0, from, through: change ? change.events.at(-1)?.seq ?? from : s.journal.seq, carrier: { kind: 'input', text }, notifierId: runtime.taskId, ...(scanThrough ? { scanThrough } : {}) }, result);
+                    return { status: 'running', checkpoint: { phase: 'submit', pageId: id, ordinal: checkpoint.ordinal } };
+                }, context);
+            },
+            submit: async (task, runtime, context) => {
+                let page;
+                await runtime.commit(async (tx) => {
+                    const s = await open(tx), o = await openObservations(tx), p = await loadPage(o, task.state.checkpoint.pageId, true);
+                    if (!p || s.team.current?.epoch !== p.epoch || s.team.current?.shutdownPending || s.team.current?.lifecycle !== 'active')
+                        return { status: 'terminal', outcome: { status: 'completed', result: null } };
+                    page = p;
+                    return undefined;
+                }, context);
+                if (!page)
+                    return;
+                const target = await runtime.conversation(page.lead, context);
+                if (!target)
+                    throw new Error('PTB lead is missing');
+                const submission = await target.submit(draft(page), context);
+                await runtime.commit(async (tx) => { const o = await openObservations(tx), p = (await loadPage(o, page.id)); p.submissionId = submission.id; await savePage(o, p); return { status: 'running', checkpoint: { ...task.state.checkpoint, phase: 'settle' } }; }, context);
+            },
+            settle: async (task, runtime, context) => {
+                let page;
+                await runtime.commit(async (tx) => { page = (await loadPage(await openObservations(tx), task.state.checkpoint.pageId, true)); return undefined; }, context);
+                const target = await runtime.conversation(page.lead, context);
+                if (!target)
+                    throw new Error('PTB lead is missing');
+                const submission = await target.submit(draft(page), context);
+                if (submission.id !== page.submissionId)
+                    throw new Error('PTB notifier admission identity changed');
+                const settled = await submission.wait(context);
+                await runtime.commit(async (tx) => {
+                    const o = await openObservations(tx), p = (await loadPage(o, page.id));
+                    if (p.run === 0)
+                        p.run = submission.id;
+                    if (settled.status !== 'done') {
+                        p.state = 'released';
+                        o.head.paused = true;
+                    }
+                    await savePage(o, p);
+                    return { status: 'sleeping', until: runtime.now() + NOTIFY_RECHECK_MS, checkpoint: { phase: 'tick', ordinal: task.state.checkpoint.ordinal + 1 } };
+                }, context);
+            },
+        },
+        abort: async (task, runtime, context) => runtime.commit(async (tx) => { const o = await openObservations(tx); for (const p of await pages(o, 'openPages'))
+            if (p.epoch === task.input.epoch && p.carrier.kind === 'input') {
+                p.state = 'released';
+                await savePage(o, p);
+            } return { status: 'terminal', outcome: { status: 'aborted' } }; }, context),
+    });
+}

package/dist/authority/observation-store.d.ts

@@ -0,0 +1,104 @@
+import { type JsonObject, type Tx, type ConversationId, type TaskId, type SubmissionId, type EntryId } from '@earendil-works/pi-durable';
+import { type Result } from './state.ts';
+export type Carrier = {
+    kind: 'tool';
+    callId: string;
+} | {
+    kind: 'input';
+    text?: string;
+};
+export interface Page {
+    id: string;
+    epoch: string;
+    lead: ConversationId;
+    run: SubmissionId;
+    from: number;
+    through: number;
+    body?: string;
+    digest: string;
+    carrier: Carrier;
+    state: 'reserved' | 'presented' | 'released' | 'acknowledged' | 'replaced';
+    scanThrough?: EntryId;
+    submissionId?: SubmissionId;
+    notifierId?: TaskId;
+    pruned?: boolean;
+}
+export interface Proof {
+    generation: TaskId;
+    lead: ConversationId;
+    run: SubmissionId;
+    pages: string[];
+    responseDigest?: string;
+}
+export interface Observations {
+    pages: Record<string, Page>;
+    proofs: Record<string, Proof>;
+    acknowledged: number;
+    epoch?: string;
+    paused?: boolean;
+    resumedOwnerRun?: SubmissionId;
+}
+export declare const ObservationDoc: import("@earendil-works/pi-durable").SessionDocToken<JsonObject>;
+interface Head {
+    initialized: boolean;
+    legacyFenced?: boolean;
+    epoch?: string;
+    acknowledged: number;
+    paused?: boolean;
+    resumedOwnerRun?: SubmissionId;
+    ordinal: number;
+    pageTail?: string;
+    openPages: Record<string, number>;
+    releasedPages: Record<string, number>;
+    waitingAck: Record<string, number>;
+    prunePages: Record<string, number>;
+    openProofs: Record<string, true>;
+    ackByEpoch: Record<string, number>;
+    scanByEpoch: Record<string, EntryId>;
+    acknowledgedScanThrough?: EntryId;
+}
+export declare const ObservationHeadDoc: import("@earendil-works/pi-durable").SessionDocToken<JsonObject>;
+export declare const PageDoc: import("@earendil-works/pi-durable").SessionDocFamilyToken<JsonObject, null>, PageBodyDoc: import("@earendil-works/pi-durable").SessionDocFamilyToken<JsonObject, null>, ProofDoc: import("@earendil-works/pi-durable").SessionDocFamilyToken<JsonObject, null>;
+export interface ObservationStore {
+    tx: Tx;
+    head: Head;
+}
+export declare const digest: (value: unknown) => string;
+export declare function startObservationEpoch(s: ObservationStore, epoch: string): void;
+export declare function openObservations(tx: Tx): Promise<ObservationStore>;
+export declare function page(s: ObservationStore, id: string, withBody?: boolean): Promise<Page | undefined>;
+export declare function pages(s: ObservationStore, index: 'openPages' | 'releasedPages' | 'waitingAck' | 'prunePages', withBody?: boolean): Promise<Page[]>;
+export declare function savePage(s: ObservationStore, value: Page): Promise<void>;
+export declare function reserve(s: ObservationStore, input: Omit<Page, 'body' | 'digest' | 'state' | 'pruned'>, result: Result): Promise<Page>;
+export declare function reservationHead(s: ObservationStore, epoch: string, run: SubmissionId): Promise<number>;
+export declare function advanceAcknowledged(s: ObservationStore): Promise<void>;
+export declare function proof(s: ObservationStore, id: string): Promise<Proof | undefined>;
+export declare function openProofs(s: ObservationStore): Promise<Proof[]>;
+export declare function saveProof(s: ObservationStore, value: Proof): Promise<void>;
+export declare function retireProof(s: ObservationStore, id: string): Promise<void>;
+export declare function retireBody(s: ObservationStore, value: Page): Promise<void>;
+/** Diagnostic UTF-8 JSON bytes. Excludes native record metadata and history. */
+export declare function observationStats(tx: Tx): Promise<{
+    pages: {
+        count: number;
+        currentRecordBytes: number;
+    };
+    bodies: {
+        count: number;
+        currentRecordBytes: number;
+    };
+    openProofs: {
+        count: number;
+        currentRecordBytes: number;
+    };
+    headBytes: number;
+    totalBytes: number;
+}>;
+/** Explicit diagnostic projection. Runtime paths read the current indexes. */
+export declare function observations(tx: Tx): Promise<Observations>;
+/** Owner reads use only pages at or below the acknowledged cursor. This read never advances it. */
+export declare function readObservationCursor(tx: Tx, epoch: string): Promise<{
+    acknowledged: number;
+    scanThrough?: EntryId;
+}>;
+export {};

package/dist/authority/observation-store.js

@@ -0,0 +1,226 @@
+// Observation authority separates current indexes, immutable page bodies, and proofs.
+// Settled pages retain metadata. Only the observer can retire bodies and proofs.
+import { defineDoc, defineDocFamily } from '@earendil-works/pi-durable';
+import { createHash } from 'node:crypto';
+import { fenceLegacyDoc, hasLegacyFence } from "./state.js";
+export const ObservationDoc = defineDoc({ kind: 'ptb.observation', version: 2, migrate: value => value, scope: 'session', initial: () => ({ pages: {}, proofs: {}, acknowledged: 0 }), checkpointWhen: () => true });
+export const ObservationHeadDoc = defineDoc({ kind: 'ptb.observation.head', version: 1, scope: 'session', initial: () => ({ initialized: false, acknowledged: 0, ordinal: 0, openPages: {}, releasedPages: {}, waitingAck: {}, prunePages: {}, openProofs: {}, ackByEpoch: {}, scanByEpoch: {} }), checkpointWhen: () => true });
+const family = (kind) => defineDocFamily({ kind, version: 1, scope: 'session', family: true, initial: () => ({}), checkpointWhen: () => true });
+export const PageDoc = family('ptb.observation.page'), PageBodyDoc = family('ptb.observation.body'), ProofDoc = family('ptb.observation.proof');
+const transactions = new WeakMap();
+export const digest = (value) => createHash('sha256').update(typeof value === 'string' ? value : JSON.stringify(value)).digest('hex');
+const copyPage = (page) => ({ ...page, carrier: { ...page.carrier } });
+const copyProof = (proof) => ({ ...proof, pages: [...proof.pages] });
+export function startObservationEpoch(s, epoch) {
+    const h = s.head;
+    if (h.epoch === epoch)
+        return;
+    if (h.epoch)
+        h.ackByEpoch[h.epoch] = h.acknowledged;
+    h.epoch = epoch;
+    h.acknowledged = h.ackByEpoch[epoch] ?? 0;
+    delete h.acknowledgedScanThrough;
+    h.paused = false;
+}
+export async function openObservations(tx) {
+    const cached = transactions.get(tx);
+    if (cached)
+        return cached;
+    const head = await tx.doc(ObservationHeadDoc), s = { tx, head };
+    transactions.set(tx, s);
+    if (!head.initialized) {
+        const old = await tx.doc(ObservationDoc);
+        if (hasLegacyFence(old))
+            throw new Error('Observation index is missing after authority cutover.');
+        if (old.epoch) {
+            head.epoch = old.epoch;
+            head.ackByEpoch[old.epoch] = old.acknowledged;
+        }
+        head.acknowledged = old.acknowledged;
+        if (old.paused !== undefined)
+            head.paused = old.paused;
+        if (old.resumedOwnerRun !== undefined)
+            head.resumedOwnerRun = old.resumedOwnerRun;
+        for (const value of Object.values(old.pages)) {
+            const page = copyPage(value);
+            if (typeof page.body !== 'string')
+                throw new Error('Legacy observation page body is missing.');
+            if (page.carrier.kind === 'input') {
+                const prefix = `${page.epoch}:notify:`, suffix = page.id.startsWith(prefix) ? page.id.slice(prefix.length).split(':') : [];
+                if (suffix.length === 2 && /^\d+$/.test(suffix[0]) && /^\d+$/.test(suffix[1]))
+                    page.notifierId = Number(suffix[0]);
+            }
+            await createPage(s, page);
+        }
+        for (const value of Object.values(old.proofs)) {
+            const { generation, lead, run, pages, responseDigest } = value;
+            if (pages.length)
+                await saveProof(s, { generation, lead, run, pages: [...pages], ...(responseDigest ? { responseDigest } : {}) });
+        }
+        await advanceAcknowledged(s);
+        if (old.epoch) {
+            head.ackByEpoch[old.epoch] = Math.max(head.ackByEpoch[old.epoch] ?? 0, old.acknowledged);
+            head.acknowledged = head.ackByEpoch[old.epoch];
+        }
+        head.initialized = true;
+    }
+    if (!head.legacyFenced) {
+        fenceLegacyDoc(await tx.doc(ObservationDoc));
+        head.legacyFenced = true;
+    }
+    return s;
+}
+export async function page(s, id, withBody = false) {
+    const record = await s.tx.doc(PageDoc, id, null);
+    if (!record.value)
+        return;
+    const value = copyPage(record.value);
+    if (withBody && !value.pruned) {
+        const body = await s.tx.doc(PageBodyDoc, id, null);
+        if (typeof body.body !== 'string' || !body.carrier)
+            throw new Error('Observation page body is missing.');
+        value.body = body.body;
+        value.carrier = { ...body.carrier };
+    }
+    return value;
+}
+export async function pages(s, index, withBody = false) {
+    const ids = Object.entries(s.head[index]).sort((a, b) => a[1] - b[1]).map(([id]) => id);
+    return (await Promise.all(ids.map(id => page(s, id, withBody)))).filter((p) => !!p);
+}
+export async function savePage(s, value) {
+    const doc = await s.tx.doc(PageDoc, value.id, null), h = s.head;
+    if (!doc.value) {
+        if (h.pageTail)
+            doc.previous = h.pageTail;
+        doc.order = ++h.ordinal;
+        h.pageTail = value.id;
+    }
+    const { body: _body, carrier, ...meta } = value;
+    doc.value = { ...meta, carrier: carrier.kind === 'input' ? { kind: 'input' } : { ...carrier } };
+    const order = Number(doc.order);
+    for (const name of ['openPages', 'releasedPages', 'waitingAck', 'prunePages'])
+        delete h[name][value.id];
+    if (value.state === 'reserved' || value.state === 'presented')
+        h.openPages[value.id] = order;
+    if (value.state === 'released')
+        h.releasedPages[value.id] = order;
+    if (value.state === 'acknowledged') {
+        if (value.through > (h.ackByEpoch[value.epoch] ?? 0))
+            h.waitingAck[value.id] = order;
+        if (value.scanThrough !== undefined) {
+            h.scanByEpoch[value.epoch] = Math.max(h.scanByEpoch[value.epoch] ?? 0, value.scanThrough);
+            if (value.epoch === h.epoch && value.through <= (h.ackByEpoch[value.epoch] ?? 0))
+                h.acknowledgedScanThrough = Math.max(h.acknowledgedScanThrough ?? 0, value.scanThrough);
+        }
+    }
+    if (!value.pruned && (value.state === 'acknowledged' || value.state === 'replaced'))
+        h.prunePages[value.id] = order;
+}
+async function createPage(s, value) {
+    const doc = await s.tx.doc(PageBodyDoc, value.id, null);
+    doc.body = value.body;
+    doc.carrier = { ...value.carrier };
+    await savePage(s, value);
+}
+export async function reserve(s, input, result) {
+    startObservationEpoch(s, input.epoch);
+    const prior = await page(s, input.id, true);
+    if (prior)
+        return prior;
+    const body = JSON.stringify(result), value = { ...input, body, digest: digest(body), state: 'reserved' };
+    await createPage(s, value);
+    return value;
+}
+export async function reservationHead(s, epoch, run) {
+    return Math.max(s.head.epoch === epoch ? s.head.acknowledged : 0, ...(await pages(s, 'openPages')).filter(p => p.epoch === epoch && p.run === run).map(p => p.through));
+}
+export async function advanceAcknowledged(s) {
+    const waiting = await pages(s, 'waitingAck'), h = s.head;
+    for (let advanced = true; advanced;) {
+        advanced = false;
+        for (const p of waiting) {
+            const cursor = h.ackByEpoch[p.epoch] ?? 0;
+            if (p.from <= cursor && p.through > cursor) {
+                h.ackByEpoch[p.epoch] = p.through;
+                advanced = true;
+            }
+        }
+    }
+    // Fold newly reachable anchors before removing their pages from the waiting index.
+    for (const p of waiting)
+        if (p.through <= (h.ackByEpoch[p.epoch] ?? 0)) {
+            if (p.epoch === h.epoch && p.scanThrough !== undefined)
+                h.acknowledgedScanThrough = Math.max(h.acknowledgedScanThrough ?? 0, p.scanThrough);
+            delete h.waitingAck[p.id];
+        }
+    if (h.epoch)
+        h.acknowledged = h.ackByEpoch[h.epoch] ?? 0;
+}
+export async function proof(s, id) {
+    if (!s.head.openProofs[id])
+        return;
+    const value = (await s.tx.doc(ProofDoc, id, null)).value;
+    return value ? copyProof(value) : undefined;
+}
+export async function openProofs(s) {
+    return (await Promise.all(Object.keys(s.head.openProofs).map(id => proof(s, id)))).filter((p) => !!p);
+}
+export async function saveProof(s, value) {
+    (await s.tx.doc(ProofDoc, String(value.generation), null)).value = copyProof(value);
+    s.head.openProofs[String(value.generation)] = true;
+}
+export async function retireProof(s, id) {
+    if (!s.head.openProofs[id])
+        return;
+    delete s.head.openProofs[id];
+    await s.tx.retireDoc(ProofDoc, id);
+}
+export async function retireBody(s, value) {
+    await s.tx.retireDoc(PageBodyDoc, value.id);
+    value.pruned = true;
+    delete value.body;
+    if (value.carrier.kind === 'input')
+        delete value.carrier.text;
+    await savePage(s, value);
+}
+/** Diagnostic UTF-8 JSON bytes. Excludes native record metadata and history. */
+export async function observationStats(tx) {
+    const s = await openObservations(tx), bytes = (value) => Buffer.byteLength(JSON.stringify(value));
+    const result = { pages: { count: 0, currentRecordBytes: 0 }, bodies: { count: 0, currentRecordBytes: 0 }, openProofs: { count: 0, currentRecordBytes: 0 }, headBytes: bytes(s.head), totalBytes: 0 };
+    let id = s.head.pageTail;
+    while (id) {
+        const record = await tx.doc(PageDoc, id, null), value = record.value;
+        result.pages.count++;
+        result.pages.currentRecordBytes += bytes(record);
+        if (!value.pruned) {
+            result.bodies.count++;
+            result.bodies.currentRecordBytes += bytes(await tx.doc(PageBodyDoc, id, null));
+        }
+        id = record.previous;
+    }
+    for (const id of Object.keys(s.head.openProofs)) {
+        result.openProofs.count++;
+        result.openProofs.currentRecordBytes += bytes(await tx.doc(ProofDoc, id, null));
+    }
+    result.totalBytes = result.headBytes + result.pages.currentRecordBytes + result.bodies.currentRecordBytes + result.openProofs.currentRecordBytes;
+    return result;
+}
+/** Explicit diagnostic projection. Runtime paths read the current indexes. */
+export async function observations(tx) {
+    const s = await openObservations(tx), all = [];
+    let id = s.head.pageTail;
+    while (id) {
+        const record = await tx.doc(PageDoc, id, null);
+        const value = await page(s, id, true);
+        if (value)
+            all.push(value);
+        id = record.previous;
+    }
+    return { pages: Object.fromEntries(all.reverse().map(p => [p.id, p])), proofs: Object.fromEntries((await openProofs(s)).map(p => [String(p.generation), p])), acknowledged: s.head.acknowledged, ...(s.head.epoch ? { epoch: s.head.epoch } : {}), ...(s.head.paused === undefined ? {} : { paused: s.head.paused }), ...(s.head.resumedOwnerRun === undefined ? {} : { resumedOwnerRun: s.head.resumedOwnerRun }) };
+}
+/** Owner reads use only pages at or below the acknowledged cursor. This read never advances it. */
+export async function readObservationCursor(tx, epoch) {
+    const head = await tx.doc(ObservationHeadDoc);
+    return head.epoch === epoch ? { acknowledged: head.acknowledged, ...(head.acknowledgedScanThrough === undefined ? {} : { scanThrough: head.acknowledgedScanThrough }) } : { acknowledged: 0 };
+}

package/dist/authority/observation.d.ts

@@ -0,0 +1,13 @@
+import type { Context } from '@earendil-works/chord/context';
+import type { AssistantMessage } from '@earendil-works/pi-ai';
+import { type Harness, type Tx, type HookApi, type Extension } from '@earendil-works/pi-durable';
+export { ObservationDoc, ObservationHeadDoc, PageDoc, PageBodyDoc, ProofDoc, observations, observationStats, openObservations, reservationHead, reserve, startObservationEpoch, digest, type Page, type Observations } from './observation-store.ts';
+export interface ObservationPort {
+    commit<T>(fn: (tx: Tx) => Promise<T>, context: Context): Promise<T>;
+}
+/** Install last among message-replacing hooks. No hook advances the acknowledged cursor. */
+export type ObservationPortResolver = (api: HookApi, context: Context) => Promise<ObservationPort>;
+export declare function observationExtension(resolvePort: ObservationPortResolver): Extension;
+export declare function recordResponse(port: ObservationPort, api: Pick<HookApi, 'taskId'>, message: AssistantMessage, context: Context): Promise<void>;
+/** Native persistence and settled runs permit ACK. Proofs never scan transcript history. */
+export declare function observe(harness: Harness, context: Context): Promise<void>;