# tools/core/resolvers/surface.resolver.ts

> 146 lines of code and 31 definitions.

Tree: Coordination tree
Language: typescript
Layer: infrastructure
Canonical: https://banes-lab.com/anatomy/coordination#file-coordination-tools-core-resolvers-surface-resolver-ts
Source text: https://banes-lab.com/source/coordination/tools/core/resolvers/surface.resolver.ts.txt

Listed in [tools/core/resolvers](https://banes-lab.com/api/source/coordination/tools/core/resolvers.md), after [tools/core/resolvers/snapshot.resolver.ts](https://banes-lab.com/source/coordination/tools/core/resolvers/snapshot.resolver.ts.md) and before [tools/core/resolvers/sweep.resolver.ts](https://banes-lab.com/source/coordination/tools/core/resolvers/sweep.resolver.ts.md).

## Definitions

- `at` (lexical_declaration, line 43)
- `pairsFor` (lexical_declaration, line 41)
- `reachedByTool` (lexical_declaration, line 105)
- `isDeclaredSlot` (lexical_declaration, line 118, exported)
- `suffixTargets` (lexical_declaration, line 34)
- `isFlagCharacter` (lexical_declaration, line 68)
- `inScope` (lexical_declaration, line 101)
- `bothVenues` (lexical_declaration, line 111)
- `immutableRoot` (lexical_declaration, line 30)
- `slotMandates` (lexical_declaration, line 122, exported)
- `mandateRoute` (lexical_declaration, line 156, exported)
- `venueMandates` (lexical_declaration, line 22, exported)
- `toolWritable` (lexical_declaration, line 62, exported)
- `flagsIn` (lexical_declaration, line 75, exported)
- `suffixMandates` (lexical_declaration, line 133, exported)
- `FLAG_OPEN` (lexical_declaration, line 18)
- `FLAG_CLOSE` (lexical_declaration, line 20)
- `immutable` (lexical_declaration, line 35)
- `anyMember` (lexical_declaration, line 42)
- `surfaceTarget` (lexical_declaration, line 53, exported)
- `prefixed` (lexical_declaration, line 58, exported)
- `prefix` (lexical_declaration, line 63, exported)
- `venues` (lexical_declaration, line 64, exported)
- `out` (lexical_declaration, line 76, exported)
- `from` (lexical_declaration, line 77, exported)
- `open` (lexical_declaration, line 80, exported)
- `cursor` (lexical_declaration, line 85, exported)
- `flag` (lexical_declaration, line 90, exported)
- `named` (lexical_declaration, line 91, exported)
- `regionsWith` (lexical_declaration, line 148, exported)
- `namedOf` (lexical_declaration, line 167, exported)

## Uses

- [config/surface.config.ts](https://banes-lab.com/source/coordination/config/surface.config.ts.md)
- [tools/core/validators/venue.validator.ts](https://banes-lab.com/source/coordination/tools/core/validators/venue.validator.ts.md)

## Source

```typescript
import { ASSESSED_FORMS, TOOL_WRITTEN } from "../registries/surface.registry.ts";
import type {
    MandateRoute,
    MandatedSurface,
    ResolvedMandate,
    ToolForm,
    WritablePair,
    WriteOperand,
} from "../types/surface.types.ts";
import { PARTY_WRITTEN, RECORD_FIELD_REFUSAL, SEEDED_MANDATES } from "../constants/surface.constants.ts";
import { config, isResolved, surfacePath, surfacePrefix } from "../../../config/surface.config.ts";
import { BLOCKING_SUFFIX } from "../constants/blocking.constants.ts";
import { BOARD_PATH } from "../constants/board.constants.ts";
import { existsSync } from "node:fs";
import { resolve } from "node:path";
import { venueFieldsFrom } from "../validators/venue.validator.ts";

const FLAG_OPEN = '"--';

const FLAG_CLOSE = '"';

export const venueMandates = function venueMandates(template: string): Omit<MandatedSurface, "slot">[] {
    const out: Omit<MandatedSurface, "slot">[] = [...SEEDED_MANDATES];
    for (const field of venueFieldsFrom(template)) {
        out.push({ member: field, operand: "field", refusal: RECORD_FIELD_REFUSAL });
    }
    return out;
};

const immutableRoot = function immutableRoot(): string | null {
    return isResolved("surface", "venue_archive") ? surfacePath("venue_archive") : null;
};

const suffixTargets = function suffixTargets(paths: readonly string[]): string[] {
    const immutable = immutableRoot();
    return paths
        .filter((path) => path.endsWith(BLOCKING_SUFFIX))
        .filter((path) => immutable === null || !path.startsWith(`${immutable}/`));
};

const pairsFor = function pairsFor(written: ToolForm, venues: string): WritablePair[] {
    const anyMember = written.anyMember === true;
    const at = (path: string): WritablePair => ({ anyMember, member: written.member, operand: written.operand, path });

    if (written.slots !== undefined) {
        return written.slots
            .filter((slotName) => isResolved("surface", slotName))
            .map((slotName) => at(surfacePath(slotName)));
    }
    return written.venueOnly ? [at(venues)] : [at(BOARD_PATH), at(venues)];
};

export const surfaceTarget = function surfaceTarget(root: string, named: string): string {
    if (existsSync(resolve(root, named))) {
        return named;
    }
    const prefix = surfacePrefix();
    const prefixed = prefix.length === 0 ? named : `${prefix}/${named}`;
    return existsSync(resolve(root, prefixed)) ? prefixed : named;
};

export const toolWritable = function toolWritable(): WritablePair[] {
    const prefix = surfacePrefix();
    const venues = prefix.length === 0 ? BLOCKING_SUFFIX : `${prefix}/${BLOCKING_SUFFIX}`;
    return TOOL_WRITTEN.flatMap((written) => pairsFor(written, venues));
};

const isFlagCharacter = function isFlagCharacter(char: string): boolean {
    if (char === "-") {
        return true;
    }
    return char >= "a" && char <= "z";
};

export const flagsIn = function flagsIn(source: string): string[] {
    const out: string[] = [];
    let from = 0;

    while (from < source.length) {
        const open = source.indexOf(FLAG_OPEN, from);
        if (open === -1) {
            break;
        }

        let cursor = open + 1;
        while (cursor < source.length && isFlagCharacter(source.charAt(cursor))) {
            cursor += 1;
        }

        const flag = source.slice(open + 1, cursor);
        const named = cursor > open + FLAG_OPEN.length;
        if (named && source.charAt(cursor) === FLAG_CLOSE && !out.includes(flag)) {
            out.push(flag);
        }
        from = open + FLAG_OPEN.length;
    }

    return out;
};

const inScope = function inScope(paths: readonly string[], target: string): boolean {
    return paths.some((path) => path === target || path.startsWith(`${target}/`));
};

const reachedByTool = function reachedByTool(
    target: string,
    operand: WriteOperand,
    member: string | null,
    writable: readonly WritablePair[],
): boolean {
    const bothVenues = (pair: WritablePair): boolean =>
        pair.path.endsWith(BLOCKING_SUFFIX) && target.endsWith(BLOCKING_SUFFIX);
    return writable
        .filter((pair) => pair.operand === operand && (pair.anyMember || pair.member === member))
        .some((pair) => target === pair.path || bothVenues(pair));
};

export const isDeclaredSlot = function isDeclaredSlot(slot: string): boolean {
    return Object.keys(config.surface).includes(slot) && isResolved("surface", slot);
};

export const slotMandates = function slotMandates(): ResolvedMandate[] {
    return PARTY_WRITTEN.filter((mandated) => isDeclaredSlot(mandated.slot)).map((mandated) => ({
        from: mandated.slot,
        member: mandated.member,
        operand: mandated.operand,
        refusal: mandated.refusal,
        target: surfacePath(mandated.slot),
        ...(mandated.lowCost === undefined ? {} : { lowCost: mandated.lowCost }),
    }));
};

export const suffixMandates = function suffixMandates(
    paths: readonly string[],
    members: readonly Omit<MandatedSurface, "slot">[],
): ResolvedMandate[] {
    return suffixTargets(paths).flatMap((target) =>
        members.map((mandated) => ({
            from: target,
            member: mandated.member,
            operand: mandated.operand,
            refusal: mandated.refusal,
            target,
        })),
    );
};

export const regionsWith = function regionsWith(effect: string): Set<string> {
    return new Set(
        Object.values(ASSESSED_FORMS).flatMap((assessment) =>
            assessment.region !== null && assessment.effect === effect ? [assessment.region] : [],
        ),
    );
};

export const mandateRoute = function mandateRoute(
    mandated: ResolvedMandate,
    paths: readonly string[],
    writable: readonly WritablePair[],
): MandateRoute {
    if (!inScope(paths, mandated.target)) {
        return "outOfScope";
    }
    return reachedByTool(mandated.target, mandated.operand, mandated.member, writable) ? "reached" : "unwritable";
};

export const namedOf = function namedOf(mandated: ResolvedMandate): string {
    return mandated.member === null ? mandated.operand : `${mandated.operand} ${mandated.member}`;
};
```