cache

func (*AmbiguousRefError) Error ¶ added in v0.2.0

func (e *AmbiguousRefError) Error() string

func (ArtifactVersion) ShortBlob ¶ added in v0.4.0

func (v ArtifactVersion) ShortBlob() string

ShortBlob abbreviates the content hash for display. Empty for a symlink record, which has no content of its own.

func (*Cache) Collapsing ¶

func (c *Cache) Collapsing() bool

Collapsing reports whether the cache is withholding per-project subprocess output until failure (collapse-on-success). Callers use it to decide whether to attach a stage observer that prints progress lines for the otherwise-hidden work.

func (*Cache) Delete ¶ added in v0.4.0

func (c *Cache) Delete(ctx context.Context, projectPaths ...string) error

Delete removes cached manifests for the given project paths (all if none given). Orphaned blobs are collected after manifests are deleted.

func (*Cache) Dir ¶ added in v0.2.0

func (c *Cache) Dir() string

Dir returns the cache's root directory. Subsystems that write sibling artifacts next to the cache (the symbol index a `scip` op produces) resolve their paths under it, so those artifacts stay out of the working tree.

func (*Cache) DiskBytes ¶ added in v0.2.0

func (c *Cache) DiskBytes() int64

DiskBytes returns the approximate on-disk size of the cache: the summed file sizes of cas/ (the blob store) and manifests/ (the index), stat-only (no file reads, unlike scanManifests). The result is memoized for diskSizeTTL so it is cheap to poll for a live dashboard. Returns 0 for a dirless cache.

func (*Cache) Evict ¶ added in v0.4.0

func (c *Cache) Evict(ctx context.Context) error

Evict removes LRU entries down to the size cap, then collects unreferenced CAS blobs.

func (*Cache) Export ¶

func (c *Cache) Export(ctx context.Context, w io.Writer) error

Export writes the cache as a gzip-compressed tar archive (paths relative to the cache root, so Import can extract into any target directory).

func (*Cache) GetArtifact ¶ added in v0.4.0

func (c *Cache) GetArtifact(ctx context.Context, v ArtifactVersion, dst string) error

GetArtifact writes v to dst, creating parent directories.

Content is cloned from the store rather than copied where the filesystem supports reflink (APFS, btrfs, XFS), so comparing a large artifact costs almost nothing.

func (*Cache) Import ¶

func (c *Cache) Import(ctx context.Context, r io.Reader) error

Import extracts a gzip-compressed tar archive produced by Export into the cache directory. Existing files are overwritten; entries older than what is on disk are skipped.

func (*Cache) IsCached ¶ added in v0.4.0

func (c *Cache) IsCached(ctx context.Context, s Step) (bool, error)

IsCached reports whether step s would replay from cache rather than run: its inputs hash to a manifest already present locally. It is Run's hash-and-lookup without the execution or the remote fetch - a read-only "is this up to date?" probe (e.g. status reporting whether a project's symbol index reflects current sources). A missing manifest is "not fresh", not an error; only a hashing failure returns one.

func (*Cache) LastEntry ¶

func (c *Cache) LastEntry(projectPath string) (*Manifest, string, error)

LastEntry returns the manifest and log-file path of the most recently created cache entry for projectPath. Returns an error wrapping fs.ErrNotExist when no entries exist for the project.

func (*Cache) LastEntryForTarget ¶

func (c *Cache) LastEntryForTarget(projectPath, target string) (*Manifest, string, error)

LastEntryForTarget returns the manifest and log-file path of the most recently created cache entry for projectPath with the given target. Returns an error wrapping fs.ErrNotExist when no matching entries exist.

func (*Cache) LastRecordedRun ¶ added in v0.4.0

func (c *Cache) LastRecordedRun(projectPath, target string) (RecordedRun, error)

LastRecordedRun returns the most recent entry recorded for target in projectPath, the comparison peer for "why would a run here MISS": its key inputs are what FirstKeyInputChange pairs the live ones against. Charms are deliberately not part of the lookup - an entry recorded under different charms is still the last thing this target stored here, and the charm lines then show up as the difference that explains the miss.

Wraps fs.ErrNotExist when nothing is recorded for that target.

func (*Cache) ListArtifacts ¶ added in v0.4.0

func (c *Cache) ListArtifacts(ctx context.Context, projectPath, wsPath string) ([]ArtifactVersion, error)

ListArtifacts returns every cached version of wsPath, newest first.

wsPath is WORKSPACE-relative, matching how snapshot recorded it and what TargetArtifact.Path carries; it is not relative to projectPath.

Consecutive versions with identical content collapse to one, keeping the earliest of each run: a target that ran twenty times producing the same bytes changed the artifact once, and the question is when content first appeared.

func (*Cache) LogBase ¶ added in v0.4.0

func (c *Cache) LogBase(ctx context.Context, base, vcs string)

