@xynogen/pix-runtime 0.1.0

package/DESIGN.md

@@ -0,0 +1,719 @@
+# `@xynogen/pix-runtime` design
+
+Status: proposed  
+Target first release: `0.1.0`
+
+## 1. Purpose
+
+`pix-runtime` is Pix's small shared runtime layer. It owns the process-wide Pix
+configuration contract and the lifecycle needed to keep that contract coherent.
+It is **not** an aggregator, renderer, model-data package, service locator, or
+state database.
+
+Its first responsibility is to make `~/.pi/agent/pix.json` the single, sparse,
+versioned user configuration file for the Pix distro. It will own:
+
+- the config schema and defaults;
+- validation and normalization;
+- one-time migrations, including `optimizer.json`;
+- atomic persistence and serialized writes;
+- an immutable in-process config snapshot;
+- typed change events with changed paths and origin;
+- lifecycle initialization and shutdown;
+- the `/pix` shared-settings command;
+- narrow, pure runtime helpers such as collapse policy.
+
+Package boundaries after adoption:
+
+- `pix-core`: dependency aggregation and extension registration only;
+- `pix-runtime`: shared configuration and lifecycle;
+- `pix-data`: model catalogs, scores, and caches only;
+- `pix-pretty`: rendering only; consumes runtime settings;
+- feature packages: own behavior and UI, and consume built-in typed runtime
+  sections where shared persistence is appropriate.
+
+## 2. Non-goals
+
+The runtime must not become a general dependency-injection container.
+Specifically, v1 does not own:
+
+- themes, ANSI values, render caches, or TUI components;
+- model catalogs or network cache refreshes;
+- session transcript state, todos, tool results, or credentials;
+- arbitrary package services;
+- project-local Pix configuration;
+- automatic filesystem watching;
+- hidden background work or package activation.
+
+There is one runtime instance per JavaScript process, not one per conversation.
+The singleton is stored under `globalThis[Symbol.for("@xynogen/pix-runtime")]`, not
+only in module scope, so duplicated compatible npm copies do not create separate
+write queues. A second incompatible runtime major must fail closed with a clear
+diagnostic. Session-specific state remains in the relevant extension or Pi
+session log.
+
+## 3. Dependency direction
+
+```text
+pix-core ───────────────► pix-runtime
+   │                         ▲
+   ├─► pix-data              │
+   ├─► pix-pretty ───────────┤
+   └─► feature packages ─────┘
+
+pix-runtime ──peer──► Pi host
+pix-runtime ──X─────► pix-core / pix-data / pix-pretty / feature packages
+```
+
+`pix-runtime` must have no dependency on another `@xynogen/pix-*` package. It
+may peer-depend on the Pi host for `getAgentDir()` and extension types. Keeping
+this direction acyclic prevents the runtime from turning into another bundle.
+
+`pix-core` registers `pix-runtime` first, before all consumers. Direct installs
+remain supported: importing a runtime accessor lazily creates the singleton and
+loads the built-in sections even if the extension factory was not run.
+The factory is still required for `/pix`, session lifecycle hooks, and user
+notifications.
+
+## 4. Storage contract
+
+### 4.1 Canonical path
+
+Always resolve the file through Pi's agent directory:
+
+```ts
+join(getAgentDir(), "pix.json")
+```
+
+This respects `PI_CODING_AGENT_DIR`; it must not reconstruct the path from
+`HOME`. Tests inject an explicit `agentDir` adapter rather than mutating the
+real user directory.
+
+### 4.2 File shape
+
+The file is a sparse document with a format version:
+
+```jsonc
+{
+  "$version": 1,
+  "pretty": {
+    "icons": "ascii",
+    "diff": { "splitMinWidth": 170 }
+  },
+  "optimizer": {
+    "caveman": "lite",
+    "rtk": "on"
+  }
+}
+```
+
+Top-level sections in v1:
+
+```ts
+interface PixConfigV1 {
+  $version: 1;
+  collapse: {
+    enabled: boolean;                    // default true
+    delaySec: number;                    // default 10
+    tools: Partial<Record<string, boolean>>;
+  };
+  pretty: {
+    icons: "nerd" | "unicode" | "ascii"; // default nerd
+    lsStyle: "grid" | "tree";          // default grid
+    maxPreviewLines: number;             // default 80
+    maxRenderLines: number;              // default 150
+    maxHighlightChars: number;           // default 80000
+    cacheLimit: number;                  // default 128
+    diff: {
+      splitMinWidth: number;             // default 150
+      splitMinCodeWidth: number;         // default 60
+    };
+  };
+  optimizer: {
+    caveman: "off" | "lite" | "full" | "ultra" | "micro"; // default off
+    rtk: "off" | "on";                                      // default on
+    toon: "off" | "on";                                     // default on
+    ponytail: "off" | "lite" | "full" | "ultra";          // default off
+  };
+  gate: {
+    disableDefaults: boolean;            // default false
+    autoApprove: string[];               // default []
+    extraRules: Array<{
+      pattern: string;
+      flags?: string;
+      severity?: "risky" | "dangerous" | "critical";
+      reason?: string;
+    }>;
+  };
+}
+```
+
+The **resolved snapshot** always contains every field. The **persisted file**
+contains `$version` plus sparse known values. Runtime tracks provenance for
+known paths (`explicit` versus `inherited`): an explicitly written value is
+retained even when it currently equals the default, while untouched inherited
+defaults are omitted. This prevents a future default change from silently
+changing an explicit user choice. `reset()` clears explicit provenance and
+restores inheritance.
+
+Unknown top-level sections and unknown keys inside known sections are preserved
+on read/write so a newer or standalone package is not erased by an older
+runtime. Runtime therefore keeps a private raw-document shadow beside the typed
+snapshot; the presence of known paths in that shadow is their explicit-value
+provenance. Section serialization merges known fields into that shadow rather
+than reconstructing the whole file from typed values. Unknown data is not
+exposed through typed selectors in v1.
+
+`$version` is metadata and is always persisted after the first successful
+migration/write. An entirely default v1 config is therefore:
+
+```json
+{ "$version": 1 }
+```
+
+### 4.3 Atomic writes
+
+All writes use one serialized in-process queue and a short-lived cross-process
+lock (`pix.json.lock`, acquired with exclusive creation). The lock contains PID
+and timestamp metadata, uses bounded retry/backoff, and may be reclaimed only
+when it is older than the configured stale threshold and its owning process is
+confirmed absent where the platform supports that check. Lock timeout returns a
+typed error rather than writing concurrently.
+
+Inside the lock, every transaction:
+
+1. reads the latest on-disk document (never trusts only the cached shadow);
+2. migrates and validates it;
+3. applies the typed update;
+4. merges known fields while preserving unknown raw fields;
+5. omits inherited defaults recursively while retaining explicitly set values;
+6. writes `<pix.json>.tmp-<pid>-<nonce>` in the same directory;
+7. flushes and closes the temporary file;
+8. renames it over `pix.json` atomically and best-effort flushes the directory;
+9. releases the cross-process lock in `finally`;
+10. updates the in-memory snapshot;
+11. emits one change event.
+
+Use mode `0o600` for a newly created file and temporary file. No caller writes
+`pix.json` directly. A failed lock/write/rename leaves the old file intact, does
+not change the snapshot, and returns a typed error. The runtime never silently
+reports success. This protects both multiple sessions in one process and
+multiple Pi processes sharing the same agent directory.
+
+## 5. Schema registry
+
+Runtime models configuration as typed sections rather than exposing one
+stringly typed mega-object. Built-in sections (`collapse`, `pretty`,
+`optimizer`, `gate`) live in runtime so the core config works immediately.
+V1 keeps the registry internal: there is no stable dynamic registration API
+until a real optional-package use case proves its lifecycle and ownership
+semantics. Unknown raw sections are still preserved, so this does not block
+forward compatibility.
+
+```ts
+export interface ConfigSection<T> {
+  key: string;
+  defaults: Readonly<T>;
+  parse(raw: unknown, ctx: ParseContext): T;
+  serialize?(value: T, defaults: T): unknown;
+  settings?: readonly SettingDescriptor<T>[];
+}
+
+export function defineSection<const K extends string, T>(
+  definition: ConfigSection<T> & { key: K },
+): SectionHandle<K, T>;
+
+```
+
+Registry rules:
+
+- duplicate built-in keys fail at module initialization;
+- parsers are pure and synchronous;
+- invalid fields fall back individually and produce diagnostics rather than
+  invalidating the whole file;
+- `gate.extraRules` validates both regex pattern and flags during parsing, so
+  malformed expressions become `INVALID_VALUE` diagnostics and never throw at
+  tool-call time;
+- a future public `registerSection()` API requires a separate design/release.
+
+Built-in handles are exported from `@xynogen/pix-runtime/sections`:
+
+```ts
+collapseSection
+prettySection
+optimizerSection
+gateSection
+```
+
+This avoids stringly typed access in consumers.
+
+## 6. Public API
+
+### 6.1 Runtime access
+
+```ts
+export interface PixRuntime {
+  readonly path: string;
+  readonly ready: boolean;
+
+  init(options?: InitOptions): Promise<ConfigSnapshot>;
+  flush(): Promise<void>;
+  shutdown(): Promise<void>;
+
+  snapshot(): ConfigSnapshot;
+  get<K extends string, T>(section: SectionHandle<K, T>): Readonly<T>;
+
+  update<K extends string, T>(
+    section: SectionHandle<K, T>,
+    updater: DeepPartial<T> | ((current: Readonly<T>) => T),
+    options?: UpdateOptions,
+  ): Promise<ConfigChange | undefined>;
+
+  reset<K extends string, T>(
+    section: SectionHandle<K, T>,
+    paths?: readonly ConfigPath<T>[],
+    options?: UpdateOptions,
+  ): Promise<ConfigChange | undefined>;
+
+  reload(options?: ReloadOptions): Promise<ConfigChange | undefined>;
+  subscribe(listener: ConfigListener, options?: SubscribeOptions): () => void;
+  diagnostics(): readonly ConfigDiagnostic[];
+}
+
+export function pixRuntime(): PixRuntime;
+```
+
+Convenience functions may delegate to the singleton:
+
+```ts
+config(section)
+updateConfig(section, patch, options?)
+onConfigChange(listener, options?)
+reloadConfig(options?)
+```
+
+There is deliberately no untyped `savePixConfig(Record<string, unknown>)` in
+the stable API. Patch semantics are explicit: objects merge recursively, arrays
+replace, `undefined` is rejected, and `null` is accepted only when the section
+schema permits it. `reset()` is the only way to restore defaults/delete known
+persisted paths. A functional updater receives the latest section parsed from
+disk inside the transaction lock, not a stale cached value.
+
+### 6.2 Snapshots and immutability
+
+Every successful commit creates a deeply frozen snapshot with a monotonically
+increasing in-process revision. Reads are synchronous after lazy initialization:
+
+```ts
+interface ConfigSnapshot {
+  readonly revision: number;
+  readonly formatVersion: 1;
+  readonly loadedAt: number;
+  get<K extends string, T>(section: SectionHandle<K, T>): Readonly<T>;
+}
+```
+
+`runtime.get(section)` and `snapshot.get(section)` return deeply frozen section
+values. The latter lets change listeners compare previous/current values
+without reaching back into mutable runtime state. Consumers must not retain and
+mutate them. Updates are immutable and typed.
+
+### 6.3 Change events
+
+```ts
+type ConfigChangeOrigin =
+  | "init"
+  | "command"
+  | "api"
+  | "reload"
+  | "migration";
+
+interface ConfigChange {
+  readonly revision: number;
+  readonly origin: ConfigChangeOrigin;
+  readonly source?: string; // e.g. "pix-pretty:/pix" or "pix-optimizer:/optimizer"
+  readonly changed: readonly string[]; // JSON paths, e.g. "pretty.icons"
+  readonly previous?: ConfigSnapshot; // absent only for init/immediate delivery
+  readonly current: ConfigSnapshot;
+  readonly persisted: boolean;
+}
+```
+
+Mutation/reload events fire only after success and only when the resolved
+config actually changes. A no-op `update()`/`reset()` returns `undefined`.
+Initialization emits one `origin: "init"` event with no `previous` snapshot;
+`{ immediate: true }` delivers that same shape for the current snapshot to the
+new listener only. Listener failures are isolated and reported as diagnostics;
+they do not roll back a committed write. Dispatch occurs in registration order
+from a copied listener list so unsubscribe during dispatch is safe.
+
+Filtering is built in:
+
+```ts
+runtime.subscribe(listener, { paths: ["pretty.icons", "optimizer.*"], immediate: true });
+```
+
+This is an in-process event bus only. External edits become visible when
+`reload()` is explicitly called or when a future Pi config-reload lifecycle
+hook invokes it. V1 intentionally avoids a permanent filesystem watcher.
+Listener-triggered updates are appended to the write queue after current event
+dispatch, preventing recursive commits and preserving event order.
+
+## 7. Initialization and lifecycle
+
+The extension entry point is idempotent:
+
+```ts
+export default function registerRuntime(pi: ExtensionAPI): void;
+```
+
+A process-global compatible-runtime record contains a registration token that
+prevents duplicate command/lifecycle registration when runtime is installed
+directly and also imported through `pix-core` (even if package copies receive
+different wrapper objects for the Pi host). On first registration it:
+
+1. installs built-in section definitions;
+2. creates the process singleton using `getAgentDir()`;
+3. registers `/pix`;
+4. registers one `session_start` hook that calls `init()` the first time and
+   `reload()` on later sessions, then surfaces aggregated migration/parse
+   diagnostics through the UI;
+5. registers one `session_shutdown` hook that calls `flush()`.
+
+A session shutdown does not destroy process-wide subscriptions: Pi may start
+another session in the same process. Explicit `shutdown()` is reserved for
+process teardown and tests; it flushes writes, releases runtime resources, and
+clears listeners.
+
+`init()` itself is single-flight. Concurrent calls share one promise. It:
+
+1. creates the agent directory if needed;
+2. acquires the in-process write queue;
+3. reads `pix.json` without modifying it yet;
+4. detects the source format;
+5. runs ordered migrations;
+6. parses all built-in sections;
+7. imports legacy sidecars;
+8. atomically persists the canonical sparse document if migration changed it
+   and the current release stage allows that migration;
+9. freezes and publishes the first snapshot;
+10. emits one consolidated event: `init` when no lazy snapshot existed, or
+    `migration` when a prior lazy snapshot changed. If a lazy snapshot is still
+    identical, initialization emits nothing; `{ immediate: true }`
+    subscriptions already received that snapshot.
+
+Consumers may call `get()` before `session_start`; this performs a synchronous,
+read-only lazy load so module-level constants continue to work during the
+transition. It does not migrate or write, but it may read a valid legacy optimizer sidecar
+as a temporary overlay so optimizer controls do not flicker to defaults before
+initialization. Later `init()` reparses under the normal transaction lock and
+publishes any difference. Packages should migrate
+module-level config constants to functions or subscriptions because a constant
+cannot react to `/pix` changes.
+
+Runtime resolves only JSON values plus schema defaults. Legacy package-specific
+environment variables are not folded into the persisted snapshot because doing
+so would make sparse serialization and change events ambiguous. During the
+compatibility window, each consumer may apply its existing environment override
+on top of `runtime.get(section)` using its current precedence; those variables
+should be documented as external overrides and deprecated separately.
+
+## 8. Migration design
+
+Migrations are ordered, idempotent, and pure over a `RawDocument`:
+
+```ts
+interface Migration {
+  from: number | "unversioned";
+  to: number;
+  migrate(document: RawDocument, context: MigrationContext): MigrationResult;
+}
+```
+
+### 8.1 Unversioned `pix.json` → v1
+
+- retain valid `collapse`, `pretty`, `optimizer`, and `gate` values;
+- remove `pretty.theme`, `pretty.syntaxTheme`, `pretty.diffColors`, and legacy
+  diff color fields because active Pi themes own all colors;
+- preserve unknown keys;
+- normalize default-valued entries out of the persisted document;
+- set `$version: 1`.
+
+### 8.2 `optimizer.json` → `pix.json.optimizer`
+
+Import `join(getAgentDir(), "optimizer.json")` exactly once:
+
+- validate each optimizer value independently;
+- when both files contain a valid value, existing `pix.json.optimizer.<key>`
+  wins;
+- otherwise import the valid sidecar value;
+- write canonical `pix.json` first;
+- only after that rename the sidecar to `optimizer.json.migrated-v1`;
+- if the archive name exists, append a timestamp;
+- never delete the sidecar before the canonical write succeeds;
+- malformed sidecars remain untouched and generate a visible diagnostic;
+- future starts skip archived files, making migration idempotent.
+
+Migration is deliberately staged because already-published `pix-data` versions
+delete `raw.optimizer` whenever they save:
+
+1. the Phase-A `pix-data` compatibility release removes that deletion and makes
+   every config write delegate to runtime;
+2. every first-party package still depending on `pix-data` raises its
+   `pix-data` floor to that compatibility version in the same release train,
+   preventing npm from resolving a known pre-delegate version for those
+   packages; package manifests and `bun.lock` are audited before tagging;
+3. the first optimizer-runtime release imports into `pix.json` but keeps
+   `optimizer.json` as a compatibility mirror/read fallback for one full
+   release train; optimizer updates write canonical config first, then update
+   the mirror;
+4. if an old writer erases `pix.json.optimizer`, runtime restores it from the
+   mirror on the next locked initialization/reload. The reverse compatibility
+   direction is not fully enforceable for arbitrary third-party/stale installs,
+   so the mirror remains the authoritative rollback source during this window;
+5. only after the compatibility window and published dependency-floor audit
+   does runtime rename the mirror to `optimizer.json.migrated-v1` (timestamping
+   conflicts). A competing process that already moved it makes `ENOENT` benign.
+
+The archived sidecar then provides a transparent rollback/audit path. A later
+major release may remove archived files, but v1 does not. This temporary mirror
+is the sole exception to the eventual one-file storage rule and exists only to
+avoid user-state loss during mixed-version upgrades.
+
+### 8.3 Old runtimes and forward compatibility
+
+If `$version` is greater than the maximum supported version, runtime enters
+read-only compatibility mode:
+
+- known sections may be read best-effort;
+- no automatic normalization or migration occurs;
+- all updates fail with `UNSUPPORTED_CONFIG_VERSION`;
+- `/pix` displays the problem and the path instead of overwriting the file.
+
+This is safer than letting an older package erase newer settings.
+
+## 9. `/pix` and package-owned controls
+
+`/pix` is registered by runtime because it edits the shared document. Its rows
+come from section `settings` descriptors. This keeps persistence centralized
+without making runtime know feature behavior.
+
+A descriptor contains a path, label, parser/formatter, allowed values, and
+optional visibility. These descriptors are internal to built-in runtime
+sections in v1. Runtime supplies the generic overlay and calls
+`runtime.update()`.
+
+Ownership rule:
+
+- `/pix` shows distro-wide settings such as icons, layout, collapse, and gate;
+- `/optimizer` remains the optimizer's complete control surface;
+- optimizer consumes runtime's built-in `optimizerSection` but does **not**
+  register controls in `/pix`;
+- `/optimizer` writes `optimizerSection` through runtime and subscribes to
+  `optimizer.*` changes;
+- config ownership and UI ownership are separate concepts.
+
+The `/pix` headless summary marks non-default values and reports the canonical
+path. It never dumps unknown sections or secrets.
+
+## 10. Consumer migration
+
+### Phase A — introduce runtime without behavior changes
+
+1. Create `pix-runtime` with built-in sections, tests, and extension entry.
+2. Add it as the first dependency/member in `pix-core`.
+3. Keep temporary compatibility exports in `pix-data/pix-config` and
+   `pix-data/collapse`, implemented as deprecated delegates to runtime. This
+   release explicitly removes `delete raw.optimizer` and direct filesystem
+   writes.
+4. Make runtime read legacy unversioned `pix.json` but postpone sidecar import
+   until optimizer has runtime support in the same release train.
+5. Ship this compatibility release before enabling optimizer migration. This is
+   essential because historical `pix-data.savePixConfig()` deletes the
+   `optimizer` key and could otherwise destroy newly migrated state in a mixed
+   install.
+6. Update `AGENTS.md` now—not in final cleanup—to recognize runtime as a
+   sanctioned shared layer and document the new dependency direction.
+7. Keep `0.1.x` private/experimental while stabilizing the contract, publish
+   `1.0.0` before broad Phase-B adoption, and then avoid 0.x caret-range churn
+   across roughly twenty consumers.
+
+### Phase B — move consumers
+
+- `pix-pretty`: use `prettySection`; subscribe to `pretty.icons`; convert
+  module-level numeric constants to getters or captured values refreshed on
+  config events.
+- runtime owns only pure `shouldCollapse()` and `collapseDelayMs()` policy;
+  move the UI timer/state machine (`tickCollapse`, `CollapseState`) to
+  `@xynogen/pix-pretty/collapse`, which consumes runtime policy. Tool packages
+  already use pix-pretty for rendering and should not get UI state from runtime.
+- `pix-gate`: read `gateSection` at tool-call time or rebuild compiled rules on
+  `gate.*` changes so `/pix` updates are live.
+- `pix-data`: remove config and command ownership; retain only data/cache APIs.
+- tests: construct isolated runtimes with injected filesystem/path/log adapters,
+  avoiding singleton and real-home leakage.
+
+### Phase C — unify optimizer state
+
+1. Add `pix-runtime` dependency to `pix-optimizer`.
+2. Replace `loadOptValue`/`saveOptValue` with `runtime.get/update` on
+   `optimizerSection`.
+3. Preserve session-log entries for branch-local restoration only: initialize
+   from global config, then let a valid current-branch session entry override
+   the live value without rewriting global config. An explicit `/optimizer`
+   change writes both the branch entry and global preference.
+4. Enable canonical sidecar import plus the temporary compatibility mirror;
+   archive `optimizer.json` only after the audited compatibility window.
+5. Keep `/optimizer` as the only optimizer UI.
+
+### Phase D — remove compatibility layer
+
+After all first-party consumers have shipped runtime-based versions:
+
+- remove `pix-config.ts`, `/pix`, and config docs from `pix-data`;
+- move collapse implementation and tests to runtime;
+- remove deprecated exports in the next planned breaking release of `pix-data`;
+- remove compatibility wording from `AGENTS.md`; runtime was already added as a
+  sanctioned layer in Phase A.
+
+## 11. Testing requirements
+
+The runtime release is blocked unless tests cover:
+
+### Schema and normalization
+
+- every built-in default resolves correctly;
+- invalid fields fall back individually and produce path diagnostics;
+- inherited defaults are removed recursively while explicit default-valued
+  choices survive;
+- unknown fields survive updates;
+- snapshots are deeply immutable;
+- duplicate built-in section registration is rejected;
+- malformed gate regex patterns/flags become diagnostics.
+
+### Persistence
+
+- writes are atomic and leave no temp file after success;
+- simulated write/rename failures preserve the old file and snapshot;
+- concurrent updates in one process and in two simulated processes are
+  serialized without lost fields;
+- functional updaters receive the latest locked on-disk value;
+- no-op updates neither write nor emit;
+- custom `PI_CODING_AGENT_DIR` is respected;
+- new files use restrictive permissions where supported.
+
+### Migration
+
+- unversioned config migrates to v1;
+- legacy color keys are removed;
+- optimizer sidecar imports valid values and serves as a temporary read/write
+  compatibility mirror;
+- canonical optimizer values win conflicts;
+- malformed sidecars remain untouched;
+- sidecar archives only after successful canonical write and the audited
+  compatibility window;
+- rerunning migration is idempotent, and concurrent archive `ENOENT` is benign;
+- future versions enter read-only mode.
+
+### Events and lifecycle
+
+- initialization is single-flight and idempotent;
+- events contain correct optional-previous/current snapshots and changed paths;
+- path filters and immediate subscriptions work;
+- listener errors are isolated;
+- session flush and explicit shutdown drain pending writes without breaking
+  subscriptions needed by a later session;
+- direct package use works without `pix-core` registration.
+
+### Integration
+
+- `/pix` updates icon mode live;
+- `/optimizer` updates only optimizer config and remains its sole UI;
+- gate rules rebuild after a gate config change;
+- collapse policy changes affect newly rendered cards;
+- installing `pix-data` alone no longer registers `/pix` after compatibility
+  removal.
+
+## 12. Error and diagnostic model
+
+No config failure should crash Pi, but failures must be visible and
+inspectable. Runtime keeps bounded diagnostics and exposes them to `/pix`:
+
+```ts
+interface ConfigDiagnostic {
+  code:
+    | "PARSE_ERROR"
+    | "INVALID_VALUE"
+    | "READ_FAILED"
+    | "WRITE_FAILED"
+    | "MIGRATION_FAILED"
+    | "UNSUPPORTED_CONFIG_VERSION"
+    | "LISTENER_FAILED";
+  severity: "warning" | "error";
+  path?: string;
+  message: string;
+  cause?: unknown;
+  at: number;
+}
+```
+
+At session start, aggregate diagnostics into at most one notification to avoid
+noise. `/pix` provides the detailed paths. Never include config values in error
+messages unless they are known non-sensitive enum/number values.
+
+## 13. Recommended source layout
+
+```text
+packages/pix-runtime/
+  package.json
+  README.md
+  DESIGN.md
+  src/
+    index.ts             # extension entry + stable public exports
+    runtime.ts           # singleton and PixRuntime implementation
+    registry.ts          # internal built-in section registry
+    schema.ts            # shared types and validation helpers
+    sections/
+      index.ts
+      collapse.ts
+      pretty.ts
+      optimizer.ts
+      gate.ts
+    persistence.ts       # read, sparse serialize, atomic write, queue
+    migrations.ts        # versioned migrations and sidecar importer
+    events.ts            # listener registry and path filtering
+    collapse.ts          # pure collapse policy only
+    diagnostics.ts
+    pix-command.ts
+    testing.ts           # createIsolatedRuntime(adapters)
+```
+
+Suggested exports:
+
+```jsonc
+{
+  ".": "./src/index.ts",
+  "./config": "./src/runtime.ts",
+  "./sections": "./src/sections/index.ts",
+  "./collapse": "./src/collapse.ts",
+  "./testing": "./src/testing.ts"
+}
+```
+
+## 14. Acceptance criteria
+
+`pix-runtime` is ready to release when:
+
+1. all config paths use `getAgentDir()` and honor `PI_CODING_AGENT_DIR`;
+2. `pix.json` is versioned, sparse, validated, atomically written, and guarded
+   against concurrent writers;
+3. unknown fields survive older-runtime updates and future versions fail closed;
+4. optimizer state migrates once with an archived rollback file;
+5. failed writes cannot corrupt or falsely update the live snapshot;
+6. typed, filtered change events update icons, gate rules, and optimizer state;
+7. `/pix` and `/optimizer` retain separate ownership;
+8. `pix-data` can become a pure model-data package;
+9. `pix-core` remains an ordered aggregator with runtime first;
+10. standalone packages work without pix-core through lazy runtime access;
+11. the full test, typecheck, lint, dependency, migration, and publish dry-run
+    suites pass.