dscs-server 0.0.0-stage → 0.0.1

package/dist/index.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ONBOARDING_CODE_FILE, ONBOARDING_TTL_MS, createDevice, createHttpServer, listDevices, mintOnboardingCode, revokeDevice, DEFAULT_MAX_BYTES } from './http.js';
+import { clearAdminPassword, ensureSetupToken, isAdminInitialized, openDatabase, readMaxBytes } from './db.js';
+function writeOnboardingCode(dataDir, code) {
+    mkdirSync(dataDir, {
+        recursive: true
+    });
+    const file = join(dataDir, ONBOARDING_CODE_FILE);
+    const temporary = `${file}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify({
+        code,
+        expiresAt: Date.now() + ONBOARDING_TTL_MS
+    })}\n`, {
+        mode: 0o600
+    });
+    try {
+        chmodSync(temporary, 0o600);
+    } catch  {}
+    renameSync(temporary, file);
+}
+function clearOnboardingCode(dataDir) {
+    rmSync(join(dataDir, ONBOARDING_CODE_FILE), {
+        force: true
+    });
+}
+function usage() {
+    console.error(`dsh-session-cloudsync-server <命令> [选项]
+
+命令：
+  serve                      启动 HTTP API 与管理台
+  token add <标签>            签发一个设备 token（只打印一次）
+  token list                 列出存活设备
+  token revoke <deviceId>    吊销某个设备 token
+  admin status               查看初始化状态与配额
+  admin reset                忘记管理密码时重置（重启 serve 后重新初始化）
+
+选项：
+  --data-dir <目录>           数据目录（默认 .tmp/dev-data）
+  --host <地址>               绑定地址（默认 127.0.0.1）
+  --port <端口>               监听端口（默认 8787）
+  --max-bytes <n>             存储上限（默认 10 GiB）
+`);
+    process.exit(2);
+}
+function parse(argv) {
+    const positionals = [];
+    const flags = new Map();
+    for(let index = 0; index < argv.length; index += 1){
+        const argument = argv[index];
+        if (argument.startsWith('--')) {
+            const value = argv[index + 1];
+            if (value === undefined || value.startsWith('--')) usage();
+            flags.set(argument.slice(2), value);
+            index += 1;
+        } else {
+            positionals.push(argument);
+        }
+    }
+    const command = positionals.shift();
+    if (command === undefined) usage();
+    return {
+        command,
+        positionals,
+        flags
+    };
+}
+async function main(parsed) {
+    const dataDir = parsed.flags.get('data-dir') ?? '.tmp/dev-data';
+    const db = openDatabase(dataDir);
+    try {
+        if (parsed.command === 'token') {
+            const action = parsed.positionals[0];
+            if (action === 'add') {
+                const label = parsed.positionals[1] ?? 'device';
+                const created = createDevice(db, label);
+                console.log(JSON.stringify(created, null, 2));
+                return;
+            }
+            if (action === 'list') {
+                console.log(JSON.stringify(listDevices(db), null, 2));
+                return;
+            }
+            if (action === 'revoke') {
+                const deviceId = parsed.positionals[1];
+                if (deviceId === undefined) usage();
+                console.log(revokeDevice(db, deviceId) ? '已吊销' : '没有这个设备');
+                return;
+            }
+            usage();
+        }
+        if (parsed.command === 'admin') {
+            const action = parsed.positionals[0];
+            if (action === 'status') {
+                console.log(JSON.stringify({
+                    initialized: isAdminInitialized(db),
+                    maxBytes: readMaxBytes(db, DEFAULT_MAX_BYTES)
+                }, null, 2));
+                return;
+            }
+            if (action === 'reset') {
+                clearAdminPassword(db);
+                clearOnboardingCode(dataDir);
+                console.log('已清除管理密码。重启 server 后会在控制台打印新的初始化密钥。');
+                return;
+            }
+            usage();
+        }
+        if (parsed.command === 'serve') {
+            const host = parsed.flags.get('host') ?? '127.0.0.1';
+            const port = Number(parsed.flags.get('port') ?? '8787');
+            const maxBytes = Number(parsed.flags.get('max-bytes') ?? DEFAULT_MAX_BYTES);
+            if (!Number.isInteger(port) || port < 0 || port > 65535) usage();
+            if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) usage();
+            const setup = ensureSetupToken(db);
+            writeFileSync(join(dataDir, 'setup-token'), `${setup.token}\n`, {
+                mode: 0o600
+            });
+            try {
+                chmodSync(join(dataDir, 'setup-token'), 0o600);
+            } catch  {}
+            const initialized = isAdminInitialized(db);
+            const onboardingCode = initialized ? undefined : mintOnboardingCode();
+            if (onboardingCode === undefined) clearOnboardingCode(dataDir);
+            else writeOnboardingCode(dataDir, onboardingCode);
+            const server = createHttpServer({
+                db,
+                dataDir,
+                maxBytes,
+                ...onboardingCode === undefined ? {} : {
+                    onboardingCode
+                }
+            });
+            server.listen(port, host, ()=>{
+                const address = server.address();
+                const actualPort = typeof address === 'object' && address !== null ? address.port : port;
+                console.log(`dsh-session-cloudsync-server 已监听 http://${host}:${actualPort}`);
+                console.log(`setup token 文件：${join(dataDir, 'setup-token')}（设备 CLI 用）`);
+                if (!initialized) {
+                    console.log('');
+                    console.log(`首次启动，请打开 http://${host}:${actualPort}/admin 完成初始化`);
+                    console.log(`初始化密钥：${onboardingCode}`);
+                    console.log('（10 分钟内有效；未完成初始化时每次启动都会重新生成）');
+                } else {
+                    console.log(`管理台：http://${host}:${actualPort}/admin（用管理密码登录）`);
+                }
+            });
+            const stop = ()=>{
+                server.close(()=>{
+                    db.close();
+                    process.exit(0);
+                });
+            };
+            process.once('SIGINT', stop);
+            process.once('SIGTERM', stop);
+            return;
+        }
+        usage();
+    } finally{
+        if (parsed.command !== 'serve') db.close();
+    }
+}
+void main(parse(process.argv.slice(2))).catch((error)=>{
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});
+
+
+//# sourceURL=index.ts

