structured-context 0.12.0 → 0.13.1

package/dist/judge/trim.d.ts

@@ -0,0 +1,27 @@
+import type { SemanticJudgeInput } from './types';
+/** The per-node input cap: estimated tokens of one node's input (the node and its related nodes), the same for every provider. */
+export declare const PER_NODE_INPUT_CAP_TOKENS = 32000;
+/** Estimated tokens of a value: its JSON length divided by 4. Provider-independent, and roughly right is enough. */
+export declare const estimateTokens: (value: unknown) => number;
+/** The placeholder that ends a body cut to fit the per-node input cap. `removed` is the number of characters cut. */
+export declare const trimMarker: (removed: number) => string;
+/** The part of a judge input that the per-node input cap measures. */
+export type NodeInput = Pick<SemanticJudgeInput, 'node' | 'related'>;
+/**
+ * Cut `body` to at most `limit` characters, ending at the last whitespace before the limit, and end it with the
+ * trim marker. A body within the limit is returned whole.
+ */
+export declare function cutBody(body: string, limit: number): string;
+/**
+ * Fit a node's input under the per-node input cap by cutting bodies only: related bodies to one shared ceiling
+ * first, then the evaluated node's body. Undefined when the input does not fit even with every body cut.
+ */
+export declare function trimToCap(input: NodeInput, cap?: number): {
+    input: NodeInput;
+    trimmed: boolean;
+} | undefined;
+/** What a run trimmed: the nodes (by label) and the rules whose input had a body cut. */
+export interface TrimReport {
+    nodes: Set<string>;
+    ruleIds: Set<string>;
+}

package/dist/judge/trim.js

