@feasibleone/blong-gogo 1.35.0 → 1.37.0

package/src/checkpoint.test.ts

@@ -0,0 +1,265 @@
+/**
+ * The framework's two progress-point handles (PRD R11/R26).
+ *
+ * A checkpoint reports a moment; a decision selects a branch. That difference is the whole
+ * reason one is optional and the other is not, so it is pinned here: a checkpoint exists
+ * only where points are recorded, a decision exists in every mode, and both reach the log
+ * through the attachable vocabulary — degrading to nothing and to a plain selection where
+ * no emitter is attached, because a dispatch path must never reach the emitter's ambient
+ * scope (F-197).
+ */
+import type {
+    IMeta,
+    IProgressEntry,
+    IProgressPoint,
+    IProgressRegion,
+} from '@feasibleone/blong/types';
+import {
+    attachSemanticVocabulary,
+    detachSemanticVocabulary,
+} from '@feasibleone/semantic-log/attachable';
+import * as semantic from '@feasibleone/semantic-log/emitter';
+import t from 'tap';
+import {createAttachCheckpoint} from './checkpoint.ts';
+
+const MODES = ['production', 'debug', 'test'] as const;
+
+/** The points an invocation recorded, in the order it announced them. */
+const pointsOf = (progress: IProgressEntry[] | undefined): IProgressPoint[] =>
+    (progress ?? []).filter((entry): entry is IProgressPoint => entry.kind === 'point');
+
+/** The branches an invocation took, in the order it took them. */
+const regionsOf = (progress: IProgressEntry[] | undefined): IProgressRegion[] =>
+    (progress ?? []).filter((entry): entry is IProgressRegion => entry.kind === 'region');
+
+t.test('a branch is taken and its rationale kept, in every mode', t => {
+    for (const mode of MODES) {
+        const meta: IMeta = {};
+        createAttachCheckpoint(mode)(meta);
+        const result = meta.decide?.('rate-within-limit', {rate: 2}, [
+            {name: 'decline', when: values => (values.rate as number) > 1, run: () => 'declined'},
+            {name: 'accept', when: () => true, run: () => 'accepted'},
+        ]);
+        t.equal(result, 'declined', `${mode}: the branch is taken`);
+        t.same(
+            meta.progress,
+            [
+                {
+                    kind: 'region',
+                    discriminator: 'rate-within-limit',
+                    candidates: ['decline', 'accept'],
+                    chosen: 'decline',
+                    values: {rate: 2},
+                },
+            ],
+            `${mode}: and the invocation keeps which one it was`,
+        );
+    }
+    t.end();
+});
+
+t.test('a checkpoint exists only where points are recorded', t => {
+    const production: IMeta = {};
+    createAttachCheckpoint('production')(production);
+    t.notOk(
+        production.checkpoint,
+        'absent in production, which is what makes the `?.` call cost nothing',
+    );
+    t.ok(production.decide, 'while the branch helper is there, because a branch cannot be skipped');
+
+    const debug: IMeta = {};
+    createAttachCheckpoint('debug')(debug);
+    debug.checkpoint?.('total-calculated', {total: 200});
+    const [point] = pointsOf(debug.progress);
+    t.equal(debug.progress?.length, 1, 'recorded where points are');
+    t.equal(point?.name, 'total-calculated');
+    t.same(point?.data, {total: 200});
+    t.type(point?.timestamp, 'number', 'and stamped when it happened');
+    t.end();
+});
+
+t.test('a point announced inside a branch names the branch it sat in', t => {
+    attachSemanticVocabulary(semantic);
+    t.teardown(() => detachSemanticVocabulary());
+    const meta: IMeta = {};
+    createAttachCheckpoint('test')(meta);
+    meta.checkpoint?.('before-the-branch');
+    meta.decide?.('rate-within-limit', {rate: 2}, [
+        {
+            name: 'decline',
+            when: () => true,
+            run: () => {
+                meta.checkpoint?.('declined');
+                return 'declined';
+            },
+        },
+        {name: 'accept', when: () => true, run: () => 'accepted'},
+    ]);
+
+    t.same(
+        meta.progress?.map(entry => entry.kind),
+        ['point', 'region', 'point'],
+        'the branch is announced where it was taken, between the points on either side of it',
+    );
+    t.same(
+        pointsOf(meta.progress).map(point => point.regions?.length ?? 0),
+        [0, 1],
+        'and only the point announced inside the branch names it, which is what nests a report',
+    );
+    t.same(
+        pointsOf(meta.progress)[1]?.regions,
+        [
+            {
+                discriminator: 'rate-within-limit',
+                candidates: ['decline', 'accept'],
+                chosen: 'decline',
+            },
+        ],
+        'by the names of the branch, not by a position the log mints for itself',
+    );
+    t.same(
+        regionsOf(meta.progress)[0]?.regions,
+        undefined,
+        'while the branch itself names nothing above it',
+    );
+    t.end();
+});
+
+t.test('a branch taken inside a branch names the one it sits in', t => {
+    attachSemanticVocabulary(semantic);
+    t.teardown(() => detachSemanticVocabulary());
+    const meta: IMeta = {};
+    createAttachCheckpoint('test')(meta);
+    meta.decide?.('outer', {}, [
+        {
+            name: 'taken',
+            when: () => true,
+            run: () =>
+                meta.decide?.('inner', {}, [{name: 'only', when: () => true, run: () => 'inner'}]),
+        },
+    ]);
+
+    t.same(
+        regionsOf(meta.progress).map(region => region.discriminator),
+        ['outer', 'inner'],
+        'both are announced, outermost first',
+    );
+    t.same(
+        regionsOf(meta.progress)[1]?.regions?.map(region => region.discriminator),
+        ['outer'],
+        'and the nested one is in the chain of the one that encloses it',
+    );
+    t.end();
+});
+
+t.test('a checkpoint is announced to the log, and announces nothing without one', t => {
+    detachSemanticVocabulary();
+    const detached: IMeta = {};
+    createAttachCheckpoint('test')(detached);
+    detached.checkpoint?.('no-log');
+    t.equal(
+        semantic.takePoints(),
+        undefined,
+        'nothing is announced where no emitter is attached: the degradation is the whole point',
+    );
+
+    attachSemanticVocabulary(semantic);
+    t.teardown(() => detachSemanticVocabulary());
+    const attached: IMeta = {};
+    createAttachCheckpoint('test')(attached);
+    attached.checkpoint?.('total-calculated', {total: 200});
+    t.same(
+        semantic.takePoints(),
+        [{name: 'total-calculated', data: {total: 200}}],
+        'PRD R26: the milestone reaches the log, so a diagram can draw it as a note',
+    );
+    t.equal(semantic.takePoints(), undefined, 'and is taken once, by the record that carries it');
+    t.end();
+});
+
+t.test('a decision is announced to the log too, and still selects without one', t => {
+    detachSemanticVocabulary();
+    const detached: IMeta = {};
+    createAttachCheckpoint('test')(detached);
+    t.equal(
+        detached.decide?.('d', {}, [{name: 'only', when: () => true, run: () => 7}]),
+        7,
+        'the branch is taken with nothing attached',
+    );
+    t.equal(semantic.takeDecision(), undefined, 'and no rationale is staged to record');
+
+    attachSemanticVocabulary(semantic);
+    t.teardown(() => detachSemanticVocabulary());
+    const attached: IMeta = {};
+    createAttachCheckpoint('test')(attached);
+    attached.decide?.('route-selection', {}, [
+        {name: 'hubB', when: () => true, run: () => 'hubB'},
+        {name: 'hold', when: () => true, run: () => undefined},
+    ]);
+    t.same(
+        semantic.takeDecision()?.candidates,
+        ['hubB', 'hold'],
+        'the rationale is staged for the next record, in evaluation order (PRD R11)',
+    );
+    t.end();
+});
+
+t.test('no branch matching is a recorded non-choice', t => {
+    const meta: IMeta = {};
+    createAttachCheckpoint('test')(meta);
+    t.equal(meta.decide?.('never', {}, [{name: 'a', when: () => false, run: () => 1}]), undefined);
+    t.equal(regionsOf(meta.progress)[0]?.chosen, 'none', 'recorded as `none` rather than lost');
+    t.end();
+});
+
+t.test('each predicate is evaluated once', t => {
+    const meta: IMeta = {};
+    createAttachCheckpoint('test')(meta);
+    let evaluations = 0;
+    meta.decide?.('counting', {}, [
+        {
+            name: 'only',
+            when: () => {
+                evaluations++;
+                return true;
+            },
+            run: () => 'taken',
+        },
+    ]);
+    t.equal(evaluations, 1, 'the `run` is wrapped, not the predicate re-evaluated');
+    t.end();
+});
+
+t.test('a branch that throws records nothing', t => {
+    const meta: IMeta = {};
+    createAttachCheckpoint('test')(meta);
+    t.throws(
+        () =>
+            meta.decide?.('boom', {}, [
+                {
+                    name: 'a',
+                    when: () => true,
+                    run: () => {
+                        throw new Error('handler failed');
+                    },
+                },
+            ]),
+        /handler failed/,
+        'the failure is not swallowed',
+    );
+    t.notOk(
+        meta.progress,
+        'a decision that never completed is not a decision, so nothing is recorded',
+    );
+    t.end();
+});
+
+t.test('attaching twice does not replace a handle already there', t => {
+    const meta: IMeta = {};
+    const attach = createAttachCheckpoint('test');
+    attach(meta);
+    const first = meta.decide;
+    attach(meta);
+    t.equal(meta.decide, first, 'a dispatch that was already prepared is left alone');
+    t.end();
+});

