Skip to main content

Assistant Composition Package

@maya/assistant-composition is the public headless composition contract package for Maya's workspace composition kernel. It defines stable data contracts for module contracts, resolved runtime summaries, contribution descriptors, explicit policy, diagnostics, opaque render handles, WorkspaceComposition, WCP-009 namespace validation, WCP-010 policy validation/application, WCP-011 composeWorkspace(), and WCP-013 Claude built-in descriptor fixtures.

This package is publishable as the shared headless contract used by hosts, trusted module packages, @maya/assistant-ui, and product-kit builders. It is not a runtime plugin registry and it does not execute UI. Claude Workspace and Data Lab remain workspace-private in v0; only the composition contract itself is public.

Install​

Install it directly when a host, product kit, or trusted module package needs the headless contract types or composeWorkspace():

pnpm add @maya/assistant-composition

The smallest first-use path is data-only and has no React runtime:

import { composeWorkspace } from '@maya/assistant-composition';

const result = composeWorkspace({ builtins: [], modules: [] });
if (!result.ok) throw new Error(result.diagnostics[0]?.message ?? 'Composition failed');

Headless Boundary​

The package belongs to the structure layer:

  • Host applications resolve module runtime.
  • @maya/assistant-composition composes workspace structure.
  • @maya/assistant-ui executes React rendering through a scoped render runtime.
  • @maya/claude-workspace packages Claude Web product defaults.

The package must stay headless: no React, DOM, CSS, fetch, storage, host adapter, backend adapter, or browser API dependency belongs here. The durable kernel contract is specified in .docs/architecture/workspace-composition-kernel.md; the render execution boundary is specified in .docs/architecture/workspace-composition-react-render-runtime.md.

Public Core Type Exports​

ExportPurpose
@maya/assistant-compositionHeadless composition type contracts and package identity metadata.
@maya/assistant-composition/package.jsonPackage metadata for tooling.

The root export includes:

AppliedCompositionPolicyCandidate, AppliedCompositionPolicyGraph, AppliedCompositionPolicyOrderEntry, AppliedCompositionPolicyRendererClaimBinding, AssistantCompositionApiVersion, AssistantCompositionPackageInfo, AssistantCompositionPackageLayer, AssistantCompositionPackageStatus, BaseComposedContribution, BaseContribution, BuiltinContributionSet, CanonicalContributionKey, CanonicalContributionKeyParts, ComposedFallbackSurface, ComposedMessageAppender, ComposedRenderer, ComposedRendererClaimBinding, ComposedRoute, ComposedRuntimeSummary, ComposedSidebarItem, ComposedSurface, ComposeWorkspaceInput, ComposeWorkspaceResult, CompositionJsonArray, CompositionJsonObject, CompositionJsonPrimitive, CompositionJsonValue, CompositionPolicy, CompositionPolicyApplicationInput, CompositionPolicyApplicationResult, CompositionPolicyCandidate, CompositionPolicyEffect, CompositionPolicyGraph, CompositionPolicyOperation, CompositionPolicyReference, CompositionPolicyValidationInput, CompositionPolicyValidationResult, CompositionSchemaVersion, ContributionKind, ContributionOwner, DiagnosticSchemaVersion, DiagnosticSubject, FallbackSurfaceContribution, MessageAppenderContribution, MessageAppenderPosition, ModuleApiVersion, ModuleCapabilityRequirement, ModuleConfigurationKind, ModuleConfigurationRequirement, ModuleContract, ModuleFallbackSemantics, ModuleHostStorageDurability, ModuleHostStorageRequirement, ModulePermissionRequirement, ModuleRequirement, ModuleRequirementCollection, ModuleRequirementId, ModuleRuntimeStatus, PolicySchemaVersion, RenderHandle, RenderHandleData, RenderHandleVersion, RendererClaim, RendererClaimKind, RendererClaimParts, RendererContribution, RequiredRenderHandle, ResolvedModuleInstance, ResolvedModuleRuntime, RouteContribution, RoutePath, RuntimeAction, RuntimeActionKind, SidebarItemContribution, SurfaceContribution, SupportedCompositionVersions, WorkspaceComposition, WorkspaceCompositionModule, WorkspaceContributions, WorkspaceDiagnostic, WorkspaceDiagnosticCategory, WorkspaceDiagnosticCode, WorkspaceDiagnosticOrigin, WorkspaceDiagnosticSeverity, WorkspaceNamespaceValidationInput, WorkspaceNamespaceValidationResult, applyCompositionPolicy, assistantCompositionApiVersion, assistantCompositionPackageInfo, composeWorkspace, formatCanonicalContributionKey, getAssistantCompositionPackageInfo, isValidBuiltinOwnerId, isValidInstanceId, isValidLocalId, isValidRendererClaim, isValidRoutePath, parseCanonicalContributionKey, parseRendererClaim, validateCompositionPolicy, and validateWorkspaceNamespace.

