Extension model

The eight capability systems — Intake, Atlas, Warrant, Lineage, Conduit, Lens, Crucible, Ports — are extensible by third parties. A plugin is an in-process TypeScript module that declares what it needs, contributes to named extension points, and reads and writes the other systems only through a permission-gated facade and a workspace-scoped event bus. It never receives a pool handle, a transaction, or a workspaceId it chose itself — which is what lets the product stay extensible without weakening the property it is actually sold on: Postgres RLS multi-tenancy.

How the pieces fit

The contract

The manifest declares everything statically — id, semver, the host API range it supports, permissions, event subscriptions, a config schema, and the name of every contribution — while setup() merely binds implementations to those declared names. The host then asserts that declaration and registration are exactly equal. A plugin can therefore be inspected, permission-reviewed and diffed across versions without executing any plugin code, and a plugin that quietly grows a contribution or a permission fails at load rather than at 3am.

export default definePlugin({
  id: "eli.freshness-sentinel",
  version: "1.0.0",
  apiVersion: "^1.0.0",
  displayName: "Knowledge Freshness Sentinel",
  description: "Finds certified concepts that have gone stale …",
  core: false,

  // Nine capabilities, each traceable to a facade call. Absent on purpose:
  //   graph:write     — it reports on the graph; it never edits it
  //   agents:execute  — it never spends model budget
  permissions: [
    "documents:read", "documents:write", "graph:read",
    "governance:read", "governance:write",
    "data:read", "data:execute", "evals:read", "settings:write",
  ],

  subscribes: [
    "answer.produced",     // Lens
    "document.ingested",   // Intake
    "document.updated",    // Intake
    "eval.run.completed",  // Crucible
  ],

  configSchema,

  contributes: {
    intakeDocumentTransforms: ["stamp_reviewed_at"],
    lineageSections: ["freshness"],
    evalMetrics: ["stale_citation_rate"],
    tools: ["freshness_report"],
    jobs: ["scan"],
    httpOperations: [{ name: "report", method: "GET", requires: "governance:read" }],
  },

  setup(reg) { /* bind exactly the names declared above */ },
});

Extension points, by system

Eleven named points. Each one is consumed by the system that owns it, through a single host helper (invokeContributions) that resolves the workspace's active installs, checks the capability the point requires, builds a per-(plugin, workspace) context, runs the contribution under a deadline, and returns typed outcomes in deterministic plugin-id order. Written once in the host rather than seven times in the consuming systems, which is what makes "the capability check happened" a property rather than a convention.

The event taxonomy

A closed, versioned set of core events, derived from real emit sites — the places that already write an audit row or finalise a durable record, so an event is never a second source of truth. Plugins subscribe to these; a plugin may only emit under its own namespace (plugin.<id>.<name>), so the core vocabulary cannot be counterfeited.

An event carries identifiers and metadata, never content — never document text, never an answer body — and is capped at 8KB. Reading the thing an event points at is a separate, permission-checked, ACL-checked act, which is precisely what stops the bus from becoming a way to see answers you are not entitled to.

Two delivery channels

A subscription may additionally set ordered: true (queued only) to serialise deliveries per subject, trading throughput for the guarantee that a retried older event cannot land after a newer one for the same document. The outbox is the durability guarantee; the worker's one-minute sweep is only the trigger, so a missed tick delays delivery and never loses it.

Permissions

A plugin declares the capabilities it needs; the runtime enforces that declaration at call time. The effective set is a three-way intersection, and every facade method asserts against it before touching any server module — so a denied write is not a rolled-back write, it never starts.

effective = declared(manifest)
          ∩ granted(plugin_installations.granted_permissions)
          ∩ principal(request-derived contexts only)

Permissions come from the existing capability union — no parallel vocabulary, no new API-key scope — so role editors, custom roles and the scope→capability map keep working unchanged. A request-derivedcontext (an MCP tool call, an HTTP operation) also intersects with the caller's live capabilities, so a viewer cannot use a plugin as a privilege ladder. An ambient context (a queued handler, a worker job, a scheduled scan) has no principal and runs at declared ∩ granted, attributed to plugin:<id>. Granting is itself bounded by the granting admin's own capabilities, exactly as workspace-key creation bounds scopes today.

A denial is explicit, never a silent empty result: it throws PluginPermissionError and writes a plugin.permission_denied row naming the capability, the surface and one of three reasons — not_declared (fix the manifest), not_granted (an admin must grant it), or principal_lacks (the caller is not allowed to do this). That distinction is what makes a denial actionable instead of a mystery.

Enterprise guarantees

Where to go next

Follow Build a plugin to scaffold, declare, subscribe, read and write across systems, test and load one — worked end to end against the real example plugin. Then read Extend or modify a plugin for changing one you did not write: which edits are safe, which trip needs_review, and how to add an extension point to the host itself. The internal decision record lives in docs/architecture/plugins.md.