# tools/core/runners/board.runner.ts

> 285 lines of code and 47 definitions.

Tree: Coordination tree
Language: typescript
Canonical: https://banes-lab.com/anatomy/coordination#file-coordination-tools-core-runners-board-runner-ts
Source text: https://banes-lab.com/assets/sources/source.0e5c239a50eaba6c162044868087d956bbaf9544375fb2308beb0e3f2f1266de.generated.txt

## Definitions

- `refuse` (lexical_declaration, line 56)
- `contended` (lexical_declaration, line 60)
- `runCompression` (lexical_declaration, line 270, exported)
- `barrierState` (lexical_declaration, line 89, exported)
- `runItem` (lexical_declaration, line 121, exported)
- `runField` (lexical_declaration, line 207, exported)
- `CompressRequest` (interface_declaration, line 36, exported)
- `CompressOutcome` (interface_declaration, line 47, exported)
- `JUDGEMENT_KIND` (lexical_declaration, line 54)
- `changes` (lexical_declaration, line 61)
- `ItemRequest` (interface_declaration, line 69, exported)
- `BOARD_ITEM_FIELD` (lexical_declaration, line 81)
- `VENUE_ITEM_FIELD` (lexical_declaration, line 83)
- `itemFieldFor` (lexical_declaration, line 85)
- `positionStructure` (lexical_declaration, line 97, exported)
- `template` (lexical_declaration, line 98, exported)
- `labels` (lexical_declaration, line 103, exported)
- `out` (lexical_declaration, line 104, exported)
- `field` (lexical_declaration, line 134, exported)
- `archive` (lexical_declaration, line 152, exported)
- `cited` (lexical_declaration, line 154, exported)
- `fenced` (lexical_declaration, line 159, exported)
- `FieldRequest` (interface_declaration, line 182, exported)
- `FIELD_COLUMN` (lexical_declaration, line 190)
- `fieldKeyAt` (lexical_declaration, line 192)
- `trimmed` (lexical_declaration, line 197, exported)
- `colon` (lexical_declaration, line 198)
- `declared` (lexical_declaration, line 220, exported)
- `at` (lexical_declaration, line 221, exported)
- `index` (lexical_declaration, line 223, exported)
- `key` (lexical_declaration, line 224, exported)
- `indent` (lexical_declaration, line 239, exported)
- `label` (lexical_declaration, line 240, exported)
- `written` (lexical_declaration, line 241, exported)
- `carried` (lexical_declaration, line 279, exported)
- `refusal` (lexical_declaration, line 280, exported)
- `before` (lexical_declaration, line 285, exported)
- `dropped` (lexical_declaration, line 288, exported)
- `span` (lexical_declaration, line 308, exported)
- `lines` (lexical_declaration, line 314, exported)
- `head` (lexical_declaration, line 315, exported)
- `body` (lexical_declaration, line 316, exported)
- `tail` (lexical_declaration, line 317, exported)
- `compressed` (lexical_declaration, line 319, exported)
- `witness` (lexical_declaration, line 325, exported)
- `conflict` (lexical_declaration, line 327, exported)
- `text` (lexical_declaration, line 336, exported)

## Uses

