IF Commons GitHub

logical/journal

Written to: 5 requirements: 5 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-evidence-capture-journal FR-001, 0002-evidence-capture-journal FR-002, 0002-evidence-capture-journal FR-003, 0002-evidence-capture-journal FR-004, 0002-evidence-capture-journal FR-005

The journal and the due assets, pure: where a day's entries are kept (journal/YYYY/MM/DD.jsonl), an entry as a line and the lines read back, the digest of a state, which kind of entry a look makes (every look, or only a change and a heartbeat, as the policy says; a failure always), and which assets are due to be looked at, by their cadences.

import { journalPath } from "./journal.ts";
journalPath("2026-12-01T10:00:00Z"); // "journal/2026/12/01.jsonl"

Source: commons/evidence-capture/src/logical/journal.ts

7 of 20 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

logical.journalPathfunctionno test imports it
function journalPath(at: string): string

The file of a day's entries, by the day of the instant (UTC).

logical.statePathfunctionno test imports it
function statePath(id: string): string

The path of the state of an asset.

logical.encodeEntryfunctionno test imports it
function encodeEntry(e: Document & { readonly seq: number; readonly previous: string; readonly type: string; readonly subject: string; readonly evidence: string; readonly digest: string; } & {}): string

An entry as one line: its canonical form and a line break.

logical.decodeEntriesfunctionno test imports it
function decodeEntries(text: string): Result<readonly (Document & { readonly seq: number; readonly previous: string; readonly type: string; readonly subject: string; readonly evidence: string; readonly digest: string; } & {})[], string>

The entries of a text of lines, or the line that is not one.

logical.textDigestfunctionno test imports it
function textDigest(text: string): Promise<string>

The digest of a text: the SHA-256 of its bytes, in hexadecimal.

logical.Foundtypeno test imports it
type Found = { readonly kind: "state"; readonly digest: string } | { readonly kind: "failure"; readonly failure: CaptureFailure };

What a look found: the state (its digest), or a failure.

logical.Beforetypeno test imports it
type Before = { readonly digest: string | undefined; readonly lastJournaledAt: string | undefined };

What is known of an asset before the look: the digest of its kept state and when it was last journaled.

logical.entryTypeForfunctionno test imports it
function entryTypeFor(found: Found, before: Before, policy: CapturePolicy, now: string): "capture.changed" | "capture.refused" | "capture.unchanged" | "capture.unreachable" | "capture.unreadable" | "push.failed" | "seal" | undefined

The kind of entry a look makes, or nothing where it makes none. A state that differs from the kept one is capture.changed; one that is the same is capture.unchanged where every capture is journaled, and, where only changes and a heartbeat are, only when the asset was last journaled a heartbeat ago or more; a failure is always an entry.

logical.isJournalTypefunctionno test imports it
function isJournalType(text: string): text is "capture.changed" | "capture.refused" | "capture.unchanged" | "capture.unreachable" | "capture.unreadable" | "push.failed" | "seal"

The kinds of entry the journal knows.

logical.dueAssetsfunctionno test imports it
function dueAssets(policy: CapturePolicy, assets: readonly Observed[], lastAttempt: (id: string) => string | undefined, now: string): readonly string[]

The ids of the assets that are due to be looked at: the cadence of each (its own, or that of its state) has run since it was last looked at, within a second; an asset never looked at is due.

journalPathfunction
function journalPath(at: string): string

The file of a day's entries, by the day of the instant (UTC).

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

statePathfunction
function statePath(id: string): string

The path of the state of an asset.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

encodeEntryfunction
function encodeEntry(e: Document & { readonly seq: number; readonly previous: string; readonly type: string; readonly subject: string; readonly evidence: string; readonly digest: string; } & {}): string

An entry as one line: its canonical form and a line break.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

decodeEntriesfunction
function decodeEntries(text: string): Result<readonly (Document & { readonly seq: number; readonly previous: string; readonly type: string; readonly subject: string; readonly evidence: string; readonly digest: string; } & {})[], string>

The entries of a text of lines, or the line that is not one.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

textDigestfunction
function textDigest(text: string): Promise<string>

The digest of a text: the SHA-256 of its bytes, in hexadecimal.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

Foundtypeno test imports it
type Found = { readonly kind: "state"; readonly digest: string } | { readonly kind: "failure"; readonly failure: CaptureFailure };

What a look found: the state (its digest), or a failure.

Beforetypeno test imports it
type Before = { readonly digest: string | undefined; readonly lastJournaledAt: string | undefined };

What is known of an asset before the look: the digest of its kept state and when it was last journaled.

entryTypeForfunction
function entryTypeFor(found: Found, before: Before, policy: CapturePolicy, now: string): "capture.changed" | "capture.refused" | "capture.unchanged" | "capture.unreachable" | "capture.unreadable" | "push.failed" | "seal" | undefined

The kind of entry a look makes, or nothing where it makes none. A state that differs from the kept one is capture.changed; one that is the same is capture.unchanged where every capture is journaled, and, where only changes and a heartbeat are, only when the asset was last journaled a heartbeat ago or more; a failure is always an entry.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

isJournalTypefunctionno test imports it
function isJournalType(text: string): text is "capture.changed" | "capture.refused" | "capture.unchanged" | "capture.unreachable" | "capture.unreadable" | "push.failed" | "seal"

The kinds of entry the journal knows.

dueAssetsfunction
function dueAssets(policy: CapturePolicy, assets: readonly Observed[], lastAttempt: (id: string) => string | undefined, now: string): readonly string[]

The ids of the assets that are due to be looked at: the cadence of each (its own, or that of its state) has run since it was last looked at, within a second; an asset never looked at is due.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.