package/dist/leases.js

@@ -0,0 +1,43 @@
+import { SyncError } from './shared/wire.js';
+import { DEFAULT_DATASET, withTransaction } from './db.js';
+export const LEASE_TTL_MS = 60_000;
+export const SYNC_RESOURCE = 'sync';
+export function vaultResource(writer) {
+    return `vault-writer:${writer}`;
+}
+export function acquireLease(db, resource, deviceId, clientId, now = Date.now()) {
+    if (clientId === '') throw new SyncError('bad-request', '缺少 clientInstanceId');
+    return withTransaction(db, ()=>{
+        const row = db.handle.prepare('SELECT device_id, client_id, lease_until FROM leases WHERE dataset = ? AND resource = ?').get(DEFAULT_DATASET, resource);
+        if (row !== undefined && (row.device_id !== deviceId || row.client_id !== clientId) && row.lease_until > now) {
+            throw new SyncError('lease-held', `${resource} 的租约由 ${row.device_id}/${row.client_id} 持有至 ${row.lease_until}`);
+        }
+        const leaseUntil = now + LEASE_TTL_MS;
+        db.handle.prepare(`INSERT INTO leases (dataset, resource, device_id, client_id, lease_until)
+                VALUES (?, ?, ?, ?, ?)
+                ON CONFLICT(dataset, resource) DO UPDATE SET
+                  device_id = excluded.device_id, client_id = excluded.client_id, lease_until = excluded.lease_until`).run(DEFAULT_DATASET, resource, deviceId, clientId, leaseUntil);
+        return {
+            resource,
+            deviceId,
+            clientId,
+            leaseUntil,
+            acquired: row === undefined || row.device_id !== deviceId || row.client_id !== clientId || row.lease_until <= now
+        };
+    });
+}
+export function requireLease(db, resource, deviceId, clientId, now = Date.now()) {
+    if (clientId === '') throw new SyncError('bad-request', '缺少 clientInstanceId');
+    const row = db.handle.prepare('SELECT device_id, client_id, lease_until FROM leases WHERE dataset = ? AND resource = ?').get(DEFAULT_DATASET, resource);
+    if (row === undefined || row.device_id !== deviceId || row.client_id !== clientId || row.lease_until <= now) {
+        throw new SyncError('lease-held', `${resource} 的租约未由当前设备/客户端持有或已过期`);
+    }
+    return row;
+}
+export function releaseLease(db, resource, deviceId, clientId) {
+    const result = db.handle.prepare('DELETE FROM leases WHERE dataset = ? AND resource = ? AND device_id = ? AND client_id = ?').run(DEFAULT_DATASET, resource, deviceId, clientId);
+    return Number(result.changes) > 0;
+}
+
+
+//# sourceURL=leases.ts

