@pikku/core 0.12.107 → 0.12.112

package/dist/wirings/flag/validate-flag-definitions.js

@@ -0,0 +1,103 @@
+const SEPARATOR = ':';
+/**
+ * Names that already exist on every object literal. Declaring one makes the
+ * meta lookup below find `Object.prototype`'s member, treat the flag as
+ * already declared, and drop it — a flag that validated but never reached the
+ * snapshot, which is the one failure a typed flag key exists to prevent.
+ */
+const INHERITED_NAMES = new Set(['__proto__', 'constructor', 'prototype']);
+const assertFlagName = (name) => {
+    if (name.length === 0) {
+        throw new Error('A feature flag is declared with an empty name.');
+    }
+    if (INHERITED_NAMES.has(name)) {
+        throw new Error(`Feature flag '${name}' is named after a property every object already ` +
+            `carries, so it cannot be told apart from one. Pick another name.`);
+    }
+    if (name.includes(SEPARATOR)) {
+        throw new Error(`Feature flag '${name}' contains the '${SEPARATOR}' separator. ` +
+            `'${SEPARATOR}' delimits scope ids; a flag named like a scope reads as one.`);
+    }
+};
+/**
+ * The declared flags as a flat list, deduplicated by name.
+ *
+ * A flag may legitimately be declared more than once — an addon and its host
+ * app both contributing one — and
+ * {@link validateAndBuildFeatureFlagDefinitionsMeta} has already guaranteed
+ * those declarations are identical.
+ */
+export const flattenFeatureFlagDefinitions = (definitions) => {
+    const seen = new Set();
+    const out = [];
+    for (const def of definitions) {
+        if (seen.has(def.name)) {
+            continue;
+        }
+        seen.add(def.name);
+        out.push({
+            name: def.name,
+            description: def.description,
+            anyOf: def.anyOf ? [...def.anyOf] : undefined,
+        });
+    }
+    return out;
+};
+/**
+ * Validates declared flags and keys them by name.
+ *
+ * Definitions sharing a name must name the same scope set; a conflicting
+ * redeclaration is a hard error naming both source files. Order within `anyOf`
+ * is not significant.
+ */
+export function validateAndBuildFeatureFlagDefinitionsMeta(definitions) {
+    const meta = {};
+    for (const def of definitions) {
+        assertFlagName(def.name);
+        if (def.anyOf && def.anyOf.length === 0) {
+            throw new Error(`Feature flag '${def.name}' declares 'anyOf: []'. ` +
+                `An empty list satisfies nobody, which is never what is meant: ` +
+                `omit 'anyOf' for a pure switch, or name the scopes that reveal it.`);
+        }
+        const existing = meta[def.name];
+        if (existing) {
+            const sameScopes = JSON.stringify([...(existing.anyOf ?? [])].sort()) ===
+                JSON.stringify([...(def.anyOf ?? [])].sort());
+            if (!sameScopes) {
+                throw new Error(`Feature flag '${def.name}' is declared with different scopes.\n` +
+                    `  First declaration: ${existing.sourceFile ?? 'unknown'}\n` +
+                    `  Second declaration: ${def.sourceFile ?? 'unknown'}\n` +
+                    `Flags sharing a name must name the same scopes.`);
+            }
+            // The description is what an operator reads beside the switch, and the
+            // winner here is whichever file the inspector walked first. Two
+            // descriptions for one flag is a disagreement about what the switch
+            // does, and source order is not the thing that should settle it.
+            if (existing.description !== def.description) {
+                throw new Error(`Feature flag '${def.name}' is declared with different descriptions.\n` +
+                    `  First declaration: ${existing.sourceFile ?? 'unknown'}\n` +
+                    `  Second declaration: ${def.sourceFile ?? 'unknown'}\n` +
+                    `Flags sharing a name must describe the same thing.`);
+            }
+            continue;
+        }
+        meta[def.name] = {
+            name: def.name,
+            description: def.description,
+            anyOf: def.anyOf ? [...def.anyOf] : undefined,
+            sourceFile: def.sourceFile,
+        };
+    }
+    return meta;
+}
+/**
+ * The snapshot a flag source falls back to when its store cannot be read: every
+ * declared flag on, no rollout, no overrides.
+ *
+ * This is the compiled declaration, not a database read — putting a fallback
+ * query on the request path is how a slow store becomes a slow product.
+ */
+export const compiledFallbackSnapshot = (flags) => Object.fromEntries(flags.map((flag) => [
+    flag.name,
+    { enabled: true, rolloutPercent: null, overrides: {} },
+]));

