Skip to main content

Versioned kernel contracts

The kernel exposes six versioned contracts. Each contract id names one public surface an extension builds against, versioned as major.minor by a constant in src/plugins/contract-versions.ts. Versions are compiled into the host, so they are reliable even when the host version string is not. All ids, constants and the compat checker are re-exported from wednesdayai/plugin-sdk.

Versioned contracts

Each root type carries a direction, and the snapshot records it per entry:
  • provided — core hands the type to you, so core may add members to it freely without breaking you.
  • implemented — you implement or construct the type, so a new required member or a changed signature in core would break your implementation.
The exact per-type split lives in scripts/contract-surface/roots.ts. The gateway contract is special: its major equals PROTOCOL_VERSION in src/gateway/protocol/schema/protocol-schemas.ts, because the wire protocol between clients and the gateway is observable outside the plugin boundary.

Delayed release and consumer-dispatched claims (sdk 2.36, plugin 2.8)

For deployment roles (ADR 1168, dev-docs/adr/1168-postgres-multi-writer-mechanism.md), the bus-work surfaces gained two additive members:
  • Backbone.release(workId, opts?) and BusWorkDispatcherOptions.backend.release(workId, opts?) accept { availableAt?: Date }: the released item returns to pending and is not claimable before availableAt. Without opts, release behaves exactly as before.
  • Optional claimDispatched(topic, consumerId, leaseMs) on Backbone and the bus-work backend claims only consumer-dispatched agent.turn items (Postgres only; absent elsewhere).
  • Session-run recovery modes gain "lease" (visible through PluginRuntime.sessions): runs executed by the runner consumer, which startup recovery skips because work-lease reclaim owns them.

Channel connecting flag (sdk 2.39, plugin 2.9)

ChannelAccountSnapshot and a channel’s status.defaultRuntime gain optional connecting?: boolean. A channel sets it while a connection handshake is in progress; wednesdayai channels status then prints connecting for a running account instead of disconnected. Without the flag, a running account that is not connected still prints disconnected, with the lastDisconnect code or reason when one is recorded.

Host bridge device settings (sdk 2.40)

packages/host-bridge gains HostSettingsEntry, SettingsOpen, WEB_FEATURE_SETTINGS_MENU, an optional HostDescribe.settings list, optional HostDescribeRequest.features, and the web → host settings.open message. The envelope stays v: 1. The change is additive only.

Role-scoped device socket revocation (sdk 2.41)

