The Plugin Seam

You asked whether the thing you have in mind is “plugins” or “composables”. They are two different axes, and conflating them is the first architectural mistake most people make.

Composability is about your own code: small pieces with clean interfaces that you assemble in different orders. A Unix pipeline is composable. React hooks are composable. itertools is composable. Composability is a property of a design, and the assembler is you, at build time, with a compiler checking your work.

Extensibility is about other people’s code: strangers add behaviour to a running system without editing it, without recompiling it, and often without you ever seeing what they wrote. That is what a plugin is. The assembler is the end user, at install time, and nothing is checking anyone’s work.

You want the second one. The first is a prerequisite: a system that is not composable internally cannot be made extensible externally, because there are no seams to hang anything on. But they are not the same problem, and extensibility brings a whole second set of concerns — trust, versioning, isolation, distribution, money — that composability never has to think about.

The one-sentence definition

That inversion is the whole trick. Everything else in this document is consequence: if code you did not write is going to be plugged into a socket at runtime, you now need a way to describe the socket (a contract), find what is plugged in (a registry), load it (a loader), call it at the right moments (extension points), and limit what it can do when you do (a boundary).

The neighbouring words, disambiguated

These get used interchangeably in blog posts and they should not be. The distinctions are about who calls whom and when the binding happens.

Whether it is 40 lines of Python or Figma’s entire runtime, every plugin system is built from the same five parts. If you can name all five in your design, you have a design. If you cannot, you have a global list of callbacks.

1. The contract

The shape of a valid plugin. A Python Protocol, a TypeScript interface, a JSON Schema for the manifest, or all three. It defines what a plugin declares about itself and what functions it must expose.

2. The registry

The in-memory map of what is currently loaded, keyed by extension point. Usually dict[str, list[Handler]]. Its persistent cousin — which plugins this tenant has installed, at which versions, with which settings — lives in your database and is a different thing; don’t merge them.

3. The loader

Turns a bundle on disk (or a URL, or a WASM blob) into a live object in the registry. This is where verification, version compatibility checks and error containment happen. A plugin that throws on load must not take down the host.

4. Extension points

The named moments in the host’s own flow where it stops and asks the registry “anyone want this?”. Naming and freezing these is 80% of the design work.

5. The capability boundary

What the plugin can reach. Enforced either by construction (a sandbox with no ambient access) or by convention (nothing stops it, please be nice). WordPress chose convention; Figma chose construction. That single choice determines almost everything else about your platform.

The sixth thing: lifecycle

Not a part so much as a state machine, but you will build it whether you plan to or not, so plan to. Every plugin moves through: discovered → installed → activated → running → deactivated → uninstalled, with upgraded and disabled-by-host as edges you will regret not having.

The two that people forget: uninstall must be able to clean up (WordPress has a dedicated uninstall.php for exactly this, run when the plugin’s code is otherwise gone), and the host must be able to disable a plugin unilaterally, without the plugin’s cooperation, ideally remotely. That second one is your kill switch, and the day you need it you will need it in minutes, not in a release cycle.

There are only about seven ways to let outside code participate in your flow. Every platform is a particular mix of them. Picking the wrong one for a given extension point is the source of most plugin-API pain, because the mechanism decides whether ordering matters, whether a plugin can veto you, and what happens when one of them is slow.

Choosing between them

Built up in the order you should actually build it. Each stage is useful on its own and none of them requires the next. The domain is a shopping cart, so the POS design in §11 has somewhere to land.

Stage 1 — The contract

Start with the data, not the callbacks. A plugin API is mostly a set of types that cross the boundary, and the single most valuable decision you will make is that those types are frozen, plain, serialisable DTOs and not your live ORM objects. Hand a plugin a SQLAlchemy model and you have just published your database schema as a public API.

from dataclasses import dataclass
from typing import Protocol, runtime_checkable

@dataclass(frozen=True, slots=True)
class Line:
    sku: str
    qty: int
    unit_cents: int          # integers. never floats for money.

@dataclass(frozen=True, slots=True)
class Cart:
    lines: tuple[Line, ...]
    subtotal_cents: int
    currency: str = "KES"

@dataclass(frozen=True, slots=True)
class Adjustment:
    """What a pricing plugin is allowed to produce: one labelled,
    signed, attributable line. Not a new total."""
    plugin_id: str
    label: str               # shown to the cashier and printed
    amount_cents: int        # negative = discount
    reason_code: str

@runtime_checkable
class PricingRule(Protocol):
    id: str
    def evaluate(self, cart: Cart, ctx: "Ctx") -> list[Adjustment]: ...

Stage 2 — The registry and the bus

Forty lines. Note the three production concerns baked in from the start: attribution (every handler knows which plugin it came from), containment (one plugin’s exception does not end the loop), and a time budget (a slow plugin gets named in your logs before it gets named in a support ticket).

import logging, time
from collections import defaultdict

log = logging.getLogger("pos.kernel")