@@ -0,0 +1,62 @@
+/** The per-node input cap: estimated tokens of one node's input (the node and its related nodes), the same for every provider. */
+export const PER_NODE_INPUT_CAP_TOKENS = 32_000;
+/** Estimated tokens of a value: its JSON length divided by 4. Provider-independent, and roughly right is enough. */
+export const estimateTokens = (value) => Math.ceil(JSON.stringify(value).length / 4);
+/** The placeholder that ends a body cut to fit the per-node input cap. `removed` is the number of characters cut. */
+export const trimMarker = (removed) => `[RULE_EVALUATION_CONTENT_TRIMMED ${removed} chars]`;
+/**
+ * Cut `body` to at most `limit` characters, ending at the last whitespace before the limit, and end it with the
+ * trim marker. A body within the limit is returned whole.
+ */
+export function cutBody(body, limit) {
+    if (body.length <= limit)
+        return body;
+    let head = body.slice(0, limit);
+    if (!/\s/.test(body.charAt(limit))) {
+        const lastSpace = head.search(/\s\S*$/);
+        head = lastSpace < 0 ? '' : head.slice(0, lastSpace);
+    }
+    head = head.trimEnd();
+    const marker = trimMarker(body.length - head.length);
+    return head ? `${head} ${marker}` : marker;
+}
+function limitBodies(input, relatedLimit, nodeLimit) {
+    const cut = (data, limit) => typeof data.content === 'string' ? { ...data, content: cutBody(data.content, limit) } : data;
+    return {
+        node: { ...input.node, schemaData: cut(input.node.schemaData, nodeLimit) },
+        ...(input.related && { related: input.related.map((r) => ({ ...r, data: cut(r.data, relatedLimit) })) }),
+    };
+}
+const bodyLength = (data) => (typeof data.content === 'string' ? data.content.length : 0);
+/** The largest limit in `[0, max]` for which `fits` holds, or -1 when even 0 does not fit. `fits` shrinks as the limit falls. */
+function largestFitting(max, fits) {
+    if (!fits(0))
+        return -1;
+    let low = 0;
+    let high = max;
+    while (low < high) {
+        const mid = Math.ceil((low + high) / 2);
+        if (fits(mid))
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    return low;
+}
+/**
+ * Fit a node's input under the per-node input cap by cutting bodies only: related bodies to one shared ceiling
+ * first, then the evaluated node's body. Undefined when the input does not fit even with every body cut.
+ */
+export function trimToCap(input, cap = PER_NODE_INPUT_CAP_TOKENS) {
+    if (estimateTokens(input) <= cap)
+        return { input, trimmed: false };
+    const nodeLength = bodyLength(input.node.schemaData);
+    const relatedMax = Math.max(0, ...(input.related ?? []).map((r) => bodyLength(r.data)));
+    const fitsRelated = (limit) => estimateTokens(limitBodies(input, limit, nodeLength)) <= cap;
+    const relatedLimit = largestFitting(relatedMax, fitsRelated);
+    if (relatedLimit >= 0)
+        return { input: limitBodies(input, relatedLimit, nodeLength), trimmed: true };
+    const fitsNode = (limit) => estimateTokens(limitBodies(input, 0, limit)) <= cap;
+    const nodeLimit = largestFitting(nodeLength, fitsNode);
+    return nodeLimit >= 0 ? { input: limitBodies(input, 0, nodeLimit), trimmed: true } : undefined;
+}

package/dist/judge/types.d.ts

@@ -0,0 +1,92 @@
+import type { RuleCategory, SpaceNode } from '../types';
+/** A semantic rule as presented to a judge: the closed verdict set it must choose from. */
+export interface SemanticRuleSpec {
+    id: string;
+    description: string;
+    rubric?: string;
+    category: RuleCategory | string;
+    /** Allowed verdicts, each with a description of when it applies. */
+    verdicts: Record<string, string>;
+}
+/**
+ * A node related to the evaluated node by its rules' `scope`. It carries all the node's schema data; the body
+ * (`data.content`) is present only when the rules' `includeContent` asks for it.
+ */
+export interface RelatedNode {
+    /** How it relates to the evaluated node. A node can have several. */
+    relations: Array<'parent' | 'sibling' | 'child' | 'ancestor' | 'descendant'>;
+    title: string;
+    type: string;
+    /** Schema data without `title` and `type`. */
+    data: Record<string, unknown>;
+}
+/**
+ * One node and the semantic rules to judge on it, which share one context: the same related nodes and the same
+ * bodies. Judges may answer all rules in a single call.
+ */
+export interface SemanticJudgeInput {
+    /** The evaluated node. Its body is in `schemaData.content` only when the rules' `includeContent` asks for it. */
+    node: Pick<SpaceNode, 'label' | 'title' | 'type' | 'resolvedType' | 'schemaData' | 'resolvedParents'>;
+    /** Nodes the rules' `scope` adds, as a flat list. Absent when the scope is empty. */
+    related?: RelatedNode[];
+    rules: SemanticRuleSpec[];
+}
+/** A judge's answer for one rule: a verdict from the rule's closed set. */
+export interface SemanticJudgeVerdict {
+    verdict: string;
+    /** 0-1, when the judge reports one. */
+    confidence?: number;
+    /** Probability per verdict, when the judge reports a distribution. */
+    probabilities?: Record<string, number>;
+    /** Free-text reasoning; decision models may not provide it. */
+    evidence?: string;
+}
+/** A judge's answer for one rule: a verdict, or an error that applies to that rule only. */
+export type SemanticJudgeResult = SemanticJudgeVerdict | {
+    error: string;
+};
+/** Judge interface. Results are keyed by rule id; a missing key is treated as an error. */
+export interface SemanticJudgeProvider {
+    readonly name: string;
+    evaluate(input: SemanticJudgeInput): Promise<Record<string, SemanticJudgeResult>>;
+    /**
+     * Optional: judge many nodes in one call, so a provider can fold them into fewer model calls. Returns one
+     * result map per input, in order. A failure that affects only some inputs is reported as `{ error }`
+     * results for those inputs' rules; throw only when nothing could be judged.
+     */
+    evaluateNodes?(inputs: SemanticJudgeInput[]): Promise<Array<Record<string, SemanticJudgeResult>>>;
+}
+/** Wire APIs a provider can speak. Names the request shape, never the vendor or model. */
+export declare const MODEL_PROVIDER_APIS: readonly ["openai-completions", "openai-decisions", "anthropic-messages", "openrouter-decisions", "typesafe-systemone", "fake"];
+export type ModelProviderApi = (typeof MODEL_PROVIDER_APIS)[number];
+/** How to reach a model: a bundled provider or config `modelProviders.<name>`, before hydration. */
+export interface ModelProviderConfig {
+    /** The wire API to speak. */
+    api: ModelProviderApi;
+    /** Fixed model override. Beats `modelEnv` and the bundled default. */
+    model?: string;
+    /** Environment variable that holds the model override. */
+    modelEnv?: string;
+    /** Fixed endpoint override. Beats `endpointEnv` and the bundled default. */
+    endpoint?: string;
+    /** Environment variable that holds the endpoint override. */
+    endpointEnv?: string;
+    /** Prefer `apiKeyEnv`: keys do not belong in config files. */
+    apiKey?: string;
+    /** Environment variable holding the key. */
+    apiKeyEnv?: string;
+}
+/** A provider after hydration: every field is a concrete value; the implementation reads no environment. */
+export interface HydratedProvider {
+    api: ModelProviderApi;
+    model?: string;
+    endpoint?: string;
+    apiKey?: string;
+    /** The environment variable the key was read from, when one was named or defaulted. */
+    keyEnv?: string;
+}
+/** Which model provider evaluates semantic rules: config `semantic`, at the top level or on a space. */
+export interface JudgeConfig {
+    /** Name of an entry in `modelProviders`, or a bundled provider. */
+    provider?: string;
+}

package/dist/judge/types.js

@@ -0,0 +1,9 @@
+/** Wire APIs a provider can speak. Names the request shape, never the vendor or model. */
+export const MODEL_PROVIDER_APIS = [
+    'openai-completions',
+    'openai-decisions',
+    'anthropic-messages',
+    'openrouter-decisions',
+    'typesafe-systemone',
+    'fake',
+];

package/dist/judge/verdicts.d.ts

@@ -0,0 +1,24 @@
+import type { Rule, RuleSeverity } from '../types';
+import type { SemanticJudgeResult, SemanticRuleSpec } from './types';
+/** Verdicts for a semantic rule that declares none. */
+export declare const DEFAULT_VERDICTS: Record<string, string>;
+/** A semantic rule resolved for evaluation: what the judge sees, and what each verdict means for the user. */
+export interface ResolvedSemanticRule {
+    /** What the judge sees: the closed verdict set. */
+    spec: SemanticRuleSpec;
+    /** Severity of each verdict that fails the rule. A verdict absent here passes (including `ignore`d ones). */
+    severities: Record<string, RuleSeverity>;
+    /** User-facing guidance for verdicts that declare it. */
+    guidance: Record<string, string>;
+}
+/**
+ * Resolve a semantic rule: apply verdict defaults, split each verdict into its judge description and user guidance,
+ * and work out which verdicts fail at what severity. Throws on an inconsistent rule.
+ */
+export declare function resolveSemanticRule(rule: Rule): ResolvedSemanticRule;
+/** The judge-facing spec for a semantic rule. */
+export declare function semanticRuleSpec(rule: Rule): SemanticRuleSpec;
+/** Whether a judge result is an error rather than a verdict. */
+export declare function isJudgeError(result: SemanticJudgeResult): result is {
+    error: string;
+};

package/dist/judge/verdicts.js

@@ -0,0 +1,82 @@
+import { RESERVED_VERDICTS } from '../schema/metadata-contract';
+import { ruleSemantic, ruleSeverity } from '../schema/rule-severity';
+import { ruleContext } from './context';
+/** Verdicts for a semantic rule that declares none. */
+export const DEFAULT_VERDICTS = {
+    pass: 'The node meets the rubric.',
+    fail: 'The node does not meet the rubric.',
+};
+/** The reserved verdict a rule with related nodes or bodies offers, for input a trim marker shows was cut. */
+const MISSING_CONTEXT_VERDICT = 'missing-context';
+const MISSING_CONTEXT_DESCRIPTION = 'Content needed to judge the rule was cut: a [RULE_EVALUATION_CONTENT_TRIMMED n chars] marker shows where. Choose this only when such a marker is present and the cut content is needed. Never choose it when no marker appears.';
+/**
+ * Resolve a semantic rule: apply verdict defaults, split each verdict into its judge description and user guidance,
+ * and work out which verdicts fail at what severity. Throws on an inconsistent rule.
+ */
+export function resolveSemanticRule(rule) {
+    const semantic = ruleSemantic(rule);
+    if (!semantic)
+        throw new Error(`Rule "${rule.id}" has no semantic part.`);
+    const declared = semantic.verdicts ?? DEFAULT_VERDICTS;
+    const verdicts = {};
+    const guidance = {};
+    for (const [name, value] of Object.entries(declared)) {
+        if (typeof value === 'string') {
+            verdicts[name] = value;
+        }
+        else {
+            verdicts[name] = value.description;
+            if (value.guidance)
+                guidance[name] = value.guidance;
+        }
+    }
+    let mapping;
+    if (semantic.verdicts) {
+        if (!semantic.severity) {
+            throw new Error(`Semantic rule "${rule.id}" declares verdicts, so semantic.severity must map the failing verdicts, e.g. { "${Object.keys(verdicts)[0]}": "warning" }.`);
+        }
+        mapping = semantic.severity;
+    }
+    else {
+        mapping = { ...semantic.severity, fail: ruleSeverity(rule) };
+    }
+    const reserved = RESERVED_VERDICTS;
+    const unknown = Object.keys(mapping).filter((v) => !(v in verdicts) && !reserved.includes(v));
+    if (unknown.length > 0) {
+        throw new Error(`Semantic rule "${rule.id}" has semantic.severity for verdicts not in its verdicts: ${unknown.join(', ')}.`);
+    }
+    const severities = {};
+    for (const [verdict, severity] of Object.entries(mapping)) {
+        if (severity !== 'ignore')
+            severities[verdict] = severity;
+    }
+    if (Object.keys(severities).filter((v) => v in verdicts).length >= Object.keys(verdicts).length) {
+        throw new Error(`Semantic rule "${rule.id}" has no passing verdict: every verdict has a severity.`);
+    }
+    // A warning by default.
+    const context = ruleContext(rule);
+    if (context.scope.length > 0 || context.content !== 'none') {
+        verdicts[MISSING_CONTEXT_VERDICT] = MISSING_CONTEXT_DESCRIPTION;
+        if (!(MISSING_CONTEXT_VERDICT in mapping))
+            severities[MISSING_CONTEXT_VERDICT] = 'warning';
+    }
+    return {
+        spec: {
+            id: rule.id,
+            description: rule.description,
+            rubric: semantic.rubric,
+            category: rule.category,
+            verdicts,
+        },
+        severities,
+        guidance,
+    };
+}
+/** The judge-facing spec for a semantic rule. */
+export function semanticRuleSpec(rule) {
+    return resolveSemanticRule(rule).spec;
+}
+/** Whether a judge result is an error rather than a verdict. */
+export function isJudgeError(result) {
+    return 'error' in result;
+}

package/dist/plugins/markdown/parse-embedded.d.ts

@@ -8,6 +8,8 @@ type StackEntry = {
     nodeType: string;
     /** Preferred wikilink key used when this heading acts as a parent. */
     refTarget: string;
+    /** Node whose section this heading opens; absent for untyped placeholders and the page's own entry. */
+    node?: BaseNode;
 };
 /** Detect a bare wikilink `[[...]]` and return the inner target, or undefined. */
 export declare function isWikilink(text: string): string | undefined;

package/dist/plugins/markdown/parse-embedded.js

@@ -1,10 +1,9 @@
-import { load as yamlLoad } from 'js-yaml';
 import { toString as mdastToString } from 'mdast-util-to-string';
 import remarkGfm from 'remark-gfm';
 import remarkParse from 'remark-parse';
 import { unified } from 'unified';
 import { extractLinksFromAstNode } from './extract-content-links';
-import { applyFieldMap, coerceDates } from './util';
+import { applyFieldMap, parseYaml } from './util';
 /** Type values that identify a space_on_a_page container (not themselves space nodes). */
 export const ON_A_PAGE_TYPES = ['ost_on_a_page', 'space_on_a_page'];
 const DEFAULT_STATUS = 'identified';
@@ -141,18 +140,91 @@ export function defaultNodeType(stack, hierarchy) {
     }
     return hierarchy[idx + 1];
 }
