IF Commons GitHub

Evidence capture journal

0002Active

0002-evidence-capture-journal · owner if · domain commons

Requirements

FR-001checkpassing

The kinds of entry of the journal MUST be capture.changed, capture.unchanged, capture.unreachable, capture.refused, capture.unreadable, push.failed and seal, and an asset the collector observes MUST be managed or adopted.

Enforced (check): .github: cd commons/evidence-capture && bun run verify — suite/journal.test.ts

Proved by: evidence-capture/suite/journal.test.ts

Written in: evidence-capture/src/governance/capture.ts, evidence-capture/src/logical/journal.ts

Tests: passed: suite/journal.test.ts the journal has its seven kinds of entry

FR-002checkpassing

journalPath MUST give journal/YYYY/MM/DD.jsonl by the day of the instant in UTC and refuse an instant that is not one; statePath MUST give state/<asset>.json.

Enforced (check): .github: cd commons/evidence-capture && bun run verify — suite/journal.test.ts

Proved by: evidence-capture/suite/journal.test.ts

Written in: evidence-capture/src/logical/journal.ts

Tests: passed: suite/journal.test.ts a day's file is by the day in UTC, a bad instant is refused, and the state of an asset has

FR-003checkpassing

encodeEntry MUST give the canonical form of an entry and a line break, and decodeEntries MUST give back the entries of a text of lines, skipping blank lines, and MUST name the line that is not JSON or not an entry of the journal.

Enforced (check): .github: cd commons/evidence-capture && bun run verify — suite/journal.test.ts

Proved by: evidence-capture/suite/journal.test.ts

Written in: evidence-capture/src/logical/journal.ts

Tests: passed: suite/journal.test.ts an entry is a line, lines are read back in order, and the line that is not an entry is nam

FR-004checkpassing

entryTypeFor MUST give capture.changed for a state whose digest differs from the one kept (or where none is kept), capture.unchanged for the same state where every capture is journaled, and for the same state where only changes and a heartbeat are, capture.unchanged only when the asset was last journaled a heartbeat ago or more (within a second) and nothing otherwise; and for a failure the kind of entry of its kind, always.

Enforced (check): .github: cd commons/evidence-capture && bun run verify — suite/journal.test.ts

Proved by: evidence-capture/suite/journal.test.ts

Written in: evidence-capture/src/logical/journal.ts

Tests: passed: suite/journal.test.ts a changed state is an entry, the same state is one where every capture is journaled and on

FR-005checkpassing

dueAssets MUST give, in order, the assets whose cadence (their own, or that of their state) has run since they were last looked at (within a second), and those never looked at; a discovered asset has no cadence and is never due, and an instant that is not one gives none.

Enforced (check): .github: cd commons/evidence-capture && bun run verify — suite/journal.test.ts

Proved by: evidence-capture/suite/journal.test.ts

Written in: evidence-capture/src/logical/journal.ts

Tests: passed: suite/journal.test.ts the assets due are those whose cadence has run or never looked at, in order, and a bad ins

Acceptance scenarios

  1. Given the same state looked at twice, When every capture is journaled, Then the second is capture.unchanged, per FR-004.
  2. Given a journal of changes and a half-hour heartbeat, When the same state is looked at after 15 and after 30 minutes, Then the first makes no entry and the second a heartbeat, per FR-004.
  3. Given a managed asset looked at 15 minutes ago and an adopted one looked at 15 minutes ago, When the due assets are asked, Then only the managed one is due, per FR-005.

Out of scope

Edge cases

  • A day of entries read back in order is a ledger that grc verifies, per FR-003.

Assumptions

  • Entries are written by one collector at a time (the collector holds a lock).

Open questions

  • None.

Key entities

  • Journal - the hash-chained list of every look the collector made, the pushes that failed and the seals.

Success criteria

SC-001success criterion

Only what the capture policy asks to be journaled is.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

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