@pikku/core 0.12.84 → 0.12.86

package/knowledge/decisions/security/an-approval-answer-outlives-the-run-it-answered.md

@@ -11,7 +11,7 @@ An approval gate is asked for so it can be answered for afterwards. "Who
 released the funds" is the entire point of four-eyes sign-off, and until this
 change none of it was kept.
 
-Run state is where a decision *waits*, not where it is kept. The record under
+Run state is where a decision _waits_, not where it is kept. The record under
 `workflowRuns.state.__approval_<hex>` is overwritten by the next write to that
 key, and cleared outright — `decidedBy: undefined` included — whenever a
 decision is refused on replay. A trail that erases exactly the events worth
@@ -31,7 +31,7 @@ shape it had before there was anything to record.
 
 `deleteRun` cascades: `workflowStep` is `onDelete('cascade')` from
 `workflowRuns`, and `workflowStepHistory` from `workflowStep`. Deleting a run
-therefore deletes the sign-off with it — and a *refused* attempt never reaches a
+therefore deletes the sign-off with it — and a _refused_ attempt never reaches a
 step at all, so it was never in that trail to begin with.
 
 Every answer — accepted, refused at submission, or cleared on replay — is
@@ -55,5 +55,5 @@ in `pikkuSchemas`.
 **What this rules out:** a dedicated `workflowApprovals` table. It would have to
 be implemented in all seven backends and would still be deleted with the run
 unless it deliberately broke the cascade — at which point it is the audit table
-with extra steps. If approvals later need to be *queried* as a first-class
+with extra steps. If approvals later need to be _queried_ as a first-class
 entity rather than read back from the trail, that is when to revisit.

package/knowledge/decisions/security/console-addon-privileged-functions-gate-themselves.md

@@ -62,9 +62,10 @@ checked whether or not the host registered a global permission — an app that
 hand-wires `wireAddon({ name: 'console', package: '@pikku/addon-console' })`
 still cannot reach `execFileSync` unauthenticated.
 
-The scopes are spelled as literals here because they are scope ids in the
-addon's own `wireScope` tree — the same tree the `pikku:console:scopes:*` gates
-on the scope-admin functions come from. The generated secret and variable
+The scopes are spelled as literals here because they are scope ids in this
+addon's own `wireScope` tree. The `admin:scopes:*` gates on the scope-admin
+functions come from a different tree — those functions now live in
+`@pikku/addon-admin`, which declares its own. The generated secret and variable
 brokers live in the app's own scaffold rather than the addon, so the addon
 boundary never covered them; they carry `pikku:console:secrets:*` and
 `pikku:console:variables:*` themselves.

package/knowledge/decisions/security/core-safe-fetch-blocks-ssrf-by-host-literal-not-dns.md

@@ -10,7 +10,7 @@ tags: core
 `packages/core/src/utils/safe-fetch.ts` guards every outbound fetch that core
 makes on a caller-supplied URL. `@pikku/core` runs in edge runtimes (Cloudflare
 Workers) that have no Node `dns` module, so the guard cannot resolve a hostname
-and inspect the resulting address. It instead rejects address *literals* that are
+and inspect the resulting address. It instead rejects address _literals_ that are
 obviously internal — loopback, `10/8`, `172.16/12`, `192.168/16`, `0.0.0.0/8`,
 link-local `169.254/16` (the cloud metadata endpoint), IPv6 `::`, `::1`,
 `fe80::/10` and `fc00::/7` — plus the alias forms that reach the same targets:

package/knowledge/decisions/security/gateway-middleware-sessions-must-be-bridged-onto-the-wire.md

