IF Commons GitHub

Evidence capture collect

0003Active

0003-evidence-capture-collect · owner if · domain commons

Requirements

FR-001checkfailing

A run MUST keep the state of an asset on the branch (state/<asset>.json) in a commit where it is not yet kept or differs from the one kept, and MUST NOT write it, nor make a commit for it, where it is the same.

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

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

Written in: evidence-capture/src/physical/collect.ts

Tests: failed: suite/collect.test.ts a state is kept only where it changed, every look is journaled, commits come when a state

FR-002checkfailing

Each look MUST be journaled as the policy says in an entry chained to the one before it (the last of the branch, or of the entries waiting), the entries MUST wait in a file of the run's own until a commit is made, and a commit MUST be made when a state changed (the waiting entries committed with it) or, with entries waiting, when the journal's commit interval has run since the last journal commit; the commit MUST be made at the instant of the run and MUST name the assets that changed.

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

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

Written in: evidence-capture/src/physical/collect.ts

Tests: failed: suite/collect.test.ts a state is kept only where it changed, every look is journaled, commits come when a state ; passed: suite/collect.test.ts with a journal of changes and a heartbeat, only a change and the heartbeat are entries

FR-003checkpassing

A look that fails (the asset could not be reached, refused or could not be read, or took longer than the time allowed) MUST be journaled as its kind of failure and MUST NOT change the state kept.

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

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

Written in: evidence-capture/src/physical/collect.ts

Tests: passed: suite/collect.test.ts a look that fails is journaled as its kind and leaves the state kept as it was

FR-004checkpassing

A run MUST look only at the assets that are due by their cadences, MUST say which were not, and MUST look at the assets it is told to, due or not, where it is told; at most the number of assets the limits say MUST be looked at at once.

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

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

Written in: evidence-capture/src/physical/collect.ts

Tests: passed: suite/collect.test.ts only the assets that are due are looked at, those told are looked at whether due or not, a

FR-005checkpassing

A run MUST take a lock and MUST NOT wait for it: where another run holds it, the run MUST end with an error that says so and change nothing.

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

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

Written in: evidence-capture/src/physical/collect.ts

Tests: passed: suite/collect.test.ts a run does not wait for the lock: it ends with an error that says so and changes nothing

FR-006checkpassing

A run MUST push the branch only as the policy says: never, after a commit, or when the interval has run, to the remote the policy names and never forced; a push that fails MUST be an entry push.failed of the journal, MUST leave the remote as it was, and MUST be tried again by the next run; the branch checked out by a person MUST NOT be pushed.

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

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

Written in: evidence-capture/src/physical/collect.ts

Tests: passed: suite/collect.test.ts the branch alone is pushed as the policy says, a push that fails is an entry and leaves th

FR-007checkpassing

The journal of the branch MUST be read back in order and verified with the ledger of grc, naming the first entry that does not follow, and the entries waiting for a commit MUST survive the end of a run and be committed by a later one.

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

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

Written in: evidence-capture/src/physical/collect.ts

Tests: passed: suite/collect.test.ts the journal is read back in order and verified naming the first entry that does not follow

Acceptance scenarios

  1. Given an asset looked at every 15 minutes, When it is looked at four times with the same state, Then one commit holds its state and the journal's entries are committed in a batch, per FR-001 and FR-002.
  2. Given a change of state, When the asset is looked at, Then one commit holds the new state and the waiting entries, per FR-002.
  3. Given an asset that cannot be reached, When it is looked at, Then the failure is journaled and the state kept is as it was, per FR-003.
  4. Given a lock held by another run, When a run starts, Then it ends with an error and changes nothing, per FR-005.
  5. Given a remote that has moved, When the branch is pushed, Then the push fails, the journal says so and the remote is as it was, per FR-006.

Out of scope

  • How an asset is observed: the program that supplies the observer.
  • Signing: a seal is a person's act.

Edge cases

  • A run in which nothing is due makes no entry and no commit, per FR-004.

Assumptions

  • The folder of the run's own memory is outside the files the branch tracks.

Open questions

  • None.

Key entities

  • Run - one pass of the collector: what was due, what was looked at, what changed and what was committed and pushed.

Success criteria

SC-001success criterion

A collector run every minute makes a commit only when a state changed or the batch interval has run.

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

Cited by

Evidence capture journal

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