@open-agent-toolkit/cli 0.2.72 → 0.2.74

package/assets/skills/explainer-kit/scripts/lib/failure.mjs

@@ -0,0 +1,13 @@
+export const FLOW_FAILURE_STAGES = Object.freeze([
+  'bundle',
+  'authoring',
+  'verify',
+  'core',
+  'interrupted',
+]);
+
+const FLOW_FAILURE_STAGE_SET = new Set(FLOW_FAILURE_STAGES);
+
+export function isFlowFailureStage(value) {
+  return FLOW_FAILURE_STAGE_SET.has(value);
+}

package/assets/skills/explainer-kit/scripts/lib/package-coverage.mjs

@@ -1,51 +1,75 @@
-import { createHash } from 'node:crypto';
 import { lstat, readdir, realpath, rm } from 'node:fs/promises';
 import { dirname, isAbsolute, join, relative, sep } from 'node:path';
 
-import { browserCaptureIdentity } from './browser-runtime.mjs';
-import { canonicalHash, validateContract } from './contracts.mjs';
+export const PACKAGE_COVERAGE_VERSION = 'explainer-kit.package-coverage/v3';
+const CONDITIONAL_SCREENSHOT_PATHS = [
+  'qa/320.png',
+  'qa/768.png',
+  'qa/1440.png',
+];
 
-export const PACKAGE_COVERAGE_VERSION = 'explainer-kit.package-coverage/v2';
-export const SET_PLAN_RECORD_PATHS = Object.freeze([
-  'source/set-plan/request.json',
-  'source/set-plan/result.json',
-  'source/set-plan/ledger.json',
-  'source/set-plan/portfolio.json',
-  'source/set-plan/drafts.json',
-]);
-export const VISUAL_REVISION_PATH = 'qa/visual-review/revision.json';
-
-const REVIEW_VIEWPORTS = Object.freeze(['mobile', 'tablet', 'desktop']);
-const SUCCESSFUL_OUTCOMES = new Set(['built-not-durable', 'built-durable']);
-const PARTIAL_REVIEW_OUTCOME = 'built-needs-review';
+export function requiredImmutablePackagePaths(manifest) {
+  if (!isObject(manifest)) {
+    throw new TypeError(
+      'Manifest package coverage requires a manifest object.',
+    );
+  }
+  return [
+    ...new Set([
+      'theme.resolved.json',
+      'source/fact-base.json',
+      'source/fact-base.md',
+      'source/ledger.json',
+      'qa/result.json',
+      ...(manifest.artifacts ?? []).map(({ contentPath }) => contentPath),
+    ]),
+  ];
+}
 
