Typed contracts for applications & agents

One product.
Many interfaces.
The same rules.

Define your product’s behavior in TypeScript. Connect it to your API, interfaces and agent tools, with explicit inputs, permissions and approval rules.

Explore the example ↗See how it fits ↓

Start with one operation in the codebase you already own.

BEHAVIOR / 001Explicit by design

{ }report.publishv1.0

INPUTreportIdstring

EFFECTPublish reportwrite

APPROVALRequired before execution↳

RESULTPublication receipttyped

↗Your APIREST adapter

▤Your interfaceBound UI

⌘Your agentMCP tool

[ shared intent ]Your handlers still do the work.

TRY A SHARED RULE

Change the rule.
Watch every interface follow.

One equipment request, three entry points. Adjust the policy and see the app, API and agent reach the same decision.

Interactive illustration · Sample data · Runs locally

Allowed by this demo policy

The local request satisfies the supplied policy.

APP

Equipment request

Studio setup · Sample workspace

€2,400.00

RequesterNo review required

Try the action and inspect the result.

APIJSON

{
  "operation": "request.submit",
  "allowed": true,
  "reviewRequired": false,
  "reviewRecorded": false,
  "role": "requester",
  "amount": 2400,
  "threshold": 5000,
  "reason": "permitted"
}

Illustrative response shape

AGENT

The next permitted step.

Read the same request and actor.
Check the €5,000.00 review threshold and the requester role.
Offer to submit the request.

Follow the tool boundary ↗

Inspect the shared demo definition

{
  "kind": "educational-fixture",
  "operation": "request.submit",
  "reviewFrom": 5000,
  "submitRoles": [
    "requester",
    "reviewer"
  ],
  "approvalIsIndependent": true,
  "interfaces": [
    "app",
    "api",
    "agent"
  ]
}

This is an educational JSON fixture, evaluated by this page. It is not an importable ContractSpec definition.

01 Explicit behavior02 Connected interfaces03 Reviewable effectsUnderstand the boundaries ↗

01 / THE PROBLEMONE OPERATION, SEVERAL ENTRY POINTS

Every new interface
needs to agree
with your product.

A person clicks a button. An integration calls an API. An agent invokes a tool.

When those paths implement the same operation separately, a permission change or new input requirement has several places to go wrong.

ContractSpec gives that behavior an explicit definition, then connects supported adapters and your implementations to it.

WHAT IS A CONTRACT?

A typed description of what an operation accepts, what it returns and the rules it must follow. Your handler implements the work. The configured runtime checks the boundary.

Define the behavior.

Inputs, outputs, policy, effects and ownership live in an inspectable contract.

Connect the interfaces.

Bind your handler and expose the operation through the adapters your application needs.

Inspect what happens.

Make successful calls, denied calls and the required evidence visible at the execution boundary.

Change the entry point. Keep the meaning.Trace the mechanism · 3 ways to look closer

Follow a request to export a report through three interfaces. The useful common ground is the registered operation and its boundary.

Where does this request begin?

A CONCRETE SITUATION

A form helps someone make a valid request.

A person selects a report and gives a reason for the export.

01 / Form

Collect the report and reason, and explain errors in the person’s language.

What changes

Labels, validation messages and the way the result is presented.

What stays explicit

The report, required reason, business implementation and configured execution checks.

FOLLOW THE CONSEQUENCE

The form can make a requirement clear. The server still needs to reject a request that bypasses the form.

CONTINUE WITH THE DETAIL

Expose one operation through API and MCP Contracts, handlers and adapters

Where this explanation comes from

An authored situation, grounded in the linked source guides. Choosing a case explores its expected responsibilities; it does not execute an operation.

Expose one operation through API and MCP Contracts, handlers and adapters

Choose a situation to inspect its explanation.

A person

A CONCRETE SITUATION

A form helps someone make a valid request.

A person selects a report and gives a reason for the export.

