@ethisyscore/protocol

Canonical TypeScript protocol types for the EthisysCore plugin ecosystem.

This package is the TypeScript companion to the .NET EthisysCore.Protocol NuGet package. It exposes the same wire-level contracts so that the host app, App Bridge, and any future TypeScript clients consume identical types.

Scope (1.0.0)

This release lands the foundation layer for the capability-first plugin runtime:

• Plugin manifest — PluginManifest, RenderMode, and the optional PluginUi sub-shape (src/manifest.ts).
• SDUI primitive vocabulary v1 — KNOWN_PRIMITIVES, recursive SduiNode schema (src/sdui/primitives.ts).
• JsonLogic operator subset + reactive rule kinds — KNOWN_OPERATORS, KNOWN_RULE_KINDS, ReactiveRule (src/sdui/operators.ts).
• Portal contributions + host slot taxonomy — PortalContribution, KNOWN_SLOTS, HostSlot (src/sdui/portal.ts).
• Theme tokens — design-token shape consumed by the host renderer (src/theme/tokens.ts).
• Capability claims — permission and capability-token types (src/capability/permissions.ts, src/capability/token.ts).
• Bridge version constant — BRIDGE_VERSION (src/bridge/version.ts).

Future contracts (reference-data, DataStore, MCP, events, logging, notifications, transport, packaging, host-callback) are not yet in this package — they will be added additively as the consuming clients land.

Install

npm install @ethisyscore/protocol

Scripts

npm run build       # bundle ESM + CJS + d.ts via tsup
npm test            # run vitest in CI mode
npm run test:watch  # vitest in watch mode
npm run lint        # tsc --noEmit type check

Layout

• src/index.ts — public barrel
• src/manifest.ts — plugin manifest + render mode
• src/sdui/ — SDUI primitives, operators, portal contributions
• src/route-template.ts — {param} route-template syntax for Contract A surfaces (RFC 0019): scanSurfaceRoute, matchRoute, substituteRouteParameters, getRouteShape, requiredContractVersionForSurfaces
• src/sdui/contract-a.ts — richer Contract A props (RFC 0020): per-primitive Zod schemas, closed lists, DATA_TABLE_QUERY_ARGUMENTS (the arguments a host sends a bound DataTable's tool, which returns a PagedResponse), requiredContractVersionForDocument (the minimum Plugin-UI Contract version a document needs, compared with isContractVersionSupported), isToolInNamespace (prefix + declared-tool membership), isPluginRelativeRoute, isContractAIcon (host icon tokens), CONTRACT_A_LIMITS, validateContractADocument
• src/sdui/bindings.ts — the closed binding set $route.<param>, $row.<field> (RFC 0020), recognised only in a top-level tool args value and Field.defaultValue
• src/theme/ — design tokens
• src/capability/ — permissions and capability-token claims
• src/bridge/ — bridge version constant
• src/__tests__/ — vitest tests
• dist/ — build output (gitignored)

Compatibility

Treat this package as a public compatibility boundary. Prefer additive changes; do not repurpose enum values; do not make breaking JSON shape changes without a coordinated release.

The vocabulary surfaces (SDUI primitives, JsonLogic operators, reactive rule kinds, host slot taxonomy) are gated by the RFC process documented in docs/rfcs/README.md. CI auto-rejects PRs that expand the vocabulary without an accepted RFC.