# Document structure

> A document says what kind of instruction it is before it gives any instruction, which is the orient stage of the loop written down: what exists is declared…

Page: PAG · Guide
Canonical: https://banes-lab.com/pag/guide#document-structure

This section is stop 16 of 102 in the learning route. Previous: [01 - Writing a first document](https://banes-lab.com/pag/guide/getting-started.md). Next: [03 - Semantic operations](https://banes-lab.com/pag/guide/tool-invocation.md). It builds on [01 - Writing a first document](https://banes-lab.com/pag/guide/getting-started.md).

A document says what kind of instruction it is before it gives any instruction, which is the orient stage of [the loop](https://banes-lab.com/disciplined-methodology/start/the-loop.md) written down: what exists is declared before anything is done with it. That makes a document a [self-describing structure](https://banes-lab.com/records/arch/self-describing-structures.md), laid out as shown in [B1·a skeleton](https://banes-lab.com/pag/guide#document-structure-panel-a) and ordered as shown in [B1·c parts in order](https://banes-lab.com/pag/guide#document-structure-panel-c). A document that opens with a directive has left its own contract unstated. The type it declares is one of those listed in [B1·b the types](https://banes-lab.com/pag/guide#document-structure-panel-b), and [B1·d what a type fixes](https://banes-lab.com/pag/guide#document-structure-panel-d) shows what that one line settles before any node is walked.

### Declare, then instruct

A document with no declared type has an unstated contract, so each reader, the developer or the model, supplies its own. A reader cannot tell whether a document is a standing policy or a one-time task, walks a policy once and then drops it, and the rules it carried end up applying to nothing. A reader classifies a document from its first lines and reads everything after against that guess.

For this reason the type comes first, and everything after it is read against that type. The contract is fixed on the first line with a type, rather than left for the reader to infer from the directives below. In practice, a document runs in this order: the header, the declaration, the meta block and the frame the nodes cite, and it closes with the repair edge and the invariants.

To check this, cover everything below the declaration and ask what the document is for, what will walk it and how it will be used. A declaration that cannot answer all three is missing a type or an intent. A fragment reused inside other documents carries no header of its own, because the enclosing document already declared the contract. A fragment that declares a second type is two documents.

The meta block settles four things before any node runs. The priority between sources decides a disagreement before it arises. The trust anchor ensures that a claim from an untrusted source is never promoted to evidence just by being read. The jurisdiction states what the document may touch and what it declares outside itself, rather than leaving that assumed; it is the same boundary [the honest gaps](https://banes-lab.com/disciplined-methodology/ship/the-honest-gaps.md) draws for a system. The recursion limit makes a repair loop terminate. Choosing the type chooses the contract, the reasoning model and the axis at once, and the verb makes that choice legible on the first line.

The substrate and the spine are declared once and cited by every node. The substrate orders the nodes, as described in [node design](https://banes-lab.com/pag/guide/node-design.md), and each node names its stage on it. The spine declares every transition: which node leads to which, where a failed [verification](https://banes-lab.com/records/arch/verification.md) sends the work back, and where the loop terminates. A node names its place on both and inherits the rest, which is why a document reads as one structure rather than ten separate documents. The document closes with its invariant records and a report, which states the verdict in a form a later checker can challenge, as described in [a report, not a checkbox](https://banes-lab.com/disciplined-methodology/verify/a-report-not-a-checkbox.md).

B1·a skeleton

```pag
---
name: <document-name>
type: WORKFLOW
version: 1.0.0
---

THIS WORKFLOW EXECUTES <what it is for>

%% META %%:
priority: <what outranks what when two sources disagree>
trust: <what is trusted> = TRUSTED, <what is not> = UNTRUSTED
objective: "<what finished looks like, checkable>"
jurisdiction: <what the document may touch> | external: <what it declares outside itself>
recursion_limit: <a bound on repair>

# THE FOUR LAYERS · each answers one question about this document
#   substrate  — how does the artifact come to be        grounds the order of the nodes, named on each by @genesis
#   epistemic  — how is it known                          orient · see · derive · project · act
#   conative   — what is worth doing                      intent · constrain            mandatory, always
#   evaluative — is it right, and are we done             verify · commit · terminate   mandatory, always

# YIELDS-SHAPE LEGEND · every decision resolves to a typed shape
#   set-theory → set|boolean · logic → boolean · graph → edge-list · optimisation → boolean|ranking · computation → procedure

# SEMANTIC OPERATION BOUNDARY · nodes say WHAT as operations; an adapter decides HOW, and the core names no tool or path

# THE LOOP SPINE · transitions declared once, every node cites it
# node · layer · axis · yields · transition out

# NODE 1 — ORIENT … NODE 10 — TERMINATE · each with its four-slot tag, its genesis stage, its contract and one evidence-bearing gate

# REPAIR EDGE · verify refutes back to the earliest invalid node, bounded by recursion_limit

# CROSS-NODE INVARIANTS
INVARIANT <name>: <a property that could be false> over: <the set it ranges over> binds: <the parties it constrains> objector: <the check that would disagree | none>

REPORT:
subject: <the terminal node>
verdict: pass | fail | unknown
domain: declared <N> measured <n>
completion: saturated <bool> complete <bool> verified <bool>
```

B1·b the types

```pag
# a type binds a document to a reasoning model and to the axis of the loop it sits on

# cognition · how a system perceives, acts and adapts
THIS AGENT PERFORMS <a behaviour, walked as nodes>                axis: reasoning
THIS WORKFLOW EXECUTES <a multi-node process>                    axis: formalisation
THIS PROMPT IS <one interaction>                                 axis: formalisation
THIS COMMAND EXECUTES <one invocable operation>                  axis: formalisation

# pattern-cycle · how pattern-work proceeds
THIS PROTOCOL DEFINES <a standing procedure, as rules>           axis: formalisation
THIS CHECKLIST PROVIDES <tasks with their contracts>             axis: formalisation
THIS TASK EXECUTES <one objective>                               axis: formalisation
THIS INSTRUCTION IS <general guidance>                           axis: formalisation
THIS COMPOSITION RENDERS <a structure from anchors and modifiers> axis: formalisation
THIS POLICY ENFORCES <a constraint set>                          axis: teleology
THIS TEMPLATE IMPLEMENTS <a reusable shape, slots open>          axis: representation

# epistemology · how a pattern is known
THIS TEST PERFORMS <a specification checked by running it>       axis: verification
THIS VERIFICATION PERFORMS <claims adjudicated against evidence> axis: verification
THIS AUDIT AUDITS <an artifact against a contract, then corrects> axis: verification
THIS DEBUG RESOLVES <a symptom to an evidence-scored cause>      axis: analysis
THIS DISTILLATION DISTILLS <repeated behaviour into one base>    axis: reasoning
THIS TRANSLATION AUDITS <a rendering against its source>         axis: representation
```

B1·c parts in order

```mermaid
flowchart TB
front["Header block · name, type, version"]
decl["Declaration · THIS TYPE VERB description"]
meta["META · priority, trust, objective, bounds"]
frame["The four layers, the shape legend, the operation boundary"]
substrate["The substrate · how the artifact comes to be"]
spine["The spine · transitions declared once"]
nodes["Nodes · each with a contract and one gate"]
repair["The repair edge · bounded"]
rules["Cross-node invariants · one record each"]
report["The report · what was measured, over what, and whether the three conditions coincide"]
front --> decl --> meta --> frame --> substrate --> spine --> nodes --> repair --> rules --> report
```

B1·d what a type fixes

```mermaid
flowchart LR
type["The declared type"]
verb["Its default verb"]
model["The reasoning model that walks it"]
axis["The axis of the loop it sits on"]
reader["A reader knows what kind of instruction this is, and what will walk it"]
type --> verb --> reader
type --> model --> reader
type --> axis --> reader
```

## Links to

- [The loop](https://banes-lab.com/disciplined-methodology/start/the-loop.md)
- [Self-Describing Structures](https://banes-lab.com/records/arch/self-describing-structures.md)
- [The honest gaps](https://banes-lab.com/disciplined-methodology/ship/the-honest-gaps.md)
- [Node design](https://banes-lab.com/pag/guide/node-design.md)
- [Verification](https://banes-lab.com/records/arch/verification.md)
- [A report, not a checkbox](https://banes-lab.com/disciplined-methodology/verify/a-report-not-a-checkbox.md)

## Linked from

- [BNF grammar](https://banes-lab.com/pag/grammar/bnf-grammar.md)
- [The behaviour document](https://banes-lab.com/disciplined-methodology/start/the-behaviour-document.md)