class Kernel:
    def __init__(self):
        self._hooks: dict[str, list] = defaultdict(list)
        self._providers: dict[str, tuple[str, object]] = {}

    # --- registration -------------------------------------------------
    def on(self, point, fn, *, priority=50, plugin_id="core"):
        self._hooks[point].append((priority, plugin_id, fn))
        # sort by priority, then plugin_id: deterministic across restarts
        self._hooks[point].sort(key=lambda h: (h[0], h[1]))

    def provide(self, slot, impl, *, plugin_id):
        if slot in self._providers:
            prev = self._providers[slot][0]
            raise RuntimeError(f"{slot} already provided by {prev}")
        self._providers[slot] = (plugin_id, impl)

    # --- invocation ---------------------------------------------------
    def emit(self, point, payload, ctx):
        """Fire-and-forget. Return values ignored. Failures isolated."""
        for _, pid, fn in self._hooks[point]:
            try:
                fn(payload, ctx.for_plugin(pid))
            except Exception:
                log.exception("plugin=%s point=%s failed", pid, point)

    def collect(self, point, payload, ctx, *, budget_ms=15):
        """Gather contributions from every plugin. Host merges them."""
        out = []
        for _, pid, fn in self._hooks[point]:
            t0 = time.perf_counter()
            try:
                out.extend(fn(payload, ctx.for_plugin(pid)) or [])
            except Exception:
                log.exception("plugin=%s point=%s skipped", pid, point)
                continue                      # fail open: keep selling
            ms = (time.perf_counter() - t0) * 1000
            if ms > budget_ms:
                log.warning("plugin=%s point=%s slow %.1fms", pid, point, ms)
        return out

Stage 3 — The capability boundary

The critical move is that a plugin never imports anything of yours. It receives a ctx, and ctx is scoped to that plugin’s declared grants. This is capability-based security: no ambient authority, no globals, nothing reachable that was not handed over.

import logging
from dataclasses import dataclass, replace

log = logging.getLogger("pos.plugin")

class Denied(Exception): pass

@dataclass(frozen=True)
class Ctx:
    plugin_id: str
    grants: frozenset[str]
    _services: dict          # capability name -> live object
    _grants_by_plugin: dict  # plugin_id -> frozenset[str]

    def for_plugin(self, pid):
        return replace(self, plugin_id=pid,
                       grants=self._grants_by_plugin.get(pid, frozenset()))

    def use(self, capability):
        if capability not in self.grants:
            raise Denied(f"{self.plugin_id} did not declare {capability!r}")
        return self._services[capability]

    # cheap, always-granted things
    def log(self, msg, **kw):
        log.info("[%s] %s %r", self.plugin_id, msg, kw)

# in a plugin:
#   products = ctx.use("catalog:read")          # ok, declared
#   ctx.use("payments:capture").capture(...)    # Denied at runtime

Stage 4 — Discovery

Do not invent a plugin directory and scan it with importlib.util.spec_from_file_location. Python already has a standard, tooling-supported answer: entry points. A plugin is just a package that declares itself in a named group; pip install is the installer; the environment is the registry.

[project]
name = "pos-happy-hour"
version = "1.2.0"
dependencies = ["pos-sdk>=2.3,<3.0"]     # host API compat range

[project.entry-points."pos.plugins.v2"]
happy_hour = "pos_happy_hour:register"

from importlib.metadata import entry_points, version

HOST_API = "pos.plugins.v2"     # the group name IS the major version

def load_all(kernel, enabled: set[str]):
    loaded = {}
    for ep in entry_points(group=HOST_API):
        if ep.name not in enabled:          # tenant opted in?
            continue
        try:
            register = ep.load()            # imports the module
            api = PluginApi(kernel, plugin_id=ep.name)
            register(api)                   # plugin wires itself up
            loaded[ep.name] = version(ep.dist.name)
        except Exception:
            log.exception("plugin=%s failed to load; skipping", ep.name)
    return loaded

Stage 5 — A plugin, in full

from pos_sdk import Adjustment

MANIFEST = {
    "id": "happy_hour",
    "api": "2.x",
    "grants": ["catalog:read", "clock:read"],
    "settings": {
        "start_hour": {"type": "int", "default": 16},
        "percent":    {"type": "int", "default": 10},
    },
}

def register(api):
    api.collect("pricing.evaluate", evaluate, priority=20)
    api.on("shift.closed", report, priority=50)

def evaluate(cart, ctx):
    cfg  = ctx.settings()                      # tenant's saved values
    hour = ctx.use("clock:read").now().hour
    if not (cfg["start_hour"] <= hour < cfg["start_hour"] + 2):
        return []
    drinks = {l.sku for l in cart.lines
              if ctx.use("catalog:read").category(l.sku) == "beverage"}
    if not drinks:
        return []
    base = sum(l.qty * l.unit_cents for l in cart.lines if l.sku in drinks)
    return [Adjustment(
        plugin_id="happy_hour",
        label=f"Happy hour −{cfg['percent']}%",
        amount_cents=-(base * cfg["percent"]) // 100,
        reason_code="HAPPY_HOUR",
    )]

