@averyyy/pi-coding-agent 0.82.1-piclient.3 → 0.82.1-piclient.5

package/dist/core/pi-server-compact-state.d.ts

@@ -0,0 +1,81 @@
+declare const COMPACT_STATE_VERSION = 1;
+interface PiServerCompactStateBase {
+    version: typeof COMPACT_STATE_VERSION;
+    sequence: number;
+    timestamp: number;
+}
+export interface PiServerPendingCompactState extends PiServerCompactStateBase {
+    kind: "compact";
+    serverHash: string;
+    sessionId: string;
+    operationId: string;
+    requestHash: string;
+    baseStaticContextHash: string;
+    baseTreeHash: string;
+    baseEntryCount: number;
+    baseLeafId: string | null;
+    baseRevision: number;
+    observation?: PiServerCompactObservationState;
+}
+export interface PiServerAppliedCompactState extends PiServerCompactStateBase {
+    kind: "applied";
+    operationId: string;
+    requestHash: string;
+    entryId: string;
+    entryHash: string;
+    updatedTreeHash: string;
+    updatedLeafId: string;
+    updatedRevision: number;
+    resolution: "tree_applied";
+}
+export interface PiServerTerminalCompactState extends PiServerCompactStateBase {
+    kind: "terminal";
+    operationId: string;
+    requestHash: string;
+    httpStatus: number;
+    error: string;
+    operationDisposition: "terminal" | "not_started";
+    status: "failed" | "rejected";
+    resolution: "terminal_failed_observed" | "server_rejected";
+}
+export type PiServerCompactObservationState = PiServerAppliedCompactState | PiServerTerminalCompactState;
+export type PiServerCompactAcknowledgementResolution = "server_ack" | "server_missing_after_tree_applied" | "server_missing_after_terminal_failure" | "server_rejected_not_started";
+export interface WritePiServerPendingCompactInput {
+    serverHash: string;
+    sessionId: string;
+    operationId: string;
+    requestHash: string;
+    baseStaticContextHash: string;
+    baseTreeHash: string;
+    baseEntryCount: number;
+    baseLeafId: string | null;
+    baseRevision: number;
+    timestamp?: number;
+}
+export interface WritePiServerAppliedCompactInput {
+    operationId: string;
+    requestHash: string;
+    entryId: string;
+    entryHash: string;
+    updatedTreeHash: string;
+    updatedLeafId: string;
+    updatedRevision: number;
+    timestamp?: number;
+}
+export interface WritePiServerTerminalCompactInput {
+    operationId: string;
+    requestHash: string;
+    httpStatus: number;
+    error: string;
+    operationDisposition: "terminal" | "not_started";
+    status: "failed" | "rejected";
+    timestamp?: number;
+}
+export declare function getPiServerCompactStatePath(sessionFile: string): string;
+export declare function readPiServerPendingCompact(path: string): PiServerPendingCompactState | undefined;
+export declare function writePiServerPendingCompact(path: string, input: WritePiServerPendingCompactInput): PiServerPendingCompactState;
+export declare function writePiServerAppliedCompact(path: string, input: WritePiServerAppliedCompactInput): PiServerAppliedCompactState;
+export declare function writePiServerTerminalCompact(path: string, input: WritePiServerTerminalCompactInput): PiServerTerminalCompactState;
+export declare function acknowledgePiServerPendingCompact(path: string, operationId: string, resolution?: PiServerCompactAcknowledgementResolution, timestamp?: number): void;
+export {};
+//# sourceMappingURL=pi-server-compact-state.d.ts.map

