# configuration/strings/construct.strings.ts

> 62 lines of code and 6 definitions.

Tree: Site tree
Language: typescript
Layer: product
Canonical: https://banes-lab.com/anatomy/tree#file-configuration-strings-construct-strings-ts
Source text: https://banes-lab.com/assets/sources/source.c58c8e114127da2ec1b60a2fb95dda619e17cd5e452c4a637f12608f6a6645c0.generated.txt

## Definitions

- `SCHEMA_SAMPLE` (lexical_declaration, line 6)
- `STATE_SAMPLE` (lexical_declaration, line 9)
- `LIFETIME_SAMPLE` (lexical_declaration, line 12)
- `RECORD_DIAGRAM` (lexical_declaration, line 15)
- `WRITE_DIAGRAM` (lexical_declaration, line 18)
- `CONSTRUCT_SECTION` (lexical_declaration, line 21, exported)

## Source

```typescript
import { CONSTRUCT_SECTION_ICON } from "#configuration/icons/grammar.icons";
import { CONSTRUCT_SECTION_ID } from "#core/ids/grammar.ids";
import { PAG_LANGUAGE } from "#configuration/constants/code.constants";
import type { Section } from "#types/document.types";

const SCHEMA_SAMPLE =
    "# the four things a document declares about a shared surface · a structure declaration, never prose\nSURFACE <key>:                                   # declared in the header, never derived from the path\n    RECORD <key>-1 subject: <what it is about>   # one writer, named on the record · the fence an edit anchors on\n        ITEM <key>-1-1 TO <reader>: <a claim>    # an addressed span · its id allocated once, never reused\n            SATISFIED_BY <artifact>              # an edge · an id in a field · resolves or does not\n            BLOCKS <key>-2-1\n    RECORD <key>-2 subject: <what it is about>\n        ITEM <key>-2-1 TO <reader>: <a claim>\n            ANSWERS <key>-1-1\n\n# the states are derived from the edges, never written\nstate: OPEN | BLOCKED | ABSORBED\n\n# the lifetime, declared on three axes a mechanism can join on\nDECLARE lifetime: object\nSET lifetime = {retention: <what ends a piece of content>, mutability: <who may rewrite a landed statement>, removal: <who may take content out>}";

const STATE_SAMPLE =
    '# no party writes a state · every state is a function over the edges, evaluated on every read\nFUNCTION state_of(item):\n  IF resolves(item.edges.satisfied_by): RETURN <absorbed>       # a transition · extract, then delete in the same change\n  FOR EACH edge IN inbound(item, <blocks>):\n    IF state_of(edge.from) == <open>: RETURN <blocked>\n  RETURN <open>\n\n# NODE 6 — ACT   [epistemic · formalisation · computation · yields: procedures]\nCONTRACT:\n  input:        <my record> + <the surface as it stands>\n  transform:    read the surface whole → anchor on my own fence → land the edit inside it\n  constraints:  a write to a path not read this turn is an edit to unknown contents; a whole-file write reports success to the one who overwrote and nothing to the one overwritten\n  output:       <my record, revised>\n  handoff:      the edit landed inside my fence and the surface had not moved, or the edit was refused with the diff (yields: boolean)\n\nHANDOFF GATE (evidence-bearing):\n  rule_id: "ACT"   yields: boolean\n  [check] nothing outside my fence changed (evidence: the diff of the surface) over: the surface\'s records measured: <untouched> / <records>\n  [check] the surface was read whole immediately before the write (evidence: the witness read)\n  [check] a moved surface refused the write, or the write commuted and replayed (evidence: the compare against my own span)\n  refuse: the surface moved inside my span since the witness read before PERSIST_ARTIFACT\n  standing: moved-set <the records that moved outside my span>\n  result: pass → NODE 7 | a write outside my fence → REPAIR (owner: NODE 6) | unknown → BLOCKED';

const LIFETIME_SAMPLE =
    "# a lifetime is three independent axes · one word for it drops the axis a reader assumes follows\nDECLARE lifetimes: array\nSET lifetimes = [\n  {surface: <a coordination surface>, retention: <current-truth>,  mutability: <owner-rewritable>, removal: <the handler of an item>},\n  {surface: <an argument>,            retention: <accumulating>,   mutability: <append-only>,      removal: <none while open · moved whole when settled>},\n  {surface: <an archive>,             retention: <accumulating>,   mutability: <frozen>,           removal: <none>}\n]\n\nFUNCTION may_remove(party, content, surface):\n  # decided from the declaration, never from the shape of the path\n  SET lifetime = lifetimes[surface]\n  RETURN lifetime.removal == party.role_on(content)";

const RECORD_DIAGRAM =
    'flowchart TB\n    surface["A surface · a file the parties read and write"]\n    r1["Record · one writer, declared on the record"]\n    r2["Record · one writer"]\n    item["Item · an allocated id, a kind, its readers"]\n    ref["An edge · an id in a field · resolves or does not"]\n    state["State · a function over the edges, written by no party"]\n    surface --> r1\n    surface --> r2\n    r1 --> item --> ref --> state';

const WRITE_DIAGRAM =
    'flowchart TB\n    intent["A party intends a write"]\n    read["Read the surface whole"]\n    span["Anchor on its own fence"]\n    moved{"Surface moved since the read?"}\n    land["Land inside the span"]\n    overlap{"Overlap with its own span?"}\n    replay["Replay · the writes commute"]\n    refuse["Refuse · with the diff of the span"]\n    intent --> read --> span --> moved\n    moved -- no --> land\n    moved -- yes --> overlap\n    overlap -- no --> replay --> land\n    overlap -- yes --> refuse';

export const CONSTRUCT_SECTION: Section = {
    icon: CONSTRUCT_SECTION_ICON,
    id: CONSTRUCT_SECTION_ID,
    intro: "When more than one party writes to one tree, the surfaces they share are shared mutable state. A document expresses four things about them, the schema, the records, the items and their lifetime, as written in <cite>surface declared</cite> and shown in <cite>surface to state</cite>. The definitions and the reasons are given in coordination is software and in the board and the venue; this section declares the shape. <cite>state as function</cite> shows how a state is read and a write is fenced, <cite>a write lands</cite> shows where a write lands or is refused, and <cite>lifetime axes</cite> shows the declaration a mechanism reads.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "In practice, a shared surface is declared as a schema: its key in the header, one record per writer with the writer named on the record, and a fence around each record so that an edit has a span to anchor on. An item is declared with an id the surface allocates, a kind that selects its closure, and the readers it is addressed to. Open, blocked and absorbed are derived by a function over the edges, an absorbed item's durable half is extracted and the item deleted in the same change, and each surface's lifetime is declared on retention, mutability and removal.",
                    boundary:
                        "An outcome surface written jointly has no per-party unit for the one-writer rule to range over, so the invariant is declared inapplicable there, with its reason. A clash of meaning on such a surface is caught by announcing the intended write, with each author removing its own duplicate.",
                    cause: "A file offers no span a party can anchor on unless the document declares one, so the only edit available is the whole file.",
                    decision:
                        "The surface is declared as a schema a tool can refuse against, rather than described in prose the parties have to keep in mind.",
                    failureMode:
                        "Two parties revise their own records by rewriting the file, each correctly, and the second write is a lost update for the first party, with no error anywhere.",
                    kind: "lesson",
                    principle:
                        "For this reason a shared surface holds records with one writer each, and every state is a query over those records.",
                    problem:
                        "A shared document with no declared writer per span is one that every party rewrites whole.",
                    validation:
                        "To check this, take the last write to a shared surface and name the span it was anchored on. A write with no span was a whole-file write, and the neighbour it overwrote is the finding.",
                },
                {
                    kind: "text",
                    text: "The document states the one writer per record on the record itself. The act node that writes carries the mechanism as its contract: a witness read, an anchor on its own fence, and a refusal when the surface has moved. An edit against a moved surface is therefore refused with the diff, and a whole-file write is never the available path.",
                },
                {
                    kind: "text",
                    text: "The document writes no state. Every state is a function over the edges, declared once and evaluated on every read, as described in derived state, and an item whose citation resolves is extracted and deleted in the same change rather than left resting in a state.",
                },
                {
                    kind: "text",
                    text: "A lifetime is declared on the three axes derived in stating an invariant, each drawn from a closed set, so the declaration is a value a mechanism can join on rather than a sentence. A mechanism decides what it may do to a surface from that declaration, never from the shape of the surface's path.",
                },
                { code: SCHEMA_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "surface declared" },
                { code: STATE_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "state as function" },
                { code: LIFETIME_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "lifetime axes" },
                { caption: "surface to state", kind: "mermaid", text: RECORD_DIAGRAM },
                { caption: "a write lands", kind: "mermaid", text: WRITE_DIAGRAM },
            ],
            title: "Records, items, derived states",
        },
    ],
    title: "Shared surfaces",
};
```