lib.surface-runtime

@lssm-tech/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-tech/lib.surface-runtime

or

bun add @lssm-tech/lib.surface-runtime

Usage

Import the root entrypoint from @lssm-tech/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-tech/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-tech/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.

The conflict resolver and widget palette consume declared UIkit-web themed primitives. Their rendering, keyboard/focus behavior, callbacks, translations and public prop shapes are preserved. They do not depend upward on DesignSystem; a surrounding DesignSystemThemeProvider still supplies resolved component customization through the shared web context.

Canonical builds retain the intentional published export map (exports.rewrite: false). New production roots must be declared in the existing build entries and manifest together; generation must not silently rename or drop supported aliases or platform conditions. Full artifact verification checks every advertised target, including native aliases. Test fixtures remain in source verification while excluded from production entry discovery.

RoleMorph consumes complete portable models from Core and the canonical rich-reference registry, audit ports, redaction and denial signer from Kernel. Current behavior, registration, defaults and tests are preserved. Adaptive shell validation requires the complete separately staged Surface validator owner; Company fixture bindings require their owning generator. Other Surface Legacy dependencies remain until their actual families are migrated.

Navigation composition

Utiliser @lssm-tech/lib.surface-runtime/navigation for the existing generic navigation contracts and NavRegistry. The narrow ./navigation/nav-surface, ./navigation/nav-graph, and ./navigation/registry entries expose the same contracts, validators and registry independently.

./capabilities/registry owns the existing CapabilityRegistry, capability query helpers and their documentation. It retains latest-version selection, reverse surface indexes and inheritance resolution. Navigation validates capability bindings through this canonical registry. Portable capability models remain in ContractSpec Core. Historical ContractSpec navigation and capability imports forward to these exact implementations.

Feature-hub policy declarations, signed discovery metadata, and injected replay/intent/lease ports have canonical leaves under ./feature-hubs/contracts/{policy,registry,ports}. These declarations neither execute policies nor confer runtime authority. Legacy entrypoints forward the same complete contracts.

./adaptive-shell/validation owns the existing complete adaptive-shell spec and resolution validators and definition factories. Diagnostics retain their original order, invariant requirements and fail-closed checks. Pure models come from ContractSpec Core; historical validation imports forward to these functions.

Autonomous Work Order fixture source projection

Managed CompanyOS owns the complete semantic authoring modules under generation/rolemorph/. They are source-generation inputs with the original Surface module context, outside the bundle TypeScript src include and builder entry patterns. They are never compiled or imported as a second runtime.

SurfaceRuntime retains its published fixture paths, barrel and singleton instance. Its contributor fixture:generate workflow parses the canonical ontology source and Core constructor source without importing either runtime module, then emits the complete original fixture bodies and a private typed six-reference binding. fixture:check rejects stale projections. Input SHA256 provenance covers both whole fixture sources, ontology/Core source and generator code; changed inputs are rejected before writing and after completion. Preparation, development, checks and publication inputs include the higher authoring source directly, without a bundle-build prerequisite or platform-to-domain dependency.

The bundle exposes ./fixtures/autonomous-work-order and ./fixtures/autonomous-work-order-helpers as exact forwards to the same Surface instance. The generator admits only the existing six literal ontology records and the known import projection. It does not evaluate product policy or emit approvals. Generated outputs and their qualification are pending the controlled owning workflow; Source implementation alone is not resulting-tree acceptance.

Complete documentation registry ownership

The compatible ./docs leaves own the complete existing registry, default seeded manifest and documentation-presentation family. Legacy forwards retain the same class, singleton, functions, registration order, errors, fixed seed metadata and objects. The canonical manifest generator keeps its existing scan algorithm and writes the relocated owning seed. Original tests continue to exercise compatibility routes; source parity does not replace generator, runtime or declaration qualification.

Canonical ontology graph/registry and capability context, guards and validation leaves preserve historical object/class identity and authority.

The explicit visualizations/registry leaf owns the canonical visualization registry. Historical imports preserve identical registry identity; visualization schemas remain with their existing Core owner.

Reference resolve/detail definitions and registration, deterministic detection, agent serialization envelopes and fail-closed markdown round trips now have canonical rich-reference and operations leaves. Core serialization/brands and Kernel registry/signer identities remain unchanged. The data-view helpers, entity compatibility and feature validation leaves retain their original behavior.

Ontology reference fixture

The existing Autonomous Work Order reference fixture is owned by the isolated ontology/autonomous-work-order.fixture subpath. The contracts-spec compatibility leaf forwards to the same objects and preserves its existing publication conditions.