-function appendContent(node, text) {
-    if (!text)
+/** Start and end offsets of an mdast node. Throws when the parser gave no position. */
+function offsetsOf(node) {
+    const start = node.position?.start.offset;
+    const end = node.position?.end.offset;
+    if (start === undefined || end === undefined) {
+        throw new Error(`Markdown ${node.type} node has no source position; cannot slice its content`);
+    }
+    return { start, end };
+}
+function addRange(claims, node, start, end) {
+    if (end <= start)
         return;
-    const existing = node.schemaData.content;
-    const updated = existing ? `${existing}\n${text}` : text;
-    node.schemaData.content = updated;
-    node.content = updated;
+    const ranges = claims.ranges.get(node) ?? [];
+    const last = ranges[ranges.length - 1];
+    if (last && last.end === start)
+        last.end = end;
+    else
+        ranges.push({ start, end });
+    claims.ranges.set(node, ranges);
+}
+/**
+ * Give a node a block of source, plus the blank lines between `from` and the block's `start`.
+ * Those lines are skipped when a consumed block just before already kept its own.
+ */
+function claim(claims, node, from, start, end) {
+    addRange(claims, node, claims.gapKept.delete(node) ? start : from, end);
+}
+/**
+ * Take a block out of a node's content (it was consumed as a node, field or other syntax).
+ * The blank lines before it stay, so the content on either side does not run together.
+ */
+function consume(claims, node, from, start) {
+    addRange(claims, node, claims.gapKept.delete(node) ? start : from, start);
+    claims.gapKept.add(node);
+}
+/** Sets each node's content from its claimed source. Leading blank lines and trailing whitespace are dropped. */
+function applyClaims(claims, body) {
+    for (const [node, ranges] of claims.ranges) {
+        let content = ranges
+            .map((r) => body.slice(r.start, r.end))
+            .join('')
+            .replace(/^(?:[ \t]*\r?\n)+/, '')
+            .trimEnd();
+        const indent = claims.contentIndent.get(node);
+        if (indent) {
+            const strip = new RegExp(`^[ \\t]{1,${indent}}`);
+            content = content
+                .split(/(?<=\n)/)
+                .map((line) => line.replace(strip, ''))
+                .join('');
+        }
+        if (!content)
+            continue;
+        node.schemaData.content = content;
+        node.content = content;
+    }
 }
-function processListItem(item, parentRef, contentTarget, nodes, makeLabel, buildLinkTargets, typeAliases, fieldMap, pendingType, parentFieldAppend, activeNodeFieldAppend, file, lineOffset) {
+/** Source lines (with terminators) of a range, as absolute offsets. */
+function sourceLines(body, range) {
+    const lines = [];
+    const re = /[^\n]*\n|[^\n]+$/g;
+    const text = body.slice(range.start, range.end);
+    for (const m of text.matchAll(re)) {
+        lines.push({
+            start: range.start + m.index,
+            end: range.start + m.index + m[0].length,
+            text: m[0].replace(/\r?\n$/, ''),
+        });
+    }
+    return lines;
+}
+/** Whether a line holds only inline fields: bracketed `[key:: value]` pieces, or one `key:: value`. */
+function isFieldOnlyLine(line) {
+    const { cleanText, fields } = extractBracketedFields(line);
+    const hasBracketed = Object.keys(fields).length > 0;
+    if (cleanText === '')
+        return hasBracketed;
+    return /^[a-zA-Z][a-zA-Z0-9_-]*:: *.*$/.test(cleanText);
+}
+function processListItem(item, parentRef, contentTarget, nodes, makeLabel, buildLinkTargets, typeAliases, fieldMap, pendingType, parentFieldAppend, activeNodeFieldAppend, file, lineOffset, walk) {
+    const itemEnd = offsetsOf(item).end;
     const firstPara = item.children.find((c) => c.type === 'paragraph');
     if (!firstPara) {
-        appendContent(contentTarget, `- ${mdastToString(item)}`);
+        claim(walk.claims, contentTarget, walk.pos, offsetsOf(item).start, itemEnd);
+        walk.pos = itemEnd;
         return;
     }
     const rawText = mdastToString(firstPara);
@@ -161,11 +233,15 @@ function processListItem(item, parentRef, contentTarget, nodes, makeLabel, build
     if (wikiTarget) {
         const linkRef = `[[${wikiTarget}]]`;
         if (parentFieldAppend) {
+            consume(walk.claims, contentTarget, walk.pos, offsetsOf(item).start);
             appendParentField(parentFieldAppend.node, parentFieldAppend.field, linkRef);
+            walk.pos = itemEnd;
             return;
         }
         if (activeNodeFieldAppend) {
+            consume(walk.claims, contentTarget, walk.pos, offsetsOf(item).start);
             appendParentField(activeNodeFieldAppend.node, activeNodeFieldAppend.field, linkRef);
+            walk.pos = itemEnd;
             return;
         }
         // No field append context — fall through to node creation or content append
@@ -204,21 +280,34 @@ function processListItem(item, parentRef, contentTarget, nodes, makeLabel, build
             ...(source ? { source } : {}),
         };
         nodes.push(newNode);
+        const contentColumn = firstPara.position?.start.column;
+        if (contentColumn !== undefined)
+            walk.claims.contentIndent.set(newNode, contentColumn - 1);
         if (parentFieldAppend) {
             appendParentField(parentFieldAppend.node, parentFieldAppend.field, `[[${linkTargets[0] ?? title}]]`);
         }
         const nestedParentRef = `[[${linkTargets[0] ?? title}]]`;
+        consume(walk.claims, contentTarget, walk.pos, offsetsOf(item).start);
+        walk.pos = offsetsOf(firstPara).end;
         for (const child of item.children) {
+            if (child === firstPara)
+                continue;
             if (child.type === 'list') {
                 for (const subItem of child.children) {
-                    processListItem(subItem, nestedParentRef, newNode, nodes, makeLabel, buildLinkTargets, typeAliases, fieldMap, pendingType, undefined, undefined, file, lineOffset);
+                    processListItem(subItem, nestedParentRef, newNode, nodes, makeLabel, buildLinkTargets, typeAliases, fieldMap, pendingType, undefined, undefined, file, lineOffset, walk);
                 }
             }
+            else {
+                const { start, end } = offsetsOf(child);
+                claim(walk.claims, newNode, walk.pos, start, end);
+                walk.pos = end;
+            }
         }
     }
     else {
-        appendContent(contentTarget, `- ${rawText}`);
+        claim(walk.claims, contentTarget, walk.pos, offsetsOf(item).start, itemEnd);
     }
+    walk.pos = itemEnd;
 }
 /**
  * Extract space nodes from markdown body text.
@@ -418,7 +507,32 @@ export function extractEmbeddedNodes(body, options) {
     }
     let grouping = null;
     let activeNode = rootNode;
+    const claims = { ranges: new Map(), gapKept: new Set(), contentIndent: new Map() };
+    /** End of the previous top-level block; a block's span starts here so the blank lines before it stay with it. */
+    let prevEnd = 0;
     for (const child of tree.children) {
+        const { start: blockStart, end: blockEnd } = offsetsOf(child);
+        const spanStart = prevEnd;
+        prevEnd = blockEnd;
+        /** Give a node this block as source content, minus any `removed` ranges inside it. */
+        const claimBlock = (node, removed = []) => {
+            let from = blockStart;
+            let first = true;
+            for (const gap of removed) {
+                if (first)
+                    claim(claims, node, spanStart, blockStart, gap.start);
+                else
+                    addRange(claims, node, from, gap.start);
+                first = false;
+                from = gap.end;
+            }
+            if (first)
+                claim(claims, node, spanStart, blockStart, blockEnd);
+            else
+                addRange(claims, node, from, blockEnd);
+        };
+        /** Take this whole block out of a node's content, keeping the blank lines before it. */
+        const consumeBlock = (node) => consume(claims, node, spanStart, blockStart);
         if (parseState === 'done') {
             if (child.type === 'heading') {
                 const rawTitle = mdastToString(child);
@@ -436,8 +550,11 @@ export function extractEmbeddedNodes(body, options) {
         if (child.type === 'heading') {
             const heading = child;
             const depth = heading.depth;
-            if (depth > 5)
+            if (depth > 5) {
+                if (parseState === 'active')
+                    claimBlock(activeNode);
                 continue;
+            }
             parseState = 'active';
             const rawText = mdastToString(heading);
             const { cleanText: afterBracketed, fields: rawInlineFields } = extractBracketedFields(rawText);
@@ -455,6 +572,10 @@ export function extractEmbeddedNodes(body, options) {
                 stack.push({ depth, title, nodeType: '', refTarget: title });
                 // Discard any pending grouping (untyped heading has no implied type)
                 grouping = null;
+                // An untyped heading is part of the body of the nearest enclosing node. Popping above removed every
+                // node at the same or a higher level, so those sections end here; deeper nodes' sections continue.
+                activeNode = stack.findLast((entry) => entry.node)?.node ?? rootNode;
+                claimBlock(activeNode);
                 continue;
             }
             if (isOnAPageMode && stack.length > 0) {
@@ -494,7 +615,7 @@ export function extractEmbeddedNodes(body, options) {
             };
             // Push to stack BEFORE resolving semantic parent — stack[-2] is the correct parent.
             const refTarget = linkTargets[0] ?? title;
-            stack.push({ depth, title, nodeType: type, refTarget });
+            stack.push({ depth, title, nodeType: type, refTarget, node: headingNode });
             // If this match came from a relationship/hierarchy and no explicit type was given,
             // create a grouping — delay adding the node until we see the following content.
             // Discard any previous grouping (not flushed — original agnostic-parse behaviour).
@@ -532,14 +653,16 @@ export function extractEmbeddedNodes(body, options) {
                 const activeNodeFieldAppendArg = isParentLevelMatch && semanticParent.node
                     ? { node: semanticParent.node, field: definition.field }
                     : undefined;
+                const walk = { claims, pos: spanStart };
                 for (const item of list.children) {
-                    processListItem(item, isParentSide ? undefined : semanticParent.ref, grouping.headingNode, nodes, makeLabel, buildListItemLinkTargets, typeAliases, fieldMap, definition.type, parentFieldAppendArg, activeNodeFieldAppendArg, options.file, options.lineOffset);
+                    processListItem(item, isParentSide ? undefined : semanticParent.ref, grouping.headingNode, nodes, makeLabel, buildListItemLinkTargets, typeAliases, fieldMap, definition.type, parentFieldAppendArg, activeNodeFieldAppendArg, options.file, options.lineOffset, walk);
                 }
                 grouping = null;
             }
             else {
+                const walk = { claims, pos: spanStart };
                 for (const item of list.children) {
-                    processListItem(item, parentRef, activeNode, nodes, makeLabel, buildListItemLinkTargets, typeAliases, fieldMap, undefined, undefined, undefined, options.file, options.lineOffset);
+                    processListItem(item, parentRef, activeNode, nodes, makeLabel, buildListItemLinkTargets, typeAliases, fieldMap, undefined, undefined, undefined, options.file, options.lineOffset, walk);
                 }
             }
         }
@@ -648,7 +771,7 @@ export function extractEmbeddedNodes(body, options) {
                     grouping = null;
                 }
                 else {
-                    appendContent(activeNode, mdastToString(child));
+                    claimBlock(activeNode);
                 }
             }
         }
@@ -662,38 +785,52 @@ export function extractEmbeddedNodes(body, options) {
             if (child.type === 'paragraph') {
                 const rawText = mdastToString(child);
                 const { cleanText: afterBracketed, fields: bracketedFields } = extractBracketedFields(rawText);
-                const { remainingText, fields: unbracketedFields } = extractUnbracketedFields(afterBracketed);
+                const { fields: unbracketedFields } = extractUnbracketedFields(afterBracketed);
                 const allFields = applyFieldMap({ ...unbracketedFields, ...bracketedFields }, fieldMap);
                 if ('type' in allFields) {
                     throw new Error(`Type override via paragraph field is not supported at "${activeNode.schemaData.title ?? activeNode.label}". ` +
                         `Put [type:: ${allFields.type}] directly in the heading text.`);
                 }
                 Object.assign(activeNode.schemaData, allFields);
-                if (remainingText)
-                    appendContent(activeNode, remainingText);
+                // Lines holding only fields are consumed as fields; any other line, including prose that mentions a field, is content.
+                const lines = sourceLines(body, { start: blockStart, end: blockEnd });
+                const fieldLines = lines.filter((l) => isFieldOnlyLine(l.text));
+                if (fieldLines.length === lines.length) {
+                    consumeBlock(activeNode);
+                }
+                else {
+                    // Each field line goes with its terminator; a last line without one takes the preceding line break instead.
+                    claimBlock(activeNode, fieldLines.map((l) => {
+                        if (/\n$/.test(body.slice(l.start, l.end)))
+                            return { start: l.start, end: l.end };
+                        return { start: l.start - (body[l.start - 2] === '\r' ? 2 : 1), end: l.end };
+                    }));
+                }
                 activeNode.contentLinks ??= [];
                 activeNode.contentLinks.push(...extractLinksFromAstNode(child));
             }
             else if (child.type === 'code' && child.lang?.trim() === 'yaml') {
                 const code = child;
-                const parsed = yamlLoad(code.value);
+                const parsed = parseYaml(code.value);
                 if (parsed && !Array.isArray(parsed) && typeof parsed === 'object') {
-                    Object.assign(activeNode.schemaData, coerceDates(applyFieldMap(parsed, fieldMap)));
+                    Object.assign(activeNode.schemaData, applyFieldMap(parsed, fieldMap));
+                    consumeBlock(activeNode);
                 }
                 else if (Array.isArray(parsed)) {
                     throw new Error(`YAML block must be an object at "${activeNode.label}".`);
                 }
                 else {
-                    appendContent(activeNode, code.value);
+                    claimBlock(activeNode);
                 }
             }
             else {
-                appendContent(activeNode, mdastToString(child));
+                claimBlock(activeNode);
                 activeNode.contentLinks ??= [];
                 activeNode.contentLinks.push(...extractLinksFromAstNode(child));
             }
         }
     }
+    applyClaims(claims, body);
     const preambleContent = rootNode.schemaData.content;
     const { type: _rootType, content: _rootContent, ...preambleFields } = rootNode.schemaData;
     return {