package/src/checkpoint.ts

@@ -1,32 +1,133 @@
-import type {CheckpointFn, IMeta} from '@feasibleone/blong/types';
+import type {
+    CheckpointFn,
+    DecideFn,
+    IMeta,
+    IProgressPoint,
+    IProgressRegion,
+    IRegionMark,
+} from '@feasibleone/blong/types';
+import {vocabulary} from '@feasibleone/semantic-log/attachable';
 
 /**
- * Records a checkpoint in the $meta.checkpoints array.
+ * The branches the calling scope is running inside, named the way `$meta` names them.
+ *
+ * Names only, and never the log's own mark: the mark carries the position it was minted at,
+ * which describes a place in *this* process' execution. An entry that travelled here from
+ * another process over a call would bring a position that means nothing here, while the three
+ * names still say exactly which branches it sat in — which is all a report groups by.
+ */
+const regionMarks = (): IRegionMark[] | undefined => {
+    const chain = vocabulary.currentRegions();
+    if (chain === undefined || chain.length === 0) {
+        return undefined;
+    }
+    return chain.map(region => ({
+        discriminator: region.discriminator,
+        candidates: region.candidates,
+        chosen: region.chosen,
+    }));
+};
+
+/**
+ * Reports a checkpoint into `$meta.progress`, and announces it as a progress point
+ * (PRD R26).
+ *
  * Uses `this` binding — works correctly when called as
  * $meta.checkpoint?.('name', data) with optional chaining.
  */
 const checkpoint: CheckpointFn = function (this: IMeta, name: string, data?: unknown): void {
-    (this.checkpoints ??= []).push({
+    const regions = regionMarks();
+    const entry: IProgressPoint = {
+        kind: 'point',
         name,
-        data,
+        ...(data === undefined ? {} : {data}),
         timestamp: Date.now(),
-    });
+        ...(regions === undefined ? {} : {regions}),
+    };
+    (this.progress ??= []).push(entry);
+    // The same moment is announced to the log, so a checkpoint reaches the record the
+    // sequence diagram is drawn from rather than only the list a test asserts on. The
+    // vocabulary degrades to nothing where no emitter is attached, so this is one call
+    // and never a way for a dispatch path to import the emitter's ambient scope (F-197).
+    vocabulary.point(name, data);
 };
 
 /**
- * Attaches the checkpoint function to $meta if not already present.
- * The function uses `this` to record into the $meta it's called on.
+ * Takes a branch, and keeps what it was and which one was taken on the invocation that took
+ * it (PRD R11/R26).
+ *
+ * `this`-bound like {@link checkpoint}. The branch's `run` is *wrapped* rather than the
+ * predicates re-evaluated: a predicate with a side effect must run exactly once, and the
+ * decision recorded has to be the one the code actually took. A branch whose `run` throws
+ * records nothing — the entry is withdrawn before the throw propagates, because a decision
+ * that never completed is not a decision.
  */
