Interfaces, payload contracts, and Quarry

Capstone writes documentation inside each source repository. Quarry imports committed references into a shared Git repository and a local index. The useful handoff is back into development: Capstone reads other services' documented expectations through Quarry, writes those constraints into a feature spec and its tasks, implements the approved change, and refreshes the source reference. A later Quarry import makes that new reference available to the next change.

What belongs in interfaces#

09-interfaces.md describes communication with sibling codebases: produced APIs, queue messages, events, shared schemas, and consumed sibling services. Internal calls stay in architecture/data-flow; third-party vendors such as payment or object-storage providers belong in 05-dependencies.md. A standalone project whose only external communication is with vendors normally has no interfaces chapter.

The chapter's canonical declaration is the frontmatter edges: block. Example, omitting ordinary stamp fields for brevity:

known_as: [ingest.internal]
edges:
  produces:
    - kind: sqs
      name: file-ingest
      site: src/publish.rs
      schema: FileIngestMessage
  consumes:
    - kind: http
      name: GET /users/{id}
      site: src/auth.rs
      schema: UserRef
      from: identity-api

This is an illustrative declaration, not real product output. The from value represents a previously confirmed decision.

Map derives kind/name/site/schema from code and preserves existing confirmed far ends while the same (direction, kind, name) row still exists. It removes and reports rows the code no longer contains. A rename can therefore be a removed old row plus a new row; previous far-end answers do not automatically transfer to a different name.

Produces and Consumes tables render the block for humans. Their columns are Kind | Name | To | Site and Kind | Name | From | Site. interfaces_frontmatter: true adds older top-level produces/consumes lists; it is unnecessary for current Quarry's canonical block support.

Payload sections must contain usable fields#

Each contract has a ### <Name> section under its direction. Named payloads point to an entity in the same repository's models chapter:

### file-ingest

Model: FileIngestMessage

The models chapter must then have ### FileIngestMessage under Fields and types with a Field | Type | Required table. Alternatively, an ad-hoc payload is inline:

### file-ingest

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| file_id | string | yes | UUID |
| content_type | enum | yes | accepted: application/json, application/xml |

A producer documents what it emits from its serializer/type. A consumer documents the fields it actually reads or the local type it deserializes into. For a subset of a larger object, an inline consumed-field table is more accurate than copying every field from a broad model. Do not replace these with a link to a schema file in another repository: the comparison needs fields locally.

Names are keys: contract headings use the row's Name verbatim, without backticks; a version suffix such as (v2) is supported. A missing payload section, an empty one, or a model reference that resolves nowhere prevents a useful comparison. map check reports those schema gaps.

Connect the references#

Install and configure Quarry separately using its source-based installation instructions. Do not assume a prebuilt GitHub Release installer is available: the research check found none. See Quarry's inspected source for the companion tool. In each source repository, first map, review, commit, and merge the reference to its default branch. Then run:

quarry init --url <docs-repo-url>
quarry add

The URL names your shared docs Git repository. This is setup, not an automatic discovery of every repository you can access. After later reference changes reach the source default branch:

quarry update

Before an investigation that needs newer imported docs:

quarry sync
quarry docs deps ingest-api --downstream --depth 2
quarry docs section record-store "file-ingest (v2)"

ingest-api and record-store are illustrative names; substitute registered repos or workspace targets. Query results normally reflect the last-synced reference, not a live read of every source repository.

When Capstone consults Quarry#

These integrations are protocol instructions, not Claude-only hooks. Missing prerequisites skip the relevant lookup. Configuring the CLI remains necessary for useful results; merely installing its executable does not populate a shared index.

Quarry can join undeclared far ends by matching published and consumed (kind, name) rows. Ambiguous matches are presented for your decision. The answer can be a name, several produced-consumer names, unknown, or skip. unknown is a deliberate answer that disables joining for that row; skip leaves it unanswered and eligible to be raised later. A by-name suggestion is only a lead, and a missing section for such a suggestion is not evidence of a broken declared contract.

What contract checks establish#

quarry check compares a producer's working-tree payload documentation with known consumers' last-synced documented fields. Missing produced fields or type changes are breaks; required/optional changes are warnings. Type text is normalized by trimming, case-folding, and collapsing whitespace; this is not a programming-language type assignability check. Model sections with both a table and a Model line use the table and report the ambiguity. Notes such as accepted enum values are useful reading material but are not automatically understood as semantic compatibility constraints. A CSV format absent from Notes is something to bring into a plan, not a guaranteed automated break finding.

Use the checks together: map check helps detect stale/malformed reference; Quarry check compares documented contracts. Neither proves actual network traffic, complete consumer registration, or runtime compatibility. A source change that never reaches the docs can evade a documentation-only compatibility comparison.

Sources: interfaces format and payload rules, groom integration, plan integration, confirmed-edge rules.