---
fragment_peers:
  access-and-processing: acesso-e-processamento
  contracts-by-capability: contratos-por-capacidade
  edition-and-signature-commitment: edicao-e-compromisso-da-assinatura
  existing-components: componentes-existentes
  from-technical-capability-to-coordination: da-capacidade-tecnica-a-coordenacao
  implementation-contracts: contratos-de-implementacao
  native-events-and-tools: eventos-nativos-e-ferramentas
  verification-scopes: escopos-da-verificacao
  when-search-or-interchange-encounters-a-problem: quando-a-busca-ou-o-intercambio-encontra-um-problema
lang: en
peer: pt/implementation/
shared_fragments: false
title: Implementation contracts
---

# Implementation contracts

For a contribution to remain understandable when it moves between tools,
implementations share contracts for format, identification and verification.
Storage, search and preparation can be handled by different components,
provided they preserve origin and the distinction between drafts and signed
declarations.

This page explains reference component contracts and limits.
To choose what to use, consult [Code and configurations](implementations.md);
to run them, follow [local setup](configurations.md).
[First use through files](first-draft.md) requires no programming.

## From technical capability to coordination

Design the integration so one person can continue another's work.
Finding a file, understanding a criterion and returning a response are different
operations. Automation can help select files or recover prior work while
preserving authorship, evidence and permissions.

Preservation keeps the record available; transport takes it to another
environment; search locates it in accessible sources. Interpretation assesses
its relevance to the reader. Structural validation and signature verification
do not replace these operations.

The current MCP offers local text search; an integration adding contextual
reading needs to identify sources, model, costs and permissions. That
combination can help both find contributions for a piece of work and
recognize occasions to contribute to someone else's, without requiring
a common provider.

## Contracts by capability

- **Drafts:** use Legible Draft with Genealogy 0.1 fields and the
  [exchange profile](drafts.md). Preserve origin, bytes and explicit selection.
- **Formal records:** follow the [specification](specification.md).
  Reuse the core and check structure and cryptography with the distributed vectors.
- **Optional contact:** use the [author-contact profile](downloads/author-contact.md).
  It is a signed auxiliary file, private until the choice to share it.
- **Agents:** follow the [preparation instructions](agents.md).
  Assistance does not give the agent authority to sign or publish for a person.

Test criteria and execution reports fit within existing descriptions and
evidence. There is no test primitive or mandatory axiology, judgment, agency
or execution field. These dimensions explain work; they neither classify
people nor assign tasks.

## Existing components

| Component | Function | Limit |
|---|---|---|
| Rust core and CLI | JCS, IDs, structural validation, SSHSIG and graph queries | Verification does not establish truth |
| Python library | Local operations using the Rust CLI | Signing and provider processing need defined authorization and key custody |
| MCP | Search, import, selected local export and unsigned preparation over stdio; restricted HTTP catalogue in the pilot | Per-participant scope; no signing, embedded model or OAuth |
| Agent Skill | Guidance for preparation, reading and human formalization | The package grants no tool permissions |
| Legible Draft | Unsigned Markdown/YAML interchange, Genealogy 0.1 convention | Importing keeps the content as a draft |
| Local app | Proof of concept for trying the workflow | Not yet a production mobile client |

In MCP, `import_draft_packet` and `search_drafts` use the Python library.
`save_draft`, `read_draft` and `prepare_from_draft` work with Legible Draft.
Formal preparation receives reviewed content and references the draft bytes;
the draft remains informal. `prepare_appoint` operates on provisional-tree
candidates, while `draft` uses a fixed stub for that tree.
`export_draft_packet` reuses the library to export a selected version into
`exports/drafts/<package>/` under the private root, without sending or overwriting.
This is a stdio MCP operation, not part of the restricted
[local pilot](pilot.md) catalogue. No MCP tool signs.

The CLI verifies and updates one contact profile per `did:key`, with a stable
filename and increasing revision. Python and MCP reuse that contract.
MCP neither signs nor publishes contacts. To appear on the site, the exact
profile version must be selected by maintainers after review of the relevant
permission. The local file and editorial confirmation stay outside Git by
default. Removal also requires checking copies distributed by the project;
third-party copies may remain.