-export function attachCheckpoint($meta: IMeta): void {
-    $meta.checkpoint ??= checkpoint;
-}
+const decide: DecideFn = function <T>(
+    this: IMeta,
+    discriminator: string,
+    values: Record<string, unknown>,
+    branches: ReadonlyArray<{
+        name: string;
+        when: (values: Record<string, unknown>) => boolean;
+        run: () => T;
+    }>,
+): T | undefined {
+    let chosen: string | undefined;
+    const wrapped = branches.map(branch => ({
+        ...branch,
+        run: () => {
+            chosen = branch.name;
+            return branch.run();
+        },
+    }));
+    // The entry is pushed *before* the branch runs, which is what puts it where the
+    // announcement order wants it: the points the branch announces come after it in the
+    // array, and a report that groups by those points therefore draws them inside the
+    // branch. Nothing else in the entry is known yet, so `chosen` is filled in below.
+    const outer = regionMarks();
+    const entry: IProgressRegion = {
+        kind: 'region',
+        discriminator,
+        candidates: branches.map(branch => branch.name),
+        chosen: '',
+        values,
+        ...(outer === undefined ? {} : {regions: outer}),
+    };
+    const held = this.progress;
+    const progress = (this.progress ??= []);
+    progress.push(entry);
+    try {
+        const result = vocabulary.decide<T>(discriminator, values, wrapped);
+        entry.chosen = chosen ?? 'none';
+        return result;
+    } catch (error) {
+        // A branch whose `run` throws records nothing, which is the rule this recorder has
+        // always kept: a decision that never completed is not a decision. The entry was
+        // pushed early, so it is withdrawn again — and, where the array was this call's own,
+        // the slot goes with it, so a throwing branch leaves `$meta.progress` exactly as
+        // absent as it found it. The throw still propagates.
+        const at = progress.lastIndexOf(entry);
+        if (at !== -1) progress.splice(at, 1);
+        if (held === undefined && progress.length === 0) delete this.progress;
+        throw error;
+    }
+};
 
 /**
- * Returns an attachCheckpoint function when checkpoint mode is enabled,
- * or undefined for production (zero overhead via optional chaining).
+ * Attach the framework's progress-point handles to a dispatch's `$meta`.
+ *
+ * `decide` is attached in **every** mode: it selects a branch, so a missing one would skip
+ * the work rather than cost a note. `checkpoint` is attached only where points are
+ * recorded, which is what keeps its `?.` call free in production.
  */
 export function createAttachCheckpoint(
     mode: 'test' | 'debug' | 'production',
-): ((meta: IMeta) => void) | undefined {
-    return mode === 'production' ? undefined : attachCheckpoint;
+): (meta: IMeta) => void {
+    const recording = mode !== 'production';
+    return (meta: IMeta): void => {
+        meta.decide ??= decide;
+        if (recording) {
+            meta.checkpoint ??= checkpoint;
+        }
+    };
 }