package/dist/sessions.js

@@ -0,0 +1,218 @@
+import { existsSync } from 'node:fs';
+import { assertChain, buildManifest, manifestDigest } from './shared/chain.js';
+import { SyncError } from './shared/wire.js';
+import { blobPath } from './blobs.js';
+import { DEFAULT_DATASET, bumpRevision, readRevision, withTransaction } from './db.js';
+import { requireLease as requireResourceLease, SYNC_RESOURCE } from './leases.js';
+export const MAX_APPEND_BODY_BYTES = 8 * 1024 * 1024;
+const HASH = /^[0-9a-f]{64}$/u;
+const KEY_ID = /^[0-9a-f]{16}$/u;
+function assertRef(frame, expectedIndex) {
+    if (frame.index !== expectedIndex) throw new SyncError('bad-request', `帧下标应为 ${expectedIndex}，实际是 ${frame.index}`);
+    if (!HASH.test(frame.chainHash) || !HASH.test(frame.blobSha256)) throw new SyncError('bad-request', `帧 ${expectedIndex} 的哈希非法`);
+    if (!KEY_ID.test(frame.keyId)) throw new SyncError('bad-request', `帧 ${expectedIndex} 的 keyId 非法`);
+    if (!Number.isSafeInteger(frame.bytes) || frame.bytes <= 0) throw new SyncError('bad-request', `帧 ${expectedIndex} 的字节数非法`);
+    if (!Number.isSafeInteger(frame.sealedVersion) || frame.sealedVersion < 1) throw new SyncError('bad-request', `帧 ${expectedIndex} 的封帧版本非法`);
+    if (!Number.isSafeInteger(frame.seqFrom) || !Number.isSafeInteger(frame.seqTo)) throw new SyncError('bad-request', `帧 ${expectedIndex} 的 seq 非法`);
+}
+function toChain(frames) {
+    return frames.map((frame)=>({
+            index: frame.index,
+            chainHash: frame.chainHash,
+            seqFrom: frame.seqFrom,
+            seqTo: frame.seqTo
+        }));
+}
+function sessionRow(db, sessionId) {
+    return db.handle.prepare('SELECT created_at, format_version, last_seq, frame_count, head_chain_hash, manifest_json, manifest_digest, revision, updated_at, deleted_at FROM sessions WHERE dataset = ? AND session_id = ?').get(DEFAULT_DATASET, sessionId);
+}
+function manifestOf(sessionId, formatVersion, createdAt, updatedAt, frames, tailOpen, safeThroughSeq, workspaceKey) {
+    assertChain(toChain(frames));
+    const manifest = buildManifest({
+        sessionId,
+        formatVersion,
+        createdAt,
+        updatedAt,
+        frames,
+        ...tailOpen === undefined ? {} : {
+            tailOpen
+        },
+        ...safeThroughSeq === undefined ? {} : {
+            safeThroughSeq
+        },
+        ...workspaceKey === undefined ? {} : {
+            workspaceKey
+        }
+    });
+    return {
+        manifest,
+        digest: manifestDigest(manifest),
+        headChainHash: frames[frames.length - 1].chainHash
+    };
+}
+export function appendFrames(db, dataDir, input, now = Date.now()) {
+    return withTransaction(db, ()=>{
+        requireResourceLease(db, SYNC_RESOURCE, input.deviceId, input.clientId, now);
+        const row = sessionRow(db, input.sessionId);
+        let combined;
+        let formatVersion = input.formatVersion;
+        let createdAt = input.createdAt;
+        let workspaceKey = input.workspaceKey;
+        if (row !== undefined && row.deleted_at !== null && row.created_at === input.createdAt) {
+            throw new SyncError('gone', `会话 ${input.sessionId} 的这个生命周期已被删除`);
+        }
+        const replacingLifecycle = row !== undefined && row.deleted_at !== null && row.created_at !== input.createdAt;
+        if (row !== undefined && row.deleted_at === null && row.created_at !== input.createdAt) {
+            throw new SyncError('conflict', `会话 ${input.sessionId} 已存在另一个生命周期（createdAt=${row.created_at}）`);
+        }
+        if (row === undefined || replacingLifecycle) {
+            if (input.baseIndex !== -1 || input.baseChainHash !== null) throw new SyncError('conflict', '新会话必须从 baseIndex=-1 开始');
+            if (input.frames.length === 0) throw new SyncError('bad-request', 'append 至少需要一帧');
+            combined = [
+                ...input.frames
+            ];
+        } else {
+            const existing = JSON.parse(row.manifest_json);
+            formatVersion = existing.formatVersion;
+            createdAt = existing.createdAt;
+            if (workspaceKey !== undefined && existing.workspaceKey !== undefined && workspaceKey !== existing.workspaceKey) {
+                throw new SyncError('conflict', 'append 的 workspaceKey 与已存 manifest 不一致');
+            }
+            if (workspaceKey === undefined && existing.workspaceKey !== undefined) workspaceKey = existing.workspaceKey;
+            if (workspaceKey !== undefined && existing.workspaceKey === undefined) {
+                throw new SyncError('conflict', '已有会话缺少 workspaceKey，不能在后续 append 补写');
+            }
+            const start = input.baseIndex + 1;
+            if (start < 0 || start > existing.frames.length) throw new SyncError('diverged', `baseIndex=${input.baseIndex} 超出链长 ${existing.frames.length}`);
+            if (start < existing.frames.length - 1) throw new SyncError('diverged', '只能追加或替换尾帧');
+            if (input.baseIndex >= 0) {
+                const base = existing.frames[input.baseIndex];
+                if (base === undefined || base.chainHash !== input.baseChainHash) throw new SyncError('diverged', 'baseChainHash 与当前链不匹配');
+            } else if (existing.frames.length !== 0) {
+                throw new SyncError('diverged', 'baseIndex=-1 但会话已存在');
+            }
+            if (input.frames.length === 0) throw new SyncError('bad-request', 'append 至少需要一帧');
+            combined = [
+                ...existing.frames.slice(0, start),
+                ...input.frames
+            ];
+        }
+        for (const frame of input.frames){
+            if (!existsSync(blobPath(dataDir, frame.blobSha256))) throw new SyncError('bad-request', `帧 ${frame.index} 的 blob 尚未上传`);
+        }
+        input.frames.forEach((frame, offset)=>assertRef(frame, (row === undefined || replacingLifecycle ? 0 : input.baseIndex + 1) + offset));
+        const { manifest, digest, headChainHash } = manifestOf(input.sessionId, formatVersion, createdAt, now, combined, input.tailOpen, input.safeThroughSeq, workspaceKey);
+        const revision = bumpRevision(db);
+        db.handle.prepare(`INSERT INTO sessions (dataset, session_id, created_at, format_version, last_seq, frame_count, head_chain_hash, manifest_json, manifest_digest, revision, updated_at, deleted_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)
+                ON CONFLICT(dataset, session_id) DO UPDATE SET
+                  created_at = excluded.created_at, format_version = excluded.format_version, last_seq = excluded.last_seq,
+                  frame_count = excluded.frame_count, head_chain_hash = excluded.head_chain_hash,
+                  manifest_json = excluded.manifest_json, manifest_digest = excluded.manifest_digest,
+                  revision = excluded.revision, updated_at = excluded.updated_at, deleted_at = NULL`).run(DEFAULT_DATASET, input.sessionId, createdAt, formatVersion, manifest.lastSeq, combined.length, headChainHash, JSON.stringify(manifest), digest, revision, now);
+        return {
+            sessionId: input.sessionId,
+            revision,
+            batchCount: combined.length,
+            headChainHash,
+            manifestDigest: digest,
+            lastSeq: manifest.lastSeq,
+            updatedAt: now,
+            deletedAt: null
+        };
+    });
+}
+export function deleteSession(db, sessionId, deviceId, clientId, createdAt, now = Date.now()) {
+    return withTransaction(db, ()=>{
+        requireResourceLease(db, SYNC_RESOURCE, deviceId, clientId, now);
+        const row = sessionRow(db, sessionId);
+        if (row === undefined) throw new SyncError('not-found', `没有会话 ${sessionId}`);
+        if (row.created_at !== createdAt) throw new SyncError('conflict', 'createdAt 与当前生命周期不符');
+        if (row.deleted_at !== null) throw new SyncError('gone', `会话 ${sessionId} 已删除`);
+        const revision = bumpRevision(db);
+        db.handle.prepare('UPDATE sessions SET deleted_at = ?, revision = ?, updated_at = ? WHERE dataset = ? AND session_id = ?').run(now, revision, now, DEFAULT_DATASET, sessionId);
+        db.handle.prepare('INSERT OR REPLACE INTO tombstones (dataset, session_id, created_at, deleted_at, deleted_by) VALUES (?, ?, ?, ?, ?)').run(DEFAULT_DATASET, sessionId, createdAt, now, deviceId);
+        return {
+            sessionId,
+            revision,
+            batchCount: row.frame_count,
+            headChainHash: row.head_chain_hash,
+            manifestDigest: row.manifest_digest,
+            lastSeq: row.last_seq,
+            updatedAt: now,
+            deletedAt: now
+        };
+    });
+}
+export function getManifest(db, sessionId) {
+    const row = sessionRow(db, sessionId);
+    if (row === undefined) return undefined;
+    return {
+        manifest: JSON.parse(row.manifest_json),
+        revision: row.revision
+    };
+}
+export function listBatches(db, sessionId, from, limit) {
+    const row = sessionRow(db, sessionId);
+    if (row === undefined) return undefined;
+    const manifest = JSON.parse(row.manifest_json);
+    return {
+        batches: manifest.frames.slice(from, from + limit),
+        batchCount: manifest.frames.length,
+        revision: row.revision
+    };
+}
+export function adminSessions(db, limit = 500) {
+    const rows = db.handle.prepare(`SELECT s.session_id, s.created_at, s.format_version, s.frame_count, s.last_seq, s.head_chain_hash,
+                     s.revision, s.updated_at, s.deleted_at,
+                     json_extract(s.manifest_json, '$.workspaceKey') AS workspace_key
+              FROM sessions s
+              WHERE s.dataset = ? ORDER BY s.updated_at DESC LIMIT ?`).all(DEFAULT_DATASET, limit);
+    return rows.map((row)=>({
+            sessionId: row.session_id,
+            createdAt: row.created_at,
+            formatVersion: row.format_version,
+            batchCount: row.frame_count,
+            lastSeq: row.last_seq,
+            headChainHash: row.head_chain_hash,
+            revision: row.revision,
+            updatedAt: row.updated_at,
+            deletedAt: row.deleted_at,
+            workspaceKey: row.workspace_key === null ? null : String(row.workspace_key)
+        }));
+}
+export function sessionCounts(db) {
+    const row = db.handle.prepare('SELECT COUNT(*) AS total, COALESCE(SUM(CASE WHEN deleted_at IS NULL THEN 0 ELSE 1 END), 0) AS deleted FROM sessions WHERE dataset = ?').get(DEFAULT_DATASET);
+    return {
+        total: Number(row?.total ?? 0),
+        deleted: Number(row?.deleted ?? 0)
+    };
+}
+export function listChanges(db, since, limit) {
+    const rows = db.handle.prepare('SELECT session_id, created_at, format_version, frame_count, head_chain_hash, manifest_digest, revision, updated_at, deleted_at FROM sessions WHERE dataset = ? AND revision > ? ORDER BY revision ASC LIMIT ?').all(DEFAULT_DATASET, since, limit + 1);
+    const tombstones = db.handle.prepare('SELECT session_id, created_at, deleted_at FROM tombstones WHERE dataset = ? AND deleted_at > ? ORDER BY deleted_at ASC LIMIT ?').all(DEFAULT_DATASET, since, limit + 1);
+    const sessions = rows.slice(0, limit).map((row)=>({
+            sessionId: row.session_id,
+            revision: row.revision,
+            formatVersion: row.format_version,
+            createdAt: row.created_at,
+            batchCount: row.frame_count,
+            headChainHash: row.head_chain_hash,
+            manifestDigest: row.manifest_digest,
+            updatedAt: row.updated_at,
+            deletedAt: row.deleted_at
+        }));
+    return {
+        revision: readRevision(db),
+        sessions,
+        tombstones: tombstones.slice(0, limit).map((row)=>({
+                sessionId: row.session_id,
+                createdAt: row.created_at,
+                deletedAt: row.deleted_at
+            })),
+        hasMore: rows.length > limit || tombstones.length > limit
+    };
+}
+
+
+//# sourceURL=sessions.ts

