functionalscript 0.45.0 → 0.46.0

package/fjs/cas/types.d.ts

@@ -6,7 +6,7 @@
 import type { Vec } from '../types/bit_vec/types.ts';
 import type { Effect, Operation } from '../effects/types.ts';
 import type { List } from '../effects/list/types.ts';
-import type { IoResult, Mkdir, Now, RandomInt, ReadBytes, Readdir, Rename, Rm, CreateExclusive, WriteBytes, Access, Stat } from '../effects/node/types.ts';
+import type { Access, CreateExclusive, IoChannel, Mkdir, Now, RandomInt, ReadBytes, Readdir, Rename, Rm, Stat, WriteBytes } from '../effects/node/types.ts';
 /**
  * The filesystem effects the streaming CAS performs: `read` pulls shards
  * (`ReadBytes`); `list` walks the store (`Access`/`Readdir`); `write` runs the
@@ -17,18 +17,32 @@ import type { IoResult, Mkdir, Now, RandomInt, ReadBytes, Readdir, Rename, Rm, C
 export type FileCasOperation = ReadBytes | Mkdir | Readdir | Access | Rename | Rm | RandomInt | Now | CreateExclusive | WriteBytes | Stat | Now | Readdir | Rm;
 export type Cas<O extends Operation> = {
     /**
-     * Streams the content for `hash` out in `<=128 KiB` chunks. Every pull yields an
-     * explicit `ok(chunk)` or `error` item, so a missing shard or I/O error is a distinct
-     * error *item* in the stream, never collapsed into end-of-stream (`undefined`).
+     * Streams the content for `hash` out in `<=128 KiB` chunks.
+     *
+     * A missing shard or an I/O error **fails the stream** rather than ending
+     * it, so it can never be mistaken for end-of-stream. That distinction used
+     * to be a rule this comment had to state, with an `ok(chunk)`/`error` item
+     * union that every consumer kept apart by hand; it is now the difference
+     * between an `error` cell and an `ok(undefined)` one, which nothing can
+     * confuse.
      */
-    readonly read: (hash: Vec) => List<O, IoResult<Vec>>;
+    readonly read: (hash: Vec) => List<O, Vec, IoChannel>;
     /**
-     * Consumes a chunk stream — each item `ok(chunk)` or `error` — hashing incrementally,
-     * and returns the content address. An error item aborts the upload.
+     * Consumes a chunk stream, hashing incrementally, and returns the content
+     * address. A stream that fails aborts the upload with that failure.
      */
-    readonly write: <O1 extends Operation>(payload: List<O1, IoResult<Vec>>) => Effect<O | O1, IoResult<Vec>>;
-    /** Lists all stored content hashes. */
-    readonly list: () => Effect<O, readonly Vec[]>;
+    readonly write: <O1 extends Operation>(payload: List<O1, Vec, IoChannel>) => Effect<O | O1, Vec, IoChannel>;
+    /**
+     * Lists all stored content hashes.
+     *
+     * Fallible like its siblings: walking the store is IO, and a store that
+     * cannot be walked must be distinguishable from one that is empty. An
+     * absent store *is* empty and answers `ok([])` — that is the fresh-store
+     * case, not a failure — but a directory that exists and cannot be read is
+     * an error, and returning it is what lets a caller say so instead of
+     * reporting no content.
+     */
+    readonly list: () => Effect<O, readonly Vec[], IoChannel>;
 };
 export type FileCas = Cas<FileCasOperation> & {
     url: (v: Vec) => string;

package/fjs/ci/config/module.f.d.mts

@@ -18,7 +18,7 @@ export declare const images: {
         readonly arm: 'windows-11-arm';
     };
 };
