Skip to content
Sigilbase

Importing history#

Most streams start recording from today. The records that came before — a legacy audit table, a logging platform's export — can be backfilled into a stream from a CSV or NDJSON file, from the stream page's Import button or php artisan sigilbase:import for large files.

Before anything else, the claim, plainly: Sigilbase proves these records are intact since import, and makes no claim about their history before it. An imported record's chain of custody starts at the moment it enters the chain; whatever happened to it in the years before is exactly as trustworthy as the file you provided. This sentence appears on the import screen and in every evidence bundle that contains imported events, because an integrity product that let you mistake backfilled history for born-verified history would be selling you something false.

How an import works#

  1. Upload and dry run. CSV files carry a header row and a column mapping (which columns hold occurred_at, actor, action; unmapped columns become string payload fields, or map a payload column of JSON objects). NDJSON files carry one event object per line, exactly the ingestion API shape. Every row is validated with the same rules as live ingestion — RFC 3339 timestamps, canonical JSON payloads, floats rejected, size caps — and the dry run appends nothing. Errors are listed by row. Up to 100,000 rows per import.
  2. Confirm. A clean dry run unlocks the import. This is the point of no return: the ledger has no undo.
  3. The bracketed run. The importer appends an import.started event to the stream (file SHA-256, row count, source label), then every row in file order, then import.completed — so the import is sequence-bracketed provenance, provable by the chain itself, not a footnote in a database. Rows are paced deliberately so a large import never starves live ingestion. If an import fails partway, the rows already appended remain (append-only means exactly that), the bracket stays open — which is precisely what a partial import should look like — and mapping an idempotency_key column makes a re-run skip what already landed.

How imported events read#

  • Each imported event carries an imported badge, and its detail view distinguishes the occurred_at the record claims from the received_at Sigilbase stamped at import — the moment tamper-evidence attached.
  • The bracket events and the per-event provenance are ordinary ledger facts: they seal, verify, and export like everything else.

In evidence bundles#

A bundle whose range contains an import gains an informational imports.json — bracket sequences, file hash, source label, and the sentence above verbatim. It is additive: bundle consumers were always required to ignore unknown files, the format version does not change, and existing verifiers pass such bundles untouched. Auditors can check the brackets in events.ndjson directly; the manifest just saves them the search.