Form — Collect the report and reason, and explain errors in the person’s language.
REST binding — Translate the request and construct trusted caller context in the host.
Registered operation — Prepare the call, apply configured checks and invoke the bound handler only when permitted.

What changes

Labels, validation messages and the way the result is presented.

What stays explicit

The report, required reason, business implementation and configured execution checks.

FOLLOW THE CONSEQUENCE

The form can make a requirement clear. The server still needs to reject a request that bypasses the form.

An API client

A CONCRETE SITUATION

A structured request reaches the same business boundary.

A script sends the report identifier and required reason through the API.

HTTP request — Supply the declared input in the adapter’s expected transport shape.
Context factory — Resolve the subject from the host’s authentication boundary.
Handler result — Inspect the canonical result and the adapter’s actual response mapping.

What changes

HTTP payload, status mapping and the client’s error handling.

What stays explicit

The meaning of the operation and the host’s responsibility for identity, policy and dependencies.

FOLLOW THE CONSEQUENCE

Compare the meaningful result and actual effect with the form path. A matching endpoint name does not establish matching behavior.

An agent

A CONCRETE SITUATION

A tool call supplies input; it does not supply authority.

An agent prepares the export tool arguments from the task context.

Tool shape — Expose the operation through the MCP registration supported by the chosen source version.
Tool context — Construct trusted context and adapt request-specific approval evidence.
Shared invocation — Call the registry path; preserve its meaningful failure information in the tool result.

What changes

Tool discovery, input schema and the structured tool result.

What stays explicit

The registered operation, handler and configured approval boundary.

FOLLOW THE CONSEQUENCE

A tool argument saying “administrator” remains input. Trusted identity comes from the host; an agent must understand a denied or approval-required result.

02 / MAKE IT CONCRETEEXPLORE THE BEHAVIOR

Approval belongs
at execution.

The same operation can be reached in several ways.
The approval requirement should still hold.

Interactive illustration · local fixture, not a live runtime trace.

THE DECLARED RULETypeScript excerpt

// Part of an operation definition
execution: {
  effects: ['write'],
  approval: {
    required: true
  }
}

↳

An approval requirement is explicit metadata. Enforcement also needs a configured runtime and approval port.

Approval evidence

HTTP REQUEST · ILLUSTRATIVE

POST /reports/demo-report/publish
Content-Type: application/json

{ "reportId": "demo-report" }

↳

READY TO TRY

What happens without approval?

Attempt the operation, then add a valid fixture receipt and try again.

Handler calls in this attempt —Awaiting attempt

The illustration explains the proposed experience. The inspected REST test asserts denial before handler invocation; this page does not execute ContractSpec packages.

Inspect the source basis ↗

03 / GROW FROM THAT FOUNDATIONADOPT WHAT YOU NEED

A small starting point.
A composable system.

Reuse product behavior while changing the experience. Add adapted interfaces, reusable capabilities and change controls as your product grows.

A / CORE

Model behavior.

Describe operations, data and events with typed contracts. Bind implementations through a runtime built around explicit boundaries.

Contracts + Runtime

B / CHANGE

Make decisions inspectable.

Connect supports scoped decisions and receipts, with durable verification supplied by a configured host. Your host performs the actual merge, deployment or effect.

Connect

C / EXPERIENCE

Adapt the experience.

RoleMorph and presentation contracts support different interfaces for different roles, with authorization kept explicit.

RoleMorph + Surfaces

D / COMPOSITION

Compose capabilities.

Feature Hubs declare their needs and provide reusable functionality. Installation, readiness and starting effects remain distinct steps.

Feature Hubs

One workflow. Two useful views.

Presentation illustration

EDITOR / PREPARE

Quarterly report

Content, supporting sources and the next review step.

Draft readyReview needed →

REVIEWER / ASSESS

Publication review

Changed content, requested effect and approval evidence.

Evidence attachedReview publication →

Shared operation report.publishPresentation changes. Backend authority stays explicit.

