Skip to content
ContractSpec
Start here

Area guide · 6 packages · Model one operation and its outcomes

Core contracts and features

Define the behavior, references and composition rules that other parts of a product can share.

What are you trying to do?

  • Where should a command, query or event be declared?
  • Which package owns portable models and which supplies registries?
  • How does a feature connect related contracts?

Why start with these packages

Suggested entry point

@lssm-tech/lib.contracts-spec-core

Begin with portable operation, event, capability and feature definitions when authoring a reusable contract.

Read package manual →

Suggested entry point

@lssm-tech/lib.contracts-spec

Use the compatibility distribution to understand existing consumers and forwarding paths in this source snapshot.

Read package manual →

Suggested entry point

@lssm-tech/lib.contracts-library

Inspect the maintained documentation, review and platform contract families for complete source examples.

Read package manual →

Practical steps

Step 01

Trace one complete operation

Open the definition and record its exact key/version, input and output model, policy and event references. Follow the implementation registration into a runtime package, then the host adapter. This establishes which parts are declarative and which part handles a real request.

Step 02

Extend a feature deliberately

List the operation, event, capability and presentation references that the feature actually needs. Reuse their canonical identities and keep optional dependencies visible. Compare a nearby maintained feature rather than guessing a new reference shape.

Step 03

Check the consumer boundary

Choose the package and subpath available in the intended release, inspect its forwarding relationship, and run the owning project’s existing validation in that environment. Record the result separately from the fact that a source declaration exists.

Choose the layer that matches the job

Portable Core owns operation metadata and the existing defineCommand, defineQuery, defineEvent and defineCapability constructors. It also owns feature composition, versioned references and documentation references. Start here to describe a reusable domain boundary. The compatibility package forwards established paths to canonical owners; it remains useful when reading older consumers. A registry, renderer, provider implementation or installed product capability is a separate part of the composition. The current README describes this ownership extraction as staged, so follow the selected release context when deciding what a consumer can adopt.

Write the contract before the transport

Describe one concrete action or read: its key, version, input, output, error outcomes and declared policy. Identify any emitted event and its relationship to the operation. Put related operations behind a capability, then use a feature to describe the larger composition and its dependencies. Keep documentation close to the definition and reference it explicitly. The source docs.generate operation is a useful complete specimen because its operation, capability requirement and colocated DocBlock can be inspected together.

Preserve identity while navigating the repository

The same contract may be reachable through a canonical leaf and a historical forwarding path. Compare the selected package export maps before creating a second declaration or duplicating a registry. Treat document revision, operation version and package version as separate identifiers. When a contract changes, inspect its callers, event consumers, presentation bindings and examples. A renamed source folder is an ownership change; it should not silently become a new semantic operation or erase an existing versioned reference.

Follow a practical path.

Trace one complete operation

Open the definition and record its exact key/version, input and output model, policy and event references. Follow the implementation registration into a runtime package, then the host adapter. This establishes which parts are declarative and which part handles a real request.

Extend a feature deliberately

List the operation, event, capability and presentation references that the feature actually needs. Reuse their canonical identities and keep optional dependencies visible. Compare a nearby maintained feature rather than guessing a new reference shape.

Check the consumer boundary

Choose the package and subpath available in the intended release, inspect its forwarding relationship, and run the owning project’s existing validation in that environment. Record the result separately from the fact that a source declaration exists.

Packages in this area (6)

6 of 6 shown

  • lib.contractsplatformnode

    Deprecated monolith package split into contracts-spec, contracts-integrations, and contracts-runtime-* packages

    Open manual →
  • lib.contracts-librarySuggested entry pointplatformnode

    Reusable contract library and registry primitives for ContractSpec applications.

    Inspect the maintained documentation, review and platform contract families for complete source examples.

    Open manual →
  • lib.contracts-specSuggested entry pointplatformbun

    Spec definitions and registries for ContractSpec

    Use the compatibility distribution to understand existing consumers and forwarding paths in this source snapshot.

    Open manual →
  • lib.contracts-spec-coreSuggested entry pointfoundationnodebunbrowser

    Portable ContractSpec feature models, ownership, query, result, approval and reference primitives

    Begin with portable operation, event, capability and feature definitions when authoring a reusable contract.

    Open manual →
  • Contract format transformations: import/export between ContractSpec and external formats (OpenAPI, AsyncAPI, etc.)

    Open manual →
  • Versioned, machine-readable ContractSpec package and capability catalog.

    Open manual →