# org.cairnsproto.draft.defs

> Shared definitions for Cairns records. Every Cairns record is dedicated to the public domain under CC0-1.0; placing a record asserts the right to dedicate it. Fractions are integers in parts per million (0 to 1000000) so every indexer computes identical results.

- Kind: defs
- Authority: draft.cairnsproto.org
- Lexicon: 1
- Published by [cairnsproto.org](https://lexicon.garden/identity/did:plc:np7ezqujtsry4bkogisaabul), the NSID's authority

## Links

- [Documentation](https://lexicon.garden/lexicon/did:plc:np7ezqujtsry4bkogisaabul/org.cairnsproto.draft.defs)
- [Schema JSON](https://lexicon.garden/lexicon/did:plc:np7ezqujtsry4bkogisaabul/org.cairnsproto.draft.defs/schema.json)
- [Analytics](https://lexicon.garden/lexicon/did:plc:np7ezqujtsry4bkogisaabul/org.cairnsproto.draft.defs/analytics)

## #blobPayload (`org.cairnsproto.draft.defs#blobPayload`)

Type: object

### Properties

- `blob` (blob, required)
  - Constraints: maxSize: 1000000

## #conversion (`org.cairnsproto.draft.defs#conversion`)

Type: object

The payload of a converted stone: the derived source a transform produces from the site's source, by hash, and the transform. Once the conversion clears the open-children bar, each course built on this one opens one unmarked site on it, which works the derived source. Its value is the source hash alone with $type org.cairnsproto.draft.defs#conversion, so two transforms that produce the same output agree and build the same sites.

### Properties

- `source` (ref, required): sha256 of the transform's output on the site's source.
  - Reference: `#hash`
- `transform` (ref, required): The transform record, at the version that produced the output. Provenance only: it tells a client what to re-run and is not part of the value.
  - Reference: `com.atproto.repo.strongRef`

## #cost (`org.cairnsproto.draft.defs#cost`)

Type: object

Self-reported effort, as the harness reports it. Comparable across contributors on the same model; never verified.

### Properties

- `cachedTokens` (integer): Input tokens served from a prompt cache.
  - Constraints: minimum: 0
- `inputTokens` (integer, required)
  - Constraints: minimum: 0
- `outputTokens` (integer, required)
  - Constraints: minimum: 0
- `seconds` (integer, required): Wall-clock seconds.
  - Constraints: minimum: 0

## #external (`org.cairnsproto.draft.defs#external`)

Type: object

Bytes stored outside the PDS. The hash is the identity; any copy matching it is valid.

### Properties

- `hash` (ref, required)
  - Reference: `#hash`
- `urls` (array)
  - Constraints: maxLength: 32
  - `items` (string · uri)

## #externalPayload (`org.cairnsproto.draft.defs#externalPayload`)

Type: object

### Properties

- `external` (ref, required)
  - Reference: `#external`

## #hash (`org.cairnsproto.draft.defs#hash`)

Type: object

A content digest. Site keys, schema identities and segment states are sha256; a source may also be a git object named by git-sha1 or git-sha256.

### Properties

- `alg` (string, required)
  - Constraints: maxLength: 32, knownValues: sha256 | git-sha1 | git-sha256
- `value` (string, required): Lowercase hex digest.
  - Constraints: minLength: 1, maxLength: 128

## #inlinePayload (`org.cairnsproto.draft.defs#inlinePayload`)

Type: object

### Properties

- `data` (unknown, required): Validated against the site's schema.

## #method (`org.cairnsproto.draft.defs#method`)

Type: object

How a stone was produced. Versions are exact. config and cost are self-reported.

### Properties

- `agent` (string): A stable label the sponsor chooses for an agent writing to the sponsor's own repo.
  - Constraints: maxLength: 64
- `config` (ref): Hash of the agent setup, so a recall can target a faulty configuration.
  - Reference: `#hash`
- `cost` (ref)
  - Reference: `#cost`
- `env` (string)
  - Constraints: maxLength: 1024
- `model` (string): Model family.
  - Constraints: maxLength: 256
- `modelVersion` (string)
  - Constraints: maxLength: 128
- `procedure` (ref): The procedure record the stone followed.
  - Reference: `com.atproto.repo.strongRef`
- `thinking` (string): Thinking or reasoning level.
  - Constraints: maxLength: 64
- `tool` (string, required)
  - Constraints: maxLength: 256
- `toolVersion` (string, required)
  - Constraints: maxLength: 128

## #methodSelector (`org.cairnsproto.draft.defs#methodSelector`)

Type: object

Matches stones by method. Absent fields match anything.

### Properties

- `config` (ref)
  - Reference: `#hash`
- `model` (string)
  - Constraints: maxLength: 256
- `modelVersion` (string)
  - Constraints: maxLength: 128
- `tool` (string, required)
  - Constraints: maxLength: 256
- `toolVersion` (string, required)
  - Constraints: maxLength: 128

## #pageRange (`org.cairnsproto.draft.defs#pageRange`)

Type: object

1-based pages of a PDF, first through last.

### Properties

- `first` (integer, required)
  - Constraints: minimum: 1
- `last` (integer, required)
  - Constraints: minimum: 1

## #pairBase (`org.cairnsproto.draft.defs#pairBase`)

Type: object

Equivalence site: two site keys in canonical (sorted) order.

### Properties

- `sites` (array, required)
  - Constraints: minLength: 2, maxLength: 2
  - `items` (ref)
    - Reference: `#hash`

## #parentBase (`org.cairnsproto.draft.defs#parentBase`)

Type: object

Course k+1: the site marks into one candidate value of a parent site.

### Properties

- `parent` (ref, required): Site key of the parent site.
  - Reference: `#hash`
- `value` (ref, required): Digest of the canonical parent value this site builds on.
  - Reference: `#hash`

## #property (`org.cairnsproto.draft.defs#property`)

Type: object

A declared property of an equivalence cluster member's value: the JSON Pointer it sits at and the value there. A pooled candidate's digest is that of this object with $type org.cairnsproto.draft.defs#property, so it never shares a digest with a site's own value.

### Properties

- `pointer` (string, required)
  - Constraints: maxLength: 1024
- `value` (unknown, required)

## #sealedPayload (`org.cairnsproto.draft.defs#sealedPayload`)

Type: object

Timelock-encrypted to a drand quicknet round under blind policies.

### Properties

- `round` (integer, required)
  - Constraints: minimum: 1
- `sealed` (blob, required)
  - Constraints: maxSize: 1000000

## #site (`org.cairnsproto.draft.defs#site`)

Type: object

The unit of work. Stones compete when base, mark and schema are exactly equal.

### Properties

- `base` (union, required)
  - One of (closed): `#sourceBase`, `#parentBase`, `#pairBase`
- `mark` (union): Absent for equivalence sites and for sites that cover a whole base.
  - One of: `org.cairnsproto.draft.mark#pdfRegion`, `org.cairnsproto.draft.mark#imageRegion`, `org.cairnsproto.draft.mark#sheetRange`, `org.cairnsproto.draft.mark#tableRange`, `org.cairnsproto.draft.mark#textQuote`, `org.cairnsproto.draft.mark#cssSelector`, `org.cairnsproto.draft.mark#textPosition`, `org.cairnsproto.draft.mark#gitPath`, `org.cairnsproto.draft.mark#jsonPointer`, `org.cairnsproto.draft.mark#archiveMember`, `org.cairnsproto.draft.mark#mediaTime`, `org.cairnsproto.draft.mark#spaceRange`
- `schema` (ref, required): Hash of the payload schema's definition. Part of the site, so competing stones are always comparable.
  - Reference: `#hash`

## #sourceBase (`org.cairnsproto.draft.defs#sourceBase`)

Type: object

Course 0: the site marks into a source.

### Properties

- `source` (ref, required)
  - Reference: `#hash`

## #split (`org.cairnsproto.draft.defs#split`)

Type: object

The payload of a split stone: the page ranges a site breaks into, in order, each starting on the page after the previous one ends. Once the split clears the open-children bar, the site's course opens one site per part, marked by a jsonPointer to it (/parts/0, /parts/1, ...). Its value is the payload with $type org.cairnsproto.draft.defs#split.

### Properties

- `parts` (array, required)
  - Constraints: minLength: 2, maxLength: 1000
  - `items` (ref)
    - Reference: `#splitPart`

## #splitPart (`org.cairnsproto.draft.defs#splitPart`)

Type: object

### Properties

- `pages` (ref, required)
  - Reference: `#pageRange`

## Schema

```json
{
  "$type": "com.atproto.lexicon.schema",
  "defs": {
    "blobPayload": {
      "properties": {
        "blob": {
          "maxSize": 1000000,
          "type": "blob"
        }
      },
      "required": [
        "blob"
      ],
      "type": "object"
    },
    "conversion": {
      "description": "The payload of a converted stone: the derived source a transform produces from the site's source, by hash, and the transform. Once the conversion clears the open-children bar, each course built on this one opens one unmarked site on it, which works the derived source. Its value is the source hash alone with $type org.cairnsproto.draft.defs#conversion, so two transforms that produce the same output agree and build the same sites.",
      "properties": {
        "source": {
          "description": "sha256 of the transform's output on the site's source.",
          "ref": "#hash",
          "type": "ref"
        },
        "transform": {
          "description": "The transform record, at the version that produced the output. Provenance only: it tells a client what to re-run and is not part of the value.",
          "ref": "com.atproto.repo.strongRef",
          "type": "ref"
        }
      },
      "required": [
        "source",
        "transform"
      ],
      "type": "object"
    },
    "cost": {
      "description": "Self-reported effort, as the harness reports it. Comparable across contributors on the same model; never verified.",
      "properties": {
        "cachedTokens": {
          "description": "Input tokens served from a prompt cache.",
          "minimum": 0,
          "type": "integer"
        },
        "inputTokens": {
          "minimum": 0,
          "type": "integer"
        },
        "outputTokens": {
          "minimum": 0,
          "type": "integer"
        },
        "seconds": {
          "description": "Wall-clock seconds.",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "inputTokens",
        "outputTokens",
        "seconds"
      ],
      "type": "object"
    },
    "external": {
      "description": "Bytes stored outside the PDS. The hash is the identity; any copy matching it is valid.",
      "properties": {
        "hash": {
          "ref": "#hash",
          "type": "ref"
        },
        "urls": {
          "items": {
            "format": "uri",
            "type": "string"
          },
          "maxLength": 32,
          "type": "array"
        }
      },
      "required": [
        "hash"
      ],
      "type": "object"
    },
    "externalPayload": {
      "properties": {
        "external": {
          "ref": "#external",
          "type": "ref"
        }
      },
      "required": [
        "external"
      ],
      "type": "object"
    },
    "hash": {
      "description": "A content digest. Site keys, schema identities and segment states are sha256; a source may also be a git object named by git-sha1 or git-sha256.",
      "properties": {
        "alg": {
          "knownValues": [
            "sha256",
            "git-sha1",
            "git-sha256"
          ],
          "maxLength": 32,
          "type": "string"
        },
        "value": {
          "description": "Lowercase hex digest.",
          "maxLength": 128,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "alg",
        "value"
      ],
      "type": "object"
    },
    "inlinePayload": {
      "properties": {
        "data": {
          "description": "Validated against the site's schema.",
          "type": "unknown"
        }
      },
      "required": [
        "data"
      ],
      "type": "object"
    },
    "method": {
      "description": "How a stone was produced. Versions are exact. config and cost are self-reported.",
      "properties": {
        "agent": {
          "description": "A stable label the sponsor chooses for an agent writing to the sponsor's own repo.",
          "maxLength": 64,
          "type": "string"
        },
        "config": {
          "description": "Hash of the agent setup, so a recall can target a faulty configuration.",
          "ref": "#hash",
          "type": "ref"
        },
        "cost": {
          "ref": "#cost",
          "type": "ref"
        },
        "env": {
          "maxLength": 1024,
          "type": "string"
        },
        "model": {
          "description": "Model family.",
          "maxLength": 256,
          "type": "string"
        },
        "modelVersion": {
          "maxLength": 128,
          "type": "string"
        },
        "procedure": {
          "description": "The procedure record the stone followed.",
          "ref": "com.atproto.repo.strongRef",
          "type": "ref"
        },
        "thinking": {
          "description": "Thinking or reasoning level.",
          "maxLength": 64,
          "type": "string"
        },
        "tool": {
          "maxLength": 256,
          "type": "string"
        },
        "toolVersion": {
          "maxLength": 128,
          "type": "string"
        }
      },
      "required": [
        "tool",
        "toolVersion"
      ],
      "type": "object"
    },
    "methodSelector": {
      "description": "Matches stones by method. Absent fields match anything.",
      "properties": {
        "config": {
          "ref": "#hash",
          "type": "ref"
        },
        "model": {
          "maxLength": 256,
          "type": "string"
        },
        "modelVersion": {
          "maxLength": 128,
          "type": "string"
        },
        "tool": {
          "maxLength": 256,
          "type": "string"
        },
        "toolVersion": {
          "maxLength": 128,
          "type": "string"
        }
      },
      "required": [
        "tool",
        "toolVersion"
      ],
      "type": "object"
    },
    "pageRange": {
      "description": "1-based pages of a PDF, first through last.",
      "properties": {
        "first": {
          "minimum": 1,
          "type": "integer"
        },
        "last": {
          "minimum": 1,
          "type": "integer"
        }
      },
      "required": [
        "first",
        "last"
      ],
      "type": "object"
    },
    "pairBase": {
      "description": "Equivalence site: two site keys in canonical (sorted) order.",
      "properties": {
        "sites": {
          "items": {
            "ref": "#hash",
            "type": "ref"
          },
          "maxLength": 2,
          "minLength": 2,
          "type": "array"
        }
      },
      "required": [
        "sites"
      ],
      "type": "object"
    },
    "parentBase": {
      "description": "Course k+1: the site marks into one candidate value of a parent site.",
      "properties": {
        "parent": {
          "description": "Site key of the parent site.",
          "ref": "#hash",
          "type": "ref"
        },
        "value": {
          "description": "Digest of the canonical parent value this site builds on.",
          "ref": "#hash",
          "type": "ref"
        }
      },
      "required": [
        "parent",
        "value"
      ],
      "type": "object"
    },
    "property": {
      "description": "A declared property of an equivalence cluster member's value: the JSON Pointer it sits at and the value there. A pooled candidate's digest is that of this object with $type org.cairnsproto.draft.defs#property, so it never shares a digest with a site's own value.",
      "properties": {
        "pointer": {
          "maxLength": 1024,
          "type": "string"
        },
        "value": {
          "type": "unknown"
        }
      },
      "required": [
        "pointer",
        "value"
      ],
      "type": "object"
    },
    "sealedPayload": {
      "description": "Timelock-encrypted to a drand quicknet round under blind policies.",
      "properties": {
        "round": {
          "minimum": 1,
          "type": "integer"
        },
        "sealed": {
          "maxSize": 1000000,
          "type": "blob"
        }
      },
      "required": [
        "sealed",
        "round"
      ],
      "type": "object"
    },
    "site": {
      "description": "The unit of work. Stones compete when base, mark and schema are exactly equal.",
      "properties": {
        "base": {
          "closed": true,
          "refs": [
            "#sourceBase",
            "#parentBase",
            "#pairBase"
          ],
          "type": "union"
        },
        "mark": {
          "description": "Absent for equivalence sites and for sites that cover a whole base.",
          "refs": [
            "org.cairnsproto.draft.mark#pdfRegion",
            "org.cairnsproto.draft.mark#imageRegion",
            "org.cairnsproto.draft.mark#sheetRange",
            "org.cairnsproto.draft.mark#tableRange",
            "org.cairnsproto.draft.mark#textQuote",
            "org.cairnsproto.draft.mark#cssSelector",
            "org.cairnsproto.draft.mark#textPosition",
            "org.cairnsproto.draft.mark#gitPath",
            "org.cairnsproto.draft.mark#jsonPointer",
            "org.cairnsproto.draft.mark#archiveMember",
            "org.cairnsproto.draft.mark#mediaTime",
            "org.cairnsproto.draft.mark#spaceRange"
          ],
          "type": "union"
        },
        "schema": {
          "description": "Hash of the payload schema's definition. Part of the site, so competing stones are always comparable.",
          "ref": "#hash",
          "type": "ref"
        }
      },
      "required": [
        "base",
        "schema"
      ],
      "type": "object"
    },
    "sourceBase": {
      "description": "Course 0: the site marks into a source.",
      "properties": {
        "source": {
          "ref": "#hash",
          "type": "ref"
        }
      },
      "required": [
        "source"
      ],
      "type": "object"
    },
    "split": {
      "description": "The payload of a split stone: the page ranges a site breaks into, in order, each starting on the page after the previous one ends. Once the split clears the open-children bar, the site's course opens one site per part, marked by a jsonPointer to it (/parts/0, /parts/1, ...). Its value is the payload with $type org.cairnsproto.draft.defs#split.",
      "properties": {
        "parts": {
          "items": {
            "ref": "#splitPart",
            "type": "ref"
          },
          "maxLength": 1000,
          "minLength": 2,
          "type": "array"
        }
      },
      "required": [
        "parts"
      ],
      "type": "object"
    },
    "splitPart": {
      "properties": {
        "pages": {
          "ref": "#pageRange",
          "type": "ref"
        }
      },
      "required": [
        "pages"
      ],
      "type": "object"
    }
  },
  "description": "Shared definitions for Cairns records. Every Cairns record is dedicated to the public domain under CC0-1.0; placing a record asserts the right to dedicate it. Fractions are integers in parts per million (0 to 1000000) so every indexer computes identical results.",
  "id": "org.cairnsproto.draft.defs",
  "lexicon": 1
}
```