@feasibleone/blong-gogo 1.37.0 → 1.38.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feasibleone/blong-gogo",
-  "version": "1.37.0",
+  "version": "1.38.0",
   "repository": {
     "url": "git+https://github.com/feasibleone/blong.git"
   },
@@ -92,7 +92,7 @@
     "tap": "^21.6.3",
     "typescript": "^6.0.3",
     "vite": "^8.2.1",
-    "@feasibleone/blong-dev": "1.7.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/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/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();
+});

package/src/Watch.ts

@@ -116,6 +116,73 @@ export function affectedNamespaces(diff: ConfigDiff, portNames: Iterable<string>
     return affected;
 }
 
+/**
+ * The port surface a config reload needs — `IRegistry`, narrowed so the reload
+ * loop can be driven with fakes (see `Watch.test.ts`).
+ */
+export interface IReloadablePort {
+    /** Zero-downtime path: the port reconfigures itself. */
+    configChanged?(diff: ConfigDiff, next: unknown, prev: unknown): Promise<void> | void;
+    stop(): Promise<void> | void;
+    start(configOverride: object): Promise<void> | void;
+    ready(): Promise<void> | void;
+}
+
+export interface IReloadRegistry {
+    ports: {keys: () => Iterable<string>};
+    getPort(id: string): Promise<IReloadablePort | undefined>;
+    createPort(id: string): Promise<IReloadablePort | undefined>;
+}
+
+/**
+ * Apply a config reload to the ports the diff affects.
+ *
+ * A port that implements `configChanged` is asked to reconfigure itself — the
+ * zero-downtime path, which is what keeps an in-flight request or an expensive
+ * connection alive. A port that does not is stopped and started again with the
+ * current override. A port the diff does not name is not touched at all, which is
+ * the property that makes a log-level change safe: it must not cost a database
+ * pool.
+ *
+ * Returns the number of ports the loop reached, and reports each one through
+ * `onReloaded` so the caller's progress view can follow it.
+ */
+export async function applyConfigReload(
+    registry: IReloadRegistry,
+    affected: Iterable<string>,
+    diff: ConfigDiff,
+    next: object,
+    prev: object,
+    configOverride: object,
+    onPortError: (error: unknown) => void = () => undefined,
+    onReloaded?: (done: number, total: number) => void,
+): Promise<number> {
+    const total = [...affected].length;
+    let reloaded = 0;
+    for (const portId of affected) {
+        const portInstance = await registry.getPort(portId);
+        if (portInstance) {
+            if (typeof portInstance.configChanged === 'function') {
+                try {
+                    await portInstance.configChanged(diff, next, prev);
+                } catch (error) {
+                    onPortError(error);
+                }
+            } else {
+                await portInstance.stop();
+                const fresh = await registry.createPort(portId);
+                if (fresh) {
+                    await fresh.start(configOverride);
+                    await fresh.ready();
+                }
+            }
+        }
+        reloaded += 1;
+        onReloaded?.(reloaded, total);
+    }
+    return reloaded;
+}
+
 export default class Watch extends Internal implements IWatch {
     #config: IConfig = {
         enabled: false,
@@ -566,28 +633,18 @@ export default class Watch extends Internal implements IWatch {
             this.log,
             'reload config',
             (async () => {
-                for (const portId of affected) {
-                    const portInstance = await registry.getPort(portId);
-                    if (portInstance) {
-                        if (typeof portInstance['configChanged'] === 'function') {
-                            // Adapter supports the configChanged hook — zero-downtime update
-                            try {
-                                await portInstance['configChanged'](diff, next, prev);
-                            } catch (error) {
-                                this.log?.error?.(error);
-                            }
-                        } else {
-                            // Fallback: stop and restart the port with the current configOverride
-                            await portInstance.stop();
-                            const fresh = await registry.createPort(portId);
-                            if (fresh) {
-                                await fresh.start(configOverride);
-                                await fresh.ready();
-                            }
-                        }
-                    }
-                    reloaded += 1;
-                }
+                await applyConfigReload(
+                    registry as unknown as IReloadRegistry,
+                    affected,
+                    diff,
+                    next,
+                    prev,
+                    configOverride,
+                    error => this.log?.error?.(error),
+                    done => {
+                        reloaded = done;
+                    },
+                );
             })(),
             {getProgress: () => ({done: reloaded, total: affected.size})},
         );

package/src/adapter/schema/knex/types.ts

@@ -96,9 +96,10 @@ export interface IResourceTableSpec {
  * Record-level (ACL) guard for a table.
  *
  * The ACL lives in `access_acl` rows — `(principalId, actionId, targetId,
- * targetKind, effect)` — where `principalId` is a user, role, unit or capability,
- * `targetId` is the guarded record (or a scope node) and `effect` is `allow` /
- * `deny` (deny always wins).
+ * targetKind, effect)` — where `principalId` is a user, role or unit (never a
+ * capability — the filter resolves the caller, their effective roles and their
+ * units), `targetId` is the guarded record (or a scope node) and `effect` is
+ * `allow` / `deny` (a deny beats a grant for a record inside a scope).
  */
 export interface IAclTableSpec {
     /**

package/src/adapter/server/acl.ts

@@ -13,10 +13,12 @@ import type {IAclAdapterConfig} from '../schema/knex/types.ts';
  * access_acl(aclId, principalId, actionId, targetId, targetKind, effect, isActive)
  * ```
  *
- * - `principalId` — a user, role, unit or capability resource id;
+ * - `principalId` — a user, role or unit resource id (never a capability: the
+ *   filter resolves the caller, their effective roles and their units);
  * - `actionId`      — the `access_action` resource of the guarded method;
  * - `targetId`      — the guarded record, or a **scope** node (`targetKind`);
- * - `effect`        — `allow` / `deny`, where **deny always wins**.
+ * - `effect`        — `allow` / `deny`; a deny beats a grant for a record inside
+ *   a scope, while a `record`-targeted deny on a record in no scope is ignored.
  *
  * Two things grant access, and both narrow RBAC (a method the caller's action
  * list does not contain is refused by the gateway before this ever runs):