@aotter/mantle 0.0.11-alpha.62 → 0.0.11-alpha.63

package/README.md

@@ -20,6 +20,7 @@ Adopters install this one package and import from subpaths. Sub-packages remain
 |---|---|
 | `@aotter/mantle/spec` (or root) | Manifest grammar, validators, JSON-Schema→Zod, diagnostic catalog (no env / no IO) |
 | `@aotter/mantle/runtime` | Hexagonal runtime: domain ports, use cases, infrastructure helpers (no adapter deps) |
+| `@aotter/mantle/runtime/testing` | Node-only crowded SQLite planner and HTTP sampling helpers |
 | `@aotter/mantle/cloudflare` | Cloudflare Workers adapter — D1, KV, R2, Better Auth, MCP via `@cloudflare/workers-oauth-provider` |
 | `@aotter/mantle/admin-ui` | Pre-built React 19 admin SPA bundle |
 
@@ -29,6 +30,13 @@ import { createCmsRuntime } from "@aotter/mantle/runtime";
 import { mountServerEndpoints } from "@aotter/mantle/cloudflare";
 ```
 
+The package also installs `mantle-harness`:
+
+```bash
+pnpm exec mantle-harness indexes --require-public
+pnpm exec mantle-harness http --base-url http://127.0.0.1:8787 --route page=/en/example
+```
+
 ## Getting started
 
 Give the [Mantle repo](https://github.com/aotter/mantle) to a coding agent or
@@ -97,6 +105,8 @@ The `mantle-runtime` package never imports Cloudflare-specific types — adapter
     Queue wiring, retry/DLQ, idempotency, and delivery guarantees)
   - `node_modules/@aotter/mantle/docs/schema-indexes.md` (ordered composite
     JSON-field indexes, D1 query plans, and the safe Procedure SQL helper)
+  - `node_modules/@aotter/mantle/docs/performance-harness.md` (crowded SQLite,
+    Wrangler-local D1, cache HIT/MISS, and coding-agent guardrails)
   - `node_modules/@aotter/mantle/docs/adr/`
   - `node_modules/@aotter/mantle/skills/develop/SKILL.md`
   - `node_modules/@aotter/mantle/skills/plugin/SKILL.md`

package/dist/harness-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=harness-cli.d.ts.map

package/dist/harness-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness-cli.d.ts","sourceRoot":"","sources":["../src/harness-cli.ts"],"names":[],"mappings":""}

package/dist/harness-cli.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+import { argv, stderr, stdout } from "node:process";
+import { parseArgs } from "node:util";
+import { ValidateManifestsUseCase, } from "@aotter/mantle-spec";
+import { loadManifestsFromRoot } from "@aotter/mantle-spec/cli";
+import { benchmarkHttpRoutes, inspectIndexCoverage, } from "@aotter/mantle-runtime/testing";
+async function main() {
+    const command = argv[2];
+    if (!command || command === "--help" || command === "-h") {
+        printHelp();
+        return command ? 0 : 2;
+    }
+    if (command === "indexes")
+        return runIndexes(argv.slice(3));
+    if (command === "http")
+        return runHttp(argv.slice(3));
+    stderr.write(`Unknown subcommand: ${command}\n`);
+    return 2;
+}
+async function runIndexes(rawArgs) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: [...rawArgs],
+            options: {
+                manifests: { type: "string" },
+                rows: { type: "string" },
+                require: { type: "string", multiple: true },
+                "require-public": { type: "boolean" },
+                format: { type: "string" },
+                help: { type: "boolean", short: "h" },
+            },
+        }));
+    }
+    catch (error) {
+        stderr.write(`${message(error)}\n`);
+        return 2;
+    }
+    if (values.help) {
+        printIndexesHelp();
+        return 0;
+    }
+    const format = outputFormat(values.format);
+    const loaded = await loadManifestsFromRoot(values.manifests ?? "./manifests");
+    const validation = ValidateManifestsUseCase.run({
+        manifests: loaded.manifests,
+        filePaths: loaded.filePaths,
+    });
+    const errors = [...loaded.parseErrors, ...validation.diagnostics]
+        .filter((diagnostic) => diagnostic.severity === "error");
+    if (errors.length > 0) {
+        emitErrors(errors, format);
+        return 1;
+    }
+    if (loaded.manifests.length === 0) {
+        stderr.write(`No manifests found under ${values.manifests ?? "./manifests"}\n`);
+        return 2;
+    }
+    const rows = values.rows === undefined ? undefined : Number(values.rows);
+    if (rows !== undefined && (!Number.isFinite(rows) || rows <= 0)) {
+        stderr.write("--rows must be a positive number\n");
+        return 2;
+    }
+    const report = await inspectIndexCoverage(loaded.manifests, {
+        rowsPerSchema: rows,
+        requirePublic: values["require-public"] === true,
+        requiredViews: values.require ?? [],
+    });
+    emitIndexReport(report, format);
+    return report.summary.requiredFailures > 0 ? 1 : 0;
+}
+async function runHttp(rawArgs) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: [...rawArgs],
+            options: {
+                route: { type: "string", multiple: true },
+                "base-url": { type: "string" },
+                rounds: { type: "string" },
+                warmup: { type: "string" },
+                format: { type: "string" },
+                help: { type: "boolean", short: "h" },
+            },
+        }));
+    }
+    catch (error) {
+        stderr.write(`${message(error)}\n`);
+        return 2;
+    }
+    if (values.help) {
+        printHttpHelp();
+        return 0;
+    }
+    if (!values.route || values.route.length === 0) {
+        stderr.write("http requires at least one --route name=/path-or-url\n");
+        return 2;
+    }
+    const format = outputFormat(values.format);
+    const baseUrl = (values["base-url"] ?? "").replace(/\/$/, "");
+    const targets = values.route.map((raw) => {
+        const separator = raw.indexOf("=");
+        if (separator < 1)
+            throw new Error(`invalid --route ${JSON.stringify(raw)}`);
+        const name = raw.slice(0, separator);
+        const path = raw.slice(separator + 1);
+        return { name, url: path.startsWith("/") ? `${baseUrl}${path}` : path };
+    });
+    if (targets.some(({ url }) => !/^https?:\/\//.test(url))) {
+        stderr.write("route URLs must be absolute, or use --base-url with /paths\n");
+        return 2;
+    }
+    let report;
+    try {
+        report = await benchmarkHttpRoutes({
+            targets,
+            rounds: numericOption(values.rounds, "--rounds"),
+            warmup: numericOption(values.warmup, "--warmup"),
+        });
+    }
+    catch (error) {
+        stderr.write(`${message(error)}\n`);
+        return 1;
+    }
+    emitHttpReport(report, format);
+    return 0;
+}
+function emitIndexReport(report, format) {
+    if (format === "json") {
+        stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        return;
+    }
+    for (const path of report.paths) {
+        const status = path.required ? path.passed ? "PASS" : "FAIL" : "ADVISORY";
+        const detail = path.findings.length > 0
+            ? path.findings.join("; ")
+            : path.usedIndexes.join(", ") || "planner found no named index";
+        stdout.write(`${status} ${path.view}: ${detail}\n`);
+    }
+    for (const view of report.summary.missingRequiredViews) {
+        stdout.write(`FAIL ${view}: required View not found\n`);
+    }
+    stdout.write(`views=${report.summary.views} required=${report.summary.required} ` +
+        `failures=${report.summary.requiredFailures} rows/schema=${report.rowsPerSchema}\n`);
+}
+function emitHttpReport(report, format) {
+    if (format === "json") {
+        stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        return;
+    }
+    for (const result of report.results) {
+        const queries = result.queryCount ? ` queries.p95=${result.queryCount.p95}` : "";
+        const rows = result.rowsRead ? ` rows_read.p95=${result.rowsRead.p95}` : "";
+        stdout.write(`${result.name}: p50=${result.timingMs.p50.toFixed(2)}ms ` +
+            `p95=${result.timingMs.p95.toFixed(2)}ms${queries}${rows}\n`);
+    }
+}
+function emitErrors(errors, format) {
+    if (format === "json")
+        stdout.write(`${JSON.stringify({ errors }, null, 2)}\n`);
+    else
+        for (const error of errors)
+            stderr.write(`${error.code} ${error.path}: ${error.message}\n`);
+}
+function outputFormat(raw) {
+    if (raw === undefined)
+        return stdout.isTTY ? "text" : "json";
+    if (raw === "json" || raw === "text")
+        return raw;
+    throw new Error(`--format must be text or json; got ${JSON.stringify(raw)}`);
+}
+function numericOption(raw, name) {
+    if (raw === undefined)
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 0)
+        throw new Error(`${name} must be a non-negative number`);
+    return value;
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function printHelp() {
+    stdout.write(`mantle-harness — measured performance checks\n\n` +
+        `Usage: mantle-harness <indexes|http> [options]\n\n` +
+        `  indexes  Execute compiled Views in crowded SQLite and inspect plans\n` +
+        `  http     Sample a running Worker and report p50/p95 + metric headers\n`);
+}
+function printIndexesHelp() {
+    stdout.write(`Usage: mantle-harness indexes [options]\n\n` +
+        `  --manifests <dir>  Manifest root (default: ./manifests)\n` +
+        `  --rows <n>         Deterministic rows per Schema (default: 2000)\n` +
+        `  --require <view>   Fail when this View lacks its access path; repeatable\n` +
+        `  --require-public   Apply the gate to public Views\n` +
+        `  --format <fmt>     text or json\n`);
+}
+function printHttpHelp() {
+    stdout.write(`Usage: mantle-harness http [options]\n\n` +
+        `  --base-url <url>   Prefix for route paths\n` +
+        `  --route <name=url> Route label and path/URL; repeatable\n` +
+        `  --rounds <n>       Measured requests per route (default: 20)\n` +
+        `  --warmup <n>       Warmup requests per route (default: 2)\n` +
+        `  --format <fmt>     text or json\n`);
+}
+main().then((code) => { process.exitCode = code; }, (error) => {
+    stderr.write(`${message(error)}\n`);
+    process.exitCode = 2;
+});
+//# sourceMappingURL=harness-cli.js.map

package/dist/harness-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness-cli.js","sourceRoot":"","sources":["../src/harness-cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EACL,wBAAwB,GAEzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EACL,mBAAmB,EACnB,oBAAoB,GAGrB,MAAM,gCAAgC,CAAC;AAIxC,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACzD,SAAS,EAAE,CAAC;QACZ,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IACD,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5D,IAAI,OAAO,KAAK,MAAM;QAAE,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,MAAM,CAAC,KAAK,CAAC,uBAAuB,OAAO,IAAI,CAAC,CAAC;IACjD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,OAA0B;IAClD,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;YACtB,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC;YAClB,OAAO,EAAE;gBACP,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBAC7B,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACxB,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC3C,gBAAgB,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;gBACrC,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBAC1B,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE;aACtC;SACF,CAAC,CAAC,CAAC;IACN,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACpC,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAChB,gBAAgB,EAAE,CAAC;QACnB,OAAO,CAAC,CAAC;IACX,CAAC;IACD,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,MAAM,qBAAqB,CAAC,MAAM,CAAC,SAAS,IAAI,aAAa,CAAC,CAAC;IAC9E,MAAM,UAAU,GAAG,wBAAwB,CAAC,GAAG,CAAC;QAC9C,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,SAAS,EAAE,MAAM,CAAC,SAAS;KAC5B,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,WAAW,EAAE,GAAG,UAAU,CAAC,WAAW,CAAC;SAC9D,MAAM,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;IAC3D,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC3B,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,MAAM,CAAC,KAAK,CAAC,4BAA4B,MAAM,CAAC,SAAS,IAAI,aAAa,IAAI,CAAC,CAAC;QAChF,OAAO,CAAC,CAAC;IACX,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACzE,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC;QAChE,MAAM,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACnD,OAAO,CAAC,CAAC;IACX,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,MAAM,CAAC,SAAS,EAAE;QAC1D,aAAa,EAAE,IAAI;QACnB,aAAa,EAAE,MAAM,CAAC,gBAAgB,CAAC,KAAK,IAAI;QAChD,aAAa,EAAE,MAAM,CAAC,OAAO,IAAI,EAAE;KACpC,CAAC,CAAC;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,OAAO,MAAM,CAAC,OAAO,CAAC,gBAAgB,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACrD,CAAC;AAED,KAAK,UAAU,OAAO,CAAC,OAA0B;IAC/C,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;YACtB,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC;YAClB,OAAO,EAAE;gBACP,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;gBACzC,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBAC9B,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBAC1B,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBAC1B,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBAC1B,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE;aACtC;SACF,CAAC,CAAC,CAAC;IACN,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACpC,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAChB,aAAa,EAAE,CAAC;QAChB,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/C,MAAM,CAAC,KAAK,CAAC,wDAAwD,CAAC,CAAC;QACvE,OAAO,CAAC,CAAC;IACX,CAAC;IACD,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACvC,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,SAAS,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC7E,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QACrC,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;QACtC,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1E,CAAC,CAAC,CAAC;IACH,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACzD,MAAM,CAAC,KAAK,CAAC,8DAA8D,CAAC,CAAC;QAC7E,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,MAA2B,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,mBAAmB,CAAC;YACjC,OAAO;YACP,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC;YAChD,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC;SACjD,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACpC,OAAO,CAAC,CAAC;IACX,CAAC;IACD,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,OAAO,CAAC,CAAC;AACX,CAAC;AAED,SAAS,eAAe,CAAC,MAA2B,EAAE,MAAc;IAClE,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACrD,OAAO;IACT,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC;QAC1E,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;YACrC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;YAC1B,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,8BAA8B,CAAC;QAClE,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC;IACtD,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,OAAO,CAAC,oBAAoB,EAAE,CAAC;QACvD,MAAM,CAAC,KAAK,CAAC,QAAQ,IAAI,6BAA6B,CAAC,CAAC;IAC1D,CAAC;IACD,MAAM,CAAC,KAAK,CACV,SAAS,MAAM,CAAC,OAAO,CAAC,KAAK,aAAa,MAAM,CAAC,OAAO,CAAC,QAAQ,GAAG;QAClE,YAAY,MAAM,CAAC,OAAO,CAAC,gBAAgB,gBAAgB,MAAM,CAAC,aAAa,IAAI,CACtF,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,MAA2B,EAAE,MAAc;IACjE,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACrD,OAAO;IACT,CAAC;IACD,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,gBAAgB,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjF,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,kBAAkB,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,MAAM,CAAC,KAAK,CACV,GAAG,MAAM,CAAC,IAAI,SAAS,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK;YACxD,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,GAAG,IAAI,IAAI,CAC/D,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,MAA6B,EAAE,MAAc;IAC/D,IAAI,MAAM,KAAK,MAAM;QAAE,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;;QAC3E,KAAK,MAAM,KAAK,IAAI,MAAM;YAAE,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;AACnG,CAAC;AAED,SAAS,YAAY,CAAC,GAAuB;IAC3C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IAC7D,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,MAAM;QAAE,OAAO,GAAG,CAAC;IACjD,MAAM,IAAI,KAAK,CAAC,sCAAsC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAC/E,CAAC;AAED,SAAS,aAAa,CAAC,GAAuB,EAAE,IAAY;IAC1D,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,gCAAgC,CAAC,CAAC;IACnG,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,OAAO,CAAC,KAAc;IAC7B,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC;AAED,SAAS,SAAS;IAChB,MAAM,CAAC,KAAK,CAAC,kDAAkD;QAC7D,oDAAoD;QACpD,yEAAyE;QACzE,0EAA0E,CAAC,CAAC;AAChF,CAAC;AAED,SAAS,gBAAgB;IACvB,MAAM,CAAC,KAAK,CAAC,6CAA6C;QACxD,6DAA6D;QAC7D,sEAAsE;QACtE,8EAA8E;QAC9E,uDAAuD;QACvD,qCAAqC,CAAC,CAAC;AAC3C,CAAC;AAED,SAAS,aAAa;IACpB,MAAM,CAAC,KAAK,CAAC,0CAA0C;QACrD,+CAA+C;QAC/C,6DAA6D;QAC7D,kEAAkE;QAClE,+DAA+D;QAC/D,qCAAqC,CAAC,CAAC;AAC3C,CAAC;AAED,IAAI,EAAE,CAAC,IAAI,CACT,CAAC,IAAI,EAAE,EAAE,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,EACtC,CAAC,KAAK,EAAE,EAAE;IACR,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CACF,CAAC"}

package/dist/runtime-testing.d.ts

@@ -0,0 +1,2 @@
+export * from "@aotter/mantle-runtime/testing";
+//# sourceMappingURL=runtime-testing.d.ts.map

package/dist/runtime-testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-testing.d.ts","sourceRoot":"","sources":["../src/runtime-testing.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAC"}

package/dist/runtime-testing.js

@@ -0,0 +1,2 @@
+export * from "@aotter/mantle-runtime/testing";
+//# sourceMappingURL=runtime-testing.js.map

package/dist/runtime-testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-testing.js","sourceRoot":"","sources":["../src/runtime-testing.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAC"}

package/docs/adapter-guide.md

@@ -61,6 +61,14 @@ await runtime.bootInit();
 
 `bootInit()` runs canonical migrations, seeds `siteDefaults`, and validates the manifest set. Call it once before serving CMS traffic. The Cloudflare adapter's reference pattern is `packages/adapters/cloudflare/src/mount/bootRuntimeOnce.ts`.
 
+Use purpose-shaped runtime surfaces for canonical data: `runtime.entryReader`
+applies Schema index declarations, locale semantics, and the public `Entry`
+projection; `runtime.siteConfig` owns site settings. `runtime.db` remains only
+for source compatibility and is deprecated. An adapter that owns additional
+tables should retain the `DatabaseDriver` it injected instead of reaching back
+through the assembled runtime. Authoring continues through the pre-wired
+content use cases.
+
 ## HTTP and MCP surfaces
 
 The runtime is a library, not an HTTP server. A new adapter must mount equivalent framework routes:

package/docs/performance-harness.md

@@ -0,0 +1,104 @@
+# Data access, cache policy, and performance harness
+
+Mantle site code declares intent; Core owns the shared storage layout and the
+Cloudflare adapter owns provider bindings. A site-building agent should not
+need Mantle table names, generated-column names, KV prefixes, or D1 APIs to
+make a normal content/API/page change.
+
+## Ownership
+
+| Read or state | Owner | Notes |
+|---|---|---|
+| Entry get/list and public slug/data-field/published reads | `DatabaseEntryRepository` through `EntryRepository` / `EntryReader` | Schema-aware field resolution is shared here. |
+| Manifest View execution | `ExecuteViewUseCase` + `ViewSqlCompiler` | The deliberate compiled-query exception; it still resolves declared Schema indexes. |
+| Editable settings and code-owned locale/media policy | `DatabaseSiteConfigRepository` | Editable values and dynamic media tool policy are read fresh; boot-seeded locale policy may be memoized within the runtime instance. |
+| Pending media uploads | `DatabasePendingUploadRepository` | Canonical, read-after-write D1 state; never publish-cache state. |
+| Rendered HTML, Markdown, and `llms.txt` | `HtmlPublishOrchestrator` plus the Cloudflare public-route cache policy | Reproducible derivatives live in KV. Settings updates invalidate through a runtime use case. |
+| D1/KV transport and optional query metrics | Cloudflare bindings | Bindings stay thin. Query/cache policy does not belong in a generic provider `BaseRepository`. |
+
+`CmsRuntime.db` remains deprecated compatibility surface. New site code uses
+Manifests, runtime use cases, `entryReader`, and `siteConfig`. A site may own
+additional tables behind its own repository at the composition root, but it
+must not query Mantle-owned tables through `runtime.db`.
+
+## Cache contract
+
+- D1 is canonical for entries, site settings, media metadata, and pending
+  uploads. KV contains only reproducible public artifacts.
+- A public KV hit checks the cache before loading full editable site settings.
+  Locale policy is the small boot-seeded exception. A warm entry/page artifact
+  therefore performs zero D1 queries.
+- A safe cache miss renders from canonical state and schedules KV write-back
+  with the request execution context. It waits inline only when no execution
+  context exists, such as a direct unit call.
+- Site-setting writes call the runtime settings use case, which completes
+  public-artifact invalidation before reporting success. HTTP routes do not
+  scan/delete KV prefixes themselves.
+- Do not cache every repository read. Cross-isolate correctness for editable
+  data wins unless a read has a measured hot-path contract and explicit
+  invalidation.
+
+## Index coverage
+
+The Node harness uses the real canonical migrations, generated Schema DDL,
+real View compiler, deterministic skewed rows, and SQLite
+`EXPLAIN QUERY PLAN`:
+
+```bash
+pnpm exec mantle-harness indexes --manifests ./manifests --format text
+pnpm exec mantle-harness indexes --require-public --format json
+pnpm exec mantle-harness indexes --require account-members --format json
+```
+
+Without `--require-public` or `--require`, findings are advisory. A required
+path fails on an `entries` table scan, a temporary ORDER BY B-tree, or a
+data-field predicate/order that does not use a declared Schema index.
+Projection alone does not require an index. `mantle validate` remains a pure
+correctness check; no performance grammar or manifest atom was added.
+
+Use the machine report in CI. It includes the compiled SQL and parameters,
+query-plan details, named indexes, scan/sort flags, result count, SQLite
+version, fixture row count, and required-failure summary.
+
+## Worker/API/page sampling
+
+Sample any running environment with the public HTTP helper:
+
+```bash
+pnpm exec mantle-harness http \
+  --base-url http://127.0.0.1:8787 \
+  --route recent=/api/views/recent-posts \
+  --route page=/en/posts/hello \
+  --rounds 20 --warmup 2 --format json
+```
+
+Timing always reports p50/p95/max. A test-only Worker wrapper may also return
+`x-mantle-query-count` and `x-mantle-rows-read`; those become distributions in
+the same report. Do not expose these diagnostic headers in production.
+
+Core CI runs `pnpm bench:wrangler` against real Wrangler-local D1, KV, Worker
+HTTP routing, View execution, and live page rendering. It compares 100 and
+10,000 row fixtures, then samples page MISS and HIT separately. CI gates
+row-read scaling, endpoint query budgets, and zero-D1 warm hits, not absolute
+milliseconds.
+
+## Seven findings: measured disposition
+
+Measured on the deterministic 2026-08-01 Wrangler-local fixture; timings are
+diagnostic, while query/row counts are the stable assertions.
+
+| Finding | Disposition |
+|---|---|
+| Public KV hits read D1 first | Fixed. A 10,000-row warm page measured 0 queries / 0 rows read. |
+| Slug/locale reads bypass generated indexes | Fixed by the shared schema-aware entry-read boundary. A 10,000-row page MISS measured 2 queries / 5 rows read. |
+| OFFSET pagination | Accepted for the v0.1 bounded-result surfaces: every response is capped at 500 rows and public hot paths must stay shallow. Deep/export workloads require a purpose-shaped cursor API before they are declared hot. |
+| Admin substring search scans | Accepted only for the authenticated Admin collection browser, with a 500-row response cap. Large/search-heavy sites should add a purpose-shaped indexed View or dedicated search service; do not expose this scan publicly. |
+| Published list/sitemap/llms paths lack system indexes | Fixed with measured partial indexes for published global, locale, collection, and collection+locale ordering. The 100-row and 10,000-row API runs both measured 1 query / 20 rows read. |
+| Page MISS waits for KV write-back | Fixed. Reproducible artifacts write through `waitUntil`; regression coverage proves response completion does not await KV. |
+| Benchmark stops at fake in-process dispatch | Fixed by the Node planner and Wrangler-local Worker/API/page layers. The old dispatch microbenchmark remains a narrow CPU signal only. |
+
+The retained OFFSET and substring-search trade-offs are visible exceptions,
+not patterns for new public APIs. Re-measure before widening either scope.
+
+See also [Schema indexes](./schema-indexes.md) and the official Cloudflare
+[D1 index guidance](https://developers.cloudflare.com/d1/best-practices/use-indexes/).

package/docs/schema-indexes.md

@@ -141,7 +141,20 @@ site still owns actor resolution, account rules, aggregation, and output.
 
 ## Verify a plan
 
-Inspect the real database when adding or changing a hot path:
+Prefer the shipped crowded-data harness for a manifest View:
+
+```bash
+pnpm exec mantle-harness indexes --require-public --format text
+```
+
+It applies Mantle's real canonical migrations and generated DDL, seeds skewed
+rows, compiles and executes the real View SQL, then records
+`EXPLAIN QUERY PLAN`. By default findings are advisory; use `--require-public`
+or repeat `--require <view-name>` only for paths whose performance is part of
+the contract. See [the performance harness](./performance-harness.md).
+
+For site-owned SQL that cannot be represented by a View, inspect the real
+database directly when adding or changing a hot path:
 
 ```sql
 PRAGMA index_list("entries");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.0.11-alpha.62",
