@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/report-model/block-walk.d.ts

@@ -41,48 +41,48 @@ export declare function statisticSlot(index: number): ChartSlot;
  * chart grammar names, and the track and each tree carry each column that they name, thus the structural tier
  * and the value tier match the same set.
  */
-export interface CollectedReference {
+export type CollectedReference = {
     blockId: string;
     reference: Reference;
     slot?: ChartSlot;
     encodingColumns?: string[];
-}
+};
 /** An advisory warning about the prose of one block. The detail is the numeral that the prose carries. */
-export interface FreeNumeralWarning {
+export type FreeNumeralWarning = {
     blockId: string;
     kind: "free-numeral";
     detail: string;
-}
+};
 /**
  * An advisory warning about one exponent form that the prose of a block carries and the page never prints.
  * The detail is the written form.
  */
-export interface ExponentFormWarning {
+export type ExponentFormWarning = {
     blockId: string;
     kind: "exponent-form";
     detail: string;
-}
+};
 /** One advisory warning about the prose of a block. */
 export type ProseWarning = FreeNumeralWarning | ExponentFormWarning;
 /**
  * An advisory warning about one derivation that no binding of the document names. The detail is the output
  * path of the record. The record stays, and the bytes are reproducible from the script and the sources.
  */
-export interface UnusedDerivationWarning {
+export type UnusedDerivationWarning = {
     kind: "unused-derivation";
     detail: string;
-}
+};
 /** One advisory warning about a report. A warning never makes a report invalid. */
 export type ReportWarning = ProseWarning | UnusedDerivationWarning;
 /** What one walk over a block tree found. */
