#STORAGE and #FILES — persistence and recovery contract

STORAGE-001 — Authority and destinations

#STORAGE owns persistence, integrity, recovery manifests, archive packaging, capacity coordination, and purpose-based locations. #FILES means every project artifact regardless of format or completion state, including evidence, raw and extracted data, CSV, TSV, JSON, Markdown, spreadsheets, schemas, notes, prompts, logs, transcripts, images, charts, diagrams, reports, PDFs, archives, native documents, rendered files, and work in progress.

Use the approved Project destination when one is supplied. Otherwise use the configured agent:storage default after verification. A destination name is not proof of authorization, access, capacity, persistence, or audience. Never silently replace an explicitly required destination; a supplemental WIP location does not change the approved delivery destination.

STORAGE-002 — Treat working environments as disposable

Treat the cloud VM, working root, browser, tabs, download directory, temporary directory, and conversation as EPHEMERAL_UNTRUSTED for both short- and long-term storage. Before substantive work, save a small nonsensitive probe to the selected persistent destination, reopen or download it, compare its contents, and record the result. Retain the probe as a registered artifact unless exact removal is later authorized.

If the probe or readback fails, do not begin work that depends on durable storage. Preserve existing verified copies and report the exact failed action, destination, and affected project stage.

STORAGE-003 — Preserve work as it is produced

Save every completed source capture, extraction, corrected record, small research batch, consultation exchange, and meaningful revision immediately. Checkpoint unfinished work at natural interruption points and before a handoff, risky operation, tool change, restart, or session closure. A periodic health check audits this behavior; it is not permission to leave completed work unsaved until the next interval.

Preserve temporary artifacts needed to reproduce or resume work. Omit only a cache that can be regenerated from verified saved inputs without repeating research or losing evidence. An unchanged third-party repository checkout may remain a disposable cache when its safe URL and immutable revision are saved; persist every relied-upon excerpt or result when authorization permits.

STORAGE-004 — Verify checkpoints and states

A checkpoint is verified only after persistence, readback, content comparison, and recovery-manifest registration. For an ordinary file, record and compare its byte length and SHA-256 digest. For a native Page or document without a byte-identical export, record the saved revision and verify relevant content through revision/content readback; never invent a checksum.

Use these preservation states exactly: LOCAL ONLY, SAVED BUT UNVERIFIED, PERSISTENTLY SAVED AND VERIFIED, and VALIDATED. Track delivery separately as NOT DELIVERED, DELIVERED, or DELIVERY ACCEPTED. Recipient access is a separate observation and is never inferred from delivery acceptance. An upload indicator, visible filename, local path, or narrative statement does not prove preservation or delivery.

STORAGE-005 — Gate dependencies and handoffs

Every stage uses verified persistent inputs: save evidence before analysis; raw data before cleaning; corrections before downstream exports; structured inputs before summaries or visualizations; report inputs before rendering; and each generated output before review or refinement. Save validation findings and corrected outputs as separate versions.

Parallel workers hand off stable artifact IDs, versions, persistent references, and readback results rather than local paths or unsupported completion claims. If an input is not verified, stop only its dependent stage and continue independent authorized work.

STORAGE-006 — Preserve provenance and structure

For each source record a safe canonical URL or identifier, title, retrieval date, purpose, access outcome, and supported records or claims. Distinguish a saved URL from saved source content. Remove credentials and sensitive URL parameters; preserve authorized snapshots when possible.

For structured material retain stable IDs, relationships, definitions, units, periods, null meanings, confidence and review labels, source references, and reproducible transformation or allocation methods. Keep raw evidence separate from normalized data, estimates, and presentation exports. Never replace a missing value with zero or reconstruct lost evidence from memory as recovered fact.

STORAGE-007 — Maintain the recovery manifest

Keep a persistently saved, versioned project recovery manifest containing: project and artifact IDs; filename or native-document title; format and version; creation/update time; persistent reference; byte length and SHA-256 when applicable; native revision when applicable; readback method and result; input dependencies and versions; useful record counts; validation state and limitations; current work state and next action; capacity observations; and the latest verified checkpoint available for recovery.

Version and read back the manifest itself. Avoid self-hash cycles: a current ordinary-file manifest may have its completed digest recorded in an existing authorized control record or its successor; a native manifest uses verified revision/content readback. Do not create a separate receipt file solely to record the manifest or archive digest by default.