def report(shift, ctx):
    ctx.log("happy hour ran", shift=shift.id)

Beyond in-process: the same host, over a pipe

When plugins stop being trusted, the kernel above barely changes — only the thing behind the handler does. This is the shape of the Language Server Protocol, of Figma’s two realms, and of every “plugin runs in a sandbox” system:

import json, subprocess
from dataclasses import asdict

class RemotePlugin:
    """Same interface as an in-process plugin. Different address space."""
    def __init__(self, plugin_id, argv, timeout=0.05):   # 50ms budget
        self.id, self.timeout = plugin_id, timeout
        self.proc = subprocess.Popen(
            argv, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
            text=True, bufsize=1,
            env={},                       # no inherited secrets
        )

    def evaluate(self, cart, ctx):
        req = {"point": "pricing.evaluate", "cart": asdict(cart)}
        self.proc.stdin.write(json.dumps(req) + "\n")
        line = _read_with_timeout(self.proc.stdout, self.timeout)
        if line is None:
            ctx.log("timed out, contribution dropped")
            return []                     # fail open, on time, every time
        return [Adjustment(**a) for a in json.loads(line)["adjustments"]]

On the backend a plugin contributes behaviour. On the frontend it contributes rendered output inside a layout it does not own, which introduces three problems the backend never has: someone else’s component can crash your tree, block your main thread, or read your DOM.

The slot registry

Keep the registry outside React. Plugins register at module-evaluation time, before any render happens; React just reads. A Map in a module is the whole thing.

const registry = new Map();   // slotName -> Contribution[]

export function contribute(slot, { id, component, priority = 50, when }) {
  const list = registry.get(slot) ?? [];
  list.push({ id, component, priority, when });
  list.sort((a, b) => a.priority - b.priority || a.id.localeCompare(b.id));
  registry.set(slot, list);
}

export function contributionsFor(slot) {
  return registry.get(slot) ?? [];
}

// The host declares its slots as data, so they can be documented,
// diffed, and frozen as a public API surface.
export const SLOTS = {
  "sale.actions":     { props: ["cart", "actions"] },
  "sale.line.badge":  { props: ["line"] },
  "receipt.footer":   { props: ["sale"] },
  "settings.page":    { props: ["pluginId"] },
};

The slot component

Three non-negotiables: an error boundary per contribution (not per slot — one bad plugin must not blank out the other three), a stable key, and props that are DTOs. Never pass a setState function, a store instance, or anything from which the plugin could reach the rest of your app.

import React from "react";
import { contributionsFor } from "../sdk/slots";

class Boundary extends React.Component {
  state = { dead: false };
  static getDerivedStateFromError() { return { dead: true }; }
  componentDidCatch(err, info) {
    telemetry.pluginCrash(this.props.pluginId, err, info);  // attribute it
  }
  render() { return this.state.dead ? null : this.props.children; }
}

export function PluginSlot({ name, ...props }) {
  const items = contributionsFor(name);
  if (!items.length) return null;
  return (
    <>
      {items.map(({ id, component: C, when }) =>
        when && !when(props) ? null : (
          <Boundary key={id} pluginId={id}>
            <C {...props} />
          </Boundary>
        )
      )}
    </>
  );
}

// in the host's own UI:
// <PluginSlot name="sale.actions" cart={cartDto} actions={safeActions} />

A plugin, and what it is allowed to do

import { contribute } from "pos-sdk/slots";
import { useHostQuery } from "pos-sdk/data";

function LoyaltyBadge({ line }) {
  // useHostQuery goes through the SDK, which enforces the plugin's
  // declared scopes and rate limits. There is no bare fetch() here.
  const { data } = useHostQuery("loyalty.points", { sku: line.sku });
  if (!data?.points) return null;
  return <span className="pos-badge">+{data.points} pts</span>;
}

contribute("sale.line.badge", {
  id: "loyalty.badge",
  component: LoyaltyBadge,
  priority: 30,
  when: ({ line }) => line.qty > 0,
});

Loading plugin code that wasn’t in your bundle

This is where frontend plugin systems get genuinely hard. Your bundler resolved imports at build time; plugin code arrives at run time. The three real options:

The iframe bridge, in miniature

When the plugin is untrusted, this is the pattern. The child gets a fixed message vocabulary and no reference to anything in the parent; every call is validated on arrival as if it came from the internet, because effectively it did.

const ALLOWED = new Set(["ui.resize", "data.query", "cart.addLine"]);

