@zq-silk/yui 2.1.0 → 2.2.0

package/dist/nativeAgent/session/catalog.js

@@ -0,0 +1,97 @@
+import { SessionError, sessionLimits } from './format.js';
+export const catalogLimits = Object.freeze({
+    defaultPageSize: 20, pageSize: 100, titleCharacters: 200, cursorBytes: 4096,
+    // Every legal event (<=1 MiB) fits with its record wrapper and page envelope.
+    historyBytes: 2 * 1024 * 1024,
+});
+const invalid = () => { throw new SessionError('invalid_cursor', 'Invalid cursor for this store, target or page size'); };
+export function pageLimit(options) {
+    if (!options || typeof options !== 'object' || Array.isArray(options)
+        || Object.keys(options).some(key => !['limit', 'cursor'].includes(key))) {
+        throw new SessionError('invalid_query', 'Expected page options containing only limit and cursor');
+    }
+    const limit = options.limit === undefined ? catalogLimits.defaultPageSize : options.limit;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > catalogLimits.pageSize) {
+        throw new SessionError('invalid_query', 'Page limit must be an integer in 1..100');
+    }
+    return limit;
+}
+export function readCursor(options, store, kind, session) {
+    if (options.cursor === undefined)
+        return undefined;
+    const text = options.cursor;
+    if (typeof text !== 'string' || !text.length || Buffer.byteLength(text) > catalogLimits.cursorBytes
+        || !/^[A-Za-z0-9_-]+$/.test(text))
+        return invalid();
+    try {
+        const raw = Buffer.from(text, 'base64url');
+        if (raw.toString('base64url') !== text)
+            return invalid();
+        const c = JSON.parse(raw.toString('utf8'));
+        if (!c || Array.isArray(c) || c.v !== 1 || c.store !== store || c.kind !== kind
+            || c.limit !== pageLimit(options) || !Number.isSafeInteger(c.revision) || c.revision < 0
+            || Object.keys(c).some(key => !['v', 'store', 'kind', 'limit', 'revision', 'after', 'session'].includes(key))
+            || (kind === 'sessions' ? c.session !== undefined || typeof c.after !== 'string'
+                || !c.after.trim() || c.after.length > 256
+                : c.session !== session || !Number.isSafeInteger(c.after) || Number(c.after) < 1
+                    || Number(c.after) >= c.revision))
+            return invalid();
+        return c;
+    }
+    catch {
+        return invalid();
+    }
+}
+export function nextCursor(store, kind, limit, revision, after, session) {
+    return Buffer.from(JSON.stringify({ v: 1, store, kind, limit, revision, after,
+        ...(session === undefined ? {} : { session }) })).toString('base64url');
+}
+export function currentCursor(cursor, revision) {
+    if (cursor && cursor.revision !== revision) {
+        throw new SessionError('cursor_stale', 'Saved data changed; restart pagination from the first page');
+    }
+}
+export function normalizeTitle(title) {
+    if (title === null)
+        return null;
+    if (typeof title !== 'string')
+        throw new SessionError('invalid_title', 'Title must be text or null');
+    const text = title.trim();
+    if (!text || [...text].length > catalogLimits.titleCharacters || /[\p{Cc}\p{Cs}]/u.test(text)) {
+        throw new SessionError('invalid_title', 'Title must contain 1..200 Unicode characters without controls or lone surrogates');
+    }
+    return text;
+}
+export function metadataRevision(expected) {
+    if (!Number.isSafeInteger(expected) || expected < 0) {
+        throw new SessionError('revision_conflict', 'Expected metadata revision must be a nonnegative integer');
+    }
+}
+export function increment(value) {
+    if (!Number.isSafeInteger(value) || value < 0 || value === Number.MAX_SAFE_INTEGER) {
+        throw new SessionError('revision_exhausted', 'Stored revision cannot be incremented safely');
+    }
+    return value + 1;
+}
+export function queryBounds(after, limit) {
+    if (!Number.isSafeInteger(after) || after < 0 || !Number.isSafeInteger(limit)
+        || limit < 1 || limit > sessionLimits.pageSize) {
+        throw new SessionError('invalid_query', 'Cursor must be nonnegative; page limit must be 1..100');
+    }
+}
+/** Reads at most limit + 1 individual bounded records, never a whole log.
+ * Reserve 64 KiB for escaped identities, file source and the <=4 KiB cursor;
+ * this also leaves every legal <=1 MiB event readable in a 2 MiB page. */
+export function historyRecords(after, revision, limit, read) {
+    const records = [];
+    let bytes = 64 * 1024;
+    for (let at = after + 1; at <= revision && records.length < limit; at++) {
+        const item = read(at);
+        const size = Buffer.byteLength(JSON.stringify(item));
+        if (bytes + size > catalogLimits.historyBytes)
+            break;
+        bytes += size;
+        records.push(item);
+    }
+    return records;
+}

