simplicio-prompt 0.1.0

package/benchmarks/v2_safe_speed_results.json

@@ -0,0 +1,446 @@
+{
+  "title": "Yool Safe-Speed Benchmark V2",
+  "run_date": "2026-05-21",
+  "environment": {
+    "python": "3.14.3",
+    "repository": "wesleysimplicio/simplicio-prompt",
+    "branch": "codex/lane-concurrency-runtime",
+    "v1_definition": "high-throughput runtime with fixed lane ceiling and safe-speed controls disabled",
+    "v2_definition": "V1 plus cache, adaptive lanes, backoff, circuit breaker, batching, context compression, local routing, and idempotent speculation"
+  },
+  "results": [
+    {
+      "scenario": "scale_representation",
+      "profile": "normal instruction",
+      "wall_ms": 174.48919999878854,
+      "tasks": 131072,
+      "peak_kb": 28751.21875,
+      "provider_calls": 0,
+      "cache_hits": 0,
+      "blocked_calls": 0,
+      "total_agents": 131072,
+      "virtual_agents": 0,
+      "tokens": 0,
+      "notes": "flat list materialization",
+      "throughput_tasks_s": 751175.4309201373
+    },
+    {
+      "scenario": "scale_representation",
+      "profile": "V1 high-throughput",
+      "wall_ms": 0.07569999434053898,
+      "tasks": 1048576,
+      "peak_kb": 7.69921875,
+      "provider_calls": 0,
+      "cache_hits": 0,
+      "blocked_calls": 0,
+      "total_agents": 1048577,
+      "virtual_agents": 1048576,
+      "tokens": 0,
+      "notes": "lazy batch_spawn depth=4, branching=32",
+      "throughput_tasks_s": 13851731550.770605
+    },
+    {
+      "scenario": "scale_representation",
+      "profile": "V2 safe-speed",
+      "wall_ms": 0.05169998621568084,
+      "tasks": 1048576,
+      "peak_kb": 7.31640625,
+      "provider_calls": 0,
+      "cache_hits": 0,
+      "blocked_calls": 0,
+      "total_agents": 1048577,
+      "virtual_agents": 1048576,
+      "tokens": 0,
+      "notes": "lazy batch_spawn depth=4, branching=32",
+      "throughput_tasks_s": 20281939643.5731
+    },
+    {
+      "scenario": "active_execution",
+      "profile": "normal instruction",
+      "wall_ms": 5615.248199959751,
+      "tasks": 1024,
+      "peak_kb": 0.6484375,
+      "provider_calls": 1024,
+      "cache_hits": 0,
+      "blocked_calls": 0,
+      "total_agents": 1024,
+      "virtual_agents": 0,
+      "tokens": 0,
+      "notes": "sequential execution",
+      "throughput_tasks_s": 182.36059449826988
+    },
+    {
+      "scenario": "active_execution",
+      "profile": "V1 high-throughput",
+      "wall_ms": 237.90680000092834,
+      "tasks": 1024,
+      "peak_kb": 3408.0009765625,
+      "provider_calls": 1024,
+      "cache_hits": 0,
+      "blocked_calls": 0,
+      "total_agents": 0,
+      "virtual_agents": 0,
+      "tokens": 0,
+      "notes": "lane_concurrency=32, max_lane_concurrency=32",
+      "throughput_tasks_s": 4304.20652119235
+    },
+    {
+      "scenario": "active_execution",
+      "profile": "V2 safe-speed",
+      "wall_ms": 215.9010999603197,
+      "tasks": 1024,
+      "peak_kb": 3105.7685546875,
+      "provider_calls": 1024,
+      "cache_hits": 0,
+      "blocked_calls": 0,
+      "total_agents": 0,
+      "virtual_agents": 0,
+      "tokens": 0,
+      "notes": "lane_concurrency=32, max_lane_concurrency=64",
+      "throughput_tasks_s": 4742.912380660405
+    },
+    {
+      "scenario": "cache_dedupe",
+      "profile": "normal instruction",
+      "wall_ms": 417.67520003486425,
+      "tasks": 256,
+      "peak_kb": 5.3759765625,
+      "provider_calls": 256,
+      "cache_hits": 0,
+      "blocked_calls": 0,
+      "total_agents": 0,
+      "virtual_agents": 0,
+      "tokens": 0,
+      "notes": "64 unique inputs repeated across 256 tasks",
+      "throughput_tasks_s": 612.9164479447933
+    },
+    {
+      "scenario": "cache_dedupe",
+      "profile": "V1 high-throughput",
+      "wall_ms": 429.37830003211275,
+      "tasks": 256,
+      "peak_kb": 5.2470703125,
+      "provider_calls": 256,
+      "cache_hits": 0,
+      "blocked_calls": 0,
+      "total_agents": 0,
+      "virtual_agents": 0,
+      "tokens": 0,
+      "notes": "64 unique inputs repeated across 256 tasks",
+      "throughput_tasks_s": 596.2108471267738
+    },
+    {
+      "scenario": "cache_dedupe",
+      "profile": "V2 safe-speed",
+      "wall_ms": 125.83869998343289,
+      "tasks": 256,
+      "peak_kb": 43.0400390625,
+      "provider_calls": 64,
+      "cache_hits": 192,
+      "blocked_calls": 0,
+      "total_agents": 0,
+      "virtual_agents": 0,
+      "tokens": 0,
+      "notes": "64 unique inputs repeated across 256 tasks",
+      "throughput_tasks_s": 2034.3503233401434
+    },
+    {
+      "scenario": "small_task_batching",
+      "profile": "normal instruction",
+      "wall_ms": 729.9779999884777,
+      "tasks": 512,
+      "peak_kb": 0.515625,
+      "provider_calls": 512,
+      "cache_hits": 0,
+      "blocked_calls": 0,
+      "total_agents": 0,
+      "virtual_agents": 0,
+      "tokens": 0,
+      "notes": "one provider-sized call per small task",
+      "throughput_tasks_s": 701.3910008357535
+    },
+    {
+      "scenario": "small_task_batching",
+      "profile": "V1 high-throughput",
+      "wall_ms": 730.3357000346296,
+      "tasks": 512,
+      "peak_kb": 0.5078125,
+      "provider_calls": 512,
+      "cache_hits": 0,
+      "blocked_calls": 0,
+      "total_agents": 0,
+      "virtual_agents": 0,
+      "tokens": 0,
+      "notes": "one provider-sized call per small task",
+      "throughput_tasks_s": 701.047477174843
+    },
+    {
+      "scenario": "small_task_batching",
+      "profile": "V2 safe-speed",
+      "wall_ms": 20.444200024940073,
+      "tasks": 512,
+      "peak_kb": 540.5927734375,
+      "provider_calls": 16,
+      "cache_hits": 0,
+      "blocked_calls": 0,
+      "total_agents": 0,
+      "virtual_agents": 0,
+      "tokens": 0,
+      "notes": "batch_size=32",
+      "throughput_tasks_s": 25043.77766679089
+    },
+    {
+      "scenario": "provider_failure_control",
+      "profile": "normal instruction",
+      "wall_ms": 0.020899984519928694,
+      "tasks": 64,
+      "peak_kb": 0.6015625,
+      "provider_calls": 192,
+      "cache_hits": 0,
+      "blocked_calls": 0,
+      "total_agents": 0,
+      "virtual_agents": 0,
+      "tokens": 0,
+      "notes": "no provider circuit breaker",
+      "throughput_tasks_s": 3062203.22502987
+    },
+    {
+      "scenario": "provider_failure_control",
+      "profile": "V1 high-throughput",
+      "wall_ms": 0.008500006515532732,
+      "tasks": 64,
+      "peak_kb": 0.5625,
+      "provider_calls": 192,
+      "cache_hits": 0,
+      "blocked_calls": 0,
+      "total_agents": 0,
+      "virtual_agents": 0,
+      "tokens": 0,
+      "notes": "no provider circuit breaker",
+      "throughput_tasks_s": 7529405.993165741
+    },
+    {
+      "scenario": "provider_failure_control",
+      "profile": "V2 safe-speed",
+      "wall_ms": 0.5077999667264521,
+      "tasks": 64,
+      "peak_kb": 5.4736328125,
+      "provider_calls": 3,
+      "cache_hits": 0,
+      "blocked_calls": 63,
+      "total_agents": 0,
+      "virtual_agents": 0,
+      "tokens": 0,
+      "notes": "breaker opens after 3 provider failures",
+      "throughput_tasks_s": 126033.87986135158
+    },
+    {
+      "scenario": "context_compression",
+      "profile": "normal instruction",
+      "wall_ms": 0.0990999978967011,
+      "tasks": 1,
+      "peak_kb": 53.1337890625,
+      "provider_calls": 0,
+      "cache_hits": 0,
+      "blocked_calls": 0,
+      "total_agents": 0,
+      "virtual_agents": 0,
+      "tokens": 5016,
+      "notes": "20000 char context",
+      "throughput_tasks_s": 10090.817570373416
+    },
+    {
+      "scenario": "context_compression",
+      "profile": "V1 high-throughput",
+      "wall_ms": 0.07440004264935851,
+      "tasks": 1,
+      "peak_kb": 53.0869140625,
+      "provider_calls": 0,
+      "cache_hits": 0,
+      "blocked_calls": 0,
+      "total_agents": 0,
+      "virtual_agents": 0,
+      "tokens": 5016,
+      "notes": "20000 char context",
+      "throughput_tasks_s": 13440.85251016482
+    },
+    {
+      "scenario": "context_compression",
+      "profile": "V2 safe-speed",
+      "wall_ms": 0.15959999291226268,
+      "tasks": 1,
+      "peak_kb": 27.6318359375,
+      "provider_calls": 0,
+      "cache_hits": 0,
+      "blocked_calls": 0,
+      "total_agents": 0,
+      "virtual_agents": 0,
+      "tokens": 1188,
+      "notes": "20000 char context",
+      "throughput_tasks_s": 6265.664438655286
+    }
+  ],
+  "comparisons": [
+    {
+      "scenario": "scale_representation",
+      "baseline": "normal instruction",
+      "improved": "V2 safe-speed",
+      "metric": "wall_ms",
+      "baseline_value": 174.48919999878854,
+      "improved_value": 0.05169998621568084,
+      "ratio": 3375.0337818439334,
+      "percent": 99.97037066694327
+    },
+    {
+      "scenario": "active_execution",
+      "baseline": "normal instruction",
+      "improved": "V1 high-throughput",
+      "metric": "wall_ms",
+      "baseline_value": 5615.248199959751,
+      "improved_value": 237.90680000092834,
+      "ratio": 23.60272257849645,
+      "percent": 95.76320063639157
+    },
+    {
+      "scenario": "active_execution",
+      "baseline": "normal instruction",
+      "improved": "V2 safe-speed",
+      "metric": "wall_ms",
+      "baseline_value": 5615.248199959751,
+      "improved_value": 215.9010999603197,
+      "ratio": 26.008427937568513,
+      "percent": 96.15509248617244
+    },
+    {
+      "scenario": "active_execution",
+      "baseline": "V1 high-throughput",
+      "improved": "V2 safe-speed",
+      "metric": "wall_ms",
+      "baseline_value": 237.90680000092834,
+      "improved_value": 215.9010999603197,
+      "ratio": 1.1019249093434589,
+      "percent": 9.249714611151415
+    },
+    {
+      "scenario": "cache_dedupe",
+      "baseline": "normal instruction",
+      "improved": "V2 safe-speed",
+      "metric": "wall_ms",
+      "baseline_value": 417.67520003486425,
+      "improved_value": 125.83869998343289,
+      "ratio": 3.3191315556331453,
+      "percent": 69.87163710631398
+    },
+    {
+      "scenario": "cache_dedupe",
+      "baseline": "normal instruction",
+      "improved": "V2 safe-speed",
+      "metric": "provider_calls",
+      "baseline_value": 256,
+      "improved_value": 64,
+      "ratio": 4.0,
+      "percent": 75.0
+    },
+    {
+      "scenario": "cache_dedupe",
+      "baseline": "V1 high-throughput",
+      "improved": "V2 safe-speed",
+      "metric": "wall_ms",
+      "baseline_value": 429.37830003211275,
+      "improved_value": 125.83869998343289,
+      "ratio": 3.4121323574436317,
+      "percent": 70.69281331310373
+    },
+    {
+      "scenario": "cache_dedupe",
+      "baseline": "V1 high-throughput",
+      "improved": "V2 safe-speed",
+      "metric": "provider_calls",
+      "baseline_value": 256,
+      "improved_value": 64,
+      "ratio": 4.0,
+      "percent": 75.0
+    },
+    {
+      "scenario": "small_task_batching",
+      "baseline": "normal instruction",
+      "improved": "V2 safe-speed",
+      "metric": "wall_ms",
+      "baseline_value": 729.9779999884777,
+      "improved_value": 20.444200024940073,
+      "ratio": 35.705872526093984,
+      "percent": 97.19934025062909
+    },
+    {
+      "scenario": "small_task_batching",
+      "baseline": "normal instruction",
+      "improved": "V2 safe-speed",
+      "metric": "provider_calls",
+      "baseline_value": 512,
+      "improved_value": 16,
+      "ratio": 32.0,
+      "percent": 96.875
+    },
+    {
+      "scenario": "small_task_batching",
+      "baseline": "V1 high-throughput",
+      "improved": "V2 safe-speed",
+      "metric": "wall_ms",
+      "baseline_value": 730.3357000346296,
+      "improved_value": 20.444200024940073,
+      "ratio": 35.72336893317841,
+      "percent": 97.20071194329256
+    },
+    {
+      "scenario": "small_task_batching",
+      "baseline": "V1 high-throughput",
+      "improved": "V2 safe-speed",
+      "metric": "provider_calls",
+      "baseline_value": 512,
+      "improved_value": 16,
+      "ratio": 32.0,
+      "percent": 96.875
+    },
+    {
+      "scenario": "provider_failure_control",
+      "baseline": "normal instruction",
+      "improved": "V2 safe-speed",
+      "metric": "provider_calls",
+      "baseline_value": 192,
+      "improved_value": 3,
+      "ratio": 64.0,
+      "percent": 98.4375
+    },
+    {
+      "scenario": "provider_failure_control",
+      "baseline": "V1 high-throughput",
+      "improved": "V2 safe-speed",
+      "metric": "provider_calls",
+      "baseline_value": 192,
+      "improved_value": 3,
+      "ratio": 64.0,
+      "percent": 98.4375
+    },
+    {
+      "scenario": "context_compression",
+      "baseline": "normal instruction",
+      "improved": "V2 safe-speed",
+      "metric": "tokens",
+      "baseline_value": 5016,
+      "improved_value": 1188,
+      "ratio": 4.222222222222222,
+      "percent": 76.31578947368422
+    },
+    {
+      "scenario": "context_compression",
+      "baseline": "V1 high-throughput",
+      "improved": "V2 safe-speed",
+      "metric": "tokens",
+      "baseline_value": 5016,
+      "improved_value": 1188,
+      "ratio": 4.222222222222222,
+      "percent": 76.31578947368422
+    }
+  ],
+  "median_wall_ms": 73.14145000418648
+}