-export function permissibleRunPackagePaths(
-  manifest,
-  { includeManifest = true, includeTerminalEvidence = false } = {},
-) {
+export function permissibleRunPackagePaths(manifest) {
   if (!isObject(manifest) || !isObject(manifest.immutableHashes)) {
     throw new TypeError(
       'Run package inventory requires a manifest with immutable hashes.',
     );
   }
   const paths = new Set([
-    ...Object.keys(manifest.immutableHashes),
-    'build-record.json',
-    ...(includeManifest ? ['manifest.json'] : []),
-    ...(includeTerminalEvidence ? ['terminal-evidence.json'] : []),
+    ...requiredImmutablePackagePaths(manifest),
+    ...CONDITIONAL_SCREENSHOT_PATHS.filter(
+      (path) => path in manifest.immutableHashes,
+    ),
+    'manifest.json',
   ]);
   for (const path of paths) assertInventoryPath(path);
   return [...paths].sort();
 }
 
+export function validateImmutablePackageEvidence(manifest) {
+  if (!isObject(manifest) || !isObject(manifest.immutableHashes)) {
+    throw new TypeError(
+      'Manifest package coverage requires immutable hash evidence.',
+    );
+  }
+  const expected = new Set(
+    permissibleRunPackagePaths(manifest).filter(
+      (path) => path !== 'manifest.json',
+    ),
+  );
+  const actual = Object.keys(manifest.immutableHashes);
+  const missing = [...expected].filter(
+    (path) => !(path in manifest.immutableHashes),
+  );
+  const unexpected = actual.filter((path) => !expected.has(path));
+  if (missing.length > 0 || unexpected.length > 0) {
+    throw new Error(
+      `Manifest immutable hashes do not match the canonical package: missing [${missing.join(', ')}]; unexpected [${unexpected.join(', ')}].`,
+    );
+  }
+}
+
 export async function enforceRunPackageInventory(
   runRoot,
   manifest,
-  {
-    includeManifest = true,
-    includeTerminalEvidence = false,
-    removeUnexpected = false,
-  } = {},
+  { removeUnexpected = false } = {},
 ) {
   if (typeof runRoot !== 'string' || runRoot.length === 0) {
     throw new TypeError('Run package inventory requires a run root.');
@@ -56,12 +80,8 @@ export async function enforceRunPackageInventory(
     throw new Error('Run package inventory root is not a real directory.');
   }
 
-  const allowedFiles = new Set(
-    permissibleRunPackagePaths(manifest, {
-      includeManifest,
-      includeTerminalEvidence,
-    }),
-  );
+  validateImmutablePackageEvidence(manifest);
+  const allowedFiles = new Set(permissibleRunPackagePaths(manifest));
   const allowedDirectories = new Set();
   for (const path of allowedFiles) {
     let parent = dirname(path);
@@ -107,326 +127,6 @@ export async function enforceRunPackageInventory(
   return [...presentFiles].sort();
 }
 
-export function requiredImmutablePackagePaths(manifest, { runMode } = {}) {
-  if (!isObject(manifest)) {
-    throw new TypeError(
-      'Manifest package coverage requires a manifest object.',
-    );
-  }
-  if (
-    runMode !== undefined &&
-    runMode !== 'interactive' &&
-    runMode !== 'unattended'
-  ) {
-    throw new TypeError(
-      'Manifest package coverage run mode must be interactive or unattended.',
-    );
-  }
-
-  const required = new Set([
-    'run-request.json',
-    'source/content-approval.json',
-    manifest.source?.factBasePath,
-    'source/fact-base.md',
-    ...(manifest.source?.authorResultPaths ?? []),
-    manifest.theme?.path,
-    ...(manifest.artifacts ?? []).flatMap((artifact) => [
-      artifact.contentPath,
-      ...(artifact.status === 'built' &&
-      typeof artifact.renderedPath === 'string'
-        ? [artifact.renderedPath]
-        : []),
-    ]),
-  ]);
-  required.delete(undefined);
-
-  if (manifest.recipe?.id !== 'project-recap') return [...required];
-
-  const successful = SUCCESSFUL_OUTCOMES.has(manifest.outcome);
-  if (successful) {
-    for (const path of SET_PLAN_RECORD_PATHS) required.add(path);
-  }
-
-  const recorded = Object.keys(manifest.immutableHashes ?? {});
-  if (manifest.outcome === PARTIAL_REVIEW_OUTCOME) return [...required];
-
-  const retainsReviewMaterial = recorded.some(isReviewMaterial);
-  const requireAttemptOne =
-    (successful && runMode === 'unattended') ||
-    (successful && runMode === 'interactive' && retainsReviewMaterial) ||
-    (!successful && retainsReviewMaterial);
-  const retainsAttemptTwo = recorded.some(isAttemptTwoMaterial);
-
-  if (requireAttemptOne || retainsAttemptTwo) {
-    addVisualReviewAttemptPaths(required, manifest, 1);
-  }
-  if (retainsAttemptTwo) {
-    required.add(VISUAL_REVISION_PATH);
-    addVisualReviewAttemptPaths(required, manifest, 2);
-  }
-  return [...required];
-}
-
-export async function validateImmutablePackageEvidence(
-  manifest,
-  { runMode, read } = {},
-) {
-  const requiredPaths = requiredImmutablePackagePaths(manifest, { runMode });
-  const missing = requiredPaths.filter(
-    (path) => !(path in (manifest?.immutableHashes ?? {})),
-  );
-  if (missing.length > 0) {
-    throw new Error(
-      `Manifest immutable hashes do not cover the canonical package: ${missing.join(', ')}.`,
-    );
-  }
-  if (manifest?.recipe?.id !== 'project-recap') return;
-
-  const recorded = Object.keys(manifest.immutableHashes ?? {});
-  if (recorded.some(isLegacyReviewMaterial)) {
-    throw new Error(
-      'Legacy review-gate evidence is not part of the canonical package.',
-    );
-  }
-  const successful = SUCCESSFUL_OUTCOMES.has(manifest.outcome);
-  const retainsReviewMaterial = recorded.some(isReviewMaterial);
-  if (manifest.outcome === PARTIAL_REVIEW_OUTCOME) return;
-  const requireAttemptOne =
-    (successful && runMode === 'unattended') ||
-    (successful && runMode === 'interactive' && retainsReviewMaterial) ||
-    (!successful &&
-      manifest.outcome !== PARTIAL_REVIEW_OUTCOME &&
-      retainsReviewMaterial);
-  const retainsAttemptTwo = recorded.some(isAttemptTwoMaterial);
-  if (!requireAttemptOne && !retainsAttemptTwo) return;
-  if (typeof read !== 'function') {
-    throw new TypeError(
-      'Canonical browser evidence validation requires an immutable package reader.',
-    );
-  }
-
-  const readVerified = async (path) => {
-    const value = await read(path);
-    const bytes = Buffer.isBuffer(value) ? value : Buffer.from(value);
-    const expected = manifest.immutableHashes[path];
-    const actual = `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
-    if (actual !== expected) {
-      throw new Error(`Immutable package hash mismatch for ${path}.`);
-    }
-    return bytes;
-  };
-  const builtArtifacts = (manifest.artifacts ?? []).filter(
-    ({ status }) => status === 'built',
-  );
-  const browserRecords = new Map();
-  let expectedRuntimeHash;
-  let expectedCaptureIdentity;
-  for (const artifact of builtArtifacts) {
-    for (const viewport of REVIEW_VIEWPORTS) {
-      const metricsPath = `qa/browser/${artifact.id}/${viewport}.json`;
-      const bytes = await readVerified(metricsPath);
-      const screenshotPath = `qa/browser/${artifact.id}/${viewport}.png`;
-      const screenshotBytes = await readVerified(screenshotPath);
-      if (!isPng(screenshotBytes)) {
-        throw new Error(
-          `Browser screenshot evidence ${screenshotPath} is not a PNG.`,
-        );
-      }
-      const record = parseJson(bytes, metricsPath);
-      validateBrowserEvidenceRecord(record, {
-        artifactId: artifact.id,
-        viewport,
-        metricsPath,
-        requireLaunched: successful && runMode === 'unattended',
-      });
-      const runtimeHash = canonicalHash(record.runtime);
-      expectedRuntimeHash ??= runtimeHash;
-      expectedCaptureIdentity ??= record.captureIdentity;
-      if (
-        runtimeHash !== expectedRuntimeHash ||
-        record.captureIdentity !== expectedCaptureIdentity
-      ) {
-        throw new Error(
-          `Browser runtime or capture identity mismatch in ${metricsPath}.`,
-        );
-      }
-      browserRecords.set(metricsPath, { bytes, record, screenshotBytes });
-    }
-  }
-
-  const attempts = retainsAttemptTwo ? [1, 2] : [1];
-  let terminalResult;
-  for (const attempt of attempts) {
-    const root = `qa/visual-review/attempt-${attempt}`;
-    const requestPath = `${root}/request.json`;
-    const request = parseJson(await readVerified(requestPath), requestPath);
-    const requestValidation = validateContract(
-      'visual-review-request',
-      request,
-    );
-    if (!requestValidation.valid) {
-      throw new Error(
-        `Immutable visual-review request ${requestPath} is invalid: ${requestValidation.errors
-          .map(({ code }) => code)
-          .join(', ')}.`,
-      );
-    }
-    if (
-      canonicalHash(request.browserRuntime) !== expectedRuntimeHash ||
-      request.captureIdentity !== expectedCaptureIdentity
-    ) {
-      throw new Error(
-        `Visual-review browser runtime or capture identity mismatch in ${requestPath}.`,
-      );
-    }
-    const requestEvidence = new Map(
-      request.renderedArtifacts.flatMap((artifact) =>
-        artifact.evidence.map((evidence) => [
-          `${artifact.artifactId}:${evidence.viewport}`,
-          evidence,
-        ]),
-      ),
-    );
-    for (const artifact of builtArtifacts) {
-      for (const viewport of REVIEW_VIEWPORTS) {
-        const key = `${artifact.id}:${viewport}`;
-        const evidence = requestEvidence.get(key);
-        const sourceMetricsPath = `qa/browser/${artifact.id}/${viewport}.json`;
-        const sourceScreenshotPath = `qa/browser/${artifact.id}/${viewport}.png`;
-        if (
-          !evidence ||
-          evidence.metricsPath !== sourceMetricsPath ||
-          evidence.screenshotPath !== sourceScreenshotPath ||
-          evidence.captureIdentity !== expectedCaptureIdentity
-        ) {
-          throw new Error(
-            `Visual-review evidence binding mismatch for ${key} in ${requestPath}.`,
-          );
-        }
-        const copiedMetricsPath = `${root}/evidence/${artifact.id}/${viewport}.json`;
-        const copiedMetrics = await readVerified(copiedMetricsPath);
-        const copiedScreenshotPath = `${root}/evidence/${artifact.id}/${viewport}.png`;
-        const copiedScreenshot = await readVerified(copiedScreenshotPath);
-        if (!isPng(copiedScreenshot)) {
-          throw new Error(
-            `Retained visual-review screenshot ${copiedScreenshotPath} is not a PNG.`,
-          );
-        }
-        const copiedRecord = parseJson(copiedMetrics, copiedMetricsPath);
-        validateBrowserEvidenceRecord(copiedRecord, {
-          artifactId: artifact.id,
-          viewport,
-          metricsPath: copiedMetricsPath,
-          requireLaunched: successful && runMode === 'unattended',
-        });
-        if (
-          canonicalHash(copiedRecord.runtime) !== expectedRuntimeHash ||
-          copiedRecord.captureIdentity !== expectedCaptureIdentity
-        ) {
-          throw new Error(
-            `Retained visual-review browser runtime or capture identity mismatch in ${copiedMetricsPath}.`,
-          );
-        }
-        if (
-          evidence.metricsHash !==
-          `sha256:${createHash('sha256').update(copiedMetrics).digest('hex')}`
-        ) {
-          throw new Error(
-            `Visual-review metrics hash mismatch for ${key} in ${requestPath}.`,
-          );
-        }
-        if (
-          evidence.screenshotHash !==
-          `sha256:${createHash('sha256')
-            .update(copiedScreenshot)
-            .digest('hex')}`
-        ) {
-          throw new Error(
-            `Visual-review screenshot hash mismatch for ${key} in ${requestPath}.`,
-          );
-        }
-        if (attempt === attempts.at(-1)) {
-          const sourceMetrics = browserRecords.get(sourceMetricsPath);
-          if (
-            !copiedMetrics.equals(sourceMetrics.bytes) ||
-            !copiedScreenshot.equals(sourceMetrics.screenshotBytes)
-          ) {
-            throw new Error(
-              `Terminal visual-review evidence differs from ${sourceMetricsPath}.`,
-            );
-          }
-        }
-      }
-    }
-    if (
-      requestEvidence.size !==
-      builtArtifacts.length * REVIEW_VIEWPORTS.length
-    ) {
-      throw new Error(
-        `Visual-review evidence set in ${requestPath} does not match the complete browser record set.`,
-      );
-    }
-
-    const resultPath = `${root}/result.json`;
-    const result = parseJson(await readVerified(resultPath), resultPath);
-    const resultValidation = validateContract(
-      'visual-review-evidence',
-      result,
-      {
-        visualReviewRequest: request,
-        attempt,
-      },
-    );
-    if (!resultValidation.valid) {
-      throw new Error(
-        `Immutable visual-review evidence ${resultPath} is invalid: ${resultValidation.errors
-          .map(({ code }) => code)
-          .join(', ')}.`,
-      );
-    }
-    terminalResult = result;
-  }
-  if (successful && terminalResult?.disposition !== 'pass') {
-    throw new Error(
-      'Successful recap package requires a terminal passing visual review.',
-    );
-  }
-}
-
-function addVisualReviewAttemptPaths(required, manifest, attempt) {
-  const root = `qa/visual-review/attempt-${attempt}`;
-  required.add(`${root}/request.json`);
-  required.add(`${root}/result.json`);
-  for (const artifact of manifest.artifacts ?? []) {
-    if (artifact.status !== 'built') continue;
-    for (const viewport of REVIEW_VIEWPORTS) {
-      required.add(`qa/browser/${artifact.id}/${viewport}.png`);
-      required.add(`qa/browser/${artifact.id}/${viewport}.json`);
-      required.add(`${root}/evidence/${artifact.id}/${viewport}.png`);
-      required.add(`${root}/evidence/${artifact.id}/${viewport}.json`);
-    }
-  }
-}
-
-function isReviewMaterial(path) {
-  return path.startsWith('qa/browser/') || path.startsWith('qa/visual-review/');
-}
-
-function isLegacyReviewMaterial(path) {
-  return path.startsWith('qa/review-gate/');
-}
-
-function isAttemptTwoMaterial(path) {
-  return (
-    path === VISUAL_REVISION_PATH ||
-    path.startsWith('qa/visual-review/attempt-2/')
-  );
-}
-
-function isObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
 function assertInventoryPath(path) {
   if (
     typeof path !== 'string' ||
@@ -446,52 +146,6 @@ function assertInventoryPath(path) {
   }
 }
 
-function isPng(bytes) {
-  return (
-    bytes.length >= 8 &&
-    bytes
-      .subarray(0, 8)
-      .equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))
-  );
-}
-
-function validateBrowserEvidenceRecord(
-  record,
-  { artifactId, viewport, metricsPath, requireLaunched },
-) {
-  if (
-    !isObject(record) ||
-    record.schemaVersion !== 'explainer-kit.browser-evidence/v2' ||
-    record.artifactId !== artifactId ||
-    record.viewport !== viewport ||
-    record.scenario !== 'default' ||
-    !isObject(record.runtime) ||
-    !['launched', 'fixture'].includes(record.runtime.kind) ||
-    record.runtime.name !== 'chromium' ||
-    typeof record.runtime.version !== 'string' ||
-    record.runtime.version.length === 0 ||
-    !isObject(record.capture) ||
-    !/^sha256:[a-f0-9]{64}$/.test(record.captureIdentity ?? '') ||
-    record.captureIdentity !==
-      browserCaptureIdentity(record.runtime, record.capture)
-  ) {
-    throw new Error(
-      `Browser evidence ${metricsPath} does not satisfy explainer-kit.browser-evidence/v2.`,
-    );
-  }
-  if (requireLaunched && record.runtime.kind !== 'launched') {
-    throw new Error(
-      `Production browser evidence ${metricsPath} must identify launched Chromium, not a fixture session.`,
-    );
-  }
-}
-
-function parseJson(bytes, path) {
-  try {
-    return JSON.parse(bytes.toString('utf8'));
-  } catch {
-    throw new Error(
-      `Immutable package record ${path} must contain valid JSON.`,
-    );
-  }
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
 }

package/assets/skills/explainer-kit/scripts/lib/qa-result.mjs

@@ -0,0 +1,168 @@
+const HASH_PATTERN = /^sha256:[a-f0-9]{64}$/;
+const REQUIRED_CHECKS = [
+  'parse',
+  'requiredNarrative',
+  'structure',
+  'sourceDumping',
+  'shellScripts',
+  'ledgerToPage',
+  'pageToLedger',
+];
+const SCREENSHOTS = ['qa/320.png', 'qa/768.png', 'qa/1440.png'];
+const BROWSER_RUNGS = new Set(['host', 'playwright']);
+
+export function validateQaResult(value) {
+  requireObject(value, 'QA result');
+  requireExactKeys(
+    value,
+    [
+      'artifactSha256',
+      'checks',
+      'rung',
+      'reason',
+      'screenshots',
+      'visual',
+      'deferredBrowserRequest',
+    ],
+    ['artifactSha256', 'checks', 'rung', 'visual'],
+    'QA result',
+  );
+  if (!HASH_PATTERN.test(value.artifactSha256)) {
+    throw new TypeError('QA result artifactSha256 is invalid.');
+  }
+
+  requireObject(value.checks, 'QA checks');
+  requireExactKeys(value.checks, REQUIRED_CHECKS, REQUIRED_CHECKS, 'QA checks');
+  for (const [id, check] of Object.entries(value.checks)) {
+    requireObject(check, `QA check ${id}`);
+    if (check.status === 'pass') {
+      requireExactKeys(check, ['status'], ['status'], `QA check ${id}`);
+    } else if (check.status === 'fail') {
+      requireExactKeys(
+        check,
+        ['status', 'cause'],
+        ['status', 'cause'],
+        `QA check ${id}`,
+      );
+      requireNonEmptyString(check.cause, `QA check ${id} cause`);
+    } else {
+      throw new TypeError(`QA check ${id} status is invalid.`);
+    }
+  }
+
+  if (value.rung === 'none') {
+    requireExactKeys(
+      value.visual,
+      ['verdict'],
+      ['verdict'],
+      'QA visual result',
+    );
+    if (value.visual.verdict !== 'none') {
+      throw new TypeError('The none rung requires visual verdict none.');
+    }
+    requireNonEmptyString(value.reason, 'QA none-rung reason');
+    if (value.screenshots !== undefined) {
+      throw new TypeError('The none rung cannot claim screenshots.');
+    }
+  } else if (BROWSER_RUNGS.has(value.rung)) {
+    if (value.reason !== undefined) {
+      throw new TypeError('A browser rung cannot carry a runtime reason.');
+    }
+    if (
+      !Array.isArray(value.screenshots) ||
+      value.screenshots.length !== SCREENSHOTS.length ||
+      !value.screenshots.every((path, index) => path === SCREENSHOTS[index])
+    ) {
+      throw new TypeError(
+        'A browser rung requires the three canonical screenshots.',
+      );
+    }
+    validateBrowserVisual(value.visual);
+  } else {
+    throw new TypeError('QA result rung is invalid.');
+  }
+
+  if (value.deferredBrowserRequest !== undefined) {
+    validateDeferredBrowserRequest(value.deferredBrowserRequest);
+    if (value.rung !== 'none') {
+      throw new TypeError(
+        'A deferred browser request is valid only on the none rung.',
+      );
+    }
+  }
+  return value;
+}
+
+function validateBrowserVisual(visual) {
+  requireObject(visual, 'QA visual result');
+  if (visual.verdict === 'pass') {
+    requireExactKeys(
+      visual,
+      ['verdict', 'notes'],
+      ['verdict', 'notes'],
+      'QA visual result',
+    );
+    requireNonEmptyString(visual.notes, 'QA visual notes');
+    return;
+  }
+  if (visual.verdict === 'findings') {
+    requireExactKeys(
+      visual,
+      ['verdict', 'findings', 'notes'],
+      ['verdict', 'findings'],
+      'QA visual result',
+    );
+    if (
+      !Array.isArray(visual.findings) ||
+      visual.findings.length === 0 ||
+      !visual.findings.every(
+        (finding) => typeof finding === 'string' && finding.length > 0,
+      )
+    ) {
+      throw new TypeError('QA visual findings are invalid.');
+    }
+    if (visual.notes !== undefined) {
+      requireNonEmptyString(visual.notes, 'QA visual notes');
+    }
+    return;
+  }
+  throw new TypeError('QA visual verdict is invalid.');
+}
+
+function validateDeferredBrowserRequest(value) {
+  requireObject(value, 'Deferred browser request');
+  requireExactKeys(
+    value,
+    ['rung', 'screenshots', 'artifactSha256', 'visualVerdict', 'visualNotes'],
+    ['rung', 'screenshots', 'artifactSha256', 'visualVerdict'],
+    'Deferred browser request',
+  );
+  if (value.rung !== 'host') {
+    throw new TypeError('Deferred browser request rung is invalid.');
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    requireNonEmptyString(entry, `Deferred browser request ${key}`);
+  }
+}
+
+function requireExactKeys(value, allowed, required, label) {
+  const keys = Object.keys(value);
+  if (
+    keys.some((key) => !allowed.includes(key)) ||
+    required.some((key) => !keys.includes(key))
+  ) {
+    throw new TypeError(`${label} keys are invalid.`);
+  }
+}
+
+function requireObject(value, label) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object.`);
+  }
+}
+
+function requireNonEmptyString(value, label) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+}