@lssm/lib.surface-runtime

Website: https://contractspec.io

Surface runtime for AI-native ContractSpec experiences, including bundle specs, planners, overlays, patching, and React rendering support.

What It Provides

• Provides the runtime layer behind AI-planned surfaces, widget registries, overrides, and bundle resolution.
• Supports React rendering, adapter boundaries, telemetry, evaluation harnesses, and planner tooling.
• Provides a UI-agnostic RoleMorph runtime for policy-aware, role/actor-specific operating surfaces.
• Recently expanded to better align with AI chat, i18n, workflow tools, and bundle export needs.
• src/adapters/ contains runtime, provider, or environment-specific adapters.

Installation

npm install @lssm/lib.surface-runtime

or

bun add @lssm/lib.surface-runtime

Usage

Import the root entrypoint from @lssm/lib.surface-runtime, or choose a documented subpath when you only need one part of the package surface.

Architecture

• src/spec/ defines module-bundle and surface-patch validation surfaces.
• src/runtime/ contains planners, registries, patch application, policy evaluation, and bundle resolution.
• src/rolemorph/ contains serializable RoleMorph contracts, the pure surface resolver, validation, AirDesk and non-AirDesk fixtures, and CompanyOS policy projection helpers.
• src/react/ exports the React integration layer for bundle rendering and override handling.
• src/adapters/, src.telemetry/, src.evals/, and src.examples/ support integration and verification flows.
• src/index.ts is the root public barrel and package entrypoint.

Feature Hub runtime

@lssm/lib.surface-runtime/feature-hubs validates and composes independent Feature Hub manifests. Installation is read-only; start() is the explicit, idempotent effect boundary. Effect calls must match a manifest-declared capability, operation, port, and policy. An allow decision with obligations is still denied unless the host fulfills those obligations and returns durable evidence references. Missing optional ports degrade only dependent capabilities; failed starts and factory initialization compensate registered resources; disposal attempts every teardown before reporting aggregate failure.

Signed registry metadata is discovery-only. It is checked for validity, revocation, signature, replay, and exact local-manifest identity, and can only resolve code already installed in the host allowlist.

RoleMorph runtime

RoleMorph resolves ContractSpec operating surfaces for different human and AI actors without generating arbitrary UI code. The exported ./rolemorph subpath includes:

• RoleMorphSurfaceSpec, actor, component-registry, action-boundary, explanation, diagnostic, and resolution-result types;
• resolveRoleMorphSurface() for deterministic workflow/role/intent matching, policy and permission boundary evaluation, hidden-data explanations, and agent action-plan projection;
• validateRoleMorphSurfaceContext() for missing binding diagnostics and generated-UI escape-hatch rejection;
• deterministic surface precedence (priority, match specificity, then semantic version) with fail-closed ambiguity diagnostics;
• fail-closed component registry enforcement for supported surface/intent kinds, required data and permissions, emitted actions, and registered action classifications;
• exact permission, authority, and policy decisions for governed actions; only explicitly registered display_only actions may omit those decisions;
• domain-neutral individual, learner, community, family/household, and trusted-delegate actor kinds alongside all existing organization literals;
• canonical seven-dimension preference and action-based capability projection adapters, including a human-safe adapter that never falls back to agentPlan;
• complete DataView fail-close projection for sensitive fields, sections, and unmatched or missing action boundaries;
• audit-persistence readiness that detects synchronous and asynchronous sink failures, retries when configured, and denies the governed result when its audit record cannot persist;
• AirDesk plus service-delivery and internal-approval fixtures for founder, ops manager, frontline staff, customer, AI agent, and auditor surfaces.
• CompanyOS policy projection helpers that compose policy/authority decisions into RoleMorph boundaries and fail closed when projections are missing or actor/workflow-mismatched.

RoleMorph may consume adaptive hints, but authorization, policy, permissions, and action boundaries remain explicit contract inputs.

Governed RichReference policy decisions await their audit sink. Production PersonalOS composition uses the server-only PostgreSQL durable sink rather than the development console sink: persistence failure denies the decision, while delivery retry, dead-letter health, and explicit recovery remain observable without storing payload values.

CommunicationOS and other downstream shells can consume projectRoleMorphCapabilities() from the ./rolemorph barrel. Live route adoption remains owned by those packages; this library does not claim downstream wiring or derive human capabilities from the AI-only agentPlan compatibility field.

Ontology-linked RoleMorph authoring

RoleMorph decisions participate in the ontology graph through stable refs rather than local-only labels. Surface specs and resolution results should be able to explain which ontology actor, work, surface, resource, adaptation, and safety refs influenced visible components, hidden data, and enabled actions.

For the Autonomous Work Order slice, founder/operator/auditor/agent surfaces must all point at the same work-order graph: pages and DataViews are surface nodes, orders and workflow transitions are work nodes, humans and agents are actor nodes, source documents and evidence receipts are resource nodes, behavior/adaptive decisions are adaptation nodes, and policy/approval/audit/redaction records are safety nodes.

