@exodus/xqa 6.0.0 → 7.0.0

package/dist/consumer-api.cjs

@@ -261,8 +261,8 @@ var require_index_cjs = __commonJS({
           return new Ok(res.value);
         })));
       }
-      match(ok5, _err) {
-        return this._promise.then((res) => res.match(ok5, _err));
+      match(ok6, _err) {
+        return this._promise.then((res) => res.match(ok6, _err));
       }
       unwrapOr(t) {
         return this._promise.then((res) => res.unwrapOr(t));
@@ -301,17 +301,17 @@ var require_index_cjs = __commonJS({
     function okAsync(value) {
       return new ResultAsync2(Promise.resolve(new Ok(value)));
     }
-    function errAsync2(err5) {
-      return new ResultAsync2(Promise.resolve(new Err(err5)));
+    function errAsync2(err6) {
+      return new ResultAsync2(Promise.resolve(new Err(err6)));
     }
     var fromPromise = ResultAsync2.fromPromise;
     var fromSafePromise = ResultAsync2.fromSafePromise;
     var fromAsyncThrowable = ResultAsync2.fromThrowable;
     var combineResultList = (resultList) => {
-      let acc = ok4([]);
+      let acc = ok5([]);
       for (const result of resultList) {
         if (result.isErr()) {
-          acc = err4(result.error);
+          acc = err5(result.error);
           break;
         } else {
           acc.map((list) => list.push(result.value));
@@ -321,12 +321,12 @@ var require_index_cjs = __commonJS({
     };
     var combineResultAsyncList = (asyncResultList) => ResultAsync2.fromSafePromise(Promise.all(asyncResultList)).andThen(combineResultList);
     var combineResultListWithAllErrors = (resultList) => {
-      let acc = ok4([]);
+      let acc = ok5([]);
       for (const result of resultList) {
         if (result.isErr() && acc.isErr()) {
           acc.error.push(result.error);
         } else if (result.isErr() && acc.isOk()) {
-          acc = err4([result.error]);
+          acc = err5([result.error]);
         } else if (result.isOk() && acc.isOk()) {
           acc.value.push(result.value);
         }
@@ -340,9 +340,9 @@ var require_index_cjs = __commonJS({
         return (...args) => {
           try {
             const result = fn(...args);
-            return ok4(result);
+            return ok5(result);
           } catch (e) {
-            return err4(errorFn ? errorFn(e) : e);
+            return err5(errorFn ? errorFn(e) : e);
           }
         };
       }
@@ -356,11 +356,11 @@ var require_index_cjs = __commonJS({
       }
       Result.combineWithAllErrors = combineWithAllErrors;
     })(exports2.Result || (exports2.Result = {}));
-    function ok4(value) {
+    function ok5(value) {
       return new Ok(value);
     }
-    function err4(err5) {
-      return new Err(err5);
+    function err5(err6) {
+      return new Err(err6);
     }
     function safeTry(body) {
       const n = body().next();
@@ -380,11 +380,11 @@ var require_index_cjs = __commonJS({
         return !this.isOk();
       }
       map(f) {
-        return ok4(f(this.value));
+        return ok5(f(this.value));
       }
       // eslint-disable-next-line @typescript-eslint/no-unused-vars
       mapErr(_f) {
-        return ok4(this.value);
+        return ok5(this.value);
       }
       // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/explicit-module-boundary-types
       andThen(f) {
@@ -399,14 +399,14 @@ var require_index_cjs = __commonJS({
           f(this.value);
         } catch (e) {
         }
-        return ok4(this.value);
+        return ok5(this.value);
       }
       orTee(_f) {
-        return ok4(this.value);
+        return ok5(this.value);
       }
       // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/explicit-module-boundary-types
       orElse(_f) {
-        return ok4(this.value);
+        return ok5(this.value);
       }
       asyncAndThen(f) {
         return f(this.value);
@@ -423,8 +423,8 @@ var require_index_cjs = __commonJS({
         return this.value;
       }
       // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      match(ok5, _err) {
-        return ok5(this.value);
+      match(ok6, _err) {
+        return ok6(this.value);
       }
       safeUnwrap() {
         const value = this.value;
@@ -455,27 +455,27 @@ var require_index_cjs = __commonJS({
       }
       // eslint-disable-next-line @typescript-eslint/no-unused-vars
       map(_f) {
-        return err4(this.error);
+        return err5(this.error);
       }
       mapErr(f) {
-        return err4(f(this.error));
+        return err5(f(this.error));
       }
       andThrough(_f) {
-        return err4(this.error);
+        return err5(this.error);
       }
       andTee(_f) {
-        return err4(this.error);
+        return err5(this.error);
       }
       orTee(f) {
         try {
           f(this.error);
         } catch (e) {
         }
-        return err4(this.error);
+        return err5(this.error);
       }
       // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/explicit-module-boundary-types
       andThen(_f) {
-        return err4(this.error);
+        return err5(this.error);
       }
       // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/explicit-module-boundary-types
       orElse(f) {
@@ -495,13 +495,13 @@ var require_index_cjs = __commonJS({
       unwrapOr(v) {
         return v;
       }
-      match(_ok, err5) {
-        return err5(this.error);
+      match(_ok, err6) {
+        return err6(this.error);
       }
       safeUnwrap() {
         const error48 = this.error;
         return (function* () {
-          yield err4(error48);
+          yield err5(error48);
           throw new Error("Do not use this generator out of `safeTry`");
         })();
       }
@@ -521,13 +521,13 @@ var require_index_cjs = __commonJS({
     exports2.Err = Err;
     exports2.Ok = Ok;
     exports2.ResultAsync = ResultAsync2;
-    exports2.err = err4;
+    exports2.err = err5;
     exports2.errAsync = errAsync2;
     exports2.fromAsyncThrowable = fromAsyncThrowable;
     exports2.fromPromise = fromPromise;
     exports2.fromSafePromise = fromSafePromise;
     exports2.fromThrowable = fromThrowable3;
-    exports2.ok = ok4;
+    exports2.ok = ok5;
     exports2.okAsync = okAsync;
     exports2.safeTry = safeTry;
   }
@@ -5320,8 +5320,8 @@ var require_resolve_flow_scalar = __commonJS({
     };
     function parseCharCode(source, offset, length, onError) {
       const cc = source.substr(offset, length);
-      const ok4 = cc.length === length && /^[0-9a-fA-F]+$/.test(cc);
-      const code = ok4 ? parseInt(cc, 16) : NaN;
+      const ok5 = cc.length === length && /^[0-9a-fA-F]+$/.test(cc);
+      const code = ok5 ? parseInt(cc, 16) : NaN;
       if (isNaN(code)) {
         const raw = source.substr(offset - 2, length + 2);
         onError(offset - 2, "BAD_DQ_ESCAPE", `Invalid escape sequence ${raw}`);
@@ -21736,7 +21736,7 @@ function redactCause(value) {
 
 // ../../packages/shared/dist/spec.js
 var import_neverthrow3 = __toESM(require_index_cjs(), 1);
-var ID_REGEX = /^[a-z0-9][a-z0-9-]*(\.[a-z0-9-]+)*$/;
+var ID_REGEX = /^[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)*$/;
 var toSpecId = (value) => ID_REGEX.test(value) ? (0, import_neverthrow3.ok)(value) : (0, import_neverthrow3.err)({ type: "CATALOG_INVALID_ID", kind: "spec", id: value });
 var toSuiteId = (value) => ID_REGEX.test(value) ? (0, import_neverthrow3.ok)(value) : (0, import_neverthrow3.err)({ type: "CATALOG_INVALID_ID", kind: "suite", id: value });
 
@@ -21744,8 +21744,88 @@ var toSuiteId = (value) => ID_REGEX.test(value) ? (0, import_neverthrow3.ok)(val
 var CATALOG_INTERFACE_VERSION = 1;
 
 // ../../packages/shared/dist/parse-spec-shared.js
-var import_neverthrow4 = __toESM(require_index_cjs(), 1);
+var import_neverthrow5 = __toESM(require_index_cjs(), 1);
 var yaml = __toESM(require_dist(), 1);
+
+// ../../packages/shared/dist/parse-spec-steps.js
+var import_neverthrow4 = __toESM(require_index_cjs(), 1);
+var STEP_LINE_PATTERN = /^\d+\.\s+(.*)$/;
+var UNICODE_ARROW = " \u2192 ";
+var ASCII_ARROW = " -> ";
+var OPTIONAL_PREFIX = "(optional) ";
+var HINT_PATTERN = /\s*\[hint:\s*(?:"([^"]*)"|([^\]]+?))\s*\]\s*$/i;
+var ASSERTION_BULLET = "- ";
+function splitHint(text) {
+  const match = HINT_PATTERN.exec(text);
+  if (match === null) {
+    return { text: text.trim() };
+  }
+  const hintValue = (match[1] ?? match[2] ?? "").trim();
+  const stripped = text.slice(0, text.length - match[0].length).trim();
+  if (hintValue === "") {
+    return { text: stripped };
+  }
+  return { text: stripped, hint: hintValue };
+}
+function splitOptional(raw) {
+  if (raw.startsWith(OPTIONAL_PREFIX)) {
+    return { body: raw.slice(OPTIONAL_PREFIX.length), isOptional: true };
+  }
+  return { body: raw, isOptional: false };
+}
+function findArrowIndex(body) {
+  const unicodeIndex = body.indexOf(UNICODE_ARROW);
+  if (unicodeIndex !== -1) {
+    return unicodeIndex;
+  }
+  return body.indexOf(ASCII_ARROW);
+}
+function arrowLength(body, arrowIndex) {
+  return body.startsWith(UNICODE_ARROW, arrowIndex) ? UNICODE_ARROW.length : ASCII_ARROW.length;
+}
+function buildStepWithoutOutcome({ body, index, isOptional }) {
+  const { text, hint } = splitHint(body);
+  if (hint === void 0) {
+    return { index, intent: text, isOptional };
+  }
+  return { index, intent: text, hint, isOptional };
+}
+function buildStepWithOutcome({ intent, remainder, index, isOptional }) {
+  const { text: outcome, hint } = splitHint(remainder);
+  if (hint === void 0) {
+    return { index, intent, outcome, isOptional };
+  }
+  return { index, intent, outcome, hint, isOptional };
+}
+function buildStep(raw, index) {
+  const { body, isOptional } = splitOptional(raw);
+  const arrowIndex = findArrowIndex(body);
+  if (arrowIndex === -1) {
+    return buildStepWithoutOutcome({ body, index, isOptional });
+  }
+  const intent = body.slice(0, arrowIndex).trim();
+  const remainder = body.slice(arrowIndex + arrowLength(body, arrowIndex));
+  return buildStepWithOutcome({ intent, remainder, index, isOptional });
+}
+function parseStepLine(line, index) {
+  const match = STEP_LINE_PATTERN.exec(line.trim());
+  return match === null ? void 0 : buildStep(match[1] ?? "", index);
+}
+function parseSteps(stepsBody) {
+  const steps = stepsBody.split("\n").map((line, index) => parseStepLine(line, index + 1)).filter((step) => step !== void 0);
+  if (steps.length === 0) {
+    return (0, import_neverthrow4.err)({ type: "EMPTY_STEPS_SECTION" });
+  }
+  return (0, import_neverthrow4.ok)(steps);
+}
+function parseAssertions(body) {
+  if (body === void 0 || body.trim() === "") {
+    return [];
+  }
+  return body.split("\n").map((line) => line.trim()).filter((line) => line.startsWith(ASSERTION_BULLET)).map((line) => line.slice(ASSERTION_BULLET.length).trim());
+}
+
+// ../../packages/shared/dist/parse-spec-shared.js
 var FRONTMATTER_OPEN = "---\n";
 var FRONTMATTER_CLOSE = "\n---\n";
 var FRONTMATTER_EMPTY_CLOSE = "---\n";
@@ -21756,13 +21836,22 @@ var SECTION_HEADING_PREFIX = "## ";
 var SETUP_HEADING = "## Setup";
 var STEPS_HEADING = "## Steps";
 var ASSERTIONS_HEADING = "## Assertions";
-var STEP_LINE_PATTERN = /^\d+\.\s+(.*)$/;
-var ARROW_SEPARATOR = " \u2192 ";
-var HINT_PATTERN = /\s*\[hint:\s*([^\]]+)\]\s*$/;
-var ASSERTION_BULLET = "- ";
-var safeParseYaml = (0, import_neverthrow4.fromThrowable)((text) => yaml.parse(text), (cause) => ({
-  type: "STORED_SPEC_PARSE_FAILED",
-  reason: "malformed yaml",
+var VARIANT_PATTERN = /^##\s+(.+)$/;
+var URL_PATTERN = /^https?:\/\//;
+var STATUS_VALUES = ["draft", "active", "deprecated"];
+var frontmatterSchema = external_exports.object({
+  id: external_exports.string().regex(ID_REGEX, { message: "invalid id slug" }),
+  feature: external_exports.string().min(1).refine((value) => value.trim().length > 0, { message: "feature cannot be blank" }),
+  owner: external_exports.string().optional(),
+  status: external_exports.enum(STATUS_VALUES).default("active"),
+  tags: external_exports.array(external_exports.string()).default([]),
+  requires: external_exports.array(external_exports.string()).default([]),
+  links: external_exports.array(external_exports.string().regex(URL_PATTERN, { message: "must be a URL" })).default([]),
+  scenarioId: external_exports.string().min(1).optional(),
+  timeout: external_exports.number().int().positive().optional()
+});
+var safeParseYaml = (0, import_neverthrow5.fromThrowable)((text) => yaml.parse(text), (cause) => ({
+  type: "MALFORMED_FRONTMATTER",
   cause
 }));
 function normalizeRawInput(value) {
@@ -21771,49 +21860,45 @@ function normalizeRawInput(value) {
 }
 function splitFrontmatter(raw) {
   if (!raw.startsWith(FRONTMATTER_OPEN)) {
-    return (0, import_neverthrow4.err)({ type: "STORED_SPEC_PARSE_FAILED", reason: "missing frontmatter" });
+    return (0, import_neverthrow5.err)({ type: "MALFORMED_FRONTMATTER", cause: "missing frontmatter delimiter" });
   }
   const afterOpen = raw.slice(FRONTMATTER_OPEN.length);
   if (afterOpen.startsWith(FRONTMATTER_EMPTY_CLOSE)) {
-    return (0, import_neverthrow4.ok)({
+    return (0, import_neverthrow5.ok)({
       frontmatterRaw: "",
       body: afterOpen.slice(FRONTMATTER_EMPTY_CLOSE.length)
     });
   }
   const closeIndex = afterOpen.indexOf(FRONTMATTER_CLOSE);
   if (closeIndex === -1) {
-    return (0, import_neverthrow4.err)({ type: "STORED_SPEC_PARSE_FAILED", reason: "missing frontmatter" });
+    return (0, import_neverthrow5.err)({ type: "MALFORMED_FRONTMATTER", cause: "missing frontmatter delimiter" });
   }
-  return (0, import_neverthrow4.ok)({
+  return (0, import_neverthrow5.ok)({
     frontmatterRaw: afterOpen.slice(0, closeIndex),
     body: afterOpen.slice(closeIndex + FRONTMATTER_CLOSE.length)
   });
 }
 function normalizeFrontmatter(value) {
   if (value === null || value === void 0) {
-    return (0, import_neverthrow4.ok)({});
+    return (0, import_neverthrow5.ok)({});
   }
   if (typeof value !== "object" || Array.isArray(value)) {
-    return (0, import_neverthrow4.err)({ type: "STORED_SPEC_PARSE_FAILED", reason: "malformed yaml" });
+    return (0, import_neverthrow5.err)({ type: "MALFORMED_FRONTMATTER", cause: "frontmatter must be a mapping" });
   }
-  return (0, import_neverthrow4.ok)(value);
+  return (0, import_neverthrow5.ok)(value);
 }
 function parseFrontmatterYaml(yamlText) {
   if (yamlText.trim() === "") {
-    return (0, import_neverthrow4.ok)({});
+    return (0, import_neverthrow5.ok)({});
   }
   return safeParseYaml(yamlText).andThen(normalizeFrontmatter);
 }
-function extractRequiredFeature(fm) {
-  const value = fm.feature;
-  if (typeof value !== "string" || value.trim() === "") {
-    return (0, import_neverthrow4.err)({ type: "STORED_SPEC_PARSE_FAILED", reason: "missing feature" });
+function validateFrontmatter(raw) {
+  const parsed = frontmatterSchema.safeParse(raw);
+  if (!parsed.success) {
+    return (0, import_neverthrow5.err)({ type: "MALFORMED_FRONTMATTER", cause: parsed.error });
   }
-  return (0, import_neverthrow4.ok)(value);
-}
-function extractOptionalNumber(fm, key) {
-  const value = fm[key];
-  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+  return (0, import_neverthrow5.ok)(parsed.data);
 }
 function findHeadingLine(lines, heading) {
   return lines.findIndex((line) => line.trim() === heading);
@@ -21832,81 +21917,55 @@ function extractSection(body, heading) {
   const endIndex = findNextHeadingIndex(lines, afterHeading);
   return lines.slice(afterHeading, endIndex).join("\n").trim();
 }
+function findCaseVariant(body, expected) {
+  const expectedLower = expected.slice("## ".length).toLowerCase();
+  const lines = body.split("\n");
+  for (const line of lines) {
+    const match = VARIANT_PATTERN.exec(line.trim());
+    const heading = match?.[1];
+    if (heading !== void 0 && heading !== expected.slice("## ".length) && heading.toLowerCase() === expectedLower) {
+      return `## ${heading}`;
+    }
+  }
+  return void 0;
+}
 function extractSpecSections(body) {
   const setup = extractSection(body, SETUP_HEADING);
   if (setup === void 0) {
-    return (0, import_neverthrow4.err)({ type: "STORED_SPEC_PARSE_FAILED", reason: "missing setup section" });
+    const suggestedHeading = findCaseVariant(body, SETUP_HEADING);
+    return (0, import_neverthrow5.err)(suggestedHeading === void 0 ? { type: "MISSING_SETUP_SECTION" } : { type: "MISSING_SETUP_SECTION", suggestedHeading });
   }
   const stepsBody = extractSection(body, STEPS_HEADING);
   if (stepsBody === void 0) {
-    return (0, import_neverthrow4.err)({ type: "STORED_SPEC_PARSE_FAILED", reason: "missing steps section" });
-  }
-  return (0, import_neverthrow4.ok)({ setup, stepsBody, assertionsBody: extractSection(body, ASSERTIONS_HEADING) });
-}
-function splitHint(text) {
-  const match = HINT_PATTERN.exec(text);
-  if (match === null) {
-    return { text: text.trim() };
-  }
-  const hintValue = match[1]?.trim();
-  const stripped = text.slice(0, text.length - match[0].length).trim();
-  if (hintValue === void 0 || hintValue === "") {
-    return { text: stripped };
-  }
-  return { text: stripped, hint: hintValue };
-}
-function buildStepWithoutOutcome(body) {
-  const { text, hint } = splitHint(body);
-  return hint === void 0 ? { intent: text } : { intent: text, hint };
-}
-function buildStepWithOutcome(intent, remainder) {
-  const { text: outcome, hint } = splitHint(remainder);
-  if (hint === void 0) {
-    return { intent, outcome };
-  }
-  return { intent, outcome, hint };
-}
-function buildStep(body) {
-  const arrowIndex = body.indexOf(ARROW_SEPARATOR);
-  if (arrowIndex === -1) {
-    return buildStepWithoutOutcome(body);
-  }
-  const intent = body.slice(0, arrowIndex).trim();
-  const remainder = body.slice(arrowIndex + ARROW_SEPARATOR.length);
-  return buildStepWithOutcome(intent, remainder);
-}
-function parseStepLine(line) {
-  const match = STEP_LINE_PATTERN.exec(line.trim());
-  return match === null ? void 0 : buildStep(match[1] ?? "");
-}
-function parseSteps(stepsBody) {
-  const steps = stepsBody.split("\n").map((line) => parseStepLine(line)).filter((step) => step !== void 0);
-  if (steps.length === 0) {
-    return (0, import_neverthrow4.err)({ type: "STORED_SPEC_PARSE_FAILED", reason: "empty steps section" });
-  }
-  return (0, import_neverthrow4.ok)(steps);
-}
-function parseAssertions(body) {
-  if (body === void 0 || body.trim() === "") {
-    return void 0;
-  }
-  const items = body.split("\n").map((line) => line.trim()).filter((line) => line.startsWith(ASSERTION_BULLET)).map((line) => line.slice(ASSERTION_BULLET.length).trim());
-  return items.length === 0 ? void 0 : items;
-}
-function buildSpec(input) {
-  const base = { feature: input.feature, setup: input.setup, steps: input.steps };
-  const withAssertions = input.assertions === void 0 ? base : { ...base, assertions: input.assertions };
-  return input.timeoutMs === void 0 ? withAssertions : { ...withAssertions, timeoutMs: input.timeoutMs };
+    const suggestedHeading = findCaseVariant(body, STEPS_HEADING);
+    return (0, import_neverthrow5.err)(suggestedHeading === void 0 ? { type: "MISSING_STEPS_SECTION" } : { type: "MISSING_STEPS_SECTION", suggestedHeading });
+  }
+  return (0, import_neverthrow5.ok)({ setup, stepsBody, assertionsBody: extractSection(body, ASSERTIONS_HEADING) });
+}
+function buildSpec({ fm, setup, steps, assertions }) {
+  const base = {
+    id: fm.id,
+    feature: fm.feature,
+    status: fm.status,
+    tags: fm.tags,
+    requires: fm.requires,
+    links: fm.links,
+    setup,
+    steps,
+    assertions
+  };
+  const withOwner = fm.owner === void 0 ? base : { ...base, owner: fm.owner };
+  const withScenarioId = fm.scenarioId === void 0 ? withOwner : { ...withOwner, scenarioId: fm.scenarioId };
+  return fm.timeout === void 0 ? withScenarioId : { ...withScenarioId, timeoutSeconds: fm.timeout };
 }
 function parseSpecShared(raw) {
   const normalized = normalizeRawInput(raw);
-  return splitFrontmatter(normalized).andThen(({ frontmatterRaw, body }) => parseFrontmatterYaml(frontmatterRaw).andThen((frontmatter) => extractRequiredFeature(frontmatter).andThen((feature) => extractSpecSections(body).andThen((sections) => parseSteps(sections.stepsBody).map((steps) => ({
+  return splitFrontmatter(normalized).andThen(({ frontmatterRaw, body }) => parseFrontmatterYaml(frontmatterRaw).andThen((frontmatter) => validateFrontmatter(frontmatter).andThen((fm) => extractSpecSections(body).andThen((sections) => parseSteps(sections.stepsBody).map((steps) => ({
     spec: buildSpec({
-      feature,
+      fm,
       setup: sections.setup,
       steps,
-      assertions: parseAssertions(sections.assertionsBody),
-      timeoutMs: extractOptionalNumber(frontmatter, "timeout")
+      assertions: parseAssertions(sections.assertionsBody)
     }),
     frontmatter
   }))))));
@@ -21916,7 +21975,7 @@ function parseSpecShared(raw) {
 var yaml2 = __toESM(require_dist(), 1);
 
 // ../../packages/shared/dist/retry.js
-var import_neverthrow5 = __toESM(require_index_cjs(), 1);
+var import_neverthrow6 = __toESM(require_index_cjs(), 1);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CATALOG_INTERFACE_VERSION,

package/dist/consumer-api.d.ts

@@ -73,16 +73,26 @@ export type SuiteId = string & {
 	readonly __brand: "SuiteId";
 };
 export interface SpecStep {
+	readonly index: number;
 	readonly intent: string;
 	readonly outcome?: string;
 	readonly hint?: string;
+	readonly isOptional: boolean;
 }
+export type SpecStatus = "draft" | "active" | "deprecated";
 export interface Spec {
+	readonly id: SpecId;
 	readonly feature: string;
+	readonly owner?: string;
+	readonly status: SpecStatus;
+	readonly tags: readonly string[];
+	readonly requires: readonly string[];
+	readonly links: readonly string[];
+	readonly scenarioId?: string;
+	readonly timeoutSeconds?: number;
 	readonly setup: string;
 	readonly steps: readonly SpecStep[];
-	readonly assertions?: readonly string[];
-	readonly timeoutMs?: number;
+	readonly assertions: readonly string[];
 }
 export interface CatalogSpec {
 	readonly id: SpecId;
@@ -118,14 +128,21 @@ export interface Catalog {
 	getSpecs(): ResultAsync<readonly CatalogSpec[], CatalogError>;
 	getSuites(): ResultAsync<readonly CatalogSuite[], CatalogError>;
 }
-export interface SharedSpecError {
-	readonly type: "STORED_SPEC_PARSE_FAILED";
-	readonly reason: string;
-	readonly cause?: unknown;
-}
+export type SpecParseError = {
+	type: "MALFORMED_FRONTMATTER";
+	cause: unknown;
+} | {
+	type: "MISSING_SETUP_SECTION";
+	suggestedHeading?: string;
+} | {
+	type: "MISSING_STEPS_SECTION";
+	suggestedHeading?: string;
+} | {
+	type: "EMPTY_STEPS_SECTION";
+};
 export declare function parseSpecShared(raw: string): Result<{
 	readonly spec: Spec;
 	readonly frontmatter: Record<string, unknown>;
-}, SharedSpecError>;
+}, SpecParseError>;
 
 export {};