Files
archie/docs/architecture/plugins-and-extensions.md
T
sam fd4420a038 docs(architecture): record decisions recovered from the pre-migration tracker
Eight approved decisions existed only as beads memories and were lost when
the tracker was removed. Recovered from a backup taken six minutes before
8bf0f6b and folded into the docs that own them, rather than a new document.

- migration-decisions: recorded position as of 2026-07-29, the deferred
  private-input-DTO compromise, and the agreed internal/app/{archied,
  agentworker} next step
- configuration: missing credential degrades a capability, only invalid
  config is fatal; config generation moves from install.sh to archied setup
- identity: the three-layer invariants/SOUL/representation model, and why
  a curator may only propose SOUL changes
- agent-system: the curator isolation invariant (curators are peers, never
  on a chat turn's critical path)
- messaging-and-work-intake: semantic search over messages is an explicit
  non-goal, with the measurements behind it
- safe-change-and-recovery: the /restart deadlock and lockout constraints
- plugins-and-extensions: dates the surprisal deferral

Also replaces the dead `**Beads issue:** archie-core-5d7` frontmatter across
all 12 documents with the GitHub issue it migrated to (#73), and rewrites
every other beads identifier to its issue number.
2026-08-09 18:10:12 +10:00

3.9 KiB
Raw Blame History

Plugins and Extensions

Status: Approved foundation
Date: 2026-07-28
Tracking issue: #73

Plugin framework

The core plugin domain lives under internal/domain/plugin. It owns:

  • plugin identity and metadata;
  • discovery and registration contracts;
  • lifecycle rules;
  • capability registration;
  • validation and compatibility rules.

The generic plugin contract remains metadata-only. Functionality is exposed through narrow typed capability contracts with an owning registry or manager.

Workflow plugins belong to the Workflow capability family. The Workflow domain at internal/domain/workflow owns their typed registration, validation, versioning, definition, and execution contracts. The generic plugin domain may provide plugin identity, discovery, compatibility, and lifecycle mechanics, but it MUST NOT define Workflow semantics or expose untyped Workflow hooks.

Plugin implementations

First-party plugins are self-contained vertical modules under plugins/<plugin>.

A plugin:

  • owns its implementation, settings, templates, assets, and tests;
  • receives only explicitly supplied contracts and services;
  • MUST NOT receive daemon internals, a service locator, or unrestricted application access;
  • MUST NOT import arbitrary infrastructure or application composition code;
  • MAY use approved domain and shared application contracts;
  • MUST remain removable without changes to unrelated domains.

Plugins may be internally cohesive like small services. They do not become network services without a concrete security or operational reason.

Curator surprisal sampling (deferred)

Deferred by decision, 2026-08-05 — Archie has no embedding capability, and wave 1 ships the strategy seam without one. Pick the deferred work up in order: #436 first, then #437 which depends on it and on #407.

The curator engine family (epic #435) selects which memories deserve agentic attention via surprisal-based sampling: score memories by how surprising they are and spend the sampled reasoner's agentic budget on the most surprising items. Wave 1 of the epic ships the Sampler strategy seam in internal/curator with cheap, embedding-free strategies (recency, random, all, and a staleness proxy). The embedding-backed strategy is a documented extension point and is gated behind an embedding capability Archie does not yet have — any surprisal-style sampling is gated behind adding one.

Requirements for the deferred work, so it can be picked up without re-deriving the design (tracked as #436 embeddings capability, then #437 surprisal strategies):

  • A Sampler implementation behind the same interface as the cheap strategies; selection deterministic given fixed inputs.
  • Algorithm: sample up to a candidate cap; build a k-NN graph over embedding vectors; row-normalize the adjacency with self-loops; power-iterate to the stationary distribution; surprisal = −log(stationary probability of the nearest point); select the highest-surprisal items.
  • Degradation: content without an embedding is skipped; an embedding failure aborts sampling and falls back to free exploration — a sampling failure must never fail or crash a curator pass.
  • Cost bound: the graph build is quadratic in the candidate cap; the cap must be a named constant with a documented bound.
  • The embedding capability itself: a narrow typed client usable by in-process components, config-driven provider/model, credential-missing degrades to "capability unavailable" (daemon still starts), timeouts on network calls, tests via httptest only.