package/dist/nativeAgent/session/catalogDemo.js

@@ -0,0 +1,87 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createAgent, createExecutionOwner, createSessionStore, createSqliteSessionBackend, } from '../index.js';
+// Standalone storage/owner evidence, not task-80's product CLI or a live model.
+const directory = await mkdtemp(join(tmpdir(), 'native-catalog-demo-'));
+const filename = join(directory, 'sessions.sqlite');
+let store;
+let owner;
+let modelCalls = 0;
+const openOwner = (sessions) => createExecutionOwner({
+    store: sessions, maxSteps: 1,
+    agent: recorder => createAgent({
+        recorder, tools: [],
+        provider: { async complete(request) {
+                modelCalls++;
+                if (modelCalls === 2)
+                    assert.deepEqual(request.messages.map(m => 'content' in m ? m.content : ''), ['hello', 'saved answer', 'again']);
+                return { kind: 'final', content: modelCalls === 1 ? 'saved answer' : 'continued after restart' };
+            } },
+    }),
+});
+try {
+    store = createSessionStore(createSqliteSessionBackend(filename));
+    for (const id of ['c', 'a'])
+        await store.create(id); // Old calls explicitly lack location.
+    const location = { root: directory, cwd: directory };
+    await store.create('b', location); // One atomic creation, never a second metadata write.
+    await store.renameSession('a', 'Same title', 0);
+    await store.renameSession('b', 'Same title', 0);
+    await store.renameSession('c', 'Temporary', 0);
+    await store.renameSession('c', null, 1); // Explicitly clear, no history replacement.
+    owner = openOwner(store);
+    await owner.submit('b', 'hello');
+    const evidence = await owner.settle('b');
+    assert.equal(evidence?.result?.reason, 'completed');
+    await owner.close();
+    owner = undefined;
+    await store.close();
+    store = undefined; // No old database connections survive.
+    store = createSessionStore(createSqliteSessionBackend(filename));
+    const discovered = [];
+    let cursor;
+    do {
+        const page = await store.listSessions({ limit: 1, cursor });
+        discovered.push(...page.items);
+        cursor = page.nextCursor ?? undefined;
+    } while (cursor);
+    assert.deepEqual(discovered.map(s => s.sessionId), ['a', 'b', 'c']);
+    assert.equal(discovered.filter(s => s.title === 'Same title').length, 2);
+    // Titles are not keys: the caller chooses the displayed exact ID.
+    const selected = discovered.find(s => s.sessionId === 'b');
+    const detail = await store.getSessionInfo(selected.sessionId);
+    assert.deepEqual(detail.location, location);
+    assert.equal((await store.getSessionInfo('a')).location, null);
+    // Consumer boundary: missing location must not be guessed. Before real execution,
+    // task-80 checks filesystem/exact explicit-location conflicts and rebuilds 82/84
+    // with fresh authority; these storage reads grant none of that authority.
+    assert.equal(detail.digest, evidence?.receipt?.digest);
+    const renamed = await store.renameSession(selected.sessionId, 'Chosen session', detail.metadataRevision);
+    assert.equal(renamed.revision, detail.revision);
+    let historyPages = 0, historyRecords = 0;
+    do {
+        const page = await store.readHistory(selected.sessionId, { limit: 2, cursor });
+        historyPages++;
+        historyRecords += page.records.length;
+        cursor = page.nextCursor ?? undefined;
+    } while (cursor);
+    assert.ok(historyPages >= 3);
+    assert.equal(historyRecords, detail.revision);
+    assert.equal(modelCalls, 1); // Discovery/selection/history never start execution.
+    owner = openOwner(store);
+    await owner.submit(selected.sessionId, 'again');
+    assert.equal((await owner.settle(selected.sessionId))?.result?.reason, 'completed');
+    console.log(JSON.stringify({
+        discovered, selected: renamed.sessionId, persistedTitle: renamed.title,
+        historyPages, historyRecords, receiptPreserved: true,
+        allConnectionsClosedBeforeReopen: true, continuedThroughExistingOwner: true, modelCalls,
+        persistedLocation: detail.location, legacyLocationExplicitlyMissing: true,
+    }, null, 2));
+}
+finally {
+    await owner?.close();
+    await store?.close();
+    await rm(directory, { recursive: true, force: true });
+}

