# Phase 5: Artifact Pipeline - Discussion Log

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.

**Date:** 2026-03-23
**Phase:** 05-artifact-pipeline
**Mode:** --auto (all selections made autonomously)
**Areas discussed:** Registry structure, rsync invocation, Node deduplication check, ArtifactDiff model, Partial failure semantics

---

## Registry Structure

| Option | Description | Selected |
|--------|-------------|----------|
| Dict keyed by artifact_id | `{artifact_id: BuildArtifact.dict()}` — O(1) lookup, natural dedup via key-exists check | ✓ |
| Array of BuildArtifact | List format — requires scan for dedup, simpler append | |

**[auto] Selected:** Dict keyed by artifact_id (recommended default)
**Notes:** Consistent with O(1) lookup requirement for dedup check. Atomic write via `.tmp` + `os.replace()` already established pattern in codebase.

---

## rsync Invocation

| Option | Description | Selected |
|--------|-------------|----------|
| subprocess rsync with -e ssh | Direct rsync subprocess using SSH transport with key auth | ✓ |
| asyncssh SCP/put | Use existing asyncssh connection for file transfer | |
| Python rsync library | Third-party library wrapping rsync | |

**[auto] Selected:** subprocess rsync with `-e ssh -i <key>` (recommended default — design doc explicitly names rsync)
**Notes:** Design doc §2.3 explicitly says "rsync the artifact tree". asyncssh SCP would work but rsync provides dedup/delta-transfer benefits for large build trees. Concurrent fan-out via `asyncio.gather` + `asyncio.create_subprocess_exec`.

---

## Node Deduplication Check

| Option | Description | Selected |
|--------|-------------|----------|
| SSH `test -d` on remote path | Check if `{dest_base}/{artifact_id}/` exists via SSH before rsync | ✓ |
| Server-side tracking in registry | Track per-node install state in the JSON registry | |
| Always rsync, let rsync decide | Rely on rsync's own checksumming to skip unchanged files | |

**[auto] Selected:** SSH `test -d` on remote path (recommended default — preserves stateless server principle from PROJECT.md)
**Notes:** Server-side tracking would violate the stateless server principle. Relying on rsync alone wouldn't set `skipped=True` in the result. SSH check reuses Phase 3 asyncssh infrastructure.

---

## ArtifactDiff Model

| Option | Description | Selected |
|--------|-------------|----------|
| changed_modules + changed_bins + git_log | Per design doc §2.4: `.ko` files and binaries that differ, plus git log between SHAs if available | ✓ |
| Full file diff listing | Include all changed files, not just .ko and bins | |

**[auto] Selected:** `changed_modules: list[str]`, `changed_bins: list[str]`, `git_log: str | None` (recommended default — matches design doc exactly)
**Notes:** ART-05 acceptance criteria says "filenames of `.ko` files and binaries that differ between two named artifacts". Diff by re-hashing files in `source_path` of each registered artifact at diff-request time.

---

## Partial Failure Semantics: artifact_install

| Option | Description | Selected |
|--------|-------------|----------|
| Best-effort per node | Each node runs independently; failures reported but don't abort others | ✓ |
| All-or-nothing | If any node fails, return error and report all | |

**[auto] Selected:** Best-effort per node with full per-node reporting (recommended default — consistent with Phase 4 snapshot_delete D-08)
**Notes:** Same applied to `artifact_sync`. agents can identify failed nodes from `InstallStatus.per_node` and retry individually. Consistent with the pattern established in Phase 4 for delete operations.

---

## Agent's Discretion

- Exact rsync flags beyond `-avz`
- Whether artifact diff re-reads source_path or caches hashes in registry
- SSH `StrictHostKeyChecking` / `known_hosts` handling for rsync subprocess
- Error contract when `source_path` no longer exists
- `kernel_version` auto-detection in `artifact_register`

## Deferred Ideas

- `artifact_build` (ART-V2-01) — out of scope for v1
- Whether to copy artifact trees to `artifact_store_dir` before sync — researcher evaluates