export function PluginFrame({ pluginId, src, grants, height }) {
  const ref = React.useRef(null);

  React.useEffect(() => {
    function onMessage(e) {
      // 1. Is it even from our frame?
      if (e.source !== ref.current?.contentWindow) return;
      // 2. Is it from the origin we sandboxed it to?
      if (e.origin !== new URL(src).origin) return;
      const { type, id, payload } = e.data ?? {};
      // 3. Is it a verb this plugin declared and we granted?
      if (!ALLOWED.has(type) || !grants.includes(type)) {
        return reply(id, { error: "denied" });
      }
      handle(pluginId, type, payload).then(r => reply(id, r));
    }
    window.addEventListener("message", onMessage);
    return () => window.removeEventListener("message", onMessage);
  }, [pluginId, src, grants]);

  return (
    <iframe
      ref={ref}
      src={src}                       // separate origin: plugins.pos.app
      title={pluginId}
      height={height}
      sandbox="allow-scripts"         // NOT allow-same-origin
      referrerPolicy="no-referrer"
      csp="default-src 'self'; connect-src https://api.pos.app"
    />
  );
}

WordPress runs a very large share of the web on a plugin architecture designed in 2004 that has essentially never changed. It is worth studying precisely because it took one position — total openness — to its absolute limit, and the consequences of that position are now all visible at once.

The whole mechanism is one global array

Every hook in WordPress lives in a single global, $wp_filter, keyed by hook name then by priority. add_action() is literally a call to add_filter(); do_action() is apply_filters() with the return value thrown away. There is one mechanism, and actions are the degenerate case of it.

$wp_filter = [
  'the_content' => [
     10 => [ 'wpautop' => [...], 'do_shortcode' => [...] ],
     20 => [ 'my_plugin_add_cta' => [...] ],
  ],
];

function apply_filters( $tag, $value, ...$args ) {
    foreach ( $wp_filter[$tag] as $priority => $callbacks ) {
        foreach ( $callbacks as $cb ) {
            $value = call_user_func_array( $cb['function'],
                       array_slice( [$value, ...$args], 0, $cb['accepted_args'] ) );
        }
    }
    return $value;        // do_action() is this, ignoring $value
}

<?php
/**
 * Plugin Name: Coffee Upsell
 * Version:     1.4.0
 * Requires PHP: 7.4
 */

// 1. FILTER — transform a value the host is about to use
add_filter( 'the_content', function ( $content ) {
    return $content . '<p class="upsell">Try our new roast.</p>';
}, 20 );                       // priority 20: after wpautop at 10

// 2. ACTION — react to a moment, return value ignored
add_action( 'woocommerce_order_status_completed', function ( $order_id ) {
    my_upsell_send_followup( $order_id );
}, 10, 1 );

// 3. LIFECYCLE — one-time setup, and its matching teardown
register_activation_hook( __FILE__,   'my_upsell_create_tables' );
register_deactivation_hook( __FILE__, 'my_upsell_clear_cron' );
// uninstall.php in the plugin root runs when the plugin is deleted

What WordPress gets right

• Hook everything, by default. Core WordPress calls apply_filters() on almost every value it computes before using it. The culture is that if you did not make it filterable, that is a bug. This is why the ecosystem can do things core never imagined.
• Priority as a first-class concept. An integer, defaulting to 10, low runs first, with room to insert on either side. Crude, obvious, and it works.
• Fanatical backward compatibility. Plugins written for WordPress 2.x still load. Deprecated functions are kept as shims for a decade. This is expensive and it is the reason the ecosystem exists.
• Lifecycle hooks including uninstall, run in a context where the plugin’s own code has already been removed — a detail most systems forget.

What it gets wrong, and what that costs

• No capability boundary whatsoever. A plugin is PHP running in your process with your database credentials, your filesystem and your network. It can read every password hash, modify any other plugin’s behaviour, and rewrite core functions. “Least privilege” is not expressible.
• Therefore: the ecosystem is the attack surface. The overwhelming majority of WordPress compromises come through plugins — usually an abandoned one, often through a supply-chain takeover of a popular free plugin. There is no sandbox to fall back on, so the mitigation is entirely social: reviews, scanners, and hoping people update.
• Hook order is an undocumented public API. Because filters thread a value through a chain, plugin A’s output is plugin B’s input, and priority collisions produce bugs no one owns.
• No versioned API surface. There is no apiVersion. Compatibility is discovered by installing it and seeing whether the site goes white.

Distribution and money

The wordpress.org plugin directory is free-only: no payment rails, no revenue share, no billing API. The result is an entire economy that lives outside the marketplace — a free plugin in the directory acts as distribution, and monetisation happens through a license key that phones home to the vendor’s own server for updates and pro features. This works, but it means the platform has no leverage over quality, no ability to enforce refunds, and no visibility into what the paid version of a plugin actually does after it self-updates from a third-party URL.

Figma had the opposite constraint. WordPress plugins run on a server the site owner controls; Figma plugins run in your browser tab, inside a design tool holding other people’s confidential work, and they are installed with one click from a public marketplace. Convention was never going to be enough.

Why QuickJS, and the lesson in the history

Figma’s first attempt used Realms — a proposal for creating a fresh JavaScript global object inside the same engine, with dangerous globals removed. It was found to be insecure quickly: sharing one heap and one engine with untrusted code means a single missed prototype path or an engine bug is a full escape. Soft isolation inside the same JS heap is a code-organisation tool, not a security boundary.