Built at LSSM. CompanyOS is an application built on this shared foundation, bringing contracts, operations and interfaces into a business workflow.

A reusable piece comes with a set of relationships.Trace the mechanism · 3 ways to look closer

A communication capability might need an operation, a provider port and a policy binding. Explore what happens when one piece is missing.

What is ready in the composition?

A CONCRETE SITUATION

You can inspect the promise before enabling an effect.

The capability is described, but no active installation or provider has been selected.

01 / Declare

Name the operations, capabilities and required ports.

What changes

The product can discover the capability and its requirements.

What stays explicit

A declaration alone does not send a message or initialize a provider.

FOLLOW THE CONSEQUENCE

Use the dependency map to choose what to bind. Do not treat catalogue presence as runtime readiness.

CONTINUE WITH THE DETAIL

Compose features with explicit dependencies Bind external services deliberately

Where this explanation comes from

An authored situation, grounded in the linked source guides. Choosing a case explores its expected responsibilities; it does not execute an operation.

Compose features with explicit dependencies Bind external services deliberately

Choose a situation to inspect its explanation.

Only the declaration

A CONCRETE SITUATION

You can inspect the promise before enabling an effect.

The capability is described, but no active installation or provider has been selected.

Declare — Name the operations, capabilities and required ports.
Inspect — Identify which requirements your product actually uses.
Prepare — Choose the host configuration and a bounded installation to evaluate.

What changes

The product can discover the capability and its requirements.

What stays explicit

A declaration alone does not send a message or initialize a provider.

FOLLOW THE CONSEQUENCE

Use the dependency map to choose what to bind. Do not treat catalogue presence as runtime readiness.

A fixture is bound

A CONCRETE SITUATION

The product behavior becomes testable without external effects.

The selected composition uses a deterministic fixture port.

Install — Activate the selected capability in the test host.
Check — Verify operation, port, actor capability and policy requirements.
Observe — Record the fixture callback and denial paths within this environment.

What changes

You can exercise the declared effect gate and inspect the fixture result.

What stays explicit

The fixture does not establish provider delivery, remote quotas or live retry semantics.

FOLLOW THE CONSEQUENCE

Keep the fixture label attached to the result. Qualify the provider separately when an external effect becomes part of the intended use.

A provider is chosen

A CONCRETE SITUATION

The boundary now includes an operating dependency.

A concrete provider supplies the required port for an intended environment.

Bind — Supply the provider behind the host-owned port.
Fulfill — Satisfy policy obligations before the effect callback runs.
Qualify — Exercise the supported provider path and record its actual scope.

What changes

Credentials, provider behavior, failure modes and operational ownership matter.

What stays explicit

The composition must still satisfy its declared requirements and policy obligations.

FOLLOW THE CONSEQUENCE

Check the behavior the application depends on, including unavailable service, duplicate requests and recovery. Matching a method signature is only a starting point.

04 / YOUR FIRST USEFUL RESULTIN YOUR EXISTING CODEBASE

Bring one operation.
Keep your application.

Start where several interfaces already need to agree.

Choose a bounded action with clear inputs, one handler and a failure you want to catch. Add a contract, connect two entry points and test the failure directly.

01
Choose the boundary
A real operation with a repeated rule.
02
Bind the implementation
Your existing business logic stays yours.
03
Demonstrate the rule
Verify both success and a denied path.

Explore the documentation ↗Check availability ↓Check the supported package versions before you start.

Choose an evaluation that can teach you something.Explore a situation · 3 ways to look closer

Keep the existing application. Make one operation explicit, then decide what the next useful proof would be.

Which situation sounds closest?

A CONCRETE SITUATION

Start with behavior you can compare.

An existing account lookup already returns a useful result to an API consumer.

What changes

The operation gains an explicit input, result, errors and ownership boundary.

What stays explicit

Its business implementation can remain in place.

FOLLOW THE CONSEQUENCE

