SDK surface

@meridian/shared (libs/shared/package.json) is the one package a plugin compiles against. It is browser-safe: no filesystem access, no host internals, no dependency on apps/api. A plugin's runtime code imports it as import type wherever possible, so the import is erased at compile/bundle time — see Bundling and distribution.

This page is the exhaustive map of what the package exports, file by file. It does not explain how to author a manifest, a behavior, or a workflow — see Plugin manifest, Autonomy and packaging, and the how-to guides linked from each section below.

Package identity

Two resolution paths coexist:

• The repository's plugins (external-plugins/<name>/) resolve @meridian/shared/* via the path alias "@meridian/shared/*": ["../libs/shared/src/*"] (external-plugins/tsconfig.json) — straight to source, no build step.
• Out-of-repo plugins resolve the published npm package, whose exports only take effect through publishConfig — a field pnpm publish/pnpm pack apply and npm ignores. See Bundling and distribution.

PLUGIN_CONTRACT_VERSION (below) is a hand-maintained constant that is decoupled from the @meridian/shared package version: it moves when the plugin-facing contract does (see version), not on every library release.

Directory layout

libs/shared/src/
  version.ts              PLUGIN_CONTRACT_VERSION
  plugin/                 the plugin-authoring contract
    behavior.ts
    source.ts
    mapping.ts
    assist.ts
    inbound.ts
    manifest.ts
    manifest-keys.ts
    dependencies.ts
    declared-events.ts
    node-contribution.ts
    agent-contribution.ts
    instance.ts
    i18n.ts
  domain/                 shared platform vocabulary
    types.ts
    object-types.ts
    value-sets.ts
    dimensions.ts
    context-kinds.ts
    event-types.ts
    event-routing.ts
    trigger-filter.ts
    trigger-facts.ts
    validation.ts
    terminology.ts
    agent-spec.ts
    agent-tools.ts
    memory.ts
    ports.ts
    workflow-spec.ts
  engine/                 type-system & catalog helpers
    type-system.ts
    conversions.ts
    catalog-metadata.ts
    event-contract.ts
    dynamic-ports.ts
    derived-ports.ts
    template.ts
    effects.ts
    agent-tool-eligibility.ts
    memory.ts
    schedule.ts
  observability/
    trace.ts

Every file above is a real, committed source file (git ls-files libs/shared/src); there is no generated or build-manifest step involved in producing this list.

plugin/* — the plugin-authoring contract

domain/* — shared platform vocabulary

Terminology port

TerminologyPort is the one domain contract with more than a data shape: has, validateCode, expand, display, subsumes — each implementation may answer synchronously (InternalTerminology) or asynchronously (a terminology adapter, reached through RoutingTerminology). A terminology server is plugged in by a plugin that contributes a terminology adapter. See Configure terminology.

engine/* — type-system & catalog helpers

observability/trace

Depends only on @opentelemetry/api — a no-op API when no SDK is registered, so this module costs nothing unless observability is enabled. See Enable observability and Observability signals.

Shared expression and configuration validation

@meridian/shared/engine/expression exports the existing JEXL evaluator (evalExpression, compiledExpression, expressionAst, TRANSFORM_NAMES). @meridian/shared/engine/expression-check exports expressionProblems for the standard expression kinds or an explicit array of allowed root names. @meridian/shared/engine/config-schema exposes configSchemaError and configValueErrors, the same JSON Schema checks used by the engine. @meridian/shared/engine/text-value exposes the shared value formatter. The engine-core paths re-export these implementations. Metadata and port resolution do not import the evaluator; plugin behaviors and host-side assistance can opt into it without bringing plugin code into the browser.

version

A plugin declares the contract range it needs in its manifest (sdk: "^0.1.1"). At plugin discovery the host (apps/api/src/plugins.ts) checks that range against PLUGIN_CONTRACT_VERSION using satisfies() from the npm semver package (no hand-rolled semver comparison); a plugin whose range does not match is logged and skipped, the others still load. See the sdk field in Plugin manifest.

The version follows its own doctrine:

• patch (0.1.0 → 0.1.1): a new manifest key that an older host would strip (the schema drops a key it does not know: a host that reports unknown keys, kind key, logs it at load; an earlier host drops it silently) and that changes what gets loaded. A plugin using it declares sdk: "^0.1.<patch>", so an older host refuses it instead of loading it by halves, while existing plugins (^0.1.0) stay accepted. 0.1.1 adds declared events (contributes.events, a trigger's event, an output's from); meridian-plugin validate/build fail on a manifest that uses them with a lower range, and the host warns. 0.1.2 adds resolve.pending on an event binding (the validation a decision is about); no load check covers its range. 0.1.3 adds the default filter of a declared event (events[].defaultSelector), checked like 0.1.1. 0.1.4 adds the description of a protocol's reception (receive.mediaTypes, receive.example, a transport written { name, defaultPort?, hint? }), checked like 0.1.1. 0.1.5 adds the derivedPorts rule when, checked the same way. 0.1.6 adds connections (contributes.connectionTypes, connection on an adapter, an event source or a node), checked like 0.1.1;
• minor: a real break of the plugin-facing surface (a type, port, helper or manifest form removed or renamed) — plugins must be republished with a widened range;
• nothing: an addition an older host can ignore without consequence, such as SubjectRecordPort.closeValidationRequest: an optional adapter method, with no manifest key, that a host which does not know it never calls, or label and params on an event source, which an older host drops at load (« clé ignorée »).

0.1.3 also removes two manifest forms, the node-level defaultSelector and the trigger without pinnedRouting and without event, which the rule above puts in a minor. It stays a patch by a decision specific to this release: only @posos/common used one of these forms in the repository, and each removal is reported at load, never dropped silently. A plugin in ^0.1.x stays accepted and shows the problem.

A host of contract 0.1.3 refuses a plugin in ^0.1.4: with a contract problem when its schema reads the manifest (it would drop the two keys), with « manifeste invalide » when a transport is written as an object, since its schema reads a transport as a name and parses the manifest before the sdk range. A transport written by its name stays valid, and plugins in ^0.1.x stay accepted.

A host of contract 0.1.5 refuses a plugin in ^0.1.6 with a contract problem; plugins in ^0.1.x stay accepted.

The check of the dependsOn ranges (kind dependency) has no contract version of its own: it adds no manifest key, and a host that predates it ignores the ranges, as every host did before. Requiring a higher sdk floor to get the check would make a rolled-back image refuse the plugins.

What is not exported

The SDK exposes contracts and pure/registry helpers only. It has no CLI (that is @meridian/plugin-cli, see meridian-plugin CLI), no plugin loader or filesystem discovery (that is the API host's PluginHost), and no bundler (plugins are built with meridian-plugin build, an esbuild bundle — see Bundling and distribution and Build and bundle). Publishing and registry resolution (meridian-plugin publish, the instance manifest's registry:/plugins: fields, the MERIDIAN_REGISTRY environment variable) are documented in Publish to the registry and Set up a plugin registry.