container

type Backend interface {
	// Capabilities reports what this backend supports. Must be callable on a
	// zero-state backend (no Create needed); the engine queries it at startup
	// to decide whether snapshot:workspace containers can be served.
	Capabilities() Caps

	// Create brings a container to readiness per the spec. The returned Handle
	// is opaque to the caller and must be passed back to Exec / CaptureFiles /
	// Snapshot / Destroy. Phase 2 fake: allocates an in-mem fs map keyed by a
	// monotonic ID. Phase 4 Docker: image-pinned create or compose `up --wait`.
	Create(ctx context.Context, spec ContainerSpec) (Handle, error)

	// Exec runs a command synchronously inside the handle. Returns two
	// channels and an error.
	//
	// chunks: STREAMING channel of IOChunks. Emits each stdout/stderr chunk
	//   as it arrives from the underlying pipe — callers ranging over it
	//   observe the process's output in real time. Closed by the Backend
	//   implementation when both stdout and stderr pipes drain (process
	//   either exited or ctx-cancelled). MUST be drained by the caller; an
	//   unread chunk back-pressures the reader goroutines (chan buffer is
	//   unspecified but bounded).
	//
	// result: SINGLE-VALUE channel of ExecResult. Receives exactly one
	//   value AFTER the chunks channel closes AND the process has been
	//   waited-on (ExitCode + accumulated Stdout + Err available). Then
	//   closes. Receiving from it before chunks closes is permitted (blocks
	//   until the close) but unusual — the natural order is
	//   `for range chunks { ... }; r := <-result`. ExecResult.Err surfaces
	//   transport-class errors (stdcopy mid-stream failure on docker;
	//   ctx.Canceled on native pipe close mid-read) WITHOUT swallowing them
	//   silently.
	//
	// On non-nil error return, BOTH channels are nil; callers must check
	// err before ranging or receiving. The "launch / transport" error
	// class — couldn't start the command at all — surfaces here. If the
	// command ran and merely exited nonzero, err is nil and result's
	// ExecResult.ExitCode carries the code.
	//
	// ctx cancellation: aborts the command; chunks channel closes; result
	// emits an ExecResult with Err set to ctx.Err() (and likely
	// process-killed ExitCode). The function's error return remains nil —
	// the cancellation surfaces via the result value's Err field, NOT via
	// err. Callers that used `errors.Is(err, context.Canceled)` must
	// update to check `result.Err` instead.
	//
	// Slice 5.3: STREAMING refactor of the original Phase 2
	// "(ExecResult, <-chan IOChunk, error)" contract. The Claude Code
	// adapter (agent/claude.Launch) needs progressive event arrival;
	// refactoring Backend.Exec across all three backends is the
	// load-bearing prerequisite.
	Exec(ctx context.Context, h Handle, cmd Cmd) (<-chan IOChunk, <-chan ExecResult, error)

	// CaptureFiles reads the named in-container paths and returns their content,
	// one CapturedFile per path in the input order. Missing-path is a hard error
	// (no partial returns) — output_files are declared by the author and absence
	// at commit time is a step bug, not graceful degradation. The slice 2.4
	// dispatcher passes the bytes up; the interpreter Puts each into Blobs at
	// the commit boundary (this method never touches state.Blobs; see pkg doc).
	CaptureFiles(ctx context.Context, h Handle, paths []string) ([]CapturedFile, error)

	// CopyTo writes each InputFile's bytes to its in-container path BEFORE the
	// step's Exec/Launch — the symmetric inverse of CaptureFiles. Overwrites an
	// existing path. len(files)==0 is a no-op returning nil. Unknown handle is a
	// hard error. Never touches state.Blobs.
	CopyTo(ctx context.Context, h Handle, files []InputFile) error

	// ReadFileAt reads a single in-container path and returns its content.
	// Missing path or unknown handle is a hard error. Mirrors CaptureFiles but
	// for one path. NEVER touches state.Blobs — the engine Puts at commit.
	ReadFileAt(ctx context.Context, h Handle, path string) ([]byte, error)

	// WriteFileAt writes content to a single in-container path, overwriting.
	// Unknown handle is a hard error. Symmetric inverse of ReadFileAt. NEVER
	// touches state.Blobs. Real impls confine the path; the fake is in-memory.
	WriteFileAt(ctx context.Context, h Handle, path string, content []byte) error

	// ReadTreeAt returns the subtree rooted at dir inside the container as a
	// gzip-tar whose entries are relative to dir (no leading dir prefix).
	// Missing or empty dir is a hard error. Unknown handle is a hard error.
	// NEVER touches state.Blobs — the engine Puts the archive at commit.
	ReadTreeAt(ctx context.Context, h Handle, dir string) ([]byte, error)

	// WriteTreeAt extracts a gzip-tar (as produced by ReadTreeAt or
	// BuildTreeTar) into the container under dir, creating dir and all
	// parent directories. Archive entries must be relative to dir (no
	// leading slash, no ".." escape); implementations reject escape
	// attempts. Overwrites existing files. Unknown handle is a hard error.
	// NEVER touches state.Blobs.
	WriteTreeAt(ctx context.Context, h Handle, dir string, tarGz []byte) error

	// Snapshot captures the handle's filesystem as a CoW diff. Only meaningful
	// for snapshot:workspace containers (spec §3). Phase 2 fake: returns
	// ("", ErrUnsupported). Phase 4 Docker (slice 4.4): streaming gzip-tar
	// diff via ContainerDiff + per-path CopyFromContainer through
	// state.Blobs.Put. Returns a 3-segment SnapshotRef:
	//     <state-blobs-ref>@<image-ref>@<base64-json-of-cmd-entrypoint>
	// so Restore can ContainerCreate against the source image AND faithfully
	// re-apply the effective Cmd/Entrypoint (a Restore→Snapshot loop
	// preserves runtime config across the round-trip).
	//
	// Peak memory: bounded by snapshotMaxBlobBytes at state.Blobs.Put time
	// (the compressed blob lives in memory for the Put call; the streaming
	// gzip+tar intermediate buffers stay at ~64 KiB throughout the build).
	//
	// If the gzip-compressed diff exceeds the configured cap (default 256
	// MiB), returns *ErrSnapshotTooLarge — the engine routes this as
	// permanent_failure.
	Snapshot(ctx context.Context, h Handle) (SnapshotRef, error)

	// Restore rebuilds a handle from a prior Snapshot. The name argument is the
	// IR-declared container name (spec §3); the returned Handle.Name is set to
	// it so the dispatcher's d.Handles[name] keys consistently across
	// pre-snapshot Create and post-resume Restore.
	//
	// Phase 2 fake: returns ErrUnsupported.
	//
	// Phase 4 Docker (slice 4.4): parses the 3-segment SnapshotRef, Blobs.Get
	// the diff-tar, ContainerCreate against the embedded image + Cmd +
	// Entrypoint, stream-CopyToContainer the data entries via io.Pipe (peak
	// memory ~64 KiB + the diff blob bytes already in RAM from Get),
	// Exec "rm -rf -- '<path>'" for each .awf-deletes entry. waitReady runs
	// on the restored container so the spec §3 readiness contract holds.
	// The embedded image is NOT auto-pulled; callers responsible for prior
	// ImagePull (same as Backend.Create's image-mode path).
	Restore(ctx context.Context, ref SnapshotRef, name string) (Handle, error)

	// Destroy releases the handle's resources. The caller must call Destroy
	// exactly once per Create; a second call returns an error (the handle is
	// gone). Matches os.File.Close and Docker's ContainerRemove behavior;
	// io.Closer itself leaves post-first-call behavior undefined, but the
	// engine relies on the stricter "error on double" guarantee to surface
	// dispatcher bugs.
	Destroy(ctx context.Context, h Handle) error
}