package/dist/wirings/virtual-user/virtual-user-scaffold.d.ts

@@ -38,9 +38,9 @@ export declare const VIRTUAL_USER_VARIABLES: {
      * and a server that cannot name its own public URL would be signing in
      * somewhere it only assumed was itself.
      */
-    readonly apiUrl: "VIRTUAL_USER_API_URL";
-    readonly secret: "SCENARIO_ACTOR_SECRET";
-    readonly model: "VIRTUAL_USER_MODEL";
+    readonly apiUrl: 'VIRTUAL_USER_API_URL';
+    readonly secret: 'SCENARIO_ACTOR_SECRET';
+    readonly model: 'VIRTUAL_USER_MODEL';
     /**
      * The same two variables a scenario run reads, because a virtual user signs
      * in and calls through exactly the doors a scenario does. An app that mounts
@@ -48,15 +48,15 @@ export declare const VIRTUAL_USER_VARIABLES: {
      * other way to say so, and without them the run signs in against a 404 and
      * spends its whole budget thinking about why nothing works.
      */
-    readonly signInPath: "SCENARIO_SIGN_IN_PATH";
-    readonly rpcPath: "SCENARIO_RPC_PATH";
+    readonly signInPath: 'SCENARIO_SIGN_IN_PATH';
+    readonly rpcPath: 'SCENARIO_RPC_PATH';
     /**
      * The deployed way in. A Fabric operator token is asymmetric — a stage can
      * verify one and can never mint one — so unlike the actor secret it is safe
      * for a run against a real environment. Read from the environment only as the
      * fallback for a run nobody handed a token to, which is what a schedule is.
      */
-    readonly operatorToken: "FABRIC_OPERATOR_TOKEN";
+    readonly operatorToken: 'FABRIC_OPERATOR_TOKEN';
 };
 /**
  * Which door under the auth mount, given the credential in hand.
@@ -66,7 +66,7 @@ export declare const VIRTUAL_USER_VARIABLES: {
  * to `/api/auth` says so once and both paths follow. A path that names neither
  * plugin is left alone, since it was configured deliberately.
  */
-export declare const signInPathFor: (configured: string | undefined, plugin: "actor" | "fabric") => string | undefined;
+export declare const signInPathFor: (configured: string | undefined, plugin: 'actor' | 'fabric') => string | undefined;
 /**
  * The declared persona behind an id, refused unless it is one a run may be.
  *
@@ -130,7 +130,7 @@ export declare const serializeVirtualUserRun: (run: VirtualUserRunRecord) => {
     persona: string;
     disposition: VirtualUserDisposition;
     seed: number;
-    status: "failed" | "running" | "completed";
+    status: "completed" | "failed" | "running";
     goals: string[];
     memory: Record<string, string>;
     findings: {

package/dist/wirings/virtual-user/virtual-user-schedule.d.ts

@@ -31,7 +31,7 @@ export declare const isDue: (schedule: VirtualUserScheduleRecord, now: Date) =>
  * than rejected, because a schedule is configuration and a swapped pair is a
  * typo, not an attack.
  */
