amduat-api/notes/walk a single artifact all the way.md

Great, let’s do this **concretely and end-to-end**, but still faithful to the specs you’ve been shaping. I’ll walk a **single artifact** all the way through its lifecycle:

* creation
* witnessing (certificate case)
* indexing
* snapshotting
* eviction from local storage
* later rehydration
* reuse in a new program

I’ll label **what is normative** vs **implementation choice**, and I’ll keep the mental model consistent: **blocks are physical, artifacts are semantic**.

---

# End-to-End Artifact Lifecycle Walkthrough

We’ll use a **certificate artifact** because it exercises *authority*, *witnessing*, and *reuse*.

Assume we are on a **personal domain** `alice.personal`, on an ASL-HOST.

---

## Phase 0 – Initial state (before anything happens)

On disk:

```
/asl/domains/alice.personal/
├── blocks/
│   ├── open/
│   └── sealed/
├── index/
├── log/
├── snapshots/
└── meta/
    └── dam/
```

Current snapshot:

```
alice.personal@42
```

Authority:

* DAM says `self-authority`
* Host holds Alice’s private key
* Host is **Active**

---

## Phase 1 – Artifact creation (certificate is generated)

### What happens conceptually

A **PEL program** is run that generates a certificate:

* Input: key material, policy parameters
* Output: certificate bytes

This is *just data* at this stage.

---

### On disk: block writing (physical layer)

1. ASL allocates an **open block**:

```
blocks/open/blk_tmp_7f3a.tmp
```

2. Certificate bytes are appended to the open block.

3. The artifact bytes occupy:

```
offset = 8192
length = 1432
```

At this moment:

* No artifact exists yet (semantically)
* Bytes are **not visible**
* Crash here is allowed

---

### Block sealing (normative)

4. Block is sealed:

```
block_id = H(block_bytes)
```

File moved to:

```
blocks/sealed/7f/7f3a9c...blk
```

**Invariant satisfied:** sealed blocks are immutable.

---

## Phase 2 – Artifact becomes real (indexing)

### Artifact identity

Artifact key is computed from:

```
H(certificate_bytes + type_tag + metadata)
```

Example:

```
artifact_key = a9c4…
```

---

### Index entry written

An index entry is appended to an **open index segment**:

```
index/shard-012/segment-0042.idx (open)
```

Entry:

```
ArtifactKey → (BlockID, offset, length)
type_tag = cert.x509
```

Still **not visible**.

---

### Log append (normative visibility point)

A log record is appended:

```
log-0000000000001200.asl
```

Record:

```
ADD_INDEX_ENTRY artifact_key=a9c4… segment=0042
```

Then:

```
SEAL_SEGMENT segment=0042
```

**Now the artifact exists.**

---

## Phase 3 – Snapshot & witnessing

### Snapshot creation

A snapshot is emitted:

```
alice.personal@43
```

Snapshot pins:

* index segment 0042
* block 7f3a…

Snapshot manifest includes:

```
authority:
  domain: alice.personal
  key: alice-root-key
```

---

### Witnessing from elsewhere (certificate use case)

Now the **certificate is taken aboard** by another domain, say:

```
common
```

How?

1. The certificate artifact is **published** (policy allows this)
2. `common` imports the artifact:

   * artifact bytes are fetched (or referenced)
   * artifact key is preserved
3. A **cross-domain reference** is indexed in `common`

No copying is required if blocks are addressable, but often they are copied.

Witnessing here means:

> The certificate is now **provably present in two domains**, each with their own snapshot history.

---

## Phase 4 – Time passes (artifact becomes cold)

A week passes.

A **local retention policy** runs (implementation choice, but policy-guided).

### GC decision (normative constraints)

The artifact:

* is sealed
* is referenced by snapshot `@43`
* is not referenced by CURRENT workflows

Policy allows **cold eviction** if:

* snapshot still exists
* artifact can be re-fetched from trusted domains

So…

---

### Block eviction (implementation choice)

Local block file is removed:

```
blocks/sealed/7f/7f3a9c...blk   ← deleted
```

But:

* index entry remains
* snapshot remains
* artifact is still **logically present**

This is allowed because:

> **ASL defines availability separately from existence.**

---

## Phase 5 – Artifact is needed again

Later, a new PEL program runs:

* Input: certificate artifact `a9c4…`
* Purpose: sign something new

### Artifact lookup

1. Index lookup finds:

   ```
   ArtifactKey → (BlockID, offset, length)
   ```
2. Block is missing locally.

---

### Rehydration (normative + policy)

ASL-HOST:

1. Consults **domain policy**
2. Finds trusted source:

   * `common`
   * or a personal mirror
3. Fetches block by `BlockID`

Block is restored to:

```
blocks/sealed/7f/7f3a9c...blk
```

**Block hash verified.**

---

## Phase 6 – Artifact reused in a new program

The certificate bytes are read from the block.

A new PEL program runs:

* Inputs:

  * certificate artifact `a9c4…`
  * new data
* Outputs:

  * new artifact(s)
  * new PER

These outputs repeat the **same lifecycle**.

---

## Phase 7 – Index & snapshot continuity

Now:

* Snapshot `@44` references:

  * old certificate
  * new artifacts
* Old artifact remains immutable
* Provenance is intact

At no point did we:

* rewrite bytes
* change meaning
* trust runtime state

---

## What was witnessed, exactly?

Three things were witnessed, independently:

1. **Bytes** (block hash)
2. **Meaning** (artifact key → index)
3. **Authority** (snapshot + DAM + signatures)

This is why the system holds together.

---

## Why this works for *everything*

This same flow works for:

* certificates
* home directory tarballs
* shell command outputs
* TGK edges
* PERs
* witness rotation artifacts

Nothing special happens for “important” artifacts.

---

## The key invariants you just saw

1. **Artifacts never move**
2. **Blocks may come and go**
3. **Snapshots pin meaning, not bytes**
4. **Witnessing is just another artifact**
5. **Time does not weaken correctness**

---

## One sentence to take away

> An artifact can disappear from disk, reappear a year later, and still mean exactly the same thing.

If you want next, we can:

* walk the **same artifact across two personal machines**
* show **what breaks if someone cheats**
* map this onto **ZFS send/receive**
* or show **how PEL receipts stitch all this together**

You’re now fully “above the filesystem” — exactly where you wanted to be.