2. Contracts — @get-bb/plugin-sdk/contracts

@get-bb/plugin-sdk/contracts is what a plugin's contracts module imports (02 §9). It is browser-safe: no Node import reaches the entry, and the app tier loads it through the import map. It adds no runtime of its own; defineService, method and defineEvent wrap @bb/kernel-contract and @bb/kernel-core with the SDK's pre-checks, and everything else is a re-export. A contracts module exports defineService objects, defineEvent objects, defineHostCommands objects and declare module merges; it contains no handlers. 02 §9 places renderText in the tier entry; the built example keeps it on the method in the contracts module, and contractJsonOf drops it. The built source wins over the spec where they differ; each row says so.

Path shorthand below: <pkg>:<file> means packages/<pkg>/src/<file>. Every value and type the lock lists for this entry appears in a table in this section.

2.1 The published-contracts convention

A sibling plugin imports only this subpath; bb plugin build fails any other import of a sibling (D19, plugin-build:externals.ts). bb plugin build imports the module named by package.json#bb.contracts, runs contractJsonOf (§2.9) and writes dist/contract.json; nothing is written back into package.json (03 §2.4).

// examples/plugins/hello-slot/src/contracts.ts (abridged)
export const greeter = defineService({
  id: "hello-slot/greeter", version: "1.0.0", summary: "Greet by name and count greetings",
  cli: { group: ["hello"] },
  methods: {
    greet: method({
      kind: "query", summary: "Greet someone by name",
      input: z.strictObject({ name: nameSchema, salutation: z.string().min(1).max(32).default("Hello") }),
      output: greetingSchema, expose: { tool: true },
      cli: { fields: { name: { positional: 0 } }, examples: [{ argv: "bb hello greet bb", note: "prints `Hello, bb!` and the counter" }] },
      tool: { presentation: { label: { pending: "Greeting…", completed: "Greeted" }, icon: "hello-slot/wave", intent: "generic" } },
      renderText: (g) => `${g.greeting} (count ${g.count})`,
    }),
    count: method({ kind: "mutation", summary: "Record a greeting in the plugin's data.db counter",
      input: z.strictObject({ name: nameSchema }), output: greetingSchema, cli: { fields: { name: { positional: 0 } } } }),
  },
});

2.2 defineService / defineContract and method

MethodDef fields, as method() and defineService fill them (kernel-contract:define.ts):

invalid_contract is thrown at definition time for: a summary outside 1–80 chars; command on a non-mutation; blocking.maxMs outside 1..3_600_000; resumable off a stream; path off a custom method or off a kernel service; tool.instructions over 4096 bytes; auth: "none" on a non-local mutation; expose.tool without tool.presentation, tool without expose.tool, or expose.tool on custom; a non-strict input root; a cli.fields key that is not an input property; a multi-letter alias; a repeated positional; variadic on a non-positional or non-array field, or more than one; an errors code outside <pluginId>/<snake> or status outside 4xx/5xx; a tool name outside [a-zA-Z0-9_-]+; a service id not <pluginId>/<kebab-service>; a CLI group deeper than two levels; a non-semver version; multi without factsKey + facts; factsKey without multi; a multi contract with a mutation (kernel-core, D2).

2.3 Handles and handlers

2.4 Events: defineEvent

// hello-slot: the merge, then the definition the server tier passes to ctx.realtime.declare / events.define
declare module "@get-bb/plugin-sdk/contracts" {
  interface Events { "hello-slot/greeted": EventDecl<GreetedPayload, "emit"> }
}
export const greeted = defineEvent({
  name: "hello-slot/greeted", mode: "emit", payload: greetedPayloadSchema, scope: "server",
  wire: { to: ["client"], key: null },
});

2.5 Commands: defineCommand

2.6 Host commands: defineHostCommands

export const helloHost = defineHostCommands({
  id: "hello-slot",
  commands: { "host-greet": { input: z.strictObject({ name: nameSchema }), output: hostGreetingSchema } },
});

2.7 Kernel hook service contracts

These are kernel-core ServiceContract objects (not ServiceDefs); inject them by object. All are version 1.0.0.

2.8 Errors, envelope, actors, JSON

2.9 contract.json and the catalog

2.10 The remaining declaration-merging hooks