The replacement is more radical: compile QuickJS, a small complete JavaScript interpreter written in C, to WebAssembly, and run the plugin’s JavaScript inside that interpreter. The plugin’s code and Figma’s code now execute in genuinely different machines. The plugin cannot reach anything that was not explicitly marshalled across the boundary, because there is nothing to reach — its entire universe is the WASM linear memory.

{
  "name": "Colour Auditor",
  "id": "1234567890",
  "api": "1.0.0",
  "main": "dist/code.js",
  "ui":   "dist/ui.html",
  "editorType": ["figma", "figjam"],
  "permissions": ["currentuser"],
  "networkAccess": {
    "allowedDomains": ["https://api.mycompany.com"],
    "reasoning": "Fetches the shared brand palette."
  },
  "documentAccess": "dynamic-page"
}

// ---- code.ts : runs in QuickJS. Sees the document, not the network.
figma.showUI(__html__, { width: 300, height: 400 });

figma.ui.onmessage = async (msg) => {
  if (msg.type === "recolour") {
    for (const node of figma.currentPage.selection) {
      if ("fills" in node) node.fills = [{ type: "SOLID", color: msg.rgb }];
    }
    figma.notify(`Recoloured ${figma.currentPage.selection.length} layers`);
  }
};

// hand data OUT to the UI so the UI can do the networking
figma.ui.postMessage({ type: "selection", count: figma.currentPage.selection.length });

// ---- ui.html : runs in the iframe. Sees the network, not the document.
window.onmessage = async (e) => {
  const msg = e.data.pluginMessage;                 // always wrapped
  if (msg.type === "selection") render(msg.count);
};
const palette = await fetch("https://api.mycompany.com/palette").then(r => r.json());
parent.postMessage({ pluginMessage: { type: "recolour", rgb: palette.brand } }, "*");

What to steal from Figma

• Split the plugin by capability, not by convenience. Logic realm and UI realm exist because they need different powers. If you find yourself wanting to give one component both document access and arbitrary network access, that is the design telling you something.
• Make the boundary structural. A boundary enforced by “we removed the dangerous globals” will be defeated. A boundary enforced by “there is no shared address space” will not.
• Declare network egress in the manifest. Cheap to implement, enormous reduction in the realistic threat model, and it gives your review process something concrete to review.
• Design the API for batching from day one. Every cross-boundary call has a fixed cost; an API of fine-grained synchronous property reads will be slow forever and you will not be able to change it later.

Two separate questions that people merge and shouldn’t. Where does the code execute? is an isolation and latency question. Where does the code come from? is a supply-chain and operations question. You need an answer to both, and for a POS you may need different answers for different kinds of plugin.

Five execution topologies

Ordered from least to most isolated. Every real platform picks two or three of these and routes different extension points to different ones.

The publish-to-run pipeline

This is the part that separates a plugin API from a plugin platform. Most of the engineering is here, and none of it is glamorous.

The registry service, concretely

manifest schema

A versioned JSON Schema, published, with a CLI that validates against it before submission. Reject unknown fields loudly — forward compatibility is not free and pretending otherwise creates accidental API.

artifact store

Object storage keyed by content hash, never by version name. Immutable, cheap to CDN, trivially deduplicated, and it makes “did this change?” a byte comparison.

version index

Which versions exist, which host API ranges each supports, which are yanked. This is the only mutable part, and it is a small, boring, extremely available service.

signing

You sign on publish; the host verifies on load. Publisher keys are separate from platform keys, so you can revoke one developer without invalidating everything.

install records

Per tenant: plugin id, pinned version, granted scopes, settings blob, enabled flag, installed-by. This is the table your support team will live in.

revocation feed

Signed, short-TTL, cached everywhere, checked on every plugin load. This is your kill switch and it must work when your API is down.

Multi-tenancy and the noisy plugin

Once plugins run in your infrastructure, one tenant’s bad plugin is everyone’s latency. The controls, roughly in order of how quickly you will need them:

• A per-invocation budget, enforced by the runtime, not requested politely. WASM engines give you fuel (an instruction counter) and epoch interruption; processes give you timeouts and SIGKILL.
• A circuit breaker per plugin per tenant. Five timeouts in a minute and the plugin is skipped for the next ten, with a visible notice. Do not make a human decide this at 2am.
• Attribution in every trace and every log line. plugin_id and plugin_version as first-class span attributes. Without this you cannot tell a plugin problem from a platform problem, and you will spend a quarter learning that lesson.
• Concurrency caps and instance pooling. WASM instances are cheap to create from a pre-compiled module; keep the compiled module cached and instantiate per call so plugins cannot accumulate state between invocations.
• A staged rollout for plugin updates, the same as for your own code: 1% of tenants, then 10%, then all, with automatic rollback on error-rate regression.

The security question is not “is this plugin malicious?” It is “what is the worst thing that happens if it is?” — and the honest answer for an in-process plugin system is everything you can do, it can do. Sandboxing is the work of making that answer smaller.

