@feasibleone/blong-gogo 1.38.0 → 1.39.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [1.39.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.38.1...blong-gogo-v1.39.0) (2026-10-11)
+
+
+### Features
+
+* blong-kustomize ([0ad6915](https://github.com/feasibleone/blong/commit/0ad6915af0d3c300a8741a509232aec7649999a1))
+
+
+### Bug Fixes
+
+* address CI issues ([83b8957](https://github.com/feasibleone/blong/commit/83b895773bb020e1e1424513ecffd3e15b13dec6))
+* address CI issues ([d23b652](https://github.com/feasibleone/blong/commit/d23b652b79eebfbaf46716ee4d7e7381730b384e))
+* address CI issues ([10cc9bf](https://github.com/feasibleone/blong/commit/10cc9bfe68f3f8bc40dba97eb627b303e1fe64b5))
+* address CI issues ([a2ff403](https://github.com/feasibleone/blong/commit/a2ff4035086ecb726d9df08798dae4a5556af7dd))
+* address CI issues ([5ce588b](https://github.com/feasibleone/blong/commit/5ce588b763bee75afc2fca603998252d41443da5))
+* address CI issues ([d32fbb1](https://github.com/feasibleone/blong/commit/d32fbb10cc945db43eb492606792f63bfb848ae6))
+* address CI issues ([bea0f62](https://github.com/feasibleone/blong/commit/bea0f62aba2dcef95cc4363b02c4ee3e05c620b1))
+* address CI issues, improve snapshots ([a86310a](https://github.com/feasibleone/blong/commit/a86310a8317e28e610a33072a483afc83b4b5bd2))
+* address latency issue ([7504310](https://github.com/feasibleone/blong/commit/750431029b7345100e4124675f36404b6e1693fa))
+* kustomize layout ([1e0eb50](https://github.com/feasibleone/blong/commit/1e0eb506617862db0e5e19f33d18ee0121c6aa42))
+* test ACL with cucumber ([3a84be9](https://github.com/feasibleone/blong/commit/3a84be99a1544dd7ae599cdd976191cf21cabba9))
+
+## [1.38.1](https://github.com/feasibleone/blong/compare/blong-gogo-v1.38.0...blong-gogo-v1.38.1) (2026-10-01)
+
+
+### Bug Fixes
+
+* error handling ([fc1af53](https://github.com/feasibleone/blong/commit/fc1af536ae814a88a661341936bd9f9c519b38d1))
+
 ## [1.38.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.37.0...blong-gogo-v1.38.0) (2026-09-29)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feasibleone/blong-gogo",
-  "version": "1.38.0",
+  "version": "1.39.0",
   "repository": {
     "url": "git+https://github.com/feasibleone/blong.git"
   },
@@ -38,6 +38,7 @@
     "@feasibleone/blong-lib": "^1.0.0",
     "@feasibleone/blong-mle": "^1.0.0",
     "@feasibleone/blong-mock": "^1.0.0",
+    "@feasibleone/blong-template": "1.0.0",
     "@feasibleone/semantic-log": "^1.0.0",
     "@keycloak/keycloak-admin-client": "^26.6.2",
     "@kubernetes/client-node": "^1.4.0",
@@ -79,26 +80,25 @@
     "ut-function.interpolate": "1.1.3",
     "ut-function.merge": "^1.5.6",
     "uuid": "^13.0.2",
-    "yaml": "^2.8.3",
-    "@feasibleone/blong-template": "1.0.0"
+    "yaml": "^2.8.3"
   },
   "devDependencies": {
+    "@feasibleone/blong-dev": "1.9.0",
     "@rushstack/heft": "^1.2.6",
     "@rushstack/heft-lint-plugin": "^1.2.6",
     "@rushstack/heft-typescript-plugin": "^1.3.1",
     "@types/cacache": "^20.0.1",
     "@types/node": "^24",
-    "playwright": "^1.60.0",
+    "playwright": "^1.63.0",
     "tap": "^21.6.3",
     "typescript": "^6.0.3",
-    "vite": "^8.2.1",
-    "@feasibleone/blong-dev": "1.7.1"
+    "vite": "^8.2.1"
   },
   "scripts": {
     "browser-check": "node scripts/browser-compat-check.mjs",
     "build": "true",
     "ci-coverage": "./run-coverage.sh",
-    "ci-lint": "blong-dev lint",
+    "ci-lint": "blong-dev lint && node docker/manifests.mjs --check",
     "ci-publish": "node ../../common/scripts/install-run-rush-pnpm.js publish --access public --provenance",
     "ci-test": "blong-dev test",
     "test": "blong-dev test"

package/src/ConfigRuntime.ts

@@ -314,7 +314,14 @@ export default class ConfigRuntime implements IConfigRuntime {
     }
 
     private mergeConfigs(blongConfig: object): object {
-        const loaded = loadBlong(blongConfig);
+        // The intents travel into `blong-config`, which reads them out of `env`. They decide which
+        // rc files a process reads at all — the *trailing* one is the suffix both source names are
+        // built from, the framework's existing convention — so a config step that cannot see them
+        // leaves every process reading the `dev` file whatever it was asked to be (Phase 15 E).
+        const intents = (this.#baseConfig as {configNames?: string[]}).configNames;
+        const loaded = loadBlong(
+            intents?.length ? {env: intents.join(','), ...blongConfig} : blongConfig,
+        );
         return merge({}, this.#baseConfig, ...this.#configs, loaded);
     }
 

package/src/Gateway.ts

@@ -14,7 +14,12 @@ import type {
     IPlatformApi,
 } from '@feasibleone/blong/types';
 import {Internal} from '@feasibleone/blong/types';
-import fastify, {type FastifyReply, type FastifyRequest, type RouteOptions} from 'fastify';
+import fastify, {
+    LogController,
+    type FastifyReply,
+    type FastifyRequest,
+    type RouteOptions,
+} from 'fastify';
 import os from 'os';
 import type {LevelWithSilent} from 'pino';
 import {Type, type TSchema} from 'typebox';
@@ -23,6 +28,7 @@ import {v4} from 'uuid';
 
 import {TRACE_HEADER, withoutCapabilities} from '@feasibleone/semantic-log/capability';
 import {CALLS_CAPABILITY, GRANT_HEADER} from './callTrace.ts';
+import {GENERATED_KEY_SPEC, GENERATED_PAIR_WARNING} from './gatewayKeys.ts';
 import {grantedCalls, grantKeyFrom} from './grant.ts';
 import {
     callsFor,
@@ -61,6 +67,17 @@ type GatewayRequest = FastifyRequest;
 
 const errorMap: IErrorMap = {
     'gateway.jwtMissingHeader': {message: 'Missing bearer authorization header', statusCode: 401},
+    // The method-level refusal of RBAC.  Typed because a test that probes a denial
+    // on purpose declares it in `expect`, and the demotion matches on the type —
+    // an untyped `Error` is always logged at error level.
+    'gateway.notAllowed': {
+        message: 'Authorization denied: method "{methodName}" not allowed',
+        statusCode: 403,
+    },
+    'gateway.noActions': {
+        message: 'Authorization denied: no actions resolved',
+        statusCode: 403,
+    },
 };
 
 declare module 'fastify' {
@@ -229,6 +246,21 @@ export default class Gateway extends Internal implements IGateway {
             };
         });
     }
+
+    /**
+     * The browser build this process was configured to serve, as the merge resolved it.
+     *
+     * `config()` is protected on purpose: that subtree carries the key pair (`sign`, `encrypt`), the
+     * exposure D-448 keeps shut. *Which* static root arrived is a different question, and one a test
+     * could not ask anywhere — the plugin's own behaviour is covered (`static.test.ts`: it serves a
+     * bundle and tolerates a missing one), while nothing could see that a process's own block reaches
+     * this port at all. That leg is what a suite's `release` block naming the artifact's browser build
+     * depends on, and its failure is silent: the plugin is registered only when the config is there,
+     * so `/s` answers nothing while every other surface works (T-246).
+     */
+    public staticRoot(): string | undefined {
+        return this.#config.static?.root;
+    }
     #errorFields: [string, unknown][] = [];
     #plugins: {plugin: unknown; options: unknown}[] = [];
     #platform: IPlatformApi;
@@ -259,16 +291,22 @@ export default class Gateway extends Internal implements IGateway {
         this.#platform = platform!;
 
         this.merge(this.#config, config);
-        this.#config.sign ||= (
-            process.env.GATEWAY_SIGN_KEY
-                ? {env: 'GATEWAY_SIGN_KEY'}
-                : {generate: {alg: 'ES384', crv: 'P-384', use: 'sig'}}
-        ) as IConfig['sign'];
-        this.#config.encrypt ||= (
-            process.env.GATEWAY_ENCRYPT_KEY
-                ? {env: 'GATEWAY_ENCRYPT_KEY'}
-                : {generate: {alg: 'ECDH-ES+A256KW', crv: 'P-384', use: 'enc'}}
-        ) as IConfig['encrypt'];
+        // A pair reaches this config as ordinary configuration — the deployment's rc file
+        // (`gateway.sign` / `gateway.encrypt` under the pod's home), the `dev` block's committed
+        // literals, or a `--gateway.sign=…` flag — and a process given none generates its own. That
+        // last case is worth a warning rather than silence: two replicas of one suite would then
+        // mint tokens the other cannot verify, and the symptom is a rejected session somewhere else,
+        // long after the cause. A deployment that mounts the file never sees this line (D-441).
+        const generated = !this.#config.sign || !this.#config.encrypt;
+        this.#config.sign ||= GENERATED_KEY_SPEC.sign as IConfig['sign'];
+        this.#config.encrypt ||= GENERATED_KEY_SPEC.encrypt as IConfig['encrypt'];
+        if (generated) {
+            // The loader resolves the pair for every process that serves a gateway
+            // (`resolveGatewayPair`), so a missing half here means a gateway built *without* one — a
+            // component constructed directly by a test. Kept as the last resort it always was, with
+            // the same descriptors and the same sentence the loader uses.
+            this.#log?.logger('warn', {name: 'gateway'})?.warn?.({}, GENERATED_PAIR_WARNING);
+        }
         this.#errorFields = Object.entries({
             type: true,
             message: true,
@@ -436,6 +474,15 @@ export default class Gateway extends Internal implements IGateway {
                                     id: Type.Optional(Type.Union([Type.String(), Type.Number()])),
                                     method: isWildcard ? Type.String() : Type.Literal(method),
                                     params: value.params,
+                                    // A caller may declare the errors it expects.  The
+                                    // gateway only *honours* it when configured to
+                                    // (`expectedErrors`), but the field has to survive
+                                    // validation for the body to reach the route at all —
+                                    // without it the declaration was silently dropped and
+                                    // every expected failure was logged as a surprise.
+                                    expect: Type.Optional(
+                                        Type.Union([Type.String(), Type.Array(Type.String())]),
+                                    ),
                                 }),
                             }
                           : undefined),
@@ -706,7 +753,12 @@ export default class Gateway extends Internal implements IGateway {
                 // both more than a reader needs and less than the flow records say.
                 // Nothing else depends on those two lines: the request has a flow, the
                 // flow has its calls, and both are recorded where they belong.
-                disableRequestLogging: true,
+                //
+                // Passed as a `LogController` instance rather than as fastify's own
+                // top-level `disableRequestLogging`, which is deprecated and warned
+                // about a line per process — one line per package in a CI run — for a
+                // flag whose replacement does exactly the same thing.
+                logController: new LogController({disableRequestLogging: true}),
                 ajv: {
                     customOptions: {
                         allErrors: true,
@@ -739,7 +791,19 @@ export default class Gateway extends Internal implements IGateway {
 
             this.#server.setErrorHandler(
                 (error: Record<string, unknown>, request: FastifyRequest, reply: FastifyReply) => {
-                    request.log.error({err: error}, 'gateway unhandled error');
+                    // A hook that refuses before the route runs (authentication, RBAC)
+                    // never reaches the handler that resolves `expect` for `$meta`, so
+                    // the declaration is read from the request body here: the caller
+                    // asked for this failure and the error stream is for the ones it did
+                    // not ask for.
+                    const expected = this.#config.expectedErrors
+                        ? (request.body as {expect?: string | string[]} | undefined)?.expect
+                        : undefined;
+                    if (isExpectedError(error.type as string | undefined, expected)) {
+                        request.log.debug?.({err: error}, 'gateway expected error');
+                    } else {
+                        request.log.error({err: error}, 'gateway unhandled error');
+                    }
                     return reply.status((error as {statusCode?: number}).statusCode || 500).send({
                         jsonrpc: '2.0',
                         id: (request.body as {id?: unknown})?.id,

package/src/Log.ts

@@ -1,7 +1,8 @@
 import {withProgress} from '@feasibleone/blong-lib';
 import {Internal, type ICallLog, type ILog, type ILogger} from '@feasibleone/blong/types';
 import {createCallChannel} from '@feasibleone/semantic-log/capability';
-import {pino, type Logger, type LoggerOptions} from 'pino';
+import {callerSite, messageMatches} from '@feasibleone/semantic-log/emitter';
+import {pino, type Logger, type LoggerOptions, type TransportSingleOptions} from 'pino';
 import {monotonicFactory} from 'ulidx';
 import {callRecord, configureCallTrace, type CallTraceConfig} from './callTrace.ts';
 import type {CacacheTransportOptions} from './pino-cacache.js';
@@ -18,6 +19,23 @@ export interface LogConfig extends LoggerOptions {
     impl?: string;
     /** The semantic implementation's store. Not a pino option; stripped below. */
     cache?: unknown;
+    /**
+     * Put the `semlog://` reference group at the end of a human line — the
+     * pretty printer renders it, and this implementation has no other way to
+     * show one. Not a pino option; stripped below. On by default, off in a
+     * released process (`log.refs: false`), whose stdout nobody resolves a
+     * reference from.
+     */
+    refs?: boolean;
+    /**
+     * The messages whose caller is worth naming — `log.callSite`.
+     *
+     * Each entry is a regular expression source, so a substring (`unauthorized`, `adapter.ready`)
+     * is written as one and `['']` names the caller of every record. The semantic implementation
+     * reads the same list, so one entry places an unexplained line whichever logger a process
+     * chose, and nothing is captured for a message that matches none of the patterns.
+     */
+    callSite?: string | string[];
     /**
      * The call channel: whether a flow's calls are recorded, and whether they
      * are shown.
@@ -34,6 +52,14 @@ export interface LogConfig extends LoggerOptions {
 
 const ulid = monotonicFactory();
 
+/**
+ * The files a pino record's stack runs through before it reaches the call site.
+ *
+ * This module's own frames — the hook that asks for the site, since it runs inside pino's write
+ * path — and pino's, which are between that hook and the caller. Everything else is the call site.
+ */
+const PINO_FRAME = /[\\/](?:Log|semantic-log|pino|thread-stream)[\\/.]/;
+
 const ignoreArgPatterns = [
     '--tls-cipher-list=',
     '--v8-pool-size=',
@@ -73,39 +99,37 @@ const WORKER_OPTS = {
     ),
 };
 
-const PRETTY_TRANSPORT = {
-    target: './pino-pretty.mjs',
+const PRETTY_TRANSPORT = (refs?: boolean): TransportSingleOptions<Record<string, unknown>> => ({
+    target: './pino-pretty.mjs' as const,
     worker: WORKER_OPTS,
     options: {
         singleLine: true,
         colorizeObjects: true,
-        ignore: [
-            'context',
-            'prefix',
-            'pid',
-            'hostname',
-            '$meta.mtid',
-            '$meta.method',
-            'req',
-            'res',
-            'config',
-            'configBase',
-            'id',
-        ].join(','),
+        // The reference group is the printer's to render, so the switch travels
+        // with the transport the process chose.
+        refs,
+        // No `ignore` here: what the header already printed is the printer's own knowledge, and it
+        // lives beside the header that prints it (`pino-pretty.ts` → `ALREADY_IN_HEADER`). It used to
+        // be a list in this file, and an entry per envelope member meant the emptied
+        // `{"$meta":{}}` was printed instead of the two members it had dropped.
     },
-};
+});
 
 export default class Log extends Internal implements ILog {
     #logger: Logger;
     #config: LogConfig = {
         level: 'info',
-        transport: PRETTY_TRANSPORT,
+        transport: PRETTY_TRANSPORT(),
     };
 
     public constructor(config: LogConfig) {
         super();
         this.merge(this.#config, config);
         configureCallTrace(this.#config.calls);
+        // The printer renders the reference group, so the switch has to be known
+        // before the transport is built — the default above is there for a caller
+        // that never merges a config at all.
+        this.#config.transport = PRETTY_TRANSPORT(this.#config.refs);
 
         // Inject a monotonic ULID `id` into every log entry before it reaches any transport
 
@@ -115,7 +139,7 @@ export default class Log extends Internal implements ILog {
             const cacacheOptions = this.#config.cacache;
             this.#config.transport = {
                 targets: [
-                    PRETTY_TRANSPORT,
+                    PRETTY_TRANSPORT(this.#config.refs),
                     {
                         target: './pino-cacache.mjs',
                         worker: WORKER_OPTS,
@@ -134,6 +158,8 @@ export default class Log extends Internal implements ILog {
             cacache: _cacacheConfig,
             impl: _impl,
             cache: _semanticCache,
+            refs: _refs,
+            callSite: _callSite,
             calls: _calls,
             ...pinoConfig
         } = this.#config;
@@ -158,6 +184,38 @@ export default class Log extends Internal implements ILog {
         bindings: object,
     ): ReturnType<ILog['logger']> {
         const child = this.#logger.child(bindings, {level});
+        // The caller of the messages `log.callSite` names. pino has no hook that sees a message:
+        // `logMethod` is not inherited by a child, and a formatter is handed the fields without
+        // the text — so the match is made here, where the framework builds the logger it hands
+        // out, and every component's logger is covered by construction.
+        const locations =
+            typeof this.#config.callSite === 'string'
+                ? [this.#config.callSite]
+                : this.#config.callSite;
+        const bind = <A extends unknown[]>(
+            method: (...args: A) => void,
+        ): ((...args: A) => void) => {
+            if (!locations?.length) return method;
+            return (...args: A) => {
+                const call = [...args] as unknown[];
+                // The message is whichever argument is text: pino's order is `(bag, message)` or
+                // `(message, values)`, and the text is the part both of those have.
+                const message = [...call].reverse().find(arg => typeof arg === 'string');
+                if (message !== undefined && messageMatches(locations, message)) {
+                    // The site has to sit where pino looks for fields, which is the *first*
+                    // argument: an object after the message is a printf value, and pino drops one
+                    // the message has no placeholder left for. A call that already leads with a
+                    // bag keeps it, and the site joins it.
+                    const leading = call[0];
+                    if (leading && typeof leading === 'object' && !Array.isArray(leading)) {
+                        call[0] = {...(leading as object), site: callerSite(PINO_FRAME)};
+                    } else {
+                        call.unshift({site: callerSite(PINO_FRAME)});
+                    }
+                }
+                return (method as (...args: unknown[]) => void)(...call);
+            };
+        };
         const result: ILogger = {
             trace: undefined,
             debug: undefined,
@@ -168,17 +226,17 @@ export default class Log extends Internal implements ILog {
         };
         switch (level) {
             case 'trace':
-                result.trace = child.trace.bind(child);
+                result.trace = bind(child.trace.bind(child));
             case 'debug':
-                result.debug = child.debug.bind(child);
+                result.debug = bind(child.debug.bind(child));
             case 'info':
-                result.info = child.info.bind(child);
+                result.info = bind(child.info.bind(child));
             case 'warn':
-                result.warn = child.warn.bind(child);
+                result.warn = bind(child.warn.bind(child));
             case 'error':
-                result.error = child.error.bind(child);
+                result.error = bind(child.error.bind(child));
             case 'fatal':
-                result.fatal = child.fatal.bind(child);
+                result.fatal = bind(child.fatal.bind(child));
         }
         return {
             ...result,

package/src/Registry.ts

@@ -87,6 +87,14 @@ export default class Registry extends Internal implements IRegistry {
     #apiSchema: IApiSchema;
     #platform: IPlatformApi;
     #config: IConfig = {};
+    /**
+     * What each realm declares about itself, keyed by realm name.
+     *
+     * Handed over by {@link setRealmConfig} rather than read from this component's config, because
+     * a realm loads *after* the config of the realm whose child it is has merged: a copy taken while
+     * any config is built holds the realms loaded up to that moment and nothing more (D-433).
+     */
+    #realmConfig: Record<string, unknown> = {};
     #attachCheckpoint?: (meta: IMeta) => void;
 
     #manifest: IManifest | undefined;
@@ -518,9 +526,23 @@ export default class Registry extends Internal implements IRegistry {
             folders: disk?.folders ?? [],
             files: disk?.files ?? [],
             layerFiles: disk?.layerFiles ?? [],
+            // What each realm declares about itself, keyed by realm name: the loader records the
+            // slice and hands the map here, so a planner reads a realm's own `k8sRealmRole` rather
+            // than inferring it from the ports the realm happens to own (D-433).
+            realmConfig: this.#realmConfig,
         };
     }
 
+    /**
+     * Publish the per-realm config map.
+     *
+     * The map is taken by reference, and the loader keeps adding to it as realms load, so a caller
+     * that asks later sees the realms that were not loaded yet when the registry was created.
+     */
+    public setRealmConfig(realmConfig: Record<string, unknown>): void {
+        this.#realmConfig = realmConfig;
+    }
+
     public async stop(): Promise<IRegistry> {
         if (this.#stopped) return this;
         await this.#watch?.stop();

package/src/ResolutionK8s.ts

@@ -0,0 +1,71 @@
+import {Internal, type IManifest} from '@feasibleone/blong/types';
+
+import type {IResolution} from './Resolution.ts';
+
+interface IConfig {
+    /** The port `RpcServer` serves an orchestrator namespace on. */
+    portRpc: number;
+    /** The gateway port (unused for namespace resolution, kept for symmetry). */
+    portGateway: number;
+    /** The cluster DNS domain the Service suffix is built from. */
+    domain: string;
+    /** The namespace the suite is deployed into. */
+    namespace: string;
+}
+
+/**
+ * Kubernetes resolution: a service id resolves to the Service of the same name
+ * in the suite's namespace, instead of to a local port.
+ *
+ * `GatewayCodec` asks for `rpc-<namespace>` and `RpcServer` serves namespaces on
+ * the RPC port, so the `rpc-` prefix is stripped and the port is the
+ * namespace's, not the gateway's. `blong-kustomize` generates one Service per
+ * orchestrator namespace with that name, which is what makes the namespace the
+ * suite's abstract name for a process (see the PRD and the deployment docs).
+ *
+ * The namespace comes from config, then from `BLONG_NAMESPACE` /
+ * `KUBERNETES_NAMESPACE` — the downward API that pins a pod to its own
+ * namespace — and only then falls back to `default`.
+ *
+ * Pinned down with `resolution.impl: kubernetes` in the suite's config; the
+ * loader then loads this module instead of `ResolutionLocal` (see the
+ * `resolution` component in `load.ts`).
+ */
+export default class ResolutionK8s extends Internal implements IResolution {
+    #config: IConfig = {
+        portRpc: 8091,
+        portGateway: 8080,
+        domain: 'svc.cluster.local',
+        namespace: '',
+    };
+    #manifest: IManifest | undefined;
+
+    public constructor(config: IConfig, {manifest}: {manifest?: IManifest} = {}) {
+        super();
+        this.merge(this.#config, config);
+        this.#manifest = manifest;
+        if (!this.#config.namespace) {
+            const env = (globalThis as {process?: {env?: Record<string, string | undefined>}})
+                .process?.env;
+            this.#config.namespace = env?.BLONG_NAMESPACE ?? env?.KUBERNETES_NAMESPACE ?? 'default';
+        }
+    }
+
+    public async resolve(service: string): ReturnType<IResolution['resolve']> {
+        const isRpc = service.startsWith('rpc-');
+        const name = service.replace(/^rpc-/, '');
+        // The manifest port is deliberately NOT preferred here: a random dev port
+        // would point at a Service port the cluster does not publish. In the
+        // cluster the Service is the address, and its port is the component's.
+        return {
+            hostname: `${name}.${this.#config.namespace}.${this.#config.domain}`,
+            port: `${isRpc ? this.#config.portRpc : this.#config.portGateway}`,
+        };
+    }
+
+    public announce(): void {}
+
+    public async start(): Promise<void> {}
+
+    public async stop(): Promise<void> {}
+}

package/src/SemanticLog.test.ts

@@ -127,12 +127,22 @@ t.test('the argument adapter lifts the framework envelope into the record slots'
     t.equal(envelope.fields.operation, 'subject.subjectModelList');
     t.equal(envelope.fields.messageId, 'request');
     t.equal(envelope.fields.extra, 1);
-    t.equal(
-        '$meta' in envelope.fields,
-        true,
-        'the envelope itself is carried through, not dropped',
+    t.same(
+        envelope.fields.$meta,
+        undefined,
+        'and the envelope is not repeated beside the slots that hold its members',
     );
 
+    // A member the slots did not take is still carried, which is what "a reader still sees the
+    // request it came from" means, and why the envelope is pruned rather than dropped.
+    const rest = toLogCall([{$meta: {mtid: 'event', method: 'a.b', expect: 'notFound'}}]);
+    t.same(rest.fields.$meta, {expect: 'notFound'}, 'the rest of the envelope stays');
+
+    // And a member that could not become a slot stays too, rather than vanishing: the header shows
+    // a `method` only when it is text, so a non-string one is nowhere else on the record.
+    const odd = toLogCall([{$meta: {mtid: 1, method: 2}}]);
+    t.same(odd.fields.$meta, {mtid: 1, method: 2}, 'a member that did not become a slot is kept');
+
     // The envelope wins over the same keys on the bag: it is the structured source.
     const overridden = toLogCall([
         {

package/src/SemanticLog.ts

@@ -80,6 +80,23 @@ export interface SemanticLogConfig {
     format?: Format;
     /** ANSI colour in human format. Opt-in, as the emitter's own option is. */
     color?: boolean;
+    /**
+     * Put the `semlog://` reference group at the end of a human line. On by
+     * default, off in a released process (`log.refs: false`): a reference is a
+     * development aid, and resolving one needs a store open beside the terminal.
+     */
+    refs?: boolean;
+    /**
+     * The messages whose caller is worth naming — `log.callSite`.
+     *
+     * Each entry is a regular expression source, so a substring (`unauthorized`, `adapter.ready`)
+     * is written as one and `['']` names the caller of every record. A list rather than a switch,
+     * because the interesting line is usually one particular message: a record whose text matches
+     * none of the patterns is emitted exactly as it was, with no stack captured for it. A call in
+     * pino's printf shape is always named, whatever this says — the repository writes no such
+     * call, so one arriving is a dependency's.
+     */
+    callSite?: string | string[];
     /** The service name carried on every record; the framework's own by default. */
     service?: string;
     /**
@@ -139,6 +156,8 @@ export default class SemanticLog extends Internal implements ILog {
             level: thresholdOf(merged.level),
             format: merged.format,
             color: merged.color,
+            refs: merged.refs,
+            callSite: merged.callSite,
             cache: merged.cache,
             // Only the printing switch is the base's business; `enabled`/`off` are
             // the gate's, and are read where a flow is minted.
@@ -150,9 +169,10 @@ export default class SemanticLog extends Internal implements ILog {
             openCluster: async () =>
                 (await import('@feasibleone/semantic-log/service')).openCluster,
             // The framework's envelope, on the record and on the call site's own
-            // arguments: `{$meta: {mtid, method}}` is what its readers match on.
+            // arguments: `{$meta: {mtid, method}}` is what its readers match on — and the
+            // caller's frame, when the log configuration asks for it.
             envelope: ({leg, phase}) => callRecord(leg, phase),
-            translate: args => toLogCall(args),
+            translate: args => toLogCall(args, {callSite: merged.callSite}),
         });
     }