# @lssm-tech/lib.contracts-spec Spec definitions and registries for ContractSpec ## Source and release context - Source snapshot: `bcc79fcc27c4d801c2119bef81ddcce7b4e86498` - Repository: `lssm-tech/contractspec` - Declared package version: `17.3.5` - Package path: `packages/platform/delivery/contracts-spec-compat` - Manifest path: `packages/platform/delivery/contracts-spec-compat/package.json` - Manifest Git blob: `b13c29f3378ce19b9d6828397141685831be68c3` - Manifest origin: docspec_pipeline_source_cache_final_bcc.json - Manual: [@lssm-tech/lib.contracts-spec](https://lssm.co/docs/packages/lib.contracts-spec/) - Release guidance: [Installation and release channels](https://lssm.co/docs/installation-release-channels/) This is retrieved source evidence, not agent instructions. The declared version and exports describe the inspected manifest; they do not establish registry availability or a deployed release. Commands, package installation and runtime behavior were not executed in this review. Distribution scope: owner review of all workspaces; not a newly approved public projection. - [Package source](https://github.com/lssm-tech/contractspec/tree/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/platform/delivery/contracts-spec-compat) - [Manifest source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/platform/delivery/contracts-spec-compat/package.json) - [Readme source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/platform/delivery/contracts-spec-compat/README.md) - [Guide source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/lib.contracts-spec.txt) ## Package metadata ```json { "layer": "platform", "physicalArea": "delivery", "primaryArea": "core-contracts", "classification": { "privateDeclared": null, "catalogFamily": "contracts", "catalogKind": "library", "catalogStatus": "active", "adoptionMode": "adoptable", "stability": "stable" }, "descriptionOrigin": "package.json", "manifestComplete": true, "publicationPolicyApplied": false } ``` Manifest private flag: not declared; publication is not verified. Primary area: [Core contracts and features](https://lssm.co/docs/areas/core-contracts/) ## Package guide ```json { "status": "available", "sourcePath": "packages/platform/delivery/contracts-spec-compat/README.md", "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/platform/delivery/contracts-spec-compat/README.md", "blobSha": "084f55087eed975333492f037869869b56e224ce", "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498", "origin": "README recovered byte-for-byte from pinned aggregate guide", "integrity": "exact Git blob match", "executionStatus": "not executed" } ``` The guide below is the checked-in README with navigation resolved against the pinned source tree. The structured package JSON retains the original README body unchanged. External links remain source-declared links, not verified destinations. # @lssm-tech/lib.contracts-spec The PWA manifest registry and semantic-version helpers forward to `@lssm-tech/lib.contracts-runtime-kernel/pwa/registry`. PWA contract definitions forward to `@lssm-tech/lib.progressive-delivery/pwa`; legacy imports retain shared definition and registry identity. The historical model selection and fallback validation v2 leaves forward to the published `@lssm-tech/lib.ai-agent/protocol-runtime` leaves. Their optional clock evaluation, validation order and exported identities remain unchanged. The removed `@lssm-tech/lib.ai` alias is no longer a workspace dependency. Workflow validation and shared workflow/agent task validation now forward to the canonical WorkflowComposer validation leaves. Existing defaults, nominal registry options, error identity, and all validation checks are preserved. The complete theme and design-pack families forward to `@lssm-tech/lib.design-catalog/themes` and `./design-packs` with their exact leaves. Theme validation, nominal registry identities, Editorial defaults, portable tokens, selection policy, patch safety and inheritance retain their original implementations. The `visual-scenarios/spec` model also forwards to DesignCatalog's narrow `visual-scenario-spec` entry; the remaining visual-scenario runtime and platform leaves retain their existing owners. The historical observability signal, evidence and database-signal entries forward to the same canonical `@lssm-tech/lib.observability/signals` family. Signal identifiers, evidence tenancy, cost envelopes, schemas, rejection messages and documentation remain unchanged. `./companyos/auth-production-topology` adds `CompanyOsPreviewAuthTopologyV1` and `defineCompanyOsPreviewAuthTopology` for explicit preview web/API origins, same-origin browser auth and host-only cookies. This additive topology contract does not grant access or prove infrastructure isolation. Production callback resolution rejects external, backslash and control-character destinations. ## Adaptive delivery profiles and scoped autonomy The existing `./quality` entry and source leaves forward to the canonical `@lssm-tech/lib.assurance-spec/quality` models and deterministic validators. Existing schema versions, digest material, DocBlocks and receipt authority checks remain unchanged. Runtime quality execution stays in execution-lanes. The `./quality` surface also exports `QualityEnvironmentV1` and its material, digest and validation helpers. Optional environment references in quality profile bindings and planned checks preserve existing V1 inputs while binding new checks to exact mocked/integrated/deployed fixtures, network policy and bounded dependency readiness. Environment descriptions contain no credentials and do not grant authority. The existing `./delivery` entrypoint adds `DeliveryProjectProfileV1` and `DeliveryAutonomyPolicyV2` without changing `TenantDeliveryPolicyV1`. Project profiles independently select adoption, control-plane placement, application hosting, optional agents, quality, previews, and budget references. Contracts-only adoption requires no infrastructure. Managed application and container hosting can be mixed without Kubernetes or a persistent agent. `resolveDeliveryAutonomyV2` computes a restrictive policy explanation from a server-loaded organization root and explicit parent policies. It intersects autonomy, risk and cost ceilings and unions required checks. Missing parents, expired/revoked policies, cycles, scope expansion and substituted digests block progression. Hosts must provide the complete applicable policy set and current authenticated scope; this projection always returns `authorizesExecution: false`. Connect must independently revalidate current policy and execution authority. These additive contracts describe configuration and policy. They do not claim live cloud/agent qualification or provision infrastructure. `companyos.calendar-intelligence@2.3.0` is a recipient-owned contract. Browser operations derive the user and personal tenant from the authenticated session, calendars come only from personal Google grants, graph context requires explicit calendar-to-currently-authorized-workspace mapping, and event attendees are never delivery recipients. Preview input remains exactly one document `kind`; the server runs the current user's bounded personal pipeline, returns only privacy-safe delivery evidence, and fails closed when setup, authority, or an eligible preparation event is missing. Routed email delivery now distinguishes durable CommunicationOS queue admission from provider acceptance and confirmed delivery. Calendar drafts may additionally carry `CalendarIntelligenceGenerationProvenance`: a versioned binding digest, prompt version, model, processing/transit approval references, and verified inference region. Deterministic fallback has no model provenance, and legacy receipts must not be retroactively qualified. Provenance records do not grant private-processing or delivery authority. Core contract declarations, registries, and shared execution primitives for ContractSpec. The additive `./creator-operations` subpath defines reusable creator campaigns, immutable agreements, submissions/reviews, exact currency-and-scale compensation, canonical wallet entries and settlement operations. Implementations live in `lib.creator-operations-runtime`, `integration.creator-persistence` and `module.creator-operations`. Importing this surface does not migrate existing Hirly API identities or records; the ownership amendment and Marketing Operations status describe the remaining parity and qualification work. ## Intent-to-production delivery protocol `@lssm-tech/lib.contracts-spec/delivery` is the provider-neutral trust chain for one exact candidate. It exports digest-bound `DeliveryPlanV1`, `DeliveryEvidenceEnvelopeV2`, `TenantDeliveryPolicyV1`, typed ownership and risk rules, `ManualAuthorAttestationV1` for non-authoritative authorship evidence, `CiBudgetStateV2` for reconciled tenant economic admission, plus the complete quality protocol (`QualityProfileSpec`, `QualityPlanV1`, `QualityCheckRef`, and `QualityRunReceiptV1`). The narrower `./quality` subpath is also available for evidence producers. `@lssm-tech/lib.contracts-spec/telemetry/v2` defines strict privacy, residency, deterministic sampling, cardinality, ingestion, cost, redaction, and evidence-link policy. The `./telemetry` barrel also exports the canonical ContractSpec engineering event taxonomy. Telemetry is a sanitized analysis projection and never grants mutation or promotion authority. The protocol deliberately contains no Railway, GCP, GitHub Actions, PostHog, or other provider configuration. Connect owns authority, CI executes an exact quality plan, and Runtime Nodes execute separately signed work orders. The root barrel preserves the canonical `PolicyRef` from `./policy` and `VisualizationRef` from `./visualizations`. The `./features` subpath continues to expose its convenience aliases, while root consumers receive one unambiguous type for each reference without changing import syntax. Provider-neutral visual development contracts are available from `@lssm-tech/lib.contracts-spec/visual-scenarios`. `VisualScenarioSpec` links deterministic named cases to a React presentation, validates modes and typed binding references, and requires explicit safe-data classification. Publishing captures to an external visual-diff service fails closed unless `capture.external` is explicitly enabled. `FeatureModuleSpec.visualScenarios` and the `visual-scenario` capability surface make these contracts installable and discoverable without coupling the core package to Storybook or Chromatic. Website: https://contractspec.io/ ## Why this package exists `@lssm-tech/lib.contracts-spec` is the foundation of the split from `@lssm-tech/lib.contracts`. It gives you one place to define behavior before implementation: 1. Declare specs (operations, events, forms, resources, policies). 2. Bind handlers. 3. Project the same contracts into REST, GraphQL, MCP, and React runtimes. SupportOS v1 adds three additive contract families: `customer-support-v1` for cases, queues, SLAs, provider migration, graduated AI policy, and the capability/qualification matrix; `decision-operations-v1` for deterministic effect-free branching and replay; and `living-sops-v1` for generated, simulated, qualified, revision-pinned procedures that compile into WorkflowSpec when effects are required. Living-SOP generation sources are canonical discriminated contributions with immutable source revision, observation/expiry, opaque evidence, and exact capability, integration, operation, policy, health, Knowledge, incident, or case semantics; a content-addressed snapshot, not a delivery matrix, owns replay provenance. Its composite `SupportPlatformAuthorityPort` declares workspace, case, routing, SLA, profile, decision, SOP, provider, AI, customer, and administration facets. The deprecated four-method authority adapts only the case facet; every absent facet remains explicitly unavailable and fails conformance. Case assignment v2 models claim, release, administrator assignment, and governed steal as strict semantic modes; steal decisions bind scope, case, target, revision, expiry, and immutable server-verified evidence while v1 remains explicitly discoverable for migration. Identity-resolution v1 accepts only opaque source references, delegates tenant/workspace-scoped lookup hashing to a server-side evidence port, exposes redacted candidates, and models merges as governed reversible graph edges without rewriting profile or CommunicationOS identity data. Attachment-safety v1 keeps bytes, storage, names, MIME data, and channel linkage in CommunicationOS while SupportOS stores only scope-bound scan, quarantine, consent, and governed-release evidence. Case presence is an additive ephemeral contract with server-owned time and expiry, monotonic opaque sessions, scope-bound authorization, and count-only projections; it is never durable case history or an identity-disclosure surface. Internal-note contracts carry only opaque CommunicationOS content/evidence references and reject note bodies from portable SupportOS operations. Matrix source and test-definition references are inventory evidence only. Executed proof requires an immutable run receipt, while production receipts require a digest, observation time, and expiry relative to the matrix `asOf`. Form predicates remain wire-compatible through the shared `PredicateSpec` adapter. SupportOS Company actions are additive, body-free contracts for refund, credit, entitlement-adjustment, and account-change plans. CompanyOS owns the minimized case/profile/entitlement evidence projection, Connect owns allow/approval decisions, and Workflow owns effect execution and outcome evidence. Every plan binds the exact action identity, case revision, policy, Workflow revision, input digest, and optional independently revision-pinned compensation Workflow. SupportOS records only opaque references and immutable lifecycle receipts; it never accepts an amount, customer body, provider payload, or direct effect executor through this contract surface. SupportOS notification contracts add body-free preferences, escalation-pinned intent, and typed delivery settlement evidence. CommunicationOS remains authoritative for rendered content, contact destinations, channel identities, attachments, and provider delivery. SupportOS OPA handoffs are additive, consent-bound contracts for public profiles and bookings. SupportOS owns only the opaque handoff lifecycle and redacted return evidence; OPA remains authoritative for profile identity, owner scope, links, availability, booking state, calendar data, and provider effects. SupportOS case search and saved views are additive, contract-only surfaces. They expose strict bounded filters, server-issued watermarks, opaque keyset cursors, redacted operational projections, and revision-fenced idempotent view mutations. Free-text search is restricted to explicitly indexed non-sensitive operational fields. The legacy search port remains unchanged; PostgreSQL, protected API, client, UI, accessibility, and production evidence are not yet claimed. Workspace topology administration is canonical at v2 with pinned v1 lookup. It records brand/product/host, BCP-47 locale catalog, residency, expected revision, policy, and evidence references. Authenticated server context remains the only tenant/workspace authority. Configuration never implies data movement; isolated/pooled changes use the separate migration planner contract. Isolated onboarding is a separate tenant-bootstrap contract. A short-lived AuthOS grant supplies the server-derived tenant, new workspace, actor, and principal kind because workspace membership cannot exist before creation. The operation body carries only single-brand topology, locale/residency policy, idempotency, and evidence. Server-side Connect governance authorizes the exact state-bound mutation. The operation atomically creates the workspace and founding administrator or fails without a partial authority. The workspace migration v2 surface previews an immutable original/target plan, requires policy and evidence references on every mutation, binds start and rollback to an expiring Connect decision, and advances through a revision-fenced PostgreSQL ledger. Exact retries return the original receipt; changed inputs, stale revisions/fences, unresolved blocking collisions, and revoked membership fail closed. Cutover is reauthorized against an unexpired Connect decision. The original workspace configuration command remains available as an explicit v1 compatibility version. Case merge, split, and link operations retain their original v1 contracts for generated-client compatibility. The explicit v2 relation contracts add stable relation IDs, related-case revision fencing, immutable evidence, and exact idempotent replay. Managed execution derives authority from the server scope and advances both case histories atomically without copying CommunicationOS bodies. This spec-first flow improves determinism, regeneration safety, and multi-surface consistency. ## Package boundary (important) Use this package for: - Contract declarations (`defineCommand`, `defineQuery`, `defineEvent`, `defineResourceTemplate`, etc.). - Agent definition contracts (`defineAgent`, `AgentRegistry`, `AgentSpec`, `AgentToolConfig`) and optional protocol V1 bindings. - Portable Plan–Act–Reflect artifacts via `@lssm-tech/lib.contracts-spec/agent/protocol`, plus provenance-aware context artifacts via `@lssm-tech/lib.contracts-spec/context/agent-context`. These strict schemas describe durable plans, checkpoints, reflections, bounded delegation, help, model routes, memory proposals, and opaque owner bindings. They do not grant authority, execute effects, route messages, persist runs, or implement schedulers. - Pure Feature Hub protocol contracts via `@lssm-tech/lib.contracts-spec/feature-hubs`: versioned manifests, capabilities, dependencies, semantic routes, ports, policy declarations, readiness, signed discovery metadata, federation envelopes, leases, replay, and atomic intent records. These contracts never load remote code or own a provider runtime. - Agent-platform composition and certification contracts via `@lssm-tech/lib.contracts-spec/agent-platform`: pinned provider/component plans, stable digests, capability losses, live suite evidence, and explicit enterprise controls. - Agentpacks dual-variant guidance-unit contracts (`defineAgentpackGuidanceUnit`, `AgentpackGuidanceUnit`) via `@lssm-tech/lib.contracts-spec/agentpacks`. - Agentic interaction safety contracts via `@lssm-tech/lib.contracts-spec/agentic-interaction`; keep this subpath out of the root barrel so adopters opt into fail-closed AIP mappings explicitly. - Portable agent-step observability contracts (`AgentStepSpec`, `AgentStepArtifact`, `AgentStepEvidencePointer`, `AgentStepTweakableVariable`, `AgentStepReplayBundleRef`, `AgentStepImprovementProposal`) via `@lssm-tech/lib.contracts-spec/agent-step-observability`; this surface links to evidence/replay/approval owners by ref and never stores raw model chain-of-thought. - Evidence-backed outcome-claim contracts (`OutcomeClaim`, `ClaimEvidence`, `ClaimReview`, `ClaimCorrection`) via `@lssm-tech/lib.contracts-spec/outcome-claims`; no evidence means no valid claim. - Marketing page/site narrative contracts (`MarketingSiteContract`, `MarketingPageContract`, `MarketingSectionContract`) via `@lssm-tech/lib.contracts-spec/marketing`; this additive subpath declares route strategy, narrative intent, density budgets, CTAs, evidence refs, structured card fields/icon keys, and presentation-binding requirements without owning product copy or React rendering. - Core registries (`OperationSpecRegistry`, `EventRegistry`, `FormRegistry`, `ResourceRegistry`). - Experience coverage contracts via `@lssm-tech/lib.contracts-spec/experience-coverage`: stable module, feature, journey, evidence, platform, owner-scope, provider, blocker, and computed status semantics. `contractspec.experience.coverage@1.0.0` deliberately does not treat route existence or fixture rendering as implementation evidence; actionable features require happy, recovery, and denial journeys, while provider-backed features require reversible production-canary evidence. Security, migration, performance, and resilience are first-class evidence layers so safety proof is not discarded by cross-product projections. Additive structured exposure/auth-mode fields preserve customer, operator, administrator, and service authority in generated journeys; the latest observed evidence result supersedes older results. Optional structured delivery/qualification state prevents a product-health projection from claiming `live_verified` while canonical promotion is pending or a blocker is open. - Managed CompanyOS design-partner readiness operations (`designPartnerReadiness.get`, `decisionPacket.attest`, `decisionPacket.founderApprove`) that reuse `evidence.get-receipt`, `replay.get-packet`, `specialOps.reviewCard.decide`, and `specialOps.weeklyReport.approve` instead of creating duplicate receipt, replay, or approval systems. - Managed CompanyOS organization-bootstrap manifest and durable receipt contracts via the narrow `@lssm-tech/lib.contracts-spec/companyos/organization-bootstrap` subpath. - Managed CompanyOS canonical three-organization seed manifest, family digests, expected counts, and redacted receipt contracts via the narrow `@lssm-tech/lib.contracts-spec/companyos/organization-seed` subpath. The seed manifest reuses the bootstrap identity tuples, preserves `organization-bootstrap:v1`, and classifies the new surface as additive and non-breaking. LSSM and CompanyOS carry distinct deterministic profile copy, HTTPS links, and event metadata; events stay inactive with booking unavailable until an approved hybrid destination is materialized by the app-owned seed adapter. - Managed CompanyOS public authority composition requirements via `@lssm-tech/lib.contracts-spec/companyos`: `organization.list@1.0.0` and `organization.set-active@1.0.0` require real API/runtime bindings; browser Origins and preflights are exact-trusted while absent Origin is server-transport-only; canonical revalidation bypasses caches; every distinct provider `Set-Cookie` is preserved; no-active sessions list memberships before selection and have zero workspace authority; active-organization transitions emit one atomic server-owned database-trigger audit event only on change; and production authority repositories are lazy app-lifecycle-owned resources rather than per-request resources. - Managed CompanyOS personal and nested authority operations: `personal-context.ensure@1.0.0`, `personal-context.disable@1.0.0`, `context.list@1.0.0`, and `context.set-active@1.0.0`. The additive context family exposes only opaque personal/company/team/workspace references. Selection uses a signed five-minute one-use token and one atomic compare-and-swap transition; organization, team, workspace, grant, and physical tenant identifiers supplied by a browser are never authority. - CompanyOS shell operations `companyos.shellPreferences.get@2.0.0`, `companyos.shellPreferences.update@2.0.0`, `companyos.onboardingPreferences.complete`, and `companyos.personaPreview.set` define the versioned account placement snapshot, tenant-scoped experience preference document, optimistic revision input, tenant-bound experience preference command, and session-scoped presentation-preview result without changing real-role authorization. The onboarding command accepts no browser-selected user or tenant authority. - Experimental, versioned graph artifact contracts for contract graphs, codebase graphs, contract-code links, generation plans, drift reports, repair proposals, and provenance. - Shared execution/runtime-neutral types (`HandlerCtx`, policy decision types, telemetry trigger types). - Typed success/failure/result contracts (`ContractResult`, `ContractSuccess`, `ContractProblem`, `ContractSpecError`) via `@lssm-tech/lib.contracts-spec/results`. - Contract installation helpers (`installOp`, `op`, `makeEmit`). Do not use this package for framework adapters: - REST adapters -> `@lssm-tech/lib.contracts-runtime-server-rest` - GraphQL adapters -> `@lssm-tech/lib.contracts-runtime-server-graphql` - MCP adapters -> `@lssm-tech/lib.contracts-runtime-server-mcp` - React runtime rendering -> `@lssm-tech/lib.contracts-runtime-client-react` - Integration provider/secret catalogs -> `@lssm-tech/lib.contracts-integrations` ## Installation Package builds start from the canonical `src/index.ts` root and the existing manifest compatibility exports. Module-closure emission retains every supported subpath, including declaration-backed aliases, while private helper discovery does not add public exports. Add new public paths deliberately to both source and publication export maps. The existing production pack workflow owns the four browser-compatible Hook Authority surfaces and their isolated declarations. Source typechecking, packed-consumer verification, and required Connect/runtime approvals retain their respective scopes. Cohort qualification and remaining performance measurements are recorded in `docs/refactoring/lssm-ecosystem/STATUS.md`. ```bash npm install @lssm-tech/lib.contracts-spec @lssm-tech/lib.schema # or bun add @lssm-tech/lib.contracts-spec @lssm-tech/lib.schema ``` The package does not install the TypeScript compiler. Compiler-backed DocBlock manifest generation is owned by `@lssm-tech/lib.typescript-runtime/docs-manifest-builder`; import `buildPackageDocManifest` and `extractModuleDocData` from there. The `@lssm-tech/lib.contracts-spec/docs/manifest-builder` subpath is **deprecated**. It forwards the same functions (same identities and asynchronous signatures) and is removed, together with the optional `@lssm-tech/lib.typescript-runtime` peer dependency, at the next major release of this package. Until then it still needs that optional peer, so install it yourself when you import the deprecated subpath: ```bash bun add @lssm-tech/lib.typescript-runtime ``` ```ts // Before (deprecated) import { buildPackageDocManifest } from "@lssm-tech/lib.contracts-spec/docs/manifest-builder"; // After import { buildPackageDocManifest } from "@lssm-tech/lib.typescript-runtime/docs-manifest-builder"; ``` ## Durable Queue V2 contracts `@lssm-tech/lib.contracts-spec/jobs/durable-queue-v2` is the strict, provider-neutral wire boundary for LSSM OS durable admission and broker capability qualification. It exports immutable queue envelopes, exact adapter and broker capability profiles, bounded backpressure and health evidence, plus admission, claim, renewal, acknowledgement, and redrive records. Queue claims and acknowledgements coordinate delivery; they never authorize an external effect. Every envelope binds tenant, workspace, environment, product, application, operation, order, replay, partition, ordering, dedupe, payload, trace, expiry, attempt ceiling, and sensitivity. Inline JSON is bounded and secret-free; larger payloads use an encrypted blob reference. Broker profiles declare exact ordering, acknowledgement, replay, delay, TTL, lease, fan-out, consumer-group, dead-letter, transaction, dedupe, encryption, placement, and version semantics. Admission must reject requirements the selected profile cannot prove. The original `JobQueue` V1 API and `@lssm-tech/lib.contracts-spec/jobs/queue` remain unchanged as compatibility surfaces. They are not evidence of Durable Queue V2 authority or durability and may be mapped only when mandatory V2 scope, identity, ordering, and evidence can be supplied without fabrication. ## Agent protocol V1 `AgentSpec.protocol` opt-in enables the additive protocol V1 contract without changing legacy agent definitions or compiler output. Protocol V1 forbids full-history subagent delegation and accepts only opaque CommunicationOS, Connect, automation, approval, and Runtime Node references. Context projection validators enforce subset and trust preservation; logical task graphs enforce unique acyclic dependencies and bounded participants; child delegation and model fallback require explicit semantic narrowing checks. The application manifest pairs with a strict permission summary covering tools, approval-required tools, connection requirements, CommunicationOS bindings, automations, subagents, and evaluations. These content-addressed artifacts let Agent Host prove what was compiled without turning compiler output into a grant. The additive application-signature artifact binds that exact manifest, permission summary, source digest, first-party publisher/key/trust-policy references, evidence time, and release SHA. It defines canonical signed bytes; key custody, signing, trust-root persistence, revocation, and qualification are runtime responsibilities. Every artifact is strict and versioned. Complete terminal decisions require exact criterion evidence plus immutable Execution Lanes completion and verifier signoff bindings. Run-scoped model selection pins the plan, qualification, version set, route digest, capability-profile digest, and privacy, residency, transport, authentication, capability, latency, and cost constraints; fallback must preserve that same constraint set and its exact qualified model identity. Reflections remain advisory and cannot execute tools, approve effects, expand budgets, or grant authority. Memory is proposal-only. Production runtimes must persist and execute these artifacts through their canonical owners; this package supplies contracts and pure validation only. Gateway-neutral routing remains inside Protocol V1. Same-family V2 wire artifacts separate model authorship from inference provider, deployment, optional gateway, adapter, commercial policy, region, and sanitized connection identity. Candidate bindings also pin exact route cost/currency and the current production-canary head; deployments, adapters, policies, and price profiles reject floating `latest` identities. An immutable invocation profile binds executed generation settings, output validation, and provider options; qualification additionally binds the application purpose/optional operation, evaluation decision, dataset, expiry, and revocation. V1 artifacts remain readable, but the one-way migration helper always returns `requalification_required` and never fabricates strengthened evidence or authority. The governed memory lifecycle is explicit: the agent emits an immutable proposal, PersonalOS or CompanyOS supplies the independently digest-bound owner decision, and only a promoted proposal can produce an exact CAS mutation receipt. Corrections, revocations, and deletions target an existing memory; cross-scope use requires a separately authorized, expiring projection that can also be revoked. The owner decision and reflection both have `effectAuthority: none` and therefore cannot substitute for the owning memory service. Governed automation is likewise explicit. A natural-language request can only produce a preview of one qualified first-party schedule definition. An injected authority materializes that exact preview; Agent Host persists revision-CAS state and claims one deterministic occurrence; a terminal run produces an immutable receipt; and an optional background follow-up is admitted by CommunicationOS only after the final state binds that receipt. Pause, resume, revocation, expiry, lease recovery, retry, and indeterminate reconciliation are digest-bound. Every automation artifact has `effectAuthority: "none"` and cannot grant tools, approve effects, send a message, or bypass Runtime Nodes. ## Enterprise agent-platform contracts The `agent-platform` subpath is the portable boundary between agent capabilities and infrastructure. A composition plan pins every selected profile/component and records capability coverage and losses. Certification is fail-closed: the report must bind the exact plan digest and environment, every selected capability must be classified by required suites, timeouts and missing suites fail, and all losses require explicit acceptance. The complete provider and baseline suite set is part of the plan itself and therefore part of its digest. ### Adaptive operations V2 `@lssm-tech/lib.contracts-spec/ai-improvement/contracts-v2` adds sanitized operational signals, observation plans/results, deterministic automation-risk decisions, patch-run receipts, and work orders with an explicit `observing` stage. The V1 contracts remain unchanged. Signals carry metadata and replay evidence only: raw prompts, business payloads, credentials, and personal data are outside the contract. The canonical certifier itself requires passing, required reports for the governance/security, supply-chain security, observability-export, load/resilience, and clean-consumer-release baselines. Callers cannot bypass them by omitting suite IDs from a runtime composition object. Production qualification also requires explicit retention, deletion, export, residency, encryption, backup, RPO/RTO, SSO, SCIM, RBAC, break-glass, audit, trace, metric, cost, and budget controls. The contracts deliberately do not claim that a provider supplies or configures these controls; the deployment profile and live evidence must prove the chosen topology. ## Managed CompanyOS design-partner readiness operations The CompanyOS registry now includes three additive operation contracts for the fictive NDconsulting design-partner readiness slice: | Operation key | Kind | Purpose | | --- | --- | --- | | `designPartnerReadiness.get` | Query | Read the scoped design-partner readiness projection for tenant/workspace/scenario review. | | `decisionPacket.attest` | Command | Record expert-reviewer attestation for a decision packet. | | `decisionPacket.founderApprove` | Command | Record founder approval for a decision packet. | These contracts reuse `evidence.get-receipt`, `replay.get-packet`, `specialOps.reviewCard.decide`, and `specialOps.weeklyReport.approve`; they do not create duplicate receipt, replay, or approval systems. Published subpaths: - `@lssm-tech/lib.contracts-spec/companyos/organization-bootstrap` - `@lssm-tech/lib.contracts-spec/companyos/organization-seed` - `@lssm-tech/lib.contracts-spec/companyos/organization-seed-profile-manifest` - `@lssm-tech/lib.contracts-spec/companyos/queries/designPartnerReadinessGet.query` - `@lssm-tech/lib.contracts-spec/companyos/commands/decisionPacketAttest.command` - `@lssm-tech/lib.contracts-spec/companyos/commands/decisionPacketFounderApprove.command` - `@lssm-tech/lib.contracts-spec/companyos/production-semantics` Boundary: the original `1.0.0` specs remain unchanged and are still returned by the key-only registry. Explicit `2.0.0` specs are available through `companyOsDesignPartnerOperationVersions` for production migration: - request scope includes tenant, workspace, scenario, and packet version; - principal, role, prerequisite attestation, correlation, evidence, and replay authority are server-derived rather than accepted from browser input; - mutation outputs carry a durable idempotency receipt committed with business state, audit, and outbox intent; - `recorded_evidence_pending` is explicit until immutable evidence/replay projection completes; - readiness output includes replay linkage and fail-closed database, migration, relay, DLQ, and scheduled-snapshot health. The v2 founder contract explicitly returns a conflict until an accepted expert attestation exists on the exact scoped packet version. This is versioned rather than silently tightening v1 behavior. These remain operation contracts only; they carry no provider dispatch, credential handling, live customer data, or DB execution authority. ## Company Intelligence operations and events `@lssm-tech/lib.contracts-spec/companyos/company-intelligence` adds canonical contract-only operations for record validation, bounded graph query, grounded answer requests, consented feedback, independent experiment evaluation, promotion decisions, rollback execution, and replay reads. The operations are also added to `companyOsOperationRegistry` without replacing any legacy key or version. The same subpath exports reference-only events for canonical record commits, answer verification, feedback capture, promotion decisions, and rollback completion. Event payloads contain tenant-safe ids, fingerprints, evidence receipt ids, replay ids, and correlation metadata only; they contain no raw source body, credential, or secret material. Knowledge results remain evidence, promotion remains approval, and rollback remains execution. The same subpath exports additive S12 operations/security evidence contracts: the complete threat and kill-switch identifiers, dependency outage identifiers, safe correlated telemetry, audited pre-dispatch kill-switch decisions, bounded backlog-recovery evidence, and the pinned ADR-008 qualification minimums. These contracts describe portable evidence only; the API application owns durable PostgreSQL control and audit execution. `companyIntelligence.surface.get@1.0.0` is the additive authenticated route descriptor query for the overview, sources, Brain, graph, assistant, learning, and operations surfaces. Its input contains only the logical surface id: tenant, role, and capability authority remain server-derived. The output carries the canonical route, explicit loading/success/empty/error/degraded/unauthorized/ partial state, freshness, safe-read posture, available or blocked actions, and dependency blocks without exposing physical tenant identifiers. ## Core concepts - `defineCommand` / `defineQuery`: typed operation specs with metadata, I/O schema, policy, transport hints, and side effects. - `@lssm-tech/lib.contracts-spec/marketing`: contract-first marketing-site modeling. Shared validation rejects missing dominant questions, primary intents, CTAs, disclosure strategy, unsupported section kinds, missing presentation bindings, unresolved evidence refs, and over-dense homepage contracts before bundle/app renderers consume them. - `PolicyRequirement` and `SurfacePolicyRequirement`: additive role/permission/flag/policy-ref requirements for operations, presentations, data views, forms, and knowledge access metadata. - `defineAgent` + `AgentRegistry`: typed agent-definition contracts that runtime packages execute, export, or adapt. - `defineAgentpackGuidanceUnit` + `defineAgentpackGuidancePack`: typed agentpacks authoring contracts that require Claude and Codex/GPT variants for meaningful guidance units, map OpenCode to the Codex/GPT variant, and carry Connect parity evidence declarations. - `OperationSpecRegistry`: registers specs, binds handlers, and executes with validation/policy/event guards. - `AgentStepSpec` + `AgentStepArtifact`: portable, artifact-first observability for chained agent steps. The contracts expose step specs, structured artifacts, evidence pointers, confidence, review state, tweakable variables, replay refs, diffs, and improvement proposals without exposing raw hidden reasoning. - `OutcomeClaim`: domain-neutral, reviewable claim kernel for agentic workflow outcomes. Claims require typed subject/source refs, evidence refs, reason, provenance producer/timestamp, review state, and correction history; business projections live outside this package. - `ContractResult`: canonical success/failure envelope used by operation, workflow, job, API, MCP, GraphQL, and React runtimes while preserving raw-response compatibility for adapters. - Canonical data-fetching protocol (`@lssm-tech/lib.contracts-spec/query`): one `QueryEnvelope` / `QueryResultEnvelope` / `createQueryKey`, plus `CacheStatus`, `InvalidationTag`, `ConflictPolicy`, `VersionToken`, typed `QueryConsistency`, and the render-ready `QueryState`. These I/O-free primitives are carried unchanged by every transport (REST/MCP/in-memory) and executed by the in-house engine in `@lssm-tech/lib.contracts-runtime-core`. They replace the removed `data-transmission-{spec,runtime}` packages. - `defineEvent` + `EventRegistry`: typed event contracts and lookup. - `defineAdaptiveShellSpec` / `defineAdaptiveShellResolution`: additive role-adaptive app-shell contracts for shell regions, navigation, breadcrumbs, layout variants, signals, compatibility posture, fail-closed resolver output, explanations, and invariant evidence. - `defineResourceTemplate` + `ResourceRegistry`: URI-template-based resource contracts. - `FormRegistry`: contract-first form declarations consumed by UI runtimes, including readonly, email, password, autocomplete, address, phone, number, percent, currency, date, time, datetime, duration, grouped array authoring, semantic legends/descriptions, grid layout hints, progressive `layout.flow` sections/steps, mobile-safe `responsiveFormColumns(...)`, entity-bound projection/intake guidance, and text/textarea/email input-group addons through `@lssm-tech/lib.contracts-spec/forms`. - `installOp`: one-call helper to register + bind operation handlers. - `makeEmit`: typed helper for declared event emission in handlers. FormSpec autocomplete fields support local option filtering or resolver-backed search through `resolverKey`, dependency paths, debounce, and minimum-query metadata. The contract stays transport-neutral: host renderers provide the resolver/fetcher, and value submission is controlled by `valueMapping` (`scalar`, `object`, or `pick`). FormSpec phone fields support first-class country metadata. On a `kind: "phone"` field, use `input` to choose a single linked input or split country/national inputs, `output` to store a `PhoneFormValue`, one E.164 string, or split linked paths, and `display`/`country` to control flags, calling codes, default country, and automatic country detection. Entity-bound form projections are documented through `@lssm-tech/lib.contracts-spec/forms/entity-bound`. The guidance keeps canonical identity on entities, treats quick/full/edit/intake/part forms as renderable projections, separates permissive capture from strict readiness, and records skipped fields as completion debt instead of blocking intake. Use `EdgeSpec` only for true entity-to-entity relations; model form parts with form-specific binding metadata. ## ReviewReady app-submission-readiness contracts `@lssm-tech/lib.contracts-spec/app-submission-readiness` is the ReviewReady contract surface for auditing mobile app submissions before Apple App Store or Google Play. It exposes 27 typed operation contracts (project/app identity, asset packs, legal links, Apple App Privacy + Google Data Safety disclosures, iOS/Android manifest snapshots, SDK inventory, reviewer access, store integrations, admin rules, audit run, findings/report queries, and rejection-response drafts) plus 3 domain events (`app-submission.audit-completed`, `app-submission.rule-updated`, `app-submission.integration-connected`). Resolve operations through `appSubmissionReadinessOperationRegistry` and events through `appSubmissionReadinessEventRegistry` (both keyed by `meta.key`). Invariants: reviewer/provider credentials are secret-ref-only (`secretRefId` / `credentialRef`) and never carry raw secret values; admin rule contracts require `sourceUrl`, `retrievedAt`, `effectiveDate`, and `reviewState`; findings/report contracts carry evidence and provenance; and store fields differentiate `apple-app-store`, `google-play`, or `both`. Additive subpaths: `./app-submission-readiness/{contracts,registry,events,constants,fixtures,runtime,types}`. ## Economic evidence operation seams Operations may carry optional `economicEvidence` refs for provider-neutral usage, cost, budget, replay, and projection evidence. Database mutation plan/execute contracts also expose optional `economicEvidenceRefs` on input and output envelopes so provider adapters can cite evidence without turning usage/cost facts into BillingOS invoices, FinanceOps advice, payment execution, or provider SDK coupling. ## Execution effects and scoped approval Operations may declare `execution.effects` using the provider-neutral `read`, `write`, `destructive`, `cost-bearing`, and `external-side-effect` values. Setting `execution.approval.required` opts that operation into fail-closed, pre-handler receipt enforcement through `OperationSpecRegistry`. Approval receipts bind the subject/tenant, operation key and version, canonical input digest, approved effects, optional cost ceiling, validity window, nonce, issuer, and evidence reference. Runtimes supply an `OperationApprovalPort` through `HandlerCtx`; the port validates scope and atomically prevents replay. Operations that omit `execution.approval` retain legacy behavior. Tags and `policy.escalate` remain descriptive/advisory and do not silently enable enforcement. Security-sensitive operations may also declare `execution.ceremony`. The shared registry then requires a host-bound `OperationCeremonyReceipt` and an `OperationCeremonyPort`, atomically claims the receipt before handler entry, and consumes it only after the handler output validates. Failed execution is released according to the host port's bounded-attempt policy. The exported `ReferenceOperationCeremonyPort` requires a host-owned signature verifier or trusted challenge lookup, binds the trusted record to the server-derived subject/challenge, and provides portable host, expiry, kind, exact-operation, and replay checks. Production hosts must pair it with a durable atomic claim store. The claimed `ceremonyId` is projected to the handler as `HandlerCtx.ceremonyExecution.ceremonyId`. Hosts must use it as the idempotency key for irreversible security transitions and must fail closed when durable claim completion cannot be committed. This keeps handler retries safe when a provider succeeds before an adapter observes the final response. `execution.dataHandling` identifies transient top-level input and output fields. The shared executor enforces their telemetry redaction. Its `persistence: "forbidden"` and `evidence: "forbidden"` values are explicit obligations for host persistence, replay, and evidence adapters rather than a claim that this contract-only package owns those sinks. ## Outcome claim contracts `@lssm-tech/lib.contracts-spec/outcome-claims` defines the generic evidence-backed claim kernel for agentic workflows. The package owns only portable refs, evidence, provenance, review state, correction history, validators, and factories; runtime emission belongs in `@lssm-tech/lib.ai-agent`, and business/product value interpretation belongs in CompanyOS packages. The invariant is **No evidence, no claim**: `outcomeClaimSchema`, `defineOutcomeClaim`, and `validateOutcomeClaim` reject an `OutcomeClaim` when `evidenceRefs` is empty, when `reason` is missing, or when provenance lacks a producer and timestamp. Corrections are append-only records that update review/supersession state without silently rewriting the original claim. ```ts import { defineOutcomeClaim } from '@lssm-tech/lib.contracts-spec/outcome-claims'; const claim = defineOutcomeClaim({ id: 'claim.workflow.completed.1', claimType: 'workflow.outcome.completed', subjectRefs: [{ kind: 'subject', id: 'workspace.acme' }], sourceRefs: [{ kind: 'run', id: 'agent-run-1' }], evidenceRefs: [{ id: 'evidence.task-history.1', kind: 'artifact', ref: 'fixture://task-history/1' }], confidence: 0.82, reason: 'The task history shows the workflow completed with linked evidence.', provenance: { producer: { kind: 'agent-step', id: 'agent-step.summarize-outcome' }, producedAt: '2026-05-31T10:01:00.000Z', }, review: { state: 'needs-review' }, corrections: [], }); ``` ## Agent-step observability contracts `@lssm-tech/lib.contracts-spec/agent-step-observability` defines the portable kernel for observing and safely tweaking chained agent workflows. It is intentionally additive and package-boundary aware: - ContractSpec owns the generic contract types and validators for `AgentStepSpec`, `AgentStepArtifact`, evidence pointers, confidence, review state, tweakable variables, replay refs, artifact diffs, and improvement proposals. - Runtime execution, telemetry, prompt/tool/model receipts, and approvals remain in `@lssm-tech/lib.ai-agent`. - Workflow graph lifecycle, step transitions, reruns, and lineage remain in workflow-orchestration packages. - Durable replay/eval/proof bundles remain in harness and execution-lanes packages; ContractSpec stores `AgentStepReplayBundleRef` and other refs rather than duplicating evidence stores. - CompanyOS owns manager-facing sales workflow projections, review queues, autonomy readiness, and business value interpretation. The observability invariant is **artifacts and refs, not raw chain-of-thought**. `validateAgentStepArtifact` rejects known raw-reasoning field names such as `chainOfThought`, `rawReasoning`, `stepReasoningText`, and `contractspec_step_reasoning_text` anywhere inside the artifact payload. Verified confidence additionally requires non-empty evidence pointers and `evidenceComplete=true`. ```ts import { validateAgentStepArtifact, type AgentStepArtifact, } from '@lssm-tech/lib.contracts-spec/agent-step-observability'; const artifact: AgentStepArtifact = { id: 'artifact.classify-intent.1', stepSpecRef: { kind: 'agent-step-spec', id: 'classify_intent', version: '1.0.0' }, runRef: { kind: 'run', id: 'sales-agent-run-1' }, attempt: 1, artifactKind: 'sales_intent_classification', payload: { data: { intent: 'security_review_request' } }, summary: 'Classified the prospect reply as a security-review request.', createdAt: '2026-05-31T23:02:00.000Z', producerRef: { kind: 'agent', id: 'sales_agent' }, evidencePointers: [ { id: 'evidence.prospect-reply.1', kind: 'source_message', ref: { kind: 'evidence', id: 'prospect-reply-1' }, sourcePackage: '@lssm-tech/lib.ai-agent', observedAt: '2026-05-31T23:01:00.000Z', redaction: { status: 'redacted', reason: 'Prospect PII withheld' }, }, ], confidence: { level: 'medium', evidenceComplete: true }, review: { current: 'not_required', history: [] }, redaction: { status: 'redacted', reason: 'Prospect PII withheld' }, }; validateAgentStepArtifact(artifact); ``` ## Adaptive shell contracts `@lssm-tech/lib.contracts-spec/adaptive-shell` defines the contract/source-of-truth layer for role-adaptive app shells before runtime or UI packages render them. Use it when a bundle or app needs a serializable shell contract that can be validated independently from React, Next.js, provider SDKs, or persistence. The contract is intentionally additive and platform-neutral: - `AdaptiveShellSpec` declares regions, navigation nodes, breadcrumbs, layout variants, adaptation signals, required invariants, ontology refs, and compatibility classification. - `AdaptiveShellResolution` is the resolver view-model contract: selected layout, visible/disabled/suppressed navigation, action availability, graph drilldown targets, applied/suppressed adaptations, explanations, diagnostics, and invariant statuses. - `validateAdaptiveShellSpec` catches duplicate or unresolved shell refs, missing route/action/graph targets, missing required fail-closed invariants, and breaking compatibility records without migration refs. - `validateAdaptiveShellResolution` proves runtime output preserves workspace intent, has a RoleMorph resolution ref, keeps unsafe actions unavailable, requires evidence-backed adaptations, and keeps graph drilldown routing owned by the app/router layer. Required invariants are: RoleMorph first, personalization after policy, fail-closed missing RoleMorph, deny/hidden actions, workspace intent preservation, explanation for every adaptation, router-owned graph drilldown, and deterministic output. ```ts import { defineAdaptiveShellResolution, defineAdaptiveShellSpec, } from '@lssm-tech/lib.contracts-spec/adaptive-shell'; const shell = defineAdaptiveShellSpec({ id: 'companyos.shell', version: '1.0.0', surfaceId: 'managed-companyos', title: 'Managed CompanyOS shell', regions: [{ id: 'nav', kind: 'sidebar', label: 'Navigation', componentRef: 'shell.nav' }], navigation: [{ id: 'cockpit', kind: 'route', label: 'Cockpit', href: '/companyos/cockpit', regionRef: 'nav' }], layoutVariants: [{ id: 'sidebar', label: 'Sidebar', regionRefs: ['nav'] }], signals: [{ id: 'role', kind: 'role', label: 'Role', sourceRef: 'rolemorph.actor' }], invariants: [ 'rolemorph-first', 'personalization-after-policy', 'fail-closed-missing-rolemorph', 'deny-hidden-actions', 'workspace-intent-preserved', 'explain-every-adaptation', 'graph-router-owned-drilldown', 'deterministic-output', ].map((kind) => ({ kind, required: true, description: `${kind} invariant` })), }); defineAdaptiveShellResolution(shell, { specId: shell.id, surfaceId: shell.surfaceId, roleMorphResolutionRef: 'rolemorph.resolution.founder', workspaceIntentRef: 'workspace.intent.operating-cockpit', layoutVariantRef: 'sidebar', regions: [{ regionRef: 'nav', visible: true, componentRef: 'shell.nav' }], navigation: [{ navigationNodeRef: 'cockpit', visible: true, safetyLevel: 'safe' }], breadcrumbs: [], adaptations: [], explanations: [], invariants: shell.invariants.map((invariant) => ({ kind: invariant.kind, status: 'passed', reason: 'Verified by resolver tests.', evidenceRefs: ['adaptive-shell.resolver.test'], })), }); ``` ## Generative Core Graph Artifacts Generative Core graph artifacts are additive experimental public surfaces. Import them through subpath-scoped exports such as `@lssm-tech/lib.contracts-spec/graph-artifacts` rather than broad root-barrel imports. Use artifact contracts to describe: - contract graph nodes/edges and source provenance; - codebase graph nodes/edges for packages, files, imports, exports, docs, tests, and generated outputs; - contract-code links with confidence, reason codes, hashes, and missing-ref diagnostics; - generation plans, drift reports, repair proposals, and Connect evidence refs. These contracts are runtime-neutral. Workspace analyzers build them, bundle services persist/classify them, and CLI/CI/Builder surfaces consume the schema-versioned JSON. Apply/write workflows remain Connect-gated. ## Typed Results `@lssm-tech/lib.contracts-spec/results` is the canonical success/failure surface for operations, workflows, jobs, API adapters, MCP tools, GraphQL resolvers, and React clients. Handlers can keep returning raw output for ordinary `OK` results. Use `contractOk`, `contractAccepted`, `contractQueued`, `contractNoContent`, `contractPartial`, and `contractFail` when an operation needs explicit status, headers, retry metadata, warnings, partial problems, or typed error args. ```ts import { contractAccepted, createContractError, defineResultCatalog, failure, standardErrors, standardSuccess, success, } from "@lssm-tech/lib.contracts-spec/results"; const results = defineResultCatalog({ success: { ...standardSuccess.pick("OK", "CREATED"), QUEUED_FOR_REVIEW: success.queued<{ reviewId: string }>(), }, errors: { ...standardErrors.pick("UNAUTHENTICATED", "FORBIDDEN"), INTENT_NOT_FOUND: failure.notFound<{ intentId: string }>({ description: "The referenced intent does not exist.", gqlCode: "INTENT_NOT_FOUND", }), }, }); ``` `OperationSpecRegistry.executeResult(...)` returns a `ContractResult`. Legacy `execute(...)` remains compatible: it unwraps success data and throws `ContractSpecError` on failure. Custom success and failure codes should be declared in `spec.results` or `io.success`/`io.errors`; undeclared custom failure codes normalize to `INTERNAL_ERROR`. Adapter defaults: - REST/Fetch keeps raw success bodies by default and emits failures as `application/problem+json`; set `resultEnvelope: true` for `{ ok, data }` success envelopes. - Next.js can use the injected `NextResponse.json(...)` helper from the REST runtime. - NestJS support is exposed as duck-typed exception filter/interceptor helpers without adding `@nestjs/common` as a hard dependency. - GraphQL keeps field success payloads unchanged by default; enable `resultExtensions` to collect success metadata, while failures use `extensions.contractspec.problem`. - MCP tools return normal content for success and `isError: true` with a safe problem payload for failures. - React runtime helpers normalize REST, GraphQL, MCP, workflow, job, and legacy error shapes into a `ContractResult`. Migration note: prefer `ContractSpecError`, `createContractError`, and `contractFail` over `@lssm-tech/lib.error/AppError`. `@lssm-tech/lib.error` is kept as a compatibility bridge. ## Experimental graph artifact contracts The generative-core graph artifact surface is exported through narrow experimental subpaths only; it is not re-exported from the root barrel. Use these versioned contracts for graph, generation-plan, and drift-report DTOs while the analyzer and orchestration layers evolve: - `@lssm-tech/lib.contracts-spec/graph-artifacts` - `@lssm-tech/lib.contracts-spec/graph-artifacts/contracts` - `@lssm-tech/lib.contracts-spec/graph-artifacts/codebase` - `@lssm-tech/lib.contracts-spec/graph-artifacts/links` - `@lssm-tech/lib.contracts-spec/graph-artifacts/generation` - `@lssm-tech/lib.contracts-spec/graph-artifacts/drift` These schemas are additive and versioned with `contractspec.graph-artifacts.v1` / `1.0.0`; consumers should persist the schema and artifact versions with every generated artifact. ## Validation And Authoring Entry Points Recent authoring and setup flows use package-level validation APIs directly instead of relying on ad hoc template or registry assumptions. ### Multi-design contracts `@lssm-tech/lib.contracts-spec/design-packs` exports the additive, serializable contract surface for versioned design packs, app and tenant selection policy, private drafts, immutable publications, certification receipts, and structured safe patches. `resolveDesignSelection()` is a pure resolver with deterministic fixed, private-user, tenant, app, declared-fallback, and ContractSpec Editorial precedence. Tenant policy can narrow an app catalog or custom-design permission, but cannot widen either boundary. Existing `ThemeSpec` and `ContractSpecEditorialTheme` exports remain the theme/token source of truth. - `@lssm-tech/lib.contracts-spec/app-config/validation` - `validateBlueprint` - `validateTenantConfig` - `validateResolvedConfig` - `assertBlueprintValid` - `assertTenantConfigValid` - `assertResolvedConfigValid` - `@lssm-tech/lib.contracts-spec/features/validation` - `validateFeatureSpec` - `assertFeatureSpecValid` - `validateFeatureTargetsV2` - `@lssm-tech/lib.contracts-spec/themes.validation` - `validateThemeSpec` - `assertThemeSpecValid` These entrypoints are the current public surface for workspace setup, CLI scaffolding, CI, and docs to verify `app-config`, `feature`, and `theme` authoring consistently. ## Translation contracts and runtime i18n `@lssm-tech/lib.contracts-spec/translations` is the canonical translation contract surface. Keep stable bundle identity in `TranslationSpec.meta.key`, keep locale variants in `TranslationSpec.locale`, and use optional metadata such as `defaultLocale`, `supportedLocales`, `fallbacks`, `direction`, `formatter`, `channels`, `audience`, `modality`, `safety`, and `rendering` to describe runtime behavior without making a UI framework canonical. Managed CompanyOS catalogs can declare those metadata blocks at bundle or message granularity so UI IA, CommunicationOS, workflows, LLM prompts, voice scripts, agent responses, redaction, and degraded-copy paths remain contract-authored. Production translation resolution lives in `@lssm-tech/lib.translation-runtime`. That package consumes `TranslationSpec[]` and provides locale negotiation, BCP 47 canonicalization, fallback chains, override layers, diagnostics, async catalog loading, compiled-message caching, and SSR snapshot serialization. Its default formatter is backed by FormatJS/`intl-messageformat` behind a small `MessageFormatter` abstraction so ContractSpec does not implement a custom ICU parser and can adopt MessageFormat 2 later. ```ts import { defineTranslation } from "@lssm-tech/lib.contracts-spec/translations"; import { createIntlMessageFormatter } from "@lssm-tech/lib.translation-runtime"; const messages = defineTranslation({ meta: { key: "commerce.cart.messages", version: "1.0.0", domain: "commerce", owners: ["platform"], }, locale: "en-US", defaultLocale: "en-US", supportedLocales: ["en-US", "ar-EG", "zh-Hans"], channels: ["ui", "agent"], audience: { roles: ["operator"], tiers: ["managed"] }, modality: { primary: "text", supported: ["voice"] }, safety: { classification: "internal", containsSensitiveData: true, redaction: "mask", degradedFallbackKey: "cart.items.degraded", }, rendering: { surface: "web", target: "cart.summary", richText: "plain" }, messages: { "cart.items": { value: "{count, plural, =0 {No items} one {One item} other {{count} items}}", placeholders: [{ name: "count", type: "plural" }], channels: ["ui"], rendering: { target: "cart.summary.count" }, }, "cart.items.degraded": { value: "Cart summary unavailable.", safety: { classification: "public", redaction: "none" }, }, }, }); const formatter = createIntlMessageFormatter(); const cartItems = formatter.compile({ id: "cart.items", locale: messages.locale, message: messages.messages["cart.items"].value, }); cartItems.format({ count: 3 }); // "3 items" ``` ### Static translation diagnostics Static catalog diagnostics are exported from `@lssm-tech/lib.contracts-spec/translations/diagnostics` for CI tools and downstream consumers that need reusable checks without depending on the CLI shell. ```ts import { analyzeTranslationCatalogGroups } from "@lssm-tech/lib.contracts-spec/translations/diagnostics"; const report = analyzeTranslationCatalogGroups([ { packagePath: "packages/platform/example", catalogDir: "src/i18n/catalogs", catalogs: [enMessages, frMessages, esMessages], baseLocale: "en", expectedLocales: ["en", "fr", "es"], }, ]); if (!report.ok) { console.error(report.issues); } ``` `catalogDir` is relative to `packagePath`: issue paths join the two, so a root-relative `catalogDir` would repeat the package path. The report shape is intentionally CI-friendly: `{ ok, summary, issues }`. Issue codes include missing catalogs/keys, extra keys, blank values, invalid ICU messages, placeholder non-parity, invalid shapes, locale non-parity, duplicate bundle identities, `unsupported_locale_claim` (a catalog's `supportedLocales` declares a locale with no matching catalog in the group), and `manifest_spec_key_missing` (a manifest route entry references a specKey absent from the registered catalog set). Use `validateManifestCatalogDrift(entries, knownSpecKeys)` with a `ManifestRouteEntry[]` list to surface drift between route shard manifests and the registered catalog. The `contractspec i18n check` command is the CLI wrapper around this API, and `.contractsrc.json` can include an optional top-level `i18n` diagnostics block with `catalogGlob`, `baseLocale`, `locales`, `allowExtraKeys`, `checkPlaceholders`, `checkIcu`, and `strict`. ### Migration notes - Prefer `meta.key: "bundle.messages"` plus `locale: "fr-FR"` over keys like `bundle.messages.fr-FR`. - Use `channels`, `audience`, `modality`, `safety`, and `rendering` metadata for Managed CompanyOS copy selection and policy-aware rendering; keep values descriptive and non-empty so validation can catch unsafe catalog gaps. - `createI18nFactory` supports SSR snapshot/hydration directly via `.snapshot()` / `.hydrationPayload()` on the factory instance and `createI18nFactoryFromHydrationPayload(payload)` for client rehydration. - `resolveLocaleWithin(supportedLocales, defaultLocale, runtimeLocale?, optionsLocale?)` is exported for callers that resolve locale outside a factory instance. - `RouteShardManifest` and `defineRouteShardManifest` live in the bundle/app layer (not `contracts-spec`) — the contract layer stays route-agnostic. Use `validateManifestCatalogDrift` to catch drift between manifests and registered catalogs. - i18next adapter support lives downstream at `@lssm-tech/lib.translation-runtime/i18next`. It projects ContractSpec specs/snapshots to i18next resources and metadata manifests, but ContractSpec specs remain canonical. - Do not encode locale in i18next namespaces or stable translation keys. Use `TranslationSpec.locale` for the language and `TranslationSpec.meta.key` (or an explicit namespace strategy) for the namespace. - ICU messages are exported intact for i18next. Configure an ICU-capable i18next format plugin when using i18next to render ContractSpec ICU plural/select/selectordinal messages. - For SSR, use the factory-stack snapshot/hydration surface (`createI18nFactory` → `.hydrationPayload()` → `createI18nFactoryFromHydrationPayload`). - For React Native, the core runtime uses no DOM APIs; hosts are responsible for locale detection and any required `Intl` polyfills. - **Optimization wave (Model A — per-request inline payload):** O2+O3 reduce the per-request inline `