+  "version": "0.0.11-alpha.63",
   "description": "Umbrella entry for @aotter/mantle. Adopters install this one package and import from subpaths: /spec, /runtime, /cloudflare, /admin-ui. Sub-packages remain individually installable on npm for tooling / alt-adapter authors. The Netlify adapter ships as a private workspace stub in v0.1 — its subpath will be added when the impl lands in v0.2.",
   "license": "Apache-2.0",
   "homepage": "https://mantle.tools/",
@@ -13,6 +13,9 @@
   "sideEffects": false,
   "main": "./dist/spec.js",
   "types": "./dist/spec.d.ts",
+  "bin": {
+    "mantle-harness": "./dist/harness-cli.js"
+  },
   "publishConfig": {
     "access": "public",
     "tag": "alpha",
@@ -31,6 +34,10 @@
       "types": "./dist/runtime.d.ts",
       "import": "./dist/runtime.js"
     },
+    "./runtime/testing": {
+      "types": "./dist/runtime-testing.d.ts",
+      "import": "./dist/runtime-testing.js"
+    },
     "./cloudflare": {
       "types": "./dist/cloudflare.d.ts",
       "import": "./dist/cloudflare.js"
@@ -47,10 +54,10 @@
     "README.md"
   ],
   "dependencies": {
-    "@aotter/mantle-cloudflare": "0.0.11-alpha.62",
-    "@aotter/mantle-admin-ui": "0.0.11-alpha.62",
-    "@aotter/mantle-spec": "0.0.11-alpha.62",
-    "@aotter/mantle-runtime": "0.0.11-alpha.62"
+    "@aotter/mantle-cloudflare": "0.0.11-alpha.63",
+    "@aotter/mantle-runtime": "0.0.11-alpha.63",
+    "@aotter/mantle-admin-ui": "0.0.11-alpha.63",
+    "@aotter/mantle-spec": "0.0.11-alpha.63"
   },
   "peerDependencies": {
     "@cloudflare/workers-oauth-provider": "^0.8.0",

package/skills/develop/SKILL.md

@@ -117,11 +117,49 @@ Do not assume Cloudflare unless the project imports `@aotter/mantle/cloudflare`
 or its adapter config is visible. A future Netlify adapter should satisfy the
 same Core workflow through its own ports and provider setup.
 
+Site code is a consumer of this abstraction. Use Manifests, runtime use cases,
+`entryReader`, and `siteConfig`; do not query Mantle-owned `entries` or
+`site_config`, reach through deprecated `runtime.db`, copy generated-column
+names, or construct SDK KV keys. Cloudflare bindings belong only at the
+composition root. If a normal feature cannot be expressed through a
+purpose-shaped surface, treat that as a Core abstraction gap instead of
+teaching the project Mantle internals.
+
+## Performance Loop
+
+After changing a Schema index, View filter/order, public API, or rendered page,
+run the project's index check when present. Otherwise run the installed
+harness directly:
+
+```bash
+pnpm exec mantle-harness indexes --require-public --format text
+```
+
+The check uses crowded real SQLite and the shipped compiler. It complements
+`pnpm validate`; it does not replace correctness validation. Declare the
+smallest ordered index justified by the measured path and respect SQLite's
+leftmost-prefix rule. Do not change user-visible filter or ordering semantics
+just to make the gate pass. Do not add every permutation or cache every read.
+
+For relevant Cloudflare serving changes, start the project and sample the
+actual routes:
+
+```bash
+pnpm exec mantle-harness http \
+  --base-url http://127.0.0.1:8787 \
+  --route page=/en/example \
+  --rounds 20 --warmup 2 --format text
+```
+
+Prefer query plan, query count, `rows_read` scaling, and cache MISS/HIT
+evidence. Do not create CI gates from absolute local milliseconds.
+
 ## Loop
 
 ```bash
 pnpm install --frozen-lockfile
 pnpm validate
+pnpm check:indexes # when the project provides it
 pnpm typecheck
 pnpm check
 ```