package/benchmarks/v2_safe_speed_results.md

@@ -0,0 +1,96 @@
+# Yool Safe-Speed Benchmark V2
+
+Run date: 2026-05-21
+
+This report compares three execution styles:
+
+- Normal instruction: generic prompt, flat or repeated work, no runtime guardrails.
+- V1 high-throughput: lazy `batch_spawn` and fixed `LaneWorkerPool` fan-out.
+- V2 safe-speed: V1 plus cache, adaptive lanes, backoff, provider circuit breaker, batching, context compression, local routing, and idempotent speculation.
+
+The benchmark is local. It does not call hosted LLMs or external APIs.
+
+## Scale Representation
+
+| Profile | Tasks | Wall ms | Throughput/s | Peak KiB | Provider calls | Cache hits | Blocked | Tokens | Notes |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---|
+| normal instruction | 131,072 | 174.49 | 751175.4 | 28751.2 | 0 | 0 | 0 | 0 | flat list materialization |
+| V1 high-throughput | 1,048,576 | 0.08 | 13851731550.8 | 7.7 | 0 | 0 | 0 | 0 | lazy batch_spawn depth=4, branching=32 |
+| V2 safe-speed | 1,048,576 | 0.05 | 20281939643.6 | 7.3 | 0 | 0 | 0 | 0 | lazy batch_spawn depth=4, branching=32 |
+
+## Active Execution
+
+| Profile | Tasks | Wall ms | Throughput/s | Peak KiB | Provider calls | Cache hits | Blocked | Tokens | Notes |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---|
+| normal instruction | 1,024 | 5615.25 | 182.4 | 0.6 | 1,024 | 0 | 0 | 0 | sequential execution |
+| V1 high-throughput | 1,024 | 237.91 | 4304.2 | 3408.0 | 1,024 | 0 | 0 | 0 | lane_concurrency=32, max_lane_concurrency=32 |
+| V2 safe-speed | 1,024 | 215.90 | 4742.9 | 3105.8 | 1,024 | 0 | 0 | 0 | lane_concurrency=32, max_lane_concurrency=64 |
+
+## Cache Dedupe
+
+| Profile | Tasks | Wall ms | Throughput/s | Peak KiB | Provider calls | Cache hits | Blocked | Tokens | Notes |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---|
+| normal instruction | 256 | 417.68 | 612.9 | 5.4 | 256 | 0 | 0 | 0 | 64 unique inputs repeated across 256 tasks |
+| V1 high-throughput | 256 | 429.38 | 596.2 | 5.2 | 256 | 0 | 0 | 0 | 64 unique inputs repeated across 256 tasks |
+| V2 safe-speed | 256 | 125.84 | 2034.4 | 43.0 | 64 | 192 | 0 | 0 | 64 unique inputs repeated across 256 tasks |
+
+## Small Task Batching
+
+| Profile | Tasks | Wall ms | Throughput/s | Peak KiB | Provider calls | Cache hits | Blocked | Tokens | Notes |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---|
+| normal instruction | 512 | 729.98 | 701.4 | 0.5 | 512 | 0 | 0 | 0 | one provider-sized call per small task |
+| V1 high-throughput | 512 | 730.34 | 701.0 | 0.5 | 512 | 0 | 0 | 0 | one provider-sized call per small task |
+| V2 safe-speed | 512 | 20.44 | 25043.8 | 540.6 | 16 | 0 | 0 | 0 | batch_size=32 |
+
+## Provider Failure Control
+
+| Profile | Tasks | Wall ms | Throughput/s | Peak KiB | Provider calls | Cache hits | Blocked | Tokens | Notes |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---|
+| normal instruction | 64 | 0.02 | 3062203.2 | 0.6 | 192 | 0 | 0 | 0 | no provider circuit breaker |
+| V1 high-throughput | 64 | 0.01 | 7529406.0 | 0.6 | 192 | 0 | 0 | 0 | no provider circuit breaker |
+| V2 safe-speed | 64 | 0.51 | 126033.9 | 5.5 | 3 | 0 | 63 | 0 | breaker opens after 3 provider failures |
+
+## Context Compression
+
+| Profile | Tasks | Wall ms | Throughput/s | Peak KiB | Provider calls | Cache hits | Blocked | Tokens | Notes |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---|
+| normal instruction | 1 | 0.10 | 10090.8 | 53.1 | 0 | 0 | 0 | 5,016 | 20000 char context |
+| V1 high-throughput | 1 | 0.07 | 13440.9 | 53.1 | 0 | 0 | 0 | 5,016 | 20000 char context |
+| V2 safe-speed | 1 | 0.16 | 6265.7 | 27.6 | 0 | 0 | 0 | 1,188 | 20000 char context |
+
+## Gains
+
+| Scenario | Baseline | Improved | Metric | Ratio | Gain |
+|---|---|---|---|---:|---:|
+| scale_representation | normal instruction | V2 safe-speed | wall_ms | 3375.03x | 99.97% |
+| active_execution | normal instruction | V1 high-throughput | wall_ms | 23.60x | 95.76% |
+| active_execution | normal instruction | V2 safe-speed | wall_ms | 26.01x | 96.16% |
+| active_execution | V1 high-throughput | V2 safe-speed | wall_ms | 1.10x | 9.25% |
+| cache_dedupe | normal instruction | V2 safe-speed | wall_ms | 3.32x | 69.87% |
+| cache_dedupe | normal instruction | V2 safe-speed | provider_calls | 4.00x | 75.00% |
+| cache_dedupe | V1 high-throughput | V2 safe-speed | wall_ms | 3.41x | 70.69% |
+| cache_dedupe | V1 high-throughput | V2 safe-speed | provider_calls | 4.00x | 75.00% |
+| small_task_batching | normal instruction | V2 safe-speed | wall_ms | 35.71x | 97.20% |
+| small_task_batching | normal instruction | V2 safe-speed | provider_calls | 32.00x | 96.88% |
+| small_task_batching | V1 high-throughput | V2 safe-speed | wall_ms | 35.72x | 97.20% |
+| small_task_batching | V1 high-throughput | V2 safe-speed | provider_calls | 32.00x | 96.88% |
+| provider_failure_control | normal instruction | V2 safe-speed | provider_calls | 64.00x | 98.44% |
+| provider_failure_control | V1 high-throughput | V2 safe-speed | provider_calls | 64.00x | 98.44% |
+| context_compression | normal instruction | V2 safe-speed | tokens | 4.22x | 76.32% |
+| context_compression | V1 high-throughput | V2 safe-speed | tokens | 4.22x | 76.32% |
+
+## Interpretation
+
+- V2 keeps the V1 lazy million-agent scale model.
+- V2 improves active fan-out by allowing lanes to grow toward the configured ceiling when backlog is high.
+- Cache reduces repeated provider calls when the same `yool + data` appears again.
+- Batching turns many tiny provider/API-sized operations into fewer bounded calls.
+- Circuit breaker reduces hammering during provider outages, which is the anti-ban part of the speed model.
+- Context compression lowers token transfer before LLM calls while preserving a digest and preview.
+
+## Reproduce
+
+```bash
+python benchmarks/v2_safe_speed_benchmark.py --json-output benchmarks/v2_safe_speed_results.json --md-output benchmarks/v2_safe_speed_results.md
+python benchmarks/generate_v2_benchmark_pdf.py
+```