type Caps struct {
	Snapshot SnapshotMode

	// RuntimeImage reports whether the backend can honor a map's runtime-
	// resolved per-element image: (P6a) — i.e. actually boot the rendered
	// image and report its content digest. Zero-value false FAILS CLOSED:
	// a backend that ignores image: (native) advertises false, and the CLI
	// guard rejects a runtime-image workflow on it rather than silently
	// running bodies on the host.
	RuntimeImage bool

	// RuntimeCompose reports whether the backend can promote compose bytes
	// generated during a workflow run into a managed project with normal
	// lifecycle ownership. Zero-value false FAILS CLOSED: native cannot honor
	// compose projects and must be rejected before execution.
	RuntimeCompose bool

	// StagingRoot is the directory under which the engine stages reduce
	// manifests, branch artifacts, and react tool-call args files inside
	// the step's container (or workdir, for native). Docker value:
	// "/work/.awf" (an absolute in-container path). Native value: ".awf"
	// (workdir-relative — native.CopyTo joins relative paths to the
	// container's workdir). The engine exposes this to the reducer's shell
	// via the AWF_STAGING_ROOT env var so the author's run: can reference
	// staged files portably.
	StagingRoot string
}

type CapturedFile struct {
	Path    string
	Content []byte
}

type Cmd struct {
	Run string
	Env map[string]string
}

type ContainerResources struct {
	CPU string
	Mem string
}