package/dist/nativeAgent/session/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/nativeAgent/session/format.js

@@ -0,0 +1,269 @@
+export const sessionLimits = Object.freeze({
+    documentBytes: 16 * 1024 * 1024, eventBytes: 1024 * 1024,
+    events: 10_000, pageSize: 100, subscribers: 64,
+});
+export class SessionError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'SessionError';
+    }
+}
+function requireFact(condition, message) {
+    if (!condition)
+        throw new SessionError('invalid_session', message);
+}
+export function identity(value) {
+    requireFact(typeof value === 'string' && value.trim().length > 0 && value.length <= 256, 'Session, Turn and call identities must be nonempty and at most 256 characters');
+}
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function fields(value, names) {
+    requireFact(object(value) && Object.keys(value).every(key => names.includes(key)), 'Invalid record fields');
+}
+function json(value, depth = 0) {
+    requireFact(depth <= 64, 'JSON nesting limit exceeded');
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number') {
+        requireFact(Number.isFinite(value), 'Nonfinite JSON number');
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            json(entry, depth + 1);
+        return;
+    }
+    requireFact(object(value) && Object.getPrototypeOf(value) === Object.prototype, 'Expected plain JSON');
+    for (const entry of Object.values(value))
+        json(entry, depth + 1);
+}
+export function immutable(value) {
+    const freeze = (item) => {
+        if (item && typeof item === 'object') {
+            for (const child of Object.values(item))
+                freeze(child);
+            Object.freeze(item);
+        }
+    };
+    freeze(value);
+    return value;
+}
+export function encode(document) { return JSON.stringify(document); }
+export function revision(document) { return document.events.length; }
+export function copyEvent(value) {
+    // The public skeleton emits the optional step as undefined before a Step.
+    const candidate = value && object(value.data) && value.data.type === 'message_appended'
+        && value.data.step === undefined
+        ? { ...value, data: Object.fromEntries(Object.entries(value.data).filter(([key]) => key !== 'step')) }
+        : value;
+    json(candidate);
+    const text = JSON.stringify(candidate);
+    requireFact(Buffer.byteLength(text) <= sessionLimits.eventBytes, 'Event byte limit exceeded');
+    return JSON.parse(text);
+}
+function outcome(value) {
+    requireFact(object(value), 'Invalid tool outcome');
+    if (value.ok === true) {
+        fields(value, ['ok', 'content']);
+        requireFact(typeof value.content === 'string', 'Missing tool content');
+    }
+    else {
+        fields(value, ['ok', 'error']);
+        requireFact(value.ok === false, 'Invalid tool outcome status');
+        fields(value.error, ['code', 'message', 'effect']);
+        identity(value.error.code);
+        requireFact(typeof value.error.message === 'string'
+            && ['none', 'unknown'].includes(value.error.effect), 'Invalid tool error');
+    }
+}
+function message(value) {
+    requireFact(object(value), 'Invalid message');
+    if (value.role === 'tool') {
+        fields(value, ['role', 'toolCallId', 'name', 'outcome']);
+        identity(value.toolCallId);
+        identity(value.name);
+        outcome(value.outcome);
+        return;
+    }
+    requireFact(typeof value.content === 'string', 'Missing message content');
+    if (value.role === 'assistant') {
+        fields(value, ['role', 'content', 'toolCalls']);
+        requireFact(Array.isArray(value.toolCalls) && value.toolCalls.length <= 8, 'Invalid tool batch');
+        for (const call of value.toolCalls) {
+            fields(call, ['id', 'name', 'arguments']);
+            identity(call.id);
+            identity(call.name);
+            requireFact('arguments' in call && Buffer.byteLength(JSON.stringify(call.arguments)) <= 64 * 1024, 'Missing or oversized tool arguments');
+        }
+    }
+    else {
+        fields(value, ['role', 'content']);
+        requireFact(value.role === 'system' || value.role === 'user', 'Invalid message role');
+    }
+}
+/**
+ * Central current-format admission and projection. No heuristic normalization,
+ * synthesized results or historical-shape fallback. Future versions migrate here.
+ */
+function inspectVersion(value, version) {
+    json(value);
+    fields(value, ['schemaVersion', 'sessionId', 'events']);
+    requireFact(value.schemaVersion === version, `Unsupported Session format; expected version ${version}`);
+    identity(value.sessionId);
+    requireFact(Array.isArray(value.events) && value.events.length <= sessionLimits.events, 'Event count limit exceeded');
+    requireFact(Buffer.byteLength(JSON.stringify(value)) <= sessionLimits.documentBytes, 'Session byte limit exceeded');
+    // Detached input protects validation and async backend calls from caller mutation.
+    const document = JSON.parse(JSON.stringify(value));
+    const messages = [];
+    const turns = [];
+    const calls = [];
+    const turnIds = new Set();
+    const callIds = new Set();
+    let active;
+    let pending = [];
+    let userSeen = false;
+    let responseSeen = false;
+    let finalSeen = false;
+    let uncertain = false;
+    let cleanupRequired = false;
+    for (const [index, event] of document.events.entries()) {
+        fields(event, ['sessionId', 'turnId', 'seq', 'data']);
+        identity(event.turnId);
+        requireFact(event.sessionId === document.sessionId && Number.isSafeInteger(event.seq), 'Event identity or sequence mismatch');
+        requireFact(Buffer.byteLength(JSON.stringify(event)) <= sessionLimits.eventBytes, 'Event byte limit exceeded');
+        const data = event.data;
+        requireFact(object(data), 'Missing event data');
+        const at = index + 1;
+        if (data.type === 'turn_started') {
+            fields(data, ['type']);
+            requireFact(!active && !turnIds.has(event.turnId) && event.seq === 1 && !uncertain && !cleanupRequired, 'Cannot start Turn: active, repeated, noninitial sequence or unknown effects require recovery');
+            active = { turnId: event.turnId, lastSequence: 1, lastStep: 0 };
+            turns.push(active);
+            turnIds.add(event.turnId);
+            userSeen = false;
+            finalSeen = false;
+            continue;
+        }
+        requireFact(active && active.turnId === event.turnId && event.seq === active.lastSequence + 1, 'Fact must extend the active Turn sequence');
+        active.lastSequence = event.seq;
+        switch (data.type) {
+            case 'step_started':
+                fields(data, ['type', 'step']);
+                requireFact(userSeen && !finalSeen && !uncertain && !cleanupRequired && active.openStep === undefined && !pending.length
+                    && data.step === active.lastStep + 1, 'Invalid Step start or unsettled calls');
+                active.lastStep = data.step;
+                active.openStep = data.step;
+                responseSeen = false;
+                break;
+            case 'message_appended': {
+                fields(data, version === 1 ? ['type', 'step', 'message'] : ['type', 'step', 'message', 'settlement']);
+                message(data.message);
+                const msg = data.message;
+                requireFact(data.settlement === undefined || msg.role === 'tool', 'Settlement requires a tool result');
+                if (msg.role === 'system' || msg.role === 'user') {
+                    requireFact(data.step === undefined && !active.lastStep && !userSeen, 'Input messages must precede Steps and occur only once per Turn');
+                    if (msg.role === 'user')
+                        userSeen = true;
+                }
+                else {
+                    requireFact(active.openStep !== undefined && data.step === active.openStep, 'Model/tool message must belong to the open Step');
+                    if (msg.role === 'assistant') {
+                        requireFact(!responseSeen && !pending.length, 'Repeated model response or unsettled calls');
+                        responseSeen = true;
+                        finalSeen = msg.toolCalls.length === 0;
+                        for (const call of msg.toolCalls) {
+                            requireFact(!callIds.has(call.id), 'Repeated tool call identity');
+                            callIds.add(call.id);
+                            const record = {
+                                turnId: event.turnId, step: data.step, call: call,
+                                callRevision: at, status: 'not-started',
+                            };
+                            calls.push(record);
+                            pending.push(record);
+                        }
+                    }
+                    else if (msg.role === 'tool') {
+                        const call = pending[0];
+                        requireFact(call && call.call.id === msg.toolCallId && call.call.name === msg.name, 'Tool result must pair with exactly the next pending call');
+                        requireFact((!msg.outcome.ok && msg.outcome.error.effect === 'none') || call.startRevision !== undefined, 'Effectful result requires a confirmed write-ahead start');
+                        requireFact(!uncertain || (!msg.outcome.ok && msg.outcome.error.effect === 'none'
+                            && call.startRevision === undefined), 'Cannot report new effects after uncertainty');
+                        call.resultRevision = at;
+                        call.outcome = msg.outcome;
+                        if (data.settlement !== undefined) {
+                            const s = data.settlement;
+                            fields(s, ['started', 'status', 'cancellationRequested', 'cleanup']);
+                            requireFact(typeof s.started === 'boolean' && typeof s.cancellationRequested === 'boolean', 'Invalid settlement flags');
+                            const expected = !s.started ? 'not_executed' : msg.outcome.ok ? 'succeeded'
+                                : msg.outcome.error.effect === 'unknown' ? 'unknown'
+                                    : msg.outcome.error.code === 'cancelled' ? 'cancelled' : 'failed';
+                            requireFact(s.status === expected && (!s.started || call.startRevision !== undefined)
+                                && (s.started || (!msg.outcome.ok && msg.outcome.error.effect === 'none')), 'Settlement contradicts outcome or intent');
+                            fields(s.cleanup, ['status', 'error']);
+                            requireFact(['not_acquired', 'released', 'failed', 'acquire_failed'].includes(s.cleanup.status), 'Invalid cleanup status');
+                            if (s.cleanup.status === 'failed' || s.cleanup.status === 'acquire_failed') {
+                                fields(s.cleanup.error, ['code', 'message']);
+                                identity(s.cleanup.error.code);
+                                requireFact(typeof s.cleanup.error.message === 'string', 'Missing cleanup diagnostic');
+                                cleanupRequired = true;
+                            }
+                            else
+                                requireFact(!('error' in s.cleanup), 'Unexpected cleanup diagnostic');
+                            requireFact(!s.started || ['released', 'failed'].includes(s.cleanup.status), 'Started tool must retain acquired-resource settlement');
+                            call.settlement = data.settlement;
+                        }
+                        call.status = !msg.outcome.ok && msg.outcome.error.effect === 'unknown' ? 'unknown' : 'settled';
+                        uncertain ||= call.status === 'unknown';
+                        pending.shift();
+                    }
+                }
+                messages.push(msg);
+                break;
+            }
+            case 'tool_started': {
+                fields(data, ['type', 'step', 'toolCallId', 'name']);
+                const call = pending[0];
+                requireFact(!uncertain && !cleanupRequired && active.openStep !== undefined && data.step === active.openStep && call
+                    && call.call.id === data.toolCallId && call.call.name === data.name && call.startRevision === undefined, 'Tool start must match the next unstarted call in the open Step');
+                call.startRevision = at;
+                call.status = 'unknown';
+                break;
+            }
+            case 'step_ended':
+                fields(data, ['type', 'step']);
+                requireFact(active.openStep !== undefined && data.step === active.openStep && !pending.length, 'Cannot end Step with unsettled calls or without an open Step');
+                delete active.openStep;
+                break;
+            case 'turn_ended':
+                fields(data, ['type', 'reason', 'errorCode']);
+                requireFact(active.openStep === undefined && !pending.length, 'Cannot end Turn with open Step or unsettled calls');
+                requireFact(['completed', 'cancelled', 'budget_exhausted', 'error'].includes(data.reason)
+                    && (data.errorCode === undefined || typeof data.errorCode === 'string'), 'Invalid terminal');
+                requireFact(data.reason !== 'completed' || finalSeen, 'Completed Turn requires final model response');
+                requireFact(!uncertain || data.reason === 'error', 'Unknown effects require error terminal');
+                requireFact(!cleanupRequired || data.reason === 'error', 'Unreleased resources require error terminal');
+                active.terminal = { reason: data.reason, revision: at,
+                    ...(data.errorCode === undefined ? {} : { errorCode: data.errorCode }) };
+                active = undefined;
+                break;
+            default:
+                throw new SessionError('invalid_session', 'Unsupported event type');
+        }
+    }
+    return { document, messages, recovery: {
+            disposition: calls.some(c => c.status === 'unknown') ? 'unknown-effects'
+                : cleanupRequired ? 'cleanup-required' : active ? 'interrupted' : 'ready',
+            turns, calls,
+        } };
+}
+/** Current readers never reinterpret old shapes or repair malformed evidence. */
+export function inspectDocument(value) { return inspectVersion(value, 2); }
+/** The one declared v1 → v2 transition. All original events remain byte-equivalent
+ * JSON values; absent historical settlement evidence is never invented. */
+export function migrateSessionDocument(value) {
+    inspectVersion(value, 1);
+    return inspectDocument({ ...value, schemaVersion: 2 }).document;
+}

