@feasibleone/blong-gogo 1.36.0 → 1.38.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [1.38.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.37.0...blong-gogo-v1.38.0) (2026-09-29)
+
+
+### Features
+
+* improve storybook scaffold ([cc66ab4](https://github.com/feasibleone/blong/commit/cc66ab480eb9af2def562873cac12d06591c0de4))
+
+
+### Bug Fixes
+
+* failed tests ([108caf5](https://github.com/feasibleone/blong/commit/108caf5f3e92151f8b929115e0a8f6b2acdd3d23))
+* gaps ([19beb7d](https://github.com/feasibleone/blong/commit/19beb7d191e853c8182409256c97af7a1e413d57))
+
+## [1.37.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.36.0...blong-gogo-v1.37.0) (2026-09-26)
+
+
+### Features
+
+* progress points in test reports ([fb73036](https://github.com/feasibleone/blong/commit/fb730360877eb371ab3d1603ae7bf35976c170dc))
+
+
+### Bug Fixes
+
+* chain dynamic import ([7db222f](https://github.com/feasibleone/blong/commit/7db222f0a6469b624fa1935027f63b0593585ee6))
+* misc CI failures ([950289d](https://github.com/feasibleone/blong/commit/950289d65e6187d10658dd0fd76361bd4d3d56e8))
+
 ## [1.36.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.35.0...blong-gogo-v1.36.0) (2026-09-24)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feasibleone/blong-gogo",
-  "version": "1.36.0",
+  "version": "1.38.0",
   "repository": {
     "url": "git+https://github.com/feasibleone/blong.git"
   },
@@ -20,7 +20,6 @@
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^12.1.0",
-    "@modelcontextprotocol/sdk": "^1.0.0",
     "@aws-sdk/client-s3": "^3.1037.0",
     "@fastify/basic-auth": "^6.2.0",
     "@fastify/bearer-auth": "^10.1.2",
@@ -33,6 +32,7 @@
     "@fastify/swagger-ui": "^5.2.5",
     "@fastify/type-provider-typebox": "^6.1.0",
     "@feasibleone/blong": "^1.0.0",
+    "@feasibleone/blong-allure": "^1.0.0",
     "@feasibleone/blong-chain": "^1.0.0",
     "@feasibleone/blong-config": "^1.0.0",
     "@feasibleone/blong-lib": "^1.0.0",
@@ -41,6 +41,7 @@
     "@feasibleone/semantic-log": "^1.0.0",
     "@keycloak/keycloak-admin-client": "^26.6.2",
     "@kubernetes/client-node": "^1.4.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
     "@octokit/rest": "^22.0.1",
     "@sinclair/typebox-codegen": "^0.11.1",
     "@slack/webhook": "^7.0.7",
@@ -91,7 +92,7 @@
     "tap": "^21.6.3",
     "typescript": "^6.0.3",
     "vite": "^8.2.1",
-    "@feasibleone/blong-dev": "1.6.0"
+    "@feasibleone/blong-dev": "1.7.1"
   },
   "scripts": {
     "browser-check": "node scripts/browser-compat-check.mjs",

package/src/ConfigRuntime.test.ts

@@ -17,7 +17,7 @@
 
 import {test} from 'tap';
 
-import {createConfigProxy, deepDiff} from './ConfigRuntime.ts';
+import ConfigRuntime, {createConfigProxy, deepDiff} from './ConfigRuntime.ts';
 
 // ---------------------------------------------------------------------------
 // deepDiff
@@ -325,3 +325,81 @@ test('factory phase guard — exitConfigFactoryPhase returns empty array in thro
     const errors = exitConfig();
     t.equal(errors.length, 0, 'no errors collected in throw mode (they were thrown)');
 });
+
+// ---------------------------------------------------------------------------
+// liveLayerConfig — the config a handler closure receives
+// ---------------------------------------------------------------------------
+
+/**
+ * The merge input is a getter over a `let`, so a "reload" in these tests replaces
+ * the object the next merge sees — the way `ConfigRuntime.#rawSnapshot` is
+ * replaced while the version moves with it.
+ */
+
+test('liveLayerConfig — a handler sees a reloaded value', async t => {
+    let source: Record<string, unknown> = {timeout: 5, db: {host: 'a', port: 1}};
+    let version = 0;
+    const config = ConfigRuntime.liveLayerConfig(
+        () => source,
+        () => version,
+    ) as {
+        timeout: number;
+        db: {host: string};
+    };
+
+    t.equal(config.timeout, 5, 'the value at assembly time');
+
+    source = {timeout: 9, db: {host: 'b', port: 2}};
+    version += 1;
+
+    t.equal(config.timeout, 9, 'a leaf read after the reload is fresh');
+    t.end();
+});
+
+test('liveLayerConfig — an intermediate node destructured at startup stays live', async t => {
+    let source: Record<string, unknown> = {db: {host: 'a'}};
+    let version = 0;
+    const config = ConfigRuntime.liveLayerConfig(
+        () => source,
+        () => version,
+    ) as {
+        db: {host: string};
+    };
+
+    // The pattern the config rationale calls safe: the node is taken once, its
+    // leaves are read at call time.
+    const {db} = config;
+    t.equal(db.host, 'a', 'the leaf before the reload');
+    t.equal(config.db, db, 'and the node reference is stable');
+
+    source = {db: {host: 'b'}};
+    version += 1;
+
+    t.equal(db.host, 'b', 'the same node reads the reloaded leaf');
+    t.end();
+});
+
+test('liveLayerConfig — an unchanged version does not re-merge', async t => {
+    let merges = 0;
+    let version = 3;
+    const config = ConfigRuntime.liveLayerConfig(
+        () => {
+            merges += 1;
+            return {timeout: 5};
+        },
+        () => version,
+    ) as {timeout: number};
+
+    t.equal(merges, 1, 'assembled once');
+    void config.timeout;
+    void config.timeout;
+    t.equal(merges, 1, 'reads at the same version do not merge again');
+
+    version += 1;
+    void config.timeout;
+    t.equal(merges, 2, 'a new version merges once');
+
+    void config.timeout;
+    t.equal(merges, 2, 'and then caches again');
+    t.end();
+});

package/src/ConfigRuntime.ts

@@ -43,6 +43,17 @@ import merge from 'ut-function.merge';
  */
 export function createConfigProxy<T extends object>(
     store: T,
+    options: {
+        /**
+         * Called before every read, at every level of the proxy.
+         *
+         * A caller whose backing store has to be re-read from somewhere charges
+         * the check here, so a node destructured once at startup (a handler's
+         * `config.db`, say) refreshes on its own reads rather than only when the
+         * root is touched.
+         */
+        beforeRead?: () => void;
+    } = {},
 ): {
     proxy: T;
     update: (next: T) => void;
@@ -131,6 +142,7 @@ export function createConfigProxy<T extends object>(
 
         const pathProxy = new Proxy({} as T, {
             get(_target, prop) {
+                options.beforeRead?.();
                 const container = getNode(path);
                 const val = container == null ? undefined : Reflect.get(container as object, prop);
                 if (
@@ -166,16 +178,19 @@ export function createConfigProxy<T extends object>(
                 return Reflect.set(container as object, prop, value);
             },
             has(_target, prop) {
+                options.beforeRead?.();
                 const container = getNode(path);
                 if (container == null) return false;
                 return Reflect.has(container as object, prop);
             },
             ownKeys() {
+                options.beforeRead?.();
                 const container = getNode(path);
                 if (container == null) return [];
                 return Reflect.ownKeys(container as object);
             },
             getOwnPropertyDescriptor(_target, prop) {
+                options.beforeRead?.();
                 const container = getNode(path);
                 if (container == null) return undefined;
                 return Object.getOwnPropertyDescriptor(container as object, prop);
@@ -265,6 +280,7 @@ export default class ConfigRuntime implements IConfigRuntime {
     #rawSnapshot: object = {};
     #proxy: object;
     #updateProxy: (next: object) => void;
+    #version = 0;
 
     readonly enterConfig: (mode?: FactoryPhaseMode) => void;
     readonly exitConfig: () => Error[];
@@ -292,6 +308,11 @@ export default class ConfigRuntime implements IConfigRuntime {
         return this.#rawSnapshot;
     }
 
+    /** Bumped whenever the effective config is replaced; see `IConfigRuntime`. */
+    public get version(): number {
+        return this.#version;
+    }
+
     private mergeConfigs(blongConfig: object): object {
         const loaded = loadBlong(blongConfig);
         return merge({}, this.#baseConfig, ...this.#configs, loaded);
@@ -305,6 +326,7 @@ export default class ConfigRuntime implements IConfigRuntime {
     public async load(params: object = {}): Promise<object> {
         const loaded = this.mergeConfigs({config: {suite: this.#suite}, ...params});
         this.#rawSnapshot = loaded;
+        this.#version += 1;
         this.#updateProxy(loaded);
         return this.#proxy;
     }
@@ -324,6 +346,7 @@ export default class ConfigRuntime implements IConfigRuntime {
         // Only do work when something actually changed
         if (diff.size > 0) {
             this.#rawSnapshot = next;
+            this.#version += 1;
             this.#updateProxy(next);
             for (const subscriber of this.#subscribers) {
                 try {
@@ -374,6 +397,44 @@ export default class ConfigRuntime implements IConfigRuntime {
         return merge({}, moduleConfigSlice, portNamespaceConfig) as Record<string, unknown>;
     }
 
+    /**
+     * A live view of one component's config slice, for a handler closure.
+     *
+     * `mergeLayerConfig` copies, so a handler that reads `config.timeout` inside
+     * its function keeps whatever the value was when the layer was assembled,
+     * however often the config is reloaded (T-159).  This hands the closure a
+     * proxy over the merged slice instead: `mergeOnce` is called again when
+     * `version()` reports a new runtime version, and the readers see the new
+     * values — the handler's own `config` argument, and any intermediate node it
+     * destructured at startup, because the nodes are the path proxies of a
+     * `createConfigProxy` instance whose backing is replaced rather than a copy
+     * of it.
+     *
+     * The merge runs at most once per runtime version, so a hot path that reads a
+     * config leaf pays a property lookup and an integer compare, not a merge.
+     */
+    static liveLayerConfig(
+        mergeOnce: () => Record<string, unknown>,
+        version: () => number,
+    ): Record<string, unknown> {
+        let seen = version();
+        const refresh = (): void => {
+            const current = version();
+            if (current === seen) return;
+            seen = current;
+            live.update(mergeOnce());
+        };
+        // The hook is passed to the proxy instance itself, so a node the closure
+        // destructured at startup refreshes on its own reads — reading through
+        // the root would leave it stale.
+        //
+        // This instance's factory-phase guard is never armed: layer assembly arms
+        // the *runtime's* proxy, and a handler has always been free to destructure
+        // a leaf from its `config` argument at factory time.
+        const live = createConfigProxy(mergeOnce(), {beforeRead: refresh});
+        return live.proxy as Record<string, unknown>;
+    }
+
     /**
      * Merge activation-scoped config for an adapter.
      *

package/src/Gateway.ts

@@ -462,7 +462,7 @@ export default class Gateway extends Internal implements IGateway {
                                                           Type.Number(),
                                                       ]),
                                                       result: value.result,
-                                                      checkpoints: Type.Optional(
+                                                      progress: Type.Optional(
                                                           Type.Array(Type.Any()),
                                                       ),
                                                   }),
@@ -643,10 +643,8 @@ export default class Gateway extends Internal implements IGateway {
                                 jsonrpc: '2.0',
                                 id,
                                 result,
-                                ...((resultMeta as {checkpoints?: unknown[]})?.checkpoints
-                                    ?.length && {
-                                    checkpoints: (resultMeta as {checkpoints?: unknown[]})
-                                        .checkpoints,
+                                ...((resultMeta as {progress?: unknown[]})?.progress?.length && {
+                                    progress: (resultMeta as {progress?: unknown[]}).progress,
                                 }),
                             };
                         }

package/src/Registry.ts

@@ -396,8 +396,8 @@ export default class Registry extends Internal implements IRegistry {
             // carries only config/handler/errors/schema/gateway/apiSchema. And
             // the lib proxy returns an attached function **raw**, so `this`
             // inside it is this object — not the port, which is only bound in the
-            // proxy's not-yet-attached fallback path. Without these keys a
-            // library function therefore cannot reach the platform or registry at
+            // proxy's not-yet-attached fallback path. Without these keys an
+            // injected library function therefore cannot reach the platform or registry at
             // all, which is what a library needs to be reusable outside a
             // request.
             platform: this.#platform,

package/src/RpcClient.ts

@@ -195,9 +195,9 @@ export default class RpcClientImpl extends RemoteImpl implements IRpcClient {
                         const result = await decode(body.result);
                         if (/\.service\.get$/.test(method!))
                             Object.assign((result as Record<string, unknown>[])[0], requestParams);
-                        if ((body as unknown as {checkpoints?: unknown[]}).checkpoints?.length) {
-                            ((callerMeta as {checkpoints?: unknown[]}).checkpoints ??= []).push(
-                                ...(body as unknown as {checkpoints: unknown[]}).checkpoints,
+                        if ((body as unknown as {progress?: unknown[]}).progress?.length) {
+                            ((callerMeta as {progress?: unknown[]}).progress ??= []).push(
+                                ...(body as unknown as {progress: unknown[]}).progress,
                             );
                         }
                         return result;

package/src/RpcServer.ts

@@ -85,8 +85,8 @@ export default class RpcServer extends Internal implements IRpcServer {
                 jsonrpc: '2.0',
                 id,
                 result,
-                ...((newMeta as {checkpoints?: unknown[]}).checkpoints?.length && {
-                    checkpoints: (newMeta as {checkpoints?: unknown[]}).checkpoints,
+                ...((newMeta as {progress?: unknown[]}).progress?.length && {
+                    progress: (newMeta as {progress?: unknown[]}).progress,
                 }),
             };
         }

package/src/SemanticLog.test.ts

@@ -324,7 +324,17 @@ t.test('every level is bound, and emits at its own level', async t => {
     // `fatal` is written synchronously, so it is staged rather than stored: it is
     // the one level whose record survives an exit that drains no I/O, and it
     // reaches the store on the next open. The other five take the queued path.
-    t.same(levels.sort(), ['debug', 'error', 'info', 'trace', 'warn']);
+    //
+    // An error appears twice, and that is the tenant model rather than a duplicate
+    // write: every record is stored once under its **shape** (keyed by the shape
+    // reference, standing for every occurrence of it), and a record whose denoise
+    // would hide something — an error, or one that withheld a payload — is stored
+    // under its own id as well, because that occurrence is what is being diagnosed.
+    t.same(
+        levels.sort(),
+        ['debug', 'error', 'error', 'info', 'trace', 'warn'],
+        'every level is stored, and the error under its shape and its own id',
+    );
     const staged = readFileSync(cachePaths.sidecarFile(dir), 'utf8')
         .trim()
         .split('\n')
@@ -332,8 +342,8 @@ t.test('every level is bound, and emits at its own level', async t => {
         .map(entry => JSON.parse(entry.json) as {levelName: string});
     t.same(
         staged.map(entry => entry.levelName),
-        ['fatal'],
-        'the fatal record is staged, not stored',
+        ['fatal', 'fatal'],
+        'the fatal record is staged under its shape and its own id, and never stored',
     );
     await cache.close();
 });

package/src/SemanticLog.ts

@@ -85,7 +85,7 @@ export interface SemanticLogConfig {
     /**
      * Retain records on disk so a printed reference resolves later. The directory is
      * the framework's log cache, which the pino transport also writes — one store,
-     * shared, so a `semantic-log://record/<id>` reference resolves whichever
+     * shared, so a `semlog://r/<id>` reference resolves whichever
      * implementation emitted it.
      */
     cache?: RetentionOptions;

package/src/Watch.test.ts

@@ -1,6 +1,13 @@
 import {test} from 'tap';
 
-import {affectedNamespaces} from './Watch.ts';
+import type {ConfigDiff} from '@feasibleone/blong/types';
+
+import {
+    affectedNamespaces,
+    applyConfigReload,
+    type IReloadablePort,
+    type IReloadRegistry,
+} from './Watch.ts';
 
 // ---------------------------------------------------------------------------
 // affectedNamespaces
@@ -49,3 +56,145 @@ test('affectedNamespaces — partial name prefix does not match', async t => {
     const affected = affectedNamespaces(diff, ports);
     t.equal(affected.size, 0, 'partial-name prefix should not match');
 });
+
+// ---------------------------------------------------------------------------
+// applyConfigReload — what a reload does to the ports it affects
+// ---------------------------------------------------------------------------
+
+interface FakePort extends IReloadablePort {
+    /** Every lifecycle call, in order — the assertion surface. */
+    calls: string[];
+    /** The arguments `configChanged` was handed, once per call. */
+    changed: Array<{diff: ConfigDiff; next: unknown; prev: unknown}>;
+}
+
+function fakePort(id: string, options: {configChanged?: boolean; throws?: boolean} = {}): FakePort {
+    const calls: string[] = [];
+    const changed: FakePort['changed'] = [];
+    const port: FakePort = {
+        calls,
+        changed,
+        async stop() {
+            calls.push('stop');
+        },
+        async start() {
+            calls.push('start');
+        },
+        async ready() {
+            calls.push('ready');
+        },
+    };
+    if (options.configChanged !== false) {
+        port.configChanged = async (diff, next, prev) => {
+            calls.push('configChanged');
+            changed.push({diff, next, prev});
+            if (options.throws) throw new Error(`${id}: reload failed`);
+        };
+    }
+    return port;
+}
+
+function fakeRegistry(ports: Record<string, FakePort>): IReloadRegistry {
+    return {
+        ports: {keys: () => Object.keys(ports)},
+        async getPort(id) {
+            return ports[id];
+        },
+        async createPort(id) {
+            return ports[id];
+        },
+    };
+}
+
+const reloadDiff: ConfigDiff = new Map([['payment.adapter.db.host', {prev: 'a', next: 'b'}]]);
+
+test('applyConfigReload — the affected port is asked to reconfigure itself', async t => {
+    const port = fakePort('payment.adapter.db');
+    const registry = fakeRegistry({'payment.adapter.db': port});
+    const next = {payment: {adapter: {db: {host: 'b'}}}};
+
+    const reloaded = await applyConfigReload(
+        registry,
+        affectedNamespaces(reloadDiff, registry.ports.keys()),
+        reloadDiff,
+        next,
+        {payment: {adapter: {db: {host: 'a'}}}},
+        {},
+    );
+
+    t.equal(reloaded, 1, 'one port reached');
+    t.equal(port.calls.join(','), 'configChanged', 'and reconfigured, not restarted');
+    t.equal(port.changed.length, 1, 'configChanged called once');
+    t.equal(port.changed[0]?.diff, reloadDiff, 'handed the diff');
+    t.equal(port.changed[0]?.next, next, 'and the new effective config');
+    t.end();
+});
+
+test('applyConfigReload — an unrelated key leaves a port running', async t => {
+    const affectedPort = fakePort('payment.adapter.db');
+    const untouched = fakePort('audit.adapter.kafka');
+    const registry = fakeRegistry({
+        'payment.adapter.db': affectedPort,
+        'audit.adapter.kafka': untouched,
+    });
+
+    const reloaded = await applyConfigReload(
+        registry,
+        affectedNamespaces(reloadDiff, registry.ports.keys()),
+        reloadDiff,
+        {payment: {adapter: {db: {host: 'b'}}}},
+        {},
+        {},
+    );
+
+    t.equal(reloaded, 1, 'only the affected port was reached');
+    t.equal(untouched.calls.length, 0, 'the unrelated port was not stopped or started');
+    t.end();
+});
+
+test('applyConfigReload — a port without configChanged is stopped and started again', async t => {
+    const port = fakePort('payment.adapter.db', {configChanged: false});
+    const registry = fakeRegistry({'payment.adapter.db': port});
+    const override = {marker: true};
+
+    await applyConfigReload(
+        registry,
+        affectedNamespaces(reloadDiff, registry.ports.keys()),
+        reloadDiff,
+        {},
+        {},
+        override,
+    );
+
+    t.equal(port.calls.join(','), 'stop,start,ready', 'the fallback restarts the port in order');
+    t.end();
+});
+
+test('applyConfigReload — a failing port does not stop the ones behind it', async t => {
+    const failing = fakePort('payment.adapter.db', {throws: true});
+    const healthy = fakePort('user.adapter.db');
+    const registry = fakeRegistry({
+        'payment.adapter.db': failing,
+        'user.adapter.db': healthy,
+    });
+    const diff: ConfigDiff = new Map([
+        ['payment.adapter.db.host', {prev: 'a', next: 'b'}],
+        ['user.adapter.db.host', {prev: 'a', next: 'b'}],
+    ]);
+    const errors: unknown[] = [];
+
+    const reloaded = await applyConfigReload(
+        registry,
+        affectedNamespaces(diff, registry.ports.keys()),
+        diff,
+        {},
+        {},
+        {},
+        error => errors.push(error),
+    );
+
+    t.equal(reloaded, 2, 'both ports were reached');
+    t.equal(healthy.calls.join(','), 'configChanged', 'the second port still reloaded');
+    t.equal(errors.length, 1, 'the failure was reported');
+    t.end();
+});