@@ -13,8 +13,8 @@ every `runPikkuFunc` call in the gateway runner, copying `await wire.getSession(
 onto `wire.session` when the latter is unset. Gateway middleware is the only
 place a webhook can acquire a session at all — typically by mapping a verified
 platform sender id to a user. Middleware that assigns `wire.session` directly
-needs no help, but the idiomatic `wire.setSession()` writes into the *enclosing
-wiring's* session service, and the handler's own invocation does not read that
+needs no help, but the idiomatic `wire.setSession()` writes into the _enclosing
+wiring's_ session service, and the handler's own invocation does not read that
 service.
 
 Without the bridge, the failure mode is silent and it fails open in the way that

package/knowledge/decisions/security/global-permissions-and-function-permissions-are-independent-gates.md

@@ -23,7 +23,7 @@ satisfy an admin-only function's requirements, because the two gates are
 evaluated independently against separate inputs. An empty or absent group passes,
 so declaring no permissions means "globals only", not "deny".
 
-Globals are bucketed per package, and a function reads *both* the root bucket and
+Globals are bucketed per package, and a function reads _both_ the root bucket and
 its own package's — root first. The generated `addGlobalPermission` wrapper takes
 no package argument, so an application's rules only ever land in the root bucket;
 resolving the package bucket alone meant a host rule like "every request needs a

package/knowledge/decisions/security/http-request-bodies-are-bounded-before-they-are-buffered.md

@@ -26,11 +26,11 @@ they divide into two kinds, and the difference is what can actually be
 prevented rather than merely reported:
 
 - **Prevention.** uWebSockets drives `res.onData` itself, so it counts bytes and
-  *drops* chunks past the limit rather than concatenating, replying 413 before
+  _drops_ chunks past the limit rather than concatenating, replying 413 before
   routing — the only point at which the buffering can be stopped, which is why
   it deviates from the fetch adapter's 404-an-unmatched-route order. Fastify
   delegates to native `bodyLimit`, set only when `maxBodySize` is configured so
-  the default never *loosens* fastify's stricter 1 MB. `PikkuExpressServer`
+  the default never _loosens_ fastify's stricter 1 MB. `PikkuExpressServer`
   feeds the limit into `express.json`/`text`/`urlencoded`.
 - **Rejection only.** `express-middleware` is handed an already-parsed body, so
   its guard makes the rejection uniform but cannot reclaim the memory; a

package/knowledge/decisions/security/index.md

@@ -9,6 +9,7 @@ description: Who may do what in core — gates, defaults, and the failures they
 A rule about who may do what, and which way it fails when it is unsure.
 
 <!-- pikku:knowledge-index -->
+
 - [A dropped audit write is always logged](a-dropped-audit-write-is-always-logged.md) — The no-op audit service falls back to the singleton logger when the wire carries none, so an unconfigured audit call is never silent
 - [A function never receives the secret service](a-function-never-receives-the-secret-service.md) — Every function-, permission- and auth-facing services type is bounded by SecretlessServices, so reaching for `secrets` in a function body is a type error rather than a lint
 - [A graph run starts at an entry node the graph declared](a-graph-run-starts-at-an-entry-node-the-graph-declared.md) — startNode may only name a node in meta.entryNodeIds, and no generated route offers it, because otherwise a caller picks which half of the graph to skip
@@ -60,4 +61,5 @@ A rule about who may do what, and which way it fails when it is unsure.
 - [A queued workflow step rehydrates its session from the persisted run wire](workflow-queued-steps-rehydrate-their-session-from-the-run-wire.md) — The queue job payload is just `{ runId }`, so without threading `pikkuUserId` an authed step sees no session and throws
 - [Scenario sessions are isolated per actor and reset between scenarios](workflow-scenario-sessions-are-isolated-per-actor-and-per-scenario.md) — One jar per actor keeps two personas from sharing a session; a browser reset keeps one scenario from leaving the next signed in as somebody else
 - [A scenario step is never registered as a callable RPC and never dispatched on the queue](workflow-scenario-steps-are-never-network-invocable.md) — A step drives a browser and holds an actor's session, so exposing it as an RPC would put that reach on the network
+
 <!-- /pikku:knowledge-index -->

package/knowledge/decisions/security/mcp-internal-error-details-are-double-gated-on-production.md

@@ -9,7 +9,7 @@ tags: mcp
 
 `RunMCPEndpointParams.exposeErrors` in
 `packages/core/src/wirings/mcp/mcp-runner.ts` defaults to `!isProduction()`, and
-`runMCPPikkuFunc` checks `exposeErrors && !isProduction()` *again* when building
+`runMCPPikkuFunc` checks `exposeErrors && !isProduction()` _again_ when building
 the `-32603` internal-error response that carries `{ message, stack }`. The
 second check looks redundant against the default — it is not. The default only
 applies when the caller omits the option; a caller that passes

package/knowledge/decisions/security/queue-jobs-carry-the-producers-pikku-user-id.md

@@ -19,10 +19,10 @@ set by whoever enqueues the job. The adapter surfaces it as
 The claim is now HMAC-signed at enqueue and verified in `runQueueJob` — see
 [[queue-job-identities-are-signed-at-enqueue]], which supersedes the "any
 producer may name any user" reading below. Everything here still holds for the
-*authorization* question: signing proves the producer held the deployment
+_authorization_ question: signing proves the producer held the deployment
 secret, not that it was entitled to name that user.
 
-There is no re-authentication at the worker boundary — the queue payload *is* the
+There is no re-authentication at the worker boundary — the queue payload _is_ the
 credential. Workers run with `auth: false`, so nothing downstream re-checks that
 the producer was entitled to name that user. This is deliberate: the whole point
 is to let a background job resolve the same per-user credentials the original
@@ -35,5 +35,5 @@ client-supplied field flow into `JobOptions.pikkuUserId` without an authorizatio
 check first. It also rules out treating the queue as an authorization boundary —
 do not add a "the worker validated the producer's rights" assumption anywhere
 downstream, and do not drop the id from the wire on the theory that workers are
-unauthenticated anyway. Dropping an id that fails *signature* verification is a
+unauthenticated anyway. Dropping an id that fails _signature_ verification is a
 different matter and is what the worker now does.

package/knowledge/decisions/security/remote-addon-tokens-are-client-credentials-not-mesh-trust.md

@@ -23,7 +23,7 @@ logged or traced. Binding a `credentialId` without a wire that supports
 credentials throws rather than falling back to a shared secret.
 
 Resolution fails closed. `null` is returned only when no auth is bound at all,
-which is the addon declaring its remote surface public. Once auth *is* bound, a
+which is the addon declaring its remote surface public. Once auth _is_ bound, a
 resolved value of `null`, `undefined` or `''` raises `RemoteAddonAuthError` (401)
 instead of dispatching an unauthenticated request that the host might accept as
 anonymous.

package/knowledge/decisions/security/scaffold-features-are-authenticated-unless-opted-out.md

@@ -16,7 +16,7 @@ dispatcher that cannot know what it dispatches to — wrong the moment one
 legitimately public sessionless function exists. For `userAdmin` it was
 redundant: the generated functions are `pikkuFunc` with `scopes:
 ['admin:users:list']`, gated twice over already. But for `agent`, `workflow`,
-`events` and `scenarios` it was the *only* gate, because those generate real
+`events` and `scenarios` it was the _only_ gate, because those generate real
 endpoints the app never authors and has nowhere else to declare a gate for.
 A uniform collapse to boolean would have silently opened four surfaces.
 
@@ -33,7 +33,7 @@ it.
 
 The object form is also what makes the legacy strings safe to remove. An
 earlier design used `string` for the output path, under which `"no-auth"` would
-have parsed as *a file named `no-auth`* — every unmigrated config silently
+have parsed as _a file named `no-auth`_ — every unmigrated config silently
 producing nonsense instead of failing. With `boolean | object`, a string is
 never valid, so `resolveScaffoldFeature` refuses `'auth'` and `'no-auth'` by
 name and prints the replacement. Coercing them was rejected outright: the value

package/knowledge/decisions/security/self-authentication-is-declared-not-detected.md

@@ -17,7 +17,7 @@ them on every build.
 The fix is a declaration — `selfAuthenticated: true` on the function config —
 not analysis of the body. Detection would have to recognise an open-ended set of
 authorization idioms, and it fails in the expensive direction: a body that
-*looks* like it checks something silences the warning for a function that
+_looks_ like it checks something silences the warning for a function that
 checks nothing. A declaration cannot be wrong by accident. Someone typed it,
 it is greppable, and it survives into meta where an audit reads it as what it
 is — a claim by a named author, not an inference.

package/knowledge/decisions/security/signed-content-urls-bind-the-request-path.md

@@ -13,8 +13,8 @@ requested. `LocalContent` requires a `JWTService` and throws without one; a
 verifier with no key available rejects with 403 rather than allowing the
 request, logging once per process so an attacker-triggerable path cannot flood.
 
-A signature over `{signedAt, expiresAt, notBefore}` alone proves only *when* a
-URL was issued, never *what* it was issued for. Any valid token was a skeleton
+A signature over `{signedAt, expiresAt, notBefore}` alone proves only _when_ a
+URL was issued, never _what_ it was issued for. Any valid token was a skeleton
 key: swap the pathname from a public thumbnail to a private document and the
 signature still verifies. Timestamps bound the window; only the path binds the
 asset.

package/knowledge/index.md

@@ -6,7 +6,7 @@ description: Why @pikku/core is built the way it is — the reasoning that used
 
 # Knowledge
 
-Pikku's source says *what* it does. These notes say *why*, for the handful of
+Pikku's source says _what_ it does. These notes say _why_, for the handful of
 choices where the code alone reads as arbitrary or, worse, reads as a mistake.
 
 The rule that produced this directory: **reasoning never lives in code.** A
@@ -19,6 +19,8 @@ meta files, the export surface. A note that repeats them is a copy that will
 drift.
 
 <!-- pikku:knowledge-index -->
+
 - [decisions](decisions/index.md) — a rule that was chosen, and what it rules out
 - [questions](questions/index.md) — something asked and not yet answered
+
 <!-- /pikku:knowledge-index -->

package/knowledge/questions/channel-middleware-accepts-bare-factories-that-nothing-resolves.md

@@ -14,7 +14,7 @@ tags: core, channel
 `channel-common.ts` and `channel-handler.ts` — assert across the gap.
 
 A factory is `(input: In) => CorePikkuChannelMiddleware`: the author is meant to
-*call* it at wiring time and put the result in the array.
+_call_ it at wiring time and put the result in the array.
 `combineChannelMiddleware` contains no factory-resolution branch, and neither
 does `combineMiddleware` for ordinary middleware — that is consistent and
 deliberate. So a bare, uncalled factory in `channelMiddleware` would be pushed

package/knowledge/questions/index.md

@@ -11,6 +11,8 @@ currently makes a choice that nobody has defended — the choice stays, the doub
 gets recorded.
 
 <!-- pikku:knowledge-index -->
+
 - [A channel's middleware list accepts bare factories that nothing ever resolves](channel-middleware-accepts-bare-factories-that-nothing-resolves.md) — CoreChannel.channelMiddleware admits CorePikkuChannelMiddlewareFactory, but no runner calls one, so a bare factory would stall the chain
 - [An unauthorized channel reply is sent outside the channel's declared Out type](unauthorized-channel-replies-escape-the-declared-out-type.md) — processMessageHandlers sends a bare string on auth failure, which no generated client type admits — nobody has decided what the typed shape should be
+
 <!-- /pikku:knowledge-index -->

package/package.json

@@ -1,11 +1,9 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.84",
+  "version": "0.12.86",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
-  "module": "dist/index.js",
-  "main": "dist/index.js",
   "type": "module",
   "scripts": {
     "tsc": "tsc && tsc -p tsconfig.type-tests.json",
@@ -21,14 +19,15 @@
   "sideEffects": [
     "./dist/errors/errors.js",
     "./dist/wirings/rpc/rpc-runner.js",
-    "./dist/wirings/rpc/remote-addon-auth.js",
+    "./dist/wirings/addon/remote-addon-auth.js",
     "./dist/wirings/workflow/workflow-approval-policy.js",
     "./dist/wirings/workflow/workflow-errors.js",
     "./dist/wirings/workflow/workflow-run-ownership.js",
     "./dist/wirings/workflow/pikku-scenario-service.js"
   ],
   "exports": {
-    ".": "./dist/index.js",
+    ".": "./dist/bootstrap-compat/root.js",
+    "./types": "./dist/types/index.js",
     "./middleware": "./dist/middleware/index.js",
     "./function": "./dist/function/index.js",
     "./channel": "./dist/wirings/channel/index.js",
@@ -46,6 +45,7 @@
     "./scheduler": "./dist/wirings/scheduler/index.js",
     "./trigger": "./dist/wirings/trigger/index.js",
     "./rpc": "./dist/wirings/rpc/index.js",
+    "./addon": "./dist/wirings/addon/index.js",
     "./safe-fetch": "./dist/utils/safe-fetch.js",
     "./node-host-resolver": "./dist/utils/node-host-resolver.js",
     "./mcp": "./dist/wirings/mcp/index.js",
@@ -73,8 +73,9 @@
     "./services/temporary-file-service": "./dist/services/temporary-file-service.js",
     "./crypto-utils": "./dist/crypto-utils.js",
     "./hmac": "./dist/utils/hmac.js",
-    "./ecosystem": "./dist/ecosystem.js",
-    "./ecosystem/*": "./dist/ecosystem/*.js",
+    "./state": "./dist/pikku-state.js",
+    "./classification": "./dist/classification/index.js",
+    "./utils": "./dist/utils.js",
     "./schema": "./dist/schema.js",
     "./testing": "./dist/testing/index.js",
     "./dev": "./dist/dev/hot-reload.js"
@@ -82,19 +83,19 @@
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
     "@types/json-schema": "^7.0.15",
-    "cookie": "^1.1.1",
+    "cookie": "^2.0.1",
     "json-schema": "^0.4.0",
-    "path-to-regexp": "^8.3.0",
+    "path-to-regexp": "^8.4.2",
     "picoquery": "^2.5.0"
   },
   "devDependencies": {
     "@ag-ui/core": "0.0.57",
-    "@types/node": "^24.11.0",
-    "esbuild": "~0.27.0",
-    "tsx": "^4.21.0",
+    "@types/node": "^24.13.3",
+    "esbuild": "~0.28.2",
+    "tsx": "^4.23.12",
     "typescript": "^6.0.3"
   },
   "engines": {
     "node": ">=24"
   }
-}
+}

package/scripts/generate-api-report.d.mts

@@ -1 +1 @@
-export {};
+export {}

package/scripts/generate-api-report.mjs

@@ -16,74 +16,81 @@
  *
  * Run: yarn api-report
  */
-import { readFileSync, writeFileSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import ts from 'typescript';
-const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const pkg = JSON.parse(readFileSync(resolve(packageRoot, 'package.json'), 'utf-8'));
+import { readFileSync, writeFileSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import ts from 'typescript'
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const pkg = JSON.parse(
+  readFileSync(resolve(packageRoot, 'package.json'), 'utf-8')
+)
 const entryPoints = Object.entries(pkg.exports).map(([subpath, dist]) => ({
-    subpath,
-    file: resolve(packageRoot, dist.replace('./dist/', './src/').replace(/\.js$/, '.ts')),
-}));
-const program = ts.createProgram(entryPoints.map((e) => e.file), {
+  subpath,
+  file: resolve(
+    packageRoot,
+    dist.replace('./dist/', './src/').replace(/\.js$/, '.ts')
+  ),
+}))
+const program = ts.createProgram(
+  entryPoints.map((e) => e.file),
+  {
     target: ts.ScriptTarget.ESNext,
     module: ts.ModuleKind.Node16,
     moduleResolution: ts.ModuleResolutionKind.Node16,
     strict: true,
     skipLibCheck: true,
-});
-const checker = program.getTypeChecker();
+  }
+)
+const checker = program.getTypeChecker()
 /** One line per symbol: how it is declared, flattened and stripped of noise. */
 const signature = (exported) => {
-    // A re-export is an alias; the declaration that matters is the target's, so
-    // an interface re-exported through a barrel still reports its members.
-    const symbol = exported.flags & ts.SymbolFlags.Alias
-        ? checker.getAliasedSymbol(exported)
-        : exported;
-    const declaration = symbol.declarations?.[0];
-    if (!declaration)
-        return exported.getName();
-    if (ts.isInterfaceDeclaration(declaration) ||
-        ts.isClassDeclaration(declaration) ||
-        ts.isTypeAliasDeclaration(declaration) ||
-        ts.isEnumDeclaration(declaration)) {
-        // The declaration itself, so member changes show up in the diff.
-        return declaration
-            .getText()
-            .replace(/\/\*\*[\s\S]*?\*\//g, '')
-            .replace(/\/\/[^\n]*/g, '')
-            .split('\n')
-            .map((l) => l.trim())
-            .filter(Boolean)
-            .join(' ');
-    }
-    const type = checker.getTypeOfSymbolAtLocation(symbol, declaration);
-    return `${exported.getName()}: ${checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation)}`;
-};
+  // A re-export is an alias; the declaration that matters is the target's, so
+  // an interface re-exported through a barrel still reports its members.
+  const symbol =
+    exported.flags & ts.SymbolFlags.Alias
+      ? checker.getAliasedSymbol(exported)
+      : exported
+  const declaration = symbol.declarations?.[0]
+  if (!declaration) return exported.getName()
+  if (
+    ts.isInterfaceDeclaration(declaration) ||
+    ts.isClassDeclaration(declaration) ||
+    ts.isTypeAliasDeclaration(declaration) ||
+    ts.isEnumDeclaration(declaration)
+  ) {
+    // The declaration itself, so member changes show up in the diff.
+    return declaration
+      .getText()
+      .replace(/\/\*\*[\s\S]*?\*\//g, '')
+      .replace(/\/\/[^\n]*/g, '')
+      .split('\n')
+      .map((l) => l.trim())
+      .filter(Boolean)
+      .join(' ')
+  }
+  const type = checker.getTypeOfSymbolAtLocation(symbol, declaration)
+  return `${exported.getName()}: ${checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation)}`
+}
 const sections = [
-    '# @pikku/core API report',
-    '',
-    'Generated by `yarn api-report`. Every exported symbol with its full',
-    'signature, so a member-level change is a reviewable diff. Do not edit.',
-    '',
-];
+  '# @pikku/core API report',
+  '',
+  'Generated by `yarn api-report`. Every exported symbol with its full',
+  'signature, so a member-level change is a reviewable diff. Do not edit.',
+  '',
+]
 for (const { subpath, file } of entryPoints) {
-    const source = program.getSourceFile(file);
-    if (!source)
-        continue;
-    const moduleSymbol = checker.getSymbolAtLocation(source);
-    if (!moduleSymbol)
-        continue;
-    const exports = checker
-        .getExportsOfModule(moduleSymbol)
-        .map((s) => [s.getName(), signature(s)])
-        .sort(([a], [b]) => a.localeCompare(b));
-    sections.push(`## ${subpath}`, '');
-    sections.push('```ts');
-    for (const [, sig] of exports)
-        sections.push(sig);
-    sections.push('```', '');
+  const source = program.getSourceFile(file)
+  if (!source) continue
+  const moduleSymbol = checker.getSymbolAtLocation(source)
+  if (!moduleSymbol) continue
+  const exports = checker
+    .getExportsOfModule(moduleSymbol)
+    .map((s) => [s.getName(), signature(s)])
+    .sort(([a], [b]) => a.localeCompare(b))
+  sections.push(`## ${subpath}`, '')
+  sections.push('```ts')
+  for (const [, sig] of exports) sections.push(sig)
+  sections.push('```', '')
 }