package/dist/nativeAgent/session/index.js

@@ -0,0 +1,5 @@
+export { createSessionStore, SessionSaveError, SessionMetadataSaveError } from './store.js';
+export { createMemorySessionBackend, createSqliteSessionBackend } from './backends.js';
+export { SessionError, sessionLimits } from './format.js';
+export { catalogLimits } from './catalog.js';
+export { locationLimits } from './location.js';

package/dist/nativeAgent/session/location.js

@@ -0,0 +1,36 @@
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { SessionError } from './format.js';
+export const locationLimits = Object.freeze({ pathBytes: 4096 });
+/** Pure lexical admission. No filesystem lookup, normalization or permission. */
+export function copyLocation(value) {
+    const invalid = () => {
+        throw new SessionError('invalid_location', 'Expected only resolved absolute root/cwd within root, each at most 4096 UTF-8 bytes');
+    };
+    if (!value || typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype
+        || Reflect.ownKeys(value).length !== 2
+        || !Object.hasOwn(value, 'root') || !Object.hasOwn(value, 'cwd'))
+        return invalid();
+    const { root, cwd } = value;
+    for (const path of [root, cwd]) {
+        if (typeof path !== 'string' || Buffer.byteLength(path) > locationLimits.pathBytes
+            || /[\p{Cc}\p{Cs}]/u.test(path) || !isAbsolute(path) || resolve(path) !== path)
+            return invalid();
+    }
+    const within = relative(root, cwd);
+    if (within === '..' || within.startsWith(`..${sep}`) || isAbsolute(within))
+        return invalid();
+    return { root: root, cwd: cwd };
+}
+export function decodeLocation(text) {
+    if (text === null)
+        return null;
+    try {
+        if (typeof text !== 'string' || Buffer.byteLength(text) > 6 * locationLimits.pathBytes + 64) {
+            throw new Error('Oversized or non-text location');
+        }
+        return copyLocation(JSON.parse(text));
+    }
+    catch (cause) {
+        throw new SessionError('corrupt_session', 'Malformed stored location; do not guess a working directory', { cause });
+    }
+}

