systemoneprompts 0.1.0

package/dist/state/requirements.js

@@ -0,0 +1,189 @@
+import { diagnostic, SystemOnePromptsError } from "../definition/diagnostics.js";
+import { locate } from "../definition/locate.js";
+import { isJsonValue, isPlainObject, typeName } from "../json.js";
+import { formatPath, getAtPath, parsePath } from "./paths.js";
+export const REQUIREMENT_TYPES = [
+    "string",
+    "number",
+    "boolean",
+    "array",
+    "object",
+    "null",
+    "exists",
+];
+export function parseRequirements(raw, index) {
+    const diagnostics = [];
+    const requires = Object.create(null);
+    if (raw == null)
+        return { requires, diagnostics };
+    if (!isPlainObject(raw)) {
+        diagnostics.push(diagnostic("error", "requires-not-table", "[requires] must be a table of path = type entries", locate(index, { table: "requires" })));
+        return { requires, diagnostics };
+    }
+    for (const [path, type] of Object.entries(raw)) {
+        const loc = locate(index, { section: "requires", key: path, table: "requires" });
+        const segments = parsePath(path);
+        if (segments == null) {
+            diagnostics.push(diagnostic("error", "invalid-require-path", `invalid [requires] path \`${path}\``, loc, "use dotted identifiers and [n], [-n], or [] indexes, e.g. ticket.message or messages[-1].text"));
+            continue;
+        }
+        if (!isRequirementType(type)) {
+            diagnostics.push(diagnostic("error", "invalid-require-type", `[requires] \`${path}\` has unknown type ${type == null ? "undefined" : `\`${String(type)}\``}`, loc, `expected ${REQUIREMENT_TYPES.join(" | ")}`));
+            continue;
+        }
+        requires[path] = type;
+    }
+    return { requires, diagnostics };
+}
+/**
+ * Check both explicit types and containers implied by dotted/indexed descendants.
+ * Compare parsed segments so spellings such as [0] and [00] refer to the same index.
+ */
+export function checkRequirementConflicts(requires, index) {
+    const diagnostics = [];
+    const entries = Object.entries(requires).flatMap(([path, type]) => {
+        const segments = parsePath(path);
+        return segments ? [{ path, canonicalPath: formatPath(segments), type, segments }] : [];
+    });
+    const explicitTypes = new Set(entries.filter((entry) => entry.type !== "exists").map((entry) => entry.canonicalPath));
+    const reportedMixed = new Set();
+    for (let leftIndex = 0; leftIndex < entries.length; leftIndex += 1) {
+        const left = entries[leftIndex];
+        for (let rightIndex = leftIndex + 1; rightIndex < entries.length; rightIndex += 1) {
+            const right = entries[rightIndex];
+            const common = commonPrefixLength(left.segments, right.segments);
+            const leftEnds = common === left.segments.length;
+            const rightEnds = common === right.segments.length;
+            if (leftEnds || rightEnds) {
+                if (leftEnds && rightEnds) {
+                    if (!compatibleAtSamePath(left.type, right.type)) {
+                        diagnostics.push(diagnostic("error", "require-conflict", `[requires] \`${left.path}\` is required as both \`${left.type}\` and \`${right.type}\``, locate(index, { section: "requires", key: left.path, table: "requires" }), "keep one compatible requirement for this path"));
+                    }
+                    continue;
+                }
+                const parent = leftEnds ? left : right;
+                const child = leftEnds ? right : left;
+                reportParentConflict(parent, child, child.segments[common], diagnostics, index);
+                continue;
+            }
+            const leftNext = left.segments[common];
+            const rightNext = right.segments[common];
+            if (leftNext.kind === rightNext.kind)
+                continue;
+            const prefix = formatPath(left.segments.slice(0, common));
+            // Explicit types are checked against each descendant by reportParentConflict.
+            if (explicitTypes.has(prefix) || reportedMixed.has(prefix))
+                continue;
+            reportedMixed.add(prefix);
+            diagnostics.push(diagnostic("error", "require-conflict", `[requires] \`${left.path}\` and \`${right.path}\` require \`${prefix}\` to be both an array and an object`, locate(index, { section: "requires", key: left.path, table: "requires" }), `use either dotted keys or [n] indexes under \`${prefix}\``));
+        }
+    }
+    return diagnostics;
+}
+function commonPrefixLength(left, right) {
+    let length = 0;
+    while (length < left.length &&
+        length < right.length &&
+        conflictSameSegment(left[length], right[length])) {
+        length += 1;
+    }
+    return length;
+}
+function sameSegment(left, right) {
+    if (left.kind === "key" && right.kind === "key")
+        return left.name === right.name;
+    if (left.kind === "index" && right.kind === "index")
+        return left.index === right.index;
+    return left.kind === "all" && right.kind === "all";
+}
+/** `[]` covers `[n]` for conflict analysis; distinct `[n]` indexes stay distinct. */
+function conflictSameSegment(left, right) {
+    if (sameSegment(left, right))
+        return true;
+    return impliesArray(left) && impliesArray(right) && (left.kind === "all" || right.kind === "all");
+}
+function impliesArray(segment) {
+    return segment.kind === "index" || segment.kind === "all";
+}
+function compatibleAtSamePath(left, right) {
+    return left === right || left === "exists" || right === "exists";
+}
+function reportParentConflict(parent, child, next, diagnostics, index) {
+    if (parent.type === "exists")
+        return;
+    const container = impliesArray(next) ? "array" : "object";
+    if (parent.type === container)
+        return;
+    const detail = parent.type === "object" || parent.type === "array"
+        ? `requires it to be an ${container}`
+        : "requires it to be a container";
+    diagnostics.push(diagnostic("error", "require-conflict", `[requires] \`${parent.path}\` is \`${parent.type}\` but \`${child.path}\` ${detail}`, locate(index, { section: "requires", key: parent.path, table: "requires" }), `change \`${parent.path}\` to "${container}" or "exists", or drop it`));
+}
+export function isRequirementType(value) {
+    return typeof value === "string" && REQUIREMENT_TYPES.includes(value);
+}
+/**
+ * Build an assertion that every `[requires]` path exists with the expected type.
+ * The assertion narrows and throws; it never copies or reshapes the state.
+ * Invalid paths fail here, at construction, rather than on first use.
+ */
+export function createStateAssert(requires) {
+    const compiled = [];
+    for (const [path, expected] of Object.entries(requires)) {
+        const segments = parsePath(path);
+        if (!segments) {
+            throw new SystemOnePromptsError(diagnostic("error", "invalid-require-path", `invalid [requires] path \`${path}\``));
+        }
+        compiled.push({ path: formatPath(segments), expected, segments });
+    }
+    return (state) => {
+        for (const { path, expected, segments } of compiled) {
+            const error = assertSegments(state, segments, 0, path, expected);
+            if (error)
+                throw new SystemOnePromptsError(error);
+        }
+    };
+}
+/** Walk `segments` from `index`; `[]` checks every element and reports a non-array container. */
+function assertSegments(current, segments, index, path, expected) {
+    if (index === segments.length)
+        return checkRequirement(path, expected, current);
+    const head = segments[index];
+    if (head.kind === "all") {
+        if (!Array.isArray(current)) {
+            return checkRequirement(formatPath(segments.slice(0, index)), "array", current);
+        }
+        for (const element of current) {
+            const error = assertSegments(element, segments, index + 1, path, expected);
+            if (error)
+                return error;
+        }
+        return undefined;
+    }
+    return assertSegments(getAtPath(current, [head]), segments, index + 1, path, expected);
+}
+export function checkRequirement(path, expected, actual) {
+    if (matchesType(expected, actual))
+        return undefined;
+    const got = actual === undefined ? "undefined" : typeName(actual);
+    return diagnostic("error", "state-requirement", `${path}: expected ${expected}, got ${got}`);
+}
+function matchesType(expected, actual) {
+    switch (expected) {
+        case "string":
+            return typeof actual === "string";
+        case "number":
+            return typeof actual === "number" && Number.isFinite(actual);
+        case "boolean":
+            return typeof actual === "boolean";
+        case "array":
+            return Array.isArray(actual) && isJsonValue(actual);
+        case "object":
+            return isPlainObject(actual) && isJsonValue(actual);
+        case "null":
+            return actual === null;
+        case "exists":
+            return actual !== undefined;
+    }
+}
+//# sourceMappingURL=requirements.js.map

