Files, logs and recovery

Role: Run submitter or authorized run reader, or artifact owner; connector/service owners investigate transfer and retained-state failures. Prerequisites: The original API/account and a retained analysis directory, prepared operation, acceptance receipt or accepted run/artifact UUID. Files: Original source bytes are needed only while their upload remains unfinished; retain state files, connector journals and final files as applicable.

Upload and download boundaries

For an unsupported file format, unexpected JSON fields or a request/envelope mismatch, first use the file and download chooser to identify the command’s intended file. An author publication, scientific inputs, wrapper request, collection manifest and saved operation are different documents. Download the complete model examples when you need matching code, fixtures and tests; preserve the rejected file and existing operation evidence while comparing them.

Symptom	Next action
Lost upload response	Resume with the original state file and unchanged source
Source checksum changed	Restore the original source for that operation; a changed file needs a deliberately new upload
Upload not usable as input	Inspect/resume completion; only completed verified artifacts belong in run inputs
Artifact inaccessible	Check account/scopes and accepted-run dependency or producer access; guessed UUIDs grant no access
Download capability expired	Request fresh content access through the artifact endpoint/CLI
Size or SHA-256 mismatch	Preserve the error, reject the bytes and investigate the exact stored version; never use an unverified result
Download output already exists	Choose a new destination filename; the CLI preserves existing files
Results wait during storage outage	Retain final files and journal; restore the transfer path without rerunning science
Required output missing or invalid	Model author inspects wrapper declaration, path/media type and scientific schema

Contact Enumeray support with the artifact or upload ID to investigate storage availability and the pinned destination. A changed default does not redirect already accepted work to a new bucket.

Inspect the exact operation before creating a replacement:

# User, with the original source and saved state:
enumeray --json artifact resume --state upload.json > completion.json
ARTIFACT_ID=$(jq -er '.artifact_id' completion.json)
enumeray artifact get "$ARTIFACT_ID"

# Submitter or current model administrator, for stalled result delivery:
enumeray run get RUN_UUID
enumeray run artifacts RUN_UUID

An expired reservation cannot be extended into a new upload by editing its state file. After establishing the old operation’s outcome, a deliberately new upload needs a new state filename. A checksum mismatch means the transfer is not usable; keep the returned error and reject the downloaded bytes. The CLI publishes the destination only after successful verification, using a temporary file in that directory.

Logs and archives

Use the supplied recovery cursor after history_cursor_expired and show the omitted prefix. Retention/discontinuity markers are evidence of missing bytes, not scientific failure. Replacing or truncating a source starts a new epoch. Stream silence and closure require independent run inspection.

Archive status is separate from completeness and the scientific outcome. An unavailable archive can reflect disabled policy, storage failure or an expired publication deadline. Inspect manifest.json in a ready archive to determine whether it is partial. Expired attachments cannot acquire new dependency pins; ordinary scientific artifacts follow separate retention rules.

Recover without losing evidence

# An accepted run whose original analysis directory was lost:
enumeray analysis attach RUN_UUID --directory recovered-analysis
# Alternative: attach using a retained acceptance receipt.
enumeray analysis attach --receipt run-receipt.json --directory receipt-analysis
enumeray analysis status recovered-analysis
enumeray analysis collect recovered-analysis

# A legacy prepared operation; import is local and sends no request:
enumeray analysis import --prepared prepared-run.json --directory imported-analysis
# After reviewing it and authenticating to its original API/account:
enumeray analysis submit imported-analysis

# An unfinished independent upload, with its unchanged original source:
enumeray artifact resume --state upload.json

For --receipt, pass the receipt object itself, such as retained state/receipt.json or the .receipt field extracted from an analysis submit --json summary. The full summary is not a receipt. Attachment reads authorized run/provenance records and retains the accepted inputs, exact publication/contract, purpose and available evidence. Today’s current publication and the old local sources are unnecessary. It grants no new read or cancellation rights; model-administrator inspection does not confer submitter cancellation. Unavailable local-only paths, source fingerprints and upload checkpoints stay explicitly unavailable. An attached directory can observe and collect its original run; submission cannot create another execution.

Import preserves the prepared file’s exact API/account, request, purpose/delegation and idempotency key without contacting the service or changing the source file. No receipt does not mean no run: explicit analysis submit reconciles the original request, including a lost acceptance reply. Do not edit the key, re-prepare against today’s publication or re-upload completed artifact/collection inputs. A never-accepted request can still be rejected by current authorization or publication rules. Retain that evidence before deliberately choosing any new work.

Repeat an interrupted attach/import with the same source and destination. Existing unrelated directories, malformed or conflicting evidence and private-file permission failures require inspection; preserve the files instead of overwriting them. A complete accepted directory can be copied to another host for the same API/account with private permissions preserved. Completed result files are rehashed and reused when they match pinned evidence. Preserve unfinished download checkpoints; a partial byte prefix may download again after its absolute destination changes. Unfinished uploads still require their retained transfer state and unchanged original source bytes; submission explains missing-source requirements. Importing a prepared operation does not restore those bytes.

If both the uncertain prepared operation and the receipt are lost, use authorized run list history to find accepted work and attach its run ID. The available history cannot establish that a lost request was never accepted. Do not automatically submit a replacement. Retain operation files until acceptance is known, then keep the receipt or accepted analysis directory. Renew credentials for the same account when needed. See analysis directories for the full recovery workflow, copied-folder use, records to retain and partial/evidence-only collection. The noninteractive recipe resumes the same reviewed folder without extracting UUIDs. Historical reruns and sweeps remain deferred under TASK-072 and TASK-074.

Connector recovery resumes retained completed execution and pending publication; it must not launch the science again. Keep the original journal and execution identity, and verify prior connector ownership before manual recovery. General local history deletion is not automated in version 1.

Expected outcome: Verified data delivery or a precise retained failure. Next: Coordinate connector operations or Enumeray support with the responsible owner.