LogBase emits what a run's affected set was compared against, beside the projects and charms headers, because it is the third input that decides what runs: the same command against a different base is a different build.

base already reads "git diff vs origin/main" - the VCS name in front of the ref, rather than a git:// URI, because no such scheme is standard across git, Mercurial and jj and inventing one would put a magus-only string where a reader expects a ref they can paste straight back into their own VCS. vcs is accepted for a caller that has the two apart.

func (*Cache) LogCache ¶ added in v0.4.0

func (c *Cache) LogCache(ctx context.Context)

LogCache emits the cache header: which tiers this run can reach and whether it may write to them.

Always printed, including the boring case, because the value is in never having to wonder. "Why was nothing cached" and "am I even talking to the remote" were previously answerable only by reading config and env, and the answer differs per event - a pull request reads the shared cache but must not publish to it, which is invisible unless something says so.

It names the backend rather than probing it. Active() is a spell op on the real implementation - arbitrary Buzz, with the whole host surface - and calling it here put that on the path before the first line of output, where a slow probe stalls the run with nothing on screen to explain the pause. Presence and name are known without asking; whether the backend engages is the run's business, not the header's.

func (*Cache) LogCharms ¶ added in v0.2.0

func (c *Cache) LogCharms(ctx context.Context, charms string)

LogCharms emits the active-charm header (the charms mixed into this run, e.g. the magus.yaml default_charms like `rw`) so the reader sees up front what state the run executes under - and can tell at a glance whether a default charm actually took effect. Routed through the cache logger like LogScope so every format receives it.

func (*Cache) LogDry ¶

func (c *Cache) LogDry(ctx context.Context, project, label, target string)

LogDry emits a per-target dry-run line through the cache logger, in place of the executed pass/fail line. project is the workspace-relative path, carried so the line can print the same repro command an executed one does.

func (*Cache) LogDryBanner ¶

func (c *Cache) LogDryBanner(ctx context.Context)

LogDryBanner emits the one-time dry-run banner through the cache logger.

func (*Cache) LogDrySummary ¶ added in v0.4.0

func (c *Cache) LogDrySummary(ctx context.Context, planned int, elapsed time.Duration)

LogDrySummary emits the end-of-run footer for a dry run: the same cache.summary event a real run ends with, marked dry and carrying what WOULD have run.

It is the same event on purpose. A dry run previously just stopped after its last [dry] line, so the one shape a reader had learned to look for at the bottom of a run - the summary - was missing exactly when they were checking a plan. Reusing cache.summary also means every output format (json, jsonl, template) keeps reporting a footer rather than only the text renderer growing one.

The cache's own counters are not consulted: nothing executed, so they are all zero and would report "0 ran" for a plan that intends to run plenty.

func (*Cache) LogMemoryPressure ¶ added in v0.4.0

func (c *Cache) LogMemoryPressure(ctx context.Context, p MemoryPressure)

LogMemoryPressure warns that the host is running out of memory, routed through the cache logger like every other header.

Warn rather than Info because a killed runner never lets magus reach its summary. Only what magus already streamed survives, and this is the line that explains an otherwise unattributable shutdown signal.

func (*Cache) LogRemoteSummary ¶ added in v0.4.0

func (c *Cache) LogRemoteSummary(ctx context.Context)

LogRemoteSummary accounts for what the remote cache did this run, reading the run-scoped counters off ctx. It is the only place the ZERO case gets stated: a run that never touched a configured remote says so rather than saying nothing, and silence is what made that indistinguishable from working.

func (*Cache) LogScope ¶

func (c *Cache) LogScope(ctx context.Context, label, source string)

LogScope emits the projects header through the cache logger so all output formats (pretty/text/JSON) receive the same event.

func (*Cache) LogStage ¶

func (c *Cache) LogStage(ctx context.Context, label, target string, elapsed time.Duration, runErr error)