type ContainerSpec struct {
	Name string

	// Image-mode fields.
	Image     string
	Resources *ContainerResources
	// Cmd is an optional override for the image's CMD instruction. When
	// nil or empty, the image's default Cmd applies. Slice 4.4 adds this
	// field so test fixtures can inject a long-running entrypoint into
	// short-CMD images (e.g., alpine's /bin/sh → sleep infinity) without
	// bypassing Backend.Create. Populated from ir.Container.Cmd by
	// engine.ContainerSpecFor (image-mode arm).
	Cmd []string

	// DisableKeepalive opts out of keepalive injection for this container.
	// Zero value (false) means "inject keepalive if needed" — the safe
	// default that preserves existing behaviour for all callers (tests,
	// map P6a, etc.) that construct ContainerSpec without setting this
	// field. Set to true only when the IR Container explicitly sets
	// keepalive: false. The docker backend (Task 3) reads !DisableKeepalive
	// to decide whether to inject a long-running CMD.
	DisableKeepalive bool

	// PullIfAbsent requests that Create ensure Image is present in the local
	// cache before starting it — image-mode only (P6a). The engine sets it
	// solely for a map's runtime-resolved per-element image: (engine/map.go),
	// where the image is learned at dispatch and is generally not pre-pulled.
	// Statically-declared containers leave it false: they are pre-provisioned
	// from a validator-pinned (digest) image, so the run-start pre-pull suffices.
	//
	// Because a runtime-resolved image cannot be validator-pinned, a backend
	// honoring this flag MUST require Image to be digest-pinned (name@sha256:…)
	// so the booted bytes are content-addressed and resume-reproducible, and
	// MUST report the booted digest on Handle.ResolvedImageDigest. The Docker
	// backend implements this; backends that ignore image: (native) advertise
	// Caps.RuntimeImage=false and are rejected by the CLI guard before dispatch.
	PullIfAbsent bool

	// Compose-mode fields (slice 4.3).
	Compose     []byte
	ComposePath string
	Service     string
}

type ExecResult struct {
	ExitCode  int
	AWFOutput []byte
	Stdout    []byte
	// Err (slice 5.3) surfaces transport-class errors that occurred AFTER
	// Backend.Exec successfully launched the process — stdcopy mid-stream
	// failure (docker), pipe-read failure (native), ctx-cancel during
	// in-flight read. nil on the happy path. Pre-slice-5.3 these came back
	// via Backend.Exec's err return; the streaming refactor moved them
	// here so the result channel can carry them without the function
	// returning early before chunks drain.
	Err error
}

type Fake struct {

	// Calls is the defensive-copied history of every Cmd this fake's Exec
	// received. Slice 2.4 (and later) tests inspect this to verify the
	// dispatcher's env-injection contract (AWF_IDEMPOTENCY_KEY per AWF §10).
	// The fake's doc-comment anticipated this need at slice-2.2 time but
	// shipped no mechanism; this is the recording slot.
	Calls []Cmd

	// CreateSpecs records every ContainerSpec passed to Create, in order
	// (test assertion aid — mirrors Calls for Exec). The P6a wiring test reads
	// PullIfAbsent / Image off it to verify the engine flags a map's
	// runtime-resolved image spec for the backend to pull. Shallow copies: the
	// recorded scalars (Name/Image/PullIfAbsent) are what tests assert on.
	CreateSpecs []ContainerSpec

	// ExecHandles records the Handle value passed to each Exec call. Tests use
	// this to assert compose service overrides (`container: lab:api`) reached
	// the backend as a handle-level Service override.
	ExecHandles []Handle

	// DestroyCalls records every Handle passed to Destroy, in order.
	DestroyCalls []Handle

	// RestoreCalls records every Restore invocation, in order (test assertion
	// aid — mirrors Calls for Exec).
	RestoreCalls []RestoreCall

	// WriteFileAtCalls records every WriteFileAt invocation, in order (test
	// assertion aid — mirrors RestoreCalls).
	WriteFileAtCalls []WriteFileAtCall

	// WriteTreeAtCalls records every WriteTreeAt invocation, in order (test
	// assertion aid — mirrors WriteFileAtCalls; used to observe session-subtree
	// restores).
	WriteTreeAtCalls []WriteTreeAtCall
	// contains filtered or unexported fields
}

type Handle struct {
	Name    string
	ID      string
	Service string

	// ResolvedImageDigest is the content digest of the image that actually
	// booted (P6a) — set by Create when the image was runtime-resolved (a map's
	// per-element image:). Empty for statically-pinned containers and backends
	// that don't resolve a digest (native). The engine records it on the
	// element's map.item commit so resume has a durable record of what booted.
	ResolvedImageDigest string
}

type IOChunk struct {
	Stream string
	Data   []byte
}

type ImageUnavailableError struct {
	Image string
	Err   error
}

type InputFile struct {
	Path    string
	Content []byte
}

type RestoreCall struct {
	Name string
	Ref  SnapshotRef
}

type SnapshotMode string

type SnapshotRef string

type WorkdirResolver interface {
	// ResolveWorkdirPath returns the absolute host path for rel (a
	// workdir-relative staging path) under the handle's working directory.
	// If the handle is unknown (defensive), rel is returned unchanged — callers
	// must not rely on an error return; the method never panics.
	ResolveWorkdirPath(h Handle, rel string) string
}

type WriteFileAtCall struct {
	Path    string
	Content []byte
}

type WriteTreeAtCall struct {
	Dir     string
	Content []byte
}