Overview

Better Compute has no plugin loader. Every place you can change its behaviour is a typed contract in @better-compute/core, and you plug an implementation in by passing it to betterCompute(). Two rules from PLAN.md §5.1 shape all of them:

• Code registers kinds; data configures instances. A driver, a provider or an attestor is code you register once. A BMC binding, a provider account or a join token is a row, validated by the manifest that code declares.
• Registration is explicit. Nothing is discovered from the file system or node_modules. Everything arrives in an options array, and the registry refuses what it cannot check: a duplicate kind:id@version, a method whose action is missing from the IAM catalog, or a migration named for another module are all INVALID_CONFIG when betterCompute() or initialize() runs.

The extension points

The root entry better-compute exports defineModule, definePlugin, defineDriver, defineSchedulerPlugin, defineAttestor and defineSink. defineMethod, defineStep, defineProfile and defineProvider come from the better-compute/core, /provision and /vps subpaths.

Other contracts in core are ports rather than plug-ins: SqlExecutor (the store), IamPort, Clock, Notifier, LeaseProvider, SecretStore, BlobStore, CertificateAuthority, ImageSource and NodeAdapter. You replace them through their own options (database, iam, clock, notifier, secrets, pki), not through extensions; the configuration reference lists them.

Where each one plugs in

A module is the unit everything else hangs off. It can carry API groups, reconcilers, migrations, command kinds, NodeSpec sections, IAM catalog fragments, CLI commands, profiles and extensions (drivers, steps, scheduler plugins, attestors, sinks). The top-level options (drivers, providers, attestors, scheduler.plugins, sinks) register extensions that do not need a module of their own. Both paths end in the same registry and the same kind:id@version uniqueness check, and every consumer reads both: scheduler plugins a module lists join scheduler.plugins in the placer, and its event and audit sinks join sinks.events and sinks.audit.

import { betterCompute, defineSchedulerPlugin, defineSink } from 'better-compute';
import { acmeWidgets } from '@acme/bc-widgets'; // definePlugin({ id: 'acme-widgets', … })

export const compute = betterCompute({
  // …database, secret, baseURL, iam
  plugins: [acmeWidgets()],
  scheduler: { plugins: [defineSchedulerPlugin({ id: 'rack-spread', scorers: [/* … */] })] },
  sinks: {
    events: [defineSink({ kind: 'events', id: 'warehouse', async deliver(events) { /* … */ } })],
  },
});

What is stable

Better Compute is pre-1.0. The contracts in @better-compute/core froze at the end of phase P0 and change only by additive edits: new optional members in minor versions, and a new interface selected by version for anything breaking. PLAN.md §5.1 keeps every define* helper experimental until v1.0, so pin your versions.

Rules every extension follows

These hold for anything you write against the contracts, and the built-in modules follow them too:

1. Modules never import each other's internals. They meet through the ports on ModuleContext: the vps module books host capacity through ctx.capacity.reserve, not by importing @better-compute/capacity. The repository enforces the direction with scripts/check-deps.mjs.
2. IAM is never awaited inside a compute transaction. The envelope makes the one decision before your handler's transaction opens. Composite methods decide their sub-calls with ctx.check before they open a transaction.
3. Write state, events and work in one transaction. ctx.events.publish, ctx.work.enqueue, ctx.commands.enqueue and ctx.authz.upsert all take the caller's tx, so a rollback leaves nothing behind.
4. Business time comes from the database. SQL uses compute_now(), never now(); TypeScript uses ctx.clock. scripts/check-sql-now.mjs fails CI on a bare now() in packages/*/src.
5. Everything is retried. Reconcilers are level-triggered, sinks are at-least-once, commands carry idempotency keys. Write each piece so that running it twice changes nothing.

Conformance

A contract comes with a conformance suite: plain { name, run } cases you run against your implementation. The runner lives on its own subpath of @better-compute/core, so the root entry carries no test code:

import { runConformance } from '@better-compute/core/conformance';
import { providerConformanceCases } from 'better-compute/vps';
import { acmeCloudSubject } from './acme-cloud-subject'; // your provider, against recorded responses

const report = await runConformance(providerConformanceCases(), () => acmeCloudSubject());
// report: { passed: string[], failed: { name, error }[] }; a factory gives each case a fresh subject

storeConformanceCases() from @better-compute/postgres/conformance does the same for a SqlExecutor. The acceptance tests in tests/extensions/ register third-party-style plugins with zero edits to @better-compute/*; see walkthroughs.