Four adversaries, not one

Note where the weight sits. Almost everyone designs against the first row and gets hurt by the second and third. The second row is why the permission diff between version N and N+1 is the single most valuable automated check you can build: a loyalty plugin that suddenly requests payment scopes should stop the release, automatically, at 3am, without a human.

The root cause: ambient authority

In most languages, any code can reach anything the process can reach: open files, make sockets, read environment variables, import your database module. That is ambient authority — power that comes from being in the room rather than from being handed something. Capability security is the inverse: a plugin can only act on objects it was given, and there is nothing to get hold of otherwise.

Every real sandbox is a way of removing ambient authority. They differ in how convincingly.

Metering, concretely

The property that makes WASM the right answer for a critical path: you can bound execution in instructions, not just seconds, so a plugin’s cost is deterministic and reproducible rather than dependent on how loaded the machine is.

from wasmtime import Engine, Store, Module, Linker, Config, FuncType, ValType

cfg = Config()
cfg.consume_fuel = True            # bound work in instructions
cfg.epoch_interruption = True      # and in wall-clock, as a backstop
engine = Engine(cfg)

# Compile ONCE, at install time. Cache the artifact.
module = Module(engine, wasm_bytes)

def run(module, cart_json, *, fuel=5_000_000, mem_mb=16):
    store = Store(engine)
    store.set_fuel(fuel)
    store.set_limits(memory_size=mem_mb * 1024 * 1024)

    linker = Linker(engine)
    # The plugin's ENTIRE universe is what we define here.
    # No WASI, so: no filesystem, no clock, no sockets, no randomness.
    linker.define_func("host", "log", FuncType([ValType.i32(),
                                                ValType.i32()], []), _log)
    instance = linker.instantiate(store, module)

    try:
        return instance.exports(store)["evaluate"](store, cart_json)
    except Exception:                # includes fuel exhaustion + traps
        metrics.incr("plugin.trapped")
        return []                    # fail open. the sale continues.

The rest of the checklist

When plugins touch money

The moment a third party depends on your extension points, your internal refactoring freedom is gone. This is the tax on having an ecosystem, and the entire discipline of versioning is about paying it in instalments rather than all at once.

Version the API, not the product

Your product ships continuously at whatever version marketing likes. Your plugin API is a separate, slow-moving, semantically versioned artifact with its own changelog. Figma has "api": "1.0.0" in every manifest; Python entry-point groups can carry it in the group name; VS Code has engines.vscode. Every plugin declares the range it works against, and the host refuses to load anything outside it — loudly, at install time, with a message the user can act on.

// plugin manifest
{ "id": "happy_hour", "version": "1.4.0", "hostApi": "^2.3" }

// host advertises, at runtime
{ "hostApi": "2.7.1",
  "supported": ["1.x (deprecated, removal 2027-01-01)", "2.x"],
  "features": ["pricing.evaluate", "receipt.blocks", "offline.queue.v2"] }

What counts as a breaking change (it is more than you think)

The mechanics that make migration survivable

• Additive-only within a major. New hooks, new optional fields, new capabilities. Never a changed meaning for an existing name — introduce pricing.evaluate.v2 rather than redefining pricing.evaluate.
• Expand–migrate–contract. Ship the new hook, run both for a deprecation window with the old one adapted onto the new one, publish usage numbers, then remove. The adapter layer is where all the ugliness lives, and it should be host code that you can delete in one commit.
• Runtime deprecation warnings, attributed. When a plugin calls something deprecated, log plugin_id, version and the removal date — and surface it in the developer’s dashboard, not only in your logs. Most plugin authors do not read your changelog; they do read the email that says their plugin breaks in 90 days.
• A published contract test suite. Ship pytest --plugin-conformance that a developer runs in their own CI against a fake host. It is your API spec in executable form, it catches breakage before you do, and it makes “we tested against the new version” a checkbox rather than a promise.
• Canary against the real ecosystem. Before a host release, run the top 200 installed plugins against it in a harness. This is the single highest-value piece of platform infrastructure after the kill switch, and almost nobody builds it early enough.
• A stated support policy. “Two major API versions, minimum 12 months of overlap, 90 days’ notice for deprecations.” Write it down and publish it. Developers will invest in a platform whose breakage schedule is predictable and will not invest in one whose isn’t.

A plugin API is a technical artifact. A plugin ecosystem is a two-sided market, and it fails for market reasons far more often than for technical ones — usually because nobody could make a living in it.

The cold-start problem, and the only reliable answer

Developers build for platforms with users; users come to platforms with plugins. The way out is to build your own features on the public plugin API and ship them as plugins. This does three things at once: it proves the API is powerful enough to build real things, it forces you to feel every ergonomic paper cut before strangers do, and it populates the catalogue on day one. If your own team needs private hooks to build the core features, external developers will hit that wall on their second afternoon and leave.

The corollary: publish the source of a handful of your first-party plugins. The most common first act of a plugin developer is copying an existing plugin that does something similar.