LogStage emits a per-stage progress event for one magus.needs sub-target that ran under a project, routed through the cache logger like the other events. In collapse mode (where a project's subprocess output is withheld) these lines give the reader a checklist of what ran and whether it passed; runErr is nil on success.

func (*Cache) LogSummary ¶

func (c *Cache) LogSummary(ctx context.Context, elapsed time.Duration)

LogSummary emits an end-of-run [summary] footer through the cache logger, drawn from the cache's own hit/miss/error counters. Like LogScope it routes through the logger so every output format receives the same event.

func (*Cache) OutputByRef ¶ added in v0.4.0

func (c *Cache) OutputByRef(ctx context.Context, ref string) ([]byte, OutputDescriptor, error)

OutputByRef resolves a ref to its captured bytes and descriptor, consulting the LOCAL store first and then, only if the ref is unknown here, the remote bundle namespace. That order matters: local is authoritative and free, and a remote lookup is a network call no one asked for until the answer is not here. A miss reports which stores were consulted, so "not found" never hides where magus looked.

func (*Cache) Prune ¶

func (c *Cache) Prune(ctx context.Context, cutoff time.Time, dryRun bool) (n int, freed int64, err error)

Prune removes cache entries whose CreatedAt is before cutoff and then GCs orphaned blobs. Returns the count of entries removed and total bytes freed. When dryRun is true no files are deleted; counts are still returned.

func (*Cache) PruneRemote ¶

func (c *Cache) PruneRemote(ctx context.Context, policy RetentionPolicy) error

PruneRemote evicts remote cache artifacts per policy. It errors when no remote backend is configured, when the backend does not implement RemotePruner, or when the backend is inactive in this environment (the same gate fetch/push use, so a misconfigured prune fails loudly instead of silently no-opping).

func (*Cache) PublishOutput ¶ added in v0.4.0

func (c *Cache) PublishOutput(ctx context.Context, ref string) (string, error)

PublishOutput uploads the run behind ref as a signed output bundle, so another machine can resolve that exact ref. Passing runs already travel with the cache artifact; this is what makes a FAILING run shareable, and it is always explicit. It errors when no remote backend is configured, when the backend is inactive, or when the cache holds no signing key (an unsigned bundle no consumer would accept).

func (*Cache) Remote ¶ added in v0.2.0

func (c *Cache) Remote() RemoteBackend

Remote returns the configured remote backend, or nil when local-only. Exposed so subsystems with their own artifacts (the knowledge-graph shard store) can ride the same backend as build artifacts, under the same signing/verification.

func (*Cache) Run ¶

func (c *Cache) Run(ctx context.Context, s Step, fn func(context.Context) error, opts ...RunOption) (Result, error)

Run executes fn under the cache. On a hash match it replays recorded outputs; otherwise fn runs and its outputs are snapshotted. Per-hash locking prevents manifest races when multiple RunAll goroutines share the same key.

// A fresh, private store so the first run is always a cold miss regardless of
// any earlier run or example. t.TempDir is unavailable in an Example, so this
// manages its own temp dir.
dir, err := os.MkdirTemp("", "magus-cache-example-run")
if err != nil {
	fmt.Println("setup:", err)
	return
}
defer os.RemoveAll(dir)

c, err := Open(context.Background(), dir, WithLog("text", slog.LevelError))
if err != nil {
	fmt.Println("open:", err)
	return
}

step := Step{
	ProjectPath:   "api",
	WorkspaceRoot: ".",
	Target:        "build",
}

ran := 0
fn := func(_ context.Context) error {
	ran++
	return nil
}

// First run: cold miss → fn is called.
r1, err := c.Run(context.Background(), step, fn)
if err != nil {
	fmt.Println("run1:", err)
	return
}
fmt.Println("run1 hit:", r1.Hit)

// Second run on the same store: hit → fn is skipped.
r2, err := c.Run(context.Background(), step, fn)
if err != nil {
	fmt.Println("run2:", err)
	return
}
fmt.Println("run2 hit:", r2.Hit)
fmt.Println("fn ran:", ran, "time(s)")

Output:
run1 hit: false
run2 hit: true
fn ran: 1 time(s)

func (*Cache) RunAll ¶

func (c *Cache) RunAll(ctx context.Context, steps []Step, fn func(context.Context, Step) error, opts ...RunOption) ([]Result, error)

RunAll schedules steps concurrently (bounded by WithLimiter, or DefaultConcurrency). Step.DependsOn imposes scheduling order for in-scope steps only; out-of-scope deps are ignored. A cyclic DependsOn graph is rejected before any goroutine launches. Upstream cache keys fold into dependent Step.Deps transitively (happens-before: markDone writes the key before waitForDeps returns in dependents). Every goroutine launches immediately and blocks on deps without holding a slot, so the pool never deadlocks and g.Wait() always drains cleanly.

dir, err := os.MkdirTemp("", "magus-cache-example-runall")
if err != nil {
	fmt.Println("setup:", err)
	return
}
defer os.RemoveAll(dir)

c, err := Open(context.Background(), dir, WithLog("text", slog.LevelError))
if err != nil {
	fmt.Println("open:", err)
	return
}

steps := []Step{
	{ProjectPath: "api", WorkspaceRoot: ".", Target: "test"},
	{ProjectPath: "web", WorkspaceRoot: ".", Target: "test"},
}

var mu sync.Mutex
var missed []string
results, err := c.RunAll(
	context.Background(), steps,
	func(_ context.Context, _ Step) error { return nil },
	WithLimiter(NewLimiter(4)),
	OnMiss(func(r *Result) {
		mu.Lock()
		missed = append(missed, r.ProjectPath)
		mu.Unlock()
	}),
)
if err != nil {
	fmt.Println("runall:", err)
	return
}

sort.Strings(missed)
fmt.Println("results:", len(results))
fmt.Println("missed:", missed)

Output:
results: 2
missed: [api web]

func (*Cache) Stats ¶

func (c *Cache) Stats() Stats

Stats returns a snapshot of the per-cache counters.

func (*Cache) StepKey ¶ added in v0.4.0

func (c *Cache) StepKey(ctx context.Context, s *Step) (key string, lines []string, err error)

StepKey computes s's cache key plus the pre-hash key inputs behind it, without executing or storing anything. It is the SDK seam for the live half of the works-on-my-machine diff: `describe target --cache` keys the step exactly as a run would, then compares these lines against the set stored behind a ref. The returned key is what portable refs truncate, so callers can also predict the ref a run of this step would print.

func (*Cache) StepKeyMemo ¶ added in v0.4.0

func (c *Cache) StepKeyMemo(ctx context.Context, s *Step, memo *SourceMemo) (key string, lines []string, err error)

StepKeyMemo is StepKey with an optional SourceMemo. It exists for a caller that keys MANY steps sharing one WorkspaceRoot in one pass - IdentifyRef's sweep, via ComputeTargetKey - so distinct targets whose buildStep gives them the SAME Sources baseline expand and hash that source set once instead of once per target/charm combination. Pass nil for ordinary StepKey behavior; see SourceMemo's doc for the safety condition on passing a real one.

computeTargetKey (run.go), the implementation behind the `describe target --cache` seam StepKey's own doc describes, calls StepKeyMemo directly rather than through StepKey; only tests exercise StepKey itself.

func (*FSRemoteBackend) Active ¶

func (r *FSRemoteBackend) Active(context.Context) bool

Active reports true: a filesystem backend is usable wherever its dir is.

func (*FSRemoteBackend) GetArtifact ¶

func (r *FSRemoteBackend) GetArtifact(_ context.Context, projectPath, hash string) (io.ReadCloser, error)

GetArtifact opens the artifact file. Returns (nil, nil) when not found.

func (*FSRemoteBackend) Name ¶ added in v0.4.0

func (r *FSRemoteBackend) Name() string

Name identifies this backend in the run header. "fs" rather than the directory: the header names the KIND of tier, and the path is already config the reader can look up.

func (*FSRemoteBackend) PutArtifact ¶

func (r *FSRemoteBackend) PutArtifact(_ context.Context, projectPath, hash string, data io.Reader) error

PutArtifact writes the artifact to the filesystem atomically.

func (*Limiter) Acquire ¶

func (l *Limiter) Acquire(ctx context.Context) error

Acquire blocks until 1 slot is available or ctx is cancelled. Returns ctx.Err() on cancellation.

func (*Limiter) AcquireN ¶

func (l *Limiter) AcquireN(ctx context.Context, n int) error

AcquireN acquires n slots under FIFO fairness. n < 1 is floored to 1 (a defensive guard; every real caller already passes >= 1). A request above capacity can never be satisfied by any wait, so it fails immediately rather than blocking forever; callers decide whether to clamp first (RunAll, where a slot count is a coarse throttle) or surface the error (os.with_slots/archive, where reserving more slots than exist would desync the reservation from the tool's own worker count). Returns ctx.Err() on cancellation.

func (*Limiter) Capacity ¶

func (l *Limiter) Capacity() int

Capacity returns the limiter's slot capacity. 0 means unlimited.

func (*Limiter) Release ¶

func (l *Limiter) Release()

Release frees 1 previously acquired slot.

func (*Limiter) ReleaseN ¶

func (l *Limiter) ReleaseN(n int)

ReleaseN frees n previously acquired slots.

func (*Limiter) SetHooks ¶

func (l *Limiter) SetHooks(onAcquire func(waitNs int64, n int), onRelease func(n int), onWait func(delta int))

SetHooks installs optional callbacks fired on every Acquire/Release. Must not block. Stored atomically so a SetHooks racing with concurrent Acquire/Release is safe.

onWait mirrors the internal queued counter exactly: it fires with +n the instant a caller begins waiting for n slots (before the blocking Acquire) and with -n once that Acquire returns, whether it acquired or the context was cancelled. Net inflight of onWait tracks Limiter.Snapshot's Queued.

func (*Limiter) Snapshot ¶

func (l *Limiter) Snapshot() LimiterStats

Snapshot returns a point-in-time view of the limiter.

func (*Limiter) Yield ¶

func (l *Limiter) Yield(ctx context.Context, fn func() error) error

Yield releases the caller's slots for the duration of fn, then re-acquires them before returning. It releases every slot the caller holds (SlotsHeld(ctx), at least 1): a weighted step holds more than one, and releasing only one would leave it pinning slots that fn's own AcquireN then blocks on forever. The caller MUST hold a slot; a slotless caller would over-release the semaphore. Re-acquire uses a non-cancellable context so the caller always returns with its slots held (RunAll releases unconditionally; a slotless return would panic). The re-acquire re-enters the FIFO queue, so a yielding goroutine goes to the back.

Trade-off: the non-cancellable re-acquire can block a returning yield on a saturated limiter even after ctx is cancelled, slowing shutdown until peers free the slots.

func (LocalAdmitter) Drop ¶ added in v0.4.0

func (l LocalAdmitter) Drop(_ context.Context, waiter string)

func (LocalAdmitter) Release ¶ added in v0.4.0

func (l LocalAdmitter) Release(_ context.Context, id string)

func (LocalAdmitter) Request ¶ added in v0.4.0

func (l LocalAdmitter) Request(_ context.Context, waiter string, c types.MachineClaim) (types.MachineVerdict, error)

func (*MachineBudget) Drop ¶ added in v0.4.0

func (b *MachineBudget) Drop(waiter string)

Drop retires a waiter that gave up, so the queue behind it moves now rather than after machineWaiterStaleAfter.

func (*MachineBudget) Release ¶ added in v0.4.0

func (b *MachineBudget) Release(id string)

Release returns a granted claim. An unknown id is ignored: a client that lost its daemon mid-run releases into a budget that never recorded it.

func (*MachineBudget) Request ¶ added in v0.4.0

func (b *MachineBudget) Request(waiter string, c types.MachineClaim) types.MachineVerdict

Request is one poll for admission on behalf of waiter, an id stable across this step's polls and unique machine-wide. It grants, refuses, or queues, and never blocks: the wait belongs to the client, which is the process that can report it.

func (*MachineBudget) Snapshot ¶ added in v0.4.0

func (b *MachineBudget) Snapshot() types.MachineSnapshot

Snapshot reports the whole budget. Read-only: it retires nothing, so a status command can ask what the machine is doing without moving a queue. Entries whose process is gone are FILTERED rather than deleted, so the report never shows a corpse the next Request would retire anyway.

func (*OutputStore) AdoptImported ¶ added in v0.4.0

func (s *OutputStore) AdoptImported(cacheKey string, output []byte) (string, bool)

AdoptImported completes an execution record that arrived from a remote artifact. An import ships the producer's DESCRIPTOR but not its output blob (the bytes travel once, as the build log), so the attempt is a descriptor with no sibling .out and stays unresolvable. Given the log bytes a cache hit just replayed, this writes that missing blob and returns the step's portable ref - so a fresh machine answers under the SAME ref the producer printed instead of minting a local one. Reports false when the key has no orphan descriptor to complete (nothing imported, or already completed), leaving the caller to persist its own attempt.

func (*OutputStore) Attempts ¶ added in v0.4.0

func (s *OutputStore) Attempts(ref string) ([]OutputDescriptor, error)

Attempts lists every stored execution of the step ref names, newest first - the keep-last-K history behind one portable ref (`magus query output <ref> --attempts`). ref may be the step ref, a unique prefix, or any attempt id within the step; the whole directory answers either way. Pre-portable descriptors carry no Attempt field; their file stem (which was the v1 ref) fills it so every row is addressable. A blob whose descriptor is missing or unreadable (a Persist that died between its two writes) still rows up - minimally, from the blob itself - because a listing that silently omits a retrievable execution reads as "it does not exist".

func (*OutputStore) ByRef ¶ added in v0.2.0

func (s *OutputStore) ByRef(ref string) ([]byte, OutputDescriptor, error)

ByRef resolves a ref (or unique prefix) to the target's VERBATIM captured output bytes plus its metadata. The bytes are read straight from the <ref>.out blob - exactly what the process wrote, no reconstruction. This is the retrieval entry point for `magus query output <ref>` (print path).

func (*OutputStore) DescriptorByRef ¶ added in v0.4.0

func (s *OutputStore) DescriptorByRef(ref string) (OutputDescriptor, error)

DescriptorByRef resolves a ref (or unique prefix) to its stored descriptor alone, without reading the output blob - the identity views (`--identity`, `--against`) want the metadata, and a captured log can be large. A resolvable ref whose descriptor is missing or unreadable yields the error, unlike ByRef, which still has bytes to return and so degrades to a zero descriptor.

func (*OutputStore) InvocationByID ¶ added in v0.2.0

func (s *OutputStore) InvocationByID(inv string) (journal.Invocation, error)

InvocationByID reads the union run log (<cacheDir>/runs/<inv>.jsonl) for one invocation id and rebuilds its header: the command lineage (subcommand/args/trigger), timing, and outcome. It is how a stored output (OutputDescriptor.Inv) is traced back to the run that produced it - `magus query output <ref> --identity` and the viewer surface this lineage. Reads off the cache ROOT (RunsDir), not outputsDir. Returns fs.ErrNotExist when the run log has aged out.

func (*OutputStore) InvocationEventsByID ¶ added in v0.4.0

func (s *OutputStore) InvocationEventsByID(inv string) (journal.Invocation, []journal.Event, error)

InvocationEventsByID reads one invocation's run log and returns its header alongside the EVENTS it was reconstructed from. OutputStore.InvocationByID keeps only the header, which is all a `--identity` line needs; this is for a caller that wants the stream itself.

It exists because the events were being read and discarded: journal.KindSecret records every credential a run reached for, and the docs offer that as the answer to "what did this run touch", but nothing could read it back. Anything answering a question FROM the journal starts here.

inv must be a FULL invocation id - unlike an output ref there is no prefix resolution, because a run log is addressed by exact filename. An id failing LooksLikeInvocationID is refused before it is joined onto the runs dir: this is reachable from the daemon's Connect API, where an unvalidated id reads any .jsonl on the machine. Returns fs.ErrNotExist when the log has aged out under the RotateLogs cap.

func (*OutputStore) InvocationEventsFrom ¶ added in v0.4.0

func (s *OutputStore) InvocationEventsFrom(inv string, from int64) ([]journal.Event, int64, error)

InvocationEventsFrom reads one invocation's journal starting at byte offset from and returns the events on COMPLETE lines plus the offset just past the last one. It is the tailing counterpart to OutputStore.InvocationEventsByID, which reads the file whole.

A journal is appended while its run is still going (journal.FileHandler flushes every kind but output), so a follower resumes from where it stopped instead of re-reading megabytes it has already delivered - which is what keeps watching a long build proportional to what arrived. Stopping at the last newline is what makes a concurrent writer safe to read: a half-written line is left for the next call rather than parsed as corruption.

A file shorter than from means the id was reused after a cache clean, so the read restarts at zero rather than seeking past the end and reporting nothing forever. Returns fs.ErrNotExist when the log never existed, has aged out, or inv is not shaped like an invocation id.

func (*OutputStore) KeyInputsByKey ¶ added in v0.4.0

func (s *OutputStore) KeyInputsByKey(cacheKey string) ([]string, error)

KeyInputsByKey returns the stored pre-hash key inputs for an EXACT cache key, the shape a manifest records. It does not scan the store the way KeyInputsByRef must: a prefix search would be a slower route to the same directory, and it fails outright once the key's attempt blobs have been pruned away while this sidecar remains.

func (*OutputStore) KeyInputsByRef ¶ added in v0.4.0

func (s *OutputStore) KeyInputsByRef(ref string) ([]string, error)

KeyInputsByRef returns the stored pre-hash key inputs behind ref (step ref, unique prefix, or any attempt id within the step). fs.ErrNotExist when the step resolves but predates key input persistence.

func (*OutputStore) LatestRefsByTarget ¶ added in v0.2.0

func (s *OutputStore) LatestRefsByTarget() []OutputDescriptor

LatestRefsByTarget returns the newest stored execution per (project, target): one OutputDescriptor each, the most recent by TimestampMs (ties broken by attempt id, then ref, so the choice is stable regardless of directory iteration order). It scans every cache-key directory's descriptor sidecars. This is what folds each target's last output ref onto its knowledge-graph node without the graph builder parsing the store's on-disk layout.

Descriptors store the REPRO target (bare name plus charm suffix, see reproTarget); this collapses that back to the bare declared target so the newest run is picked across charm variants and Target matches a knowledge-graph node. Descriptors without a target are skipped, as is anything unreadable - fewer entries, never an error. Sorted by project then bare target for deterministic assembly.

func (*OutputStore) ListDescriptors ¶ added in v0.2.0

func (s *OutputStore) ListDescriptors() []OutputDescriptor

ListDescriptors returns every stored execution's descriptor, newest run first, across all cache keys - the feed for the console's run browser (the log-viewer tree groups them project -> target -> run so a reader can browse recent runs and open any one's captured output). Unlike LatestRefsByTarget, which collapses to the single newest run per target, this keeps every retained execution (the store holds keep-last-K per cache key), so a target's recent history is browsable. The REPRO target is preserved verbatim (with any charm suffix) so a run's exact invocation stays visible; the caller collapses to the bare name for grouping if it wants. Best-effort: an absent or unreadable store, or an undecodable descriptor, yields fewer entries, never an error.

func (*OutputStore) ListRunLogs ¶ added in v0.4.0

func (s *OutputStore) ListRunLogs(limit int) []RunLog

ListRunLogs returns the newest retained invocation journals, newest first by modtime, capped at limit (limit <= 0 returns every retained one). It is the run browser's feed and the invocation-addressed counterpart to OutputStore.ListDescriptors, which lists stored OUTPUTS.

Cost is bounded per journal, not per event: a head read for the started event and a tail read for the finished one. A run killed before it finished has no finished event, so its Status is empty and FinishedMs falls back to the last event the tail window holds - the same honest degradation journal.InvocationFromEvents makes.

Best-effort throughout: an unreadable dir, an unparsable line, or a journal whose head is not a started event yields fewer rows, never an error.

func (*OutputStore) Persist ¶ added in v0.2.0

func (s *OutputStore) Persist(ctx context.Context, cacheKey string, output []byte, d OutputDescriptor) (OutputDescriptor, error)

Persist writes the execution's captured output VERBATIM as outputs/<cacheKey>/<attempt>.out (byte-for-byte what the process wrote, so `magus query output <ref>` is a straight read - never a reconstruction) plus an <attempt>.json descriptor, then prunes the cache key's directory to keep-last-K. Per-line structured events are NOT stored here - they live in the invocation journal, so no output is stored twice. Returns the descriptor as stamped and stored: Ref is the step's portable ref (shared by every attempt of this key), Attempt the execution-unique id that names the files just written. Best-effort at the call site: on error the caller keeps the run's own outcome.

func (*OutputStore) PersistKeyInputs ¶ added in v0.4.0

func (s *OutputStore) PersistKeyInputs(ctx context.Context, cacheKey string, inputs []string) error

PersistKeyInputs writes the step's pre-hash key inputs beside its attempts, env values digested (DigestEnvValues) and the result secret-redacted line-by-line as a second net for non-env classes. One file per cache key: the lines are a property of the KEY, so later attempts of the same step overwrite with identical content. Best-effort at the call site: an error just means a later --identity/--against has no lines to explain with.

func (*OutputStore) RotateRuns ¶ added in v0.2.0

func (s *OutputStore) RotateRuns(keepLast int, keepBytes int64) (removed int, bytesFreed int64)

RotateRuns keeps the newest invocation journals (runs/<inv>.jsonl, by modtime) and removes the rest, returning how many it deleted and the bytes that freed. The runs dir is flat (one file per invocation, not keyed like outputs/), so this is a single keep-last over the whole directory - the run-log analogue of pruneKey, and the worker behind the rotate-logs job.

TWO caps, and the tighter one wins. keepLast bounds the COUNT; keepBytes bounds the total on disk. Count alone does not bound anything: a journal holds every output line of its run, so its size is whatever the subprocess printed, and 500 of them is 500 times an unbounded number. A run that emits a gigabyte earns a gigabyte.

Best-effort: an unreadable dir or a failed remove is skipped, never fatal. keepLast <= 0 is a no-op (never wipe the whole dir by accident), and keepBytes <= 0 means no size cap.

func (*OutputStore) RunsStat ¶ added in v0.2.0

func (s *OutputStore) RunsStat() (bytes int64, count int64)

RunsStat reports the invocation-journal directory's current footprint: total bytes across every runs/<inv>.jsonl and the number of such files. Best-effort and read-only; a missing dir is (0, 0). It is what the RotateLogs job reports as its target size.

func (*OutputStore) StepRef ¶ added in v0.4.0

func (s *OutputStore) StepRef(cacheKey string) string

StepRef returns the step's portable ref when at least one execution is stored for cacheKey, or "" if none. A cache HIT reuses it instead of re-persisting identical output under a fresh attempt - so hits point at the existing events, not bloat the store. Pre-portable directories qualify too: the ref derives from the key, not from what any stored descriptor says.

func (*PrettyHandler) Close ¶ added in v0.4.0

func (h *PrettyHandler) Close() error

Close releases the sticky error region if one was reserved. Idempotent and safe to defer; required so a panic or interrupted run does not leave the terminal with the scroll margins still set. The next non-magus command the user runs inherits a clean terminal state.

func (*PrettyHandler) Enabled ¶ added in v0.4.0

func (h *PrettyHandler) Enabled(_ context.Context, lvl slog.Level) bool

Enabled reports whether a level is worth handling. slog calls it from every logging goroutine, and setLevel writes h.level under the mutex, so this reads it under the mutex too.

func (*PrettyHandler) Failures ¶ added in v0.4.0

func (h *PrettyHandler) Failures() []Failure

Failures returns the failures currently pinned in the band, in the order they are DRAWN, skipping empty slots. It is the keyboard counterpart to HitFailure: a caller offering "select with the arrow keys" needs the list, not a row.

Drawn order, not arrival order. The ring keeps a failure in the row it was painted into, so once it has wrapped the oldest entry sits in the middle - and the list has to match the screen, because a reader picks by position.

func (*PrettyHandler) Handle ¶ added in v0.4.0

func (h *PrettyHandler) Handle(ctx context.Context, r slog.Record) error

Handle renders one record. It deliberately does NOT skip on ctx.Err(): a handler must not treat cancellation as permission to drop output. The check that used to live here was inert for as long as it existed, because every call site reached slog through Logger.Info/Warn/..., which passes context.Background() - Err() was never non-nil. Once the run path started passing its REAL context (so records could reach the secret resolver), it woke up and began eating exactly the lines that matter most: in a concurrent run, the first failure cancels the errgroup, and every [pass]/[fail] that finished afterwards, plus the [summary] footer and the Ctrl-C service-release warning, vanished from the default output while -o json still showed them.

func (*PrettyHandler) HitFailure ¶ added in v0.4.0

func (h *PrettyHandler) HitFailure(row int) (Failure, bool)

HitFailure maps an absolute terminal row to the failure drawn on it.

The handler answers this rather than exposing its band layout, because the layout is its own business: the status line owns the first row and the ring owns the rest, and a caller that had to know that would be a second copy of the arrangement waiting to drift. Callers pass the Row from a mouse event straight through.

Reports false for the status row, for an empty ring slot, and for any row outside this handler's band - including a click on another consumer's rows.

func (*PrettyHandler) ReleaseBand ¶ added in v0.4.0

func (h *PrettyHandler) ReleaseBand() error

ReleaseBand hands this handler's rows back, for a caller that held them past the end of a run to offer an interactive prompt over the pinned failures.

func (*PrettyHandler) RendersBand ¶ added in v0.4.0

func (h *PrettyHandler) RendersBand() bool

RendersBand reports whether this handler has a live band to paint into. The cache asks before emitting pool samples, so a piped, JSON, or CI run pays nothing for a feature it cannot show, and the CLI asks before offering an interactive prompt over failures it may not have drawn.

Not named Enabled: that one belongs to slog.Handler and answers an entirely different question (whether a level is worth handling).

func (*PrettyHandler) SetFocus ¶ added in v0.4.0

func (h *PrettyHandler) SetFocus(f PaneFocus)

SetFocus moves focus between the two views, which resizes them: the focused one takes the golden ratio's major share.

Resizing on focus rather than offering a drag handle is deliberate - there is no pointer contract to invent, and the pane you are working in is the one that should be big.

func (*PrettyHandler) SetPreview ¶ added in v0.4.0

func (h *PrettyHandler) SetPreview(lines []string)

SetPreview gives the band a right-hand column: the captured output of whatever is selected. Nil or empty returns it to a single column.

This is the "two views, one run" surface. It is deliberately not two PANES - nothing here manages a terminal, and a caller cannot put arbitrary content in it. Both columns are things this handler already owns, which is the line between showing a reader their run and becoming a multiplexer.

func (*PrettyHandler) SetSelection ¶ added in v0.4.0

func (h *PrettyHandler) SetSelection(n int)

SetSelection highlights the nth pinned failure, counting only the occupied slots that PrettyHandler.Failures returns. A negative n clears it.

Selection lives here rather than in the prompt for the reason the band does: this repaints on a timer, so a highlight painted from outside would be erased by the next status tick.

func (*PrettyHandler) ToggleFocus ¶ added in v0.4.0

func (h *PrettyHandler) ToggleFocus() PaneFocus

ToggleFocus swaps which view has the major share, and reports the new focus.

func (*PrettyHandler) WithAttrs ¶ added in v0.4.0

func (h *PrettyHandler) WithAttrs(_ []slog.Attr) slog.Handler

func (*PrettyHandler) WithGroup ¶ added in v0.4.0

func (h *PrettyHandler) WithGroup(_ string) slog.Handler

func (*PrettyHandler) Zone ¶ added in v0.4.0

func (h *PrettyHandler) Zone() *tty.Zone

Zone returns the terminal owner this handler paints its band into.

Exposed so a second consumer can lease rows from the SAME owner: the failure prompt puts its instruction row directly beneath the band, and two zones over one terminal each compute their margins from their own row arithmetic and overwrite each other - the exact failure tty.Zone exists to prevent. In production both sides reach the same singleton through standard error and the sharing is invisible; for any other writer it has to be asked for.

func (RecordedRun) WouldReplay ¶ added in v0.4.0

func (r RecordedRun) WouldReplay(key string) bool

WouldReplay reports whether a run whose cache key is key would replay a stored entry here instead of executing: a manifest sits at that exact key and passes the gates a hit applies (key, project, platform).

The entry it finds need not be this one. RecordedRun.Key names only the NEWEST entry, so an edit followed by a revert leaves Key pointing at the edited run while the key a run now mints belongs to an older entry that still hits - and that is the case a verdict read off the newest entry alone gets wrong.

False on a zero RecordedRun and on an empty key.

func (*RefNotFoundError) Error ¶ added in v0.4.0

func (e *RefNotFoundError) Error() string

func (*RefNotFoundError) Is ¶ added in v0.4.0

func (e *RefNotFoundError) Is(target error) bool

Is reports RefNotFoundError as fs.ErrNotExist, so existing not-found handling (the CLI's MGS8001 path) keeps working while the message gains the store list.

func (Stalled) AvgMs ¶ added in v0.4.0

func (s Stalled) AvgMs() int64

AvgMs is the mean execution time across Runs.