Compare the current route with the new binding using the same valid and invalid cases. Widen the scope only after the difference is understood.

CONTINUE WITH THE DETAIL

Follow the first operation Adopt ContractSpec in an existing codebase Test the promise at the boundary

Where this explanation comes from

An authored situation, grounded in the linked source guides. Choosing a case explores its expected responsibilities; it does not execute an operation.

Adopt ContractSpec in an existing codebase Test the promise at the boundary

Choose a situation to inspect its explanation.

The API already works

A CONCRETE SITUATION

Start with behavior you can compare.

An existing account lookup already returns a useful result to an API consumer.

What changes

The operation gains an explicit input, result, errors and ownership boundary.

What stays explicit

Its business implementation can remain in place.

FOLLOW THE CONSEQUENCE

Compare the current route with the new binding using the same valid and invalid cases. Widen the scope only after the difference is understood.

An agent needs access

A CONCRETE SITUATION

A second entry point makes consistency observable.

An operation already used by the application needs a tool interface.

What changes

Tool discovery and transport handling are added around the registered behavior.

What stays explicit

The host still supplies identity, validation, policy and provider dependencies.

FOLLOW THE CONSEQUENCE

Exercise the actual API and MCP bindings. Compare meaningful error codes and effect counts rather than expecting identical wire payloads.

A rule is duplicated

A CONCRETE SITUATION

Make the invariant the center of the evaluation.

A required reason or approval rule is repeated across several interfaces.

What changes

The shared declaration makes the intended obligation visible to each consumer.

What stays explicit

Business logic and trusted runtime enforcement must still be implemented and tested.

FOLLOW THE CONSEQUENCE

Choose one denied request that would expose a bypass. Show that it cannot enter the handler through either selected entry point.

05 / KNOW WHAT YOU ARE ADOPTINGEXPLICIT BOUNDARIES, TOO

Understand the promise.
Inspect the limits.

What do I still implement?+

Your business logic, host authentication, infrastructure and provider integrations. Contracts describe behavior; adapters and configured runtime ports connect that description to execution.

Does declaring a policy enforce it?+

Enforcement requires the appropriate runtime path and configuration. In the inspected operation model, approval is explicitly enabled through execution metadata. Descriptive tags alone do not protect an operation.

Does ContractSpec regenerate and deploy everything?+

No. Supported artifact generation exists. The inspected integration CLI still restricts generation apply to a dry run. Review, merge, deployment and real effects remain separate responsibilities.

Do I need CompanyOS or Studio?+

The developer foundation has its own adoption path. Packaged applications are separate products built on top; they are not a prerequisite for using the foundation.

Find the point where the handler can begin.Trace the mechanism · 3 ways to look closer

Take an operation that explicitly requires approval. Change one condition and inspect the expected path from the captured runtime guide.

Which request are you inspecting?

A CONCRETE SITUATION

Input preparation stops the path early.

The request omits an input required by the operation schema.

01 / INPUT

Parse and validate the request against the declared schema.

What changes

The request cannot become a valid prepared input.

What stays explicit

No visible button or descriptive tag makes the missing value valid.

FOLLOW THE CONSEQUENCE

A denial test for approval should use otherwise valid input, so it actually reaches the approval boundary.

CONTINUE WITH THE DETAIL

What the runtime checks Authentication, policy and scoped approval Test the promise at the boundary

Where this explanation comes from

An authored situation, grounded in the linked source guides. Choosing a case explores its expected responsibilities; it does not execute an operation.

What the runtime checks Authentication, policy and scoped approval Test the promise at the boundary

Choose a situation to inspect its explanation.

Required input is missing

A CONCRETE SITUATION

Input preparation stops the path early.

The request omits an input required by the operation schema.

Input — Parse and validate the request against the declared schema.
Stop — The malformed request fails before the intended handler entry.
Recover — Explain the missing input; then retry through the same trusted boundary.

What changes

The request cannot become a valid prepared input.

What stays explicit