-export declare const nextRunAt: (schedule: Pick<VirtualUserScheduleRecord, "minIntervalMs" | "maxIntervalMs">, now: Date, random: () => number) => Date;
+export declare const nextRunAt: (schedule: Pick<VirtualUserScheduleRecord, 'minIntervalMs' | 'maxIntervalMs'>, now: Date, random: () => number) => Date;
 export type VirtualUserSkipReason = 'in-flight' | 'dispatch-failed' | 'claimed-elsewhere';
 export interface VirtualUserTickResult {
     dispatched: {

package/dist/wirings/workflow/workflow-queue-routing.d.ts

@@ -21,6 +21,6 @@ export declare const stepWorkerQueueName: (strategy: WorkflowQueueStrategy, rpcN
  * every step dispatch would pay for that — only a step that names a workflow
  * and has a queue to reach ever asks.
  */
-export declare const stepDispatchTarget: (rpcName: string, stepName: string, parentIsInline: () => Promise<boolean>) => Promise<"queue" | "inline">;
+export declare const stepDispatchTarget: (rpcName: string, stepName: string, parentIsInline: () => Promise<boolean>) => Promise<'queue' | 'inline'>;
 export declare const jobGroupFor: (strategy: WorkflowQueueStrategy, id?: string) => JobGroup | undefined;
 export declare const stepJobOptions: (stepOptions?: WorkflowStepOptions) => JobOptions;

package/knowledge/decisions/internals/a-reset-suite-makes-the-dev-seed-the-fixture.md

@@ -0,0 +1,50 @@
+---
+type: decision
+title: With scenarios.reset on, the dev seed is the fixture every assertion is written against
+description: The rollback restores the database as the suite found it, so seed rows are the shared baseline — which makes an absolute date in the seed a test that expires
+tags: cli, scenarios
+---
+
+# A reset suite makes the dev seed the fixture
+
+`scenarios.reset` takes a copy of every table when the suite starts and restores
+that copy between scenarios. It is a snapshot-and-restore, not a
+truncate-and-reseed: nothing replays the seed file, and nothing regenerates its
+rows.
+
+Two things follow, and both are easy to get wrong.
+
+**The seed is the fixture.** Before a reset was available, a project usually had
+a hand-rolled reset RPC that wiped and re-created the handful of rows its
+scenarios touched. That RPC was the fixture and the seed was scenery. With the
+rollback on, the whole seed is in scope — every booking, invoice and event a
+developer put there for their own convenience is now a row some scenario can
+count. Assertions written as counts against the old narrow fixture go wrong the
+moment the baseline widens.
+
+**A date literal in the seed expires.** A seed is applied once, and from then on
+the restore keeps handing back the same rows. Write `'2026-03-14'` and the
+fixture is correct on the day it was written and quietly wrong a month later —
+the booking that was supposed to be upcoming is in the past, and the scenario
+that asserts on it fails for a reason that has nothing to do with the code. Seed
+dates belong relative to the moment the seed is applied:
+
+```sql
+INSERT INTO booking (id, starts_at, ends_at) VALUES
+  ('b_upcoming', date('now', '+200 days'), date('now', '+207 days')),
+  ('b_ended',    date('now', '-8 days'),   date('now', '-1 days'));
+```
+
+`date('now', ...)` in sqlite, `now() + interval '200 days'` in postgres. Pick the
+offsets so each row sits unambiguously on the side of whatever boundary the
+scenarios test, rather than a day away from it.
+
+There is a third limit worth stating plainly: the baseline is the database _as
+the suite starts_, so it is not a pristine seed. Run N+1 inherits whatever run N
+left behind. A value that must be unique in the database — an invoice number, a
+reference code — has to be scoped to the run, not hard-coded, or the second run
+collides with the first.
+
+**What this rules out:** treating the reset as "the suite starts from the seed
+every time". It starts from wherever the database was, and keeps returning
+there.

package/knowledge/decisions/internals/hot-reload-reads-the-changed-source-never-a-compiled-copy.md

@@ -0,0 +1,38 @@
+---
+type: decision
+title: Hot reload reads the changed source, never a compiled copy of it
+description: A leftover .js beside a .ts made the reloader announce a reload while re-registering the previous implementation; project TypeScript is now compiled by the reloader itself
+tags: core, dev
+---
+
+# Hot reload reads the changed source, never a compiled copy of it
+
+The reloader watches `.ts` files and runs the file that changed. It used to
+look for a compiled `.js` first — `<outDir>/dist/<rel>.js`, then the sibling
+`<file>.js` — and import the source only when neither existed.
+
+`pikku dev` compiles nothing. Every one of those `.js` files is a leftover from
+an earlier `tsc`, `pikku dist` or bundler run, so reading one re-registered the
+implementation the developer had just replaced and logged `Hot-reloaded: <fn>`
+over the top of it. The log line reads as confirmation, so the change looks
+applied and wrong rather than unapplied — which is the expensive way round
+(#1721).
+
+The lookup was a leftover of the first implementation, which imported raw file
+content through a `data:` URL and genuinely could not handle TypeScript. The
+module runner has transpiled with esbuild since, so the source was loadable all
+along and the compiled candidates could only ever supply stale code.
+
+Loading the source means the reloader also owns resolution. `require('./x.js')`
+where only `x.ts` exists is what every relative import in a TypeScript project
+looks like, and node's `require` has no `.js → .ts` rewrite. Resolution goes
+through the host first — so packages bind to the instance the rest of the
+process holds and `wire*` side effects mutate live state — and a resolved
+TypeScript file outside `node_modules` is then compiled by the reloader rather
+than handed back, because both node and Bun cache what they load and a helper
+edited alongside its caller would otherwise keep answering with the copy loaded
+at startup. That cache is scoped to a single reload for the same reason.
+
+**What this rules out:** reintroducing a compiled-output lookup as a
+"performance" shortcut, and letting the host load project `.ts` dependencies so
+reloads inherit its module cache.

package/knowledge/decisions/internals/index.md

@@ -12,6 +12,7 @@ caller is entitled to assume.
 <!-- pikku:knowledge-index -->
 
 - [A non-streaming agent run registers with aiRunState on the same terms as a streaming one](a-non-streaming-agent-run-registers-with-airunstate-too.md) — Otherwise interruptAIAgent finds the run, passes the ownership check, then cannot stop it — and reports that as if the run were on another host
+- [With scenarios.reset on, the dev seed is the fixture every assertion is written against](a-reset-suite-makes-the-dev-seed-the-fixture.md) — The rollback restores the database as the suite found it, so seed rows are the shared baseline — which makes an absolute date in the seed a test that expires
 - [A resumed turn is as interruptible as the first one](a-resumed-agent-turn-is-as-interruptible-as-the-first.md) — It is the same person listening to the same voice, and after an approval it is where most of the reply actually gets spoken
 - [A scenario step's prose template is offered to a virtual user unfilled](a-scenario-step-template-is-offered-unfilled.md) — A reporter fills placeholders from a run that happened; there is no run yet, and the filled form would answer the question the user is there to answer
 - [A secret that fails to decrypt fails the whole read](a-secret-that-fails-to-decrypt-fails-the-whole-read.md) — getSecrets throws naming the key and its key_version rather than omitting the row, because a silent omission surfaces as an unrelated failure much later
@@ -73,6 +74,7 @@ caller is entitled to assume.
 - [Gateway webhook challenges echo bytes not JSON](gateway-webhook-challenges-echo-bytes-not-json.md) — String verification challenges are returned raw with returnsJSON false, because platforms byte-compare the echo and JSON quoting fails the handshake
 - [Gateway wiring is a meta-wiring over HTTP and channels](gateway-wiring-is-a-meta-wiring-over-http-and-channels.md) — wireGateway writes handler implementations into the HTTP and channel state directly while the inspector compiles the corresponding meta, so runtime registration deliberately writes no meta
 - [Generated src paths in pikku meta are absolute](generated-src-paths-in-pikku-meta-are-absolute.md) — emailsMeta.src is resolved by the CLI at generation time, so reading through the project-relative helpers produces a wrong compound path
+- [Hot reload reads the changed source, never a compiled copy of it](hot-reload-reads-the-changed-source-never-a-compiled-copy.md) — A leftover .js beside a .ts made the reloader announce a reload while re-registering the previous implementation; project TypeScript is now compiled by the reloader itself
 - [Hot reload writes into the function map captured at startup, not pikkuState's current one](hot-reload-writes-into-the-function-map-captured-at-startup.md) — A dev-server watcher may have swapped in a codegen-scoped map whose writes are discarded on restore, and schemas are deliberately left alone
 - [HTTP request bodies are read once and shared between consumers](http-request-bodies-are-read-once-and-shared.md) — The fetch request wrapper memoises the single-use body and builds web Requests lazily, at the cost of holding the whole body in memory
 - [HTTP route groups cascade config in a fixed, per-field order](http-route-groups-cascade-config-in-a-fixed-order.md) — basePath concatenates, tags and middleware merge outward-in, auth is overridden by the innermost group

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.107",
+  "version": "0.12.112",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pikkujs/pikku.git",
+    "directory": "packages/core"
+  },
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -13,7 +18,7 @@
     "test": "bash run-tests.sh",
     "test:watch": "bash run-tests.sh --watch",
     "test:coverage": "bash run-tests.sh --coverage",
-    "prepublishOnly": "yarn build",
+    "prepublishOnly": "bun run build",
     "api-report": "tsx scripts/generate-api-report.mts"
   },
   "sideEffects": [
@@ -51,6 +56,7 @@
     "./mcp": "./dist/wirings/mcp/index.js",
     "./agent": "./dist/wirings/agent/index.js",
     "./agent-scorer": "./dist/wirings/agent-scorer/index.js",
+    "./analytics": "./dist/analytics/index.js",
     "./gateway": "./dist/wirings/gateway/index.js",
     "./cli": "./dist/wirings/cli/index.js",
     "./cli/command-parser": "./dist/wirings/cli/command-parser.js",
@@ -65,6 +71,7 @@
     "./oauth2": "./dist/wirings/oauth2/index.js",
     "./errors": "./dist/errors/index.js",
     "./services": "./dist/services/index.js",
+    "./flag": "./dist/wirings/flag/index.js",
     "./services/local-meta": "./dist/services/meta-service.js",
     "./services/v8-coverage": "./dist/services/v8-coverage-service.js",
     "./services/istanbul-coverage": "./dist/services/istanbul-coverage-service.js",
@@ -92,10 +99,9 @@
     "@ag-ui/core": "0.0.57",
     "@types/node": "^24.13.3",
     "esbuild": "~0.28.2",
-    "tsx": "^4.23.12",
-    "typescript": "^6.0.3"
+    "tsx": "^4.23.12"
   },
   "engines": {
     "node": ">=24"
   }
-}
+}

package/run-tests.sh

@@ -1,8 +1,5 @@
 #!/bin/bash
 
-script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-cd "$script_dir"
-
 # Enable nullglob to handle cases where no files match the pattern
 shopt -s nullglob
 
@@ -43,18 +40,29 @@ if [ ${#files[@]} -eq 0 ]; then
   exit 0
 fi
 
-# Construct the node command
-node_cmd=(node --import tsx --test)
+# Construct the bun command
+#
+# --parallel gives every test file its own worker process, which is what node's
+# `--test` did. Several suites keep module-level caches (a TypeScript program, a
+# temp fixture directory) that a shared process would leak between files.
+#
+# --timeout because bun caps a test at 5s by default where node had no cap, and
+# the suites that build real TypeScript programs run well past that.
+bun_cmd=(bun test --parallel --timeout 120000)
 
 # Append options based on flags
 if [ "$watch_mode" = true ]; then
-  node_cmd+=(--watch)
+  # --watch reruns in one process; parallel workers have nothing to watch.
+  bun_cmd=(bun test --watch --timeout 120000)
 fi
 
 if [ "$coverage_mode" = true ]; then
-  node_cmd+=(--test-coverage-include="src/**/*.{ts,js}" --test-coverage-exclude="**/dist/**" --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=lcov.info)
+  # --coverage-dir=. keeps lcov.info at the package root: CI merges every
+  # package's report by prefixing its SF paths with the file's own directory,
+  # so a nested coverage/ directory would re-root them one level too deep.
+  bun_cmd+=(--coverage --coverage-reporter=lcov --coverage-reporter=text --coverage-dir=.)
   export PIKKU_TEST_COVERAGE=1
 fi
 
-# Execute the node command with the expanded list of files
-"${node_cmd[@]}" "${files[@]}"
+# Execute the bun command with the expanded list of files
+"${bun_cmd[@]}" "${files[@]}"

package/src/public-surface.json

@@ -350,6 +350,7 @@
     "BadRequestError",
     "ConflictError",
     "ExpectationFailedError",
+    "FeatureUnavailableError",
     "ForbiddenError",
     "GatewayTimeoutError",
     "GoneError",
@@ -449,6 +450,19 @@
     "verifyActorSecret",
     "withoutSecrets"
   ],
+  "./flag": [
+    "CachedFlagSource",
+    "assertFeatureAvailable",
+    "bucketOf",
+    "compiledFallbackSnapshot",
+    "defineFeatureFlags",
+    "flattenFeatureFlagDefinitions",
+    "resolveFlag",
+    "resolveFlagForClient",
+    "resolveFlagsForClient",
+    "subjectIdOf",
+    "validateAndBuildFeatureFlagDefinitionsMeta"
+  ],
   "./services/local-meta": [
     "LocalMetaService"
   ],
@@ -549,5 +563,17 @@
     "pikkuDevReloader",
     "reconcileAddonRegistry",
     "reloadGeneratedMeta"
+  ],
+  "./analytics": [
+    "LoggerAnalyticsService",
+    "anonymousAnalyticsIdentity",
+    "composeAnalyticsIdentity",
+    "cookieAnalyticsIdentity",
+    "createInvocationAnalytics",
+    "defineAnalyticsEvents",
+    "fanOutAnalytics",
+    "flattenAnalyticsEvent",
+    "mintCookie",
+    "randomDigits"
   ]
 }

package/src/agent-naming.test.ts

@@ -1,68 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-import { readFileSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import { join, dirname } from 'node:path'
-
-const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
-const reportPath = join(packageRoot, 'api-report.md')
-
-/**
- * `AI` described the model provider, never the agent runtime, so #596 renamed
- * every agent symbol to `Agent`. The names below are the ones that survived,
- * because each really does wrap a provider call.
- *
- * Listing them here is what makes the rule checkable: anything else exported as
- * `AI*` is a symbol that slipped back to the old naming, and this fails rather
- * than letting it reach a consumer.
- */
-const PROVIDER_SYMBOLS = new Set([
-  'AIEmbeddingService',
-  'AIEmbedManyParams',
-  'AIEmbedManyResult',
-  'AIEmbedParams',
-  'AIEmbedResult',
-  'AIGenerateImageParams',
-  'AIGenerateImagePrompt',
-  'AIGenerateImageResult',
-  'AIGenerateSpeechParams',
-  'AIGenerateSpeechResult',
-  'AIProviderAuthError',
-  'AIProviderNotConfiguredError',
-  'AIProviderOptions',
-  'AIRerankParams',
-  'AIRerankResult',
-  'AITranscriptionParams',
-  'AITranscriptionResult',
-])
-
-describe('the agent runtime is not exported under the AI name', () => {
-  test('every AI* symbol in the public surface is a provider wrapper', () => {
-    const report = readFileSync(reportPath, 'utf-8')
-    const found = new Set(report.match(/\bAI[A-Z][A-Za-z]*/g) ?? [])
-
-    const strays = [...found].filter((name) => !PROVIDER_SYMBOLS.has(name))
-
-    assert.deepEqual(
-      strays,
-      [],
-      'these are exported as `AI*` but are not provider wrappers — rename them ' +
-        'to `Agent*`, or add them to PROVIDER_SYMBOLS if they genuinely wrap a ' +
-        'model provider call'
-    )
-  })
-
-  test('the agent entry points are the renamed ones', () => {
-    const { exports } = JSON.parse(
-      readFileSync(join(packageRoot, 'package.json'), 'utf-8')
-    )
-
-    assert.ok(exports['./agent'], 'expected the ./agent entry point')
-    assert.ok(
-      exports['./agent-scorer'],
-      'expected the ./agent-scorer entry point'
-    )
-    assert.equal(exports['./ai-agent'], undefined)
-    assert.equal(exports['./ai-scorer'], undefined)
-  })
-})

package/src/api-report.test.ts

@@ -1,138 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-import { execFileSync } from 'node:child_process'
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { fileURLToPath } from 'node:url'
-import { join, dirname } from 'node:path'
-
-const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
-const reportPath = join(packageRoot, 'api-report.md')
-
-/**
- * `public-surface.json` pins the *names* a consumer can reach. That catches an
- * export appearing or vanishing and nothing else — adding a method to
- * `MetaService`, or making a field on `ChannelMeta` required, sails past it,
- * as does every type-only export. Those are the changes that break a
- * consumer's build, and the report's summary counts how many more of them
- * there are than there are names.
- *
- * So `api-report.md` records what each symbol *is*, and this fails when the
- * committed report and the code disagree.
- *
- * knowledge: decisions/internals/the-api-report-pins-members-not-just-names.md
- */
-describe('the API report matches the code', () => {
-  test('regenerating produces no diff', () => {
-    const committed = readFileSync(reportPath, 'utf-8')
-
-    execFileSync(
-      'npx',
-      ['tsx', join(packageRoot, 'scripts', 'generate-api-report.mts')],
-      { cwd: packageRoot, stdio: 'pipe' }
-    )
-    const regenerated = readFileSync(reportPath, 'utf-8')
-
-    if (committed !== regenerated) {
-      // Restore, so a failing run does not leave the tree dirty.
-      const committedLines = committed.split('\n')
-      const regeneratedLines = regenerated.split('\n')
-      const firstDiff = regeneratedLines.findIndex(
-        (line, i) => line !== committedLines[i]
-      )
-      writeFileSync(reportPath, committed)
-
-      assert.fail(
-        'the public API changed but api-report.md was not regenerated.\n' +
-          `First difference at line ${firstDiff + 1}:\n` +
-          `  committed:   ${committedLines[firstDiff] ?? '(end of file)'}\n` +
-          `  regenerated: ${regeneratedLines[firstDiff] ?? '(end of file)'}\n` +
-          'Run `yarn api-report` and review the diff — a member added to an ' +
-          'exported interface or class is a change consumers compile against.'
-      )
-    }
-  })
-
-  test('the report actually contains member-level detail', () => {
-    // Guards the test above: a report of bare names would match itself forever
-    // while pinning nothing that public-surface.json does not already pin.
-    const report = readFileSync(reportPath, 'utf-8')
-
-    assert.ok(
-      /export interface MetaService \{[^}]*getHttpMeta/.test(report),
-      'expected MetaService to be reported with its members'
-    )
-    assert.ok(
-      !/^\w+: any$/m.test(report),
-      'symbols reported as `any` mean re-export aliases are not being followed'
-    )
-  })
-})
-
-/**
- * Every branch that touches the public surface rewrites the whole report, so
- * two of them meeting is a ~9000-line conflict with no meaningful resolution
- * in it. A merge driver takes the conflict away; the test above is what still
- * insists on a report that matches the code.
- *
- * knowledge: decisions/internals/the-api-report-pins-members-not-just-names.md
- */
-describe('merging the API report is not hand work', () => {
-  const repoRoot = join(packageRoot, '..', '..')
-
-  test('.gitattributes routes the report through the driver', () => {
-    const attributes = readFileSync(join(repoRoot, '.gitattributes'), 'utf-8')
-
-    assert.match(
-      attributes,
-      /^packages\/core\/api-report\.md\s+merge=api-report\b/m,
-      'the report must name the merge driver, or git conflicts on it as usual'
-    )
-  })
-
-  test('the setup script registers the driver as a plain take-one-side', () => {
-    // Against a throwaway repository rather than this one: a driver is written
-    // to `.git/config`, which every worktree of a checkout shares, so running
-    // this in place would reach into whatever else is checked out beside it.
-    const sandbox = mkdtempSync(join(tmpdir(), 'pikku-merge-driver-'))
-    try {
-      execFileSync('git', ['init', '--quiet', sandbox], { stdio: 'pipe' })
-      execFileSync(
-        'node',
-        [join(repoRoot, 'scripts', 'setup-merge-drivers.mjs')],
-        { cwd: sandbox, stdio: 'pipe' }
-      )
-      const driver = execFileSync(
-        'git',
-        ['config', '--local', 'merge.api-report.driver'],
-        { cwd: sandbox, stdio: 'pipe' }
-      )
-        .toString()
-        .trim()
-
-      // `true` writes nothing and succeeds, which is how a driver tells git to
-      // keep the side already in %A. Anything that regenerates the report is
-      // the trap this pins shut: git runs a driver while merging that one
-      // path, with the rest of the tree still unmerged, so the generator reads
-      // the old sources and resolves to a report missing exactly the API the
-      // incoming branch adds — conflict-free and wrong, which is worse than a
-      // conflict. The regeneration belongs to the guard above, which runs
-      // against a finished tree.
-      assert.equal(
-        driver,
-        'true',
-        'the driver must resolve to one side verbatim and run nothing'
-      )
-    } finally {
-      rmSync(sandbox, { recursive: true, force: true })
-    }
-  })
-
-  test('postinstall runs the setup, so a fresh clone is not left without it', () => {
-    const manifest = JSON.parse(
-      readFileSync(join(repoRoot, 'package.json'), 'utf-8')
-    )
-
-    assert.match(manifest.scripts.postinstall, /setup-merge-drivers\.mjs/)
-  })
-})