package/src/ci.intent.test.ts

@@ -0,0 +1,94 @@
+import {server} from '@feasibleone/blong';
+import {test} from 'tap';
+
+import load from './loadServer.ts';
+
+/**
+ * The `ci` block is a captured run's configuration — colours off, Allure results
+ * written — and a CI run is one by definition, so `activeConfigs` activates the
+ * block for it whether or not the entry named the intent.
+ *
+ * What made this worth a test: only the entries that remembered to pass `ci` in CI
+ * wrote Allure results, so a package whose only runner is tap produced no report and
+ * the CI summary had nothing to link for it. The observable here is the same trick
+ * `exit.intent.test.ts` uses — a config key that only the `ci` block sets — because
+ * the resolved `watch.allure.enabled` is not exposed on the registry.
+ *
+ * Only `load` is exercised, never `start`: the assertions are about which config
+ * blocks merged. Every load is stopped, since the `integration` intent opens the
+ * semantic-log cluster service and a registry that is never stopped leaves the suite
+ * reporting `timeout!` instead of passing (`exit.intent.test.ts` explains it at
+ * length).
+ */
+
+/**
+ * The suite the load is built from. `pkg` is supplied so the loader skips its
+ * `createRequire(mod.url)('./package.json')` lookup, and `parentConfig` is an object
+ * rather than a name so the test does not depend on the working directory.
+ */
+const suite = (config: object) =>
+    server(
+        () =>
+            ({
+                url: import.meta.url,
+                pkg: {name: 'ci-intent-test', version: '0.0.0'},
+                children: [],
+                config: {default: {}, ...config},
+            }) as never,
+    );
+
+/** The `exit` the run resolves, with `ci` as the only thing that sets it. */
+async function exitWithCiBlock(intents: string[]): Promise<boolean | undefined> {
+    const registry = await load(
+        suite({ci: {exit: true}}) as unknown as Parameters<typeof load>[0],
+        'ci-intent-test',
+        {},
+        intents,
+    );
+    try {
+        return registry.exit;
+    } finally {
+        await registry.stop();
+    }
+}
+
+/** Run `fn` with `CI` set the way a runner sets it, and restore it afterwards. */
+async function withCi<T>(value: string | undefined, fn: () => Promise<T>): Promise<T> {
+    const previous = process.env['CI'];
+    if (value === undefined) delete process.env['CI'];
+    else process.env['CI'] = value;
+    try {
+        return await fn();
+    } finally {
+        if (previous === undefined) delete process.env['CI'];
+        else process.env['CI'] = previous;
+    }
+}
+
+test('a CI run activates the ci block without being asked', async t => {
+    t.equal(
+        await withCi('true', () => exitWithCiBlock([])),
+        true,
+        'the block merged although no intent named it',
+    );
+    t.equal(
+        await withCi('true', () => exitWithCiBlock(['dev', 'integration'])),
+        true,
+        'the intents a run normally passes do not take it away',
+    );
+});
+
+test('a run that is not CI needs the intent', async t => {
+    // `false`, not `undefined`: the registry always carries a boolean once loaded.
+    // Deleting `CI` rather than inheriting it, because this suite runs in CI itself.
+    t.equal(
+        await withCi(undefined, () => exitWithCiBlock([])),
+        false,
+        'the block stays out of a run whose output is watched',
+    );
+    t.equal(
+        await withCi(undefined, () => exitWithCiBlock(['ci'])),
+        true,
+        'and naming it still does what it always did',
+    );
+});