-export interface BlockWalk {
+export type BlockWalk = {
     /** Each reference, in document order, tied to the block that carries it. */
     references: CollectedReference[];
     /** Each id that more than one block holds, named one time, in sorted order. */
     repeatedIds: string[];
     /** Each free numeral and each drifted exponent form that prose carries. */
     warnings: ProseWarning[];
-}
+};
 /** Warn for each free-standing numeral that the prose of one block carries. */
 export declare function numeralWarnings(blockId: string, prose: string): FreeNumeralWarning[];
 /**

package/dist/report-model/block-walk.js

@@ -35,6 +35,7 @@ export function statisticSlot(index) {
  * can be a real free-standing figure or a harmless part of a name. Thus a hit warns, and it never fails
  * the report.
  */
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- a free-standing numeral with its optional sign, percent, and decimals; the lookbehind keeps a symbol such as `TP53` outside the match.
 const NUMERAL_PATTERN = /(?<![A-Za-z0-9])-?\d+(?:\.\d+)?%?/g;
 /**
  * A free-standing token that states a number in an exponent form, for example `4.3e-05`.
@@ -42,6 +43,7 @@ const NUMERAL_PATTERN = /(?<![A-Za-z0-9])-?\d+(?:\.\d+)?%?/g;
  * The left boundary is the one of the numeral scan, thus a token inside a name never matches. The exponent
  * itself carries an optional sign, because a written form gives one and a shown form never does.
  */
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the same left boundary with the exponent tail, so one warning names the exponent form and not its coefficient alone.
 const EXPONENT_PATTERN = /(?<![A-Za-z0-9])-?\d+(?:\.\d+)?[eE][+-]?\d+/g;
 /** Warn for each free-standing numeral that the prose of one block carries. */
 export function numeralWarnings(blockId, prose) {

package/dist/report-model/draft-finish.d.ts

@@ -31,26 +31,26 @@ import { type ChartSlot, type ReportWarning } from "./block-walk.js";
 import type { DraftDocument } from "./draft.js";
 import type { ReportSnapshot } from "./reference-resolver.js";
 /** A schema conformance gap, reduced to a path and a message. */
-export interface SchemaGap {
+export type SchemaGap = {
     kind: "schema";
     path: string;
     message: string;
-}
+};
 /** A duplicate id gap. More than one block holds the id. */
-export interface DuplicateIdGap {
+export type DuplicateIdGap = {
     kind: "duplicate-id";
     id: string;
-}
+};
 /**
  * An unresolved reference gap. It ties the block that carries the reference to the reason it did not resolve.
  * `slot` names the place of the reference inside a chart block: the binding, the track, a tree, or one statistic.
  */
-export interface UnresolvedReferenceGap {
+export type UnresolvedReferenceGap = {
     kind: "unresolved-reference";
     blockId: string;
     slot?: ChartSlot;
     failure: UnresolvedReference;
-}
+};
 /** One completeness gap of a draft. The kind set is closed. */
 export type FinishGap = SchemaGap | DuplicateIdGap | UnresolvedReferenceGap;
 /**
@@ -70,9 +70,9 @@ export type FinishResult = {
  * One derivation of the session, as the finish reads it. The finish needs the output path alone, because
  * the used set is the paths that the bindings name.
  */
-export interface SessionDerivation {
+export type SessionDerivation = {
     readonly outputPath: string;
-}
+};
 /**
  * Finish a draft. The finish validates the schema, the unique ids, and the structural resolution of each
  * reference, and it reports each gap as data. It warns about each free numeral in prose, and about each

package/dist/report-model/draft-finish.js

@@ -79,7 +79,7 @@ export function finishDraft(draft, snapshot, derivations = []) {
             gaps.push({
                 kind: "unresolved-reference",
                 blockId: entry.blockId,
-                ...(entry.slot !== undefined ? { slot: entry.slot } : {}),
+                slot: entry.slot,
                 failure: result.error,
             });
         }

package/dist/report-model/draft-hash.js

@@ -10,6 +10,7 @@
  * give one hash, and a marker survives a round trip through storage.
  */
 import { createHash } from "node:crypto";
+import { parseUnknownRecord } from "../lib/unknown-containers.js";
 /**
  * Give back a copy of a value with each object key in sorted order, at every depth.
  *
@@ -20,14 +21,14 @@ function canonicalize(value) {
     if (Array.isArray(value)) {
         return value.map(canonicalize);
     }
-    if (value !== null && typeof value === "object") {
-        const sorted = {};
-        for (const key of Object.keys(value).sort()) {
-            sorted[key] = canonicalize(value[key]);
-        }
-        return sorted;
+    const record = parseUnknownRecord(value);
+    if (record === undefined)
+        return value;
+    const sorted = {};
+    for (const key of Object.keys(record).sort()) {
+        sorted[key] = canonicalize(record[key]);
     }
-    return value;
+    return sorted;
 }
 /** The sha256 hash of the draft, over a JSON serialization with sorted keys. */
 export function computeDraftHash(document) {

package/dist/report-model/draft-operations.d.ts

@@ -47,15 +47,15 @@ export type DraftPlace = "start" | "end" | {
     after: string;
 };
 /** The destination of an add or a move. `parentId` names a section, or the root when it is absent. */
-export interface DraftDestination {
+export type DraftDestination = {
     parentId?: string;
     place?: DraftPlace;
-}
+};
 /** The add operation value. The payload can be an atom, or a section that carries children. */
-export interface AddOperation {
+export type AddOperation = {
     block: unknown;
     destination?: DraftDestination;
-}
+};
 /**
  * The change operation value. A `title` retitles a section target. A `block` replaces an atom target.
  * The operation stamps the target id on the block, thus an id mismatch is unrepresentable.
@@ -68,14 +68,14 @@ export type ChangeOperation = {
     block: unknown;
 });
 /** The remove operation value. It names one block by its id. */
-export interface RemoveOperation {
+export type RemoveOperation = {
     targetId: string;
-}
+};
 /** The move operation value. It names one block, and a destination with the shape of the add destination. */
-export interface MoveOperation {
+export type MoveOperation = {
     targetId: string;
     destination?: DraftDestination;
-}
+};
 /**
  * Set the title of the document.
  *
@@ -114,15 +114,27 @@ export declare function removeBlock(draft: DraftDocument, operation: RemoveOpera
  */
 export declare function moveBlock(draft: DraftDocument, operation: MoveOperation, snapshot: ReportSnapshot): Result<DraftDocument, DraftRefusal>;
 /** One block, the path of child indices from the root to the block, and the section that holds it. */
-export interface Located {
+export type Located = {
     block: DraftBlock;
     path: number[];
+    /** The path of the container that holds the block, empty when the container is the root. */
+    containerPath: number[];
+    /** The index of the block inside its container. */
+    index: number;
     /** The section that holds the block, or `undefined` when the block sits at the root. */
     parent?: DraftSectionBlock;
-}
+};
 /**
  * Find a block by its id, with the path from the root. The search visits each block one time.
  *
  * The read surface needs the same search, thus this is the one find-by-id in the draft model.
  */
 export declare function locate(document: DraftDocument, id: string): Located | undefined;
+/**
+ * Rebuild the document with new children at a container path, and share each untouched branch.
+ *
+ * The root holds sections only, thus a root path with a child that is not a section refuses with
+ * `atom-at-root` and gives no candidate. Each operation refuses an atom at the root before it builds a
+ * candidate, thus no operation reaches this refusal.
+ */
+export declare function setChildren(document: DraftDocument, containerPath: number[], children: DraftBlock[]): Result<DraftDocument, DraftRefusal>;

package/dist/report-model/draft-operations.js

@@ -16,6 +16,7 @@
  * an anchor id stays stable.
  */
 import { err, ok } from "neverthrow";
+import { parseUnknownRecord } from "../lib/unknown-containers.js";
 import { walkBlocks } from "./block-walk.js";
 import { DraftBlockSchema } from "./draft.js";
 import { stampReferenceHashes } from "./reference-stamp.js";
@@ -52,8 +53,7 @@ export function addBlock(draft, operation, snapshot) {
         if (destination.parentIsRoot && block.kind !== "section") {
             return err({ reason: "atom-at-root", detail: `a ${block.kind} block cannot sit at the root` });
         }
-        const candidate = insertAt(draft, destination.containerPath, destination.index, block);
-        return commit(candidate, block, snapshot);
+        return insertAt(draft, destination.containerPath, destination.index, block).andThen((candidate) => commit(candidate, block, snapshot));
     });
 }
 /**
@@ -67,20 +67,19 @@ export function changeBlock(draft, operation, snapshot) {
     if (target === undefined) {
         return err({ reason: "unknown-target", detail: `no block holds the id ${operation.targetId}` });
     }
-    const containerPath = target.path.slice(0, -1);
-    const index = target.path[target.path.length - 1];
+    const { containerPath, index } = target;
     if (target.block.kind === "section") {
         if (!("title" in operation)) {
             return err({ reason: "payload-kind-mismatch", detail: `the section ${operation.targetId} takes a title, not a block payload` });
         }
         const retitled = { ...target.block, title: operation.title };
-        return commit(replaceAt(draft, containerPath, index, retitled), undefined, snapshot);
+        return replaceAt(draft, containerPath, index, retitled).andThen((candidate) => commit(candidate, undefined, snapshot));
     }
     if ("title" in operation) {
         return err({ reason: "payload-kind-mismatch", detail: `the block ${operation.targetId} is an atom, and it takes a full block, not a title` });
     }
-    const payload = operation.block;
-    if (payload === null || typeof payload !== "object") {
+    const payload = parseUnknownRecord(operation.block);
+    if (payload === undefined) {
         return err({ reason: "malformed-block", detail: "the payload is not an object" });
     }
     // The id stamp sets the target id on the payload before the parse. Thus an id mismatch is
@@ -99,7 +98,8 @@ export function changeBlock(draft, operation, snapshot) {
     if (parsed.data.kind === "section") {
         return err({ reason: "payload-kind-mismatch", detail: `the block ${operation.targetId} is an atom, and it cannot take a section payload` });
     }
-    return commit(replaceAt(draft, containerPath, index, parsed.data), parsed.data, snapshot);
+    const replacement = parsed.data;
+    return replaceAt(draft, containerPath, index, replacement).andThen((candidate) => commit(candidate, replacement, snapshot));
 }
 /**
  * Remove one block by its id.
@@ -111,9 +111,8 @@ export function removeBlock(draft, operation, snapshot) {
     if (target === undefined) {
         return err({ reason: "unknown-target", detail: `no block holds the id ${operation.targetId}` });
     }
-    const containerPath = target.path.slice(0, -1);
-    const index = target.path[target.path.length - 1];
-    return commit(removeAt(draft, containerPath, index), undefined, snapshot);
+    const { containerPath, index } = target;
+    return removeAt(draft, containerPath, index).andThen((candidate) => commit(candidate, undefined, snapshot));
 }
 /**
  * Move one block to a destination.
@@ -129,7 +128,7 @@ export function moveBlock(draft, operation, snapshot) {
     const movedBlock = target.block;
     const movedPath = target.path;
     const place = operation.destination?.place;
-    if (place !== undefined && typeof place === "object") {
+    if (place !== undefined && place !== "start" && place !== "end") {
         const anchorId = "before" in place ? place.before : place.after;
         if (anchorId === operation.targetId) {
             return err({ reason: "unknown-target", detail: `the block ${operation.targetId} cannot anchor its own move` });
@@ -144,13 +143,11 @@ export function moveBlock(draft, operation, snapshot) {
         if (movedBlock.kind === "section" && isPrefix(movedPath, destination.containerPath)) {
             return err({ reason: "cycle", detail: `the section ${operation.targetId} cannot move into its own subtree` });
         }
-        const afterRemove = removeAt(draft, movedPath.slice(0, -1), movedPath[movedPath.length - 1]);
         // The removal shifts the sibling indices of the old parent. Thus the destination resolves again
         // against the reduced tree, and the fresh path and index address the correct place.
-        return resolveDestination(afterRemove, operation.destination).andThen((landing) => {
-            const candidate = insertAt(afterRemove, landing.containerPath, landing.index, movedBlock);
-            return commit(candidate, undefined, snapshot);
-        });
+        return removeAt(draft, target.containerPath, target.index).andThen((afterRemove) => resolveDestination(afterRemove, operation.destination)
+            .andThen((landing) => insertAt(afterRemove, landing.containerPath, landing.index, movedBlock))
+            .andThen((candidate) => commit(candidate, undefined, snapshot)));
     });
 }
 /**
@@ -162,14 +159,14 @@ export function moveBlock(draft, operation, snapshot) {
 function resolveDestination(document, destination) {
     const place = destination?.place ?? "end";
     const parentId = destination?.parentId;
-    if (typeof place === "object") {
+    if (place !== "start" && place !== "end") {
         const anchorId = "before" in place ? place.before : place.after;
         const anchor = locate(document, anchorId);
         if (anchor === undefined) {
             return err({ reason: "unknown-target", detail: `no block holds the anchor id ${anchorId}` });
         }
-        const containerPath = anchor.path.slice(0, -1);
-        const anchorIndex = anchor.path[anchor.path.length - 1];
+        const containerPath = anchor.containerPath;
+        const anchorIndex = anchor.index;
         const parentIsRoot = containerPath.length === 0;
         if (parentId !== undefined && idAtPath(document, containerPath) !== parentId) {
             return err({ reason: "unknown-target", detail: `the parent ${parentId} does not hold the anchor ${anchorId}` });
@@ -235,11 +232,11 @@ export function locate(document, id) {
     return locateInBlocks(document.sections, id, [], undefined);
 }
 function locateInBlocks(blocks, id, prefix, parent) {
-    for (let index = 0; index < blocks.length; index++) {
-        const block = blocks[index];
+    for (const [index, block] of blocks.entries()) {
         const path = [...prefix, index];
         if (block.id === id) {
-            return parent === undefined ? { block, path } : { block, path, parent };
+            const located = { block, path, containerPath: prefix, index };
+            return parent === undefined ? located : { ...located, parent };
         }
         if (block.kind === "section") {
             const found = locateInBlocks(block.blocks, id, path, block);
@@ -270,7 +267,7 @@ function getChildren(document, containerPath) {
     let blocks = document.sections;
     for (const index of containerPath) {
         const node = blocks[index];
-        if (node.kind !== "section") {
+        if (node === undefined || node.kind !== "section") {
             // A container path names a section at each step, thus this branch never runs.
             return [];
         }
@@ -278,19 +275,36 @@ function getChildren(document, containerPath) {
     }
     return blocks;
 }
-/** Rebuild the document with new children at a container path, and share each untouched branch. */
-function setChildren(document, containerPath, children) {
+/** Give `true` when every member of the list is a section. The root of a draft holds sections alone. */
+function isSectionBlocks(blocks) {
+    return blocks.every((block) => block.kind === "section");
+}
+/**
+ * Rebuild the document with new children at a container path, and share each untouched branch.
+ *
+ * The root holds sections only, thus a root path with a child that is not a section refuses with
+ * `atom-at-root` and gives no candidate. Each operation refuses an atom at the root before it builds a
+ * candidate, thus no operation reaches this refusal.
+ */
+export function setChildren(document, containerPath, children) {
     if (containerPath.length === 0) {
-        // The root holds sections only. Each operation enforces that rule before it builds a candidate.
-        return { ...document, sections: children };
+        if (!isSectionBlocks(children)) {
+            const atom = children.find((child) => child.kind !== "section");
+            return err({ reason: "atom-at-root", detail: `a ${atom?.kind ?? "non-section"} block cannot sit at the root` });
+        }
+        return ok({ ...document, sections: children });
     }
-    return { ...document, sections: setChildrenInBlocks(document.sections, containerPath, children) };
+    return ok({ ...document, sections: setChildrenInBlocks(document.sections, containerPath, children) });
 }
 function setChildrenInBlocks(blocks, containerPath, children) {
     const head = containerPath[0];
+    if (head === undefined) {
+        // setChildren splits off the root before it calls here, thus the path carries an index.
+        return blocks;
+    }
     const rest = containerPath.slice(1);
     const target = blocks[head];
-    if (target.kind !== "section") {
+    if (target === undefined || target.kind !== "section") {
         // A container path names a section at each step, thus this branch never runs.
         return blocks;
     }
@@ -349,6 +363,10 @@ function isPrefix(prefix, path) {
 /** Reduce a parse failure to a `malformed-block` refusal that names the first fault. */
 function malformed(error) {
     const issue = error.issues[0];
+    if (issue === undefined) {
+        // A ZodError carries at least one issue, thus this branch never runs.
+        return { reason: "malformed-block", detail: "the block does not match the draft grammar" };
+    }
     const location = issue.path.map((segment) => String(segment)).join(".");
     const detail = location.length > 0 ? `${location}: ${issue.message}` : issue.message;
     return { reason: "malformed-block", detail };

package/dist/report-model/draft-read.d.ts

@@ -13,18 +13,19 @@
  * A read gives each binding with no hash. The pinned snapshot owns that value, thus an echoed hash would
  * give the agent a value to mistype.
  */
-import type { AuthoringAtomBlock } from "./authoring-grammar.js";
+import { type Result } from "neverthrow";
+import { type AuthoringAtomBlock } from "./authoring-grammar.js";
 import type { DraftBlock, DraftDocument } from "./draft.js";
 /**
  * One outline entry. It carries the id, the kind, the nesting depth, and a short label. A top-level
  * section is depth 0. The entry carries no binding, thus the outline stays small.
  */
-export interface OutlineEntry {
+export type OutlineEntry = {
     id: string;
     kind: DraftBlock["kind"];
     depth: number;
     label: string;
-}
+};
 /**
  * A section as the read surface gives it: its own fields, and the id of each child in document order.
  *
@@ -32,12 +33,12 @@ export interface OutlineEntry {
  * subtree would be a second copy of the outline, and a read of a top-level section would return the whole
  * draft.
  */
-export interface ShallowSection {
+export type ShallowSection = {
     kind: "section";
     id: string;
     title: string;
     childIds: string[];
-}
+};
 /** One block as the read surface gives it. An atom reads in full and hash-free, and a section reads shallow. */
 export type ReadableBlock = AuthoringAtomBlock | ShallowSection;
 /**
@@ -55,8 +56,19 @@ export declare function buildOutline(draft: DraftDocument): OutlineEntry[];
  * `depth` is the depth of the children, thus the entries read the same as the entries of a full outline.
  */
 export declare function childOutline(blocks: readonly DraftBlock[], depth: number): OutlineEntry[];
+/**
+ * A stored atom that the authoring grammar refuses. The draft grammar admits every stored atom, and the
+ * read gives the atom in the authoring grammar. The two grammars differ in the stamped hash alone, thus
+ * this failure shows drift between them, not a missing block.
+ */
+export type AtomRefusedByAuthoringGrammar = {
+    type: "atom-refused-by-authoring-grammar";
+    id: string;
+    cause: unknown;
+};
 /**
  * Read one block by its id. An atom gives the block with its bindings, and each binding gives no hash. A
- * section gives its own fields and the id of each child. A block that no id holds gives `undefined`.
+ * section gives its own fields and the id of each child. A block that no id holds gives `undefined`. A
+ * stored atom that the authoring grammar refuses gives an error that names the id.
  */
-export declare function readBlock(draft: DraftDocument, id: string): ReadableBlock | undefined;
+export declare function readBlock(draft: DraftDocument, id: string): Result<ReadableBlock | undefined, AtomRefusedByAuthoringGrammar>;

package/dist/report-model/draft-read.js

@@ -13,7 +13,9 @@
  * A read gives each binding with no hash. The pinned snapshot owns that value, thus an echoed hash would
  * give the agent a value to mistype.
  */
+import { err, ok } from "neverthrow";
 import { locate } from "./draft-operations.js";
+import { AuthoringBlockSchema } from "./authoring-grammar.js";
 import { stripReferenceHashes } from "./reference-stamp.js";
 /** The label keeps a prose head of at most this many code points. A clipped label ends with the marker. */
 const PROSE_CLIP = 80;
@@ -31,7 +33,7 @@ const CLIP_MARKER = "…";
  * were the whole one.
  */
 function clip(text) {
-    const points = [...text];
+    const points = Array.from(text);
     if (points.length <= PROSE_CLIP) {
         return text;
     }
@@ -109,17 +111,25 @@ export function childOutline(blocks, depth) {
 }
 /**
  * Read one block by its id. An atom gives the block with its bindings, and each binding gives no hash. A
- * section gives its own fields and the id of each child. A block that no id holds gives `undefined`.
+ * section gives its own fields and the id of each child. A block that no id holds gives `undefined`. A
+ * stored atom that the authoring grammar refuses gives an error that names the id.
  */
 export function readBlock(draft, id) {
     const found = locate(draft, id)?.block;
     if (found === undefined) {
-        return undefined;
+        return ok(undefined);
     }
     if (found.kind === "section") {
-        return { kind: "section", id: found.id, title: found.title, childIds: found.blocks.map((child) => child.id) };
+        return ok({ kind: "section", id: found.id, title: found.title, childIds: found.blocks.map((child) => child.id) });
     }
     // The stored atom and the read atom differ in the stamped hash alone, and the walk removes that field.
-    // Thus the assertion states what the walk did.
-    return stripReferenceHashes(found);
+    const atom = AuthoringBlockSchema.safeParse(stripReferenceHashes(found));
+    if (!atom.success) {
+        return err({ type: "atom-refused-by-authoring-grammar", id, cause: atom.error });
+    }
+    if (atom.data.kind === "section") {
+        // The walk keeps the kind of a stored atom, thus this branch never runs. It refuses and does not give a section as an atom.
+        return err({ type: "atom-refused-by-authoring-grammar", id, cause: atom.data });
+    }
+    return ok(atom.data);
 }