GatewayRequestHandlerOptions.context gains optional revokeDeviceRoleConnections(deviceId, role, reason). It works like revokeDeviceConnections but suspends and then closes only the device’s live connections that hold role. device.token.revoke uses it, so revoking a token closes the sockets that token authenticated (#2282). The change is additive only.

Channel account mode (sdk 2.42)

resolveChannelAccountMode(cfg, channel, accountId?) and the ChannelAccountMode type ("channel" | "inbox") are exported. An account resolves to channels.<ch>.accounts.<id>.mode ?? channels.<ch>.mode ?? "channel"; only whatsapp, bluebubbles, and discord can resolve to "inbox" (ADR 2572).

Device accessories (gateway 3.20, sdk 2.43)

A signed-in WednesdayAI app device manages the credential-less accessories vouched for by its own record (plan C2 of docs/plans/app-login-accessory-scopes.md, ADR 2242 D4):
  • New methods device.accessory.attach / device.accessory.detach / device.accessory.list (all own-device, operator.write / operator.write / operator.read, app-profile callers only), with new ProtocolSchemas entries DeviceAccessory*Params / DeviceAccessory*Result.
  • The request frame gains optional accessoryId (RequestFrame.accessoryId), so GatewayRequestHandlerOptions.req carries it; a tagged request is clamped to the accessory’s gateway-owned profile after the method-scope check (the clamp only narrows). The change is additive only.
  • A tag admits only the explicit allowlist ACCESSORY_TAGGABLE_METHODS (in src/shared/accessory-profiles.ts): node.invoke, node.event, node.invoke.result, chat.send, chat.abort, chat.history, exec.approval.resolve, device.self. Everything else tagged is refused accessory_method_denied before any scope check.
  • Refusal reasons (all INVALID_REQUEST, in error.details.reason): accessory_forbidden (the caller is not a signed-in app device — includes device-less connections), accessory_kind_unknown, accessory_id_invalid, accessory_limit (9th accessory), accessory_not_attached (unknown or detached tag), accessory_method_denied (method not on the taggable allowlist), accessory_scope_denied (the kind’s profile does not grant the method’s required operator scope), accessory_command_denied (node.invoke command outside the kind’s commands grants). One further reason travels as UNAVAILABLE, not INVALID_REQUEST: accessory_busy (the device’s accessory state is locked by a concurrent connect or mutation; retry).
  • A tagged request that passes the clamp runs its handler with a request-local client view whose connect.scopes hold every accessory-profile scope the connection satisfies under the implication rules (never a scope outside the profile); the view’s connect delegates to the original connection for person-scope state, so a live suspension or unlink applies to tagged requests too. The socket’s client object is never mutated.
  • The tag is attribution plus a ceiling on the accessory’s own direct requests — not an isolation boundary against the app or the person’s agent: an agent turn started by a tagged chat.send runs under the person’s tool policy and exec approvals like any untagged app request. For audit and approval display, a run started by a tagged chat.send carries accessoryId and kind in its chat events’ optional origin (next to deviceId/clientId).

App sign-in requirement (gateway 3.21, plugin 2.10, sdk 2.44)

C4 of docs/plans/app-login-accessory-scopes.md (ADR 2242 D4). All changes are additive:
  • GATEWAY_CLIENT_IDS gains WEDNESDAYAI_MOBILE: "wednesdayai-mobile" and WEDNESDAYAI_DESKTOP: "wednesdayai-desktop", both mapped to the app bootstrap profile (the same object as the deprecated wednesdayai-glass-node). ConnectParams.client’s id enum and its expanded surfaces therefore widen.
  • PluginRuntime.identity.issueEnrollment accepts profile: "wednesdayai-mobile" and "wednesdayai-desktop", minting the app bootstrap profile like wednesdayai-glass-node.
  • The identity-oidc plugin config gains appSignIn ("required" | "optional", default "optional") and appSessionMaxAgeDays (optional positive integer); GET /plugins/identity-oidc/providers returns the resolved appSignIn and, when set, appSessionMaxAgeDays.
  • Connect refusal detail codes app_sign_in_required and app_sign_in_expired (src/gateway/protocol/connect-error-details.ts) for an app device connecting without a person, or with a pairing older than appSessionMaxAgeDays.

Your devices (gateway 3.22)

A person reads and removes their own devices from any of their own devices (plan C5 of docs/plans/app-login-accessory-scopes.md, ADR 2600):
  • New methods identity.devices.list (operator.read, narrow-admitted via operator.sessions.read) and identity.devices.remove (operator.write, narrow-admitted via operator.sessions.write), with new ProtocolSchemas entries IdentityDevicesListParams/Result, IdentityDevicesRemoveParams/Result and the shared IdentityDeviceEntry row. Additive only; no existing payload changed.
  • identity.devices.list returns the paired devices whose stored ownerPerson is the caller’s person — device id, optional display/client/platform/family fields, lastActiveAtMs, approvedAtMs, companionOf, current, and the vouched accessories (accessoryId, kind, model?). No tokens, public keys or scopes cross the wire.
  • identity.devices.remove runs the guarded owned-removal cascade: one conditional store mutation re-checks owner, row revision and token fingerprint under the store lock and removes the parent, its companion grants and its companion rows in that transaction (the captured companion ids drive the socket closes). identity_device_not_owned is the uniform refusal for another person’s device, for an unknown id and for a re-enrollment between the read and the write, and identity_person_required refuses a caller with no person.

Session-storage Postgres connect timeout (sdk 2.45)

OpenClawConfig.session.storage gained the optional postgres.connectionTimeoutMs key (#2520). It is a provided config member, so the change is additive.

Channel account failed state (sdk 2.46, plugin 2.11)

A channel’s gateway.startAccount may resolve with ChannelAccountStartResult ({ accountFailure: { reason, code?, remediation? } }). ChannelAccountStartResult and ChannelAccountFailure are exported from wednesdayai/plugin-sdk. The channel manager then sets ChannelAccountSnapshot.failure (reason, code, remediation, at) and lastError, skips the backoff restart, and the health monitor does not restart the account. The account starts again only when its resolved config changes, when it resolves disabled or unconfigured, or when the gateway restarts. wednesdayai channels status prints failed (code N) and a warning, and wednesdayai doctor lists the same warning. status.defaultRuntime gains optional failure. The change is additive only: channels that never return accountFailure behave as before.

Alert mutes and preview dedupe (gateway 3.23, plugin 2.12)

A person can mute their own alert pushes per kind, per inbox source, or per inbox source and account, from the app (device settings C4, ADR 2242 D2):
  • New gateway methods push.mute.get (operator.read, {}) and push.mute.set (operator.write) return { mutes }, the person’s full sorted mute list after the change. push.mute.set is one idempotent toggle ({ kind, source?, accountId?, muted }), not a snapshot replace, so concurrent devices do not overwrite each other.
  • A mute matches an alert when the kind is equal and the optional source and accountId match exactly. "chat.final" mutes reply alerts; "inbox" with a source mutes that inbox source, with accountId one account. Approvals are never muted.
  • RuntimePushAlertInput (plugin 2.12) gains optional source and accountId, so inbox plugins pass the emitting account and the person’s mutes apply to them. Additive only.
  • Refusals carry error.details.reason: push_mute_person_required (the connection resolves no person), push_mute_invalid (bad or inconsistent source/accountId), push_mute_limit (more than 64 mutes per person).
  • Superseded in plugin 2.13: dedupe is by event id, not preview text (see below).

Alert event dedupe (plugin 2.13)

  • RuntimePushAlertInput gains optional eventId, a stable id of the event the alert is for (the inbox plugin passes its row id, the percent-encoded source:accountId:sourceId; reply alerts use the run id). Additive only.
  • A repeat with the same eventId is pushed to a device at most once per kind every 10 minutes (PERSON_ALERT_EVENT_DEDUPE_MS). Identical text never suppresses a distinct event; only the 30-second per-collapse-key rate limit (PERSON_ALERT_MIN_INTERVAL_MS) applies. Without eventId nothing is deduped. Approvals are never deduped. Only digests are kept in memory.
  • Replaces the gateway 3.23 / plugin 2.12 preview-text dedupe, which dropped the second of two different mails sharing a subject.

Inbox classification provenance (gateway 3.27, sdk 2.49)

Inbox classification is live-only by default, and history is opt-in per account (ADR 2637, dev-docs/adr/2637-inbox-classify-history-opt-in.md):
  • InboxItemDto gains optional categorySource, categorySignal, classifyState (pending | skipped-history | done), classifiedAt and classifyModel. They are optional, so the change is additive: older gateways omit them, and readers treat an absent field as null.
  • OpenClawConfig.inbox.classify gains optional history (InboxClassifyHistoryConfig): default and accounts (keyed "<source>:<accountId>" or "<source>"), each a policy { mode: "live" | "window" | "all", days? }. It is a provided config member, so the change is additive.

People seam (sdk 2.51)

A process-scoped seam between the people-graph plugin and the inbox plugin, which never import each other (src/plugin-sdk/people.ts):
  • registerPeopleResolver / getPeopleResolver with the PeopleResolver type: people-graph registers it; inbox calls resolveSenders and resolveEmails for display names and recordInboxItems / recordCalendarEvents for touch points.
  • registerPeopleHistorySource / getPeopleHistorySource with PeopleHistorySource: inbox registers read-only paging over its own history, so people-graph backfills never read inbox tables (ADR 0099).
  • Each register returns an unregister that removes only its own registration. All additive.

System-origin chat provenance (gateway 3.28, sdk 2.52)

  • ChatEvent gains optional trigger: "heartbeat" | "cron" | "subagent" | "acp", the run’s system origin. It is optional, so the change is additive: user runs and older gateways omit it.
  • New subpath wednesdayai/plugin-sdk/reply-sentinels: the client-safe sentinel rules (REPLY_SENTINEL_TOKENS, isSilentReplyText, isSilentReplyLeadFragment, stripEdgeSentinelLines and siblings).

Version semantics

Contract versions are major.minor strings. The policy is:
  • Breaking (requires a major bump): removing an entry, adding a required member to an implemented type, changing a signature or type shape, or flipping a direction.
  • Additive (requires only a minor bump): new optional members, new members on a provided type, new required members beneath a newly added optional member (omitting the optional parent omits them), new deprecation markers, and pure string-literal union widening — a union that gains literals while its literal-elided shape stays unchanged — in either direction (proved by literalRuns/shapeHash on digest-stored entries, or by the elided shape of a short text).
A type-text difference that vanishes under member-order canonicalization is no change at all: the checker’s print order for spread and inferred object types follows symbol allocation, not the contract, so order-only permutations emit no change line. Member order that is semantic is never canonicalized: bare call/construct signatures and same-name overload groups keep authored order. Three refinements keep the classifier honest. First, adding members to a provided type changes the parent’s recorded shape text, and that parent change is classified as additive as long as every new entry beneath it is absorbable — a new provided member (always additive, required or not) or an optional one. The same holds one step removed: a provided entry whose text only embeds the grown type by reference (the registry entry ProtocolSchemas.AgentSummary, a flattened member like AgentsListResult.agents) is additive while every addition in the whole contract is absorbable, and breaking otherwise. Second, the sdk barrel records each export’s whole printed type as one entry with no member entries beneath it, so a member added inside a barrel type changes the barrel entry’s text with nothing in the sdk contract to explain it. A provided barrel text change (plugin-sdk#MsgContext) therefore defers to that type’s member subtree in the contract that enumerates it (ingress for MsgContext and InboundUserContext): additive while the subtree has diffs and every one of them is additive, breaking otherwise. Kernel version constants (plugin-sdk#GATEWAY_CONTRACT_VERSION and siblings) are exempt from type-text comparison: their literal changes exactly when a contract version is bumped, and the per-contract rules already police that bump. Type text is also only compared when both snapshots were produced by the same text algorithm (the snapshot’s typeTextVersion); an algorithm change is a notice with per-contract counts, like a TypeScript bump, never a breaking change by itself. Optional members can also hide inside one entry’s text. A leaf entry with no keys recorded beneath it whose type is an inline object (ConnectParams.auth) classifies additive in either direction when the only difference is new optional properties; a union of object arms, a retyped, removed or newly required property stays breaking. The registry check applies the same rule one level down: a nested object property that only gained optional properties, with every other keyword unchanged, is an optional addition. A breaking change without a major bump fails CI (see Changing a contract).

Declaring what your plugin needs

The optional contracts field in wednesdayai.plugin.json maps contract ids to the minimum major.minor version your plugin requires (the legacy openclaw.plugin.json filename still loads):
The field is parsed in src/plugins/manifest.ts and checked in src/plugins/contract-versions.ts (checkPluginContractCompat). The compat rule is: same major, and the host minor must be greater than or equal to the required minor. A plugin that declares nothing is always compatible; a plugin can require a subset of the contracts. Entries whose value is an array of strings (upstream capability-ownership lists such as contracts.tools) are accepted and ignored for kernel contract versioning; an array holding any non-string is rejected. When the check fails, the host refuses the plugin with one of these reasons, taken verbatim from checkPluginContractCompat:
  • requires kernel contract "<id>", which this host does not provide
  • contracts.<id> "<v>" is not a valid "major.minor" version
  • requires <id> contract <M>.x (>= <v>), but host provides <host>
  • requires <id> contract >= <v>, but host provides <host>
Where the check runs:
  • At install: src/plugins/install.ts refuses the install with the error code VERSION_INCOMPATIBLE and the message plugin "<id>" is not compatible with this host: <reason>. Upgrade WednesdayAI and retry. An invalid version string is prefixed with invalid contract version in <manifest>:. A malformed contracts field (not a map whose values are version strings or arrays of strings) is rejected the same way — and before any files are copied — with the message invalid contracts field in <manifest>: <error>. <manifest> is the filename actually read: wednesdayai.plugin.json, or the legacy openclaw.plugin.json when that is the only file present.
  • At load: src/plugins/manifest-registry.ts drops the plugin and records an error diagnostic with the internal code PLUGIN_CONTRACT_INCOMPATIBLE (or PLUGIN_MANIFEST_INVALID when the manifest fails to parse — including a malformed contracts field — or the declared version is not a valid major.minor string) and the message plugin "<id>" <reason>. Config validation (src/config/validation.ts) turns every error-level manifest diagnostic into a config error at plugins.entries.<id>, so config validate, plugins list and Gateway startup fail until the plugin is removed or upgraded — the same behaviour as the existing minimum-host-version check. The check runs in dev builds too, because contract versions are compiled into the host.
See Plugin manifest for the rest of the manifest shape.

Conformance suite

src/plugin-sdk/conformance.ts, conformance-delivery.ts and conformance-ingress.ts ship framework-free checkers through wednesdayai/plugin-sdk/testing. Each checker returns a report of rule violations; assertConformance throws a typed ConformanceError when any report has violations, so extension tests never need to import a test framework to run the checks.
checkExtensionConformance loads the plugin through the real plugin loader and runs the plugin, hooks and delivery checks; checkDeliveryConformance and checkIngressConformance can also be called directly on an adapter or a MsgContext. Two properties of checkExtensionConformance matter for test suites: calls are serialised through a module-level promise chain (the inspecting load activates process-global plugin state, so overlapping loads would restore over each other), and after the load the checker restores the pre-call state — registry, hook runner, plugin APIs, speech and voice providers, internal-hook handlers, plugin commands and the task-pass buffer — so other plugins’ commands and registrations survive the check. Rule ids, grouped by checker: Plugin and hooks (checkExtensionConformance, which includes checkHooksConformance):
  • plugin.load.loaded — the plugin module actually loaded into the registry. When the plugin fails to load, this is the only check reported.
  • plugin.register.no-diagnostics — no warn or error diagnostic is attributed to the plugin. Discovery, manifest parsing, config validation and registration all count, not only registration.
  • hooks.handler.function — every registered hook handler is a function.
  • hooks.priority.finite — hook priority, when set, is a finite number.
  • hooks.timeout.positive — hook timeoutMs, when set, is greater than 0.
Delivery (checkDeliveryConformance):
  • delivery.mode.known — deliveryMode is direct, gateway or hybrid.
  • delivery.direct.handlers — non-gateway delivery provides both sendText and sendMedia (otherwise createPluginHandler returns null and delivery throws at send time).
  • delivery.text-chunk-limit.positive — textChunkLimit, when set, is a positive integer.
  • delivery.chunker.bounded — a chunker returns a non-empty chunk array at the adapter’s own limit (default 4000) without throwing. The probe text is capped independently of the declared limit (~8000 chars), so a huge valid textChunkLimit does not scale the probe allocation.
  • delivery.send-text.result — the optional sendText probe resolves to a result object with a non-empty messageId and the adapter’s own channel.
Ingress (checkIngressConformance):
  • ingress.sender.identity — sender identity fields pass validateSenderIdentity.
  • ingress.body.strings — Body, BodyForAgent and BodyForCommands are strings.
  • ingress.group.conversation-label — group/channel context carries a conversation label (ConversationLabel or fields that derive one).
These checks are not sandboxed: the checkers execute the adapter’s own code in-process, with neither a sandbox nor a timeout. delivery.chunker.bounded calls the adapter’s chunker twice, and the optional deliveryProbe makes the delivery.send-text.result check call the adapter’s real send path — with a credential-bearing config, that sends a real message. Run the send-text probe only against an in-memory or sandbox adapter. test/fixtures/plugins/conformance-reference/ is the reference implementation: a minimal in-memory channel plugin that imports only from wednesdayai/plugin-sdk and passes every check. For an extension-side example, see extensions/telegram/src/outbound.conformance.test.ts.

Private imports

An extension may import core only through the plugin-sdk surface:
  • wednesdayai/plugin-sdk (alias wednesdayai/plugin-sdk), and
  • its exported ./plugin-sdk/* subpaths, for example wednesdayai/plugin-sdk/account-id, wednesdayai/plugin-sdk/keyed-async-queue, wednesdayai/plugin-sdk/process-scoped-map, wednesdayai/plugin-sdk/lazy-runtime, wednesdayai/plugin-sdk/escape-regexp, wednesdayai/plugin-sdk/control-ui, wednesdayai/plugin-sdk/provider-web-search and wednesdayai/plugin-sdk/provider-media-understanding, and
  • wednesdayai/plugin-sdk/testing from test files only. Importing it from production code is forbidden because the jiti manifest entrypoint never loads it in production. The legacy openclaw/plugin-sdk specifier and its subpaths still load (ADR 2057).
The bare package root openclaw and openclaw/cli-entry appear in the root package.json exports map, but they are not part of the allowed plugin surface; importing either one from an extension is a violation. A “test file” here means a file whose name ends in .test.ts, .test.tsx, .test-harness.ts, .shared-test.ts, .test-utils.ts or .e2e-harness.ts, or any file inside a __tests__ directory. Deep relative imports into src/ resolve inside the monorepo but crash in the installed package, which ships dist/ only. The gate is pnpm lint:extensions:no-private-imports (scripts/check-extension-imports.ts), part of pnpm check. Violations print one line each:
Rule ids:
  • relative-outside-package — a relative import leaves the extension package (test files may still deep-import src/ when their file is in the documented allowlist).
  • core-internal-package-path — a openclaw/... or wednesdayai/... import that is not one of the allowed plugin-sdk subpaths above.
  • testing-subpath-in-production — wednesdayai/plugin-sdk/testing imported from a production file instead of a test file.
  • stale-allowlist-entry — an allowlist entry whose file no longer deep-imports src/, so the exception can be deleted.

Lazy imports

Plugins load from TypeScript source through jiti, which hands a second concurrent import() of a module that is still evaluating a partially initialized copy. Calling into it throws ReferenceError: Cannot access '<name>' before initialization. Wrap every relative dynamic import in a module-level loader from wednesdayai/plugin-sdk/lazy-runtime:
The loader caches the module, retries after a failed load, and runs one first load at a time per process. Never use top-level await in a plugin module: a module that awaited a loader while it was being evaluated would wait on itself. The gate is pnpm lint:extensions:no-bare-lazy-import (scripts/check-extension-lazy-imports.ts), part of pnpm check. Rule ids:
  • bare-relative-dynamic-import — a ./ or ../ import() that is not the direct argument of createLazyRuntimeModule(() => import(...)).
  • top-level-await — an await or for await outside any function.
Test files are exempt.

Changing a contract

To change a public contract surface:
  1. Edit the type.
  2. Run pnpm contracts:update to regenerate src/plugin-sdk/contract-surface.json.
  3. Bump the version constant in src/plugins/contract-versions.ts: minor bump for additive-only changes, major bump for breaking changes.
  4. Commit the updated src/plugin-sdk/contract-surface.json with your change.
pnpm lint:contracts:surface (scripts/check-contract-surface.ts) inside pnpm check diffs the committed snapshot against the merge base with the PR base branch (the first parent on a push build) and the latest release tag — true only because the CI check job checks out full history (fetch-depth: 0); do not reduce that checkout depth, or the gate silently degrades to a base-tip comparison. The script accepts only --update and --base-ref <ref>: a missing --base-ref value, or a value that is itself a flag, and any unknown argument are a usage error, never a silent fallback to the default base. It fails CI with:
  • snapshot.stale — src/plugin-sdk/contract-surface.json does not match the generated snapshot. Fix: run pnpm contracts:update and commit the result.
  • base.unresolved — the base snapshot cannot be read at all. The check fails rather than passing silently; a base branch that simply does not carry the snapshot yet is only a notice.
  • version.bump-required — the surface changed but the contract version constant did not. Fix: bump the constant (minor for additive changes).
  • version.major-bump-required — the change is breaking but the constant kept its major. Fix: bump the major.
  • version.decreased — the constant went down relative to the base branch’s snapshot. Fix: restore or correctly bump the version.
  • contract.removed — a contract id disappeared from the snapshot. Fix: reinstate it or record the removal with a major bump and a released @deprecated alias (see Renaming and removing).
  • payload.untyped — a member newly typed as an open Record<string, unknown> (see What the snapshot tracks).

What the snapshot tracks

The snapshot is deliberately shallow: per entry it records only its presence, whether it is optional, its direction, its deprecation marker, and the entry’s printed type text, with two exceptions: an anonymous object property that gets flattened into dotted child entries records a marker instead of its own text (its children carry the shape), and a non-enumerable type text longer than 240 characters is stored as a sha256: digest (an enumerable one is flattened instead; see below). A digest-stored entry whose text contains string literals also records them as literalRuns — the sorted vocabulary per literal run, in position order — plus shapeHash, a digest of the text with every literal run replaced by a placeholder, so the diff can prove a pure vocabulary append without the digest pre-image (runs compare positionally, so one union narrowing while another grows is still breaking). Four positions never count as vocabulary, in short texts or recorded evidence: template-literal text (quoted fragments there are static content, not union members); the argument lists of Record, Pick, Omit, and Exclude (key and subtraction sets, where a growing union adds or removes properties); a literal carrying the array postfix (the "b"[] arm of "a" | "b"[] is its own alternative, not another run member); and conditional-type operands (T extends "a" ? … — the inline form of Exclude). Edits in those positions flip the elided shape and keep the conservative classification. For generic interfaces, classes and type aliases the declaration’s type-parameter list — constraints and defaults included — is appended to the recorded text (Box<T> { value: T; } <T>), because the printed type alone drops them; this closes the generic-type-alias known limit in ADR 0117. A member whose type is a named object type declared in this repository (an alias or interface outside node_modules, not a class, not a root) is flattened into dotted child entries like an anonymous object, so removing a member inside it demands a major bump of the contract that references it. Types from dependencies and the TypeScript library (Date, arrays) stay nominal, and so does any type whose declaration carries the JSDoc tag @contractNominal <reason>: OpenClawConfig does, because config keys are versioned by the config schema and the sdk contract tracks the OpenClawConfig export itself. The test-only wednesdayai/plugin-sdk/testing subpath is deliberately excluded from the sdk contract. A member typed as an open record (Record<string, unknown>, { [key: string]: unknown } or an alias of either) is recorded with untyped: true, because its keys cannot be diffed. Typing a new member that way fails the check with payload.untyped. Fix: give it a typed shape, or tag the property /** @openPayload <reason> */ when its keys are deliberately opaque. Open records that already existed are listed in a grandfathered notice on every run. When an entry’s printed text is opaque (past the 240-char digest cap) but the shape behind it is enumerable, the generator records that shape as dotted per-member entries and marks the parent with a stable marker (object, or object <config> such as object $strict for a zod object schema, so a strictness change diffs) — for provided object-shaped types and for zod object schemas (the config keys under TtsConfigSchema and friends), where member optionality comes from the zod ZodOptional/ZodDefault wrappers and nested ZodObject shapes flatten to the same depth cap as anonymous types. Introducing that recording changed the emitted type text, so it shipped with a typeTextVersion bump: snapshots recorded before it are not compared text for text (the notice reports the skip). Entry keys, optionality, deprecation and direction are still compared, so removals and optionality regressions stay breaking. A same-key retype or signature change is not detected on the run that crosses the version bump. Zod library types are recorded by their resolved class name plus authored type arguments, wherever they appear: ZodEnum<{ allowlist: "allowlist"; open: "open"; }>, (schema: ZodType<unknown, unknown>): …. zod’s derived *Internals arguments and the class’s own methods are left out. A zod release that only changes the library’s API, or how it aliases ZodTypeAny, is therefore not a contract change, while an authored change such as a new enum option still diffs. This recording shipped with typeTextVersion 8.

Renaming and removing

Config keys, CLI flags and SDK exports are never removed immediately; the same discipline applies to kernel contract entries. The flow:
  1. Add the new name.
  2. Keep the old name with a /** @deprecated Use <new> */ marker and ship the whole change as a minor bump.
  3. Wait one release cycle so a released snapshot carries the deprecated alias.
  4. Remove the old name with a major bump.
CI enforces the alias requirement through deprecation.alias-release-required: a removed entry must have shipped @deprecated in the latest release tag’s snapshot, otherwise the removal is rejected. Two key shapes are exempt because nobody authors them and so nobody can deprecate them: hook-name literal entries (PluginHookName|"message_received", including dotted literals like PluginHookName|"context.collect") and generated union-constituent keys (<Root>|kind="a".member, <Root>|m:<digest>.member, <Root>|v:<digest>, <Root>|<n>.member), whose prefix changes whenever that constituent’s shape changes. Both still require the major bump when an entry disappears, and ordinary payload properties are never exempt. See the general policy in Release.