package/src/codec/adapter/jsonrpc/receive.ts

@@ -1,4 +1,4 @@
-import {handler, type IMeta, type ITypedError} from '@feasibleone/blong/types';
+import {handler, type IMeta, type IProgressEntry, type ITypedError} from '@feasibleone/blong/types';
 import {type Response} from 'got';
 
 export default handler(({errors}) => ({
@@ -8,7 +8,7 @@ export default handler(({errors}) => ({
             error?: unknown;
             validation?: unknown;
             debug?: unknown;
-            checkpoints?: unknown[];
+            progress?: unknown[];
         }>,
         $meta?: IMeta,
     ) {
@@ -54,8 +54,8 @@ export default handler(({errors}) => ({
                 }),
             });
         } else if (typeof body === 'object' && 'result' in body && !('error' in body)) {
-            if ($meta && body.checkpoints?.length) {
-                ($meta.checkpoints ??= []).push(...body.checkpoints);
+            if ($meta && body.progress?.length) {
+                ($meta.progress ??= []).push(...(body.progress as IProgressEntry[]));
             }
             return body.result;
         } else {

package/src/codec/adapter/mle/ready.ts

@@ -99,10 +99,13 @@ export default handler<{
      * expired session) the tokens are cleared so the next request surfaces a
      * clean 401 to the caller, which the UI turns into a login prompt.
      */
-    async function refresh(this: {
-        exec?(...params: unknown[]): Promise<unknown>;
-        error?(error: unknown, $meta?: unknown): void;
-    }, opts: {force?: boolean} = {}): Promise<void> {
+    async function refresh(
+        this: {
+            exec?(...params: unknown[]): Promise<unknown>;
+            error?(error: unknown, $meta?: unknown): void;
+        },
+        opts: {force?: boolean} = {},
+    ): Promise<void> {
         const now = Date.now();
         if (token && (opts.force || tokenExpire < now)) {
             if (refreshToken && refreshTokenExpire > now) {
@@ -126,7 +129,10 @@ export default handler<{
                                 {},
                             )) as {
                                 statusCode?: number;
-                                body?: {result?: IToken; error?: {type?: string; message?: string; statusCode?: number}};
+                                body?: {
+                                    result?: IToken;
+                                    error?: {type?: string; message?: string; statusCode?: number};
+                                };
                             };
                             return result;
                         })();
@@ -134,7 +140,10 @@ export default handler<{
                     if (pending !== null) pending = null;
                     const {body, statusCode} = result as {
                         statusCode?: number;
-                        body?: {result?: IToken; error?: {type?: string; message?: string; statusCode?: number}};
+                        body?: {
+                            result?: IToken;
+                            error?: {type?: string; message?: string; statusCode?: number};
+                        };
                     };
                     // The gateway MLE-encrypts the response with the handshake
                     // keys, so decrypt the result before reading the token.
@@ -263,7 +272,14 @@ export default handler<{
         },
         async loginTokenCreateResponseReceive(result: Response<{result: unknown}>, $meta: unknown) {
             await decrypt(result.body, 'result');
-            if ((result.body as {error?: unknown})?.error) return super.receive(result, $meta);
+            if ((result.body as {error?: unknown})?.error) {
+                // The base `receive` reads an error from the *decrypted* body and this hook
+                // delegates to it, so the error has to be decrypted here: without this the
+                // encrypted envelope is what a failed login throws, and the reason for the
+                // failure is unreadable to the caller that has to act on it.
+                await decrypt(result.body, 'error');
+                return super.receive(result, $meta);
+            }
             readToken(result.body.result as IToken);
             return super.receive(result, $meta);
         },
@@ -272,9 +288,15 @@ export default handler<{
         async loginTokenRefreshRequestSend(params: {$http?: unknown}, $meta: unknown) {
             return super.send(await encryptPublic(params), $meta);
         },
-        async loginTokenRefreshResponseReceive(result: Response<{result: unknown}>, $meta: unknown) {
+        async loginTokenRefreshResponseReceive(
+            result: Response<{result: unknown}>,
+            $meta: unknown,
+        ) {
             await decrypt(result.body, 'result');
-            if ((result.body as {error?: unknown})?.error) return super.receive(result, $meta);
+            if ((result.body as {error?: unknown})?.error) {
+                await decrypt(result.body, 'error');
+                return super.receive(result, $meta);
+            }
             readToken(result.body.result as IToken);
             return super.receive(result, $meta);
         },
@@ -290,9 +312,15 @@ export default handler<{
         async loginTokenRestoreRequestSend(params: {$http?: unknown}, $meta: unknown) {
             return super.send(await encryptPublic(params), $meta);
         },
-        async loginTokenRestoreResponseReceive(result: Response<{result: unknown}>, $meta: unknown) {
+        async loginTokenRestoreResponseReceive(
+            result: Response<{result: unknown}>,
+            $meta: unknown,
+        ) {
             await decrypt(result.body, 'result');
-            if ((result.body as {error?: unknown})?.error) return super.receive(result, $meta);
+            if ((result.body as {error?: unknown})?.error) {
+                await decrypt(result.body, 'error');
+                return super.receive(result, $meta);
+            }
             readToken(result.body.result as IToken);
             return super.receive(result, $meta);
         },