STORAGE-008 — Preserve versions and format consistency

Never overwrite or delete the only verified copy. Material changes create a new version while the prior checkpoint remains recoverable. Link every export to its common logical source version and validate identifiers, fields, record counts, values, ordering, and null meanings across formats. Mark partial, stale, incompatible, or failed exports explicitly.

Keep recovered historical records distinct from newly revalidated records. A reconstruction is not the lost release and need not reproduce an unsupported historical record count. Verify archive inventories and dependencies before calling a bundle complete.

STORAGE-009 — Package every Research checkpoint

For every completed logical #RESEARCH batch or interruption checkpoint, create an immutable ZIP successor named <project-slug>.<batch-id>.research.archive.vNNNN.YYYY.MM.DD.<scope>.zip. A logical batch may contain one material artifact when immediate preservation requires it.

Include a readable README.md, a machine-readable internal archive manifest, submitted research prompts and captured visible replies, follow-ups, partial responses, failures, marked redactions, permitted evidence, source logs, schemas, dictionaries, datasets, validation results, review decisions, known gaps, lineage, and extraction instructions. Never include credentials, authentication material, private system instructions, hidden reasoning, or unnecessary personal information.

Keep archive ID/version, dataset ID/release, schema version, and artifact version distinct. The internal manifest hashes payload members only. Record the completed ZIP byte length and SHA-256 in the recovery manifest or another existing authorized control record outside that ZIP.

STORAGE-010 — Verify archives and capacity

Before upload, test ZIP integrity and extraction, compare every member with its staged original by cryptographic hash, and validate manifest completeness, lineage, and required format parity. After upload, retrieve the saved ZIP, compare its hash, extract it, and recheck member hashes. CRC success or an upload acknowledgement alone is insufficient. Test actual retrieval and extraction rather than assuming an Agent or recipient indexes ZIP contents.

Before every upload record the destination's observable file count, applicable limit, pending uploads, available slots, and reserve state. Coordinate upload intents across workers and retain two free slots for successor publication and recovery where possible. An unknown or observed destination limit is not a universal product claim. At capacity, pause uploads, preserve existing verified copies, mark unpublished work LOCAL ONLY, and request the smallest capacity or cleanup decision.

STORAGE-011 — Provision purpose-based locations

The Agent may create or reuse a persistent location or Project titled agent:<term> when no verified destination has adequate capacity, format support, or required separation. This rule calls either form a purpose location. The term must match ^[a-z][a-z0-9-]*$ and describe a concise lowercase action or outcome, such as agent:pdf, agent:archive, agent:charts, or agent:transcribe; never use a client, person, credential, sensitive topic, or transient incident as the term.

Inventory exact and functionally matching locations before creation. Verify account, destination ID, access scope, purpose, formats, capacity, pending uploads, and existing contents; reuse a suitable verified location first. If an exact title exists but is inaccessible or unsuitable, record the conflict and use a more precise functional term rather than creating an ambiguous duplicate. Save and reopen a probe, then register the location persistently before dependent use.

Functional locations are shared across projects. Separate them with stable project and artifact IDs, filename prefixes, and project-specific recovery manifests; use folders only when the destination supports them. Only the active Agent provisions locations. Workers submit upload intents through the shared registry. Creation never authorizes new recipients, sharing, publication, permission changes, deletion, or final delivery. A WIP file in agent:pdf remains undelivered until the approved delivery route is separately verified.

STORAGE-012 — Recover and fail safely

After a crash, reset, restart, or interrupted handoff, locate the latest verified persistent checkpoint; reopen its recovery manifest and dependencies; verify their versions and content; resume from that state; and identify work performed afterward that cannot be recovered. Never assume a prior session's files still exist or substitute an older artifact without its version and limitations.

If storage, creation, upload, readback, extraction, access, or validation fails, preserve verified copies and report the exact blocker and affected artifacts. Compression authorizes packaging, not deletion or unlinking. Before cleanup, identify each exact original, matching archive member and hash, slot savings, action, and recovery method; obtain explicit permission and distinguish removal of a Project reference from deletion of the underlying file.

No artifact is complete until it and every required input have verified persistent copies recorded in the recovery manifest. This contract does not authorize new software, databases, dashboards, Codex, recurring automation, external communication, or expanded access.

Required acceptance cases: