# Artifact Safety and Failures

Bounded references do not make source tools, embedded Python, or sensitive payloads safe to execute or disclose.

## Failure Semantics

Artifact failures are explicit and do not silently expose the full payload:

| Error | Meaning |
| --- | --- |
| `ArtifactPolicyError` | Invalid field, unit, store, duration, or bound |
| `ArtifactInputError` | Invalid read/search arguments, incompatible modes, or missing JSON path; also a `ValueError` |
| `ArtifactSerializationError` | Value cannot be represented by the selected store |
| `ArtifactQuotaExceededError` | Count or byte quota would be exceeded |
| `ToolOutputTooLargeError` | Artifacts are disabled and a tool result exceeds 100,000 bytes |
| `ArtifactNotFoundError` | Reference is unknown to the active session |
| `ArtifactAccessError` | Cross-session access or unsafe store path |
| `ArtifactReleasedError` | Payload was explicitly released or is pending release |
| `ArtifactExpiredError` | TTL or idle TTL elapsed |
| `ArtifactStreamError` | Stream kind, chunk, reuse, or transactional consumption failed |
| `ArtifactCodeAccessError` | Code attempted to access a ref outside its allowlist |
| `ArtifactCodeBudgetError` | Code exceeded a host-call, read, materialization, or result bound |
| `ArtifactCodeError` | Sandboxed artifact computation failed |

Quota failure occurs before publishing a reference. Stream failure aborts the
transaction. Code-mode failure does not create a derived artifact. None of
these errors include the rejected raw payload in their message or telemetry.

For agent calls, invalid read/search arguments and unknown, expired, or released
references become tool-error responses. The model may correct its arguments under
the adapter's existing retry/turn limits; Kedi does not retry automatically or
increase those limits. Pattern search requires `path=None`, `offset=0`, and
`offset_from="start"`. It cannot be combined with JSON selection or pagination.

Direct Python callers still receive typed exceptions. Storage corruption,
configuration failures and unexpected runtime exceptions are not reclassified
as correctable artifact arguments. Provider harnesses retain their own ordinary
tool-failure reporting behavior.


## Security and Observability

Artifact metadata, summaries, bounded previews, read sizes, lifecycle states,
and code-mode provenance may appear in telemetry. Raw payloads are not attached
to artifact lifecycle spans. Code provenance contains a code hash and source
references, not an unrestricted payload copy.

Artifact storage is not a secret-management boundary. Sensitive data still
requires a suitable file-store root, TTL, approval policy, process isolation,
and telemetry configuration. The `sensitive` marker is metadata for policy and
observability consumers; it does not encrypt the payload.


## Operational Guidance

- Keep artifacts enabled for agentic programs. Disabling them does not permit
  unbounded tool context; it converts oversized results into hard failures.
- Set `threshold` above the expected size of useful reductions so
  `run_artifact_code` can return them inline.
- Use `ArtifactStream` for producer-memory control. Ordinary artifact admission
  controls model context, not the allocation already made inside a tool.
- Prefer `read_artifact` for one bounded fact and `run_artifact_code` for data
  reduction. Paging an entire payload through the model defeats the design.
- Release payloads only after the needed evidence and derived values have been
  obtained. Release frees quota but intentionally leaves history immutable.
- Use the file store when process memory offload or restart persistence matters;
  use the memory store when native opaque Python values are required.

Explicitly setting `enabled: false` removes artifact references and management
tools from that scope. A tool result over the hard inline limit still fails
before model history insertion.