package/dist/state/requirements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirements.js","sourceRoot":"","sources":["../../src/state/requirements.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,UAAU,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAClG,OAAO,EAAE,MAAM,EAAoB,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAoB,SAAS,EAAE,MAAM,YAAY,CAAC;AAEhF,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,QAAQ;IACR,QAAQ;IACR,SAAS;IACT,OAAO;IACP,QAAQ;IACR,MAAM;IACN,QAAQ;CACA,CAAC;AASX,MAAM,UAAU,iBAAiB,CAC/B,GAAY,EACZ,KAAkB;IAElB,MAAM,WAAW,GAAiB,EAAE,CAAC;IACrC,MAAM,QAAQ,GAAiB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACnD,IAAI,GAAG,IAAI,IAAI;QAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;IAClD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,WAAW,CAAC,IAAI,CACd,UAAU,CACR,OAAO,EACP,oBAAoB,EACpB,mDAAmD,EACnD,MAAM,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CACrC,CACF,CAAC;QACF,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;IACnC,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAA8B,CAAC,EAAE,CAAC;QAC1E,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;QACjF,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;YACrB,WAAW,CAAC,IAAI,CACd,UAAU,CACR,OAAO,EACP,sBAAsB,EACtB,6BAA6B,IAAI,IAAI,EACrC,GAAG,EACH,+FAA+F,CAChG,CACF,CAAC;YACF,SAAS;QACX,CAAC;QACD,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,WAAW,CAAC,IAAI,CACd,UAAU,CACR,OAAO,EACP,sBAAsB,EACtB,gBAAgB,IAAI,uBAAuB,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,EAC/F,GAAG,EACH,YAAY,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAC5C,CACF,CAAC;YACF,SAAS;QACX,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACxB,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;AACnC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CACvC,QAAsB,EACtB,KAAkB;IAElB,MAAM,WAAW,GAAiB,EAAE,CAAC;IACrC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE;QAChE,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QACjC,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,UAAU,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACzF,CAAC,CAAC,CAAC;IACH,MAAM,aAAa,GAAG,IAAI,GAAG,CAC3B,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,CACvF,CAAC;IACF,MAAM,aAAa,GAAG,IAAI,GAAG,EAAU,CAAC;IAExC,KAAK,IAAI,SAAS,GAAG,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,SAAS,IAAI,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,GAAG,OAAO,CAAC,SAAS,CAAE,CAAC;QACjC,KAAK,IAAI,UAAU,GAAG,SAAS,GAAG,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,EAAE,UAAU,IAAI,CAAC,EAAE,CAAC;YAClF,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,CAAE,CAAC;YACnC,MAAM,MAAM,GAAG,kBAAkB,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;YACjE,MAAM,QAAQ,GAAG,MAAM,KAAK,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;YACjD,MAAM,SAAS,GAAG,MAAM,KAAK,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;YAEnD,IAAI,QAAQ,IAAI,SAAS,EAAE,CAAC;gBAC1B,IAAI,QAAQ,IAAI,SAAS,EAAE,CAAC;oBAC1B,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;wBACjD,WAAW,CAAC,IAAI,CACd,UAAU,CACR,OAAO,EACP,kBAAkB,EAClB,gBAAgB,IAAI,CAAC,IAAI,4BAA4B,IAAI,CAAC,IAAI,YAAY,KAAK,CAAC,IAAI,IAAI,EACxF,MAAM,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EACzE,+CAA+C,CAChD,CACF,CAAC;oBACJ,CAAC;oBACD,SAAS;gBACX,CAAC;gBAED,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;gBACvC,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;gBACtC,oBAAoB,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAE,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC;gBACjF,SAAS;YACX,CAAC;YAED,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAE,CAAC;YACxC,MAAM,SAAS,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAE,CAAC;YAC1C,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS,CAAC,IAAI;gBAAE,SAAS;YAE/C,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;YAC1D,8EAA8E;YAC9E,IAAI,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,SAAS;YACrE,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC1B,WAAW,CAAC,IAAI,CACd,UAAU,CACR,OAAO,EACP,kBAAkB,EAClB,gBAAgB,IAAI,CAAC,IAAI,YAAY,KAAK,CAAC,IAAI,gBAAgB,MAAM,sCAAsC,EAC3G,MAAM,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EACzE,iDAAiD,MAAM,IAAI,CAC5D,CACF,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,SAAS,kBAAkB,CAAC,IAA4B,EAAE,KAA6B;IACrF,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,OACE,MAAM,GAAG,IAAI,CAAC,MAAM;QACpB,MAAM,GAAG,KAAK,CAAC,MAAM;QACrB,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAE,EAAE,KAAK,CAAC,MAAM,CAAE,CAAC,EAClD,CAAC;QACD,MAAM,IAAI,CAAC,CAAC;IACd,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,WAAW,CAAC,IAAiB,EAAE,KAAkB;IACxD,IAAI,IAAI,CAAC,IAAI,KAAK,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,CAAC;IACjF,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK,CAAC;IACvF,OAAO,IAAI,CAAC,IAAI,KAAK,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC;AACrD,CAAC;AAED,qFAAqF;AACrF,SAAS,mBAAmB,CAAC,IAAiB,EAAE,KAAkB;IAChE,IAAI,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,YAAY,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC;AACpG,CAAC;AAED,SAAS,YAAY,CAAC,OAAoB;IACxC,OAAO,OAAO,CAAC,IAAI,KAAK,OAAO,IAAI,OAAO,CAAC,IAAI,KAAK,KAAK,CAAC;AAC5D,CAAC;AAED,SAAS,oBAAoB,CAAC,IAAqB,EAAE,KAAsB;IACzE,OAAO,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,QAAQ,IAAI,KAAK,KAAK,QAAQ,CAAC;AACnE,CAAC;AAED,SAAS,oBAAoB,CAC3B,MAA+C,EAC/C,KAAuB,EACvB,IAAiB,EACjB,WAAyB,EACzB,KAAkB;IAElB,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO;IACrC,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC1D,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO;IAEtC,MAAM,MAAM,GACV,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO;QACjD,CAAC,CAAC,wBAAwB,SAAS,EAAE;QACrC,CAAC,CAAC,+BAA+B,CAAC;IACtC,WAAW,CAAC,IAAI,CACd,UAAU,CACR,OAAO,EACP,kBAAkB,EAClB,gBAAgB,MAAM,CAAC,IAAI,WAAW,MAAM,CAAC,IAAI,YAAY,KAAK,CAAC,IAAI,MAAM,MAAM,EAAE,EACrF,MAAM,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAC3E,YAAY,MAAM,CAAC,IAAI,UAAU,SAAS,2BAA2B,CACtE,CACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,iBAAuC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC/F,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAsB;IAEtB,MAAM,QAAQ,GAAgF,EAAE,CAAC;IACjG,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxD,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,qBAAqB,CAC7B,UAAU,CAAC,OAAO,EAAE,sBAAsB,EAAE,6BAA6B,IAAI,IAAI,CAAC,CACnF,CAAC;QACJ,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;IACpE,CAAC;IAED,OAAO,CAAC,KAAc,EAAsB,EAAE;QAC5C,KAAK,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,QAAQ,EAAE,CAAC;YACpD,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;YACjE,IAAI,KAAK;gBAAE,MAAM,IAAI,qBAAqB,CAAC,KAAK,CAAC,CAAC;QACpD,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,iGAAiG;AACjG,SAAS,cAAc,CACrB,OAAgB,EAChB,QAAgC,EAChC,KAAa,EACb,IAAY,EACZ,QAAyB;IAEzB,IAAI,KAAK,KAAK,QAAQ,CAAC,MAAM;QAAE,OAAO,gBAAgB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAChF,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAE,CAAC;IAC9B,IAAI,IAAI,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;QACxB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,OAAO,gBAAgB,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAClF,CAAC;QACD,KAAK,MAAM,OAAO,IAAI,OAAO,EAAE,CAAC;YAC9B,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,GAAG,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;YAC3E,IAAI,KAAK;gBAAE,OAAO,KAAK,CAAC;QAC1B,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,cAAc,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,GAAG,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;AACzF,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,QAAyB,EACzB,MAAe;IAEf,IAAI,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IACpD,MAAM,GAAG,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAClE,OAAO,UAAU,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,IAAI,cAAc,QAAQ,SAAS,GAAG,EAAE,CAAC,CAAC;AAC/F,CAAC;AAED,SAAS,WAAW,CAAC,QAAyB,EAAE,MAAe;IAC7D,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,QAAQ;YACX,OAAO,OAAO,MAAM,KAAK,QAAQ,CAAC;QACpC,KAAK,QAAQ;YACX,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC/D,KAAK,SAAS;YACZ,OAAO,OAAO,MAAM,KAAK,SAAS,CAAC;QACrC,KAAK,OAAO;YACV,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;QACtD,KAAK,QAAQ;YACX,OAAO,aAAa,CAAC,MAAM,CAAC,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;QACtD,KAAK,MAAM;YACT,OAAO,MAAM,KAAK,IAAI,CAAC;QACzB,KAAK,QAAQ;YACX,OAAO,MAAM,KAAK,SAAS,CAAC;IAChC,CAAC;AACH,CAAC"}

