Repository navigation
Releases: RaycarlLei/tool-journal
Release list
v0.3.1 — conservative schema recovery and verified CI packages
This patch prevents a previously used SQLite database with both journal tables missing from silently becoming a fresh journal. Initialization now requires an empty schema and a zero schema-version counter, checked inside the opening transaction. Databases retaining schema history or unrelated objects are rejected. Valid v1/v2 journals, newly created paths and empty files remain supported.
The check is conservative recovery behavior, not authentication. It cannot detect a replacement empty file, an externally reset counter, or actions missing from an old backup. Keep executors stopped while reconciling damaged or restored storage. The public API and storage schema version are unchanged.
The package is now promoted directly from the final main CI candidate that passed offline installation, SQLite reopen and public TypeScript consumption. Package checks also reject stale compiled modules. build-provenance.json is the original CI build record; provenance.json binds it to the final source, CI jobs and experiment artifacts. SHA256SUMS covers the package and all JSON assets. The release guide documents reproduction and promotion.
Validation: 147 core tests, nine targeted mutation checks and seven LangGraph tests passed in each of six OS/Node combinations; the final package job and CodeQL also passed. The six new SQLite regressions reproduce two failures on the previous implementation. Full main CI and CodeQL correspond to source 3ec3391ec06563bc3d1e9a16631fec80dd802d0d.
The attached six crash matrices and six runtime reports remain synthetic, same-host experiments with their recorded workloads and failures. In this run, the Windows Node 24.15 four-process execution batch recorded two SQLITE_BUSY failures; the other measured batches recorded none. Those samples are retained. These results do not establish production capacity, multi-host availability, a performance SLA, or cross-service exactly-once execution. Checksums and build records are not cryptographic attestations or an independent security audit.
Download raycarllei-tool-journal-0.3.1.tgz and install it with npm install ./raycarllei-tool-journal-0.3.1.tgz. Node.js 24.15 or later is required. This release is distributed through GitHub; it is not an npm-registry publication.
v0.3.0 — Bounded reads and observable runtime costs
Completed receipt replay now reads one validated committed snapshot without requesting SQLite's writer reservation. New execution claims still reread under BEGIN IMMEDIATE; an absent or pending snapshot never authorizes a tool call. Custom stores without read retain the transaction path.
Persisted-record and migration queries bound values before they cross from SQLite into JavaScript, including record IDs and schema metadata. UTF-16 databases remain supported, and the existing exact UTF-8 decoder limit still applies. This does not impose a global SQLite or process memory limit. Storage schema remains v2; v0.2 records require no migration.
Run npm run benchmark:runtime for raw operation latencies, one/four-process workloads, held-writer controls, event-loop probes and database-file growth. Each report identifies its source, build, lockfile and environment. New operating guidance covers synchronous work, lock errors, backup age and recovery boundaries.
Release attachments include the package archive, crash-control and runtime-cost reports from the final source's six CI environments, build provenance and SHA-256 checksums. Runtime observations carry no timing pass threshold or availability SLA. The API remains synchronous; a completed-read fast path does not make writes or reads asynchronous.
The raw reports retain contention failures: each Windows environment recorded one SQLITE_BUSY in its four-process execution batch. The Linux and macOS batches and the other Windows batches recorded none. These errors remain in the reported samples and elapsed batch time; successful-operation rates exclude failed attempts from their numerator. The six-second held-writer control is reported separately. No rerun was selected to remove the two errors.
This is an independent reference implementation. Automatic recovery still requires the downstream idempotency contract and a finite retry-admission window; there is no cross-service exactly-once guarantee. The package is distributed here as an archive, with no npm registry publication implied.
v0.2.0: Bounded retry admission
Idempotent operations now require an explicit retryForMs. The first journal acquisition fixes the cutoff; retries, reopening and lease renewal cannot restart it. Changing a known window conflicts, including for completed actions. At the cutoff, an expired pending lease becomes indeterminate instead of authorizing another attempt. An active owner can still renew or record a receipt, and matching completed receipts continue to replay locally.
This is a breaking API and storage change. SQLite v1 records migrate atomically to schema v2 without inventing historical timestamps. Completed legacy receipts replay; legacy operations with an expired lease cannot obtain a fresh retry window. Corrupt records and partial schemas stop execution. Already-open v0.1 clients cannot write v1 records after migration, and newly opened v0.1 clients reject the new schema.
Before upgrading, stop every old executor and background retry, reconcile outstanding work where possible, and take a consistent SQLite backup. Add a fixed window to each idempotent intent while preserving its operation identity. The storage migration is forward only; mixed versions and database downgrades are unsupported. Custom stores must preserve the v2 fields and supply their own atomic migration. See the upgrade procedure and admission contract.
A finite retry admission window does not guarantee arrival at the provider before its key expires. A request admitted before the cutoff can pause and arrive after retention ends; an old executor can also continue running. The regression suite includes a counterexample that produces a second downstream effect. The journal cannot extend provider retention, cancel a remote request, fence an external service, or establish cross-service exactly-once execution.
Validation includes 116 core tests, eight targeted mutation checks, an independently installed TypeScript package consumer, and seven LangGraph integration tests. Linux, Windows and macOS run on Node 24.15.0 and 26, including the official SQLite checkpointer and process-kill examples. A separate local compatibility check uses the actual v0.1.2 release archive to verify migration, legacy receipt replay, and old-client rejection. Passing checks are not an independent security audit or production SLA.
Release assets contain the installable package archive, all six raw CI crash matrices, provenance, and SHA-256 checksums. Each matrix contains 100 runs: five strategies × four boundaries × five repetitions. These are controlled recovery experiments, not throughput measurements or 100 distinct failure types. Provider idempotency prevents duplicate effects in both idempotent controls; the journal adds durable local replay, coordination and explicit uncertainty. Framework dependencies remain isolated from the core library, which has zero runtime dependencies.
This release is distributed through source and archive assets. It is not published to the npm registry.
Source: c1cb8a8bcded56a0a084d597013b6c944ab84905.
v0.1.2 — LangGraph recovery across checkpoint boundaries
This release adds a runnable LangGraph integration using the official SQLite checkpointer and the installed tool-journal package. It reproduces two recovery boundaries: an HTTP service commits but loses its response, and the journal saves a receipt before LangGraph records the node's result.
The graph uses a stable operation identity across threads. Idempotent recovery retrieves the original downstream receipt; a journal-confirmed operation replays without another HTTP call; an expired manual operation stays indeterminate. The tests kill actual child processes and reopen the official graph checkpoints. No model, API key, or external service is needed.
Source: d46d4fa0c971d5eb9cf8d221e9029efbd36c5632.
- LangGraph example and guarantees
- Process-kill integration tests
- Release-source CI
- Release-source CodeQL
- Reviewed change
Validation covers 93 core tests, seven targeted mutation checks, real package installation with a TypeScript consumer, and seven LangGraph integration tests. The six Linux/Windows/macOS × Node 24.15.0/26 jobs also install the native SQLite checkpointer and run the demo. Framework dependencies remain isolated from the core library's zero-runtime-dependency package. Dependabot now monitors the example independently.
The public-tree guard uses Git's candidate-file list and checks tracked ignored files without traversing installed dependencies. Node ambient types are declared explicitly. GitHub Actions updates are pinned by commit.
Release assets include the installable npm archive, the raw local protocol-2 experiment with source and runtime metadata, a provenance record, and SHA-256 checksums. The experiment has 100 runs: five strategies × four boundaries × five repetitions. It is a controlled correctness experiment, not a throughput benchmark or 100 distinct failure types. This remains source/archive distribution; the package has not been published to the npm registry.
The downstream idempotency contract prevents duplicate effects in both idempotent controls. The journal adds local receipt replay, operation coordination and explicit uncertainty. It cannot extend the provider's key-retention period, fence an external service, or establish cross-service exactly-once execution. SQLite remains synchronous and local to one host; neither this release nor its passing checks establishes multi-host availability, a production SLA, or an independent security audit.
v0.1.1 — Strict recovery state and HTTP fault reproduction
This release rejects malformed persisted recovery policies before they can authorize an unsafe retry, validates replayed receipts, bounds JSON during encoding, and makes memory and SQLite transaction failures consistent.
Recovery validation now covers renewal, settlement, multiple action identities, reopening, old executors and real HTTP receipt loss. A synthetic HTTP service commits to its own SQLite file and drops the TCP connection before returning a receipt; tests verify both safe idempotent recovery and manual uncertainty.
Validation: 91 tests, seven targeted mutations, public-tree checks, and offline archive installation with a TypeScript consumer and SQLite reopen. The package has no runtime dependencies. The supported CI matrix is Linux, Windows and macOS on Node 24.15.0 and 26. See the repository Actions checks for the exact release source.
Protocol 2 measures 100 cases: five strategies × four controlled boundaries × five repetitions. These are 20 distinct strategy/boundary pairs, not 100 independent failure types.
| Strategy | Cases | Service calls | Effects | Cases with duplicates | Indeterminate | Confirmed |
|---|---|---|---|---|---|---|
| Naive retry | 20 | 35 | 35 | 15 | 0 | 20 |
| Completion checkpoint | 20 | 30 | 30 | 10 | 0 | 20 |
| Downstream idempotency only | 20 | 35 | 20 | 0 | 0 | 20 |
| Journal + downstream idempotency | 20 | 30 | 20 | 0 | 0 | 20 |
| Journal + manual recovery | 20 | 15 | 15 | 0 | 15 | 5 |
Both idempotent strategies use the same downstream key. The downstream prevents duplicate effects; the journal adds live-executor coordination, changed-intent detection and local receipt replay. A baseline can return a confirmed receipt after duplicating an effect. Manual uncertainty is not counted as confirmed success.
Assets include the installable npm archive, raw local experiment results with source/runtime metadata, and SHA-256 checksums. This is a GitHub release archive, not an npm registry publication.
Valid 0.1.0 records retain their canonical representation. Malformed records now fail closed. SQLite remains synchronous, on local disk and within one host. Neither this experiment nor a passing CI suite establishes a production SLA, cross-service exactly-once execution, or an independent security audit. See README, SECURITY.md and docs/contract.md for the supported boundary.
v0.1.0 — explicit recovery for retryable tools
First reference release of tool-journal: a TypeScript/SQLite execution journal for retryable tools.
Implemented intent binding, lease takeover, fenced completion, renewal and explicit settlement of uncertain actions. Includes a memory adapter, real child-process crash tests, eight-process contention, 1,000 seeded model histories and four targeted mutation checks.
Validation: the source commit passed GitHub Actions on Ubuntu and Windows with Node.js 24.15.0. The attached compiled package was separately installed and exercised with the SQLite adapter. The attached 60-case crash matrix records its environment, source commit and raw outcomes.
The experiment uses original synthetic data and an injected logical clock. Automatic recovery depends on downstream idempotency; manual mode can stop with an indeterminate outcome. No cross-service exactly-once guarantee or production SLA is claimed. Node's SQLite API is experimental in Node 24.
Independent implementation informed by work on TraderBear; no production code, private history, customer data or strategy configuration is included. MIT licensed. No npm registry publication is implied.