feat(dashboard/contract): slice (k) audit storage + live audit.tail subscription

Closes two related gaps:

1. The audit emitter (slice b) wrote to stdout/Logger and disappeared. There
   was no way for the dashboard to surface audited commands.
2. The audit.tail vocabulary intent + React component (slice e) had no
   matching server-side handler — clicking the audit widget produced
   nothing.

Added:
- contract/audit_store.go:
  - AuditStore interface + AuditFilter (Limit/Contributor/Intent/User/Result).
  - In-memory ring-buffer impl (default cap 1000), fan-out subscriptions,
    non-blocking sends so a slow consumer can't block command writes.
  - RecordingAuditEmitter that wraps an inner emitter (existing log-based
    one) and persists to the store.
- contract/pilot/audit.go:
  - AuditProvider interface + AuditRecordDTO with RFC3339Nano timestamps.
  - audit.list query handler (filters + nil-store -> CodeUnavailable).
  - audit.tail subscription handler (streams Append events; cancellation
    tears down the subscriber cleanly).
- pilot/manifest.yaml:
  - Two new intents (audit.list query, audit.tail subscription/append).
  - auditList named query with 5s staleTime cache.
  - New /audit route under Operations nav rendering audit.tail.
- contract/slots.go: extend page.shell.main Accepts to include audit.tail
  so the new top-level route validates.
- extension.go:
  - Construct e.auditStore at NewExtension time.
  - Wrap the chosen audit emitter (log/structured) with RecordingAuditEmitter
    so commands flow into both log lines AND the store.
  - Pass e.auditStore as pilot.Deps.Audit.

Tests:
- audit_store_test.go: append/list ordering, intent filter, limit clamping,
  ring truncation, subscribe broadcast, cancel-closes-channel,
  RecordingEmitter fan-out.
- pilot/audit_test.go: handler projection (timestamp formatting),
  CodeUnavailable on nil provider, subscription streams Appends,
  CodeUnavailable from subscription handler.
- pilot/types_test.go: bumped manifest counts (intents 9->11, routes 8->9).

go build + go test ./... clean (37 packages green).

Author: juicycleff

extensions/dashboard/contract/SLICE_K_DESIGN.md