-export declare const functionalscript = /** @type {const} */ "0.44.0";
+export declare const functionalscript = /** @type {const} */ "0.45.0";
 export declare const bun = "1.3.14";
 export declare const deno = "2.9.5";
 export declare const node: {
@@ -28,7 +28,7 @@ export declare const node: {
 };
 export declare const nixpkgs: {
     readonly ref: 'nixos-26.05';
-    readonly commit: '9f78f44a87948854445dae0b6bf82b2e87e4efb5';
+    readonly commit: '02e08985a27c65ffd33d434eeb2e660a2e4dc84d';
 };
 export declare const wasmtime = "47.0.3";
 export declare const wasmer = "7.2.1";

package/fjs/ci/config/module.f.mjs

@@ -25,7 +25,7 @@ export const images = /** @type {const} */({
 // published FunctionalScript release; do not tie it to package.json's current
 // in-repo version.
 // https://www.npmjs.com/package/functionalscript
-export const functionalscript = /** @type {const} */ '0.44.0'
+export const functionalscript = /** @type {const} */ '0.45.0'
 
 // https://bun.sh/
 export const bun = '1.3.14'
@@ -53,7 +53,7 @@ export const node = /** @type {const} */({
 // https://channels.nixos.org/nixos-26.05/git-revision
 export const nixpkgs = /** @type {const} */({
     ref: 'nixos-26.05',
-    commit: '9f78f44a87948854445dae0b6bf82b2e87e4efb5',
+    commit: '02e08985a27c65ffd33d434eeb2e660a2e4dc84d',
 })
 
 // https://github.com/bytecodealliance/wasmtime/releases

package/fjs/ci/module.f.d.mts

@@ -5,15 +5,15 @@
  *
  * @module
  *
- * @import { Effect } from '../effects/types.ts'
  * @import { NodeOp } from '../effects/node/types.ts'
  * @import { Architecture, GitHubAction, Job, Jobs, MetaStep, Os } from './common/types.ts'
  * @import { NixJob } from './nix/types.ts'
  * @import { Setup } from './types.ts'
+ * @import { Effect } from '../effects/types.ts'
  */
-import type { Effect } from '../effects/types.ts';
 import type { NodeOp } from '../effects/node/types.ts';
 import type { Setup } from './types.ts';
-/** @type {(setup: Setup) => Effect<NodeOp, number>} */
-export declare const ci: (setup: Setup) => Effect<NodeOp, number>;
-export declare const main: () => Effect<NodeOp, number>;
+import type { Effect } from '../effects/types.ts';
+/** @type {(setup: Setup) => Effect<NodeOp, 0, number>} */
+export declare const ci: (setup: Setup) => Effect<NodeOp, 0, number>;
+export declare const main: () => Effect<NodeOp, 0, number>;

package/fjs/ci/module.f.mjs

@@ -5,15 +5,16 @@
  *
  * @module
  *
- * @import { Effect } from '../effects/types.ts'
  * @import { NodeOp } from '../effects/node/types.ts'
  * @import { Architecture, GitHubAction, Job, Jobs, MetaStep, Os } from './common/types.ts'
  * @import { NixJob } from './nix/types.ts'
  * @import { Setup } from './types.ts'
+ * @import { Effect } from '../effects/types.ts'
  */
 
-import { mapStep, step } from '../effects/module.f.mjs'
-import { access, writeUtf8File } from '../effects/node/module.f.mjs'
+import { resultStep } from '../effects/module.f.mjs'
+import { access, exitStep, writeUtf8File } from '../effects/node/module.f.mjs'
+import { step as ioStep } from '../effects/module.f.mjs'
 import { functionalscript, images } from './config/module.f.mjs'
 import {
     architecture,
@@ -57,8 +58,8 @@ const canonicalJobs = rust => ({
     'nix-flakes': nixFlakeJob,
 })
 
-/** @type {(setup: Setup) => Effect<NodeOp, number>} */
-export const ci = ({ nodeExtra }) => step(
+/** @type {(setup: Setup) => Effect<NodeOp, 0, number>} */
+export const ci = ({ nodeExtra }) => resultStep(
     access('Cargo.toml'),
     result => {
         const rust = result[0] === 'ok'
@@ -82,8 +83,8 @@ export const ci = ({ nodeExtra }) => step(
         const workflowWritten = writeUtf8File(
             '.github/workflows/ci.yml',
             JSON.stringify(gha, null, '  '))
-        const flakesWritten = step(workflowWritten, () => nixFlakes(nixJobs))
-        return mapStep(flakesWritten, () => 0)
+        const flakesWritten = ioStep(workflowWritten, () => nixFlakes(nixJobs))
+        return exitStep(flakesWritten)
     })
 
 export const main = () => ci({ nodeExtra: () => [] })

package/fjs/ci/nix/module.f.d.mts

@@ -11,14 +11,14 @@
  *
  * @module
  *
+ * @import { IoChannel, Mkdir, WriteFile } from '../../effects/node/types.ts'
  * @import { Effect } from '../../effects/types.ts'
- * @import { Mkdir, WriteFile } from '../../effects/node/types.ts'
  * @import { Expression } from '../../media/nix/types.ts'
  * @import { MetaStep } from '../common/types.ts'
  * @import { NixJob } from './types.ts'
  */
+import type { IoChannel, Mkdir, WriteFile } from '../../effects/node/types.ts';
 import type { Effect } from '../../effects/types.ts';
-import type { Mkdir, WriteFile } from '../../effects/node/types.ts';
 import type { MetaStep } from '../common/types.ts';
 import type { NixJob } from './types.ts';
 /** Directory owned by this generator. */
@@ -35,16 +35,18 @@ export declare const generatedDirectory: 'nix/generated';
  */
 export declare const flakeText: (job: NixJob) => string;
 /**
- * Writes one generated flake per job.
+ * Writes one generated flake per job, stopping at the first failure.
  *
- * @type {(jobs: readonly NixJob[]) => Effect<Mkdir | WriteFile, void>}
+ * @type {(jobs: readonly NixJob[]) => Effect<Mkdir | WriteFile, void, IoChannel>}
  */
-export declare const nixFlakes: (jobs: readonly NixJob[]) => Effect<Mkdir | WriteFile, void>;
+export declare const nixFlakes: (jobs: readonly NixJob[]) => Effect<Mkdir | WriteFile, void, IoChannel>;
 /** Path a workflow passes to `nix develop`, for the job of the given id. */
+/** @type {(id: string) => string} */
 export declare const flakePath: (id: string) => string;
 /** Installs Nix, with `nix-command` and `flakes` enabled by the action's defaults. */
 export declare const nixInstall: MetaStep;
 /** Runs one command inside a job's generated development shell. */
+/** @type {(id: string, command: string) => string} */
 export declare const nixDevelop: (id: string, command: string) => string;
 /**
  * Runs a migrated job's whole command sequence in one development shell, so the

package/fjs/ci/nix/module.f.mjs

@@ -11,15 +11,16 @@
  *
  * @module
  *
+ * @import { IoChannel, Mkdir, WriteFile } from '../../effects/node/types.ts'
  * @import { Effect } from '../../effects/types.ts'
- * @import { Mkdir, WriteFile } from '../../effects/node/types.ts'
  * @import { Expression } from '../../media/nix/types.ts'
  * @import { MetaStep } from '../common/types.ts'
  * @import { NixJob } from './types.ts'
  */
 
-import { forEachStep, mapStep, pure, step } from '../../effects/module.f.mjs'
+import { pureOk } from '../../effects/module.f.mjs'
 import { mkdir, writeUtf8File } from '../../effects/node/module.f.mjs'
+import { forEachStep, step } from '../../effects/module.f.mjs'
 import { nixToString } from '../../media/nix/module.f.mjs'
 import { fromUndefined, unwrap as unwrapNullable } from '../../types/nullable/module.f.mjs'
 import { unwrap } from '../../types/result/module.f.mjs'
@@ -72,33 +73,33 @@ const flake = ({ system, packages, shellHook }) => ['set',
 export const flakeText = job =>
     unwrapNullable(fromUndefined(nixToString(flake(job))))
 
-/** @type {(job: NixJob) => Effect<Mkdir | WriteFile, void>} */
+/** @type {(job: NixJob) => Effect<Mkdir | WriteFile, void, IoChannel>} */
 const writeFlake = job => {
     const directory = `${generatedDirectory}/${job.id}`
-    const created = mapStep(mkdir(directory, { recursive: true }), unwrap)
-    const written = step(
+    const created = mkdir(directory, { recursive: true })
+    return step(
         created,
         () => writeUtf8File(`${directory}/flake.nix`, flakeText(job)))
-    return mapStep(written, unwrap)
 }
 
 /**
- * Writes one generated flake per job.
+ * Writes one generated flake per job, stopping at the first failure.
  *
- * @type {(jobs: readonly NixJob[]) => Effect<Mkdir | WriteFile, void>}
+ * @type {(jobs: readonly NixJob[]) => Effect<Mkdir | WriteFile, void, IoChannel>}
  */
 export const nixFlakes = jobs =>
-    forEachStep(pure(jobs), writeFlake)
+    forEachStep(pureOk(jobs), writeFlake)
 
 /** Path a workflow passes to `nix develop`, for the job of the given id. */
-export const flakePath = /** @type {(id: string) => string} */ (id => `./${generatedDirectory}/${id}`)
+/** @type {(id: string) => string} */
+export const flakePath = id => `./${generatedDirectory}/${id}`
 
 /** Installs Nix, with `nix-command` and `flakes` enabled by the action's defaults. */
 export const nixInstall = install(uses('cachix/install-nix-action'))
 
 /** Runs one command inside a job's generated development shell. */
-export const nixDevelop = /** @type {(id: string, command: string) => string} */
-    ((id, command) => `nix develop ${flakePath(id)} --command ${command}`)
+/** @type {(id: string, command: string) => string} */
+export const nixDevelop = (id, command) => `nix develop ${flakePath(id)} --command ${command}`
 
 /**
  * Wraps a string so a POSIX shell reproduces it exactly. Single quotes protect

package/fjs/ci/nix/proof.f.mjs

@@ -7,7 +7,7 @@
  */
 
 import { assert, assertEq } from '../../asserts/module.f.mjs'
-import { step } from '../../effects/module.f.mjs'
+import { step as ioStep } from '../../effects/module.f.mjs'
 import { readUtf8File } from '../../effects/node/module.f.mjs'
 import { emptyState, virtual } from '../../effects/node/virtual/module.f.mjs'
 import { nixpkgs } from '../config/module.f.mjs'
@@ -74,7 +74,7 @@ const shellHookFlake = `{
 
 /** @type {(jobs: readonly NixJob[], id: string) => string} */
 const generated = (jobs, id) => {
-    const written = step(
+    const written = ioStep(
         nixFlakes(jobs),
         () => readUtf8File(`${generatedDirectory}/${id}/flake.nix`))
     const [, [tag, result]] = virtual(emptyState)(written)

package/fjs/ci/proof.f.mjs

@@ -3,6 +3,7 @@
  * @import { Dir, State } from '../effects/node/virtual/types.ts'
  */
 
+import { exitCode } from '../effects/node/module.f.mjs'
 import { ci, main } from './module.f.mjs'
 import { functionalscript, node } from './config/module.f.mjs'
 import { nodeNixJobs } from './node/module.f.mjs'
@@ -39,8 +40,11 @@ const makeState = (/** @type {boolean} */ rust, /** @type {string | undefined} *
 /** @type {(dir: Dir, name: string) => Dir} */
 const subDir = (dir, name) => {
     const entity = dir[name]
-    assert(typeof entity === 'object' && !Array.isArray(entity), entity)
-    return /** @type {Dir} */ (entity)
+    // `Array.isArray` narrows to `any[]`, which `readonly Vec[]` is not assignable
+    // to, so its negative branch never removes a `readonly` array from a union.
+    // `instanceof Array` does, so this `assert` narrows `entity` to `Dir`.
+    assert(typeof entity === 'object' && !(entity instanceof Array), entity)
+    return entity
 }
 
 /** @type {(dir: Dir, name: string) => string} */
@@ -66,14 +70,14 @@ const flake = (state, id) =>
 /** @type {(rust: boolean, nodeExtra?: (o: Os) => readonly MetaStep[]) => GitHubAction} */
 const run = (rust, nodeExtra = () => []) => {
     const [state, result] = virtual(makeState(rust, undefined))(ci({ nodeExtra }))
-    assertEq(result, 0)
+    assertEq(exitCode(result), 0)
     return workflow(state)
 }
 
 /** @type {(packageJson?: string) => GitHubAction} */
 const runDefault = packageJson => {
     const [state, result] = virtual(makeState(false, packageJson))(main())
-    assertEq(result, 0)
+    assertEq(exitCode(result), 0)
     return workflow(state)
 }
 
@@ -175,7 +179,7 @@ export const proof = {
     },
     nixFlakes: () => {
         const [state, result] = virtual(makeState(false, undefined))(main())
-        assertEq(result, 0)
+        assertEq(exitCode(result), 0)
         for (const { id, packages } of nodeNixJobs) {
             const [nodePackage] = packages
             assert(

package/fjs/cli/module.f.d.mts

@@ -5,12 +5,10 @@
  *
  * @module
  *
- * @import { NodeOp, NodeProgramOptions, Write } from '../effects/node/types.ts'
- * @import { Effect } from '../effects/types.ts'
+ * @import { NodeOp, Program, Write } from '../effects/node/types.ts'
  * @import { Commands } from './types.ts'
  */
-import type { NodeOp, NodeProgramOptions, Write } from '../effects/node/types.ts';
-import type { Effect } from '../effects/types.ts';
+import type { NodeOp, Program, Write } from '../effects/node/types.ts';
 import type { Commands } from './types.ts';
-/** @type {<O extends NodeOp>(commands: Commands<O>) => (options: NodeProgramOptions) => Effect<O | Write, number>} */
-export declare const dispatch: <O extends NodeOp>(commands: Commands<O>) => (options: NodeProgramOptions) => Effect<O | Write, number>;
+/** @type {<O extends NodeOp>(commands: Commands<O>) => Program<O | Write>} */
+export declare const dispatch: <O extends NodeOp>(commands: Commands<O>) => Program<O | Write>;

package/fjs/cli/module.f.mjs

@@ -5,18 +5,16 @@
  *
  * @module
  *
- * @import { NodeOp, NodeProgramOptions, Write } from '../effects/node/types.ts'
- * @import { Effect } from '../effects/types.ts'
+ * @import { NodeOp, Program, Write } from '../effects/node/types.ts'
  * @import { Commands } from './types.ts'
  */
 
-import { errorExit, log } from '../effects/node/module.f.mjs'
-import { pure, step } from '../effects/module.f.mjs'
+import { errorExit, exitStep, log } from '../effects/node/module.f.mjs'
 import { at, fromEntries } from '../types/object/module.f.mjs'
 
 const helpMeta = { names: ['help', 'h', '?'], description: 'Print this help message' }
 
-/** @type {<O extends NodeOp>(commands: Commands<O>) => (options: NodeProgramOptions) => Effect<O | Write, number>} */
+/** @type {<O extends NodeOp>(commands: Commands<O>) => Program<O | Write>} */
 export const dispatch = commands => options => {
     const [cmd, ...rest] = options.args
     const rows = [...commands, helpMeta]
@@ -38,9 +36,7 @@ export const dispatch = commands => options => {
                 return dispatch(targetCmd.handler)({ ...options, args: ['help'] })
             }
         }
-        return step(
-            log(helpText),
-            () => pure(0))
+        return exitStep(log(helpText))
     }
     const found = at(cmd)(map)
     if (found === null) {

package/fjs/cli/proof.f.mjs

@@ -3,7 +3,8 @@
  * @import { Commands } from './types.ts'
  */
 
-import { pure } from '../effects/module.f.mjs'
+import { exitCode } from '../effects/node/module.f.mjs'
+import { pureError, pureOk } from '../effects/module.f.mjs'
 import { defaultNodeProgramOptions, emptyState, virtual } from '../effects/node/virtual/module.f.mjs'
 import { dispatch } from './module.f.mjs'
 import { assert, assertEq } from '../asserts/module.f.mjs'
@@ -17,7 +18,7 @@ const echoCommands = [
     {
         names: ['echo', 'e'],
         description: 'Print the first argument',
-        handler: ({ args: [arg = ''] }) => pure(arg.length),
+        handler: ({ args: [arg = ''] }) => arg.length === 0 ? pureOk(0) : pureError(arg.length),
     },
 ]
 
@@ -27,25 +28,25 @@ const run = (/** @type {Commands<NodeOp>} */ commands) => (/** @type {readonly s
 export const proof = {
     knownCommand: () => {
         const [, code] = run(echoCommands)(['echo', 'hello'])
-        assertEq(code, 5, ['expected length 5', code])
+        assertEq(exitCode(code), 5, ['expected length 5', code])
     },
     alias: () => {
         const [, code] = run(echoCommands)(['e', 'hi'])
-        assertEq(code, 2, ['expected length 2', code])
+        assertEq(exitCode(code), 2, ['expected length 2', code])
     },
     noArgs: () => {
         const [state, code] = run(echoCommands)([])
-        assertEq(code, 1, ['expected exit 1', code])
+        assertEq(exitCode(code), 1, ['expected exit 1', code])
         assert(state.stderr.length !== 0, 'expected error in stderr')
     },
     unknownCommand: () => {
         const [state, code] = run(echoCommands)(['bogus'])
-        assertEq(code, 1, ['expected exit 1', code])
+        assertEq(exitCode(code), 1, ['expected exit 1', code])
         assert(state.stderr.length !== 0, 'expected error in stderr')
     },
     help: () => {
         const [state, code] = run(echoCommands)(['help'])
-        assertEq(code, 0, ['expected exit 0', code])
+        assertEq(exitCode(code), 0, ['expected exit 0', code])
         assert(state.stdout.includes('echo'), 'expected command name in stdout')
         assert(state.stdout.includes('help'), 'expected help entry in stdout')
     },
@@ -62,7 +63,7 @@ export const proof = {
             description: 'Capture args',
             handler: (/** @type {{ args: readonly string[] }} */ { args }) => {
                 captured.push(...args)
-                return pure(0)
+                return pureOk(0)
             },
         }]
         run(commands)(['grab', 'a', 'b', 'c'])
@@ -73,7 +74,7 @@ export const proof = {
         const inner = [{
             names: ['ping'],
             description: 'Inner ping',
-            handler: () => pure(42),
+            handler: () => pureError(42),
         }]
         /** @type {Commands<NodeOp>} */
         const outer = [{
@@ -82,14 +83,14 @@ export const proof = {
             handler: inner,
         }]
         const [, code] = run(outer)(['sub', 'ping'])
-        assertEq(code, 42, ['expected 42', code])
+        assertEq(exitCode(code), 42, ['expected 42', code])
     },
     nestedHelp: () => {
         /** @type {Commands<NodeOp>} */
         const inner = [{
             names: ['ping'],
             description: 'Inner ping',
-            handler: () => pure(0),
+            handler: () => pureOk(0),
         }]
         /** @type {Commands<NodeOp>} */
         const outer = [{
@@ -98,17 +99,17 @@ export const proof = {
             handler: inner,
         }]
         const [state, code] = run(outer)(['sub', 'help'])
-        assertEq(code, 0, ['expected exit 0', code])
+        assertEq(exitCode(code), 0, ['expected exit 0', code])
         assert(state.stdout.includes('ping'), 'expected inner command in help')
     },
     prototypeNameIsUnknownCommand: () => {
         const [state, code] = run(echoCommands)(['toString'])
-        assertEq(code, 1, ['expected exit 1 for prototype-name command', code])
+        assertEq(exitCode(code), 1, ['expected exit 1 for prototype-name command', code])
         assert(state.stderr.includes('unknown command'), 'expected unknown-command error in stderr')
     },
     helpPrototypeSafe: () => {
         const [state, code] = run(echoCommands)(['help', 'toString'])
-        assertEq(code, 0, ['expected exit 0, not a throw', code])
+        assertEq(exitCode(code), 0, ['expected exit 0, not a throw', code])
         assert(state.stdout.includes('echo'), 'expected top-level help for unknown target')
     },
     helpWithTarget: () => {
@@ -116,7 +117,7 @@ export const proof = {
         const inner = [{
             names: ['ping'],
             description: 'Inner ping',
-            handler: () => pure(0),
+            handler: () => pureOk(0),
         }]
         /** @type {Commands<NodeOp>} */
         const outer = [{
@@ -125,7 +126,7 @@ export const proof = {
             handler: inner,
         }]
         const [state, code] = run(outer)(['help', 'sub'])
-        assertEq(code, 0, ['expected exit 0', code])
+        assertEq(exitCode(code), 0, ['expected exit 0', code])
         assert(state.stdout.includes('ping'), 'expected inner command in help')
         assert(!(state.stdout.includes('Subcommand group')), 'expected inner help, not outer')
     },

package/fjs/cli/types.d.ts

@@ -3,9 +3,8 @@
  *
  * @module
  */
-import type { NodeOp, NodeProgramOptions } from '../effects/node/types.ts';
-import type { Effect } from '../effects/types.ts';
-type Handler<O extends NodeOp> = (options: NodeProgramOptions) => Effect<O, number>;
+import type { NodeOp, Program } from '../effects/node/types.ts';
+type Handler<O extends NodeOp> = Program<O>;
 export type Command<O extends NodeOp> = {
     readonly names: readonly string[];
     readonly description: string;

package/fjs/common/monoid/types.d.ts

@@ -65,7 +65,7 @@ export type Monoid<T> = {
  * has `null`, meaning "longer than `maxLength`".
  *
  * The monoid is carried as a field rather than intersected in, so it stays
- * independently constructed and consumed (`AGENTS.md` §6.2).
+ * independently constructed and consumed (`fjs/AGENTS.md` §3.2).
  */
 export type Absorbing<T> = {
     readonly monoid: Monoid<T>;

package/fjs/crypto/hmac/module.f.mjs

@@ -44,8 +44,8 @@ const iPad = vec8(0x36n)
  * that takes a message and computes the HMAC.
  */
 export const hmac = hashFunc => {
-    const { blockLength } = hashFunc
-    const p = repeat(blockLength >> 3n)
+    const { blockLength, blockBytes } = hashFunc
+    const p = repeat(blockBytes)
     const ip = p(iPad)
     const op = p(oPad)
     const c = computeSync(hashFunc)

package/fjs/crypto/sha2/module.f.mjs

@@ -11,7 +11,7 @@
  * @import { Base, Sha2, State, V16, V8 } from './types.ts'
  */
 
-import { mask } from '../../types/bigint/module.f.mjs'
+import { divUp8, mask } from '../../types/bigint/module.f.mjs'
 import {
     vec,
     length,
@@ -257,6 +257,8 @@ const base = ({ logBitLen, k, bs0, bs1, ss0, ss1 }) => {
 const sha2 = ({ append, end, chunkLength }, hash, hashLength) => ({
     hashLength,
     blockLength: chunkLength,
+    hashBytes: divUp8(hashLength),
+    blockBytes: divUp8(chunkLength),
     init: {
         hash,
         len: 0n,

package/fjs/crypto/sha2/proof.f.d.mts

@@ -22,6 +22,7 @@ export declare const proof: {
         sha512x256: () => void;
         sha512x224: () => void;
     };
+    byteLengths: (() => void)[];
     utf8: (() => void)[];
     fill: () => {
         8: () => void;

package/fjs/crypto/sha2/proof.f.mjs

@@ -9,6 +9,19 @@ import { assertEq } from '../../asserts/module.f.mjs'
 import { map } from '../../types/list/module.f.mjs'
 import { base32, base64, computeSync, sha224, sha256, sha384, sha512, sha512x224, sha512x256 } from './module.f.mjs'
 
+/**
+ * Every SHA-2 length is a whole number of bytes, so the rounded-up byte count
+ * and the exact division agree — this pins both that identity and the values.
+ *
+ * @type {(sha2: Sha2) => (hashBytes: bigint, blockBytes: bigint) => void}
+ */
+const checkBytes = ({ hashLength, blockLength, hashBytes, blockBytes }) => (h, b) => {
+    assertEq(hashBytes, h)
+    assertEq(blockBytes, b)
+    assertEq(hashBytes, hashLength >> 3n)
+    assertEq(blockBytes, blockLength >> 3n)
+}
+
 /** @type {(sha2: Sha2) => (x: bigint) => void} */
 const checkEmpty = ({ init, end, hashLength }) => x => {
     const result = end(init)
@@ -71,6 +84,17 @@ export const proof = {
         sha512x256: () => checkEmpty(sha512x256)(0xc672b8d1ef56ed28ab87c3622c5114069bdd3ad7b8f9737498d0c01ecef0967an),
         sha512x224: () => checkEmpty(sha512x224)(0x6ed0dd02806fa89e25de060c19d3ac86cabb87d6a0ddd05c333b84f4n),
     },
+    // The byte counts consumers read instead of converting bit lengths
+    // themselves. Asserted against the bit length each is derived from, not
+    // against a hand-written number, so the pairing is what is pinned.
+    byteLengths: [
+        () => checkBytes(sha224)(28n, 64n),
+        () => checkBytes(sha256)(32n, 64n),
+        () => checkBytes(sha384)(48n, 128n),
+        () => checkBytes(sha512)(64n, 128n),
+        () => checkBytes(sha512x224)(28n, 128n),
+        () => checkBytes(sha512x256)(32n, 128n),
+    ],
     utf8: [
         () => {
             const e = 0x730e109bd7a8a32b1cb9d9a09aa2325d2430587ddbc0c38bad911525n

package/fjs/crypto/sha2/types.d.ts

@@ -51,6 +51,17 @@ export type Base = {
 export type Sha2 = {
     readonly hashLength: bigint;
     readonly blockLength: bigint;
+    /**
+     * `hashLength` and `blockLength` in whole bytes, rounded up. Consumers
+     * that size a byte buffer read these instead of converting: `hmac` and
+     * `sign` each used to do it themselves, with two different spellings
+     * (`>> 3n` and `divUp8`), leaving a reader to work out per site whether
+     * the two roundings agree. They do for every SHA-2 variant, whose lengths
+     * are byte multiples — which is exactly why the decision belongs here
+     * once rather than at each call site.
+     */
+    readonly hashBytes: bigint;
+    readonly blockBytes: bigint;
     readonly init: State;
     readonly append: Fold<Vec, State>;
     readonly end: (state: State) => Vec;

package/fjs/crypto/sign/module.f.mjs

@@ -12,7 +12,7 @@
  */
 
 import { assertNotNullish } from '../../asserts/module.f.mjs'
-import { bitLength, divUp8, roundUp8 } from '../../types/bigint/module.f.mjs'
+import { bitLength, roundUp8 } from '../../types/bigint/module.f.mjs'
 import { empty, length, msb, repeat, unpack, vec, vec8 } from '../../types/bit_vec/module.f.mjs'
 import { hmac } from '../hmac/module.f.mjs'
 import { computeSync } from '../sha2/module.f.mjs'
@@ -75,7 +75,7 @@ export const computeK =
         //    step and all subsequent steps, we use the same H function as the
         //    one used in step 'a' to process the input message; this choice
         //    will be discussed in more detail in Section 3.6.
-        const rep = repeat(divUp8(hf.hashLength))
+        const rep = repeat(hf.hashBytes)
         const v0 = rep(x01)
         // c. Set:
         //      K = 0x00 0x00 0x00 ... 0x00