package/dist/nativeAgent/session/sqliteFormat.js

@@ -0,0 +1,134 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { encode, inspectDocument, migrateSessionDocument, revision, SessionError, sessionLimits } from './format.js';
+import { metadataRevision, normalizeTitle } from './catalog.js';
+export const applicationId = 0x4e415331; // NAS1, independent of Yui Home.
+export const oldSchema = 'CREATE TABLE sessions (id TEXT PRIMARY KEY, revision INTEGER NOT NULL, document TEXT NOT NULL, digest TEXT NOT NULL)';
+const layout3 = [
+    'CREATE TABLE sessions (id TEXT PRIMARY KEY, revision INTEGER NOT NULL, document TEXT NOT NULL, digest TEXT NOT NULL, title TEXT, metadata_revision INTEGER NOT NULL)',
+    'CREATE TABLE session_events (session_id TEXT NOT NULL REFERENCES sessions(id), revision INTEGER NOT NULL, event TEXT NOT NULL, digest TEXT NOT NULL, PRIMARY KEY (session_id, revision))',
+    'CREATE TABLE session_catalog (singleton INTEGER PRIMARY KEY CHECK (singleton = 1), id TEXT NOT NULL, revision INTEGER NOT NULL)',
+    // Cover every lightweight read without traversing the document's overflow
+    // pages. SQLite maintains this index; it is not a separately writable catalog.
+    'CREATE INDEX session_info ON sessions (id, title, metadata_revision, revision, digest)',
+];
+const tables = [
+    'CREATE TABLE sessions (id TEXT PRIMARY KEY, revision INTEGER NOT NULL, document TEXT NOT NULL, digest TEXT NOT NULL, title TEXT, metadata_revision INTEGER NOT NULL, location TEXT)',
+    ...layout3.slice(1, 3),
+    'CREATE INDEX session_info ON sessions (id, title, metadata_revision, revision, digest, location)',
+];
+export function hash(text) { return createHash('sha256').update(text).digest('hex'); }
+export function digest(document) { return hash(encode(document)); }
+export function decode(row) {
+    try {
+        if (Buffer.byteLength(row.document) > sessionLimits.documentBytes)
+            throw new Error('Oversized document');
+        const document = inspectDocument(JSON.parse(row.document)).document;
+        if (row.id !== document.sessionId || row.revision !== revision(document) || row.digest !== digest(document)) {
+            throw new Error('Stored identity, revision or digest mismatch');
+        }
+        return document;
+    }
+    catch (cause) {
+        throw new SessionError('corrupt_session', 'Stored Session is malformed; preserve the file for diagnosis', { cause });
+    }
+}
+/** One centralized, atomic layout chain: v1 document -> v2 settlement format ->
+ * v3 catalog/projection -> v4 immutable creation location.
+ * Document v2 and its existing receipts stay intact.
+ * This is called only on the caller-selected independent database. */
+export function initializeSessionDatabase(db) {
+    db.transaction(() => {
+        const id = db.pragma('application_id', { simple: true });
+        const version = db.pragma('user_version', { simple: true });
+        const objects = db.prepare("SELECT sql FROM sqlite_master WHERE name NOT LIKE 'sqlite_%' ORDER BY sql").all();
+        const sql = objects.map(x => x.sql);
+        const unsupported = () => { throw new SessionError('unsupported_format', 'Not a supported Session database layout/version; no migration applied'); };
+        const create = () => {
+            for (const table of tables)
+                db.exec(table);
+            db.prepare('INSERT INTO session_catalog VALUES (1, ?, 0)').run(randomUUID());
+        };
+        if (id === 0 && version === 0 && !objects.length) {
+            create();
+            db.pragma(`application_id = ${applicationId}`);
+            db.pragma('user_version = 4');
+            return;
+        }
+        if (id !== applicationId || ![1, 2, 3, 4].includes(version))
+            unsupported();
+        if (version === 3 || version === 4) {
+            if (JSON.stringify(sql) !== JSON.stringify([...(version === 3 ? layout3 : tables)].sort()))
+                unsupported();
+            const rows = db.prepare('SELECT id, revision FROM session_catalog').all();
+            if (rows.length !== 1 || !/^[0-9a-f-]{36}$/.test(rows[0].id)
+                || !Number.isSafeInteger(rows[0].revision) || rows[0].revision < 0)
+                unsupported();
+            if (version === 4)
+                return;
+            // No document rewrites: add only missing location, preserve catalog UUID,
+            // title CAS, events, document bytes and all existing save receipts.
+            db.exec('ALTER TABLE sessions ADD COLUMN location TEXT');
+            db.exec('DROP INDEX session_info');
+            db.exec(tables[3]);
+            const events = db.prepare('SELECT revision, event, digest FROM session_events WHERE session_id = ? ORDER BY revision');
+            const count = db.prepare('SELECT count(*) AS n FROM session_events WHERE session_id = ?');
+            const next = db.prepare('SELECT * FROM sessions WHERE id > ? COLLATE BINARY ORDER BY id COLLATE BINARY LIMIT 1');
+            let row = db.prepare('SELECT * FROM sessions ORDER BY id COLLATE BINARY LIMIT 1').get();
+            while (row) {
+                const document = decode(row);
+                metadataRevision(row.metadata_revision);
+                if (normalizeTitle(row.title) !== row.title)
+                    throw new SessionError('corrupt_session', 'Malformed migrated title');
+                if (count.get(row.id).n !== row.revision) {
+                    throw new SessionError('corrupt_session', 'Malformed migrated history projection');
+                }
+                let at = 0;
+                for (const projected of events.iterate(row.id)) {
+                    const original = JSON.stringify(document.events[at++]);
+                    if (projected.revision !== at || projected.event !== original || projected.digest !== hash(original)) {
+                        throw new SessionError('corrupt_session', 'Migrated history differs from its authoritative document');
+                    }
+                }
+                row = next.get(row.id);
+            }
+            if (db.prepare('SELECT 1 FROM session_events WHERE NOT EXISTS (SELECT 1 FROM sessions WHERE id = session_id) LIMIT 1').get()) {
+                throw new SessionError('corrupt_session', 'Orphaned migrated history projection');
+            }
+            db.pragma('user_version = 4');
+            return;
+        }
+        if (objects.length !== 1 || sql[0] !== oldSchema)
+            unsupported();
+        // DDL and all data transformations share this transaction. A rejected row or
+        // failed insert rolls back even the table rename and the version transition.
+        db.exec('ALTER TABLE sessions RENAME TO source_sessions');
+        create();
+        const insert = db.prepare('INSERT INTO sessions VALUES (?, ?, ?, ?, NULL, 0, NULL)');
+        const eventInsert = db.prepare('INSERT INTO session_events VALUES (?, ?, ?, ?)');
+        const next = db.prepare('SELECT id, revision, document, digest FROM source_sessions WHERE id > ? COLLATE BINARY ORDER BY id COLLATE BINARY LIMIT 1');
+        let row = db.prepare('SELECT id, revision, document, digest FROM source_sessions ORDER BY id COLLATE BINARY LIMIT 1').get();
+        while (row) {
+            let document;
+            if (version === 1) {
+                if (Buffer.byteLength(row.document) > sessionLimits.documentBytes)
+                    throw new SessionError('corrupt_session', 'Oversized version-1 document');
+                const original = JSON.parse(row.document);
+                if (row.id !== original.sessionId || row.revision !== original.events?.length || row.digest !== hash(JSON.stringify(original))) {
+                    throw new SessionError('corrupt_session', 'Version-1 identity, revision or digest mismatch');
+                }
+                document = migrateSessionDocument(original);
+                row = { ...row, document: encode(document), digest: digest(document) };
+            }
+            else
+                document = decode(row);
+            insert.run(row.id, row.revision, row.document, row.digest);
+            for (const [index, event] of document.events.entries()) {
+                const text = JSON.stringify(event);
+                eventInsert.run(row.id, index + 1, text, hash(text));
+            }
+            row = next.get(row.id);
+        }
+        db.exec('DROP TABLE source_sessions');
+        db.pragma('user_version = 4');
+    }).immediate();
+}