Adapters reuse the core to avoid divergent rules.
The independent test checks Python/ECMAScript canonicalization and OpenSSH
signature verification. These tests have a defined scope; compatibility
with an external client needs to be tested in that client.

## Verification scopes

`validate` checks structure. `verify` checks the hash and baseline signature.
Relationships, external evidence, time witnesses and host policies require
their own checks. A correct hash does not make an unknown schema conform
to the protocol.

Dependency relationships can contain cycles. Safe traversal marks visited
nodes; algorithms requiring an acyclic graph need to define the projection
on which they operate. Lifecycle chains retain their specific author,
target-type and cycle requirements.

Baseline signing uses plain `ssh-ed25519`. It does not cover `ed25519-sk`
or certificates. `did:key` identifies a key without native rotation or
deactivation. Persistent recovery through `did:legible` is an experimental
profile outside the baseline.

For record search, discovery or presentation, also consult the
[guide for indexers](downloads/indexing-and-responsibility.md), distributed
in English in the technical repository. It distinguishes the signatory's
statement, checks performed and the service's interpretations, alongside the
separate conditions for publication and processing. NCO accompanies the meaning
of the signature; it does not grant general indexing authorization.

## Access and processing

Define participant identity, login, file access, provider processing, signing
and sharing separately. The session owner is not necessarily the author.
External providers can be used when authorizations and policies permit;
an organization may require internal processing.

Treat records and evidence as data, not instructions to execute tools.
Keep CH private and out of public exports, and check each piece of evidence's
own permissions. Baseline record verification does not need to fetch referenced
content automatically.

[Conformance artifacts](downloads/vectors.json) ·
[Code in the protocol repository](https://github.com/LegibleProtocol/protocolDev/tree/main/reference) ·
[Genealogy and recognition](records.md)


## Native events and tools

When mapping chat events to drafts, an adapter needs to identify the mapping
version, preserve origin and document the information it cannot transport.
The event's native signature remains distinct from a Legible signature.

The Python library imports original bytes, searches fields and text,
and exports a selected draft with its transport manifest.
These operations need no hosted model and leave private CH out of exports.
Stdio MCP provides import, local search and `export_draft_packet` to prepare
a selected packet under the private root. Exporting does not send it;
importing does not produce a signed declaration. The network pilot MCP
retains its restricted catalogue.

In the reference, `.ch/genealogy/` is a private cache, not the directory to
publish. A selected export contains Markdown and its `manifest.json`; only
that reviewed packet enters the shared collection. The [creation guide](configurations.md)
shows this transition and an example Git policy. For MCP, configure an explicit
stable origin per collection/participant, not derived solely from a name.
Importing or resending preserves the received origin.

The Rust reader can recover from some small errors: unquoted descriptive text
containing `: `, as well as files with BOM/CRLF. It preserves original bytes
and reports notices. If the structure requires guessing meaning, reading fails
so the author can review it. Signed records use the strict parser.
Attaching the guide to a chat does not install or run this reader.

## When search or interchange encounters a problem

MCP search returns `complete` and `issues` alongside drafts. When an entry is
corrupt or unreadable, healthy ones remain available with a partial-result
warning identifying the affected file. This does not mean the contribution
ceased to exist. Nothing is automatically deleted, moved or repaired. Reading
and exporting an exact version check that file without depending on the
integrity of other entries.

An editor can change LF line endings to CRLF without changing the text as
read, although the bytes and their hash change. When the stored original
is available, the reference identifies this difference without normalizing
or replacing files; to resend, use the exported original with its manifest,
preserving the corresponding hash. A formatting-only change is not, by
itself, another cognitive contribution.

Draft origins and authors remain unauthenticated declarations. Checking the hash
protects byte integrity, not proof of who formulated the content. Review before
sharing: restricted text copied into the draft itself travels with its export;
there is no automatic removal of sensitive data.

## Edition and signature commitment

The current edition uses `legible/protocol/v2/...` schemas, with canonical
Portuguese NCO and NRC texts and English reference translations. Select NCO by
the signed schema, never by date. An unknown edition receives no other edition’s
NCO by approximation. Changing a record’s schema requires a new core, ID and
signature; preserve the original.