package/dist/shared/batches.js

@@ -0,0 +1,214 @@
+import { sha256 } from './crypto.js';
+import { stableStringify } from './chain.js';
+import { openSealedFrame, sealFrame } from './sealed-frame.js';
+export const HEADER_INDEX = 0;
+export const HEADER_SEQ = -1;
+export const DEFAULT_BATCH_EVENTS = 50;
+export const DEFAULT_BATCH_BYTES = 256 * 1024;
+export function headerMetaOf(header, inheritedEventCount) {
+    return {
+        formatVersion: header.version,
+        createdAt: header.createdAt,
+        isSeeded: header.isSeeded,
+        delegationDepth: header.delegationDepth ?? 0,
+        ...header.agentPreset === undefined ? {} : {
+            agentPreset: header.agentPreset
+        },
+        ...header.parentSession === undefined ? {} : {
+            parentSession: header.parentSession
+        },
+        ...header.origin === undefined ? {} : {
+            origin: header.origin
+        },
+        ...header.isSeeded ? {
+            inheritedEventCount: inheritedEventCount ?? 0
+        } : {}
+    };
+}
+export function headerChainHash(meta) {
+    return sha256(stableStringify(meta));
+}
+export function sealHeader(meta, sessionId, sessionKey) {
+    const plain = Buffer.from(stableStringify(meta), 'utf8');
+    return sealFrame(plain, {
+        sessionId,
+        index: HEADER_INDEX,
+        seqFrom: HEADER_SEQ,
+        seqTo: HEADER_SEQ
+    }, sessionKey);
+}
+export function openHeader(sealed, ref, sessionId, sessionKey) {
+    if (ref.index !== HEADER_INDEX || ref.seqFrom !== HEADER_SEQ || ref.seqTo !== HEADER_SEQ) {
+        throw new Error('第 0 个链条目不是会话头');
+    }
+    const plain = openSealedFrame(sealed, {
+        sessionId,
+        index: ref.index,
+        seqFrom: ref.seqFrom,
+        seqTo: ref.seqTo,
+        chainHash: ref.chainHash
+    }, sessionKey);
+    return parseHeaderMeta(JSON.parse(plain.toString('utf8')));
+}
+function parseEvents(value) {
+    if (!Array.isArray(value)) throw new Error('批次不是事件数组');
+    return value.map((entry, position)=>{
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) throw new Error(`批次第 ${position} 项不是事件对象`);
+        const seq = entry['seq'];
+        if (!Number.isSafeInteger(seq) || seq < 0) throw new Error(`批次第 ${position} 项的 seq 非法`);
+        return entry;
+    });
+}
+function parseHeaderMeta(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new Error('会话头不是对象');
+    const record = value;
+    const formatVersion = record['formatVersion'];
+    const createdAt = record['createdAt'];
+    const isSeeded = record['isSeeded'];
+    const delegationDepth = record['delegationDepth'];
+    if (!Number.isSafeInteger(formatVersion) || formatVersion < 1) throw new Error('会话头 formatVersion 非法');
+    if (!Number.isSafeInteger(createdAt)) throw new Error('会话头 createdAt 非法');
+    if (typeof isSeeded !== 'boolean') throw new Error('会话头 isSeeded 非法');
+    if (!Number.isSafeInteger(delegationDepth) || delegationDepth < 0) throw new Error('会话头 delegationDepth 非法');
+    const stringField = (key)=>{
+        const field = record[key];
+        if (field === undefined) return undefined;
+        if (typeof field !== 'string') throw new Error(`会话头 ${key} 非法`);
+        return field;
+    };
+    const inherited = record['inheritedEventCount'];
+    if (inherited !== undefined && (!Number.isSafeInteger(inherited) || inherited < 0)) {
+        throw new Error('会话头 inheritedEventCount 非法');
+    }
+    const agentPreset = stringField('agentPreset');
+    const parentSession = stringField('parentSession');
+    const origin = stringField('origin');
+    return {
+        formatVersion: formatVersion,
+        createdAt: createdAt,
+        isSeeded,
+        delegationDepth: delegationDepth,
+        ...agentPreset === undefined ? {} : {
+            agentPreset
+        },
+        ...parentSession === undefined ? {} : {
+            parentSession
+        },
+        ...origin === undefined ? {} : {
+            origin
+        },
+        ...inherited === undefined ? {} : {
+            inheritedEventCount: inherited
+        }
+    };
+}
+export function serializeEventBatch(events) {
+    return stableStringify(events);
+}
+export function eventBatchHash(events) {
+    return sha256(serializeEventBatch(events));
+}
+export function sealEventBatchFromText(text, sessionId, index, seqFrom, seqTo, sessionKey) {
+    if (index < 1) throw new Error('事件批次的链下标必须 >= 1');
+    if (seqFrom > seqTo) throw new Error('事件批次的 seq 区间非法');
+    return sealFrame(Buffer.from(text, 'utf8'), {
+        sessionId,
+        index,
+        seqFrom,
+        seqTo
+    }, sessionKey);
+}
+export function sealEventBatch(events, sessionId, index, sessionKey) {
+    if (index < 1) throw new Error('事件批次的链下标必须 >= 1');
+    if (events.length === 0) throw new Error('不能封空批次');
+    const seqFrom = events[0].seq;
+    const seqTo = events[events.length - 1].seq;
+    assertContiguous(events, seqFrom, seqTo);
+    return sealEventBatchFromText(serializeEventBatch(events), sessionId, index, seqFrom, seqTo, sessionKey);
+}
+export function openEventBatch(sealed, ref, sessionId, sessionKey) {
+    const plain = openSealedFrame(sealed, {
+        sessionId,
+        index: ref.index,
+        seqFrom: ref.seqFrom,
+        seqTo: ref.seqTo,
+        chainHash: ref.chainHash
+    }, sessionKey);
+    const events = parseEvents(JSON.parse(plain.toString('utf8')));
+    if (events.length !== ref.seqTo - ref.seqFrom + 1) throw new Error('批次事件数与 seq 区间不符');
+    if (events.length === 0 || events[0].seq !== ref.seqFrom || events[events.length - 1].seq !== ref.seqTo) {
+        throw new Error('批次首尾 seq 与清单不符');
+    }
+    assertContiguous(events, ref.seqFrom, ref.seqTo);
+    return events;
+}
+function assertContiguous(events, seqFrom, seqTo) {
+    if (events.length !== seqTo - seqFrom + 1) throw new Error('事件数与 seq 区间不符');
+    events.forEach((event, offset)=>{
+        if (event.seq !== seqFrom + offset) throw new Error(`第 ${offset} 个事件的 seq 应为 ${seqFrom + offset}，实际是 ${event.seq}`);
+    });
+}
+export function* iterateEventBatches(events, startAfterSeq, options = {}, includeText = true) {
+    const maxEvents = options.maxEvents ?? DEFAULT_BATCH_EVENTS;
+    const maxBytes = options.maxBytes ?? DEFAULT_BATCH_BYTES;
+    if (!Number.isSafeInteger(maxEvents) || maxEvents < 1) throw new Error('maxEvents 必须是正整数');
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new Error('maxBytes 必须是正整数');
+    events.forEach((event, offset)=>{
+        if (!Number.isSafeInteger(event.seq) || event.seq < 0) throw new Error(`第 ${offset} 个事件的 seq 非法`);
+        if (offset > 0 && events[offset - 1].seq + 1 !== event.seq) throw new Error(`事件 seq 不连续：${events[offset - 1].seq} -> ${event.seq}`);
+    });
+    const pending = events.filter((event)=>event.seq > startAfterSeq);
+    if (pending.length === 0) return;
+    if (pending[0].seq !== startAfterSeq + 1) throw new Error(`待传事件应从 ${startAfterSeq + 1} 开始，实际是 ${pending[0].seq}`);
+    let current = [];
+    let currentTexts = includeText ? [] : undefined;
+    let currentBytes = 2;
+    for (const event of pending){
+        const eventText = stableStringify(event);
+        const eventBytes = Buffer.byteLength(eventText, 'utf8');
+        const candidateBytes = current.length === 0 ? currentBytes + eventBytes : currentBytes + 1 + eventBytes;
+        const candidateLength = current.length + 1;
+        if (current.length > 0 && (candidateLength > maxEvents || candidateBytes > maxBytes)) {
+            yield {
+                seqFrom: current[0].seq,
+                seqTo: current[current.length - 1].seq,
+                events: current,
+                bytes: currentBytes,
+                text: currentTexts === undefined ? '' : `[${currentTexts.join(',')}]`
+            };
+            current = [
+                event
+            ];
+            currentTexts = includeText ? [
+                eventText
+            ] : undefined;
+            currentBytes = 2 + eventBytes;
+        } else {
+            current.push(event);
+            currentTexts?.push(eventText);
+            currentBytes = candidateBytes;
+        }
+    }
+    if (current.length > 0) {
+        yield {
+            seqFrom: current[0].seq,
+            seqTo: current[current.length - 1].seq,
+            events: current,
+            bytes: currentBytes,
+            text: currentTexts === undefined ? '' : `[${currentTexts.join(',')}]`
+        };
+    }
+}
+export function planEventBatches(events, startAfterSeq, options = {}) {
+    return [
+        ...iterateEventBatches(events, startAfterSeq, options, false)
+    ].map(({ seqFrom, seqTo, events: batchEvents, bytes })=>({
+            seqFrom,
+            seqTo,
+            events: batchEvents,
+            bytes
+        }));
+}
+
+
+//# sourceURL=batches.ts