Discovery, install, consent

• Ranking is policy, and everyone knows it. Installs, retention, review score, support responsiveness, and recency of update — weight them explicitly and publish the weights. An opaque ranking algorithm in a marketplace with paid apps generates suspicion that costs you more than the flexibility gains.
• The consent screen is a security control. It should list scopes in the user’s language (“read your product catalogue”, not catalog:read), name the network domains, and highlight anything new when a plugin update requests more than it had. Most users click through, so the value is in what it forces developers to justify, and in what it gives you to point at afterwards.
• Make uninstall genuinely clean. Data deleted or exported, tokens revoked, webhooks removed, scheduled jobs cancelled. Users install more freely on platforms where uninstall is trustworthy.

Who charges what

Why you want to own billing

Letting developers charge through their own Stripe account is much less work and it is usually a mistake for a business tool. When the platform owns billing you get: one invoice for the merchant (a real purchase-decision unlock for a shop owner with fourteen line items already), trials and proration handled once and correctly, refunds and chargebacks you can actually enforce, dunning that does not silently disable a store’s tax plugin mid-shift, and a usage-based billing primitive that lets developers charge per transaction — which for a POS is the natural pricing model and is very hard for a small developer to build alone.

Pricing models worth supporting from the start: free, flat subscription, tiered by store count or volume, and usage-based. One-time purchase looks attractive and ages badly for software that must be maintained against a moving API.

The tension nobody escapes

Now the actual question. A point-of-sale system is an unusually demanding host: it is a microkernel by nature, it handles money, it must keep selling when the network dies, it drives physical hardware, and in many countries the receipt it prints is a legally regulated document. Every one of those constraints changes the plugin design.

The shape: three planes, two plugin runtimes

The invariant that everything else hangs off

The extension point catalogue

This table is the actual product. Write it before you write any code, review it like a schema migration, and treat every row as a promise you will be keeping in five years. Six columns, and none of them are optional: a point without a declared budget and failure policy is a future incident.

A plugin, end to end

{
  "id": "co.dukalink.tuesday-coffee",
  "name": "Tuesday Coffee Club",
  "version": "1.4.0",
  "hostApi": "^2.3",
  "tier": "verified",

  "runtimes": {
    "till":  { "module": "dist/rules.wasm", "sha256": "9f2c...", "fuel": 2000000 },
    "ui":    { "entry":  "dist/ui.js" },
    "cloud": { "webhook": "https://api.dukalink.co/pos/events" }
  },

  "contributes": {
    "pricing.evaluate": { "priority": 20, "runtime": "till" },
    "receipt.blocks":   { "priority": 60, "runtime": "till" },
    "sale.completed":   { "runtime": "cloud" },
    "ui.slot.sale.line.badge": { "runtime": "ui" },
    "settings.page":    { "runtime": "ui" }
  },

  "scopes": ["cart:read", "catalog:read", "receipt", "ui", "webhooks"],
  "networkAccess": {
    "allowedDomains": ["https://api.dukalink.co"],
    "reasoning": "Posts completed sales to the loyalty ledger."
  },

  "settingsSchema": {
    "day":      { "type": "enum", "values": ["mon","tue","wed"], "default": "tue" },
    "percent":  { "type": "int",  "min": 1, "max": 30, "default": 10 },
    "category": { "type": "categoryRef", "default": null }
  },

  "limits": { "maxDiscountPercent": 30, "maxAdjustmentsPerSale": 3 },
  "offline": { "required": true, "maxCatalogStalenessDays": 30 }
}

from pos_sdk import Adjustment, ReceiptBlock, hook

@hook("pricing.evaluate")
def evaluate(cart, env):
    """env carries everything the sandbox cannot fetch for itself:
       env.local_date, env.settings, env.catalog (a frozen snapshot)."""
    cfg = env.settings
    if env.local_date.weekday_name != cfg["day"]:
        return []

    eligible = [l for l in cart.lines
                if env.catalog.category_of(l.sku) == cfg["category"]]
    if not eligible:
        return []

    base = sum(l.qty * l.unit_cents for l in eligible)
    return [Adjustment(
        label       = f"{cfg['day'].title()} club −{cfg['percent']}%",
        amount_cents= -(base * cfg["percent"]) // 100,   # int maths only
        reason_code = "TUESDAY_CLUB",
        applies_to  = [l.id for l in eligible],
    )]

@hook("receipt.blocks")
def receipt(sale, env):
    if not any(a.reason_code == "TUESDAY_CLUB" for a in sale.adjustments):
        return []
    return [ReceiptBlock.text("You saved with Tuesday Club ☕",
                              align="center", size="small")]

import { contribute, useSaleContext } from "pos-sdk/ui";

function ClubBadge({ line }) {
  const { adjustments } = useSaleContext();          // DTO, read-only
  const hit = adjustments.find(
    a => a.reason_code === "TUESDAY_CLUB" && a.applies_to.includes(line.id)
  );
  if (!hit) return null;
  return <span className="pos-badge pos-badge--save">club</span>;
}