package/dist/core/pi-server-compact-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-server-compact-state.d.ts","sourceRoot":"","sources":["../../src/core/pi-server-compact-state.ts"],"names":[],"mappings":"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","sourcesContent":["import { Buffer } from \"node:buffer\";\nimport { createHash } from \"node:crypto\";\nimport { closeSync, existsSync, fsyncSync, openSync, readFileSync, truncateSync, writeSync } from \"node:fs\";\nimport { dirname, resolve } from \"node:path\";\nimport { DatabaseSync } from \"node:sqlite\";\n\nconst COMPACT_STATE_VERSION = 1;\nconst COMPACT_STATE_MAX_BYTES = 8 * 1024 * 1024;\nconst SHA256_PATTERN = /^[a-f0-9]{64}$/u;\nconst IDENTIFIER_MAX_CHARS = 4096;\nconst ERROR_MAX_CHARS = 1024 * 1024;\n\ninterface PiServerCompactStateBase {\n\tversion: typeof COMPACT_STATE_VERSION;\n\tsequence: number;\n\ttimestamp: number;\n}\n\nexport interface PiServerPendingCompactState extends PiServerCompactStateBase {\n\tkind: \"compact\";\n\tserverHash: string;\n\tsessionId: string;\n\toperationId: string;\n\trequestHash: string;\n\tbaseStaticContextHash: string;\n\tbaseTreeHash: string;\n\tbaseEntryCount: number;\n\tbaseLeafId: string | null;\n\tbaseRevision: number;\n\tobservation?: PiServerCompactObservationState;\n}\n\nexport interface PiServerAppliedCompactState extends PiServerCompactStateBase {\n\tkind: \"applied\";\n\toperationId: string;\n\trequestHash: string;\n\tentryId: string;\n\tentryHash: string;\n\tupdatedTreeHash: string;\n\tupdatedLeafId: string;\n\tupdatedRevision: number;\n\tresolution: \"tree_applied\";\n}\n\nexport interface PiServerTerminalCompactState extends PiServerCompactStateBase {\n\tkind: \"terminal\";\n\toperationId: string;\n\trequestHash: string;\n\thttpStatus: number;\n\terror: string;\n\toperationDisposition: \"terminal\" | \"not_started\";\n\tstatus: \"failed\" | \"rejected\";\n\tresolution: \"terminal_failed_observed\" | \"server_rejected\";\n}\n\nexport type PiServerCompactObservationState = PiServerAppliedCompactState | PiServerTerminalCompactState;\n\nexport type PiServerCompactAcknowledgementResolution =\n\t| \"server_ack\"\n\t| \"server_missing_after_tree_applied\"\n\t| \"server_missing_after_terminal_failure\"\n\t| \"server_rejected_not_started\";\n\ninterface PiServerAcknowledgedCompactState extends PiServerCompactStateBase {\n\tkind: \"ack\";\n\toperationId: string;\n\tresolution: PiServerCompactAcknowledgementResolution;\n}\n\ntype PiServerCompactStateRecord =\n\t| PiServerPendingCompactState\n\t| PiServerCompactObservationState\n\t| PiServerAcknowledgedCompactState;\n\ninterface ParsedPiServerCompactState {\n\tnextSequence: number;\n\tpending: PiServerPendingCompactState | undefined;\n}\n\nexport interface WritePiServerPendingCompactInput {\n\tserverHash: string;\n\tsessionId: string;\n\toperationId: string;\n\trequestHash: string;\n\tbaseStaticContextHash: string;\n\tbaseTreeHash: string;\n\tbaseEntryCount: number;\n\tbaseLeafId: string | null;\n\tbaseRevision: number;\n\ttimestamp?: number;\n}\n\nexport interface WritePiServerAppliedCompactInput {\n\toperationId: string;\n\trequestHash: string;\n\tentryId: string;\n\tentryHash: string;\n\tupdatedTreeHash: string;\n\tupdatedLeafId: string;\n\tupdatedRevision: number;\n\ttimestamp?: number;\n}\n\nexport interface WritePiServerTerminalCompactInput {\n\toperationId: string;\n\trequestHash: string;\n\thttpStatus: number;\n\terror: string;\n\toperationDisposition: \"terminal\" | \"not_started\";\n\tstatus: \"failed\" | \"rejected\";\n\ttimestamp?: number;\n}\n\nfunction sha256(value: string): string {\n\treturn createHash(\"sha256\").update(value).digest(\"hex\");\n}\n\nfunction assertObject(value: unknown, path: string): asserts value is Record<string, unknown> {\n\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n\t\tthrow new Error(`${path} must be an object`);\n\t}\n}\n\nfunction assertIdentifier(value: unknown, path: string): asserts value is string {\n\tif (typeof value !== \"string\" || value.length === 0 || value.length > IDENTIFIER_MAX_CHARS || value.includes(\"\\0\")) {\n\t\tthrow new Error(`${path} must be a non-empty string without NUL bytes`);\n\t}\n}\n\nfunction assertHash(value: unknown, path: string, allowEmpty = false): asserts value is string {\n\tif (\n\t\ttypeof value !== \"string\" ||\n\t\t(!allowEmpty && !SHA256_PATTERN.test(value)) ||\n\t\t(allowEmpty && value !== \"\" && !SHA256_PATTERN.test(value))\n\t) {\n\t\tthrow new Error(`${path} must be ${allowEmpty ? \"empty or \" : \"\"}a lowercase SHA-256 digest`);\n\t}\n}\n\nfunction assertError(value: unknown, path: string): asserts value is string {\n\tif (typeof value !== \"string\" || value.length === 0 || value.length > ERROR_MAX_CHARS || value.includes(\"\\0\")) {\n\t\tthrow new Error(`${path} must be a non-empty string without NUL bytes`);\n\t}\n}\n\nfunction assertNonNegativeSafeInteger(value: unknown, path: string): asserts value is number {\n\tif (!Number.isSafeInteger(value) || (value as number) < 0) {\n\t\tthrow new Error(`${path} must be a non-negative safe integer`);\n\t}\n}\n\nfunction parsePayload(payload: string, lineNumber: number): PiServerCompactStateRecord {\n\tlet value: unknown;\n\ttry {\n\t\tvalue = JSON.parse(payload) as unknown;\n\t} catch (error) {\n\t\tthrow new Error(`pi-server compact state payload is invalid JSON at line ${lineNumber}`, { cause: error });\n\t}\n\tassertObject(value, `pi-server compact state line ${lineNumber}`);\n\tif (value.version !== COMPACT_STATE_VERSION) {\n\t\tthrow new Error(`Unsupported pi-server compact state version at line ${lineNumber}`);\n\t}\n\tassertNonNegativeSafeInteger(value.sequence, `pi-server compact state line ${lineNumber}.sequence`);\n\tassertNonNegativeSafeInteger(value.timestamp, `pi-server compact state line ${lineNumber}.timestamp`);\n\tif (value.kind === \"ack\") {\n\t\tassertIdentifier(value.operationId, `pi-server compact state line ${lineNumber}.operationId`);\n\t\tif (\n\t\t\tvalue.resolution !== \"server_ack\" &&\n\t\t\tvalue.resolution !== \"server_missing_after_tree_applied\" &&\n\t\t\tvalue.resolution !== \"server_missing_after_terminal_failure\" &&\n\t\t\tvalue.resolution !== \"server_rejected_not_started\"\n\t\t) {\n\t\t\tthrow new Error(`pi-server compact state acknowledgement resolution is invalid at line ${lineNumber}`);\n\t\t}\n\t\treturn {\n\t\t\tversion: COMPACT_STATE_VERSION,\n\t\t\tkind: \"ack\",\n\t\t\tsequence: value.sequence,\n\t\t\ttimestamp: value.timestamp,\n\t\t\toperationId: value.operationId,\n\t\t\tresolution: value.resolution,\n\t\t};\n\t}\n\tif (value.kind === \"applied\") {\n\t\tassertIdentifier(value.operationId, `pi-server compact state line ${lineNumber}.operationId`);\n\t\tassertHash(value.requestHash, `pi-server compact state line ${lineNumber}.requestHash`);\n\t\tassertIdentifier(value.entryId, `pi-server compact state line ${lineNumber}.entryId`);\n\t\tassertHash(value.entryHash, `pi-server compact state line ${lineNumber}.entryHash`);\n\t\tassertHash(value.updatedTreeHash, `pi-server compact state line ${lineNumber}.updatedTreeHash`);\n\t\tassertIdentifier(value.updatedLeafId, `pi-server compact state line ${lineNumber}.updatedLeafId`);\n\t\tassertNonNegativeSafeInteger(value.updatedRevision, `pi-server compact state line ${lineNumber}.updatedRevision`);\n\t\tif (value.resolution !== \"tree_applied\") {\n\t\t\tthrow new Error(`pi-server compact applied resolution is invalid at line ${lineNumber}`);\n\t\t}\n\t\treturn {\n\t\t\tversion: COMPACT_STATE_VERSION,\n\t\t\tkind: \"applied\",\n\t\t\tsequence: value.sequence,\n\t\t\ttimestamp: value.timestamp,\n\t\t\toperationId: value.operationId,\n\t\t\trequestHash: value.requestHash,\n\t\t\tentryId: value.entryId,\n\t\t\tentryHash: value.entryHash,\n\t\t\tupdatedTreeHash: value.updatedTreeHash,\n\t\t\tupdatedLeafId: value.updatedLeafId,\n\t\t\tupdatedRevision: value.updatedRevision,\n\t\t\tresolution: value.resolution,\n\t\t};\n\t}\n\tif (value.kind === \"terminal\") {\n\t\tassertIdentifier(value.operationId, `pi-server compact state line ${lineNumber}.operationId`);\n\t\tassertHash(value.requestHash, `pi-server compact state line ${lineNumber}.requestHash`);\n\t\tif (\n\t\t\t!Number.isSafeInteger(value.httpStatus) ||\n\t\t\t(value.httpStatus as number) < 100 ||\n\t\t\t(value.httpStatus as number) > 599\n\t\t) {\n\t\t\tthrow new Error(`pi-server compact terminal HTTP status is invalid at line ${lineNumber}`);\n\t\t}\n\t\tassertError(value.error, `pi-server compact state line ${lineNumber}.error`);\n\t\tif (\n\t\t\t(value.operationDisposition !== \"terminal\" && value.operationDisposition !== \"not_started\") ||\n\t\t\t(value.status !== \"failed\" && value.status !== \"rejected\") ||\n\t\t\t(value.operationDisposition === \"terminal\" && value.status !== \"failed\") ||\n\t\t\t(value.operationDisposition === \"not_started\" && value.status !== \"rejected\")\n\t\t) {\n\t\t\tthrow new Error(`pi-server compact terminal disposition is invalid at line ${lineNumber}`);\n\t\t}\n\t\tconst expectedResolution =\n\t\t\tvalue.operationDisposition === \"terminal\" ? \"terminal_failed_observed\" : \"server_rejected\";\n\t\tif (value.resolution !== expectedResolution) {\n\t\t\tthrow new Error(`pi-server compact terminal resolution is invalid at line ${lineNumber}`);\n\t\t}\n\t\treturn {\n\t\t\tversion: COMPACT_STATE_VERSION,\n\t\t\tkind: \"terminal\",\n\t\t\tsequence: value.sequence,\n\t\t\ttimestamp: value.timestamp,\n\t\t\toperationId: value.operationId,\n\t\t\trequestHash: value.requestHash,\n\t\t\thttpStatus: value.httpStatus as number,\n\t\t\terror: value.error,\n\t\t\toperationDisposition: value.operationDisposition,\n\t\t\tstatus: value.status,\n\t\t\tresolution: expectedResolution,\n\t\t};\n\t}\n\tif (value.kind !== \"compact\") {\n\t\tthrow new Error(`Unsupported pi-server compact state record kind at line ${lineNumber}`);\n\t}\n\tassertHash(value.serverHash, `pi-server compact state line ${lineNumber}.serverHash`);\n\tassertIdentifier(value.sessionId, `pi-server compact state line ${lineNumber}.sessionId`);\n\tassertIdentifier(value.operationId, `pi-server compact state line ${lineNumber}.operationId`);\n\tassertHash(value.requestHash, `pi-server compact state line ${lineNumber}.requestHash`);\n\tassertHash(value.baseStaticContextHash, `pi-server compact state line ${lineNumber}.baseStaticContextHash`, true);\n\tassertHash(value.baseTreeHash, `pi-server compact state line ${lineNumber}.baseTreeHash`);\n\tassertNonNegativeSafeInteger(value.baseEntryCount, `pi-server compact state line ${lineNumber}.baseEntryCount`);\n\tif (value.baseLeafId !== null) {\n\t\tassertIdentifier(value.baseLeafId, `pi-server compact state line ${lineNumber}.baseLeafId`);\n\t}\n\tassertNonNegativeSafeInteger(value.baseRevision, `pi-server compact state line ${lineNumber}.baseRevision`);\n\treturn {\n\t\tversion: COMPACT_STATE_VERSION,\n\t\tkind: \"compact\",\n\t\tsequence: value.sequence,\n\t\ttimestamp: value.timestamp,\n\t\tserverHash: value.serverHash,\n\t\tsessionId: value.sessionId,\n\t\toperationId: value.operationId,\n\t\trequestHash: value.requestHash,\n\t\tbaseStaticContextHash: value.baseStaticContextHash,\n\t\tbaseTreeHash: value.baseTreeHash,\n\t\tbaseEntryCount: value.baseEntryCount,\n\t\tbaseLeafId: value.baseLeafId,\n\t\tbaseRevision: value.baseRevision,\n\t};\n}\n\nfunction parseCompactStateFile(path: string): ParsedPiServerCompactState {\n\tif (!existsSync(path)) return { nextSequence: 0, pending: undefined };\n\tconst encoded = readFileSync(path);\n\tif (encoded.byteLength > COMPACT_STATE_MAX_BYTES) {\n\t\tthrow new Error(`pi-server compact state exceeds ${COMPACT_STATE_MAX_BYTES} bytes: ${path}`);\n\t}\n\tconst content = encoded.toString(\"utf-8\");\n\tconst lines = content.split(\"\\n\");\n\tif (!content.endsWith(\"\\n\")) lines.pop();\n\tlet expectedSequence = 0;\n\tlet pending: PiServerPendingCompactState | undefined;\n\tfor (const [index, line] of lines.entries()) {\n\t\tif (!line) continue;\n\t\tlet envelope: unknown;\n\t\ttry {\n\t\t\tenvelope = JSON.parse(line) as unknown;\n\t\t} catch (error) {\n\t\t\tthrow new Error(`pi-server compact state envelope is invalid JSON at line ${index + 1}`, {\n\t\t\t\tcause: error,\n\t\t\t});\n\t\t}\n\t\tassertObject(envelope, `pi-server compact state envelope line ${index + 1}`);\n\t\tif (typeof envelope.payload !== \"string\") {\n\t\t\tthrow new Error(`pi-server compact state envelope payload must be a string at line ${index + 1}`);\n\t\t}\n\t\tassertHash(envelope.sha256, `pi-server compact state envelope line ${index + 1}.sha256`);\n\t\tif (sha256(envelope.payload) !== envelope.sha256) {\n\t\t\tthrow new Error(`pi-server compact state checksum mismatch at line ${index + 1}`);\n\t\t}\n\t\tconst record = parsePayload(envelope.payload, index + 1);\n\t\tif (record.sequence !== expectedSequence) {\n\t\t\tthrow new Error(\n\t\t\t\t`pi-server compact state sequence mismatch at line ${index + 1}: expected ${expectedSequence}, received ${record.sequence}`,\n\t\t\t);\n\t\t}\n\t\texpectedSequence++;\n\t\tif (record.kind === \"compact\") {\n\t\t\tif (pending) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`pi-server compact state contains a new operation before ${pending.operationId} was acknowledged`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tpending = record;\n\t\t} else if (record.kind === \"applied\" || record.kind === \"terminal\") {\n\t\t\tif (\n\t\t\t\t!pending ||\n\t\t\t\tpending.operationId !== record.operationId ||\n\t\t\t\tpending.requestHash !== record.requestHash ||\n\t\t\t\tpending.observation\n\t\t\t) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`pi-server compact state observation does not match the pending operation at line ${index + 1}`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tpending = { ...pending, observation: record };\n\t\t} else {\n\t\t\tif (!pending || pending.operationId !== record.operationId) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`pi-server compact state acknowledgement does not match the pending operation at line ${index + 1}`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tpending = undefined;\n\t\t}\n\t}\n\treturn { nextSequence: expectedSequence, pending };\n}\n\nfunction appendRecord(path: string, record: PiServerCompactStateRecord): void {\n\tconst payload = JSON.stringify(record);\n\tconst encoded = Buffer.from(`${JSON.stringify({ payload, sha256: sha256(payload) })}\\n`, \"utf-8\");\n\tconst existing = existsSync(path) ? readFileSync(path) : Buffer.alloc(0);\n\tconst validBytes = existing.lastIndexOf(0x0a) + 1;\n\tif (validBytes !== existing.byteLength) truncateSync(path, validBytes);\n\tif (validBytes + encoded.byteLength > COMPACT_STATE_MAX_BYTES) {\n\t\tthrow new Error(`pi-server compact state would exceed ${COMPACT_STATE_MAX_BYTES} bytes: ${path}`);\n\t}\n\tconst fileExisted = existsSync(path);\n\tconst handle = openSync(path, \"a\", 0o600);\n\ttry {\n\t\tlet written = 0;\n\t\twhile (written < encoded.byteLength) {\n\t\t\tconst bytesWritten = writeSync(handle, encoded, written, encoded.byteLength - written);\n\t\t\tif (bytesWritten === 0) throw new Error(`Failed to make progress writing pi-server compact state: ${path}`);\n\t\t\twritten += bytesWritten;\n\t\t}\n\t\tfsyncSync(handle);\n\t} finally {\n\t\tcloseSync(handle);\n\t}\n\tif (!fileExisted && process.platform !== \"win32\") {\n\t\tconst directoryHandle = openSync(dirname(path), \"r\");\n\t\ttry {\n\t\t\tfsyncSync(directoryHandle);\n\t\t} finally {\n\t\t\tcloseSync(directoryHandle);\n\t\t}\n\t}\n}\n\nfunction withCompactStateLock<T>(path: string, operation: () => T): T {\n\tconst normalizedPath = resolve(path);\n\tconst database = new DatabaseSync(`${normalizedPath}.lock.sqlite`);\n\tlet transactionStarted = false;\n\ttry {\n\t\tdatabase.exec(\"PRAGMA busy_timeout = 0\");\n\t\tdatabase.exec(\"CREATE TABLE IF NOT EXISTS compact_state_lock (id INTEGER PRIMARY KEY CHECK (id = 1))\");\n\t\tdatabase.exec(\"BEGIN IMMEDIATE\");\n\t\ttransactionStarted = true;\n\t\treturn operation();\n\t} catch (error) {\n\t\tconst details = error instanceof Error ? error.message : String(error);\n\t\tthrow new Error(`Cannot update pi-server compact state ${normalizedPath}: ${details}`, { cause: error });\n\t} finally {\n\t\tif (transactionStarted) {\n\t\t\ttry {\n\t\t\t\tdatabase.exec(\"ROLLBACK\");\n\t\t\t} catch {\n\t\t\t\t// Closing the connection is the authoritative lock release.\n\t\t\t}\n\t\t}\n\t\tdatabase.close();\n\t}\n}\n\nexport function getPiServerCompactStatePath(sessionFile: string): string {\n\treturn `${sessionFile}.pi-server-compacts.jsonl`;\n}\n\nexport function readPiServerPendingCompact(path: string): PiServerPendingCompactState | undefined {\n\treturn parseCompactStateFile(path).pending;\n}\n\nexport function writePiServerPendingCompact(\n\tpath: string,\n\tinput: WritePiServerPendingCompactInput,\n): PiServerPendingCompactState {\n\treturn withCompactStateLock(path, () => {\n\t\tconst state = parseCompactStateFile(path);\n\t\tif (state.pending) {\n\t\t\tthrow new Error(\n\t\t\t\t`pi-server compaction ${state.pending.operationId} must be acknowledged before starting another compaction`,\n\t\t\t);\n\t\t}\n\t\tif (state.nextSequence > 0) {\n\t\t\ttruncateSync(path, 0);\n\t\t\tstate.nextSequence = 0;\n\t\t}\n\t\tconst timestamp = input.timestamp ?? Date.now();\n\t\tassertNonNegativeSafeInteger(timestamp, \"pi-server compact state timestamp\");\n\t\tassertHash(input.serverHash, \"pi-server compact state serverHash\");\n\t\tassertIdentifier(input.sessionId, \"pi-server compact state sessionId\");\n\t\tassertIdentifier(input.operationId, \"pi-server compact state operationId\");\n\t\tassertHash(input.requestHash, \"pi-server compact state requestHash\");\n\t\tassertHash(input.baseStaticContextHash, \"pi-server compact state baseStaticContextHash\", true);\n\t\tassertHash(input.baseTreeHash, \"pi-server compact state baseTreeHash\");\n\t\tassertNonNegativeSafeInteger(input.baseEntryCount, \"pi-server compact state baseEntryCount\");\n\t\tif (input.baseLeafId !== null) assertIdentifier(input.baseLeafId, \"pi-server compact state baseLeafId\");\n\t\tassertNonNegativeSafeInteger(input.baseRevision, \"pi-server compact state baseRevision\");\n\t\tconst record: PiServerPendingCompactState = {\n\t\t\tversion: COMPACT_STATE_VERSION,\n\t\t\tkind: \"compact\",\n\t\t\tsequence: state.nextSequence,\n\t\t\ttimestamp,\n\t\t\tserverHash: input.serverHash,\n\t\t\tsessionId: input.sessionId,\n\t\t\toperationId: input.operationId,\n\t\t\trequestHash: input.requestHash,\n\t\t\tbaseStaticContextHash: input.baseStaticContextHash,\n\t\t\tbaseTreeHash: input.baseTreeHash,\n\t\t\tbaseEntryCount: input.baseEntryCount,\n\t\t\tbaseLeafId: input.baseLeafId,\n\t\t\tbaseRevision: input.baseRevision,\n\t\t};\n\t\tappendRecord(path, record);\n\t\treturn record;\n\t});\n}\n\nexport function writePiServerAppliedCompact(\n\tpath: string,\n\tinput: WritePiServerAppliedCompactInput,\n): PiServerAppliedCompactState {\n\treturn withCompactStateLock(path, () => {\n\t\tconst state = parseCompactStateFile(path);\n\t\tconst pending = state.pending;\n\t\tif (!pending || pending.operationId !== input.operationId || pending.requestHash !== input.requestHash) {\n\t\t\tthrow new Error(\"Cannot record an applied pi-server compaction without its matching pending operation\");\n\t\t}\n\t\tassertIdentifier(input.entryId, \"pi-server compact applied entryId\");\n\t\tassertHash(input.entryHash, \"pi-server compact applied entryHash\");\n\t\tassertHash(input.updatedTreeHash, \"pi-server compact applied updatedTreeHash\");\n\t\tassertIdentifier(input.updatedLeafId, \"pi-server compact applied updatedLeafId\");\n\t\tassertNonNegativeSafeInteger(input.updatedRevision, \"pi-server compact applied updatedRevision\");\n\t\tif (pending.observation) {\n\t\t\tif (\n\t\t\t\tpending.observation.kind !== \"applied\" ||\n\t\t\t\tpending.observation.entryId !== input.entryId ||\n\t\t\t\tpending.observation.entryHash !== input.entryHash ||\n\t\t\t\tpending.observation.updatedTreeHash !== input.updatedTreeHash ||\n\t\t\t\tpending.observation.updatedLeafId !== input.updatedLeafId ||\n\t\t\t\tpending.observation.updatedRevision !== input.updatedRevision\n\t\t\t) {\n\t\t\t\tthrow new Error(\"Pi-server compaction already has a divergent durable observation\");\n\t\t\t}\n\t\t\treturn pending.observation;\n\t\t}\n\t\tconst timestamp = input.timestamp ?? Date.now();\n\t\tassertNonNegativeSafeInteger(timestamp, \"pi-server compact applied timestamp\");\n\t\tconst record: PiServerAppliedCompactState = {\n\t\t\tversion: COMPACT_STATE_VERSION,\n\t\t\tkind: \"applied\",\n\t\t\tsequence: state.nextSequence,\n\t\t\ttimestamp,\n\t\t\toperationId: input.operationId,\n\t\t\trequestHash: input.requestHash,\n\t\t\tentryId: input.entryId,\n\t\t\tentryHash: input.entryHash,\n\t\t\tupdatedTreeHash: input.updatedTreeHash,\n\t\t\tupdatedLeafId: input.updatedLeafId,\n\t\t\tupdatedRevision: input.updatedRevision,\n\t\t\tresolution: \"tree_applied\",\n\t\t};\n\t\tappendRecord(path, record);\n\t\treturn record;\n\t});\n}\n\nexport function writePiServerTerminalCompact(\n\tpath: string,\n\tinput: WritePiServerTerminalCompactInput,\n): PiServerTerminalCompactState {\n\treturn withCompactStateLock(path, () => {\n\t\tconst state = parseCompactStateFile(path);\n\t\tconst pending = state.pending;\n\t\tif (!pending || pending.operationId !== input.operationId || pending.requestHash !== input.requestHash) {\n\t\t\tthrow new Error(\"Cannot record a terminal pi-server compaction without its matching pending operation\");\n\t\t}\n\t\tif (!Number.isSafeInteger(input.httpStatus) || input.httpStatus < 100 || input.httpStatus > 599) {\n\t\t\tthrow new Error(\"pi-server compact terminal HTTP status is invalid\");\n\t\t}\n\t\tassertError(input.error, \"pi-server compact terminal error\");\n\t\tif (\n\t\t\t(input.operationDisposition === \"terminal\" && input.status !== \"failed\") ||\n\t\t\t(input.operationDisposition === \"not_started\" && input.status !== \"rejected\")\n\t\t) {\n\t\t\tthrow new Error(\"pi-server compact terminal disposition is invalid\");\n\t\t}\n\t\tif (pending.observation) {\n\t\t\tif (\n\t\t\t\tpending.observation.kind !== \"terminal\" ||\n\t\t\t\tpending.observation.httpStatus !== input.httpStatus ||\n\t\t\t\tpending.observation.error !== input.error ||\n\t\t\t\tpending.observation.operationDisposition !== input.operationDisposition ||\n\t\t\t\tpending.observation.status !== input.status\n\t\t\t) {\n\t\t\t\tthrow new Error(\"Pi-server compaction already has a divergent durable observation\");\n\t\t\t}\n\t\t\treturn pending.observation;\n\t\t}\n\t\tconst timestamp = input.timestamp ?? Date.now();\n\t\tassertNonNegativeSafeInteger(timestamp, \"pi-server compact terminal timestamp\");\n\t\tconst record: PiServerTerminalCompactState = {\n\t\t\tversion: COMPACT_STATE_VERSION,\n\t\t\tkind: \"terminal\",\n\t\t\tsequence: state.nextSequence,\n\t\t\ttimestamp,\n\t\t\toperationId: input.operationId,\n\t\t\trequestHash: input.requestHash,\n\t\t\thttpStatus: input.httpStatus,\n\t\t\terror: input.error,\n\t\t\toperationDisposition: input.operationDisposition,\n\t\t\tstatus: input.status,\n\t\t\tresolution: input.operationDisposition === \"terminal\" ? \"terminal_failed_observed\" : \"server_rejected\",\n\t\t};\n\t\tappendRecord(path, record);\n\t\treturn record;\n\t});\n}\n\nexport function acknowledgePiServerPendingCompact(\n\tpath: string,\n\toperationId: string,\n\tresolution: PiServerCompactAcknowledgementResolution = \"server_ack\",\n\ttimestamp = Date.now(),\n): void {\n\twithCompactStateLock(path, () => {\n\t\tconst state = parseCompactStateFile(path);\n\t\tif (!state.pending) return;\n\t\tif (state.pending.operationId !== operationId) {\n\t\t\tthrow new Error(\n\t\t\t\t`Cannot acknowledge pi-server compaction ${operationId}; pending operation is ${state.pending.operationId}`,\n\t\t\t);\n\t\t}\n\t\tassertNonNegativeSafeInteger(timestamp, \"pi-server compact acknowledgement timestamp\");\n\t\tappendRecord(path, {\n\t\t\tversion: COMPACT_STATE_VERSION,\n\t\t\tkind: \"ack\",\n\t\t\tsequence: state.nextSequence,\n\t\t\ttimestamp,\n\t\t\toperationId,\n\t\t\tresolution,\n\t\t});\n\t});\n}\n"]}