@@ -0,0 +1,127 @@
+# Slice (k) — Audit storage + live `audit.tail` subscription
+
+**Status:** Active
+**Branch:** `dashboard-contract-slice-a`
+**Predecessors:** (a)–(j)
+
+## Why
+
+The audit emitter (slice b) writes to stdout/Logger via `LogAuditEmitter` and disappears. The vocabulary intent `audit.tail` (slice e) has had a React component that subscribes to a server intent named `audit.tail`, but that intent was never registered — clicking the audit widget would silently produce nothing. Slice (k) closes both gaps:
+
+1. **Persistent (in-memory) audit storage** — every command run is stored in a ring buffer the dashboard can query.
+2. **`audit.list` query intent** — paginated history of recent commands.
+3. **`audit.tail` subscription intent** — live append-mode stream of new audit records, which is what the React `AuditTail` component is already wired to consume.
+4. **`/audit` route** — top-level page in the manifest that combines history + live tail.
+
+This unlocks the audit widget that's been a no-op since slice (e) and gives the dashboard real command observability without external infrastructure.
+
+## Approach
+
+### 1. `AuditStore` interface + in-memory impl
+
+```go
+type AuditStore interface {
+    Append(rec AuditRecord)
+    List(filter AuditFilter) []AuditRecord  // newest first, capped by Limit
+    Subscribe() (<-chan AuditRecord, func())
+}
+```
+
+In-memory implementation:
+- Ring buffer (default cap 1000) protected by RWMutex.
+- `List(filter)` walks newest→oldest, applying optional `User`, `Contributor`, `Intent`, `Result` filters; returns up to `filter.Limit` (default 200, max 1000).
+- `Subscribe()` registers a fan-out channel; `Append()` non-blocking-sends to all subscribers (drops on slow consumers — telemetry, not authoritative).
+
+The store lives in `extensions/dashboard/contract` next to `audit.go`.
+
+### 2. `RecordingAuditEmitter`
+
+Wraps any inner `AuditEmitter` and adds a store side-effect:
+
+```go
+func NewRecordingAuditEmitter(inner AuditEmitter, store AuditStore) AuditEmitter
+```
+
+Slice (b) wired `dispatcher.NewLoggerAuditEmitter(...)` into the extension. After slice (k) the wiring becomes `NewRecordingAuditEmitter(NewLoggerAuditEmitter(...), e.auditStore)` so log-line semantics stay and the store fills.
+
+### 3. `audit.list` query handler
+
+Lives in pilot at `extensions/dashboard/contract/pilot/audit.go`:
+
+```go
+type AuditListInput struct {
+    Limit       int    `json:"limit,omitempty"`
+    Contributor string `json:"contributor,omitempty"`
+    Intent      string `json:"intent,omitempty"`
+    User        string `json:"user,omitempty"`
+    Result      string `json:"result,omitempty"`
+}
+type AuditListResponse struct {
+    Records []AuditRecordDTO `json:"records"`
+    Total   int              `json:"total"`
+}
+```
+
+Records are projected to a wire-friendly DTO with RFC3339Nano timestamps and the same fields the React component renders.
+
+### 4. `audit.tail` subscription handler
+
+A `dispatcher.SubscriptionHandler` that calls `store.Subscribe()`, fans events out as `StreamEvent{Mode: ModeAppend, Payload: AuditRecordDTO}`. Cancellation closes the subscriber channel.
+
+### 5. Manifest entry
+
+Add to `pilot/manifest.yaml`:
+
+```yaml
+intents:
+  - { name: audit.list, kind: query,        version: 1, capability: read }
+  - { name: audit.tail, kind: subscription, version: 1, capability: read, mode: append }
+
+queries:
+  auditList:
+    intent: audit.list
+    cache: { staleTime: 5s }
+
+graph:
+  - route: /audit
+    intent: page.shell
+    title: Audit
+    nav: { group: Operations, icon: history, priority: 23 }
+    slots:
+      main:
+        - intent: audit.tail
+          title: Live audit
+          data:
+            intent: audit.tail
+          props:
+            bufferSize: 200
+```
+
+This is the first time `audit.tail` appears in `page.shell.main`. Slot vocabulary needs an update: today `page.shell.main` accepts `[resource.list, resource.detail, dashboard.grid, form.edit, custom, iframe]` — extend with `audit.tail`.
+
+The `audit.list` query stays available for future history-style pages; v1 of the audit page only ships the live tail because the React `AuditTail` component is already built around subscriptions and history-styled rendering would need a new component.
+
+### 6. Wiring in `extension.go`
+
+- `NewExtension` constructs `e.auditStore = contract.NewInMemoryAuditStore()`
+- `e.auditEmitter = contract.NewRecordingAuditEmitter(<existing emitter>, e.auditStore)` after the existing `auditEmitter` selection block
+- Pilot `Deps` gets a new `Audit AuditProvider` field carrying the store; `Register()` registers the two handlers when non-nil
+
+## Tests
+
+- **Store:** `TestAuditStore_AppendList` (round-trip), `TestAuditStore_Filter`, `TestAuditStore_RingTruncates`, `TestAuditStore_SubscribeBroadcasts`, `TestAuditStore_DropsSlowSubscriber`.
+- **RecordingEmitter:** chains to inner + writes to store.
+- **Pilot audit.list handler:** happy path, projection (timestamps formatted), CodeUnavailable when nil store, filter behavior.
+- **Pilot audit.tail handler:** subscribes, emits events when store appends, cancellation cleans up.
+- **Manifest:** loads with new intents, validates with new vocabulary entry.
+
+## Out of scope
+
+- Persistent storage backends (Postgres, SQLite). The interface is shaped to allow them; in-memory is the slice-(k) impl.
+- Pagination cursors for `audit.list` (limit/offset would need a stable order key — slice (k2) when audit becomes a real history page).
+- Per-tenant scoping. The store is global; multi-tenant filtering happens in handlers when we add tenant resolution to AuditRecord (slice l, separate concern).
+- A history-rendering React component for `audit.list`. Slice (k) ships the live tail (`audit.tail`); a `resource.list`-style audit history page is a follow-on.
+
+## Why not split
+
+`audit.list` and `audit.tail` share the store and the projection helpers. The vocabulary update + manifest route benefits from being one PR with a single test pass. ~250 LOC total.

extensions/dashboard/contract/audit_store.go