package/docs/SPEC.html

@@ -0,0 +1,57 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>systemoneprompts definition contract</title>
+  <style>
+    :root { color-scheme: light dark; }
+    body { max-width: 920px; margin: 3rem auto; padding: 0 1.25rem; font: 16px/1.6 system-ui, sans-serif; }
+    code, pre { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+    code { padding: .1rem .25rem; border-radius: .25rem; background: #8882; }
+    pre { overflow-x: auto; padding: 1rem; border-radius: .5rem; background: #8882; }
+    h1, h2, h3 { line-height: 1.2; margin-top: 2rem; }
+    a { color: #268bd2; }
+  </style>
+</head>
+<body>
+<h1 id="systemoneprompts-definition-contract">systemoneprompts definition contract</h1>
+<p>Status: contract version <code>v1</code>. The TypeScript package is the reference implementation; the Python package is required to match the language-neutral rules below. Package-specific APIs may be idiomatic, but the parsed questions, state guarantees, factor truth tables, diagnostics, and generated artifacts must preserve the same behavior.</p>
+<h2 id="definition-shape">Definition shape</h2>
+<p>A definition is a TOML document with optional scalar metadata (<code>title</code>, <code>version</code>, <code>description</code>, <code>model</code>, plus other scalar keys) and four recognized tables: <code>[requires]</code>, <code>[questions]</code>, <code>[factors]</code>, and optional <code>[data]</code>. Unknown top-level tables produce warnings and are not silently interpreted. <code>model</code> is an optional non-empty string; a blank model is an error.</p>
+<p>The parser throws only for invalid TOML. Structural problems are returned as diagnostics and the invalid entry is omitted. <code>checkDefinition</code>/<code>check_definition</code> adds cross-cutting reference, conflict, cycle, and lint diagnostics.</p>
+<h2 id="application-data">Application data</h2>
+<p><code>[data]</code> is an optional application-owned namespace. Its root must be a TOML table. Beneath it, arbitrary nested JSON-compatible objects, arrays, strings, booleans, finite numbers, and arrays of tables are preserved verbatim. TOML dates/times and other non-JSON values are rejected with diagnostics. An absent or invalid data tree is represented as an empty object/dictionary when the definition is returned; invalid definitions still fail normal checking and generation.</p>
+<p>systemoneprompts does not assign meaning to child keys, validate application IDs or placeholders, resolve references, interpolate strings, load files, send data to TypeSafe, or make factors and questions depend on it. It does not apply question backtick linting inside data. Applications decide their own schema, validation and runtime use. Generated TypeScript and Python modules export the parsed tree as <code>data</code>; generated output remains deterministic. Application-only data therefore has no provider or cache effect unless application code explicitly projects it into a question or state.</p>
+<h2 id="questions">Questions</h2>
+<p>At least one question is required. Question IDs are literal TOML keys, including quoted IDs containing dots. Every question is a table with only <code>type</code>, <code>instructions</code>, and <code>criteria</code>:</p>
+<ul>
+<li><code>noul</code>: optional <code>criteria</code> table with only <code>true</code> and <code>false</code> entries.</li>
+<li><code>choice</code>: non-empty criteria table with at most 255 labels.</li>
+<li><code>score</code>: criteria array with at least two entries.</li>
+</ul>
+<p><code>instructions</code> and criteria entries are forwarded verbatim when they are a string, JSON-compatible table, or JSON-compatible array. TOML dates, times, cycles, non-finite numbers, and other runtime-only values are rejected. The resulting objects use the native TypeSafe field names and shapes; no aliases or implicit question vocabulary are introduced.</p>
+<p>Native System One answers under a response <code>answers</code> map:</p>
+<ul>
+<li>Noul: type <code>noul</code> and a finite <code>noul</code> number.</li>
+<li>Choice: type <code>choice</code>, a <code>choice</code> label, finite <code>confidence</code>, and <code>probabilities</code> with a finite probability for every criteria label.</li>
+<li>Score: type <code>score</code>, a finite <code>score</code> expected value (a float between levels, not a level label), finite <code>confidence</code>, plus <code>legend</code> and <code>probabilities</code> keyed by the decimal string of each criteria index (<code>"0"</code>, <code>"1"</code>, ...).</li>
+</ul>
+<p>Packages may expose helpers that read those fields and that partition answers into valid, missing, and malformed ids. They must not invent a Score level as a native field. <code>wireQuestions</code> / <code>wire_questions</code> returns only <code>type</code>, <code>instructions</code>, and <code>criteria</code> for each question.</p>
+<h2 id="state-requirements">State requirements</h2>
+<p><code>[requires]</code> maps dotted and indexed paths to one of: <code>string</code>, <code>number</code>, <code>boolean</code>, <code>array</code>, <code>object</code>, <code>null</code>, or <code>exists</code>. Paths use own object keys, zero-based <code>[n]</code> indexes, negative <code>[-n]</code> indexes from the end of an array, and empty <code>[]</code> indexes. <code>[]</code> means every array element: <code>"messages[].text" = "string"</code> requires <code>messages</code> to be an array and every element's <code>text</code> to be a string. An empty array satisfies a <code>[]</code> requirement; a container that is not an array fails as <code>messages: expected array, got &lt;type&gt;</code>. <code>[]</code> and <code>[n]</code> both imply an array container and do not conflict with each other. A backticked <code>[n]</code> path is guaranteed when <code>[requires]</code> names the same path with <code>[]</code>; a backticked <code>[]</code> path is not guaranteed by a more specific <code>[n]</code> requirement. <code>exists</code> accepts null; all other types require the value to match. <code>number</code>, <code>array</code>, and <code>object</code> also require JSON-compatible values. Assertions never copy, coerce, or reshape the application state.</p>
+<p>Explicit requirements and containers implied by descendants must agree. For example, <code>ticket = "object"</code> may accompany <code>ticket.message</code>, while <code>ticket = "string"</code> may not. Dotted and indexed descendants cannot require the same container to be both an object and an array. Equivalent index spellings refer to the same index, and out-of-bounds indexes fail at runtime.</p>
+<h2 id="factors">Factors</h2>
+<p>Every factor evaluates to a Boolean. A factor is exactly one predicate (<code>ref</code>) or one Boolean operator (<code>all</code>, <code>any</code>, <code>not</code>, <code>at_least</code>). Predicate fields are <code>known</code>, <code>choice</code>, <code>noul</code>, <code>score</code>, and <code>confidence</code>; numeric fields use one or more finite comparators from <code>gt</code>, <code>gte</code>, <code>lt</code>, and <code>lte</code> and all present comparators are ANDed.</p>
+<p>Bare Noul references in Boolean operators use <code>noul &gt;= 0.5</code>. Choice and Score answers must be wrapped in a predicate. Missing answers are runtime errors, not false values, except a <code>known</code>-only predicate: it returns false for an absent or unusable answer. <code>known</code> treats explicit <code>missing</code>, confidence <code>0</code>, and a bare Noul exactly equal to <code>0.5</code> as unknown; usable Choice and Score answers are known.</p>
+<p>Boolean operators validate every operand even if an earlier operand already determines the result. Factor definitions are snapshotted when an evaluator is created, factor IDs are prototype-safe, and independent cycles are reported together. Unknown references, question/factor ID collisions, invalid operator fields, invalid choice labels, primitive mismatches, and cycles are definition errors.</p>
+<h2 id="generation-and-cli">Generation and CLI</h2>
+<p>Generation is deterministic. It emits native question objects, model metadata, the verbatim factor definitions, a state assertion, and a typed factor evaluator. Empty requirements still produce a state type assignable to the package <code>EntryType</code>. Generated output must typecheck/import in a clean consumer.</p>
+<p>The CLI supports <code>check</code>, <code>generate</code>, <code>run</code>, <code>eval</code>, and <code>cache</code>. <code>check</code> and <code>generate --check</code> process every input and return nonzero if any input fails. They never call the provider. <code>run</code> validates state before any request. <code>eval</code> validates cases, labels, factor names, sweep fields, and report paths before requests; partial reports survive execution errors. Live credentials are required only by explicit live commands.</p>
+<h2 id="cache-and-patterns">Cache and patterns</h2>
+<p>The TypeScript development cache is a fetch interceptor, not a client wrapper. It keys per-question requests by canonical JSON request data and model, writes records atomically, treats malformed records as misses, validates cached answers against the question criteria, and merges valid cached hits with valid live answers. Read-only misses fail. Cache statistics are cumulative and prototype-safe.</p>
+<p><code>runMany</code> requires a positive concurrency limit, preserves input order, and invokes a result callback at most once per result. It may ask the same questions about many states, or a list of <code>{state, questions}</code> items. Callback failures reject the batch without retries. <code>walkTaxonomy</code> requires a positive beam width and is an explicit approximate beam search; it does not promise an exhaustive traversal.</p>
+<h2 id="compatibility">Compatibility</h2>
+<p>The TOML author-owned <code>version</code> is distinct from this behavioral contract version. Cases in <code>conformance/v1</code> are the executable compatibility boundary. Any change to native question shape, state assertion semantics, factor truth tables, diagnostic codes, cache records, or CLI exit behavior requires a new fixture and a compatibility review.</p>
+</body>
+</html>

package/docs/skills/systemoneprompts/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: systemoneprompts
+description: "Use the systemoneprompts TypeScript package to author System One TOML decision definitions, validate and generate modules, integrate native TypeSafe questions, and evaluate decisions. Includes domain organization and application-data authoring guidance. Use for systemoneprompts package work, not generic TypeSafe prompting without this package."
+---
+
+# Using systemoneprompts
+
+systemoneprompts turns System One TOML decision definitions into native TypeSafe questions,
+minimum state assertions and Boolean factors. Application code calls the
+provider and decides what happens. Keep that boundary visible.
+
+## Establish the supported contract
+
+Read the package documentation before choosing an API or CLI option:
+
+- [Package README](../../../README.md) for APIs, CLI options and examples.
+- [Shared specification](../../SPEC.html) for format and semantic details.
+- [Application-data layout](references/application-data.md) when organizing
+  copy, labels and examples beside domain questions.
+
+Check the installed package version when it differs from this checkout.
+
+Structured `[data]` is implemented in this package. It is an arbitrary,
+JSON-compatible application-owned tree beneath a TOML table root. The package
+preserves and exports it; it does not assign child-key semantics, render it,
+send it to the provider, or validate an application's schema. For older
+installed versions, verify support before using `definition.data` or a
+generated `data` export.
+
+## Author a definition
+
+Use native question fields: `type`, `instructions`, `criteria`. Define at least
+one question. Use `noul` for a yes/no judgment, `choice` for a categorical
+selection, and `score` for an ordered magnitude. Instructions and criteria
+entries may contain strings, objects or arrays; they are forwarded to the
+provider, so application-only metadata does not belong there.
+
+```toml
+title = "Support topic"
+
+[requires]
+"message" = "string"
+
+[questions.topic]
+type = "choice"
+instructions = "Which topic best describes `message`?"
+
+[questions.topic.criteria]
+delivery = "Shipment tracking, delivery timing, or a missing parcel."
+billing = "Charges, invoices, or payment failures; excludes shipment tracking."
+other = "The request fits neither topic, or its topic is unspecified."
+
+[factors]
+is_delivery = { ref = "topic", choice = "delivery" }
+```
+
+Define one clear judgment per question. Explain neighboring boundaries rather
+than relying on labels or examples alone. Structured criteria such as
+`{ what = "...", not_for = "...", examples = [...] }` are ordinary author-chosen
+payloads, not extra question fields or a phrase-matching grammar.
+
+Use `[requires]` for the minimum evidence the questions need. Supported types
+are `string`, `number`, `boolean`, `array`, `object`, `null` and `exists`.
+Quote dotted or indexed paths, such as `"customer.orders[0].id"`; `"messages[].text"` requires every element's `text`. Assertions
+check the supplied state; they neither transform it nor remove extra fields.
+Build an appropriate provider state explicitly in application code.
+
+Question and factor IDs are literal keys. A dotted ID is not a nested path:
+quote it when authoring one. Do not give a question and factor the same ID.
+Quote date/time values intended as strings and avoid non-finite numbers.
+
+## Check, generate and integrate
+
+1. Validate the definition before provider calls. `checkDefinition` returns
+   diagnostics for structural and cross-reference problems;
+   parsing successfully does not mean a definition is valid. Fix errors and
+   inspect warnings. `--strict` makes warnings errors when that is appropriate
+   for the project.
+2. Generate the module using the package CLI, or load and validate definitions
+   at runtime using its API. Do not hand-edit generated files.
+3. Assert state, call `TypeSafeClient.systemOne` (or Python
+   `TypeSafeClient.system_one`), and evaluate factors against its answers.
+   Application code owns thresholds, routing and side effects.
+4. After source changes, regenerate checked-in output and use `generate --check`
+   to detect stale artifacts. Follow the target package's output-path options.
+
+TypeScript consumer commands:
+
+```sh
+npm install systemoneprompts
+# or: bun add systemoneprompts
+npx systemoneprompts check support.toml --strict
+npx systemoneprompts generate support.toml
+npx systemoneprompts generate support.toml --check
+# bunx systemoneprompts works the same way
+```
+
+Generated-module usage; executing the provider call requires live credentials:
+
+```ts
+import { TypeSafeClient } from "systemoneprompts";
+import {
+  assertState, questions, model, evaluateFactors,
+} from "./support.generated.js";
+
+const state = { message: "Where is my parcel?" };
+assertState(state);
+const response = await new TypeSafeClient().systemOne({ state, questions, model });
+const factors = evaluateFactors(response.answers);
+// Application code consumes factors.is_delivery and the underlying answers.
+```
+
+`assertState` returns nothing; do not assign its result to state. For an
+offline answer check, call the generated `evaluateFactors` with supplied
+answers. The TypeScript CLI has no `run --answers` option.
+
+Live `run` and `eval` build `{ state, questions, model }`. Native TypeSafe uses
+`TYPESAFE_API_KEY`. OpenRouter is the same client with
+`baseURL: "https://openrouter.ai/api"`; pass the OpenRouter key as `apiKey`, or
+put it in `TYPESAFE_API_KEY` for CLI. There is no `OPENROUTER_API_KEY`
+integration. Cloudflare Workers AI is the same client with
+`cloudflareAccountId` / `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN`
+(not `TYPESAFE_API_KEY`); do not set `TYPESAFE_BASE_URL` at the same time. The
+client rewrites the body to `{ model: "typesafe/jev", input: { state, questions } }`
+at `https://api.cloudflare.com/client/v4/accounts/{id}/ai/run`. `--model` does
+not change that catalog id. `--cache` wraps Cloudflare inside the cache so keys
+stay System One JSON. See the package README Providers section for model ids.
+
+`check` and `generate` are offline. Live `run` and `eval` use provider
+credentials; a format or rendering edit alone does not require a live call.
+
+## Use factors for small Boolean derivations
+
+Every factor is one predicate (`ref`) or one operator (`all`, `any`, `not`,
+`at_least`). Use explicit `choice`, `noul`, `score` or supported `confidence`
+predicates with finite `gt`, `gte`, `lt`, `lte` comparisons where needed.
+Calibrate operational thresholds against the application's evaluation cases.
+
+Keep these semantics in mind:
+
+- A bare Noul in a Boolean operator means `noul >= 0.5`. It is not a calibrated
+  authorization threshold. Choice and Score references require predicates.
+- Missing answers normally throw. A `known`-only predicate is the exception
+  for checking absent or unusable answers. `known` does not prove correctness.
+- Boolean operators validate every operand, even when an earlier operand
+  determines the result. Do not build a conditional decoder by assuming
+  short-circuit behaviour or that `known` will guard a later missing operand.
+- Weighted scores, required-versus-optional answers, calculations and workflow
+  precedence belong in ordinary code. Factors do not authorize actions merely
+  because their names contain words such as `safe` or `approved`.
+
+## Organize domain files for humans
+
+Prefer one file per coherent area and a separate `router.toml` when useful.
+Keep local meanings and related authored material together. Split a file when
+navigating it becomes harder than understanding the domain; one giant TOML is
+not a goal.
+
+The router owns distinctions between areas; domain files own their local
+distinctions. These are organizational conventions, not built-in routing.
+Application code imports and assembles files, handles ID collisions explicitly,
+and decides scheduling. Separate files do not require separate model calls.
+Independent questions can share a batch, but a question cannot consume another
+answer from that same batch.
+
+Use TOML when changing the definition is easier to review than changing code.
+If an edit requires mentally executing conditions, loops or state transitions,
+prefer a function. Do not invent include/merge rules or a workflow language to
+make every part of an application fit in configuration.
+
+## Author application data without imposing a universal schema
+
+Apply these conventions to application-owned configuration and `[data]`. The
+feature preserves and exports an arbitrary JSON-compatible tree beneath a
+table root. Applications choose its structure, validation and interpretation.
+Names such
+as `topics`, `templates`, `utterances` or `examples` have no core semantics.
+
+Choose content deliberately:
+
+- Co-locate stable authored labels, descriptions, short copy, wording variants,
+  domain metadata and representative cases that change together.
+- Keep model instructions in questions. Application data is not automatically
+  sent to the model; projecting selected values into a request requires code.
+- Keep live facts, dynamic candidates and state in their authoritative runtime
+  sources. Avoid duplicating prices, availability or capability lists across
+  prompts and UI copy. A static authored policy may live in configuration when
+  that configuration is its authoritative source.
+- Keep rendering decisions, computations, consent, state changes and execution
+  in code. A template can hold wording; it does not choose when to speak or
+  supply facts. Literal braces do not imply a systemoneprompts template engine.
+- Distinguish recognition examples, response utterances and evaluation cases.
+  Held-out cases must not automatically become prompt examples. Example lists
+  illustrate boundaries; they do not enumerate all supported wording.
+- Keep secrets, private conversation histories and runtime logs out of authored
+  definition files.
+
+Format for easy scanning and review:
+
+- Use shallow hierarchy and one header per meaningful collection, avoiding a
+  repeated dotted header for each label or phrase.
+- Prefer keyed tables for simple dictionaries. Prefer multiline arrays of
+  compact inline records when entries have several fields, one record per row.
+- Put each utterance on its own line in a variant list. Use multiline strings
+  for paragraphs. Expand large records into tables or arrays of tables when a
+  single row becomes unwieldy.
+- Use stable IDs instead of list positions for references. Keep a predictable
+  order, related entries together, and one authoritative definition per purpose.
+- Use normal TOML values, not delimiter-separated strings or embedded expression
+  languages. Comments should explain distinctions and ownership.
+- Show a complete small domain when explaining a layout, focused diffs when
+  reviewing an edit, and clearly label future or application-specific syntax.
+
+The [delivery example](references/application-data.md)
+illustrates compact records, multiline utterances and application-owned cases.
+Its alternative keyed label table illustrates when records add needless noise.
+These layouts are suggestions; follow an application's established schema.
+
+Validate that schema in the application, preferably before runtime use. Check
+duplicate record IDs, unknown fields, copy references, placeholders and code
+registrations where relevant. Those are application guarantees, not core
+systemoneprompts checks. A field such as `read_only = true` cannot enforce behaviour.
+Inline examples also need an application adapter before they are CLI eval cases.
+
+## Evaluate the decision, then report what was verified
+
+The CLI eval format is JSONL: each case supplies `state`, optional `id`,
+expected question `labels`, and/or expected Boolean `factors`. Choice labels
+are option IDs, Noul labels are Booleans, and Score labels are integer indices.
+Use full cases and defined factor names; inspect errors before provider calls.
+
+Include contrastive, ambiguous and out-of-domain inputs. Keep held-out cases
+separate from prompt examples. For a bad result, inspect the failed boundary
+before adding more wording or changing a threshold. Application tests should
+also verify any state or action invariants beyond classification.
+
+Distinguish offline parsing, generation and supplied-answer checks from live
+recognition evaluation. Report the checks actually run. Keep the change scoped
+to package usage unless the user also requests library implementation work.

package/docs/skills/systemoneprompts/references/application-data.md

@@ -0,0 +1,79 @@
+# Application-owned data layout
+
+Status: `[data]` is implemented in this package as of 20 September 2026.
+Verify support in older installed versions before relying on the generated
+`data` export. Applications own the child schema and interpretation.
+
+This example keeps one area's questions, compact metadata, copy and a few
+recognition checks together. The `data` namespace is the core feature; every
+child name and reference is an application convention.
+
+```toml
+title = "Delivery"
+
+[requires]
+"message" = "string"
+
+[questions.topic]
+type = "choice"
+instructions = """
+Identify the delivery information requested in `message`.
+Asking about a delivery method does not select it.
+"""
+
+[questions.topic.criteria]
+cost = "Asks about delivery prices or charges."
+timing = "Asks when delivery arrives or how long it takes."
+none = "No delivery-information request."
+unclear = "A delivery question whose meaning is uncertain."
+
+[data]
+topics = [
+  { id = "cost",   label = "Delivery prices", scope = "delivery_method", reply = "cost" },
+  { id = "timing", label = "Delivery times",  scope = "delivery_method", reply = "timing" },
+]
+
+templates = [
+  { id = "cost",          text = "{method_label} costs {price_label}." },
+  { id = "timing",        text = "{method_label}: {timing_label}." },
+  { id = "missing_scope", text = "Which delivery method do you mean?" },
+]
+
+utterances = [
+  { id = "acknowledge", variants = [
+    "Of course.",
+    "Sure.",
+  ] },
+  { id = "explain", variants = [
+    """
+I can explain delivery prices and timing.
+The available options depend on your order.
+""",
+  ] },
+]
+
+examples = [
+  { message = "what would express set me back?", labels = { topic = "cost" } },
+  { message = "how long does standard take?",    labels = { topic = "timing" } },
+  { message = "use express",                    labels = { topic = "none" } },
+]
+```
+
+The application validates IDs, references and placeholders, supplies verified
+prices and timing, and decides whether to acknowledge or clarify. systemoneprompts
+would preserve data without rendering it, forwarding it to the model or
+executing anything. The examples need an application adapter to become CLI
+eval cases with full `state` objects; they are not automatically prompt examples.
+
+For a simple dictionary, a keyed table can be shorter than records:
+
+```toml
+[data.labels]
+cost = "Delivery prices"
+timing = "Delivery times"
+```
+
+This is an alternative organization, not a requirement to duplicate the labels
+from `topics`. Prefer a header for a meaningful collection over a separate
+`[data.labels.cost]` header for a single string. Use tables or arrays of tables
+when complex records cease to fit comfortably on one row.