AirCoding/AirPlan/docs/architecture/artifact-naming-v1.md

AirCoding Artifact Naming and Layout V1

Date: 2026-05-27 Status: Canonical artifact naming/layout standard for V1.0.0 Alpha skeleton

This document defines artifact URI format, directory layout, naming conventions, metadata requirements, compression rules, and evidence linkage.

1. Goals

Artifact storage must be:

1. Project-local and session-local.
2. Stable across project moves when using artifact URI and DB records.
3. Queryable through SQLite domain tables.
4. Safe for large logs/binaries/screenshots/pcaps/core dumps.
5. Linked to tool/command/task/agent/evidence records.
6. Compatible with crash recovery and final reports.

2. Root Layout

Session artifact root:

<project>/.air/local/sessions/<session-id>/artifacts/

Canonical subdirectories:

artifacts/
  messages/
  context/
  command-runs/
  tool-runs/
  builds/
  tests/
  static-analysis/
  debug/
  screenshots/
  pcaps/
  core-dumps/
  diffs/
  reports/
  doctor/
  permissions/
  workspaces/
  ui-assets/
  tmp/

tmp/ is not referenced by artifacts table until a file is atomically renamed into a canonical directory.

3. Artifact URI

Canonical URI:

artifact://project/<project-id>/session/<session-id>/<artifact-id>

Rules:

1. URI is stable and stored in artifacts.uri.
2. Filesystem path is stored in artifacts.path.
3. Consumers should prefer URI + DB lookup over reconstructing paths.
4. Artifact IDs are opaque stable IDs, not semantic filenames.

4. Artifact ID

V1 artifact ID format:

art_<ulid>

Examples:

art_01JZ7QX4D4N9Y6QZ3C9QH4SX2A

Rules:

1. IDs are generated before writing temp files.
2. IDs must be unique within session DB.
3. IDs are not reused after failed writes.
4. Human-readable meaning belongs in filename and metadata, not ID.

5. Filename Format

Canonical filename:

<timestamp>-<artifact-id>-<slug><extension>

Timestamp format:

YYYYMMDDTHHMMSSmmmZ

Examples:

20260527T142233120Z-art_01JZ7QX4D4N9Y6QZ3C9QH4SX2A-build-log.txt.gz
20260527T142240992Z-art_01JZ7QXXM8WAPVTA5Y4F4P5NTQ-screenshot.png
20260527T142251002Z-art_01JZ7QY8P6PR3G2T5BXE91D6KD-diff.patch

Slug rules:

lowercase
ascii letters/numbers/hyphen only
collapse repeated hyphens
max 64 chars
no secrets, usernames, absolute paths, tokens, or raw command strings

6. Type to Directory Mapping

Artifact type	Directory	Default extension
message_snapshot	messages/	.json.gz
context_pack	context/	.json.gz
stdout	command-runs/<command-run-id>/	.stdout.txt.gz
stderr	command-runs/<command-run-id>/	.stderr.txt.gz
combined_output	command-runs/<command-run-id>/	.combined.txt.gz
tool_output	tool-runs/<tool-run-id>/	.json.gz
build_log	builds/	.txt.gz
test_report	tests/	.json or .xml
static_analysis_report	static-analysis/	.json
debug_report	debug/	.md
backtrace	debug/	.txt
screenshot	screenshots/	.png
pcap	pcaps/	.pcap
core_dump	core-dumps/	.core
diff	diffs/	.patch
review_report	reports/	.md
doctor_report	doctor/	.json
permission_report	permissions/	.json
workspace_diff	workspaces/<workspace-id>/	.patch
ui_asset	ui-assets/	.svg / .png / .json

7. Command and Tool Run Layout

Command run artifacts:

command-runs/<command-run-id>/
  <timestamp>-<artifact-id>-stdout.txt.gz
  <timestamp>-<artifact-id>-stderr.txt.gz
  <timestamp>-<artifact-id>-combined.txt.gz
  <timestamp>-<artifact-id>-diagnostics.json

Tool run artifacts:

tool-runs/<tool-run-id>/
  <timestamp>-<artifact-id>-input.json.gz
  <timestamp>-<artifact-id>-output.json.gz
  <timestamp>-<artifact-id>-report.md

Only store tool input as artifact when needed for audit/debug; secrets must be redacted or omitted according to tool policy.

8. Write Protocol

Artifact file write protocol:

1. generate artifact_id
2. write to artifacts/tmp/<artifact-id>.tmp
3. fsync/close where supported and appropriate
4. compute sha256 and size
5. atomic rename into canonical directory
6. insert artifacts row and emit artifact.created in same logical operation
7. link evidence_refs if applicable

If DB insert fails after rename, recovery scans orphaned files and either registers or quarantines them under tmp/orphans/.

9. Compression Rules

Default compression:

Content	Rule
text logs over threshold	gzip
JSON context/message snapshots	gzip
screenshots PNG/JPEG	no double compression
pcap	no compression by default
core dumps	no compression by default in MVP
small markdown reports	no compression
patches	no compression unless very large

Default threshold:

compress text/json artifacts >= 64 KiB

10. Metadata Requirements

Minimum artifact row:

interface ArtifactMetadataV1 {
  schema_version: 1
  producer: "tool" | "command" | "agent" | "scheduler" | "main" | "system"
  content_type?: string
  compression?: "gzip" | "none"
  redaction?: "none" | "partial" | "full" | "not_applicable"
  preview_available?: boolean
  original_path?: string
  command_run_id?: string
  tool_run_id?: string
  task_id?: string
  agent_id?: string
  related_event_ids?: string[]
  notes?: string[]
}

DB columns store common query fields separately; metadata is for extra detail.

11. Evidence Linking

Artifacts are facts only when linked by evidence_refs.

Example:

artifact: command combined output
claim: "cpp.build failed with undefined reference in linker stage"
evidence_ref.kind: command_output
evidence_ref.ref: artifact://...
location_json: { "line_start": 120, "line_end": 148 }

Rules:

1. A report may cite many evidence refs.
2. A single artifact may support multiple claims.
3. Evidence claims should be concise and testable.
4. Do not treat artifact existence as proof without a claim.

12. Redaction and Sensitive Data

Default local artifacts are not automatically redacted because they are project-local debug evidence.

Before export/share/upload:

preview
redact secrets/credentials/private paths where policy requires
record redaction status
require explicit user authorization

Doctor bundles may include full diagnostics and are encrypted for the development team when exported through that channel.

13. Retention

Session artifacts are retained with the session by default.

Cleanup candidates:

tmp files
orphaned failed writes
duplicate large command stream chunks after combined artifact exists
old developer logs outside project session artifacts

No automatic deletion of evidence-bearing artifacts in MVP unless user explicitly runs cleanup and confirms the policy.

14. V1.0.0 Alpha Cut Line

V1.0.0 Alpha skeleton must implement:

1. Artifact ID generation.
2. Canonical URI creation.
3. Directory mapping by artifact type.
4. Temp-write then atomic rename.
5. sha256 and size recording.
6. gzip compression for large text/json.
7. artifacts table insertion.
8. artifact.created event emission.
9. Evidence ref linking.
10. Orphan scan/quarantine on startup.

Post-MVP:

content-addressed deduplication
artifact browser UI
automatic retention policies
export bundle redaction profiles
remote artifact storage adapters