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; to run them, follow local setup. First use through files 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. Preserve origin, bytes and explicit selection.
- Formal records: follow the specification. Reuse the core and check structure and cryptography with the distributed vectors.
- Optional contact: use the author-contact profile. It is a signed auxiliary file, private until the choice to share it.
- Agents: follow the preparation instructions. 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 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, 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 · Code in the protocol repository · Genealogy and recognition
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
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.