Runtime Status​

ModuleRuntimeStatus supports ready, readOnly, needsConfiguration, unauthorized, disabled, and error.

The host resolves these statuses from deployment capability, tenant policy, user permission, configuration state, and backend health. The composition package only models the granted runtime data that the host has already resolved.

Render Handles​

RenderHandle is typed opaque data with renderHandleVersion, kind, id, and optional JSON data. render handles cannot carry executable UI, component references, dynamic imports, loaders, callbacks, or render functions.

@maya/assistant-ui and host-provided scoped render runtime code are responsible for mapping handles to executable React UI later in the pipeline.

Explicit Policy​

The v0 CompositionPolicy type only models explicit hide, reorder, replace, pathAlias, and rendererOverride operations. It does not model local patching, DOM selector hooks, implicit overrides, plugin marketplace installs, iframe isolation, remote ESM, or runtime untrusted installation.

Policy Validation And Application​

validateCompositionPolicy() validates an explicit v0 policy against a flat CompositionPolicyGraph. applyCompositionPolicy() first runs the same validation, then returns an AppliedCompositionPolicyGraph, sorted policyEffects, and structured diagnostics. Invalid policy is atomic: any error keeps graph: null and policyEffects: [].

The policy graph is an intermediate composer candidate graph, not WorkspaceComposition. Policy application does not resolve grants, decide authorization, materialize fallbacks, generate the final required render-handle manifest, execute render handles, or create missing render handles. It preserves the selected contribution's own opaque renderHandle data and reports deterministic diagnostics for missing targets, inactive targets, duplicate operations, replacement cycles, reorder cycles, protected default text renderer overrides, and dangling references created by hide or replace.

Namespace Validation​

validateWorkspaceNamespace() validates declared built-in and module contribution namespaces before the full composer lands. It emits structured WCP-003 diagnostics for duplicate module instances, duplicate canonical contribution keys, route path conflicts, renderer claim conflicts, invalid local IDs, invalid route paths, invalid renderer claims, and protected default text renderer claims.

The namespace validator does not apply policy, perform runtime resolution, materialize fallbacks, produce WorkspaceComposition, or select winners by import order.

Composition Kernel​

composeWorkspace() composes built-ins, host-resolved module instances, and explicit policy into a WorkspaceComposition. It validates structure and supported versions, preserves the single built-ins/modules pipeline, gates contributions by resolved runtime status, materializes explicit fallback surfaces, applies WCP-010 policy through applyCompositionPolicy(), detects effective route and renderer conflicts after policy, and collects the deterministic requiredRenderHandles manifest.

composeWorkspace() does not resolve grants, decide authorization, fetch data, access storage, execute render handles, inspect render packs, import React, or create fallback UI. Runtime status is already host-owned input; grants remain UI activation context rather than a security boundary.

WCP-011 fixtures live in projects/assistant-composition/test/fixtures/wcp-011 and lock success, route conflicts, renderer conflicts, explicit policy effects, runtime statuses, fallback materialization, and required render handle manifest behavior.

WCP-013 fixtures live in projects/assistant-composition/test/fixtures/wcp-013 and lock Claude product default descriptors as composition inputs. WCP-019 exports the matching descriptors from @maya/claude-workspace. They cover fixture-claude-builtins-default-composition, fixture-kernel-builtins-and-modules-same-pipeline, fixture-builtin-any-non-ready-fallback-omitted, built-in/module route conflicts, built-in/module renderer conflicts, owner-shape diagnostics, builtin-claude-workspace ownership, status-specific built-in fallback surfaces, and render-handle manifest coverage. WCP-011 policy fixtures continue to cover built-in hide and replace behavior; WCP-013 adds Claude product identity and parity coverage on top.

Verification​

Changing this package requires running the build before the package test because package tests execute built dist output:

  • pnpm build:composition
  • pnpm --filter @maya/assistant-composition typecheck
  • pnpm --filter @maya/assistant-composition test
  • pnpm --filter @maya/assistant-composition pack:check
  • pnpm verify:package-registry
  • pnpm verify:source-boundaries
  • node tools/verify-public-api-surface.mjs
  • node tools/verify-docs-api-parity.mjs
  • pnpm security:supply-chain

Canonical package documentation stays in .docs/packages/assistant-composition.md. Package-root README copies, generated dist docs, and copied package docs are intentionally excluded from the package so there is no second documentation truth. The package tarball is limited to dist, LICENSE, and package.json.