workspace

type Capabilities struct {
	// AtomicRename is true when [Workspace.Rename] succeeds or
	// fails as a single observable operation; readers never see a
	// half-renamed state. POSIX rename(2) on the same filesystem
	// satisfies this. Object stores that emulate Rename as
	// copy+delete do not.
	AtomicRename bool

	// ReadAfterWrite is true when a successful [Workspace.Write]
	// or [Workspace.Append] is immediately observable to a
	// subsequent [Workspace.Read] / [Workspace.List] /
	// [Workspace.Exists] / [Workspace.Stat] from the same client.
	// Strongly-consistent stores (local filesystem, sufficiently
	// recent S3) are true; eventually-consistent stores are false.
	ReadAfterWrite bool

	// DurableOnWrite is true when a successful Write hits stable
	// storage before returning. Implementations that only buffer
	// in user-space (in-memory mocks, write-back caches) report
	// false. Adapters that own crash-recovery logic (WAL replay,
	// manifest swap) read this to decide whether to perform extra
	// flush operations themselves.
	DurableOnWrite bool

	// Distributed is true when more than one process or host can
	// be opened against the same workspace concurrently. Single-
	// process backends (in-memory map, exclusive local directory)
	// report false; cluster file systems and object stores report
	// true. Coordinators use this to choose between a process-
	// local mutex and a distributed lock primitive.
	Distributed bool
}

type CapabilityReporter interface {
	Capabilities() Capabilities
}

type CommandOption func(*LocalCommandRunner)

type CommandRunner interface {
	Exec(ctx context.Context, cmd string, args []string, opts ExecOptions) (*ExecResult, error)
}

type ExecOptions struct {
	WorkDir string
	Env     map[string]string
	Stdin   []byte
	Timeout time.Duration
}

type ExecResult struct {
	ExitCode int    `json:"exit_code"`
	Stdout   string `json:"stdout"`
	Stderr   string `json:"stderr"`
}

type GitWorkspace interface {
	Workspace
	GitClone(ctx context.Context, url, dest string) error
	GitPull(ctx context.Context, dir string) error
	GitHead(ctx context.Context, dir string) (string, error)
}

type LocalCommandRunner struct {
	// contains filtered or unexported fields
}

type LocalWorkspace struct {
	// contains filtered or unexported fields
}

type MemWorkspace struct {
	// contains filtered or unexported fields
}

type NoopCommandRunner struct{}

type ScopedCommandRunner struct {
	// contains filtered or unexported fields
}

type ScopedGitWorkspace struct {
	*ScopedWorkspace
	// contains filtered or unexported fields
}

type ScopedOption func(*ScopedWorkspace)

type ScopedWorkspace struct {
	// contains filtered or unexported fields
}

type ViolationLogger interface {
	LogViolation(ctx context.Context, record ViolationRecord)
}

type ViolationRecord struct {
	Time      time.Time `json:"time"`
	Operation string    `json:"operation"`
	Path      string    `json:"path"`
	Reason    string    `json:"reason"`
}

type WalkFunc func(path string, entry fs.DirEntry) error

type Workspace interface {
	Read(ctx context.Context, path string) ([]byte, error)
	Write(ctx context.Context, path string, data []byte) error
	Append(ctx context.Context, path string, data []byte) error
	// Rename moves src to dst within the same workspace. Implementations
	// MUST be atomic when the underlying medium supports it (e.g. POSIX
	// rename(2) on a local filesystem). When the medium cannot rename
	// atomically (e.g. object stores) the implementation MAY fall back
	// to copy + delete, but callers should treat Rename as the canonical
	// "publish a finalized payload" operation: write to a tmp path then
	// Rename to the live path so readers never observe a half-written file.
	//
	// Returns ErrNotFound if src does not exist. Overwriting an existing
	// dst is allowed; on local filesystems this is atomic.
	Rename(ctx context.Context, src, dst string) error
	Delete(ctx context.Context, path string) error
	RemoveAll(ctx context.Context, path string) error
	List(ctx context.Context, dir string) ([]fs.DirEntry, error)
	Exists(ctx context.Context, path string) (bool, error)
	Stat(ctx context.Context, path string) (fs.FileInfo, error)
}