@zhin.js/harness 0.0.0-stage → 0.0.0

package/lib/journal.js

@@ -0,0 +1,712 @@
+/**
+ * Engagement journal implementations (ADR 0048 §3.5).
+ *
+ * Depends on `contracts.ts` only. The database store targets a narrow query
+ * interface (`EngagementJournalDatabase`) that `@zhin.js/database` satisfies,
+ * so the host registers `ENGAGEMENT_EVENT_MODEL` and passes its database in.
+ */
+import { BUDGET_KEYS, DEFAULT_JOURNAL_RETENTION, JournalFullError, } from './contracts.js';
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+/** Deep-copies a JSON value, throwing TypeError for anything JSON cannot round-trip. */
+function cloneJson(value, path, seen) {
+    if (value === null)
+        return null;
+    switch (typeof value) {
+        case 'string':
+        case 'boolean':
+            return value;
+        case 'number':
+            if (!Number.isFinite(value))
+                throw new TypeError(`Journal data at ${path} is not a finite number`);
+            return value;
+        case 'object':
+            break;
+        default:
+            throw new TypeError(`Journal data at ${path} is not JSON-serializable (${typeof value})`);
+    }
+    const obj = value;
+    if (seen.has(obj))
+        throw new TypeError(`Journal data at ${path} contains a cycle`);
+    seen.add(obj);
+    try {
+        if (Array.isArray(obj)) {
+            return obj.map((item, i) => cloneJson(item, `${path}[${i}]`, seen));
+        }
+        const proto = Object.getPrototypeOf(obj);
+        if (proto !== Object.prototype && proto !== null) {
+            throw new TypeError(`Journal data at ${path} is not a plain object`);
+        }
+        const out = {};
+        for (const [key, item] of Object.entries(obj)) {
+            out[key] = cloneJson(item, `${path}.${key}`, seen);
+        }
+        return out;
+    }
+    finally {
+        seen.delete(obj);
+    }
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const item of Object.values(value))
+            deepFreeze(item);
+    }
+    return value;
+}
+function buildEvent(input, seq, data) {
+    return deepFreeze({
+        engagementId: input.engagementId,
+        seq,
+        at: input.at,
+        type: input.type,
+        data,
+    });
+}
+function validateInput(input) {
+    if (typeof input.engagementId !== 'string' || input.engagementId === '') {
+        throw new TypeError('engagementId must be a non-empty string');
+    }
+    if (!Number.isFinite(input.at))
+        throw new TypeError('at must be a finite number');
+    const data = cloneJson(input.data, 'data', new Set());
+    if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+        throw new TypeError('data must be a JSON object');
+    }
+    return data;
+}
+/** Runs tasks one at a time per key, in call order. */
+class KeyedSerializer {
+    #tails = new Map();
+    run(key, task) {
+        const prev = this.#tails.get(key) ?? Promise.resolve();
+        const result = prev.then(task, task);
+        const tail = result.catch(() => undefined);
+        this.#tails.set(key, tail);
+        void tail.then(() => {
+            if (this.#tails.get(key) === tail)
+                this.#tails.delete(key);
+        });
+        return result;
+    }
+}
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function recordPayload(record) {
+    const data = isPlainRecord(record.data) ? record.data : {};
+    const event = isPlainRecord(record.event) ? record.event : {};
+    return { ...event, ...data };
+}
+function recordType(record) {
+    if (typeof record.type === 'string' && record.type)
+        return record.type;
+    if (isPlainRecord(record.event) && typeof record.event.type === 'string')
+        return record.event.type;
+    return '';
+}
+function isActorRef(value) {
+    return (typeof value === 'string'
+        && value.length > 0
+        && !value.startsWith('human:')
+        && !value.startsWith('system:')
+        && value !== 'human'
+        && value !== 'system');
+}
+/** Reconstructs blackboard entries from a sequence of journal records. */
+export function reconstructBoardFromEvents(records, filter) {
+    const byKey = new Map();
+    for (const record of records) {
+        if (recordType(record) !== 'board_written')
+            continue;
+        const payload = recordPayload(record);
+        const key = typeof payload.key === 'string' ? payload.key.trim() : '';
+        if (!key)
+            continue;
+        const prev = byKey.get(key);
+        const kind = payload.kind === 'artifact' || payload.kind === 'todo' || payload.kind === 'note'
+            ? payload.kind
+            : prev?.kind ?? 'note';
+        const content = typeof payload.content === 'string' ? payload.content : prev?.content ?? '';
+        const author = typeof payload.actor === 'string'
+            ? payload.actor
+            : typeof payload.author === 'string'
+                ? payload.author
+                : prev?.author ?? '';
+        const version = typeof payload.version === 'number' && Number.isFinite(payload.version)
+            ? payload.version
+            : (prev?.version ?? 0) + 1;
+        const status = payload.status === 'pending' || payload.status === 'in_progress' || payload.status === 'done'
+            ? payload.status
+            : prev?.status;
+        byKey.set(key, deepFreeze({
+            key,
+            kind,
+            content,
+            author,
+            updatedAt: record.at,
+            version,
+            ...(status !== undefined ? { status } : {}),
+        }));
+    }
+    const entries = [...byKey.values()].filter((entry) => {
+        if (filter?.key !== undefined && entry.key !== filter.key)
+            return false;
+        if (filter?.kind !== undefined && entry.kind !== filter.kind)
+            return false;
+        return true;
+    });
+    return Object.freeze(entries);
+}
+/** Pure helper that summarizes an engagement's journal records into a collaboration graph and metrics. */
+export function summarizeEngagementEvents(engagementId, records) {
+    let initiator;
+    let venue;
+    let startedAt = records[0]?.at ?? 0;
+    let endedAt;
+    let closedStatus;
+    let reason;
+    let toolCallCount = 0;
+    const actors = [];
+    const seenActors = new Set();
+    const addActor = (actor) => {
+        if (isActorRef(actor) && !seenActors.has(actor)) {
+            seenActors.add(actor);
+            actors.push(actor);
+        }
+    };
+    const guardBlocks = [];
+    const escalations = [];
+    const projections = [];
+    const consumed = { modelCalls: 0, tokens: 0, wallMs: 0, sideEffects: 0 };
+    let closedSpent;
+    const hopsById = new Map();
+    const hopOrder = [];
+    const seenMailIds = new Set();
+    let anonymousMailCount = 0;
+    for (const record of records) {
+        const type = recordType(record);
+        const payload = recordPayload(record);
+        switch (type) {
+            case 'engagement_opened': {
+                startedAt = record.at;
+                if (isPlainRecord(payload.initiator) && typeof payload.initiator.id === 'string') {
+                    initiator = payload.initiator;
+                }
+                else if (isPlainRecord(payload.principal) && typeof payload.principal.id === 'string') {
+                    initiator = payload.principal;
+                }
+                else if (typeof payload.principal === 'string' && payload.principal) {
+                    initiator = {
+                        kind: 'human',
+                        id: payload.principal,
+                        trust: 'group_member',
+                    };
+                }
+                if (isPlainRecord(payload.venue) && typeof payload.venue.kind === 'string' && typeof payload.venue.id === 'string') {
+                    venue = { kind: payload.venue.kind, id: payload.venue.id };
+                }
+                addActor(payload.entry);
+                break;
+            }
+            case 'mail_admitted':
+            case 'mail_sent': {
+                const mailId = typeof payload.mailId === 'string' ? payload.mailId : '';
+                const kind = (typeof payload.kind === 'string' ? payload.kind : 'ask');
+                const from = typeof payload.from === 'string' ? payload.from : '';
+                const to = typeof payload.to === 'string' ? payload.to : '';
+                const causationId = typeof payload.causationId === 'string' && payload.causationId ? payload.causationId : undefined;
+                addActor(from);
+                addActor(to);
+                if (mailId) {
+                    seenMailIds.add(mailId);
+                    if (!hopsById.has(mailId)) {
+                        hopsById.set(mailId, {
+                            mailId,
+                            kind,
+                            from,
+                            to,
+                            ...(causationId !== undefined ? { causationId } : {}),
+                            status: 'sent',
+                        });
+                        hopOrder.push(mailId);
+                    }
+                    if (kind === 'result' && causationId) {
+                        const parentHop = hopsById.get(causationId);
+                        if (parentHop) {
+                            parentHop.status = payload.status === 'cancelled' ? 'cancelled' : 'completed';
+                        }
+                    }
+                }
+                else {
+                    anonymousMailCount++;
+                }
+                break;
+            }
+            case 'turn_started':
+            case 'mail_delivered': {
+                addActor(payload.actor);
+                const ids = [];
+                if (typeof payload.mailId === 'string')
+                    ids.push(payload.mailId);
+                if (Array.isArray(payload.mails)) {
+                    for (const id of payload.mails)
+                        if (typeof id === 'string')
+                            ids.push(id);
+                }
+                for (const id of ids) {
+                    const hop = hopsById.get(id);
+                    if (hop && hop.status === 'sent')
+                        hop.status = 'delivered';
+                }
+                break;
+            }
+            case 'turn_finished':
+            case 'mail_completed': {
+                addActor(payload.actor);
+                const nextStatus = payload.status === 'cancelled' ? 'cancelled' : 'completed';
+                const ids = [];
+                if (typeof payload.mailId === 'string')
+                    ids.push(payload.mailId);
+                if (Array.isArray(payload.mails)) {
+                    for (const id of payload.mails)
+                        if (typeof id === 'string')
+                            ids.push(id);
+                }
+                for (const id of ids) {
+                    const hop = hopsById.get(id);
+                    if (hop)
+                        hop.status = nextStatus;
+                }
+                break;
+            }
+            case 'mail_cancelled': {
+                const mailId = typeof payload.mailId === 'string' ? payload.mailId : '';
+                const hop = mailId ? hopsById.get(mailId) : undefined;
+                if (hop)
+                    hop.status = 'cancelled';
+                break;
+            }
+            case 'tool_called': {
+                toolCallCount++;
+                addActor(payload.actor);
+                break;
+            }
+            case 'board_written': {
+                addActor(payload.actor ?? payload.author);
+                break;
+            }
+            case 'guard_blocked':
+            case 'mail_denied': {
+                const from = typeof payload.from === 'string'
+                    ? payload.from
+                    : typeof payload.actor === 'string'
+                        ? payload.actor
+                        : '';
+                const to = typeof payload.to === 'string' ? payload.to : undefined;
+                addActor(from);
+                addActor(to);
+                const blockReason = isPlainRecord(payload.reason) && typeof payload.reason.code === 'string'
+                    ? {
+                        code: payload.reason.code,
+                        ...(typeof payload.reason.detail === 'string' ? { detail: payload.reason.detail } : {}),
+                    }
+                    : {
+                        code: typeof payload.code === 'string' ? payload.code : 'denied',
+                        ...(typeof payload.reason === 'string' ? { detail: payload.reason } : {}),
+                    };
+                guardBlocks.push({
+                    from,
+                    ...(to !== undefined ? { to } : {}),
+                    reason: blockReason,
+                    at: record.at,
+                });
+                break;
+            }
+            case 'escalated': {
+                const by = typeof payload.by === 'string'
+                    ? payload.by
+                    : typeof payload.from === 'string'
+                        ? payload.from
+                        : typeof payload.actor === 'string'
+                            ? payload.actor
+                            : '';
+                addActor(by);
+                const escReason = typeof payload.reason === 'string' ? payload.reason : '';
+                escalations.push({ by, reason: escReason, at: record.at });
+                break;
+            }
+            case 'venue_projected': {
+                addActor(payload.actor);
+                if (isPlainRecord(payload.venue) && typeof payload.venue.kind === 'string' && typeof payload.venue.id === 'string') {
+                    projections.push({
+                        venue: { kind: payload.venue.kind, id: payload.venue.id },
+                        actor: typeof payload.actor === 'string' ? payload.actor : '',
+                        mailId: typeof payload.mailId === 'string' ? payload.mailId : '',
+                        mode: payload.mode === 'summary' ? 'summary' : 'visible',
+                        at: record.at,
+                    });
+                }
+                break;
+            }
+            case 'budget_charged': {
+                const usage = isPlainRecord(payload.usage)
+                    ? payload.usage
+                    : isPlainRecord(payload.amount)
+                        ? payload.amount
+                        : isPlainRecord(payload.consumed)
+                            ? payload.consumed
+                            : payload;
+                for (const key of BUDGET_KEYS) {
+                    const val = usage[key];
+                    if (typeof val === 'number' && Number.isFinite(val) && val > 0) {
+                        consumed[key] += val;
+                    }
+                }
+                break;
+            }
+            case 'engagement_closed': {
+                endedAt = record.at;
+                if (payload.status === 'completed'
+                    || payload.status === 'escalated'
+                    || payload.status === 'cancelled'
+                    || payload.status === 'blocked') {
+                    closedStatus = payload.status;
+                }
+                if (typeof payload.reason === 'string') {
+                    reason = payload.reason;
+                }
+                if (isPlainRecord(payload.budget) && isPlainRecord(payload.budget.spent)) {
+                    closedSpent = payload.budget.spent;
+                }
+                else if (isPlainRecord(payload.consumed)) {
+                    closedSpent = payload.consumed;
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    if (closedSpent) {
+        for (const key of BUDGET_KEYS) {
+            const val = closedSpent[key];
+            if (typeof val === 'number' && Number.isFinite(val)) {
+                consumed[key] = Math.max(consumed[key], val);
+            }
+        }
+    }
+    const status = closedStatus
+        ?? (endedAt !== undefined
+            ? escalations.length > 0
+                ? 'escalated'
+                : 'completed'
+            : escalations.length > 0
+                ? 'escalated'
+                : 'open');
+    if (reason === undefined && escalations.length > 0) {
+        reason = escalations[escalations.length - 1]?.reason;
+    }
+    const boardEntries = reconstructBoardFromEvents(records);
+    const hops = [];
+    for (const id of hopOrder) {
+        const hop = hopsById.get(id);
+        if (hop)
+            hops.push({ ...hop });
+    }
+    return deepFreeze({
+        engagementId,
+        ...(initiator !== undefined ? { initiator } : {}),
+        ...(venue !== undefined ? { venue } : {}),
+        startedAt,
+        ...(endedAt !== undefined ? { endedAt } : {}),
+        status,
+        ...(reason !== undefined ? { reason } : {}),
+        actors,
+        mailCount: seenMailIds.size + anonymousMailCount,
+        toolCallCount,
+        boardEntries,
+        guardBlocks,
+        escalations,
+        projections,
+        consumed,
+        hops,
+    });
+}
+const COMPACTABLE_EVENT_TYPES = new Set([
+    'budget_charged',
+    'budget_granted',
+    'mail_delivered',
+    'turn_started',
+]);
+function compactRecordList(engagementId, records) {
+    if (records.length <= 20)
+        return undefined;
+    let closedRecord;
+    for (const record of records) {
+        const type = recordType(record);
+        if (type === 'guard_blocked' || type === 'mail_denied' || type === 'escalated') {
+            return undefined;
+        }
+        if (type === 'engagement_closed') {
+            closedRecord = record;
+        }
+    }
+    if (!closedRecord)
+        return undefined;
+    const closedStatus = closedRecord.data.status;
+    if (closedStatus !== undefined && closedStatus !== 'completed') {
+        return undefined;
+    }
+    const summary = summarizeEngagementEvents(engagementId, records);
+    const filtered = records.filter((record) => !COMPACTABLE_EVENT_TYPES.has(recordType(record)));
+    if (filtered.length === records.length)
+        return undefined;
+    return filtered.map((record, index) => {
+        const data = record === closedRecord
+            ? cloneJson({
+                ...record.data,
+                status: 'completed',
+                consumed: summary.consumed,
+            }, 'data', new Set())
+            : cloneJson(record.data, 'data', new Set());
+        return buildEvent({ engagementId: record.engagementId, at: record.at, type: record.type, data }, index, data);
+    });
+}
+// ---------------------------------------------------------------------------
+// In-memory
+// ---------------------------------------------------------------------------
+export class InMemoryEngagementJournal {
+    #retention;
+    #events = new Map();
+    #serial = new KeyedSerializer();
+    constructor(options = {}) {
+        this.#retention = options.retention ?? DEFAULT_JOURNAL_RETENTION;
+    }
+    append(event) {
+        let data;
+        try {
+            data = validateInput(event);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        const input = { ...event };
+        return this.#serial.run(input.engagementId, async () => {
+            const list = this.#events.get(input.engagementId) ?? [];
+            if (list.length >= this.#retention.maxEventsPerEngagement) {
+                throw new JournalFullError(input.engagementId, this.#retention.maxEventsPerEngagement);
+            }
+            const stored = buildEvent(input, list.length, data);
+            list.push(stored);
+            this.#events.set(input.engagementId, list);
+            return stored;
+        });
+    }
+    async read(engagementId) {
+        return Object.freeze([...(this.#events.get(engagementId) ?? [])]);
+    }
+    async prune(now) {
+        const cutoff = now - this.#retention.maxAgeMs;
+        let removed = 0;
+        for (const [id, list] of this.#events) {
+            const last = list[list.length - 1];
+            if (last !== undefined && last.at < cutoff) {
+                this.#events.delete(id);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    async listEngagements(limit) {
+        const entries = [];
+        let order = 0;
+        for (const [id, list] of this.#events) {
+            const last = list[list.length - 1];
+            if (!last)
+                continue;
+            const lastAt = last.at;
+            entries.push({ id, lastAt, order: order++ });
+        }
+        entries.sort((a, b) => (b.lastAt !== a.lastAt ? b.lastAt - a.lastAt : b.order - a.order));
+        const ids = entries.map((entry) => entry.id);
+        return Object.freeze(limit !== undefined ? ids.slice(0, Math.max(0, limit)) : ids);
+    }
+    async summarize(engagementId) {
+        const records = await this.read(engagementId);
+        if (records.length === 0)
+            return undefined;
+        return summarizeEngagementEvents(engagementId, records);
+    }
+    async compact(engagementId) {
+        await this.#serial.run(engagementId, async () => {
+            const list = this.#events.get(engagementId);
+            if (!list)
+                return;
+            const compacted = compactRecordList(engagementId, list);
+            if (compacted) {
+                this.#events.set(engagementId, [...compacted]);
+            }
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Database-backed
+// ---------------------------------------------------------------------------
+export const ENGAGEMENT_EVENTS_TABLE = 'engagement_events';
+/**
+ * Table schema. `id` (`<engagement_id>:<seq>`) is the primary key and therefore
+ * the unique (engagement_id, seq) constraint: `@zhin.js/database` column
+ * definitions have no composite unique key.
+ */
+export const ENGAGEMENT_EVENT_MODEL = {
+    id: { type: 'text', primary: true, nullable: false },
+    engagement_id: { type: 'text', nullable: false },
+    seq: { type: 'integer', nullable: false },
+    at: { type: 'bigint', nullable: false },
+    type: { type: 'text', nullable: false },
+    data: { type: 'text', nullable: false },
+};
+/** Registers the table on a `@zhin.js/database` instance. */
+export function defineEngagementEventModel(database) {
+    database.define(ENGAGEMENT_EVENTS_TABLE, ENGAGEMENT_EVENT_MODEL);
+}
+export class DatabaseEngagementJournal {
+    #db;
+    #retention;
+    #maxRetries;
+    #serial = new KeyedSerializer();
+    constructor(database, options = {}) {
+        this.#db = database;
+        this.#retention = options.retention ?? DEFAULT_JOURNAL_RETENTION;
+        this.#maxRetries = options.maxConflictRetries ?? 5;
+    }
+    append(event) {
+        let data;
+        try {
+            data = validateInput(event);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        const input = { ...event };
+        return this.#serial.run(input.engagementId, async () => {
+            const json = JSON.stringify(data);
+            let lastError;
+            for (let attempt = 0; attempt <= this.#maxRetries; attempt++) {
+                const seq = await this.#nextSeq(input.engagementId);
+                if (seq >= this.#retention.maxEventsPerEngagement) {
+                    throw new JournalFullError(input.engagementId, this.#retention.maxEventsPerEngagement);
+                }
+                try {
+                    await this.#db.insert(ENGAGEMENT_EVENTS_TABLE, {
+                        id: `${input.engagementId}:${seq}`,
+                        engagement_id: input.engagementId,
+                        seq,
+                        at: input.at,
+                        type: input.type,
+                        data: json,
+                    });
+                    return buildEvent(input, seq, JSON.parse(json));
+                }
+                catch (error) {
+                    lastError = error;
+                    // A unique-key conflict means another writer took this seq: re-read and retry.
+                    // If the max seq did not advance, the failure was something else.
+                    if ((await this.#nextSeq(input.engagementId)) <= seq)
+                        throw error;
+                }
+            }
+            throw lastError;
+        });
+    }
+    async read(engagementId) {
+        const rows = await this.#db
+            .select(ENGAGEMENT_EVENTS_TABLE, ['engagement_id', 'seq', 'at', 'type', 'data'])
+            .where({ engagement_id: engagementId });
+        return Object.freeze(rows
+            .map(row => ({ row, seq: Number(row.seq) }))
+            .sort((a, b) => a.seq - b.seq)
+            .map(({ row, seq }) => buildEvent({ engagementId, at: Number(row.at), type: row.type, data: {} }, seq, JSON.parse(String(row.data)))));
+    }
+    async prune(now) {
+        const cutoff = now - this.#retention.maxAgeMs;
+        const rows = await this.#db
+            .select(ENGAGEMENT_EVENTS_TABLE, ['engagement_id', 'at'])
+            .where({});
+        const lastAt = new Map();
+        for (const row of rows) {
+            const id = String(row.engagement_id);
+            lastAt.set(id, Math.max(lastAt.get(id) ?? -Infinity, Number(row.at)));
+        }
+        let removed = 0;
+        for (const [id, last] of lastAt) {
+            if (last >= cutoff)
+                continue;
+            await this.#serial.run(id, async () => {
+                await this.#db.delete(ENGAGEMENT_EVENTS_TABLE, { engagement_id: id });
+            });
+            removed++;
+        }
+        return removed;
+    }
+    async listEngagements(limit) {
+        const rows = await this.#db
+            .select(ENGAGEMENT_EVENTS_TABLE, ['engagement_id', 'at', 'seq'])
+            .where({});
+        const meta = new Map();
+        let order = 0;
+        for (const row of rows) {
+            const id = String(row.engagement_id);
+            const at = Number(row.at);
+            const existing = meta.get(id);
+            if (!existing) {
+                meta.set(id, { lastAt: at, order: order++ });
+            }
+            else {
+                if (at >= existing.lastAt)
+                    existing.lastAt = at;
+                existing.order = order++;
+            }
+        }
+        const entries = [...meta.entries()].sort(([, a], [, b]) => b.lastAt !== a.lastAt ? b.lastAt - a.lastAt : b.order - a.order);
+        const ids = entries.map(([id]) => id);
+        return Object.freeze(limit !== undefined ? ids.slice(0, Math.max(0, limit)) : ids);
+    }
+    async summarize(engagementId) {
+        const records = await this.read(engagementId);
+        if (records.length === 0)
+            return undefined;
+        return summarizeEngagementEvents(engagementId, records);
+    }
+    async compact(engagementId) {
+        await this.#serial.run(engagementId, async () => {
+            const records = await this.read(engagementId);
+            const compacted = compactRecordList(engagementId, records);
+            if (!compacted)
+                return;
+            await this.#db.delete(ENGAGEMENT_EVENTS_TABLE, { engagement_id: engagementId });
+            for (const record of compacted) {
+                await this.#db.insert(ENGAGEMENT_EVENTS_TABLE, {
+                    id: `${engagementId}:${record.seq}`,
+                    engagement_id: engagementId,
+                    seq: record.seq,
+                    at: record.at,
+                    type: record.type,
+                    data: JSON.stringify(record.data),
+                });
+            }
+        });
+    }
+    async #nextSeq(engagementId) {
+        const rows = await this.#db
+            .select(ENGAGEMENT_EVENTS_TABLE, ['seq'])
+            .where({ engagement_id: engagementId });
+        let max = -1;
+        for (const row of rows)
+            max = Math.max(max, Number(row.seq));
+        return max + 1;
+    }
+}