package/dist/core/pi-server-compact-state.js

@@ -0,0 +1,438 @@
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, openSync, readFileSync, truncateSync, writeSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+const COMPACT_STATE_VERSION = 1;
+const COMPACT_STATE_MAX_BYTES = 8 * 1024 * 1024;
+const SHA256_PATTERN = /^[a-f0-9]{64}$/u;
+const IDENTIFIER_MAX_CHARS = 4096;
+const ERROR_MAX_CHARS = 1024 * 1024;
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function assertObject(value, path) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${path} must be an object`);
+    }
+}
+function assertIdentifier(value, path) {
+    if (typeof value !== "string" || value.length === 0 || value.length > IDENTIFIER_MAX_CHARS || value.includes("\0")) {
+        throw new Error(`${path} must be a non-empty string without NUL bytes`);
+    }
+}
+function assertHash(value, path, allowEmpty = false) {
+    if (typeof value !== "string" ||
+        (!allowEmpty && !SHA256_PATTERN.test(value)) ||
+        (allowEmpty && value !== "" && !SHA256_PATTERN.test(value))) {
+        throw new Error(`${path} must be ${allowEmpty ? "empty or " : ""}a lowercase SHA-256 digest`);
+    }
+}
+function assertError(value, path) {
+    if (typeof value !== "string" || value.length === 0 || value.length > ERROR_MAX_CHARS || value.includes("\0")) {
+        throw new Error(`${path} must be a non-empty string without NUL bytes`);
+    }
+}
+function assertNonNegativeSafeInteger(value, path) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`${path} must be a non-negative safe integer`);
+    }
+}
+function parsePayload(payload, lineNumber) {
+    let value;
+    try {
+        value = JSON.parse(payload);
+    }
+    catch (error) {
+        throw new Error(`pi-server compact state payload is invalid JSON at line ${lineNumber}`, { cause: error });
+    }
+    assertObject(value, `pi-server compact state line ${lineNumber}`);
+    if (value.version !== COMPACT_STATE_VERSION) {
+        throw new Error(`Unsupported pi-server compact state version at line ${lineNumber}`);
+    }
+    assertNonNegativeSafeInteger(value.sequence, `pi-server compact state line ${lineNumber}.sequence`);
+    assertNonNegativeSafeInteger(value.timestamp, `pi-server compact state line ${lineNumber}.timestamp`);
+    if (value.kind === "ack") {
+        assertIdentifier(value.operationId, `pi-server compact state line ${lineNumber}.operationId`);
+        if (value.resolution !== "server_ack" &&
+            value.resolution !== "server_missing_after_tree_applied" &&
+            value.resolution !== "server_missing_after_terminal_failure" &&
+            value.resolution !== "server_rejected_not_started") {
+            throw new Error(`pi-server compact state acknowledgement resolution is invalid at line ${lineNumber}`);
+        }
+        return {
+            version: COMPACT_STATE_VERSION,
+            kind: "ack",
+            sequence: value.sequence,
+            timestamp: value.timestamp,
+            operationId: value.operationId,
+            resolution: value.resolution,
+        };
+    }
+    if (value.kind === "applied") {
+        assertIdentifier(value.operationId, `pi-server compact state line ${lineNumber}.operationId`);
+        assertHash(value.requestHash, `pi-server compact state line ${lineNumber}.requestHash`);
+        assertIdentifier(value.entryId, `pi-server compact state line ${lineNumber}.entryId`);
+        assertHash(value.entryHash, `pi-server compact state line ${lineNumber}.entryHash`);
+        assertHash(value.updatedTreeHash, `pi-server compact state line ${lineNumber}.updatedTreeHash`);
+        assertIdentifier(value.updatedLeafId, `pi-server compact state line ${lineNumber}.updatedLeafId`);
+        assertNonNegativeSafeInteger(value.updatedRevision, `pi-server compact state line ${lineNumber}.updatedRevision`);
+        if (value.resolution !== "tree_applied") {
+            throw new Error(`pi-server compact applied resolution is invalid at line ${lineNumber}`);
+        }
+        return {
+            version: COMPACT_STATE_VERSION,
+            kind: "applied",
+            sequence: value.sequence,
+            timestamp: value.timestamp,
+            operationId: value.operationId,
+            requestHash: value.requestHash,
+            entryId: value.entryId,
+            entryHash: value.entryHash,
+            updatedTreeHash: value.updatedTreeHash,
+            updatedLeafId: value.updatedLeafId,
+            updatedRevision: value.updatedRevision,
+            resolution: value.resolution,
+        };
+    }
+    if (value.kind === "terminal") {
+        assertIdentifier(value.operationId, `pi-server compact state line ${lineNumber}.operationId`);
+        assertHash(value.requestHash, `pi-server compact state line ${lineNumber}.requestHash`);
+        if (!Number.isSafeInteger(value.httpStatus) ||
+            value.httpStatus < 100 ||
+            value.httpStatus > 599) {
+            throw new Error(`pi-server compact terminal HTTP status is invalid at line ${lineNumber}`);
+        }
+        assertError(value.error, `pi-server compact state line ${lineNumber}.error`);
+        if ((value.operationDisposition !== "terminal" && value.operationDisposition !== "not_started") ||
+            (value.status !== "failed" && value.status !== "rejected") ||
+            (value.operationDisposition === "terminal" && value.status !== "failed") ||
+            (value.operationDisposition === "not_started" && value.status !== "rejected")) {
+            throw new Error(`pi-server compact terminal disposition is invalid at line ${lineNumber}`);
+        }
+        const expectedResolution = value.operationDisposition === "terminal" ? "terminal_failed_observed" : "server_rejected";
+        if (value.resolution !== expectedResolution) {
+            throw new Error(`pi-server compact terminal resolution is invalid at line ${lineNumber}`);
+        }
+        return {
+            version: COMPACT_STATE_VERSION,
+            kind: "terminal",
+            sequence: value.sequence,
+            timestamp: value.timestamp,
+            operationId: value.operationId,
+            requestHash: value.requestHash,
+            httpStatus: value.httpStatus,
+            error: value.error,
+            operationDisposition: value.operationDisposition,
+            status: value.status,
+            resolution: expectedResolution,
+        };
+    }
+    if (value.kind !== "compact") {
+        throw new Error(`Unsupported pi-server compact state record kind at line ${lineNumber}`);
+    }
+    assertHash(value.serverHash, `pi-server compact state line ${lineNumber}.serverHash`);
+    assertIdentifier(value.sessionId, `pi-server compact state line ${lineNumber}.sessionId`);
+    assertIdentifier(value.operationId, `pi-server compact state line ${lineNumber}.operationId`);
+    assertHash(value.requestHash, `pi-server compact state line ${lineNumber}.requestHash`);
+    assertHash(value.baseStaticContextHash, `pi-server compact state line ${lineNumber}.baseStaticContextHash`, true);
+    assertHash(value.baseTreeHash, `pi-server compact state line ${lineNumber}.baseTreeHash`);
+    assertNonNegativeSafeInteger(value.baseEntryCount, `pi-server compact state line ${lineNumber}.baseEntryCount`);
+    if (value.baseLeafId !== null) {
+        assertIdentifier(value.baseLeafId, `pi-server compact state line ${lineNumber}.baseLeafId`);
+    }
+    assertNonNegativeSafeInteger(value.baseRevision, `pi-server compact state line ${lineNumber}.baseRevision`);
+    return {
+        version: COMPACT_STATE_VERSION,
+        kind: "compact",
+        sequence: value.sequence,
+        timestamp: value.timestamp,
+        serverHash: value.serverHash,
+        sessionId: value.sessionId,
+        operationId: value.operationId,
+        requestHash: value.requestHash,
+        baseStaticContextHash: value.baseStaticContextHash,
+        baseTreeHash: value.baseTreeHash,
+        baseEntryCount: value.baseEntryCount,
+        baseLeafId: value.baseLeafId,
+        baseRevision: value.baseRevision,
+    };
+}
+function parseCompactStateFile(path) {
+    if (!existsSync(path))
+        return { nextSequence: 0, pending: undefined };
+    const encoded = readFileSync(path);
+    if (encoded.byteLength > COMPACT_STATE_MAX_BYTES) {
+        throw new Error(`pi-server compact state exceeds ${COMPACT_STATE_MAX_BYTES} bytes: ${path}`);
+    }
+    const content = encoded.toString("utf-8");
+    const lines = content.split("\n");
+    if (!content.endsWith("\n"))
+        lines.pop();
+    let expectedSequence = 0;
+    let pending;
+    for (const [index, line] of lines.entries()) {
+        if (!line)
+            continue;
+        let envelope;
+        try {
+            envelope = JSON.parse(line);
+        }
+        catch (error) {
+            throw new Error(`pi-server compact state envelope is invalid JSON at line ${index + 1}`, {
+                cause: error,
+            });
+        }
+        assertObject(envelope, `pi-server compact state envelope line ${index + 1}`);
+        if (typeof envelope.payload !== "string") {
+            throw new Error(`pi-server compact state envelope payload must be a string at line ${index + 1}`);
+        }
+        assertHash(envelope.sha256, `pi-server compact state envelope line ${index + 1}.sha256`);
+        if (sha256(envelope.payload) !== envelope.sha256) {
+            throw new Error(`pi-server compact state checksum mismatch at line ${index + 1}`);
+        }
+        const record = parsePayload(envelope.payload, index + 1);
+        if (record.sequence !== expectedSequence) {
+            throw new Error(`pi-server compact state sequence mismatch at line ${index + 1}: expected ${expectedSequence}, received ${record.sequence}`);
+        }
+        expectedSequence++;
+        if (record.kind === "compact") {
+            if (pending) {
+                throw new Error(`pi-server compact state contains a new operation before ${pending.operationId} was acknowledged`);
+            }
+            pending = record;
+        }
+        else if (record.kind === "applied" || record.kind === "terminal") {
+            if (!pending ||
+                pending.operationId !== record.operationId ||
+                pending.requestHash !== record.requestHash ||
+                pending.observation) {
+                throw new Error(`pi-server compact state observation does not match the pending operation at line ${index + 1}`);
+            }
+            pending = { ...pending, observation: record };
+        }
+        else {
+            if (!pending || pending.operationId !== record.operationId) {
+                throw new Error(`pi-server compact state acknowledgement does not match the pending operation at line ${index + 1}`);
+            }
+            pending = undefined;
+        }
+    }
+    return { nextSequence: expectedSequence, pending };
+}
+function appendRecord(path, record) {
+    const payload = JSON.stringify(record);
+    const encoded = Buffer.from(`${JSON.stringify({ payload, sha256: sha256(payload) })}\n`, "utf-8");
+    const existing = existsSync(path) ? readFileSync(path) : Buffer.alloc(0);
+    const validBytes = existing.lastIndexOf(0x0a) + 1;
+    if (validBytes !== existing.byteLength)
+        truncateSync(path, validBytes);
+    if (validBytes + encoded.byteLength > COMPACT_STATE_MAX_BYTES) {
+        throw new Error(`pi-server compact state would exceed ${COMPACT_STATE_MAX_BYTES} bytes: ${path}`);
+    }
+    const fileExisted = existsSync(path);
+    const handle = openSync(path, "a", 0o600);
+    try {
+        let written = 0;
+        while (written < encoded.byteLength) {
+            const bytesWritten = writeSync(handle, encoded, written, encoded.byteLength - written);
+            if (bytesWritten === 0)
+                throw new Error(`Failed to make progress writing pi-server compact state: ${path}`);
+            written += bytesWritten;
+        }
+        fsyncSync(handle);
+    }
+    finally {
+        closeSync(handle);
+    }
+    if (!fileExisted && process.platform !== "win32") {
+        const directoryHandle = openSync(dirname(path), "r");
+        try {
+            fsyncSync(directoryHandle);
+        }
+        finally {
+            closeSync(directoryHandle);
+        }
+    }
+}
+function withCompactStateLock(path, operation) {
+    const normalizedPath = resolve(path);
+    const database = new DatabaseSync(`${normalizedPath}.lock.sqlite`);
+    let transactionStarted = false;
+    try {
+        database.exec("PRAGMA busy_timeout = 0");
+        database.exec("CREATE TABLE IF NOT EXISTS compact_state_lock (id INTEGER PRIMARY KEY CHECK (id = 1))");
+        database.exec("BEGIN IMMEDIATE");
+        transactionStarted = true;
+        return operation();
+    }
+    catch (error) {
+        const details = error instanceof Error ? error.message : String(error);
+        throw new Error(`Cannot update pi-server compact state ${normalizedPath}: ${details}`, { cause: error });
+    }
+    finally {
+        if (transactionStarted) {
+            try {
+                database.exec("ROLLBACK");
+            }
+            catch {
+                // Closing the connection is the authoritative lock release.
+            }
+        }
+        database.close();
+    }
+}
+export function getPiServerCompactStatePath(sessionFile) {
+    return `${sessionFile}.pi-server-compacts.jsonl`;
+}
+export function readPiServerPendingCompact(path) {
+    return parseCompactStateFile(path).pending;
+}
+export function writePiServerPendingCompact(path, input) {
+    return withCompactStateLock(path, () => {
+        const state = parseCompactStateFile(path);
+        if (state.pending) {
+            throw new Error(`pi-server compaction ${state.pending.operationId} must be acknowledged before starting another compaction`);
+        }
+        if (state.nextSequence > 0) {
+            truncateSync(path, 0);
+            state.nextSequence = 0;
+        }
+        const timestamp = input.timestamp ?? Date.now();
+        assertNonNegativeSafeInteger(timestamp, "pi-server compact state timestamp");
+        assertHash(input.serverHash, "pi-server compact state serverHash");
+        assertIdentifier(input.sessionId, "pi-server compact state sessionId");
+        assertIdentifier(input.operationId, "pi-server compact state operationId");
+        assertHash(input.requestHash, "pi-server compact state requestHash");
+        assertHash(input.baseStaticContextHash, "pi-server compact state baseStaticContextHash", true);
+        assertHash(input.baseTreeHash, "pi-server compact state baseTreeHash");
+        assertNonNegativeSafeInteger(input.baseEntryCount, "pi-server compact state baseEntryCount");
+        if (input.baseLeafId !== null)
+            assertIdentifier(input.baseLeafId, "pi-server compact state baseLeafId");
+        assertNonNegativeSafeInteger(input.baseRevision, "pi-server compact state baseRevision");
+        const record = {
+            version: COMPACT_STATE_VERSION,
+            kind: "compact",
+            sequence: state.nextSequence,
+            timestamp,
+            serverHash: input.serverHash,
+            sessionId: input.sessionId,
+            operationId: input.operationId,
+            requestHash: input.requestHash,
+            baseStaticContextHash: input.baseStaticContextHash,
+            baseTreeHash: input.baseTreeHash,
+            baseEntryCount: input.baseEntryCount,
+            baseLeafId: input.baseLeafId,
+            baseRevision: input.baseRevision,
+        };
+        appendRecord(path, record);
+        return record;
+    });
+}
+export function writePiServerAppliedCompact(path, input) {
+    return withCompactStateLock(path, () => {
+        const state = parseCompactStateFile(path);
+        const pending = state.pending;
+        if (!pending || pending.operationId !== input.operationId || pending.requestHash !== input.requestHash) {
+            throw new Error("Cannot record an applied pi-server compaction without its matching pending operation");
+        }
+        assertIdentifier(input.entryId, "pi-server compact applied entryId");
+        assertHash(input.entryHash, "pi-server compact applied entryHash");
+        assertHash(input.updatedTreeHash, "pi-server compact applied updatedTreeHash");
+        assertIdentifier(input.updatedLeafId, "pi-server compact applied updatedLeafId");
+        assertNonNegativeSafeInteger(input.updatedRevision, "pi-server compact applied updatedRevision");
+        if (pending.observation) {
+            if (pending.observation.kind !== "applied" ||
+                pending.observation.entryId !== input.entryId ||
+                pending.observation.entryHash !== input.entryHash ||
+                pending.observation.updatedTreeHash !== input.updatedTreeHash ||
+                pending.observation.updatedLeafId !== input.updatedLeafId ||
+                pending.observation.updatedRevision !== input.updatedRevision) {
+                throw new Error("Pi-server compaction already has a divergent durable observation");
+            }
+            return pending.observation;
+        }
+        const timestamp = input.timestamp ?? Date.now();
+        assertNonNegativeSafeInteger(timestamp, "pi-server compact applied timestamp");
+        const record = {
+            version: COMPACT_STATE_VERSION,
+            kind: "applied",
+            sequence: state.nextSequence,
+            timestamp,
+            operationId: input.operationId,
+            requestHash: input.requestHash,
+            entryId: input.entryId,
+            entryHash: input.entryHash,
+            updatedTreeHash: input.updatedTreeHash,
+            updatedLeafId: input.updatedLeafId,
+            updatedRevision: input.updatedRevision,
+            resolution: "tree_applied",
+        };
+        appendRecord(path, record);
+        return record;
+    });
+}
+export function writePiServerTerminalCompact(path, input) {
+    return withCompactStateLock(path, () => {
+        const state = parseCompactStateFile(path);
+        const pending = state.pending;
+        if (!pending || pending.operationId !== input.operationId || pending.requestHash !== input.requestHash) {
+            throw new Error("Cannot record a terminal pi-server compaction without its matching pending operation");
+        }
+        if (!Number.isSafeInteger(input.httpStatus) || input.httpStatus < 100 || input.httpStatus > 599) {
+            throw new Error("pi-server compact terminal HTTP status is invalid");
+        }
+        assertError(input.error, "pi-server compact terminal error");
+        if ((input.operationDisposition === "terminal" && input.status !== "failed") ||
+            (input.operationDisposition === "not_started" && input.status !== "rejected")) {
+            throw new Error("pi-server compact terminal disposition is invalid");
+        }
+        if (pending.observation) {
+            if (pending.observation.kind !== "terminal" ||
+                pending.observation.httpStatus !== input.httpStatus ||
+                pending.observation.error !== input.error ||
+                pending.observation.operationDisposition !== input.operationDisposition ||
+                pending.observation.status !== input.status) {
+                throw new Error("Pi-server compaction already has a divergent durable observation");
+            }
+            return pending.observation;
+        }
+        const timestamp = input.timestamp ?? Date.now();
+        assertNonNegativeSafeInteger(timestamp, "pi-server compact terminal timestamp");
+        const record = {
+            version: COMPACT_STATE_VERSION,
+            kind: "terminal",
+            sequence: state.nextSequence,
+            timestamp,
+            operationId: input.operationId,
+            requestHash: input.requestHash,
+            httpStatus: input.httpStatus,
+            error: input.error,
+            operationDisposition: input.operationDisposition,
+            status: input.status,
+            resolution: input.operationDisposition === "terminal" ? "terminal_failed_observed" : "server_rejected",
+        };
+        appendRecord(path, record);
+        return record;
+    });
+}
+export function acknowledgePiServerPendingCompact(path, operationId, resolution = "server_ack", timestamp = Date.now()) {
+    withCompactStateLock(path, () => {
+        const state = parseCompactStateFile(path);
+        if (!state.pending)
+            return;
+        if (state.pending.operationId !== operationId) {
+            throw new Error(`Cannot acknowledge pi-server compaction ${operationId}; pending operation is ${state.pending.operationId}`);
+        }
+        assertNonNegativeSafeInteger(timestamp, "pi-server compact acknowledgement timestamp");
+        appendRecord(path, {
+            version: COMPACT_STATE_VERSION,
+            kind: "ack",
+            sequence: state.nextSequence,
+            timestamp,
+            operationId,
+            resolution,
+        });
+    });
+}
+//# sourceMappingURL=pi-server-compact-state.js.map