fix: resolve 8 remaining design-decision audit items

Fixes (4 items):
  S4 — Add TypeScript, Deno, Bun cache ecosystems to
       cacheVolumesByEcosystem. TypeScript shares node+pnpm volumes;
       Deno and Bun get dedicated cache volumes.
  R4 — Share single Docker client between container.Pool and
       storage.DockerBackend. NewPool now accepts an optional
       DockerClient in Config; if nil, creates its own. Pool
       tracks ownership (ownCli) and only closes its own client.
  S2 — Wire Storage.Teardown() call in daemon.process() after
       workflow.Run(). Docker backend is a no-op; this closes the
       interface contract for future backends.
  R5 — Emit observability event on AugmentRegistry failure.
       Previously only logged a warning; now emits a
       'registry_augment_failed' event with error detail.
       Promoted log level to Error.

Documentation (4 items):
  D1 — Document PluginRegistry as reserved for future daemon
       extension points (forge resolvers, storage backends, etc.)
  S1 — Fix /data/ layout comment to reflect actual task.json path
       (/data/worktree/task.json, not /data/task.json)
  S3 — Add TODO(PRD §3) for session.jsonl, memory.jsonl, plugins/
       volume — these need agent-side implementation first
  N6 — Document that VolumeInspectOptions{} requires moby v25+
       (go.mod pins compatible version)
  N7 — Document that _Plugin.IValue is required by Yaegi interface
       bridging; warn that go generate strips nil-guards

Test: TestCacheMountsForTypeScript verifies typescript ecosystem
returns node+pnpm volumes sorted by destination.

Verification: single client.New(client.FromEnv) in main.go;
all 21 storage tests pass; full suite green.
This commit is contained in:
sam committed 2026-07-22 05:00:37 +10:00
1 parent 8a8e676bd6
commit fd360fcc0b
7 files changed
+106 -17

No files matched your search