@@ -0,0 +1,146 @@
+package contract
+
+import (
+	"context"
+	"sync"
+)
+
+// AuditStore is the persistent (process-local for slice (k)) view of audit
+// records. It exists to back the audit.list query and audit.tail subscription
+// the dashboard exposes; production deployments swap the in-memory impl for a
+// durable backend when one is wired.
+type AuditStore interface {
+	Append(rec AuditRecord)
+	List(filter AuditFilter) []AuditRecord
+	// Subscribe returns a channel that receives every Append from now on, plus
+	// a cancel func that closes the channel and unregisters the subscriber.
+	// Slow subscribers drop events rather than block writers — audit is
+	// telemetry, not the source of truth.
+	Subscribe() (<-chan AuditRecord, func())
+}
+
+// AuditFilter narrows audit.list results. All fields are optional. Limit is
+// clamped to [1, 1000]; zero defaults to 200.
+type AuditFilter struct {
+	Limit       int
+	Contributor string
+	Intent      string
+	User        string
+	Result      string
+}
+
+const (
+	defaultAuditListLimit = 200
+	maxAuditListLimit     = 1000
+)
+
+// NewInMemoryAuditStore returns a store that keeps the most recent `cap`
+// records in a ring buffer. cap <= 0 defaults to 1000.
+func NewInMemoryAuditStore(cap int) AuditStore {
+	if cap <= 0 {
+		cap = 1000
+	}
+	return &memAuditStore{
+		buf: make([]AuditRecord, 0, cap),
+		cap: cap,
+	}
+}
+
+type memAuditStore struct {
+	mu          sync.RWMutex
+	buf         []AuditRecord
+	cap         int
+	subs        []chan AuditRecord
+	subSeq      int // monotonic id for a future remove-by-id; not exposed yet
+	subsCleanup []chan AuditRecord
+}
+
+func (s *memAuditStore) Append(rec AuditRecord) {
+	s.mu.Lock()
+	if len(s.buf) >= s.cap {
+		// drop oldest
+		copy(s.buf, s.buf[1:])
+		s.buf = s.buf[:len(s.buf)-1]
+	}
+	s.buf = append(s.buf, rec)
+	subs := append([]chan AuditRecord(nil), s.subs...)
+	s.mu.Unlock()
+	// non-blocking fan-out — slow subscribers drop events
+	for _, ch := range subs {
+		select {
+		case ch <- rec:
+		default:
+		}
+	}
+}
+
+func (s *memAuditStore) List(filter AuditFilter) []AuditRecord {
+	limit := filter.Limit
+	if limit <= 0 {
+		limit = defaultAuditListLimit
+	}
+	if limit > maxAuditListLimit {
+		limit = maxAuditListLimit
+	}
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	out := make([]AuditRecord, 0, limit)
+	// walk newest -> oldest
+	for i := len(s.buf) - 1; i >= 0 && len(out) < limit; i-- {
+		rec := s.buf[i]
+		if filter.Contributor != "" && rec.Contributor != filter.Contributor {
+			continue
+		}
+		if filter.Intent != "" && rec.Intent != filter.Intent {
+			continue
+		}
+		if filter.User != "" && rec.User != filter.User {
+			continue
+		}
+		if filter.Result != "" && rec.Result != filter.Result {
+			continue
+		}
+		out = append(out, rec)
+	}
+	return out
+}
+
+func (s *memAuditStore) Subscribe() (<-chan AuditRecord, func()) {
+	ch := make(chan AuditRecord, 32)
+	s.mu.Lock()
+	s.subs = append(s.subs, ch)
+	s.mu.Unlock()
+	cancel := func() {
+		s.mu.Lock()
+		for i, c := range s.subs {
+			if c == ch {
+				s.subs = append(s.subs[:i], s.subs[i+1:]...)
+				break
+			}
+		}
+		s.mu.Unlock()
+		close(ch)
+	}
+	return ch, cancel
+}
+
+// NewRecordingAuditEmitter returns an emitter that fans out to inner (typically
+// the log emitter) and also persists to store. Either may be nil; both nil is
+// a noop.
+func NewRecordingAuditEmitter(inner AuditEmitter, store AuditStore) AuditEmitter {
+	return &recordingEmitter{inner: inner, store: store}
+}
+
+type recordingEmitter struct {
+	inner AuditEmitter
+	store AuditStore
+}
+
+func (e *recordingEmitter) Emit(ctx context.Context, rec AuditRecord) {
+	if e.store != nil {
+		e.store.Append(rec)
+	}
+	if e.inner != nil {
+		e.inner.Emit(ctx, rec)
+	}
+}

extensions/dashboard/contract/audit_store_test.go