High-impact RoleMorph actions must fail closed when ontology safety refs are missing or mismatched. Display-only and low-risk render decisions may remain policy-optional, but explanations should still carry evidence refs when they are part of a governed work-order trace.

Public Entry Points

• Exports runtime, spec, React integration, adapters, telemetry, eval, and example subpaths for AI-native surface composition.
• Export . resolves through ./src/index.ts.
• Export ./adapters resolves through ./src/adapters/index.ts.
• Export ./adapters/ai-sdk-stub resolves through ./src/adapters/ai-sdk-stub.ts.
• Export ./adapters/blocknote-stub resolves through ./src/adapters/blocknote-stub.tsx.
• Export ./adapters/dnd-kit-adapter resolves through ./src/adapters/dnd-kit-adapter.tsx.
• Export ./adapters/dnd-kit-stub resolves through ./src/adapters/dnd-kit-stub.ts.
• Export ./adapters/floating-ui-stub resolves through ./src/adapters/floating-ui-stub.tsx.
• Export ./adapters/interfaces resolves through ./src/adapters/interfaces.ts.
• Export ./adapters/motion-stub resolves through ./src/adapters/motion-stub.ts.
• Export ./adapters/resizable-panels-stub resolves through ./src/adapters/resizable-panels-stub.tsx.
• Export ./feature-hubs resolves through ./src/feature-hubs/index.ts.
• Export ./rolemorph resolves through ./src/rolemorph/index.ts.
• Export ./rolemorph/types resolves through ./src/rolemorph/types.ts.
• Export ./rolemorph/companyos-policy resolves through ./src/rolemorph/companyos-policy.ts.
• Export ./rolemorph/companyos-policy-types resolves through ./src/rolemorph/companyos-policy-types.ts.
• Export ./rolemorph/companyos-policy-fail-closed resolves through ./src/rolemorph/companyos-policy-fail-closed.ts.
• Export ./rolemorph/resolver resolves through ./src/rolemorph/resolver.ts.
• Export ./rolemorph/validation resolves through ./src/rolemorph/validation.ts.
• Export ./rolemorph/fixtures resolves through ./src/rolemorph/fixtures/index.ts.
• Export ./rolemorph/fixtures/airdesk resolves through ./src/rolemorph/fixtures/airdesk.ts.
• Export ./rolemorph/fixtures/service-delivery resolves through ./src/rolemorph/fixtures/service-delivery.ts.
• Export ./rolemorph/fixtures/internal-approval resolves through ./src/rolemorph/fixtures/internal-approval.ts.
• The package publishes 65 total export subpaths; keep docs aligned with package.json.

Local Commands

• bun run dev — contractspec-bun-build dev
• bun run build — bun run prebuild && bun run build:bundle && bun run build:types
• bun run test — bun test --pass-with-no-tests
• bun run lint — bun lint:fix
• bun run lint:check — biome check .
• bun run lint:fix — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
• bun run typecheck — tsgo --noEmit
• bun run publish:pkg — bun publish --tolerate-republish --ignore-scripts --verbose
• bun run publish:pkg:canary — bun publish:pkg --tag canary
• bun run clean — rimraf dist .turbo
• bun run build:bundle — contractspec-bun-build transpile && node scripts/fix-use-client-directive.mjs
• bun run build:types — contractspec-bun-build types
• bun run lint:adapters — node scripts/lint-adapters.mjs
• bun run test:evals — bun test src/evals/
• bun run prebuild — contractspec-bun-build prebuild

Recent Updates

• Replace eslint+prettier by biomejs to optimize speed.
• Export, sidebar, workflow tools, slotContent.
• Vercel AI SDK parity + surface-runtime i18n and bundle alignment.
• Bundle spec alignment, i18n support, PM workbench pilot.
• RoleMorph first canonical serialized runtime slice with AirDesk fixtures and Builder preview inputs.
• RoleMorph gap-closure hardening adds non-AirDesk fixtures and a fail-closed CompanyOS policy projection bridge without provider or storage side effects.

Notes

• No direct third-party UI imports outside src/adapters/ (when adapters are added).
• Every surface must have verification.dimensions for all 7 preference dimensions.
• Adapter rule: BlockNote, dnd-kit, etc. behind adapter boundaries only.

RoleMorph rich content adapter

@lssm/lib.surface-runtime/rolemorph/rich-content-adapter converts RoleMorph permission and policy decisions into rich-content redaction policies for code and diff payloads. Use it before rendering governed CodeBlock and DiffBlock surfaces so denied references or sensitivity classes are removed from client-safe models.

Published export maps include explicit browser conditions for the emitted browser artifacts, alongside the existing Node and Bun conditions. A browser bundler can select these without relying on the default server-runtime condition.