-writeFileSync(resolve(packageRoot, 'api-report.md'), sections.join('\n'));
-console.log(`api-report.md written for ${entryPoints.length} entry points`);
+writeFileSync(resolve(packageRoot, 'api-report.md'), sections.join('\n'))
+console.log(`api-report.md written for ${entryPoints.length} entry points`)

package/scripts/generate-api-report.mts

@@ -180,9 +180,7 @@ const isPublic = (member: ts.ClassElement | ts.TypeElement): boolean =>
  */
 const membered = (
   declaration:
-    | ts.ClassDeclaration
-    | ts.InterfaceDeclaration
-    | ts.EnumDeclaration,
+    ts.ClassDeclaration | ts.InterfaceDeclaration | ts.EnumDeclaration,
   members: ts.NodeArray<ts.ClassElement | ts.TypeElement | ts.EnumMember>
 ): string => {
   if (members.length === 0) return oneLine(declaration.getText())
@@ -233,17 +231,6 @@ const signature = (exported: ts.Symbol): string => {
   return `${exported.getName()}: ${checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation)}`
 }
 
-/**
- * Entry points whose signatures move with the CLI's codegen. Everything else
- * is what an application imports, and is what a compatibility promise covers.
- *
- * knowledge: decisions/internals/the-ecosystem-entry-point-carries-the-adapter-surface.md
- */
-const isEcosystem = (subpath: string) =>
-  subpath === './ecosystem' ||
-  subpath === './internal' ||
-  subpath.startsWith('./ecosystem/')
-
 type Exported = { name: string; members: number; signature: string }
 
 /** The members the report lists, which is what the tally is counting. */
@@ -282,33 +269,16 @@ for (const { subpath, file } of entryPoints) {
   )
 }
 