- [tools/core/formatters/board.formatter.ts](https://banes-lab.com/source/coordination/tools/core/formatters/board.formatter.ts.md)
- [tools/core/strings/board.strings.ts](https://banes-lab.com/source/coordination/tools/core/strings/board.strings.ts.md)

## Used by

- [tools/core/coordinators/board.coordinator.ts](https://banes-lab.com/source/coordination/tools/core/coordinators/board.coordinator.ts.md)
- [tools/core/entrypoints/board.entrypoint.ts](https://banes-lab.com/source/coordination/tools/core/entrypoints/board.entrypoint.ts.md)

## Source

```typescript
import {
    COMPRESS_NEEDS_AGENT,
    barrierHeld,
    barrierOpen,
    compressionNoRecord,
    fieldRewritten,
    fieldUnchanged,
    fieldUndeclared,
    fieldsCompressed,
    itemAdded,
    itemDropped,
    itemFenceMalformed,
    itemFieldMissing,
    kindEcho,
    noMarkedField,
    noOwnRecord,
    nothingToCompress,
    positionOnBoard,
    positionUnsigned,
    recordContended,
    surfaceAbsent,
    surfaceContended,
} from "../strings/board.strings.ts";
import { SIGNED_LEAD, positionFieldLabels } from "../validators/venue.validator.ts";

import { type SpanConflict, compareSpans, dropItemSpan } from "../resolvers/board.resolver.ts";
import { blockOf, compressBoard } from "../transformers/board.transformer.ts";
import { citedSurfaces, fencedItem, isItemId, nextOrdinal } from "../formatters/board.formatter.ts";
import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
import { BLOCKING_SUFFIX } from "../constants/blocking.constants.ts";
import { citedAbsolute } from "../validators/claim.validator.ts";
import { extractionRefusal } from "../validators/archive.validator.ts";
import { resolve } from "node:path";
import { surfacePath } from "../../../config/surface.config.ts";

export interface CompressRequest {
    readonly target: string;
    readonly absolute: string;
    readonly marker: string;
    readonly agent: string | null;
    readonly extracted: string | null;
    readonly archive: string;
    readonly changelog: string;
    readonly heal: boolean;
}

export interface CompressOutcome {
    readonly message: string;
    readonly code: number;
    readonly excised: readonly string[];
    readonly write: string | null;
}

const JUDGEMENT_KIND = "judgement";

const refuse = function refuse(message: string, code: number): CompressOutcome {
    return { code, excised: [], message, write: null };
};

const contended = function contended(target: string, agent: string, conflict: SpanConflict): CompressOutcome {
    const changes = [
        ...conflict.added.map((line) => `  + ${line.trim().slice(0, 110)}\n`),
        ...conflict.removed.map((line) => `  - ${line.trim().slice(0, 110)}\n`),
    ];

    return { code: 1, excised: [], message: recordContended(target, agent, changes), write: null };
};

export interface ItemRequest {
    readonly target: string;
    readonly absolute: string;
    readonly agent: string;
    readonly text: string;
    readonly at: number;
    readonly kind: string;
    readonly archive: string;
    readonly siblings: readonly string[];
    readonly repoRoot: string;
}

const BOARD_ITEM_FIELD = "  Flags:";

const VENUE_ITEM_FIELD = "  Positions:";

const itemFieldFor = function itemFieldFor(target: string): string {
    return target.endsWith(BLOCKING_SUFFIX) ? VENUE_ITEM_FIELD : BOARD_ITEM_FIELD;
};

export const barrierState = function barrierState(agents: number, parked: number): { message: string; code: number } {
    if (agents > 0 && parked >= agents - 1) {
        return { code: 0, message: barrierHeld(parked, agents - 1) };
    }

    return { code: 1, message: barrierOpen(parked, agents - 1) };
};

export const positionStructure = function positionStructure(repoRoot: string, text: string): string[] {
    const template = resolve(repoRoot, surfacePath("venue_template"));
    if (!existsSync(template)) {
        return [];
    }

    const labels = positionFieldLabels(readFileSync(template, "utf8"));
    const out: string[] = [];

    for (const line of text.split("\n")) {
        const trimmed = line.trim();
        for (const label of labels) {
            if (out.includes(label)) {
                continue;
            }
            if (trimmed.startsWith(`${label}:`)) {
                out.push(label);
            }
        }
    }

    return out;
};

export const runItem = function runItem(request: ItemRequest): CompressOutcome {
    if (!existsSync(request.absolute)) {
        return refuse(surfaceAbsent(request.target), 2);
    }

    const before = readFileSync(request.absolute, "utf8");
    const span = blockOf(before, request.agent);

    if (span === null) {
        return refuse(noOwnRecord(request.agent), 2);
    }

    const lines = before.split("\n");
    const field = itemFieldFor(request.target);
    const at = lines.findIndex((line, index) => index >= span.from && line.startsWith(field));

    if (at === -1 || at >= span.to) {
        return refuse(itemFieldMissing(request.agent, field.trim(), request.target), 2);
    }

    if (!request.target.endsWith(BLOCKING_SUFFIX)) {
        const carried = positionStructure(request.repoRoot, request.text);
        if (carried.length > 1) {
            return refuse(positionOnBoard(carried), 2);
        }
    }

    if (request.target.endsWith(BLOCKING_SUFFIX) && !request.text.includes(SIGNED_LEAD)) {
        return refuse(positionUnsigned(SIGNED_LEAD), 2);
    }

    const archive = existsSync(request.archive) ? readFileSync(request.archive, "utf8") : "";
    const key = `${request.agent}-${String(nextOrdinal([before, ...request.siblings], request.agent, archive))}`;
    const cited = citedSurfaces(request.text)
        .map((path) => ({ absolute: citedAbsolute(request.repoRoot, path), path }))
        .filter((entry) => entry.absolute !== null)
        .map((entry) => ({ at: statSync(entry.absolute ?? "").mtimeMs, path: entry.path }));

    const fenced = fencedItem(key, request.text, request.at, request.kind, cited);

    const written = [...lines.slice(0, at + 1), ...fenced, ...lines.slice(at + 1)].join("\n");

    const witness = readFileSync(request.absolute, "utf8");
    if (witness === before) {
        writeFileSync(request.absolute, written, "utf8");
        return {
            code: 0,
            excised: [],
            message: `${itemAdded(key, request.target)}${kindEcho(request.kind, request.kind === JUDGEMENT_KIND)}`,
            write: written,
        };
    }

    const conflict = compareSpans(before, witness, request.agent);
    if (conflict.overlapping) {
        return contended(request.target, request.agent, conflict);
    }

    return runItem({ ...request });
};

export interface FieldRequest {
    readonly target: string;
    readonly absolute: string;
    readonly agent: string;
    readonly field: string;
    readonly text: string;
}

const FIELD_COLUMN = 9;

const fieldKeyAt = function fieldKeyAt(line: string): string {
    if (!line.startsWith("  ") || line.charAt(2) === " ") {
        return "";
    }

    const trimmed = line.trim();
    const colon = trimmed.indexOf(":");
    if (colon <= 0) {
        return "";
    }

    const key = trimmed.slice(0, colon);
    return key.includes(" ") ? "" : key;
};

export const runField = function runField(request: FieldRequest): CompressOutcome {
    if (!existsSync(request.absolute)) {
        return refuse(surfaceAbsent(request.target), 2);
    }

    const before = readFileSync(request.absolute, "utf8");
    const span = blockOf(before, request.agent);

    if (span === null) {
        return refuse(noOwnRecord(request.agent), 2);
    }

    const lines = before.split("\n");
    const declared: string[] = [];
    let at = -1;

    for (let index = span.from; index < span.to && index < lines.length; index += 1) {
        const key = fieldKeyAt(lines[index] ?? "");
        if (key.length === 0) {
            continue;
        }

        declared.push(key);
        if (key === request.field) {
            at = index;
        }
    }

    if (at === -1) {
        return refuse(fieldUndeclared(request.agent, request.field, request.target, declared), 2);
    }

    const indent = (lines[at] ?? "").slice(0, (lines[at] ?? "").indexOf(request.field));
    const label = `${indent}${request.field}:`;
    const written = [
        ...lines.slice(0, at),
        `${label}${" ".repeat(Math.max(1, FIELD_COLUMN - request.field.length - 1))}${request.text}`,
        ...lines.slice(at + 1),
    ].join("\n");

    if (written === before) {
        return { code: 0, excised: [], message: fieldUnchanged(request.field, request.target), write: before };
    }

    const witness = readFileSync(request.absolute, "utf8");
    if (witness === before) {
        writeFileSync(request.absolute, written, "utf8");
        return {
            code: 0,
            excised: [],
            message: fieldRewritten(request.field, request.agent, request.target),
            write: written,
        };
    }

    const conflict = compareSpans(before, witness, request.agent);
    if (conflict.overlapping) {
        return contended(request.target, request.agent, conflict);
    }

    return runField({ ...request });
};

export const runCompression = function runCompression(request: CompressRequest): CompressOutcome {
    if (!existsSync(request.absolute)) {
        return refuse(nothingToCompress(request.target), 2);
    }

    if (request.agent === null) {
        return refuse(COMPRESS_NEEDS_AGENT, 2);
    }

    const carried = existsSync(request.archive) ? readFileSync(request.archive, "utf8") : "";
    const refusal = extractionRefusal(request.changelog, request.extracted, carried);
    if (refusal !== null) {
        return refuse(refusal, 2);
    }

    const before = readFileSync(request.absolute, "utf8");

    if (isItemId(request.marker)) {
        const dropped = dropItemSpan(before, request.marker);
        if (dropped === null) {
            return refuse(itemFenceMalformed(request.marker), 2);
        }

        if (request.heal) {
            if (readFileSync(request.absolute, "utf8") !== before) {
                return refuse(surfaceContended(request.target), 1);
            }
            writeFileSync(request.absolute, dropped.text, "utf8");
        }

        return {
            code: 0,
            excised: [request.marker],
            message: itemDropped(request.marker, dropped.removed, request.heal),
            write: request.heal ? dropped.text : null,
        };
    }

    const span = blockOf(before, request.agent);

    if (span === null) {
        return refuse(compressionNoRecord(request.agent), 2);
    }

    const lines = before.split("\n");
    const head = lines.slice(0, span.from);
    const body = lines.slice(span.from, span.to - 1);
    const tail = lines.slice(span.to - 1);

    const compressed = compressBoard(body.join("\n"), request.marker);
    if (compressed.fields === 0) {
        return refuse(noMarkedField(request.target), 0);
    }

    if (request.heal) {
        const witness = readFileSync(request.absolute, "utf8");
        if (witness !== before) {
            const conflict = compareSpans(before, witness, request.agent);
            if (conflict.overlapping) {
                return contended(request.target, request.agent, conflict);
            }

            return runCompression({ ...request });
        }
    }

    const text = [...head, compressed.text, ...tail].join("\n");
    if (request.heal) {
        writeFileSync(request.absolute, text, "utf8");
    }

    return {
        code: 0,
        excised: compressed.excised,
        message: fieldsCompressed(request.target, compressed.fields, compressed.removed, request.heal),
        write: request.heal ? text : null,
    };
};
```