@@ -0,0 +1,121 @@
+package contract
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func mkRec(intent string, t time.Time) AuditRecord {
+	return AuditRecord{
+		Time: t, Contributor: "core-contract", Intent: intent, Result: "ok",
+	}
+}
+
+func TestAuditStore_AppendList(t *testing.T) {
+	s := NewInMemoryAuditStore(0)
+	now := time.Now()
+	s.Append(mkRec("a", now.Add(-1*time.Second)))
+	s.Append(mkRec("b", now))
+	got := s.List(AuditFilter{})
+	if len(got) != 2 {
+		t.Fatalf("len = %d", len(got))
+	}
+	if got[0].Intent != "b" || got[1].Intent != "a" {
+		t.Errorf("expected newest-first ordering, got %+v", got)
+	}
+}
+
+func TestAuditStore_FilterIntent(t *testing.T) {
+	s := NewInMemoryAuditStore(0)
+	s.Append(mkRec("a", time.Now()))
+	s.Append(mkRec("b", time.Now()))
+	s.Append(mkRec("a", time.Now()))
+	got := s.List(AuditFilter{Intent: "a"})
+	if len(got) != 2 {
+		t.Errorf("expected 2 intent=a records, got %d", len(got))
+	}
+}
+
+func TestAuditStore_LimitClamping(t *testing.T) {
+	s := NewInMemoryAuditStore(0)
+	for i := 0; i < 50; i++ {
+		s.Append(mkRec("x", time.Now()))
+	}
+	if got := s.List(AuditFilter{Limit: 5}); len(got) != 5 {
+		t.Errorf("limit=5 -> %d records", len(got))
+	}
+	if got := s.List(AuditFilter{Limit: -1}); len(got) != 50 {
+		t.Errorf("limit=-1 -> %d records (want default 50 since cap < default)", len(got))
+	}
+}
+
+func TestAuditStore_RingTruncates(t *testing.T) {
+	s := NewInMemoryAuditStore(3)
+	for i := 0; i < 5; i++ {
+		s.Append(AuditRecord{Time: time.Now(), Intent: "x", User: string(rune('a' + i))})
+	}
+	got := s.List(AuditFilter{})
+	if len(got) != 3 {
+		t.Fatalf("expected 3 (cap), got %d", len(got))
+	}
+	// Newest is "e", oldest kept is "c"; "a" and "b" dropped.
+	if got[0].User != "e" || got[2].User != "c" {
+		t.Errorf("ring kept wrong records: %+v", got)
+	}
+}
+
+func TestAuditStore_SubscribeBroadcasts(t *testing.T) {
+	s := NewInMemoryAuditStore(0)
+	ch, cancel := s.Subscribe()
+	defer cancel()
+	go s.Append(mkRec("hello", time.Now()))
+	select {
+	case rec := <-ch:
+		if rec.Intent != "hello" {
+			t.Errorf("got %+v", rec)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("no event received")
+	}
+}
+
+func TestAuditStore_CancelClosesChannel(t *testing.T) {
+	s := NewInMemoryAuditStore(0)
+	ch, cancel := s.Subscribe()
+	cancel()
+	select {
+	case _, ok := <-ch:
+		if ok {
+			t.Errorf("expected closed channel")
+		}
+	case <-time.After(time.Second):
+		t.Fatal("channel did not close")
+	}
+}
+
+func TestRecordingAuditEmitter_FansOut(t *testing.T) {
+	store := NewInMemoryAuditStore(0)
+	captured := []AuditRecord{}
+	innerCalled := false
+	inner := auditEmitterFunc(func(_ context.Context, rec AuditRecord) {
+		innerCalled = true
+		captured = append(captured, rec)
+	})
+	em := NewRecordingAuditEmitter(inner, store)
+	em.Emit(context.Background(), mkRec("x", time.Now()))
+	if !innerCalled {
+		t.Errorf("inner emitter not called")
+	}
+	if len(captured) != 1 {
+		t.Errorf("inner saw %d records", len(captured))
+	}
+	if got := store.List(AuditFilter{}); len(got) != 1 {
+		t.Errorf("store has %d records", len(got))
+	}
+}
+
+// auditEmitterFunc is a tiny test-only adapter from func to AuditEmitter.
+type auditEmitterFunc func(ctx context.Context, rec AuditRecord)
+
+func (f auditEmitterFunc) Emit(ctx context.Context, rec AuditRecord) { f(ctx, rec) }