-// A name reachable from more than one entry point is counted once, against the
-// weaker promise — reaching it through a stable subpath is what a consumer will
-// have done, whatever else also exports it.
-const tierOf = new Map<string, string>()
+// A name reachable from more than one entry point is counted once: what a
+// compatibility promise owes is the name, not each door onto it.
 const membersOf = new Map<string, number>()
-for (const [subpath, exports] of modules) {
-  const tier = isEcosystem(subpath) ? 'ecosystem' : 'stable'
-  for (const { name, members } of exports) {
-    if (tier === 'stable' || !tierOf.has(name)) tierOf.set(name, tier)
+for (const exports of modules.values())
+  for (const { name, members } of exports)
     membersOf.set(name, Math.max(membersOf.get(name) ?? 0, members))
-  }
-}
 
-const tally = (tier: string) => {
-  const names = [...tierOf].filter(([, t]) => t === tier).map(([n]) => n)
-  return {
-    entryPoints: [...modules.keys()].filter(
-      (s) => (isEcosystem(s) ? 'ecosystem' : 'stable') === tier
-    ).length,
-    names: names.length,
-    members: names.reduce((total, n) => total + (membersOf.get(n) ?? 0), 0),
-  }
-}
-const stable = tally('stable')
-const ecosystem = tally('ecosystem')
-const observable =
-  stable.names + stable.members + ecosystem.names + ecosystem.members
+const names = membersOf.size
+const members = [...membersOf.values()].reduce((total, n) => total + n, 0)
+const observable = names + members
 
 const reachableFrom = new Map<string, number>()
 for (const exports of modules.values())