contribute("ui.slot.sale.line.badge", {
  id: "tuesday-coffee.badge",
  component: ClubBadge,
  priority: 40,
});

Offline is the architecture, not a feature

• Bundles are pre-staged like firmware. The till holds the signed WASM modules and UI bundles for every enabled plugin, pinned by content hash, verified on load, and usable for weeks with no connectivity. Updates download in the background and take effect at the next shift open — never mid-sale.
• The sale record pins the plugin set. Each completed sale stores {plugin_id, version, sha256} for every contribution it received. Two months later you can replay that exact cart through those exact modules and reproduce the total to the cent. This is the audit story, the dispute story and the bug-report story all at once.
• Sync is an idempotent event log. The till appends immutable events with a client-generated ULID; the cloud is a replay of them. Cloud-side plugins therefore see an ordered, at-least-once stream and must be idempotent — say this loudly in your developer docs, because it is the single most common cause of duplicated loyalty points and double-posted invoices.
• Revocation works offline, carefully. The device carries a signed catalogue snapshot with an issue timestamp. If a plugin is revoked, it stops loading everywhere as the snapshot propagates. If the snapshot itself goes stale past maxCatalogStalenessDays, disable non-certified plugins and keep selling — a stale revocation list must never be able to close a shop.
• Conflicts are business rules, not merge rules. Inventory that went negative because two tills sold the last item offline is not a data conflict to resolve automatically; it is an oversell to surface to a human, with both sales intact.

Trust tiers

Almost all of your ecosystem should be tier 1, and that is a success, not a limitation. Tier 1 costs you nothing to run, carries no risk to a sale, and is where the long tail of integrations lives. Tier 3 should have perhaps a dozen members and each one should have a phone number you can call.

What to build, in what order

Resist building “a plugin system”. Build the three extension points you have a named customer for, and let the system emerge from the second and third.

1. Cloud events + a REST API. sale.completed, shift.closed, inventory.changed as signed, retried webhooks. Zero runtime risk, zero infrastructure to run, unblocks accounting and ecommerce integrations immediately — which is what shops ask for first.
2. UI slots. React contributions with error boundaries. Visible, satisfying for developers, and it forces you to define your DTOs.
3. The settings-schema-driven admin. Host-rendered forms. Removes most of the reason a plugin would need custom UI at all.
4. The WASM pricing runtime. Only now, and only for pricing.evaluate. This is where you earn your architecture — the money invariant, contributions, budgets, replay.
5. Provider registries for tax and tender, with your own built-ins written against the same public interfaces.
6. The certified tier for fiscal and hardware, once a real regulatory requirement forces it. Not before.

Ship the kill switch, the plugin-attributed tracing, and the contract test suite alongside step 1, not step 4. Those three are the difference between a platform you can operate and a platform that operates you.

Before you publish an extension point

Six questions. If you cannot answer all six, the point is not ready.

Principles worth holding to

• Start with three hooks, not thirty. Additions are cheap forever; removals are impossible after the first thousand installs.
• Build your own features on the public API. If your team needs a private hook, your API is not finished.
• Data in, data out. Frozen DTOs across the boundary. Never an ORM object, a store instance, a live connection, or a callback into your internals.
• Declarative for the boring, imperative for the interesting. Manifests for settings, menus, permissions and metadata; code only where behaviour genuinely varies. Declarative contributions can be validated, diffed, rendered and reviewed without running anything.
• Attribute everything. Every log line, span, error and side effect carries plugin_id and version. Cheap on day one, impossible to retrofit.
• Design the failure before the feature. For each point, what happens when the plugin is slow, wrong, or gone.
• Version from the very first release, even when there is exactly one plugin and you wrote it.

The pitfalls, in the order people hit them

Ambient authority

Power a piece of code has merely by existing in the process — open a file, make a socket, import a module. The thing capability security removes.

Capability

An unforgeable handle that both names a resource and grants the right to use it. If you weren’t handed one, you cannot act on it.

Content addressing

Storing an artifact under the hash of its bytes, so a name can never come to mean different content.

Extension point

A named, documented moment in the host’s flow at which plugin code is invited to participate.

Fuel / epoch interruption

WASM mechanisms that bound execution in instructions and in wall-clock time, so a plugin’s cost is deterministic rather than machine-dependent.

Hyrum’s Law

With enough users, every observable behaviour of your system is depended on by somebody, whatever you documented.

Idempotency key

A client-generated identifier that lets a retried operation be recognised as the same operation. The backbone of offline sync.

Manifest

Declarative metadata describing a plugin: identity, version, compatibility, contributions, permissions, settings schema.

Microkernel architecture

A minimal core plus plug-in modules carrying the domain behaviour. The formal name for what this document is about.

Sherlocking

A platform shipping natively what a successful third-party plugin already did, ending that plugin’s business.

Slot

A named UI region into which plugins contribute components.

Trust tier

A class of plugin with a defined review bar, runtime and set of reachable capabilities.