Ingest and reconstruct with BTDU
This walkthrough puts a real Git repository under governed BTDU state, records pinned provenance, then reconstructs an object exactly. The purpose is not merely storage: it is to preserve source, controller, evidence and lineage while keeping topology separate from ownership.
Before you start
You need an ENTITY identity state directory, a BTDU state directory, the ADAM runtime root, Git, and a local repository you are authorized to ingest.
main.1. Initialize BTDU
python tools/entity_btdu_cli.py \ --entity-state STATE \ --btdu-state BTDU_STATE \ --adam-root ADAM_ROOT \ --git-bin git \ init
The init command materializes the primitive-byte universe and deep-verifies the BTDU state.
2. Check the state before mutation
python tools/entity_btdu_cli.py \ --entity-state STATE \ --btdu-state BTDU_STATE \ --adam-root ADAM_ROOT \ --git-bin git \ status
Treat signature, authorization, reconstruction or atomic-root mismatch as failure. Do not bypass verification to make a tutorial pass.
3. Ingest a pinned repository
python tools/entity_btdu_cli.py \ --entity-state STATE \ --btdu-state BTDU_STATE \ --adam-root ADAM_ROOT \ --git-bin git \ ingest-repo REPO_PATH \ --provenance git://OWNER/REPO@COMMIT_SHA
The repository manifest can include repository path, Git commit/tree where available, tracked-file count, aggregate SHA-256 and resulting atomic root. BTDU ingestion computes exact content hashes and bonds the governed objects to source/controller/rights/evidence/provenance references.
4. Record the output you will need later
- repository manifest or receipt
- atomic root
- pinned commit/tree
- tracked-file count
- aggregate/content SHA-256 values
- object references you want to query or reconstruct
5. Inspect bounded object context
python tools/entity_btdu_cli.py \ --entity-state STATE \ --btdu-state BTDU_STATE \ --adam-root ADAM_ROOT \ --git-bin git \ context OBJECT_REF
context projects bounded governed context. Use it to inspect relationships without assuming that a graph relationship creates ownership, licence rights or economic entitlement.
6. Reconstruct exact bytes
python tools/entity_btdu_cli.py \ --entity-state STATE \ --btdu-state BTDU_STATE \ --adam-root ADAM_ROOT \ --git-bin git \ reconstruct OBJECT_REF OUTPUT_PATH
The command reconstructs the governed object and reports SHA-256. Compare that hash with the expected source hash.
7. What a successful run proves
| Evidence | What it supports |
|---|---|
| Pinned provenance | The ingest points to an immutable source state rather than a moving branch. |
| Atomic/content hashes | The represented bytes/state can be integrity-checked. |
| Exact reconstruction | The governed object can be recreated byte-for-byte for the tested object. |
| ENTITY/BTDU relationships | Source/controller/evidence/provenance relationships are explicit. |
| Not automatically proven | Ownership, external legal rights, payment or objective truth. |
8. Success criteria
statusverifies before and after ingestion.- The repository is ingested under a pinned provenance reference.
- You can retrieve bounded context for an object.
- The reconstructed SHA-256 equals the expected source SHA-256.