@@ -337,13 +307,9 @@ const sections: string[] = [
   '',
   '## What a compatibility promise covers',
   '',
-  `**${observable} observable things**: ${stable.names + ecosystem.names} exported names, plus`,
-  `${stable.members + ecosystem.members} members on the classes and interfaces among them.`,
-  '',
-  '| tier | entry points | names | members |',
-  '| --- | ---: | ---: | ---: |',
-  `| stable | ${stable.entryPoints} | ${stable.names} | ${stable.members} |`,
-  `| ecosystem | ${ecosystem.entryPoints} | ${ecosystem.names} | ${ecosystem.members} |`,
+  `**${observable} observable things**: ${names} exported names, plus`,
+  `${members} members on the classes and interfaces among them, reachable`,
+  `through ${modules.size} entry points.`,
   '',
   'An entry point whose exports are mostly *exclusive* is a self-contained',
   'subsystem rather than shared machinery — which tends to mean a newer one.',

package/src/api-report.test.ts

@@ -1,7 +1,8 @@
 import { describe, test } from 'node:test'
 import assert from 'node:assert/strict'
 import { execFileSync } from 'node:child_process'
-import { readFileSync, writeFileSync } from 'node:fs'
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
 import { fileURLToPath } from 'node:url'
 import { join, dirname } from 'node:path'
 
@@ -67,3 +68,71 @@ describe('the API report matches the code', () => {
     )
   })
 })
+
+/**
+ * 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/)
+  })
+})