package/examples/node/build-catalog.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Node wrapper around scripts/build_hamt.py.
+ * Lets JS/TS adopters consume the same catalog format.
+ *
+ * Usage:
+ *   node examples/node/build-catalog.mjs --source AGENTS.md --output .catalog/hamt.json
+ */
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, "..", "..");
+const PY_SCRIPT = resolve(REPO_ROOT, "scripts", "build_hamt.py");
+
+function parseArgs(argv) {
+  const args = { format: "auto" };
+  for (let i = 0; i < argv.length; i++) {
+    const k = argv[i];
+    if (k === "--source") args.source = argv[++i];
+    else if (k === "--output") args.output = argv[++i];
+    else if (k === "--format") args.format = argv[++i];
+    else if (k === "--help" || k === "-h") {
+      console.log("Usage: build-catalog.mjs --source <path> --output <path> [--format auto|agents-md|yool-list]");
+      process.exit(0);
+    }
+  }
+  if (!args.source || !args.output) {
+    console.error("error: --source and --output are required");
+    process.exit(2);
+  }
+  return args;
+}
+
+function runPython(args) {
+  return new Promise((resolveP, rejectP) => {
+    if (!existsSync(PY_SCRIPT)) {
+      rejectP(new Error(`build_hamt.py not found at ${PY_SCRIPT}`));
+      return;
+    }
+    const py = process.env.PYTHON || "python3";
+    const child = spawn(py, [
+      PY_SCRIPT,
+      "--source", args.source,
+      "--output", args.output,
+      "--format", args.format,
+    ], { stdio: ["ignore", "inherit", "inherit"] });
+    child.on("error", rejectP);
+    child.on("exit", (code) => {
+      if (code === 0) resolveP();
+      else rejectP(new Error(`build_hamt.py exited with code ${code}`));
+    });
+  });
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  await runPython(args);
+  if (existsSync(args.output)) {
+    const catalog = JSON.parse(readFileSync(args.output, "utf-8"));
+    console.error(`# loaded catalog: ${catalog.meta?.count} entries`);
+  }
+}
+
+main().catch((e) => {
+  console.error(e.message);
+  process.exit(1);
+});