+10 -7
View File
@@ -129,11 +129,20 @@ func run() int {
var containerPool *container.Pool
var storeBackend storage.Backend
if cfg.Containers.Enabled {
// Single Docker client shared between pool and storage backend.
dockerCli, err := client.New(client.FromEnv)
if err != nil {
log.Error("docker client failed", "err", err)
return 1
}
defer dockerCli.Close()
containerPool, err = container.NewPool(ctx, container.Config{
Image: cfg.Containers.Image,
Image: cfg.Containers.Image,
MaxConcurrency: cfg.Containers.MaxConcurrency,
MaxUptime: cfg.Containers.MaxUptime.Std(),
PullPolicy: cfg.Containers.PullPolicy,
DockerClient: dockerCli,
}, cfg.NATS.URL, log)
if err != nil {
log.Error("container pool failed", "err", err)
@@ -141,12 +150,6 @@ func run() int {
}
defer containerPool.Close()
// Storage backend — Docker volume management for cache mounts.
dockerCli, err := client.New(client.FromEnv)
if err != nil {
log.Error("docker client for storage failed", "err", err)
return 1
}
storeBackend = storage.NewDockerBackend(dockerCli)
}
+23 -6
View File
@@ -56,6 +56,7 @@ func WriteTaskJSON(workspace string, payload TaskPayload) error {
// Pool manages a set of Docker containers running archie-agent.
type Pool struct {
cli *client.Client
ownCli bool // true when the pool created the client (owns Close)
cfg Config
log *slog.Logger
natsURL string
@@ -75,15 +76,26 @@ type Config struct {
// container is killed. The agent stays alive to handle follow-ups
// (gate re-runs, human replies) during this window. PRD §1.
GracePeriod time.Duration
PullPolicy string
PullPolicy string
// DockerClient is an optional pre-connected Docker client. When nil,
// NewPool creates its own via client.New(client.FromEnv). Pass a
// shared client to avoid multiple independent connections.
DockerClient *client.Client
}
// NewPool connects to the Docker daemon, optionally pulls the image,
// and cleans up orphaned containers from a previous daemon crash.
//
// If cfg.DockerClient is set, it is reused (caller owns Close).
// Otherwise a new client is created via client.FromEnv (pool owns Close).
func NewPool(ctx context.Context, cfg Config, natsURL string, log *slog.Logger) (*Pool, error) {
cli, err := client.New(client.FromEnv)
if err != nil {
return nil, fmt.Errorf("docker client: %w", err)
cli := cfg.DockerClient
if cli == nil {
var err error
cli, err = client.New(client.FromEnv)
if err != nil {
return nil, fmt.Errorf("docker client: %w", err)
}
}
p := &Pool{
@@ -91,6 +103,7 @@ func NewPool(ctx context.Context, cfg Config, natsURL string, log *slog.Logger)
cfg: cfg,
log: log,
natsURL: natsURL,
ownCli: cfg.DockerClient == nil,
}
// Pull image if needed.
@@ -191,7 +204,8 @@ func (p *Pool) Release(c *Container) {
p.log.Info("container released", "id", c.ID[:12])
}
// Close stops and removes all active containers, then closes the client.
// Close stops and removes all active containers. If the pool created its
// own Docker client, it is closed. Shared clients are not closed.
func (p *Pool) Close() error {
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
@@ -209,7 +223,10 @@ func (p *Pool) Close() error {
p.cli.ContainerRemove(ctx, c.ID, client.ContainerRemoveOptions{Force: true})
}
}
return p.cli.Close()
if p.ownCli {
return p.cli.Close()
}
return nil
}
// ── helpers ──────────────────────────────────────────────────────────
+22 -1
View File
@@ -53,6 +53,10 @@ type Daemon struct {
Storage storage.Backend
// PluginRegistry holds core daemon plugins loaded from the configured
// plugin_dir at startup (Layer 2). Nil when no plugin_dir is configured.
//
// Reserved for future daemon extension points (forge resolvers, storage
// backends, notification handlers). Loaded plugins are logged at startup;
// the registry is available when extension point interfaces are defined.
PluginRegistry *plugin.Registry
// CustomStages discovers a repo's per-repo Yaegi custom stages
// (.archie/stages/*.go) from its prepared worktree. Set by the
@@ -498,7 +502,12 @@ func (d *Daemon) process(ctx context.Context, task *store.Task) {
if _, err := os.Stat(workDir); err == nil {
aug, err := skillbuild.AugmentRegistry(workDir, d.Workflows)
if err != nil {
d.Log.Warn("worktree registry augmentation failed — using startup registry", "dir", workDir, "err", err)
d.Log.Error("worktree registry augmentation failed — using startup registry", "dir", workDir, "err", err)
d.emit(events.Event{
Kind: "registry_augment_failed", TaskID: task.ID,
Repo: task.Owner + "/" + task.Repo, Issue: task.IssueNumber,
Detail: err.Error(),
})
} else {
registry = aug
}
@@ -565,6 +574,18 @@ func (d *Daemon) process(ctx context.Context, task *store.Task) {
Log: d.Log,
CustomStages: d.CustomStages,
})
// Teardown storage after workflow completes. The Docker backend is a
// no-op; future backends (temp volumes, NFS leases) use this hook.
if d.Storage != nil {
_ = d.Storage.Teardown(ctx, storage.TaskRef{
WorktreeDir: workDir,
Ecosystem: repo.Ecosystem,
PersistentStorage: repo.PersistentStorage,
Owner: task.Owner,
Repo: task.Repo,
})
}
}
// containerEnv returns the environment variables passed to agent containers.
@@ -22,6 +22,9 @@ func init() {
}
// _github_com_samcharles93_archie_core_internal_plugin_Plugin is an interface wrapper for Plugin type
// generated by 'yaegi extract'. IValue is required by Yaegi's interface bridging —
// it holds the underlying concrete value for the interpreter's type system even
// though Name()/Version() delegate to the function fields. Do not remove.
type _github_com_samcharles93_archie_core_internal_plugin_Plugin struct {
IValue interface{}
WName func() string
@@ -1,6 +1,12 @@
// Package pluginextract holds the Yaegi symbol table for internal/plugin,
// generated by `go generate`. Kept separate from internal/plugin itself
// so the generated file can import it without a self-import cycle.
//
// IMPORTANT: Running `go generate` overwrites the generated file with
// Yaegi's default wrapper which does NOT include nil-guards on function
// fields. The `TestGeneratedWrapperHasNilGuards` test catches this if
// regeneration strips the guards. Re-apply nil-guards manually after
// regeneration until Yaegi supports generating them natively.
package pluginextract
import "reflect"
+24 -3
View File
@@ -2,18 +2,27 @@
// container execution. The Docker backend (DockerBackend) is the MVP
// implementation — no NFS/SMB/S3 yet, just Docker volumes + bind mounts.
//
// /data/ volume layout:
// /data/ volume layout (implemented):
//
// /data/
// task.json — boot-time brief (written by container.WriteTaskJSON)
// task.json — at /data/worktree/task.json (WriteTaskJSON writes
// to the worktree root, which is bind-mounted)
// worktree/ — bind mount of host worktree
// repo/ — per-repo persistent volume (optional, on request)
// cache/
// go/ — GOMODCACHE (shared across all tasks)
// node/ — npm cache (shared)
// pnpm/ — pnpm store (shared)
// deno/ — Deno module cache (shared)
// bun/ — Bun package cache (shared)
// pip/ — pip cache (shared)
// cargo/ — Rust cargo cache (shared)
// plugins/ — skill plugins staged from worktree
//
// TODO(PRD §3): session.jsonl, memory.jsonl, plugins/ volume — these
// require agent-side implementation before the storage layer can mount
// them. session.jsonl needs per-stage structured output from the agent;
// memory.jsonl needs cross-session persistence; plugins/ needs daemon-
// staged bundled plugins.
//
// Cache volumes are named Docker volumes created once and shared across all
// tasks. They are never deleted — the daemon operator manages them.
@@ -81,6 +90,16 @@ var cacheVolumesByEcosystem = map[string][]cacheVolume{
{Name: "archie-cache-node", MountPath: "/data/cache/node"},
{Name: "archie-cache-pnpm", MountPath: "/data/cache/pnpm"},
},
"typescript": {
{Name: "archie-cache-node", MountPath: "/data/cache/node"},
{Name: "archie-cache-pnpm", MountPath: "/data/cache/pnpm"},
},
"deno": {
{Name: "archie-cache-deno", MountPath: "/data/cache/deno"},
},
"bun": {
{Name: "archie-cache-bun", MountPath: "/data/cache/bun"},
},
"python": {
{Name: "archie-cache-pip", MountPath: "/data/cache/pip"},
},
@@ -149,6 +168,8 @@ func (d *DockerBackend) ensureVolume(ctx context.Context, name string) error {
if d.cli == nil {
return nil // nil client for testing — volumes must be pre-created
}
// VolumeInspectOptions{} is the empty struct form (requires moby v25+).
// The go.mod pins a compatible version; zero value is always valid.
_, err := d.cli.VolumeInspect(ctx, name, client.VolumeInspectOptions{})
if err == nil {
return nil // already exists
+18
View File
@@ -369,6 +369,24 @@ func TestRepoVolumeName(t *testing.T) {
}
}
func TestCacheMountsForTypeScript(t *testing.T) {
// S4: typescript ecosystem must share node + pnpm cache volumes.
mounts := cacheMounts("typescript")
names := mountDestinations(mounts)
if !contains(names, "/data/cache/node") {
t.Errorf("typescript ecosystem missing /data/cache/node in %v", names)
}
if !contains(names, "/data/cache/pnpm") {
t.Errorf("typescript ecosystem missing /data/cache/pnpm in %v", names)
}
// Must be sorted.
if !sort.SliceIsSorted(mounts, func(i, j int) bool {
return mounts[i].Destination < mounts[j].Destination
}) {
t.Error("typescript cacheMounts not sorted by Destination")
}
}
// ── audit fixes ──────────────────────────────────────────────────────
func TestCacheMountsCaseInsensitive(t *testing.T) {