Use one local SQLite file to record commands, state, results and events atomically. The private software-factory package offers the ESM entry point software-factory/command-journal; it starts no Factory process. This first E28 increment passed independent Astra review and was merged on 1 October 2026 after an Opus 5.5 review and accepted locally the same day by the owner-designated acceptance reviewer after a Fable 5.1 review. It does not close the adoption programme.
Install the private artefact
Obtain a reviewed private software-factory-0.1.0.tgz from the producer. Its package-specific README and included guides need no Factory checkout. From your separate application, install that file:
npm install --offline --ignore-scripts --engine-strict /path/to/software-factory-0.1.0.tgz
Keep the application's package version and artefact integrity pinned in its lockfile. Import only the named entry point. The package root, src/ and internal dist/ paths are not exported; compiled helpers are implementation details. There is no CommonJS entry point.
Record a command
Save this as counter.mjs in the consuming application. Its working directory owns counter.sqlite and SQLite's adjacent coordination files.
import { CommandJournal } from 'software-factory/command-journal';
const journal = CommandJournal.open('./counter.sqlite');
try {
const result = journal.execute(
'add:one', { amount: 2 }, 0, 'counter:one',
(state, payload) => {
const count = (state?.count ?? 0) + payload.amount;
return {
state: { count },
result: { count },
events: [{ type: 'counter.added', data: payload }],
};
},
);
console.log(result);
} finally {
journal.close();
}
Run node counter.mjs twice. The second result has replayed: true, the same result and the original version. The decision is not called again. Reusing the command ID with different inputs throws CommandConflictError; a new command with a stale expected version throws VersionConflictError. Neither writes anything. A replay is historical, so read current state before acting on it.
Contract and dependencies
The runtime closure is journal, canonical-json and errors, using only Node's built-in sqlite, fs, perf_hooks, url and buffer modules. No npm runtime dependency, Git, provider, credential, Portfolio, Dashboard or coordinator is required. The host supplies a trusted local file path and filesystem access. SQLite WAL is single-host storage; network filesystems are unsupported.
Node.js ≥26.8.1 is required. The initial consumer proof targets Node.js 26.8.1 on macOS 27 arm64. Other environments have no independent adoption evidence. Consumers need neither a compiler nor TypeScript to run; the shipped declarations also support typed callers.
| API | Contract |
|---|---|
CommandJournal.open(path, options?) | Create an empty journal or open schema 1; current tables/columns are prepared before WAL/FULL configuration; never migrate a foreign schema |
openExisting(path, options?) | Open a current journal for writes; never create a missing file |
openReadOnly(path, options?) | Open an existing journal; refuse all commands, including replays |
execute(commandId, payload, expectedVersion, aggregateId, decide) | Commit state, result, events and outbox rows together; return CommandOutcome |
readAggregate(id) | Frozen { aggregateId, version, state }, or undefined |
readHistory(id, page?) / readPendingOutbox(page?) | Frozen events ordered by global sequence |
close() | Release the handle; repeated close is harmless |
Decide receives frozen state, payload and {commandId, aggregateId, version}. Initial state is null. It returns exactly {state, result, events} with 1–100 events, each exactly {type, data}. It is trusted, synchronous, pure application code; it must not call journal methods or perform external effects. There is no replaceable storage/provider adapter, and this increment introduces none.
JsonValue permits finite JSON values, dense arrays and plain objects. Documents have a 1,048,576-byte limit and at most 64 nested containers. IDs and event types match /^[A-Za-z0-9][A-Za-z0-9._:\/-]{0,127}$/. Versions and page afterSequence are nonnegative safe integers. Page limit is 1–1000, default 100. busyTimeoutMs is 0–60000, default 5000. Limits refuse excess; nothing is truncated. JOURNAL_LIMITS, JSON_LIMITS, SCHEMA_VERSION, canonicalJson, all public interfaces and error classes are exported from the same entry point.
Deliberate failures extend JournalError with codes INVALID_INPUT, COMMAND_CONFLICT, VERSION_CONFLICT, DECISION_FAILED, UNSUPPORTED_SCHEMA, STORAGE, CLOSED, NOT_FOUND or READ_ONLY. Conflicts expose their command or aggregate identifiers and mismatches/versions. Native failures remain possible outside the documented boundary, including explicitly passing null as options. Caller decision failure rolls back the command. If a process dies before the result arrives, the outcome is unknown: retry the same ID and inputs to resolve it. Never infer failure and issue a fresh command.
Compatibility and evidence
Private package version 0.1.0 is separate from persisted SCHEMA_VERSION = 1. Source files and the SQLite schema are unchanged. The external test reads source-created state and source code reads package-created state without migration. Preserve old artefacts and state; a future schema change needs an explicit migration and compatibility proof. Every draft build keeps version 0.1.0, including incompatible changes such as the eight-value guidance /2 contract, so identify a draft by its tarball integrity, never its version. A version bump policy starts with the first reviewed non-draft hand-off. New entry points need their own bounded evidence.
The source distribution checks pack and install into an external temporary application, check declarations, deny import-time filesystem writes/network/process permissions, reject private imports, and exercise replay, conflicts, close/reopen, isolation, invalid input, rollback, missing/foreign/future/corrupt storage and killed-process recovery before and after commit. Temporary storage is removed afterwards. The accepted source tests remain separate; this distribution's own independent Astra review passed, and it was accepted locally on 1 October 2026.
No outbox delivery, migration, retention, storage identity fencing, hostile-file defence or power-loss guarantee is supplied. Cancellation is not a journal operation; callers own it around synchronous commands. Other Modules, worker resources, integrity manifests and complete Workflows remain adoption gaps.