No visible button or descriptive tag makes the missing value valid.

FOLLOW THE CONSEQUENCE

A denial test for approval should use otherwise valid input, so it actually reaches the approval boundary.

Approval evidence is absent

A CONCRETE SITUATION

An explicit approval requirement blocks handler entry.

The input is valid, the fixture subject is known, and the receipt is omitted.

Prepare — Use valid input and a trusted fixture identity.
Require — Apply the operation’s explicit execution.approval requirement.
Observe denial — Inspect the adapter’s failure and verify the disposable effect remains untouched in your test.

What changes

The shared preparation path reports APPROVAL_REQUIRED with missing_receipt at the inspected snapshot.

What stays explicit

The handler should not have produced an effect.

FOLLOW THE CONSEQUENCE

Use a disposable counter or fake outbox through the real adapter to observe the denied path. This illustration is not that test run.

The returned result is invalid

A CONCRETE SITUATION

A late check cannot promise to undo an earlier effect.

The handler returns a value that fails output validation.

Invoke — The handler carries out the bound business work.
Validate output — Check the returned value against the declared result shape.
Recover deliberately — Use the application’s persistence and retry design; output rejection is not automatic rollback.

What changes

The final operation result reports the invalid output.

What stays explicit

A database change or provider request may already have occurred inside the handler.

FOLLOW THE CONSEQUENCE

If the effect and its record must be atomic, the host needs an appropriate transaction, outbox or recovery design.

06 / SOURCE & AVAILABILITYOBSERVED 27 OCTOBER 2026

The example has
a source basis.

The concept is grounded in inspected repository code. It is a design review, not a fresh runtime verification or a claim of production qualification.

Approval fixture at inspected release ↗

The repository link currently requires access.

Availability matters.

Observed

Several packages have public npm metadata. That metadata and the current source tree describe different dependency layouts.

To verify

A clean, anonymous installation of the exact starter and versions advertised on the new site.

This concept

A local illustration of an approval boundary. No provider calls, backend execution or production data.

WATCH THE IDEA TAKE SHAPE

From intent to an experience
you can make your own.

A short illustrated walkthrough of shared meaning, AI-assisted creation and reusable execution.

Then try it yourself ↗

Read the walkthrough

Intent. Start with a goal. ContractSpec gives the pieces shared meaning, data, behavior and policy.

Create and run. AI can help generate source or compose supported interfaces. Reusable components and ordinary runtimes execute defined work.

Adapt. The same work can be presented differently for a desktop workspace, a mobile view or an agent, with the applicable action boundaries.

Compose. Bring domain capabilities together around the outcome: communication, billing, growth, building and more.

Download the full transcript ↓

START WITH A RULE THAT MATTERS

Give your next interface
something explicit to follow.

Explore the example ↗Discuss your operation ↗

One product.Many interfaces.The same rules.

Set the request.

Shape the policy.

Equipment request

The next permitted step.

Every new interfaceneeds to agreewith your product.

Define the behavior.

Connect the interfaces.

Inspect what happens.

A form helps someone make a valid request.

Approval belongsat execution.

What happens without approval?

A small starting point.A composable system.

Model behavior.

Make decisions inspectable.

Adapt the experience.

Compose capabilities.

One workflow. Two useful views.

Quarterly report

Publication review

You can inspect the promise before enabling an effect.

Bring one operation.Keep your application.

Start with behavior you can compare.

Understand the promise.Inspect the limits.

Input preparation stops the path early.

The example hasa source basis.

Availability matters.

From intent to an experienceyou can make your own.

Give your next interfacesomething explicit to follow.

One product.
Many interfaces.
The same rules.

Every new interface
needs to agree
with your product.

Approval belongs
at execution.

A small starting point.
A composable system.

Bring one operation.
Keep your application.

Understand the promise.
Inspect the limits.

The example has
a source basis.

From intent to an experience
you can make your own.

Give your next interface
something explicit to follow.