agentopology 0.1.0

package/dist/parser/index.js

@@ -0,0 +1,1985 @@
+/**
+ * AgenTopology parser.
+ *
+ * Takes the raw text of an `.at` file and produces a fully-typed
+ * {@link TopologyAST}. Individual section parsers are also exported for
+ * advanced / incremental use.
+ *
+ * ```ts
+ * import { parse } from "./parser";
+ * const ast = parse(source);
+ * ```
+ *
+ * @module
+ */
+import { stripComments, extractBlock, extractAllBlocks, parseKV, parseList, parseMultilineList, unquote, parseFields, parseOutputsBlock, dedentBlock, } from "./lexer.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Convert a kebab-case or snake_case identifier to a Title Case label. */
+function toLabel(id) {
+    return id
+        .split(/[-_]/)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ");
+}
+/**
+ * Parse an `extensions { binding-name { key: value } }` sub-block.
+ *
+ * Each named sub-block inside `extensions` becomes a key in the returned
+ * record, with its key-value pairs parsed via {@link parseFields}.
+ */
+function parseExtensionsBlock(block) {
+    const extBlock = extractBlock(block, "extensions");
+    if (!extBlock)
+        return undefined;
+    const result = {};
+    // Extract each named sub-block inside extensions
+    const re = /(?:^|\n)\s*([a-zA-Z][a-zA-Z0-9_-]*)\s*\{/gm;
+    let m;
+    while ((m = re.exec(extBlock.body)) !== null) {
+        const name = m[1];
+        const startIdx = m.index + m[0].length;
+        let depth = 1;
+        let i = startIdx;
+        while (i < extBlock.body.length && depth > 0) {
+            if (extBlock.body[i] === "{")
+                depth++;
+            else if (extBlock.body[i] === "}")
+                depth--;
+            i++;
+        }
+        if (depth === 0) {
+            const innerBody = extBlock.body.slice(startIdx, i - 1);
+            const fields = parseFields(innerBody);
+            const entry = {};
+            for (const [k, v] of Object.entries(fields)) {
+                // Try to parse booleans and numbers
+                if (v === "true")
+                    entry[k] = true;
+                else if (v === "false")
+                    entry[k] = false;
+                else if (/^\d+$/.test(v))
+                    entry[k] = parseInt(v, 10);
+                else
+                    entry[k] = unquote(v);
+            }
+            result[name] = entry;
+        }
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+// ---------------------------------------------------------------------------
+// Schema parsing
+// ---------------------------------------------------------------------------
+/** Known primitive type names for the schema type system. */
+const SCHEMA_PRIMITIVES = new Set(["string", "number", "integer", "boolean", "object"]);
+/**
+ * Parse a type expression string into a {@link SchemaType}.
+ *
+ * Supports:
+ * - Primitives: `"string"`, `"number"`, `"integer"`, `"boolean"`, `"object"`
+ * - Arrays: `"array of string"`, `"array of finding"`
+ * - Enums: `"low | medium | high"`
+ * - References: any non-primitive identifier like `"finding"`
+ */
+export function parseSchemaType(typeStr) {
+    const trimmed = typeStr.trim();
+    // Enum: contains ` | ` separator
+    if (trimmed.includes("|")) {
+        const values = trimmed.split("|").map((v) => v.trim()).filter(Boolean);
+        return { kind: "enum", values };
+    }
+    // Array: "array of <type>"
+    const arrayMatch = trimmed.match(/^array\s+of\s+(.+)$/i);
+    if (arrayMatch) {
+        return { kind: "array", itemType: parseSchemaType(arrayMatch[1]) };
+    }
+    // Primitive
+    if (SCHEMA_PRIMITIVES.has(trimmed)) {
+        return { kind: "primitive", value: trimmed };
+    }
+    // Reference to a named schema
+    return { kind: "ref", name: trimmed };
+}
+/**
+ * Parse a block body of `name: type-expression` lines into schema field definitions.
+ *
+ * Each line is parsed as a KV pair. A leading `?` on the type expression marks
+ * the field as optional.
+ */
+export function parseSchemaFields(body) {
+    const fields = [];
+    for (const line of body.split("\n")) {
+        const kv = parseKV(line);
+        if (!kv)
+            continue;
+        const [name, rawType] = kv;
+        let typeStr = rawType.trim();
+        let optional = false;
+        if (typeStr.startsWith("?")) {
+            optional = true;
+            typeStr = typeStr.slice(1).trim();
+        }
+        fields.push({
+            name,
+            type: parseSchemaType(typeStr),
+            optional,
+        });
+    }
+    return fields;
+}
+/**
+ * Parse the top-level `schemas { schema <id> { ... } ... }` block.
+ *
+ * Returns an array of named schema definitions.
+ */
+export function parseSchemas(topBody) {
+    const schemasBlock = extractBlock(topBody, "schemas");
+    if (!schemasBlock)
+        return [];
+    const schemaBlocks = extractAllBlocks(schemasBlock.body, "schema");
+    const schemas = [];
+    for (const block of schemaBlocks) {
+        if (!block.id)
+            continue;
+        schemas.push({
+            id: block.id,
+            fields: parseSchemaFields(block.body),
+        });
+    }
+    return schemas;
+}
+// ---------------------------------------------------------------------------
+// Section parsers
+// ---------------------------------------------------------------------------
+/**
+ * Parse the topology header line.
+ *
+ * Expects `topology <name> : [pattern, ...] {` somewhere in the source.
+ *
+ * @throws If no topology header is found.
+ */
+export function parseTopologyHeader(src) {
+    const m = src.match(/topology\s+(\S+)\s*:\s*\[([^\]]*)\]\s*\{/);
+    if (!m)
+        throw new Error("Could not find topology header");
+    return {
+        name: m[1],
+        patterns: m[2]
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean),
+    };
+}
+/**
+ * Parse the `meta { ... }` block.
+ *
+ * Extracts version, description, foundations, and advanced fields.
+ */
+export function parseMeta(body) {
+    const fields = parseFields(body);
+    const result = {};
+    if (fields.version)
+        result.version = unquote(fields.version);
+    if (fields.description)
+        result.description = unquote(fields.description);
+    if (fields.domain)
+        result.domain = fields.domain;
+    const foundations = parseMultilineList(body, "foundations");
+    if (foundations.length)
+        result.foundations = foundations;
+    const advanced = parseMultilineList(body, "advanced");
+    if (advanced.length)
+        result.advanced = advanced;
+    if (fields.timeout)
+        result.timeout = fields.timeout;
+    if (fields["error-handler"])
+        result.errorHandler = fields["error-handler"];
+    if (fields.durable)
+        result.durable = fields.durable === "true";
+    return result;
+}
+/**
+ * Parse the `orchestrator { ... }` block into an {@link OrchestratorNode}.
+ */
+export function parseOrchestrator(body) {
+    const fields = parseFields(body);
+    const handles = parseMultilineList(body, "handles");
+    const outputs = parseOutputsBlock(body);
+    const node = {
+        id: "orchestrator",
+        type: "orchestrator",
+        label: "Orchestrator",
+        model: fields.model ?? "unknown",
+        handles,
+    };
+    if (fields.generates)
+        node.generates = unquote(fields.generates);
+    if (outputs)
+        node.outputs = outputs;
+    return node;
+}
+/**
+ * Parse the `roles { ... }` block into a map of role name to description.
+ */
+export function parseRoles(body) {
+    const roles = {};
+    for (const line of body.split("\n")) {
+        const m = line.match(/^\s*([a-zA-Z_-]+)\s*:\s*"(.+?)"\s*$/);
+        if (m)
+            roles[m[1]] = m[2];
+    }
+    return roles;
+}
+/**
+ * Parse an `action <id> { ... }` block into an {@link ActionNode}.
+ */
+export function parseAction(id, body) {
+    const fields = parseFields(body);
+    const commands = parseMultilineList(body, "commands");
+    const node = {
+        id,
+        type: "action",
+        label: toLabel(id),
+    };
+    if (fields.kind)
+        node.kind = fields.kind;
+    if (fields.source)
+        node.source = unquote(fields.source);
+    if (fields.description)
+        node.description = unquote(fields.description);
+    if (commands.length)
+        node.commands = commands;
+    if (fields.timeout)
+        node.timeout = fields.timeout;
+    if (fields["on-fail"])
+        node.onFail = fields["on-fail"];
+    if (fields.join)
+        node.join = fields.join;
+    return node;
+}
+/**
+ * Parse an `agent <id> { ... }` block into an {@link AgentNode}.
+ *
+ * @param id    - The agent identifier from the block header.
+ * @param body  - The block body (between braces).
+ * @param roles - Role descriptions from the `roles` block, used to attach a
+ *                role description to matching agents.
+ */
+export function parseAgent(id, body, roles) {
+    const fields = parseFields(body);
+    const tools = parseMultilineList(body, "tools");
+    const skills = parseMultilineList(body, "skills");
+    const reads = parseMultilineList(body, "reads");
+    const writes = parseMultilineList(body, "writes");
+    const disallowedTools = parseMultilineList(body, "disallowed-tools");
+    const outputs = parseOutputsBlock(body);
+    const node = {
+        id,
+        type: "agent",
+        label: toLabel(id),
+    };
+    if (fields.phase)
+        node.phase = parseFloat(fields.phase);
+    if (fields.model)
+        node.model = fields.model;
+    if (fields.permissions)
+        node.permissions = fields.permissions;
+    // Extract prompt from prompt {} block (not KV pair)
+    const promptBlock = extractBlock(body, "prompt");
+    if (promptBlock) {
+        node.prompt = dedentBlock(promptBlock.body);
+    }
+    if (tools.length)
+        node.tools = tools;
+    if (skills.length)
+        node.skills = skills;
+    if (reads.length)
+        node.reads = reads;
+    if (writes.length)
+        node.writes = writes;
+    if (disallowedTools.length)
+        node.disallowedTools = disallowedTools;
+    if (fields.skip)
+        node.skip = fields.skip;
+    if (fields.behavior)
+        node.behavior = fields.behavior;
+    if (fields.invocation)
+        node.invocation = fields.invocation;
+    // Retry: support both simple number and structured block form
+    const retryBlock = extractBlock(body, "retry");
+    if (retryBlock) {
+        const rFields = parseFields(retryBlock.body);
+        const retryConfig = {
+            max: rFields.max ? parseInt(rFields.max, 10) : 1,
+        };
+        if (rFields.backoff)
+            retryConfig.backoff = rFields.backoff;
+        if (rFields.interval)
+            retryConfig.interval = rFields.interval;
+        if (rFields["max-interval"])
+            retryConfig.maxInterval = rFields["max-interval"];
+        if (rFields.jitter)
+            retryConfig.jitter = rFields.jitter === "true";
+        const nonRetryable = parseMultilineList(retryBlock.body, "non-retryable");
+        if (nonRetryable.length)
+            retryConfig.nonRetryable = nonRetryable;
+        node.retry = retryConfig;
+    }
+    else if (fields.retry) {
+        node.retry = parseInt(fields.retry, 10);
+    }
+    // Timeout
+    if (fields.timeout)
+        node.timeout = fields.timeout;
+    // On-fail
+    if (fields["on-fail"])
+        node.onFail = fields["on-fail"];
+    // Sampling parameters
+    if (fields.temperature)
+        node.temperature = parseFloat(fields.temperature);
+    if (fields["max-tokens"])
+        node.maxTokens = parseInt(fields["max-tokens"], 10);
+    if (fields["top-p"])
+        node.topP = parseFloat(fields["top-p"]);
+    if (fields["top-k"])
+        node.topK = parseInt(fields["top-k"], 10);
+    const stop = parseMultilineList(body, "stop");
+    if (stop.length)
+        node.stop = stop;
+    if (fields.seed)
+        node.seed = parseInt(fields.seed, 10);
+    // Thinking
+    if (fields.thinking)
+        node.thinking = fields.thinking;
+    if (fields["thinking-budget"])
+        node.thinkingBudget = parseInt(fields["thinking-budget"], 10);
+    // Output format
+    if (fields["output-format"])
+        node.outputFormat = fields["output-format"];
+    // Log level
+    if (fields["log-level"])
+        node.logLevel = fields["log-level"];
+    // Join semantics
+    if (fields.join)
+        node.join = fields.join;
+    // Circuit breaker
+    const cbBlock = extractBlock(body, "circuit-breaker");
+    if (cbBlock) {
+        const cbFields = parseFields(cbBlock.body);
+        const cb = {
+            threshold: cbFields.threshold ? parseInt(cbFields.threshold, 10) : 1,
+            window: cbFields.window ?? "1m",
+            cooldown: cbFields.cooldown ?? "30s",
+        };
+        node.circuitBreaker = cb;
+    }
+    // Compensation / saga
+    if (fields.compensates)
+        node.compensates = fields.compensates;
+    if (fields.isolation)
+        node.isolation = fields.isolation;
+    if (fields.background)
+        node.background = fields.background === "true";
+    const mcpServers = parseMultilineList(body, "mcp-servers");
+    if (mcpServers.length)
+        node.mcpServers = mcpServers;
+    if (outputs)
+        node.outputs = outputs;
+    // Parse scale sub-block
+    const scaleBlock = extractBlock(body, "scale");
+    if (scaleBlock) {
+        const sFields = parseFields(scaleBlock.body);
+        const scale = {
+            mode: sFields.mode ?? "auto",
+            by: sFields.by ?? "",
+            min: sFields.min ? parseInt(sFields.min, 10) : 1,
+            max: sFields.max ? parseInt(sFields.max, 10) : 1,
+            batchSize: sFields["batch-size"]
+                ? parseInt(sFields["batch-size"], 10)
+                : null,
+        };
+        node.scale = scale;
+    }
+    // Parse per-agent hooks block
+    const agentHooksBlock = extractBlock(body, "hooks");
+    if (agentHooksBlock) {
+        const agentHooks = [];
+        const hookBlocks = extractAllBlocks(agentHooksBlock.body, "hook");
+        for (const hBlock of hookBlocks) {
+            if (!hBlock.id)
+                continue;
+            const hFields = parseFields(hBlock.body);
+            const agentHook = {
+                name: hBlock.id,
+                on: hFields.on ?? "",
+                matcher: hFields.matcher ? unquote(hFields.matcher) : "",
+                run: hFields.run ? unquote(hFields.run) : "",
+                ...(hFields.type ? { type: hFields.type } : {}),
+                ...(hFields.timeout
+                    ? { timeout: parseInt(hFields.timeout, 10) }
+                    : {}),
+            };
+            // Parse extensions sub-block inside per-agent hook
+            const hookExtensions = parseExtensionsBlock(hBlock.body);
+            if (hookExtensions)
+                agentHook.extensions = hookExtensions;
+            agentHooks.push(agentHook);
+        }
+        if (agentHooks.length > 0)
+            node.hooks = agentHooks;
+    }
+    // Sandbox override
+    if (fields.sandbox) {
+        const sv = fields.sandbox;
+        if (sv === "true")
+            node.sandbox = true;
+        else if (sv === "false")
+            node.sandbox = false;
+        else
+            node.sandbox = sv;
+    }
+    // Fallback chain
+    const fallbackChain = parseMultilineList(body, "fallback-chain");
+    if (fallbackChain.length)
+        node.fallbackChain = fallbackChain;
+    // Input/output schema blocks
+    const inputSchemaBlock = extractBlock(body, "input-schema");
+    if (inputSchemaBlock) {
+        node.inputSchema = parseSchemaFields(inputSchemaBlock.body);
+    }
+    const outputSchemaBlock = extractBlock(body, "output-schema");
+    if (outputSchemaBlock) {
+        node.outputSchema = parseSchemaFields(outputSchemaBlock.body);
+    }
+    // Artifact lineage: produces and consumes
+    const produces = parseMultilineList(body, "produces");
+    if (produces.length)
+        node.produces = produces;
+    const consumes = parseMultilineList(body, "consumes");
+    if (consumes.length)
+        node.consumes = consumes;
+    // Prompt variants (A/B testing)
+    const variantsBlock = extractBlock(body, "variants");
+    if (variantsBlock) {
+        const variants = [];
+        const variantBlocks = extractAllBlocks(variantsBlock.body, "variant");
+        for (const vBlock of variantBlocks) {
+            if (!vBlock.id)
+                continue;
+            const vFields = parseFields(vBlock.body);
+            const variant = {
+                id: vBlock.id,
+                weight: vFields.weight ? parseFloat(vFields.weight) : 0,
+            };
+            const vPromptBlock = extractBlock(vBlock.body, "prompt");
+            if (vPromptBlock) {
+                variant.prompt = dedentBlock(vPromptBlock.body);
+            }
+            if (vFields.temperature)
+                variant.temperature = parseFloat(vFields.temperature);
+            if (vFields.model)
+                variant.model = vFields.model;
+            variants.push(variant);
+        }
+        if (variants.length > 0)
+            node.variants = variants;
+    }
+    // Rate limit
+    if (fields["rate-limit"])
+        node.rateLimit = fields["rate-limit"];
+    // New fields: description, max-turns, extensions
+    if (fields.description)
+        node.description = unquote(fields.description);
+    if (fields["max-turns"])
+        node.maxTurns = parseInt(fields["max-turns"], 10);
+    const extensions = parseExtensionsBlock(body);
+    if (extensions)
+        node.extensions = extensions;
+    // Attach role description if available.
+    // Prefer exact match, then longest prefix match.
+    const exactRole = roles[id];
+    if (exactRole) {
+        node.role = exactRole;
+    }
+    else {
+        const prefixMatches = Object.keys(roles)
+            .filter((r) => id.startsWith(r))
+            .sort((a, b) => b.length - a.length);
+        if (prefixMatches.length > 0)
+            node.role = roles[prefixMatches[0]];
+    }
+    return node;
+}
+/**
+ * Parse a `gate <id> { ... }` block into a {@link GateNode}.
+ */
+export function parseGate(id, body) {
+    const fields = parseFields(body);
+    const checks = parseMultilineList(body, "checks");
+    const node = {
+        id,
+        type: "gate",
+        label: toLabel(id),
+    };
+    if (fields.after)
+        node.after = fields.after;
+    if (fields.before)
+        node.before = fields.before;
+    if (fields.run)
+        node.run = unquote(fields.run);
+    if (checks.length)
+        node.checks = checks;
+    if (fields.retry)
+        node.retry = parseInt(fields.retry, 10);
+    if (fields["on-fail"])
+        node.onFail = fields["on-fail"];
+    if (fields.behavior)
+        node.behavior = fields.behavior;
+    if (fields.timeout)
+        node.timeout = fields.timeout;
+    const extensions = parseExtensionsBlock(body);
+    if (extensions)
+        node.extensions = extensions;
+    return node;
+}
+/**
+ * Parse a `human <id> { ... }` block into a {@link HumanNode}.
+ */
+export function parseHuman(id, body) {
+    const fields = parseFields(body);
+    const node = {
+        id,
+        type: "human",
+        label: toLabel(id),
+    };
+    if (fields.description)
+        node.description = unquote(fields.description);
+    if (fields.timeout)
+        node.timeout = fields.timeout;
+    if (fields["on-timeout"])
+        node.onTimeout = fields["on-timeout"];
+    return node;
+}
+/**
+ * Parse a `group <id> { ... }` block into a {@link GroupNode}.
+ */
+export function parseGroup(id, body) {
+    const fields = parseFields(body);
+    const members = parseList(fields.members ?? "");
+    const node = {
+        id,
+        type: "group",
+        label: toLabel(id),
+        members,
+    };
+    if (fields["speaker-selection"])
+        node.speakerSelection = fields["speaker-selection"];
+    if (fields["max-rounds"])
+        node.maxRounds = parseInt(fields["max-rounds"], 10);
+    if (fields.termination)
+        node.termination = unquote(fields.termination);
+    if (fields.description)
+        node.description = unquote(fields.description);
+    if (fields.timeout)
+        node.timeout = fields.timeout;
+    return node;
+}
+/**
+ * Parse the `flow { ... }` block into an array of {@link EdgeDef}.
+ *
+ * Supports chain syntax (`a -> b -> c`), fan-out (`a -> [b, c]`),
+ * error edges (`-x->`, `-x[type]->`), and edge annotations
+ * (`[when condition, max N, tolerance: N, race, wait 30s]`).
+ */
+export function parseFlow(body, _edgeAttributeErrors) {
+    const edges = [];
+    for (const line of body.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let condition = null;
+        let maxIterations = null;
+        let per = null;
+        let tolerance;
+        let race;
+        let wait;
+        let weight;
+        let reflection;
+        let flowPart = trimmed;
+        // Match annotation at end of line: [when ..., max N, per agent-id, tolerance: N, race, wait 30s, reflection]
+        // Must start with "when", "max", "per", "tolerance", "race", "wait", "join", "weight", or "reflection" to avoid matching fan-out lists.
+        const bracketMatch = trimmed.match(/\[(when\s+.+?|max\s+\d+.*?|per\s+\S+.*?|tolerance\s*:.+?|race.*?|wait\s+\S+.*?|join\s+\S+.*?|weight\s+\S+.*?|reflection.*?)\]\s*$/);
+        if (bracketMatch) {
+            flowPart = trimmed.slice(0, bracketMatch.index).trim();
+            const annotation = bracketMatch[1];
+            // V12: Detect wrong attribute order — "max" before "when"
+            const maxIdx = annotation.search(/\bmax\s+\d+/);
+            const whenIdx = annotation.search(/\bwhen\s+/);
+            if (maxIdx !== -1 && whenIdx !== -1 && maxIdx < whenIdx && _edgeAttributeErrors) {
+                _edgeAttributeErrors.push({
+                    rule: "V12",
+                    level: "error",
+                    message: `Edge annotation has wrong attribute order: "max" before "when" — expected [when ..., max N] (line: ${trimmed})`,
+                });
+            }
+            const whenMatch = annotation.match(/when\s+(.+?)(?:,\s*(?:max|per|tolerance|race|wait|weight|reflection)|$)/);
+            if (whenMatch)
+                condition = whenMatch[1].trim();
+            const maxMatch = annotation.match(/max\s+(\d+)/);
+            if (maxMatch)
+                maxIterations = parseInt(maxMatch[1], 10);
+            const perMatch = annotation.match(/per\s+(\S+)/);
+            if (perMatch)
+                per = perMatch[1].replace(/,\s*$/, "");
+            // tolerance: N or tolerance: 33%
+            const toleranceMatch = annotation.match(/tolerance\s*:\s*(\d+%?)/);
+            if (toleranceMatch) {
+                const tolVal = toleranceMatch[1];
+                tolerance = tolVal.endsWith("%") ? tolVal : parseInt(tolVal, 10);
+            }
+            // race
+            if (/\brace\b/.test(annotation)) {
+                race = true;
+            }
+            // wait 30s
+            const waitMatch = annotation.match(/wait\s+(\d+[smhd])/);
+            if (waitMatch) {
+                wait = waitMatch[1];
+            }
+            // weight 0.7
+            const weightMatch = annotation.match(/weight\s+(\d+(?:\.\d+)?)/);
+            if (weightMatch) {
+                weight = parseFloat(weightMatch[1]);
+            }
+            // reflection
+            if (/\breflection\b/.test(annotation)) {
+                reflection = true;
+            }
+        }
+        // Split the flow part into segments, handling error edge arrows.
+        // We need to split on both -> and -x-> / -x[type]->.
+        // Strategy: use regex to split on arrow patterns, tracking which type each is.
+        const segments = [];
+        const arrowPattern = /-x\[([^\]]+)\]->|-x->|->/g;
+        let lastIndex = 0;
+        let arrowMatch;
+        const arrowTypes = [];
+        // Reset lastIndex
+        arrowPattern.lastIndex = 0;
+        while ((arrowMatch = arrowPattern.exec(flowPart)) !== null) {
+            const before = flowPart.slice(lastIndex, arrowMatch.index).trim();
+            if (before) {
+                segments.push({ text: before, isError: false });
+            }
+            if (arrowMatch[0].startsWith("-x")) {
+                // Error edge
+                if (arrowMatch[1]) {
+                    // -x[type]->
+                    arrowTypes.push({ isError: true, errorType: arrowMatch[1] });
+                }
+                else {
+                    // -x->
+                    arrowTypes.push({ isError: true });
+                }
+            }
+            else {
+                // Normal ->
+                arrowTypes.push({ isError: false });
+            }
+            lastIndex = arrowMatch.index + arrowMatch[0].length;
+        }
+        // Remaining text after last arrow
+        const remaining = flowPart.slice(lastIndex).trim();
+        if (remaining) {
+            segments.push({ text: remaining, isError: false });
+        }
+        // Now segments[i] and arrowTypes[i] give us: segments[i] --arrowTypes[i]--> segments[i+1]
+        for (let i = 0; i < segments.length - 1; i++) {
+            const from = segments[i].text;
+            const to = segments[i + 1].text;
+            const arrow = arrowTypes[i];
+            const isLastSegment = i === segments.length - 2;
+            // Check for fan-out: [a, b, c]
+            const fanOutMatch = to.match(/^\[([^\]]+)\]$/);
+            // Build base edge properties
+            const baseEdge = {
+                condition: isLastSegment ? condition : null,
+                maxIterations: isLastSegment ? maxIterations : null,
+                per: isLastSegment ? per : null,
+            };
+            if (arrow.isError) {
+                baseEdge.isError = true;
+                if (arrow.errorType)
+                    baseEdge.errorType = arrow.errorType;
+            }
+            if (isLastSegment && tolerance !== undefined)
+                baseEdge.tolerance = tolerance;
+            if (isLastSegment && race)
+                baseEdge.race = true;
+            if (isLastSegment && wait)
+                baseEdge.wait = wait;
+            if (isLastSegment && weight !== undefined)
+                baseEdge.weight = weight;
+            if (isLastSegment && reflection)
+                baseEdge.reflection = true;
+            if (fanOutMatch) {
+                const targets = fanOutMatch[1].split(",").map((s) => s.trim());
+                for (const target of targets) {
+                    edges.push({
+                        from,
+                        to: target,
+                        condition: baseEdge.condition ?? null,
+                        maxIterations: baseEdge.maxIterations ?? null,
+                        per: baseEdge.per ?? null,
+                        ...(baseEdge.isError ? { isError: true } : {}),
+                        ...(baseEdge.errorType ? { errorType: baseEdge.errorType } : {}),
+                        ...(baseEdge.tolerance !== undefined ? { tolerance: baseEdge.tolerance } : {}),
+                        ...(baseEdge.race ? { race: true } : {}),
+                        ...(baseEdge.wait ? { wait: baseEdge.wait } : {}),
+                        ...(baseEdge.weight !== undefined ? { weight: baseEdge.weight } : {}),
+                        ...(baseEdge.reflection ? { reflection: true } : {}),
+                    });
+                }
+            }
+            else {
+                edges.push({
+                    from,
+                    to,
+                    condition: baseEdge.condition ?? null,
+                    maxIterations: baseEdge.maxIterations ?? null,
+                    per: baseEdge.per ?? null,
+                    ...(baseEdge.isError ? { isError: true } : {}),
+                    ...(baseEdge.errorType ? { errorType: baseEdge.errorType } : {}),
+                    ...(baseEdge.tolerance !== undefined ? { tolerance: baseEdge.tolerance } : {}),
+                    ...(baseEdge.race ? { race: true } : {}),
+                    ...(baseEdge.wait ? { wait: baseEdge.wait } : {}),
+                    ...(baseEdge.weight !== undefined ? { weight: baseEdge.weight } : {}),
+                    ...(baseEdge.reflection ? { reflection: true } : {}),
+                });
+            }
+        }
+    }
+    return edges;
+}
+/**
+ * Parse the `depth { ... }` block.
+ */
+export function parseDepth(body) {
+    const factors = parseMultilineList(body, "factors");
+    const levels = [];
+    const levelRe = /level\s+(\d+)\s+"([^"]+)"\s*\{([^}]*)\}/g;
+    let m;
+    while ((m = levelRe.exec(body)) !== null) {
+        const omit = parseMultilineList(m[3], "omit");
+        levels.push({
+            level: parseInt(m[1], 10),
+            label: m[2],
+            omit,
+        });
+    }
+    return { factors, levels };
+}
+/**
+ * Parse the `memory { ... }` block.
+ *
+ * Extracts known sub-blocks (domains, references, external-docs, metrics,
+ * workspace) and returns them as a nested record.
+ */
+export function parseMemory(body, _unknownSubBlockWarnings) {
+    const memory = {};
+    const knownSubs = [
+        "domains",
+        "references",
+        "external-docs",
+        "metrics",
+        "workspace",
+    ];
+    const knownSubsSet = new Set(knownSubs);
+    for (const name of knownSubs) {
+        const block = extractBlock(body, name);
+        if (!block)
+            continue;
+        const fields = parseFields(block.body);
+        const entry = {};
+        for (const [k, v] of Object.entries(fields)) {
+            entry[k] = v.startsWith("[") ? parseList(v) : unquote(v);
+        }
+        // Check for multiline lists
+        for (const key of ["blueprints", "files", "structure"]) {
+            const list = parseMultilineList(block.body, key);
+            if (list.length)
+                entry[key] = list;
+        }
+        memory[name] = entry;
+    }
+    // Detect unknown sub-blocks
+    if (_unknownSubBlockWarnings) {
+        const subBlockRe = /(?:^|\n)\s*([a-zA-Z][a-zA-Z0-9_-]*)\s*\{/gm;
+        let m;
+        while ((m = subBlockRe.exec(body)) !== null) {
+            const name = m[1];
+            if (!knownSubsSet.has(name)) {
+                _unknownSubBlockWarnings.push({
+                    rule: "V24",
+                    level: "warning",
+                    message: `Unknown sub-block "${name}" in memory block — known sub-blocks are: ${knownSubs.join(", ")}`,
+                });
+            }
+        }
+    }
+    return memory;
+}
+/**
+ * Parse the `batch { ... }` block.
+ */
+export function parseBatch(body) {
+    const fields = parseFields(body);
+    const result = {};
+    if (fields.parallel)
+        result.parallel = fields.parallel === "true";
+    if (fields.per)
+        result.per = fields.per;
+    if (fields.workspace)
+        result.workspace = unquote(fields.workspace);
+    // Parse conflicts sub-block
+    const conflictsBlock = extractBlock(body, "conflicts");
+    if (conflictsBlock) {
+        const cFields = parseFields(conflictsBlock.body);
+        const detect = parseMultilineList(conflictsBlock.body, "detect");
+        result.conflicts = {
+            detect,
+            resolve: cFields.resolve ?? null,
+        };
+    }
+    return result;
+}
+/**
+ * Parse the `environments { ... }` block.
+ *
+ * Extracts named environment sub-blocks. Handles any environment name,
+ * not just "staging" and "production".
+ */
+export function parseEnvironments(body) {
+    const envs = {};
+    // Extract all named sub-blocks generically
+    const re = /(?:^|\n)\s*([a-zA-Z][a-zA-Z0-9_-]*)\s*\{/gm;
+    let m;
+    while ((m = re.exec(body)) !== null) {
+        const envName = m[1];
+        const startIdx = m.index + m[0].length;
+        let depth = 1;
+        let i = startIdx;
+        while (i < body.length && depth > 0) {
+            if (body[i] === "{")
+                depth++;
+            else if (body[i] === "}")
+                depth--;
+            i++;
+        }
+        if (depth === 0) {
+            const innerBody = body.slice(startIdx, i - 1);
+            const fields = parseFields(innerBody);
+            const env = {};
+            for (const [k, v] of Object.entries(fields)) {
+                env[k] = unquote(v);
+            }
+            envs[envName] = env;
+        }
+    }
+    return envs;
+}
+/**
+ * Parse the `triggers { ... }` block.
+ */
+export function parseTriggers(body) {
+    const triggers = [];
+    const cmdBlocks = extractAllBlocks(body, "command");
+    for (const block of cmdBlocks) {
+        if (!block.id)
+            continue;
+        const fields = parseFields(block.body);
+        const trigger = {
+            name: block.id,
+            pattern: fields.pattern ? unquote(fields.pattern) : "",
+        };
+        if (fields.argument)
+            trigger.argument = fields.argument;
+        triggers.push(trigger);
+    }
+    return triggers;
+}
+/**
+ * Parse the global `hooks { ... }` block.
+ */
+export function parseHooks(body) {
+    const hooks = [];
+    const hookBlocks = extractAllBlocks(body, "hook");
+    for (const block of hookBlocks) {
+        if (!block.id)
+            continue;
+        const fields = parseFields(block.body);
+        const hook = {
+            name: block.id,
+            on: fields.on ?? "",
+            matcher: fields.matcher ? unquote(fields.matcher) : "",
+            run: fields.run ? unquote(fields.run) : "",
+            ...(fields.type ? { type: fields.type } : {}),
+            ...(fields.timeout
+                ? { timeout: parseInt(fields.timeout, 10) }
+                : {}),
+        };
+        // Parse extensions sub-block inside hook
+        const extensions = parseExtensionsBlock(block.body);
+        if (extensions)
+            hook.extensions = extensions;
+        hooks.push(hook);
+    }
+    return hooks;
+}
+/**
+ * Parse the `settings { ... }` block.
+ */
+export function parseSettings(body) {
+    const result = {};
+    for (const key of ["allow", "deny", "ask"]) {
+        const list = parseMultilineList(body, key);
+        result[key] = list;
+    }
+    // Sandbox setting
+    const fields = parseFields(body);
+    if (fields.sandbox) {
+        const sv = fields.sandbox;
+        if (sv === "true")
+            result.sandbox = true;
+        else if (sv === "false")
+            result.sandbox = false;
+        else
+            result.sandbox = sv;
+    }
+    // Fallback chain
+    const fallbackChain = parseMultilineList(body, "fallback-chain");
+    if (fallbackChain.length)
+        result.fallbackChain = fallbackChain;
+    return result;
+}
+/**
+ * Parse the `metering { ... }` block.
+ */
+export function parseMetering(body) {
+    const fields = parseFields(body);
+    const track = parseMultilineList(body, "track");
+    const per = parseMultilineList(body, "per");
+    if (track.length === 0 && !fields.output)
+        return null;
+    return {
+        track,
+        per,
+        output: fields.output ? unquote(fields.output) : "",
+        format: fields.format ?? "",
+        pricing: fields.pricing ?? "",
+    };
+}
+/**
+ * Parse the `mcp-servers { ... }` block.
+ */
+export function parseMcpServers(body) {
+    const servers = {};
+    const re = /(?:^|\n)\s*([a-zA-Z][a-zA-Z0-9_-]*)\s*\{/gm;
+    let m;
+    while ((m = re.exec(body)) !== null) {
+        const name = m[1];
+        const startIdx = m.index + m[0].length;
+        let depth = 1;
+        let i = startIdx;
+        while (i < body.length && depth > 0) {
+            if (body[i] === "{")
+                depth++;
+            else if (body[i] === "}")
+                depth--;
+            i++;
+        }
+        if (depth === 0) {
+            const innerBody = body.slice(startIdx, i - 1);
+            const fields = parseFields(innerBody);
+            const server = {};
+            for (const [k, v] of Object.entries(fields)) {
+                server[k] = unquote(v);
+            }
+            const args = parseMultilineList(innerBody, "args");
+            if (args.length)
+                server.args = args;
+            // Parse env sub-block (key-value pairs for environment variables)
+            const envBlock = extractBlock(innerBody, "env");
+            if (envBlock) {
+                const envVars = {};
+                for (const line of envBlock.body.split("\n")) {
+                    const kv = parseKV(line);
+                    if (kv) {
+                        envVars[kv[0]] = unquote(kv[1]);
+                    }
+                }
+                if (Object.keys(envVars).length > 0) {
+                    server.env = envVars;
+                }
+            }
+            servers[name] = server;
+        }
+    }
+    return servers;
+}
+/**
+ * Parse `skill <id> { ... }` blocks.
+ */
+export function parseSkillBlocks(topBody) {
+    const skillBlocks = extractAllBlocks(topBody, "skill");
+    const skillDefs = [];
+    for (const block of skillBlocks) {
+        if (!block.id)
+            continue;
+        const sFields = parseFields(block.body);
+        const sd = {
+            id: block.id,
+            description: sFields.description ? unquote(sFields.description) : "",
+        };
+        const scripts = parseMultilineList(block.body, "scripts");
+        const domains = parseMultilineList(block.body, "domains");
+        const references = parseMultilineList(block.body, "references");
+        if (scripts.length)
+            sd.scripts = scripts;
+        if (domains.length)
+            sd.domains = domains;
+        if (references.length)
+            sd.references = references;
+        if (sFields.prompt)
+            sd.prompt = unquote(sFields.prompt);
+        // New skill fields
+        if (sFields["disable-model-invocation"]) {
+            sd.disableModelInvocation = sFields["disable-model-invocation"] === "true";
+        }
+        if (sFields["user-invocable"]) {
+            sd.userInvocable = sFields["user-invocable"] === "true";
+        }
+        if (sFields.context)
+            sd.context = sFields.context;
+        if (sFields.agent)
+            sd.agent = sFields.agent;
+        const allowedTools = parseMultilineList(block.body, "allowed-tools");
+        if (allowedTools.length)
+            sd.allowedTools = allowedTools;
+        const skillExtensions = parseExtensionsBlock(block.body);
+        if (skillExtensions)
+            sd.extensions = skillExtensions;
+        skillDefs.push(sd);
+    }
+    return skillDefs;
+}
+/**
+ * Parse the `context { ... }` block.
+ *
+ * Returns context file configuration with optional file path and includes list.
+ */
+export function parseContext(body) {
+    const fields = parseFields(body);
+    const result = {};
+    if (fields.file)
+        result.file = unquote(fields.file);
+    const includes = parseMultilineList(body, "includes");
+    if (includes.length)
+        result.includes = includes;
+    return result;
+}
+/**
+ * Parse the `env { ... }` block.
+ *
+ * Returns a record of environment variable key-value pairs. Values may be
+ * plain strings (backward compatible) or {@link SensitiveValue} objects when
+ * the `sensitive` or `secret` modifier is used.
+ */
+export function parseEnv(body) {
+    const result = {};
+    for (const line of body.split("\n")) {
+        const kv = parseKV(line);
+        if (kv) {
+            const rawValue = kv[1].trim();
+            // Check for `secret "uri"` modifier
+            if (rawValue.startsWith("secret ")) {
+                const uriPart = rawValue.slice("secret ".length).trim();
+                const uri = unquote(uriPart);
+                const schemeMatch = uri.match(/^([a-zA-Z][a-zA-Z0-9]*):\/\//);
+                const scheme = schemeMatch ? schemeMatch[1] : "";
+                const secretRef = { scheme, uri };
+                result[kv[0]] = {
+                    value: uri,
+                    sensitive: true,
+                    secretRef,
+                };
+            }
+            // Check for `encrypted` modifier
+            else if (rawValue.startsWith("encrypted ")) {
+                const innerValue = rawValue.slice("encrypted ".length).trim();
+                const unquoted = unquote(innerValue);
+                const sv = {
+                    value: unquoted,
+                    sensitive: true,
+                    encrypted: true,
+                };
+                // Parse SOPS envelope: ENC[METHOD,data:...]
+                const sopsMatch = unquoted.match(/^ENC\[([A-Z0-9_]+),data:/);
+                if (sopsMatch) {
+                    sv.sopsMethod = sopsMatch[1];
+                }
+                result[kv[0]] = sv;
+            }
+            // Check for `sensitive` modifier
+            else if (rawValue.startsWith("sensitive ")) {
+                const innerValue = rawValue.slice("sensitive ".length).trim();
+                result[kv[0]] = {
+                    value: unquote(innerValue),
+                    sensitive: true,
+                };
+            }
+            // Plain string (backward compatible)
+            else {
+                result[kv[0]] = unquote(rawValue);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Parse the `providers { ... }` block.
+ *
+ * Each named sub-block declares a provider with api-key, base-url, models,
+ * default, and any extra fields.
+ */
+export function parseProviders(body) {
+    const providers = [];
+    // Extract each named sub-block inside providers
+    const re = /(?:^|\n)\s*([a-zA-Z][a-zA-Z0-9_-]*)\s*\{/gm;
+    let m;
+    while ((m = re.exec(body)) !== null) {
+        const name = m[1];
+        const startIdx = m.index + m[0].length;
+        let depth = 1;
+        let i = startIdx;
+        while (i < body.length && depth > 0) {
+            if (body[i] === "{")
+                depth++;
+            else if (body[i] === "}")
+                depth--;
+            i++;
+        }
+        // Advance regex past the closing brace so we don't match sub-blocks
+        re.lastIndex = i;
+        if (depth === 0) {
+            const innerBody = body.slice(startIdx, i - 1);
+            const fields = parseFields(innerBody);
+            // Parse models list
+            const models = parseMultilineList(innerBody, "models");
+            // Collect known fields
+            const knownKeys = new Set(["api-key", "base-url", "models", "default"]);
+            const extra = {};
+            for (const [k, v] of Object.entries(fields)) {
+                if (!knownKeys.has(k)) {
+                    if (v === "true")
+                        extra[k] = true;
+                    else if (v === "false")
+                        extra[k] = false;
+                    else if (/^\d+$/.test(v))
+                        extra[k] = parseInt(v, 10);
+                    else
+                        extra[k] = unquote(v);
+                }
+            }
+            const provider = {
+                name,
+                models,
+                extra,
+            };
+            if (fields["api-key"])
+                provider.apiKey = unquote(fields["api-key"]);
+            if (fields["base-url"])
+                provider.baseUrl = unquote(fields["base-url"]);
+            if (fields["default"])
+                provider.default = fields["default"] === "true";
+            // Parse auth sub-block
+            const authBlock = extractBlock(innerBody, "auth");
+            if (authBlock) {
+                const aFields = parseFields(authBlock.body);
+                const auth = {
+                    type: aFields.type ?? "api-key",
+                };
+                if (aFields.issuer)
+                    auth.issuer = unquote(aFields.issuer);
+                if (aFields.audience)
+                    auth.audience = unquote(aFields.audience);
+                if (aFields["token-url"])
+                    auth.tokenUrl = unquote(aFields["token-url"]);
+                if (aFields["client-id"])
+                    auth.clientId = unquote(aFields["client-id"]);
+                const scopes = parseMultilineList(authBlock.body, "scopes");
+                if (scopes.length)
+                    auth.scopes = scopes;
+                provider.auth = auth;
+            }
+            providers.push(provider);
+        }
+    }
+    return providers;
+}
+/**
+ * Parse the `schedule { ... }` block.
+ *
+ * Extracts `job <id> { ... }` sub-blocks within the schedule section.
+ */
+export function parseSchedule(body) {
+    const jobs = [];
+    const jobBlocks = extractAllBlocks(body, "job");
+    for (const block of jobBlocks) {
+        if (!block.id)
+            continue;
+        const fields = parseFields(block.body);
+        const job = {
+            id: block.id,
+            enabled: true,
+        };
+        if (fields.cron)
+            job.cron = unquote(fields.cron);
+        if (fields.every)
+            job.every = unquote(fields.every);
+        if (fields.agent)
+            job.agent = fields.agent;
+        if (fields.action)
+            job.action = fields.action;
+        if (fields.enabled)
+            job.enabled = fields.enabled !== "false";
+        jobs.push(job);
+    }
+    return jobs;
+}
+/**
+ * Parse the `interfaces { ... }` block.
+ *
+ * Each named sub-block declares an interface with a `type` field and arbitrary
+ * configuration. Follows the same named-sub-block pattern as {@link parseMcpServers}.
+ */
+export function parseInterfaces(body) {
+    const interfaces = [];
+    const re = /(?:^|\n)\s*([a-zA-Z][a-zA-Z0-9_-]*)\s*\{/gm;
+    let m;
+    while ((m = re.exec(body)) !== null) {
+        const name = m[1];
+        const startIdx = m.index + m[0].length;
+        let depth = 1;
+        let i = startIdx;
+        while (i < body.length && depth > 0) {
+            if (body[i] === "{")
+                depth++;
+            else if (body[i] === "}")
+                depth--;
+            i++;
+        }
+        if (depth === 0) {
+            const innerBody = body.slice(startIdx, i - 1);
+            const fields = parseFields(innerBody);
+            const config = {};
+            for (const [k, v] of Object.entries(fields)) {
+                if (k === "type")
+                    continue;
+                if (v === "true")
+                    config[k] = true;
+                else if (v === "false")
+                    config[k] = false;
+                else if (/^\d+$/.test(v))
+                    config[k] = parseInt(v, 10);
+                else
+                    config[k] = unquote(v);
+            }
+            const iface = {
+                id: name,
+                config,
+            };
+            if (fields.type)
+                iface.type = fields.type;
+            interfaces.push(iface);
+        }
+    }
+    return interfaces;
+}
+/**
+ * Parse the top-level `tools { ... }` block containing `tool <id> { ... }` sub-blocks.
+ */
+export function parseToolsBlock(topBody) {
+    const toolsBlock = extractBlock(topBody, "tools");
+    const toolDefs = [];
+    if (!toolsBlock)
+        return toolDefs;
+    const toolBlocks = extractAllBlocks(toolsBlock.body, "tool");
+    for (const block of toolBlocks) {
+        if (!block.id)
+            continue;
+        const tFields = parseFields(block.body);
+        const td = {
+            id: block.id,
+            script: tFields.script ? unquote(tFields.script) : "",
+            description: tFields.description ? unquote(tFields.description) : "",
+        };
+        const args = parseMultilineList(block.body, "args");
+        if (args.length)
+            td.args = args;
+        if (tFields.lang)
+            td.lang = tFields.lang;
+        toolDefs.push(td);
+    }
+    return toolDefs;
+}
+/**
+ * Parse the `defaults { ... }` block.
+ *
+ * Extracts topology-level default values for sampling parameters and
+ * shared agent configuration.
+ */
+export function parseDefaults(body) {
+    const fields = parseFields(body);
+    const defaults = {};
+    let hasFields = false;
+    if (fields.temperature) {
+        defaults.temperature = parseFloat(fields.temperature);
+        hasFields = true;
+    }
+    if (fields["max-tokens"]) {
+        defaults.maxTokens = parseInt(fields["max-tokens"], 10);
+        hasFields = true;
+    }
+    if (fields["top-p"]) {
+        defaults.topP = parseFloat(fields["top-p"]);
+        hasFields = true;
+    }
+    if (fields["top-k"]) {
+        defaults.topK = parseInt(fields["top-k"], 10);
+        hasFields = true;
+    }
+    const stop = parseMultilineList(body, "stop");
+    if (stop.length) {
+        defaults.stop = stop;
+        hasFields = true;
+    }
+    if (fields.seed) {
+        defaults.seed = parseInt(fields.seed, 10);
+        hasFields = true;
+    }
+    if (fields.thinking) {
+        defaults.thinking = fields.thinking;
+        hasFields = true;
+    }
+    if (fields["thinking-budget"]) {
+        defaults.thinkingBudget = parseInt(fields["thinking-budget"], 10);
+        hasFields = true;
+    }
+    if (fields["output-format"]) {
+        defaults.outputFormat = fields["output-format"];
+        hasFields = true;
+    }
+    if (fields.timeout) {
+        defaults.timeout = fields.timeout;
+        hasFields = true;
+    }
+    if (fields["log-level"]) {
+        defaults.logLevel = fields["log-level"];
+        hasFields = true;
+    }
+    return hasFields ? defaults : null;
+}
+/**
+ * Parse the `observability { ... }` block.
+ *
+ * Extracts simple KV fields plus `capture { ... }` and `spans { ... }`
+ * sub-blocks. Returns an {@link ObservabilityDef} with defaults applied
+ * for any omitted fields.
+ */
+export function parseObservability(body) {
+    const fields = parseFields(body);
+    // Parse simple KV fields with defaults
+    const enabled = fields.enabled !== undefined ? fields.enabled === "true" : true;
+    const level = fields.level ?? "info";
+    const exporter = fields.exporter ?? "otlp";
+    const endpoint = fields.endpoint ? unquote(fields.endpoint) : undefined;
+    const service = fields.service ? unquote(fields.service) : undefined;
+    const sampleRate = fields["sample-rate"] !== undefined
+        ? parseFloat(fields["sample-rate"])
+        : 1.0;
+    // Parse capture sub-block with defaults (all false)
+    const captureBlock = extractBlock(body, "capture");
+    const captureFields = captureBlock ? parseFields(captureBlock.body) : {};
+    const capture = {
+        prompts: captureFields.prompts === "true",
+        completions: captureFields.completions === "true",
+        toolArgs: (captureFields["tool-args"] ?? captureFields.toolArgs) === "true",
+        toolResults: (captureFields["tool-results"] ?? captureFields.toolResults) === "true",
+    };
+    // Parse spans sub-block with defaults (agents/tools/gates: true, memory: false)
+    const spansBlock = extractBlock(body, "spans");
+    const spansFields = spansBlock ? parseFields(spansBlock.body) : {};
+    const spans = {
+        agents: spansFields.agents !== undefined ? spansFields.agents === "true" : true,
+        tools: spansFields.tools !== undefined ? spansFields.tools === "true" : true,
+        gates: spansFields.gates !== undefined ? spansFields.gates === "true" : true,
+        memory: spansFields.memory !== undefined ? spansFields.memory === "true" : false,
+    };
+    const def = {
+        enabled,
+        level,
+        exporter,
+        sampleRate,
+        capture,
+        spans,
+    };
+    if (endpoint !== undefined)
+        def.endpoint = endpoint;
+    if (service !== undefined)
+        def.service = service;
+    return def;
+}
+/**
+ * Parse the `checkpoint { ... }` block.
+ *
+ * Extracts KV fields plus an optional `replay { ... }` sub-block.
+ * Returns a {@link CheckpointDef} with parsed connection supporting
+ * the `secret "uri"` modifier.
+ */
+export function parseCheckpoint(body) {
+    const fields = parseFields(body);
+    const def = {
+        backend: fields.backend ?? "memory",
+        strategy: fields.strategy ?? "every-node",
+    };
+    // Connection: may use `secret "uri"` modifier
+    if (fields.connection) {
+        const rawConn = fields.connection.trim();
+        if (rawConn.startsWith("secret ")) {
+            const uri = unquote(rawConn.slice("secret ".length).trim());
+            def.connection = uri;
+        }
+        else {
+            def.connection = unquote(rawConn);
+        }
+    }
+    if (fields.ttl)
+        def.ttl = fields.ttl;
+    // Parse replay sub-block
+    const replayBlock = extractBlock(body, "replay");
+    if (replayBlock) {
+        const rFields = parseFields(replayBlock.body);
+        const replay = {
+            enabled: rFields.enabled === "true",
+        };
+        if (rFields["max-history"]) {
+            replay.maxHistory = parseInt(rFields["max-history"], 10);
+        }
+        if (rFields.branch) {
+            replay.branch = rFields.branch === "true";
+        }
+        def.replay = replay;
+    }
+    return def;
+}
+/**
+ * Parse the top-level `artifacts { artifact <id> { ... } ... }` block.
+ *
+ * Returns an array of artifact definitions with their dependencies.
+ */
+export function parseArtifacts(topBody) {
+    const artifactsBlock = extractBlock(topBody, "artifacts");
+    if (!artifactsBlock)
+        return [];
+    const artifactBlocks = extractAllBlocks(artifactsBlock.body, "artifact");
+    const artifacts = [];
+    for (const block of artifactBlocks) {
+        if (!block.id)
+            continue;
+        const fields = parseFields(block.body);
+        const artifact = {
+            id: block.id,
+            type: fields.type ?? "unknown",
+        };
+        if (fields.path)
+            artifact.path = unquote(fields.path);
+        if (fields.retention)
+            artifact.retention = fields.retention;
+        const dependsOn = parseMultilineList(block.body, "depends-on");
+        if (dependsOn.length)
+            artifact.dependsOn = dependsOn;
+        artifacts.push(artifact);
+    }
+    return artifacts;
+}
+// ---------------------------------------------------------------------------
+// Main parser
+// ---------------------------------------------------------------------------
+/**
+ * Parse an AgenTopology `.at` source string into a complete {@link TopologyAST}.
+ *
+ * @param source - The raw `.at` file content.
+ * @returns The fully-parsed AST.
+ * @throws If the topology header or body cannot be extracted.
+ */
+/**
+ * Build a source map that records the line number (1-based) where each named
+ * block starts in the raw source. Scans for `agent <id> {`, `gate <id> {`,
+ * `action <id> {`, and `orchestrator {` patterns.
+ */
+function buildSourceMap(rawSource) {
+    const sourceMap = {};
+    const lines = rawSource.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // Match: agent <id> {, action <id> {, gate <id> {, human <id> {
+        const namedMatch = line.match(/^\s*(?:agent|action|gate|human|group)\s+([a-zA-Z][a-zA-Z0-9_-]*)\s*(?:\{|[^{]*\{)/);
+        if (namedMatch) {
+            sourceMap[namedMatch[1]] = i + 1; // 1-based line number
+            continue;
+        }
+        // Match: orchestrator {
+        const orchMatch = line.match(/^\s*orchestrator\s*(?:\{|[^{]*\{)/);
+        if (orchMatch) {
+            sourceMap["orchestrator"] = i + 1;
+        }
+    }
+    return sourceMap;
+}
+// ---------------------------------------------------------------------------
+// Composition parsing: params, interface, import, include, fragment
+// ---------------------------------------------------------------------------
+/**
+ * Parse a `params { ... }` block into typed parameter definitions.
+ *
+ * Each line has the form `name: type` or `name: type = default`.
+ * If a default is provided, the parameter is optional; otherwise required.
+ */
+export function parseParams(body) {
+    const params = [];
+    const VALID_TYPES = new Set(["string", "number", "boolean"]);
+    for (const line of body.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        // Match: name: type = default  OR  name: type
+        const m = trimmed.match(/^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:\s*(string|number|boolean)(?:\s*=\s*(.+))?$/);
+        if (!m)
+            continue;
+        const [, name, type, rawDefault] = m;
+        const paramType = type;
+        let defaultValue;
+        let required = true;
+        if (rawDefault !== undefined) {
+            required = false;
+            const dv = rawDefault.trim();
+            if (paramType === "number") {
+                defaultValue = parseFloat(dv);
+            }
+            else if (paramType === "boolean") {
+                defaultValue = dv === "true";
+            }
+            else {
+                // string — strip quotes if present
+                defaultValue = unquote(dv);
+            }
+        }
+        params.push({ name, type: paramType, required, ...(defaultValue !== undefined ? { default: defaultValue } : {}) });
+    }
+    return params;
+}
+/**
+ * Parse an `interface { entry: <id>  exit: <id> }` block body.
+ */
+export function parseInterfaceEndpoints(body) {
+    const fields = parseFields(body);
+    const entry = fields["entry"];
+    const exit = fields["exit"];
+    if (!entry || !exit)
+        return null;
+    return { entry: unquote(entry), exit: unquote(exit) };
+}
+/**
+ * Extract and parse the `interface { ... }` block from a topology body,
+ * carefully avoiding collision with `interfaces { ... }`.
+ */
+function parseInterfaceBlock(topBody) {
+    // Match "interface" followed by whitespace+"{" but NOT "interfaces"
+    const re = /(?:^|\n)\s*interface\s*\{/m;
+    const m = re.exec(topBody);
+    if (!m)
+        return null;
+    // Make sure we did not match "interfaces" — check what precedes the `{`
+    const matchText = m[0];
+    if (/interfaces/.test(matchText))
+        return null;
+    // Find the opening brace and count braces to extract the body
+    const braceIdx = m.index + m[0].length;
+    let depth = 1;
+    let i = braceIdx;
+    while (i < topBody.length && depth > 0) {
+        if (topBody[i] === "{")
+            depth++;
+        else if (topBody[i] === "}")
+            depth--;
+        i++;
+    }
+    if (depth !== 0)
+        return null;
+    const body = topBody.slice(braceIdx, i - 1);
+    return parseInterfaceEndpoints(body);
+}
+/**
+ * Parse import statements from a topology body.
+ *
+ * Syntax:
+ *   import "./path.at" as alias
+ *   import "./path.at" as alias with { key: value ... }
+ *
+ * Import statements are parsed from the raw body text since they are
+ * not brace-delimited blocks in the usual sense.
+ */
+export function parseImports(body) {
+    const imports = [];
+    // Regex: import "source" as alias (captures everything after for optional with block)
+    const importRe = /(?:^|\n)\s*import\s+"([^"]+)"\s+as\s+([a-zA-Z][a-zA-Z0-9_-]*)/g;
+    let m;
+    while ((m = importRe.exec(body)) !== null) {
+        const source = m[1];
+        const alias = m[2];
+        const params = {};
+        // Check for `with { ... }` block following the import
+        const afterImport = body.slice(m.index + m[0].length);
+        const withMatch = afterImport.match(/^\s*with\s*\{([^}]*)\}/);
+        if (withMatch) {
+            const withBody = withMatch[1];
+            for (const line of withBody.split("\n")) {
+                const kv = parseKV(line);
+                if (!kv)
+                    continue;
+                const [key, rawVal] = kv;
+                const val = unquote(rawVal);
+                // Try number
+                if (/^-?\d+(\.\d+)?$/.test(val)) {
+                    params[key] = parseFloat(val);
+                }
+                else if (val === "true" || val === "false") {
+                    params[key] = val === "true";
+                }
+                else {
+                    params[key] = val;
+                }
+            }
+        }
+        const importDef = { source, alias, params };
+        // Detect registry imports (not starting with ./ or ../)
+        const isRegistry = !source.startsWith("./") && !source.startsWith("../");
+        if (isRegistry) {
+            importDef.registry = true;
+            // Parse package@version format
+            const atIdx = source.lastIndexOf("@");
+            if (atIdx > 0) {
+                importDef.registryPackage = source.slice(0, atIdx);
+                importDef.registryVersion = source.slice(atIdx + 1);
+            }
+            else {
+                importDef.registryPackage = source;
+            }
+        }
+        // Check for sha256 after the with block (or after alias if no with block)
+        const afterWithOrAlias = withMatch
+            ? afterImport.slice(withMatch[0].length)
+            : afterImport;
+        const sha256Match = afterWithOrAlias.match(/^\s*sha256\s*:\s*"([^"]+)"/);
+        if (sha256Match) {
+            importDef.sha256 = sha256Match[1];
+        }
+        imports.push(importDef);
+    }
+    return imports;
+}
+/**
+ * Parse include statements from a topology body.
+ *
+ * Syntax: include "./path.at"
+ */
+export function parseIncludes(body) {
+    const includes = [];
+    const re = /(?:^|\n)\s*include\s+"([^"]+)"/g;
+    let m;
+    while ((m = re.exec(body)) !== null) {
+        includes.push({ source: m[1] });
+    }
+    return includes;
+}
+export function parse(source) {
+    const src = stripComments(source);
+    // --- Source map (line numbers for nodes) ---
+    const sourceMap = buildSourceMap(source);
+    // --- Detect fragment vs topology root ---
+    const isFragment = /(?:^|\n)\s*fragment\s+\S+\s*\{/.test(source);
+    // --- Topology header ---
+    let header;
+    if (isFragment) {
+        // Fragment header: fragment <name> { ... }
+        const fm = source.match(/fragment\s+(\S+)\s*\{/);
+        if (!fm)
+            throw new Error("Could not find fragment header");
+        header = { name: fm[1], patterns: [] };
+    }
+    else {
+        // Use raw source to preserve the topology line (comments already on other lines)
+        header = parseTopologyHeader(source);
+    }
+    // --- Extract the full topology/fragment body ---
+    const topoBlock = extractBlock(source, isFragment ? "fragment" : "topology");
+    if (!topoBlock) {
+        throw new Error(isFragment ? "Could not extract fragment body" : "Could not extract topology body");
+    }
+    const topBody = stripComments(topoBlock.body);
+    // --- Meta ---
+    const metaBlock = extractBlock(topBody, "meta");
+    const metaFields = metaBlock ? parseMeta(metaBlock.body) : {};
+    const topology = {
+        name: header.name,
+        version: metaFields.version ?? "0.0.0",
+        description: metaFields.description ?? "",
+        patterns: header.patterns,
+        ...(metaFields.foundations ? { foundations: metaFields.foundations } : {}),
+        ...(metaFields.advanced ? { advanced: metaFields.advanced } : {}),
+        ...(metaFields.domain ? { domain: metaFields.domain } : {}),
+        ...(metaFields.timeout ? { timeout: metaFields.timeout } : {}),
+        ...(metaFields.errorHandler ? { errorHandler: metaFields.errorHandler } : {}),
+        ...(metaFields.durable !== undefined ? { durable: metaFields.durable } : {}),
+    };
+    // --- Roles ---
+    const rolesBlock = extractBlock(topBody, "roles");
+    const roles = rolesBlock ? parseRoles(rolesBlock.body) : {};
+    // --- Nodes ---
+    const nodes = [];
+    // Orchestrator
+    const orchBlock = extractBlock(topBody, "orchestrator");
+    if (orchBlock) {
+        nodes.push(parseOrchestrator(orchBlock.body));
+    }
+    // Actions
+    const actionBlocks = extractAllBlocks(topBody, "action");
+    for (const block of actionBlocks) {
+        if (block.id) {
+            nodes.push(parseAction(block.id, block.body));
+        }
+    }
+    // Agents
+    const agentBlocks = extractAllBlocks(topBody, "agent");
+    for (const block of agentBlocks) {
+        if (block.id) {
+            nodes.push(parseAgent(block.id, block.body, roles));
+        }
+    }
+    // Gates
+    const gatesBlock = extractBlock(topBody, "gates");
+    if (gatesBlock) {
+        const gateBlocks = extractAllBlocks(gatesBlock.body, "gate");
+        for (const block of gateBlocks) {
+            if (block.id) {
+                nodes.push(parseGate(block.id, block.body));
+            }
+        }
+    }
+    // Human nodes
+    const humanBlocks = extractAllBlocks(topBody, "human");
+    for (const block of humanBlocks) {
+        if (block.id) {
+            nodes.push(parseHuman(block.id, block.body));
+        }
+    }
+    // Group chat nodes
+    const groupBlocks = extractAllBlocks(topBody, "group");
+    for (const block of groupBlocks) {
+        if (block.id) {
+            nodes.push(parseGroup(block.id, block.body));
+        }
+    }
+    // --- Skills ---
+    const skillDefs = parseSkillBlocks(topBody);
+    // --- Tools ---
+    const toolDefs = parseToolsBlock(topBody);
+    // --- Edges (flow) ---
+    const flowBlock = extractBlock(topBody, "flow");
+    const edgeAttributeErrors = [];
+    const edges = flowBlock ? parseFlow(flowBlock.body, edgeAttributeErrors) : [];
+    // --- Depth ---
+    const depthBlock = extractBlock(topBody, "depth");
+    const depth = depthBlock
+        ? parseDepth(depthBlock.body)
+        : { factors: [], levels: [] };
+    // --- Memory ---
+    const memoryBlock = extractBlock(topBody, "memory");
+    const unknownMemorySubBlockWarnings = [];
+    const memory = memoryBlock ? parseMemory(memoryBlock.body, unknownMemorySubBlockWarnings) : {};
+    // --- Batch ---
+    const batchBlock = extractBlock(topBody, "batch");
+    const batch = batchBlock ? parseBatch(batchBlock.body) : {};
+    // --- Environments ---
+    const envsBlock = extractBlock(topBody, "environments");
+    const environments = envsBlock
+        ? parseEnvironments(envsBlock.body)
+        : {};
+    // --- Triggers ---
+    const triggersBlock = extractBlock(topBody, "triggers");
+    const triggers = triggersBlock
+        ? parseTriggers(triggersBlock.body)
+        : [];
+    // --- Hooks (global) ---
+    // Collect per-agent hook names to avoid double-counting them as global.
+    const perAgentHookNames = new Set();
+    for (const n of nodes) {
+        if (n.type === "agent" && n.hooks) {
+            for (const h of n.hooks) {
+                perAgentHookNames.add(h.name);
+            }
+        }
+    }
+    const allHooksBlocks = extractAllBlocks(topBody, "hooks");
+    let hooks = [];
+    for (const hb of allHooksBlocks) {
+        const parsed = parseHooks(hb.body);
+        const globalOnly = parsed.filter((h) => !perAgentHookNames.has(h.name));
+        if (globalOnly.length > 0) {
+            hooks = globalOnly;
+            break;
+        }
+    }
+    if (hooks.length === 0 && allHooksBlocks.length > 1) {
+        const lastBlock = allHooksBlocks[allHooksBlocks.length - 1];
+        hooks = parseHooks(lastBlock.body);
+    }
+    // --- Settings ---
+    const settingsBlock = extractBlock(topBody, "settings");
+    const settings = settingsBlock
+        ? parseSettings(settingsBlock.body)
+        : {};
+    // --- MCP Servers ---
+    const mcpBlock = extractBlock(topBody, "mcp-servers");
+    const mcpServers = mcpBlock ? parseMcpServers(mcpBlock.body) : {};
+    // --- Metering ---
+    const meteringBlock = extractBlock(topBody, "metering");
+    const metering = meteringBlock
+        ? parseMetering(meteringBlock.body)
+        : null;
+    // --- Context ---
+    const contextBlock = extractBlock(topBody, "context");
+    const context = contextBlock ? parseContext(contextBlock.body) : {};
+    // --- Env ---
+    const envBlock = extractBlock(topBody, "env");
+    const env = envBlock ? parseEnv(envBlock.body) : {};
+    // --- Providers ---
+    const providersBlock = extractBlock(topBody, "providers");
+    const providers = providersBlock ? parseProviders(providersBlock.body) : [];
+    // --- Schedule ---
+    const scheduleBlock = extractBlock(topBody, "schedule");
+    const schedules = scheduleBlock ? parseSchedule(scheduleBlock.body) : [];
+    // --- Interfaces ---
+    const interfacesBlock = extractBlock(topBody, "interfaces");
+    const interfaces = interfacesBlock ? parseInterfaces(interfacesBlock.body) : [];
+    // --- Defaults ---
+    const defaultsBlock = extractBlock(topBody, "defaults");
+    const defaults = defaultsBlock ? parseDefaults(defaultsBlock.body) : null;
+    // --- Schemas ---
+    const schemas = parseSchemas(topBody);
+    // --- Observability ---
+    const observabilityBlock = extractBlock(topBody, "observability");
+    const observability = observabilityBlock ? parseObservability(observabilityBlock.body) : null;
+    // --- Checkpoint ---
+    const checkpointBlock = extractBlock(topBody, "checkpoint");
+    const checkpoint = checkpointBlock ? parseCheckpoint(checkpointBlock.body) : null;
+    // --- Artifacts ---
+    const artifacts = parseArtifacts(topBody);
+    // --- Top-level Extensions ---
+    const topLevelExtensions = parseExtensionsBlock(topBody);
+    // --- Params ---
+    const paramsBlock = extractBlock(topBody, "params");
+    const params = paramsBlock ? parseParams(paramsBlock.body) : [];
+    // --- Interface (entry/exit endpoints) ---
+    // Note: "interface" block is distinct from "interfaces" (external interface definitions).
+    // We use a targeted regex to avoid matching "interfaces" when looking for "interface".
+    const interfaceEndpoints = parseInterfaceBlock(topBody);
+    // --- Imports ---
+    const imports = parseImports(topBody);
+    // --- Includes ---
+    const includes = parseIncludes(topBody);
+    // --- Duplicate section detection ---
+    const singletonKeywords = [
+        "meta", "orchestrator", "flow", "memory", "batch", "environments",
+        "triggers", "settings", "mcp-servers", "metering", "context", "env",
+        "providers", "schedule", "interfaces", "depth", "gates", "roles", "tools",
+        "defaults", "schemas", "observability", "params", "interface",
+        "checkpoint", "artifacts",
+    ];
+    const duplicateSectionWarnings = [];
+    for (const keyword of singletonKeywords) {
+        const allBlocks = extractAllBlocks(topBody, keyword);
+        if (allBlocks.length > 1) {
+            duplicateSectionWarnings.push({
+                rule: "V23",
+                level: "warning",
+                message: `Duplicate "${keyword}" block detected (found ${allBlocks.length}) — only the first occurrence is used`,
+            });
+        }
+    }
+    // --- Assemble AST ---
+    const ast = {
+        topology,
+        nodes,
+        edges,
+        depth,
+        memory,
+        batch,
+        environments,
+        triggers,
+        hooks,
+        settings,
+        mcpServers,
+        metering,
+        skills: skillDefs,
+        toolDefs,
+        roles,
+        context,
+        env,
+        providers,
+        schedules,
+        interfaces,
+        defaults,
+        schemas,
+        ...(topLevelExtensions ? { extensions: topLevelExtensions } : {}),
+        observability,
+        params,
+        interfaceEndpoints,
+        imports,
+        includes,
+        checkpoint,
+        artifacts,
+        ...(isFragment ? { isFragment: true } : {}),
+    };
+    // Attach V12 parse-time errors for the validator to consume.
+    if (edgeAttributeErrors.length > 0) {
+        ast._edgeAttributeErrors = edgeAttributeErrors;
+    }
+    // Attach V23 duplicate section warnings for the validator to consume.
+    if (duplicateSectionWarnings.length > 0) {
+        ast._duplicateSectionWarnings = duplicateSectionWarnings;
+    }
+    // Attach V24 unknown memory sub-block warnings for the validator to consume.
+    if (unknownMemorySubBlockWarnings.length > 0) {
+        ast._unknownMemorySubBlockWarnings = unknownMemorySubBlockWarnings;
+    }
+    // Attach source map for line number tracking in validation results.
+    if (Object.keys(sourceMap).length > 0) {
+        ast._sourceMap = sourceMap;
+    }
+    return ast;
+}
+//# sourceMappingURL=index.js.map