Module agentforge4j.runtime

Package com.agentforge4j.runtime

Interface GeneratedArtifactStore

All Known Implementing Classes:

InMemoryGeneratedArtifactStore

public interface GeneratedArtifactStore

Run-scoped, transient holder for the bytes a run emits via CREATE_FILE, so a later deterministic step (artifact validation) can read the authoritative emitted content in-process — never from disk and never from an LLM-echoed copy.

Contract:

• Run isolation — entries are keyed by runId; a run never observes another run's artifacts.
• Last-write-wins — registering a path already present for a runId replaces its content (honouring the CREATE_FILE overwrite contract); a rewind that re-emits a captured path upserts rather than failing.
• Bounds — implementations enforce configured limits and reject writes that exceed them, failing closed rather than growing without limit. The per-run artifact-count bound is evaluated only when registering a new path; an upsert of an existing path does not count against it.
• Eviction — remove(String, String) drops a single captured path (used when a retry/rewind clears the emitting step's execution range).
• Lifecycle — clear(String) releases a run's artifacts when the run reaches a terminal state. The store is transient: bytes are not guaranteed to survive a suspend/resume (a distributed or restarted resume loses them), so validation must run in the same drive as capture; the persisted record is the ArtifactDescriptor set on the run state. A rewind landing between two writes of the same captured path evicts that path rather than restoring the earlier write — capture feeds a same-drive VALIDATE step, not general file history.

The default InMemoryGeneratedArtifactStore retains bytes in memory; embedding applications may supply an alternative implementation.

Method Summary

Modifier and Type	Method	Description
List<GeneratedArtifact>	artifacts(String runId)	Returns the artifacts registered for runId, in registration order.
void	clear(String runId)	Releases all artifacts held for runId.
Optional<String>	find(String runId, String path)	Returns the emitted content for path within runId, if present.
void	register(String runId, String stepId, String path, String content)	Registers the emitted bytes of a file produced by a step for the given run.
void	remove(String runId, String path)	Removes the artifact at path for runId, if present.

Method Details

register

void register(String runId,
 String stepId,
 String path,
 String content)

Registers the emitted bytes of a file produced by a step for the given run.

Parameters:

runId - non-blank owning run id

stepId - non-blank producing step id

path - non-blank requested artifact path

content - emitted content; must not be null

Throws:

IllegalArgumentException - if a configured bound would be exceeded, or an argument is invalid. Re-registering an already-present path is not an error — it replaces the prior content (last-write-wins).

find

Optional<String> find(String runId,
 String path)

Returns the emitted content for path within runId, if present.

Parameters:

runId - non-blank run id

path - non-blank artifact path

Returns:

the content, or empty when no artifact was registered at that path for the run

artifacts

List<GeneratedArtifact> artifacts(String runId)

Returns the artifacts registered for runId, in registration order.

Parameters:

runId - non-blank run id

Returns:

an immutable snapshot (empty when the run has no registered artifacts)

remove

void remove(String runId,
 String path)

Removes the artifact at path for runId, if present. Idempotent (a no-op when the run or path is absent).

Parameters:

runId - non-blank run id

path - non-blank artifact path to evict

clear

void clear(String runId)

Releases all artifacts held for runId. Idempotent.

Parameters:

runId - non-blank run id