# OpsRegistry: complete agent context

OpsRegistry is an open, application-neutral operation language for business, software and equipment. It separates action semantics from provider APIs, credentials, identifiers and transport details.

## Core model

An **operation** answers: "What needs to happen?" Its code describes the meaning of an action, for example `logistics.shipment.quote`, `finance.merchantPayment.create` or `it.identity.authenticate`.

A **contract** defines normalized operation input and output. The `@opsregistry/contracts` package publishes Zod schemas and TypeScript types. Contracts must remain provider-neutral.

A **provider** identifies an organization, service or system that can perform operations.

A **capability** declares that a provider supports an operation. Authentication mode and provider limitations belong to the capability and adapter, not to the universal operation.

An **adapter** maps a universal contract to a provider API. It handles provider authentication, field names, local identifiers, errors and response normalization. Runtime adapters are separate versioned packages, commonly named `@opsregistry/adapter-<provider>`.

An operation can have alternative **direct and composite implementations**. Direct implementations
use an API, SDK, device or internal function. Composite implementations call other operations;
those operations may themselves be decomposed further. Decomposition belongs to a particular
implementation, not a mandatory child tree within Operation. Higher-level operations are valid
when they have independent meaning and a verifiable contract. Do not require every provider
to expose its internals or standardize all primitives in advance.

**Composition** describes this implementation approach, not a mandatory new registry entity.
A **scenario** is a reusable user process template using the same composition mechanism,
not a second kind of callable action. Not every template becomes a canonical operation.
A **run** is a concrete execution; its state, credentials, permissions, budget and approvals
belong to an application, Bridge or another runtime, independently of VARM.

## Naming rules

- Every executable operation uses `domain.resource.action`; deeper resource nesting is allowed.
- Every segment uses English lowerCamelCase and the final segment is an action verb.
- Describe universal action semantics, not a provider API method.
- Do not include provider, application or product names in `operationCode` unless they change the actual meaning of the action.
- Add a new operation when lifecycle, parties, legal meaning, authorization model or status semantics materially change.
- Use parameters, tags or capabilities when only provider, technology, material, tariff or execution method changes.
- Two-segment labels such as `manufacturing.cutting` or `rental.vehicle` are catalog categories, not executable operations.

## Localization

English text in `title`, `summary`, `description`, `requestDescription` and `responseDescription` is canonical. Localized text is stored alongside it in `translations` using BCP 47 language tags, for example `translations.ru`.

Operation codes, versions, statuses and tags are not translated. Clients should select the requested translation and fall back to canonical English when a field or locale is unavailable.

Correct examples:

- `logistics.shipment.quote`
- `finance.merchantPayment.create`
- `finance.fiscalReceipt.createClosing`
- `it.access.authorize`
- `inventory.stock.reserve`
- `storage.object.uploadFile`
- `manufacturing.workpiece.cut`

Incorrect examples:

- `finance.tbank.init`
- `logistics.cdek.calculate`
- `varm.user.login`
- `manufacturing.cutting`
- `rental.vehicle`

## Current domains

Read `/data/domains.json` and operation statuses for the actual snapshot. Catalog entries
may be draft; an entry alone does not prove a published npm contract or executable adapter.
`cad` describes draft sketch creation, batched entities and constraints, extrusion,
revolution, booleans, fillets and chamfers. CAD execution support is not yet declared.

- `logistics`: shipment quote, create, list, tracking and pickup.
- `finance`: merchant payments, QR payments and fiscal receipts.
- `accounting`: journal entries, accounting periods, reconciliation and reports.
- `workforce`: employment, assignments, shifts, time, leave and payroll calculation.
- `inventory`: physical stock availability, receipt, issue, reservation, transfer and adjustment.
- `manufacturing`: workpiece cutting, bending and welding; product assembly, inspection and packaging.
- `it`: authentication, token lifecycle, authorization and policy evaluation.
- `storage`: S3-compatible object and static website operations.
- `commerce`: commercial offers and orders.
- `documents`: document exchange and recognition.
- `trust`: signing environments, devices, certificates and digital signatures.

Finance, accounting and workforce are separate domains. Workforce calculates earnings, accounting
records the economic event, and finance performs or tracks the actual movement of money. A user
identity belongs to IT; an employment relationship belongs to workforce.

Inventory, logistics and storage are separate domains. Inventory owns physical stock and warehouse
movements, logistics owns transportation and carrier shipments, and storage owns files and
S3-compatible objects. A cross-domain workflow may link their execution records without merging
their state.

## Recommended agent workflow

1. Read `/registry.json` to identify the current snapshot and dataset URLs.
2. Read `/data/domains.json` for domain meaning, then search `/data/operations.json` by code, tags, title or summary.
3. Inspect the matching contract in `@opsregistry/contracts` or its source repository.
4. Search capabilities for providers supporting the operation.
5. Inspect adapter metadata and the provider adapter README.
6. Confirm authentication mode and provider-specific limitations before execution.
7. Validate inputs with the operation contract before calling an adapter.

## Example

For a delivery quote, use `logistics.shipment.quote`. The application supplies normalized origin, destination, delivery mode and packages. A carrier adapter may resolve city names to provider IDs, authenticate when required and return normalized options containing provider code, service code, price, currency and delivery estimates.

The application should not perform provider city lookup or reproduce provider authentication logic when the adapter already owns those concerns.

## Runtime and state

A composite implementation may start as ordinary adapter code. A shared declarative format,
dependency resolver and composition execution API are not implemented. A separate mandatory
Scenario schema or DSL is not required. Do not invent tools for these planned facilities.
Verified compositions should execute programmatically without an LLM decision at every step.

Every implementation must satisfy the original operation contract, including error and effect
guarantees. Step-level rollback does not prove whole-operation atomicity. If all-or-nothing is
required, a composite implementation must provide it for the entire chain. Otherwise it must
not claim support for that contract. Partial completion is valid only when the contract allows it.
Semantic unity does not imply a universal transaction across systems.

Capability declarations do not yet provide structured contract-version and mode
compatibility for automatic composition preflight. Primitive operation codes alone do not
prove derived support: verify the chosen implementation, versions, constraints, object references,
shared CAD session and guarantees. Nested implementation resolution must reject cycles and bound
depth, total steps, time and cost. Public source does not imply trust or execution permission.
The existing native/adapter executionMode describes connection mode, not decomposition depth.
MCP annotations are hints, not authorization or proof of retry safety. A timeout after
a write may mean an unknown outcome; do not automatically retry or switch providers.
CAD geometry support does not prove support for editable parametric history.

The registry does not store individual orders, payments or shipment state. Business applications own execution records and runtime status. Those records may reference an `operationCode` and `providerCode` while keeping application-specific workflow data locally.

## Sources of truth

- Registry definitions: https://gitflic.ru/project/opsregistry/registry
- Contract schemas: https://gitflic.ru/project/opsregistry/contracts
- Published contracts: https://www.npmjs.com/package/@opsregistry/contracts
- Website manifest: https://opsregistry.org/registry.json

## Interface status

Static JSON datasets and npm contracts are available. A public MCP endpoint is planned but must not be assumed operational until it is explicitly marked as available in `/registry.json` and the agent guide.