@itookit/dsht 0.5.1 → 0.6.0

package/dist/controller/loop-prompts-schema.js

@@ -2,7 +2,11 @@
  *
  * Kept apart from `loop-prompts.ts` so the build script can validate a YAML file before the
  * generated module exists: this module imports nothing, while the renderer imports the generated
- * data. The validator is the single copy of the schema — the generator and the tests both call it.
+ * data. The validator is the single copy of the schema — the generator, the runtime loader and the
+ * tests all call it, so a file that passes here is the one the renderer will read.
+ *
+ * Two entry points share one set of rules: `validateLoopPrompts` checks a whole built-in file, and
+ * `validateLoopOverlayPrompts` checks a user file that may carry only the records it changes.
  */
 /** Placeholders every template may use; a record's own `vars` add to these. */
 export const LOOP_PLACEHOLDERS = ['from', 'to', 'score', 'tries', 'step', 'attempt', 'title', 'artifact', 'checks'];
@@ -16,18 +20,94 @@ export const RESERVED_PROTOCOL_NAMES = ['answer', 'abort', 'stop'];
  */
 export function validateLoopPrompts(source) {
     const errors = [];
-    const document = source;
-    if (document?.version !== 1)
+    const document = asDocument(source);
+    if (document.version !== 1)
         errors.push('version must be 1');
-    if (!Number.isFinite(document?.defaults?.score))
-        errors.push('defaults.score must be a number');
-    if (!Number.isFinite(document?.defaults?.tries))
-        errors.push('defaults.tries must be a number');
-    const protocols = document?.protocols;
-    if (protocols === null || typeof protocols !== 'object' || Object.keys(protocols ?? {}).length === 0) {
+    validateDefaults(document.defaults, errors, true);
+    const protocols = document.protocols;
+    if (protocols === null || typeof protocols !== 'object' || Array.isArray(protocols) || Object.keys(protocols ?? {}).length === 0) {
         errors.push('protocols must be a non-empty mapping');
         return errors;
     }
+    validateProtocols(protocols, errors);
+    return errors;
+}
+/** Check a user file that layers over the shipped records.
+ *
+ * It is a whole `loop.yaml` in shape, but partial in content: an overlay that only adds one record
+ * or only moves the global defaults is exactly what it is for, so a missing or empty `protocols` is
+ * valid here. Every record it does declare is held to the same rules as a shipped one, because the
+ * renderer cannot tell the two apart once they are merged.
+ * @param source - Parsed overlay file.
+ * @returns One message per problem; an empty list means valid.
+ */
+export function validateLoopOverlayPrompts(source) {
+    const errors = [];
+    const document = asDocument(source);
+    // A version is required even from an overlay: a file written for a later shape must fail loudly
+    // instead of having its fields read as this shape's, which is how a silent misread becomes a run
+    // judged against a rubric nobody wrote.
+    if (document.version !== 1)
+        errors.push('version must be 1');
+    validateDefaults(document.defaults, errors, false);
+    const protocols = document.protocols;
+    if (protocols === undefined || protocols === null)
+        return errors;
+    if (typeof protocols !== 'object' || Array.isArray(protocols)) {
+        errors.push('protocols must be a mapping');
+        return errors;
+    }
+    validateProtocols(protocols, errors);
+    return errors;
+}
+/** A parsed document with every unsafe value normalized to `undefined`.
+ * @param source - Anything a caller parsed out of a file.
+ * @returns The document, or an empty one for a null, scalar or array root.
+ */
+function asDocument(source) {
+    return source !== null && typeof source === 'object' && !Array.isArray(source) ? source : {};
+}
+/** Check the global defaults.
+ *
+ * A shipped file must state them, because every record falls back to them. An overlay may state
+ * neither, one or both, but a value it does state reaches real runs, so it is checked for range
+ * even though the shipped file only has to be numeric.
+ * @param defaults - The `defaults` field as parsed.
+ * @param errors - Collector to append messages to.
+ * @param required - Whether this document must carry both numbers.
+ */
+function validateDefaults(defaults, errors, required) {
+    if (defaults === undefined || defaults === null) {
+        if (required) {
+            errors.push('defaults.score must be a number');
+            errors.push('defaults.tries must be a number');
+        }
+        return;
+    }
+    if (typeof defaults !== 'object' || Array.isArray(defaults)) {
+        errors.push('defaults must be a mapping');
+        return;
+    }
+    const { score, tries } = defaults;
+    if (required) {
+        if (!Number.isFinite(score))
+            errors.push('defaults.score must be a number');
+        if (!Number.isFinite(tries))
+            errors.push('defaults.tries must be a number');
+        return;
+    }
+    if (score !== undefined && (!Number.isFinite(score) || score < 0 || score > 10)) {
+        errors.push('defaults.score must be a number in 0-10');
+    }
+    if (tries !== undefined && (!Number.isInteger(tries) || tries < 1)) {
+        errors.push('defaults.tries must be a positive integer');
+    }
+}
+/** Check every record of one document against the rules the renderer relies on.
+ * @param protocols - The `protocols` mapping.
+ * @param errors - Collector to append messages to.
+ */
+function validateProtocols(protocols, errors) {
     const runtime = new Set(LOOP_PLACEHOLDERS);
     const reserved = new Set(RESERVED_PROTOCOL_NAMES);
     const placeholders = (text) => [...text.matchAll(/\{\{(\w+)\}\}/g)].map(match => match[1]);
@@ -36,7 +116,7 @@ export function validateLoopPrompts(source) {
         if (reserved.has(kind))
             errors.push(`${at} is a reserved name: ${RESERVED_PROTOCOL_NAMES.join(', ')} belong to /loop itself`);
         // A template may name a runtime value or one of this record's own vars, and nothing else.
-        const vars = protocol.vars;
+        const vars = protocol?.vars;
         if (vars !== undefined && (vars === null || typeof vars !== 'object' || Array.isArray(vars))) {
             errors.push(`${at}.vars must be a mapping of names to strings`);
         }
@@ -55,15 +135,15 @@ export function validateLoopPrompts(source) {
                 if (!allowed.has(name))
                     errors.push(`${where}: unknown placeholder {{${name}}}`);
         };
-        checkPlaceholders(typeof protocol.title === 'string' ? protocol.title : '', `${at}.title`);
-        if (typeof protocol.title !== 'string' || protocol.title === '')
+        checkPlaceholders(typeof protocol?.title === 'string' ? protocol.title : '', `${at}.title`);
+        if (typeof protocol?.title !== 'string' || protocol.title === '')
             errors.push(`${at}.title must be a non-empty string`);
-        if (!Number.isInteger(protocol.steps) || (protocol.steps ?? 0) < 1)
+        if (!Number.isInteger(protocol?.steps) || (protocol?.steps ?? 0) < 1)
             errors.push(`${at}.steps must be a positive integer`);
-        if (protocol.artifact !== undefined && (typeof protocol.artifact !== 'string' || protocol.artifact === '')) {
+        if (protocol?.artifact !== undefined && (typeof protocol.artifact !== 'string' || protocol.artifact === '')) {
             errors.push(`${at}.artifact must be a non-empty string when present`);
         }
-        else if (typeof protocol.artifact === 'string') {
+        else if (typeof protocol?.artifact === 'string') {
             // The file name may use the record's vars — that is how one run per input gets its own file —
             // but never a runtime placeholder: the artifact must not move between rounds.
             for (const name of placeholders(protocol.artifact)) {
@@ -72,7 +152,7 @@ export function validateLoopPrompts(source) {
                 }
             }
         }
-        if (protocol.artifactMarker !== undefined) {
+        if (protocol?.artifactMarker !== undefined) {
             if (typeof protocol.artifactMarker !== 'string' || protocol.artifactMarker.trim() === '') {
                 errors.push(`${at}.artifactMarker must be a non-empty string when present`);
             }
@@ -84,28 +164,28 @@ export function validateLoopPrompts(source) {
                 errors.push(`${at}.artifactMarker needs ${at}.artifact: there is no file to look in`);
             }
         }
-        if (typeof protocol.fallbackLabel !== 'string' || protocol.fallbackLabel === '')
+        if (typeof protocol?.fallbackLabel !== 'string' || protocol.fallbackLabel === '')
             errors.push(`${at}.fallbackLabel must be a non-empty string`);
-        if (protocol.standard !== undefined && (typeof protocol.standard !== 'string' || protocol.standard.trim() === '')) {
+        if (protocol?.standard !== undefined && (typeof protocol.standard !== 'string' || protocol.standard.trim() === '')) {
             errors.push(`${at}.standard must be a non-empty string when present`);
         }
-        if (protocol.starts !== undefined && protocol.starts !== 'verify' && protocol.starts !== 'work') {
+        if (protocol?.starts !== undefined && protocol.starts !== 'verify' && protocol.starts !== 'work') {
             errors.push(`${at}.starts must be 'verify' or 'work'`);
         }
-        if (protocol.defaults !== undefined) {
+        if (protocol?.defaults !== undefined) {
             const { score, tries } = protocol.defaults;
             if (score !== undefined && (!Number.isFinite(score) || score < 0 || score > 10))
                 errors.push(`${at}.defaults.score must be a number in 0-10`);
             if (tries !== undefined && (!Number.isInteger(tries) || tries < 1))
                 errors.push(`${at}.defaults.tries must be a positive integer`);
         }
-        const rounds = protocol.rounds;
+        const rounds = protocol?.rounds;
         if (!Array.isArray(rounds)) {
             errors.push(`${at}.rounds must be a list`);
         }
         else {
-            if (rounds.length > 0 && rounds.length !== protocol.steps) {
-                errors.push(`${at}.rounds has ${rounds.length} entries but steps is ${protocol.steps}`);
+            if (rounds.length > 0 && rounds.length !== protocol?.steps) {
+                errors.push(`${at}.rounds has ${rounds.length} entries but steps is ${protocol?.steps}`);
             }
             rounds.forEach((round, index) => {
                 if (typeof round?.title !== 'string' || round.title === '')
@@ -115,7 +195,7 @@ export function validateLoopPrompts(source) {
             });
         }
         for (const key of ['brief', 'followUp']) {
-            const lines = protocol[key];
+            const lines = protocol?.[key];
             if (!Array.isArray(lines) || lines.length === 0) {
                 errors.push(`${at}.${key} must be a non-empty list`);
                 continue;
@@ -128,17 +208,16 @@ export function validateLoopPrompts(source) {
                 checkPlaceholders(line, `${at}.${key}[${index}]`);
             });
         }
-        const checksLines = (protocol.brief ?? []).filter(line => typeof line === 'string' && line.trim() === '{{checks}}');
+        const checksLines = (protocol?.brief ?? []).filter(line => typeof line === 'string' && line.trim() === '{{checks}}');
         if ((rounds?.length ?? 0) > 0 && checksLines.length !== 1)
             errors.push(`${at}.brief must contain exactly one line that is just {{checks}}`);
         if ((rounds?.length ?? 0) === 0 && checksLines.length > 0)
             errors.push(`${at}.brief uses {{checks}} but defines no rounds`);
-        if (protocol.verifyFocus !== undefined) {
+        if (protocol?.verifyFocus !== undefined) {
             if (typeof protocol.verifyFocus !== 'string' || protocol.verifyFocus === '')
                 errors.push(`${at}.verifyFocus must be a non-empty string when present`);
             else
                 checkPlaceholders(protocol.verifyFocus, `${at}.verifyFocus`);
         }
     }
-    return errors;
 }

package/dist/controller/loop-prompts.d.ts

@@ -1,3 +1,5 @@
+import type { LoopSourceInfo } from '../contracts.ts';
+import type { LoopPromptSource } from './loop-prompts-schema.ts';
 export type { LoopPromptSource, LoopProtocolText, LoopRoundText } from './loop-prompts-schema.ts';
 /** Values one render call supplies; a record's `vars` are merged in on top of these. */
 export interface LoopPromptValues {
@@ -49,7 +51,20 @@ export interface LoopPrompts {
     /** One record's declared `vars`, unrendered, so a form can offer them before a run starts. */
     vars(kind: string): Readonly<Record<string, string>>;
 }
-/** The records of loop.yaml.
- * @returns Names, lookups and the declared vars of each record, built once.
+/** Put the records this process runs in place, before any run or record list reads them.
+ *
+ * The files are read and merged at startup rather than at module load, so a bad user file can be
+ * reported and refused before the client opens, and a run keeps the rubric it started with even if
+ * the file is edited underneath it.
+ * @param source - Merged records: shipped ones with the user's file layered on top.
+ * @param sourceInfo - Where they came from, and what the user's file changed.
+ */
+export declare function installLoopSource(source: LoopPromptSource, sourceInfo: LoopSourceInfo): void;
+/** Where the installed records came from.
+ * @returns The installed source info; the compiled-in records are the empty default.
+ */
+export declare function loopSourceInfo(): LoopSourceInfo;
+/** The records in force.
+ * @returns Names, lookups and the declared vars of each record, built once per installed source.
  */
 export declare function loopPrompts(): LoopPrompts;

package/dist/controller/loop-prompts.generated.js

@@ -1,5 +1,6 @@
 // GENERATED FILE — do not edit. Edit loop.yaml and run `npm run build:prompts`.
-// Kept in sync by tests/controller/loop-prompts.test.ts.
+// The fallback table: loop.yaml is read at runtime, and this is what a package whose file is
+// missing or unreadable starts on. Kept in sync by tests/controller/loop-prompts.test.ts.
 export const LOOP_PROMPTS = {
     "version": 1,
     "defaults": {

package/dist/controller/loop-prompts.js

@@ -1,14 +1,19 @@
 /** Typed access to the loop prompts and the placeholder renderer.
  *
- * `loop.yaml` is the editable source; `loop-prompts.generated.ts` is its inlined form and
- * `loop-prompts-schema.ts` holds the shape and the rules. This module turns one record into the
- * strings a protocol needs, so the dynamic parts (this round's title, its checklist, the record's
- * own vars) are filled here and nowhere else. A template may only use placeholders the caller can
- * supply; anything else throws rather than putting a literal `{{name}}` into a prompt.
+ * The loop record is configuration, not code: the shipped `loop.yaml` is read at startup from beside
+ * the package and a user file may be layered over it (`loop-source.ts`), then the merged table is
+ * installed here once. `loop-prompts-schema.ts` holds the shape and the rules, and
+ * `loop-prompts.generated.ts` is the compiled-in fallback for a package whose file is missing. This
+ * module turns one record into the strings a protocol needs, so the dynamic parts (this round's title,
+ * its checklist, the record's own vars) are filled here and nowhere else. A template may only use
+ * placeholders the caller can supply; anything else throws rather than putting a literal `{{name}}`
+ * into a prompt.
  */
 import { LOOP_PROMPTS } from "./loop-prompts.generated.js";
 const PLACEHOLDER = /\{\{(\w+)\}\}/g;
-const SOURCE = LOOP_PROMPTS;
+/** The records in force: the shipped file with the user's layered on top, installed once at startup
+ * and replaced only by another install, never by a reload while a run is in flight. */
+let SOURCE = LOOP_PROMPTS;
 /** Replace every `{{name}}` in one template list.
  * @param lines - Template lines.
  * @param values - Values keyed by placeholder name.
@@ -75,10 +80,31 @@ function render(kind, protocol, overrides) {
         followUp: runtime => fill(protocol.followUp, values(runtime), kind),
     };
 }
-/** All records, rendered once at module load: the config cannot change under a running client. */
+/** All records, rendered when the source is installed: a file edited mid-run cannot change a brief. */
 let cache;
-/** The records of loop.yaml.
- * @returns Names, lookups and the declared vars of each record, built once.
+/** Where the installed records came from, for the record list to show. */
+let info = { overridden: [], added: [], warnings: [] };
+/** Put the records this process runs in place, before any run or record list reads them.
+ *
+ * The files are read and merged at startup rather than at module load, so a bad user file can be
+ * reported and refused before the client opens, and a run keeps the rubric it started with even if
+ * the file is edited underneath it.
+ * @param source - Merged records: shipped ones with the user's file layered on top.
+ * @param sourceInfo - Where they came from, and what the user's file changed.
+ */
+export function installLoopSource(source, sourceInfo) {
+    SOURCE = source;
+    info = { ...sourceInfo, overridden: [...sourceInfo.overridden], added: [...sourceInfo.added], warnings: [...sourceInfo.warnings] };
+    cache = undefined;
+}
+/** Where the installed records came from.
+ * @returns The installed source info; the compiled-in records are the empty default.
+ */
+export function loopSourceInfo() {
+    return info;
+}
+/** The records in force.
+ * @returns Names, lookups and the declared vars of each record, built once per installed source.
  */
 export function loopPrompts() {
     if (cache !== undefined)

package/dist/controller/loop-protocols.d.ts

@@ -5,7 +5,9 @@ export declare function loopProtocolNames(): string[];
 /** Every record `/loop` may run, in file order, with the defaults a run would start from.
  *
  * The list and the run read the same records, so a chooser can show exactly the name, round count,
- * artifact and defaults the runner would use — never a second table that could drift.
+ * artifact and defaults the runner would use — never a second table that could drift. A record the
+ * user's own file supplied is marked, because an operator who overrode a shipped record can no longer
+ * tell the two apart from the name alone.
  * @returns One summary per record.
  */
 export declare function loopRecords(): LoopRecord[];

package/dist/controller/loop-protocols.js

@@ -6,7 +6,7 @@
  * record without code knowing which one it is.
  */
 import { LOOP_MARKER, followUpContract, resultContract, verdictBrief } from "./loop-contract.js";
-import { loopPrompts } from "./loop-prompts.js";
+import { loopPrompts, loopSourceInfo } from "./loop-prompts.js";
 import { coversWholeProtocol } from "./loop.js";
 /** Names `/loop` may run, in file order. */
 export function loopProtocolNames() {
@@ -15,10 +15,14 @@ export function loopProtocolNames() {
 /** Every record `/loop` may run, in file order, with the defaults a run would start from.
  *
  * The list and the run read the same records, so a chooser can show exactly the name, round count,
- * artifact and defaults the runner would use — never a second table that could drift.
+ * artifact and defaults the runner would use — never a second table that could drift. A record the
+ * user's own file supplied is marked, because an operator who overrode a shipped record can no longer
+ * tell the two apart from the name alone.
  * @returns One summary per record.
  */
 export function loopRecords() {
+    const { overridden, added } = loopSourceInfo();
+    const mine = new Set([...overridden, ...added]);
     return loopPrompts().names.flatMap(name => {
         const text = loopPrompts().find(name);
         if (text === undefined)
@@ -26,7 +30,8 @@ export function loopRecords() {
         return [{ name, title: text.title, steps: text.steps,
                 ...(text.artifact === undefined ? {} : { artifact: text.artifact }),
                 defaultScore: text.defaultScore, defaultTries: text.defaultTries,
-                vars: loopPrompts().vars(name) }];
+                vars: loopPrompts().vars(name),
+                ...(mine.has(name) ? { fromFile: true } : {}) }];
     });
 }
 /** One record's declared variables, so a caller can offer or validate them before a run starts.

package/dist/controller/loop-source.d.ts

@@ -0,0 +1,74 @@
+import type { LoopSourceInfo } from '../contracts.ts';
+import type { LoopProtocolText, LoopPromptSource } from './loop-prompts-schema.ts';
+/** A user file: a whole document in shape, any part of it in content. */
+export interface LoopOverlaySource {
+    readonly version: number;
+    /** Global defaults this file moves; each field it omits keeps the shipped value. */
+    readonly defaults?: {
+        readonly score?: number;
+        readonly tries?: number;
+    };
+    /** Records this file adds or replaces, keyed by the name `/loop` takes. */
+    readonly protocols?: Readonly<Record<string, LoopProtocolText>>;
+}
+/** The records one process runs, and where they came from. */
+export interface LoopSourceLoad {
+    /** The merged table the renderer reads: shipped records, then the user's on top. */
+    source: LoopPromptSource;
+    /** Which files were read, what the user's file changed, and any note for the operator. */
+    info: LoopSourceInfo;
+}
+/** Where the records come from for one process. */
+export interface LoopSourceOptions {
+    /** Overlay to read instead of `<configDirectory>/loop.yaml`, from `--loop-file`/`DSHT_LOOP_FILE`. */
+    overlayFile?: string;
+    /** Configuration directory holding `loop.yaml` when no explicit file is given. */
+    configDirectory: string;
+    /** State directory holding the override stamp; omit to skip drift reporting. */
+    stateDirectory?: string;
+    /** Shipped file to read; defaults to the `loop.yaml` beside the package entry point. */
+    builtinFile?: string;
+    /** Table used when the shipped file cannot be read; defaults to the compiled-in one. */
+    fallback?: LoopPromptSource;
+}
+/** Path of the `loop.yaml` shipped beside this module.
+ *
+ * The path is relative to the module, so it resolves both in the source tree (`src/controller/`) and
+ * in the published build (`dist/controller/`), exactly as the version read in `cli/dsht.tsx` does.
+ * @returns Absolute path to the shipped record file.
+ */
+export declare function shippedLoopFile(): string;
+/** The overlay file a process reads, if it reads one at all.
+ *
+ * An explicit file wins over the configuration directory: it is how a script or a second checkout
+ * points at another set of records without moving the one the interactive client uses.
+ * @param options - Resolved options.
+ * @returns Absolute path of the overlay to try.
+ */
+export declare function loopOverlayFile(options: LoopSourceOptions): string;
+/** Layer one user file over the shipped records.
+ *
+ * A record is taken whole: replacing one does not merge its fields with the shipped copy, because a
+ * record is a single prompt contract and a half-new brief with a half-old round table is a protocol
+ * nobody wrote. Records the file does not name are untouched, which is what lets a shipped fix reach
+ * an install that customises something else.
+ * @param builtin - Shipped records.
+ * @param overlay - Parsed user file.
+ * @returns The merged table and the names the user file replaced or added.
+ */
+export declare function mergeLoopSource(builtin: LoopPromptSource, overlay: LoopOverlaySource): {
+    source: LoopPromptSource;
+    overridden: string[];
+    added: string[];
+};
+/** Read the merged records for one process.
+ *
+ * The shipped file falls back to the compiled-in table with a warning, because a packaging mistake
+ * should not stop the client; a user file does not, because an invalid override the operator wrote is
+ * a mistake they can fix and a silent fallback would run the shipped records while they believe their
+ * own are in force. An absent overlay is ordinary: most installs have none.
+ * @param options - Resolution options.
+ * @returns The merged records, their sources and the notes to show the operator.
+ * @throws when the overlay exists but is not a valid loop file.
+ */
+export declare function loadLoopSource(options: LoopSourceOptions): Promise<LoopSourceLoad>;