functionalscript 0.40.0 → 0.41.0

package/fjs/cas/evo/module.f.d.ts

@@ -17,7 +17,10 @@
  * subject (see [`fjs/media/revision/README.md`](../../media/revision/README.md)).
  * `Cache` therefore tracks, per subject, every revision hash seen and every
  * hash referenced as somebody's parent; heads are the set difference between
- * the two, computed at read time ({@link headsOf}). Storing both sets rather
+ * the two, computed at read time ({@link headsOf}). Alongside them it records
+ * which of the seen revisions are `archived`, so {@link Evo.list} can classify
+ * a subject as active or archived from its heads' flags
+ * ({@link subjectListed}) without touching the store. Storing both sets rather
  * than a running head list is what makes folding revisions truly order
  * independent: `cas.list()` (used by {@link buildCache} to scan an existing
  * store) returns hashes in hash order, not revision ancestry, so a child can
@@ -97,14 +100,22 @@ export type RevisionData = {
     readonly generation?: number | undefined;
 };
 /**
- * Per-subject bookkeeping: every revision hash seen for the subject, and
- * every hash any of those revisions names as a parent. See the module doc
- * for why both sets are kept (rather than a running head list) and
- * {@link headsOf} for how heads are derived from them.
+ * Per-subject bookkeeping: every revision hash seen for the subject, every
+ * hash any of those revisions names as a parent, and which of the seen
+ * revisions are `archived`. See the module doc for why the first two sets are
+ * kept (rather than a running head list), {@link headsOf} for how heads are
+ * derived from them, and {@link subjectListed} for how `archived` classifies a
+ * subject once its heads are known.
+ *
+ * `archived` is keyed by revision hash, not by subject, for the same reason
+ * heads are computed at read time: which revisions are heads is only known
+ * once the whole store has been folded in, so a per-subject archived flag
+ * would have to be revised every time a later fold changes the head set.
  */
 export type SubjectState = {
     readonly hashes: readonly Hash[];
     readonly parents: readonly Hash[];
+    readonly archived: readonly Hash[];
 };
 /** In-memory index: subject → its {@link SubjectState}. */
 export type Cache = {
@@ -182,8 +193,17 @@ export declare const addRevision: <O extends Operation>(cas: Cas<O>) => (cacheKe
 export declare const readRevision: <O extends Operation>(cas: Cas<O>) => (hash: Hash) => Effect<O, Result<RevisionData, string>>;
 /** The Evo API described in `fjs/cas/evo/README.md`, bound to a `Cas<O>` and its cache slot. */
 export type Evo<O extends Operation> = {
-    /** Returns every subject with at least one stored revision. */
-    readonly list: () => Effect<MemOp, readonly Subject[]>;
+    /**
+     * Returns the subjects matching a status filter: the active ones by
+     * default, the archived ones when `archived` is `true`. A subject's status
+     * is derived from its current heads — see {@link subjectListed}, which
+     * also explains why a subject with no current heads is in neither result.
+     *
+     * There is deliberately no all-subjects mode: nothing needs one yet, and
+     * adding it later is a compatible extension of this parameter, while
+     * removing it would not be.
+     */
+    readonly list: (archived?: true) => Effect<MemOp, readonly Subject[]>;
     /** Returns the current head hashes of `subject` (empty if unknown). */
     readonly head: (subject: Subject) => Effect<MemOp, readonly Hash[]>;
     /** Adds a new head; see {@link addRevision}. */

package/fjs/cas/evo/module.f.js

@@ -17,7 +17,10 @@
  * subject (see [`fjs/media/revision/README.md`](../../media/revision/README.md)).
  * `Cache` therefore tracks, per subject, every revision hash seen and every
  * hash referenced as somebody's parent; heads are the set difference between
- * the two, computed at read time ({@link headsOf}). Storing both sets rather
+ * the two, computed at read time ({@link headsOf}). Alongside them it records
+ * which of the seen revisions are `archived`, so {@link Evo.list} can classify
+ * a subject as active or archived from its heads' flags
+ * ({@link subjectListed}) without touching the store. Storing both sets rather
  * than a running head list is what makes folding revisions truly order
  * independent: `cas.list()` (used by {@link buildCache} to scan an existing
  * store) returns hashes in hash order, not revision ancestry, so a child can
@@ -58,7 +61,7 @@ import { isNotFound } from '../../effects/node/module.f.js';
 export const emptyCache = { bySubject: {} };
 /** Canonical JSON encoder for a `Revision` — key order carries no meaning for detection. */
 const toJson = stringify(identity);
-const emptySubjectState = { hashes: [], parents: [] };
+const emptySubjectState = { hashes: [], parents: [], archived: [] };
 /** Adds every item of `items` to `set` that isn't already there, preserving `set`'s existing order. */
 const union = (set) => (items) => items.reduce((acc, h) => acc.includes(h) ? acc : [...acc, h], set);
 /**
@@ -76,12 +79,37 @@ const union = (set) => (items) => items.reduce((acc, h) => acc.includes(h) ? acc
 const canonicalHash = (h) => vecToCBase32(unwrap(cBase32ToVec(h)));
 /** A subject's current heads: revision hashes seen that no other revision of the same subject names as a parent. */
 const headsOf = (state) => state.hashes.filter(h => !state.parents.includes(h));
+/**
+ * Whether a subject in `state` belongs in {@link Evo.list}'s result for the
+ * given `archived` filter — the subject-level status derived from its
+ * revision-level `archived` flags:
+ *
+ * - **active** — at least one current head is not archived. This is the
+ *   default result set (`archived` omitted).
+ * - **archived** — the subject has at least one current head and every one of
+ *   them is archived (`archived: true`).
+ *
+ * Concurrent heads can disagree, and the two rules resolve that the same way:
+ * one unarchived head keeps the whole subject active, because a subject is
+ * only done evolving when nothing left to build on remains. A subject with no
+ * current heads is neither active nor archived and appears in no result — the
+ * status is a statement about heads, and there is nothing to state. That case
+ * needs the explicit `heads.length` test only in the archived branch, since
+ * "every head is archived" is vacuously true of no heads at all.
+ */
+const subjectListed = (archived) => (state) => {
+    const heads = headsOf(state);
+    const unarchived = heads.filter(h => !state.archived.includes(h));
+    return archived === undefined
+        ? unarchived.length !== 0
+        : heads.length !== 0 && unarchived.length === 0;
+};
 /**
  * Folds one more stored revision into `cache`: `hash` joins its subject's
- * `hashes` set, and `revision.parents` (canonicalized, see
- * {@link canonicalHash}) join its `parents` set. Order independent (see the
- * module doc) — used both for a full-store scan and for a single
- * incremental `add`.
+ * `hashes` set, `revision.parents` (canonicalized, see {@link canonicalHash})
+ * join its `parents` set, and `hash` also joins the `archived` set when the
+ * revision carries `archived: true`. Order independent (see the module doc) —
+ * used both for a full-store scan and for a single incremental `add`.
  *
  * Looks `revision.subject` up via {@link at} (own-property only), not plain
  * bracket indexing: a subject is an arbitrary caller-supplied string
@@ -96,6 +124,7 @@ const addRevisionToCache = (hash, revision) => (cache) => {
     const state = {
         hashes: union(existing.hashes)([hash]),
         parents: union(existing.parents)(revision.parents.map(canonicalHash)),
+        archived: union(existing.archived)(revision.archived === undefined ? [] : [hash]),
     };
     return { bySubject: { ...cache.bySubject, [revision.subject]: state } };
 };
@@ -407,9 +436,13 @@ export const readRevision = (cas) => (hash) => {
 };
 /** Builds the {@link Evo} API over `cas`, backed by the cache at `cacheKey` (see {@link initEvo}). */
 export const evo = (cas) => (cacheKey) => ({
-    list: () => eff(read(cacheKey))
-        .step(cache => pure(definedEntries(cache.bySubject).map(([subject]) => subject)))
-        .value,
+    list: archived => {
+        const listed = subjectListed(archived);
+        return eff(read(cacheKey))
+            .step(cache => pure(definedEntries(cache.bySubject)
+            .flatMap(([subject, state]) => listed(state) ? [subject] : [])))
+            .value;
+    },
     head: subject => eff(read(cacheKey))
         .step(cache => {
         const state = at(subject)(cache.bySubject);

package/fjs/cas/evo/proof.f.d.ts

@@ -9,6 +9,10 @@ export declare const proof: {
     buildCacheOrderIndependentWhenChildScannedBeforeParent: () => void;
     buildCacheCanonicalizesNonCanonicalParentHashes: () => void;
     addRevisionBuildsHeadsAcrossChainAndFork: () => void;
+    listPartitionsSubjectsByHeadArchivedFlag: () => void;
+    listTreatsDisagreeingHeadsAsActive: () => void;
+    listIgnoresArchivedRevisionsThatAreNoLongerHeads: () => void;
+    listExcludesSubjectWithNoCurrentHeads: () => void;
     addRevisionIdempotentOnDuplicateContent: () => void;
     addRevisionCanonicalizesParentSpellingBeforeSerializing: () => void;
     addRevisionResolvesSubjectFromSingleParent: () => void;

package/fjs/cas/evo/proof.f.js

@@ -183,6 +183,87 @@ export const proof = {
         assertEq(subjects.length, 1);
         assertEq(subjects[0], 'doc');
     },
+    // `list()` and `list(true)` partition subjects by the archived flags of
+    // their current heads: a lone root revision carrying `archived: true`
+    // makes its subject archived, one without it leaves the subject active,
+    // and neither subject appears in the other's result.
+    listPartitionsSubjectsByHeadArchivedFlag: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const [state1, live] = virtual(state0)(e.add({ parents: [], subject: 'live', snapshot: vecToCBase32(vec8(0x40n)) }));
+        assert(live[0] === 'ok', ['expected the active add to succeed', live]);
+        const [state2, gone] = virtual(state1)(e.add({ parents: [], subject: 'gone', snapshot: vecToCBase32(vec8(0x41n)), archived: true }));
+        assert(gone[0] === 'ok', ['expected the archived add to succeed', gone]);
+        const [state3, active] = virtual(state2)(e.list());
+        assertEq(active.length, 1);
+        assertEq(active[0], 'live');
+        const [, archived] = virtual(state3)(e.list(true));
+        assertEq(archived.length, 1);
+        assertEq(archived[0], 'gone');
+    },
+    // Concurrent heads can disagree about `archived`. One unarchived head
+    // keeps the whole subject active — there is still a head left to build on
+    // — so the subject stays out of the archived-only result.
+    listTreatsDisagreeingHeadsAsActive: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const [state1, root] = virtual(state0)(e.add({ parents: [], subject: 'doc', snapshot: vecToCBase32(vec8(0x42n)) }));
+        assert(root[0] === 'ok', ['expected root ok', root]);
+        // The two children differ only in `archived`, which is enough to make
+        // them distinct blobs, hence two concurrent heads of one root.
+        const [state2, kept] = virtual(state1)(e.add({ parents: [root[1]], subject: 'doc' }));
+        assert(kept[0] === 'ok', ['expected the unarchived child ok', kept]);
+        const [state3, dropped] = virtual(state2)(e.add({ parents: [root[1]], subject: 'doc', archived: true }));
+        assert(dropped[0] === 'ok', ['expected the archived child ok', dropped]);
+        const [state4, heads] = virtual(state3)(e.head('doc'));
+        assertEq(heads.length, 2);
+        const [state5, active] = virtual(state4)(e.list());
+        assertEq(active.length, 1);
+        assertEq(active[0], 'doc');
+        const [, archived] = virtual(state5)(e.list(true));
+        assertEq(archived.length, 0);
+    },
+    // `archived` is a property of a revision, not of a subject: a subject
+    // archived at one revision is active again as soon as an unarchived child
+    // demotes that revision out of the head set.
+    listIgnoresArchivedRevisionsThatAreNoLongerHeads: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const [state1, root] = virtual(state0)(e.add({ parents: [], subject: 'doc', snapshot: vecToCBase32(vec8(0x45n)), archived: true }));
+        assert(root[0] === 'ok', ['expected the archived root ok', root]);
+        const [state2, revived] = virtual(state1)(e.add({ parents: [root[1]], subject: 'doc' }));
+        assert(revived[0] === 'ok', ['expected the unarchived child ok', revived]);
+        const [state3, active] = virtual(state2)(e.list());
+        assertEq(active.length, 1);
+        assertEq(active[0], 'doc');
+        const [, archived] = virtual(state3)(e.list(true));
+        assertEq(archived.length, 0);
+    },
+    // A subject can end up with no current head at all, and a status is a
+    // statement about heads — so such a subject is neither active nor
+    // archived and belongs to neither result. Nothing verifies that a stored
+    // blob actually hashes to the key it sits under, so a hand-crafted or
+    // corrupt store can present a revision naming its own hash as its parent;
+    // `fixedCas` reproduces exactly that, which a real `fileCas` cannot.
+    listExcludesSubjectWithNoCurrentHeads: () => {
+        const selfHash = vec8(0x43n);
+        const snapshotHash = vecToCBase32(vec8(0x44n));
+        const text = `{"dialect":"${revisionDialect}","subject":"doc","parents":["${vecToCBase32(selfHash)}"],"snapshot":"${snapshotHash}","generation":1}`;
+        const bytes = tryUtf8(text);
+        assert(bytes !== null, 'expected the sample revision text to encode as UTF-8');
+        const cas = fixedCas([[selfHash, bytes]]);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(cas));
+        const e = evo(cas)(cacheKey);
+        const [state1, heads] = virtual(state0)(e.head('doc'));
+        assertEq(heads.length, 0);
+        const [state2, active] = virtual(state1)(e.list());
+        assertEq(active.length, 0);
+        const [, archived] = virtual(state2)(e.list(true));
+        assertEq(archived.length, 0);
+    },
     // Adding the exact same revision twice yields the same (deduplicated)
     // content hash and must not duplicate the head entry.
     addRevisionIdempotentOnDuplicateContent: () => {

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

@@ -18,19 +18,19 @@ export declare const images: {
         readonly arm: 'windows-11-arm';
     };
 };
-export declare const functionalscript: '0.38.0';
+export declare const functionalscript: '0.39.0';
 export declare const bun = "1.3.14";
 export declare const deno = "2.9.4";
 export declare const node: {
     readonly default: '26.5.1';
-    readonly node22: '22.23.1';
+    readonly node22: '22.23.2';
     readonly node24: '24.18.0';
 };
 export declare const nixpkgs: {
     readonly ref: 'nixos-26.05';
-    readonly commit: '21ea275a7c46aef9d4d6ddc962e6d562e9d94183';
+    readonly commit: '6d65bfc1bcef2ef39a239d38e577e92a89fb0f07';
 };
-export declare const wasmtime = "47.0.2";
+export declare const wasmtime = "47.0.3";
 export declare const wasmer = "7.2.1";
 export declare const actions: {
     readonly 'actions/checkout': 'v7.0.1';

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

@@ -23,7 +23,7 @@ export const images = {
 // published FunctionalScript release; do not tie it to package.json's current
 // in-repo version.
 // https://www.npmjs.com/package/functionalscript
-export const functionalscript = '0.38.0';
+export const functionalscript = '0.39.0';
 // https://bun.sh/
 export const bun = '1.3.14';
 // https://deno.com/
@@ -37,7 +37,7 @@ export const deno = '2.9.4';
 // https://nodejs.org/en/download
 export const node = {
     default: '26.5.1',
-    node22: '22.23.1',
+    node22: '22.23.2',
     node24: '24.18.0',
 };
 // Official Nixpkgs snapshot used by the generated CI flakes. `ref` is the
@@ -47,10 +47,10 @@ export const node = {
 // https://channels.nixos.org/nixos-26.05/git-revision
 export const nixpkgs = {
     ref: 'nixos-26.05',
-    commit: '21ea275a7c46aef9d4d6ddc962e6d562e9d94183',
+    commit: '6d65bfc1bcef2ef39a239d38e577e92a89fb0f07',
 };
 // https://github.com/bytecodealliance/wasmtime/releases
-export const wasmtime = '47.0.2';
+export const wasmtime = '47.0.3';
 // https://github.com/wasmerio/wasmer/releases
 export const wasmer = '7.2.1';
 // GitHub Action versions used by CI step builders. The key is the action

package/fjs/ci/node/proof.f.d.ts

@@ -0,0 +1,3 @@
+export declare const proof: {
+    basicNode: () => void;
+};

package/fjs/ci/node/proof.f.js

@@ -0,0 +1,17 @@
+import { basicNode } from './module.f.js';
+import { test } from '../common/module.f.js';
+import { assertEq } from '../../asserts/module.f.js';
+export const proof = {
+    basicNode: () => {
+        const extra = [test({ run: 'echo extra' })];
+        const steps = basicNode('22.0.0')(extra);
+        assertEq(steps.length, 3);
+        const [setupNode, npmCi, extraStep] = steps;
+        assertEq(setupNode.type, 'install');
+        assertEq(setupNode.type === 'install' ? setupNode.step.uses : undefined, 'actions/setup-node@v7.0.0');
+        assertEq(setupNode.type === 'install' ? setupNode.step.with?.['node-version'] : undefined, '22.0.0');
+        assertEq(npmCi.type, 'test');
+        assertEq(npmCi.type === 'test' ? npmCi.step.run : undefined, 'npm ci');
+        assertEq(extraStep, extra[0]);
+    },
+};

package/fjs/effects/module.f.d.ts

@@ -379,6 +379,26 @@ export type MatchResult<O extends Operation, T, R> = readonly ['done', T] | read
  * with the continuation. The one world-specific step — `await` for async
  * runners, state threading for sync ones — is left to the caller, so every
  * interpreter loop is this skeleton plus a single eliminator line.
+ *
+ * **The handler is looked up with `at`, never with `map[command]`.**
+ * `OperationMap<O, R>` pins `command` to `O[0]` at the type level, but a `Do`
+ * node's `command` is runtime data — it can reach an interpreter from a decoded
+ * payload or a deserialized continuation, where no type ever constrained it.
+ * `map` is an ordinary object, so a plain index read resolves an inherited name
+ * (`'constructor'`, `'toString'`, `'hasOwnProperty'`) to the `Object.prototype`
+ * member instead of `undefined`, and the line below would then call it with the
+ * node's payload: a value the type system promised was `(...payload) => R` turns
+ * out to be an arbitrary inherited function, chosen by the same input that
+ * supplies its arguments. `at` reads through `getOwnPropertyDescriptor`, which
+ * only ever sees own properties, so such a command yields `null` and never a
+ * callable.
+ *
+ * A `null` handler is an invariant violation, not an outcome: every `O1 extends
+ * O` the signature admits has its command in `map`, so reaching it means the
+ * node's `command` was never the `O1[0]` it claimed to be. It therefore throws
+ * (`assert`) rather than widening {@link MatchResult} with a variant no
+ * type-correct caller could ever observe — a runner cannot resume a command it
+ * has no handler for, so there is nothing for a recovery branch to do.
  */
 export declare const match: <O extends Operation, R>(map: OperationMap<O, R>) => <O1 extends O, T>(e: Effect<O1, T>) => MatchResult<O1, T, R>;
 export type ToAsyncOperationMap<O extends Operation> = {

package/fjs/effects/module.f.js

@@ -94,7 +94,9 @@
  *
  * @module
  */
+import { assert } from '../asserts/module.f.js';
 import { fold } from '../types/list/module.f.js';
+import { at } from '../types/object/module.f.js';
 export const pure = (v) => () => v;
 /**
  * Composes effects: run `e`, then continue with `f` applied to its result.
@@ -278,11 +280,33 @@ export const runPure = (e) => typeof e === 'function' ? [e()] : [];
  * with the continuation. The one world-specific step — `await` for async
  * runners, state threading for sync ones — is left to the caller, so every
  * interpreter loop is this skeleton plus a single eliminator line.
+ *
+ * **The handler is looked up with `at`, never with `map[command]`.**
+ * `OperationMap<O, R>` pins `command` to `O[0]` at the type level, but a `Do`
+ * node's `command` is runtime data — it can reach an interpreter from a decoded
+ * payload or a deserialized continuation, where no type ever constrained it.
+ * `map` is an ordinary object, so a plain index read resolves an inherited name
+ * (`'constructor'`, `'toString'`, `'hasOwnProperty'`) to the `Object.prototype`
+ * member instead of `undefined`, and the line below would then call it with the
+ * node's payload: a value the type system promised was `(...payload) => R` turns
+ * out to be an arbitrary inherited function, chosen by the same input that
+ * supplies its arguments. `at` reads through `getOwnPropertyDescriptor`, which
+ * only ever sees own properties, so such a command yields `null` and never a
+ * callable.
+ *
+ * A `null` handler is an invariant violation, not an outcome: every `O1 extends
+ * O` the signature admits has its command in `map`, so reaching it means the
+ * node's `command` was never the `O1[0]` it claimed to be. It therefore throws
+ * (`assert`) rather than widening {@link MatchResult} with a variant no
+ * type-correct caller could ever observe — a runner cannot resume a command it
+ * has no handler for, so there is nothing for a recovery branch to do.
  */
 export const match = (map) => (e) => {
     if (typeof e === 'function') {
         return ['done', e()];
     }
     const { command, payload, continuation } = e;
-    return ['cont', map[command](...payload), continuation];
+    const handler = at(command)(map);
+    assert(handler !== null, command);
+    return ['cont', handler(...payload), continuation];
 };

package/fjs/effects/proof.f.d.ts

@@ -31,6 +31,11 @@ export declare const proof: {
     match: {
         done: () => void;
         cont: () => void;
+        ownCommand: () => void;
+        throw: {
+            constructorCommand: () => void;
+            toStringCommand: () => void;
+        };
     };
     step: {
         pure: () => void;

package/fjs/effects/proof.f.js

@@ -15,6 +15,7 @@ export const assertPure = (e, expected) => {
     assertEq(o[0], expected);
 };
 const next = match({ add: (a, b) => a + b });
+const anyNext = match({ add: a => a + 1 });
 export const proof = {
     foldStep: {
         empty: () => {
@@ -103,6 +104,27 @@ export const proof = {
             assert(r2[0] === 'done', r2);
             assertEq(r2[1], 5);
         },
+        ownCommand: () => {
+            // The same map the two cases below dispatch against: an own
+            // property still resolves, so what they prove is refusal of
+            // inherited names, not a map that dispatches nothing.
+            const r = anyNext(do_('add')(41));
+            assert(r[0] === 'cont', r);
+            assertEq(r[1], 42);
+        },
+        // A `command` naming an `Object.prototype` member must not dispatch to
+        // the inherited value. `map['constructor']` is `Object` and
+        // `map['toString']` is `Function.prototype.toString` — both callable,
+        // neither a handler — so a plain index read would call one of them with
+        // the node's payload instead of throwing.
+        throw: {
+            constructorCommand: () => {
+                anyNext(do_('constructor')(1));
+            },
+            toStringCommand: () => {
+                anyNext(do_('toString')(1));
+            },
+        },
     },
     step: {
         pure: () => {

package/fjs/mcp/evo/module.f.d.ts

@@ -2,8 +2,13 @@ import { type Operation } from '../../effects/module.f.ts';
 import { type MemOp } from '../../effects/memory/module.f.ts';
 import { type ToolEntry } from '../../protocol/mcp/module.f.ts';
 import { type Evo } from '../../cas/evo/module.f.ts';
-/** Arguments for `evo_list`: none. */
-export declare const evoListArgs: {};
+/**
+ * Arguments for `evo_list`: an optional status filter, forwarded unchanged to
+ * `Evo.list` — omitted lists the active subjects, `true` the archived ones.
+ */
+export declare const evoListArgs: {
+    readonly archived: import("../../types/rtti/module.f.ts").Or<readonly [true, undefined]>;
+};
 /** Arguments for `evo_head`: the subject whose current heads are requested. */
 export declare const evoHeadArgs: {
     readonly subject: import("../../types/rtti/module.f.ts").String;

package/fjs/mcp/evo/module.f.js

@@ -8,7 +8,7 @@
  *
  * | Tool           | args                                          | action            | result                               |
  * |----------------|-----------------------------------------------|-------------------|--------------------------------------|
- * | `evo_list`     | `{}`                                          | `e.list()`        | subjects, as a JSON array of strings |
+ * | `evo_list`     | `{ archived? }`                               | `e.list(...)`     | subjects, as a JSON array of strings |
  * | `evo_head`     | `{ subject }`                                 | `e.head(...)`     | head hashes, one per line            |
  * | `evo_revision` | `{ hash }`                                    | `e.revision(...)` | the revision, as JSON `RevisionData` |
  * | `evo_add`      | `{ parents, snapshot?, subject?, archived? }`  | `e.add(...)`      | hash (cBase32)                       |
@@ -51,8 +51,13 @@ import { stringify } from '../../media/json/module.f.js';
 import { identity } from '../../types/function/module.f.js';
 import {} from '../../cas/evo/module.f.js';
 // ── Argument schemas (declared once, used for both inputSchema and validate) ─────
-/** Arguments for `evo_list`: none. */
-export const evoListArgs = {};
+/**
+ * Arguments for `evo_list`: an optional status filter, forwarded unchanged to
+ * `Evo.list` — omitted lists the active subjects, `true` the archived ones.
+ */
+export const evoListArgs = {
+    archived: option(true),
+};
 /** Arguments for `evo_head`: the subject whose current heads are requested. */
 export const evoHeadArgs = {
     subject: string,
@@ -77,12 +82,12 @@ export const evoAddArgs = {
 const toJson = stringify(identity);
 /** Registry of all Evo tools, bound to an `Evo<O>`. */
 export const evoToolRegistry = (e) => [
-    toolEntry('evo_list', 'List all subjects with at least one stored revision, as a JSON array of strings.', evoListArgs, 
+    toolEntry('evo_list', 'List subjects, as a JSON array of strings. By default only the active ones: a subject is active while at least one of its current heads is not archived. Pass `archived: true` to list the archived subjects instead — those with at least one current head, all of them archived. A subject with no current heads is in neither list.', evoListArgs, 
     // Subjects are arbitrary caller-supplied strings (unlike hashes, not
     // constrained to a newline-free alphabet), so a `join('\n')` line
     // format could not represent an empty subject or one containing a
     // newline without ambiguity — JSON encoding can.
-    () => step(e.list(), subjects => pure(okResult(toJson(subjects))))),
+    ({ archived }) => step(e.list(archived), subjects => pure(okResult(toJson(subjects))))),
     toolEntry('evo_head', 'List the current head hashes (cBase32) of a subject, one per line. Empty when the subject is unknown.', evoHeadArgs, ({ subject }) => step(e.head(subject), heads => pure(okResult(heads.join('\n'))))),
     toolEntry('evo_revision', 'Read one revision by hash, as JSON: `{ subject, parents, snapshot, generation, archived? }`. `parents[0]` is the mainline parent and every further entry is a merged-in branch; `parents` and `snapshot` come back in their canonical cBase32 spelling, so they compare directly against `evo_head` output. Errors when the hash is not cBase32, is not present in the store, could not be read, or does not hold a `vnd.fjs.revision` blob — use `cas_get` for raw bytes of non-revision content.', evoRevisionArgs, 
     // The revision goes out as JSON in a text content item, like

package/fjs/mcp/evo/proof.f.d.ts

@@ -2,6 +2,7 @@ export declare const proof: {
     toolNamesMatchTheDesign: () => void;
     evoListReflectsTheCache: () => void;
     evoListEncodesArbitrarySubjectsAsJson: () => void;
+    evoListForwardsTheArchivedFilter: () => void;
     evoHeadReflectsTheCache: () => void;
     evoHeadMissingSubjectIsInvalidArguments: () => void;
     evoRevisionReturnsRevisionJson: () => void;

package/fjs/mcp/evo/proof.f.js

@@ -57,6 +57,22 @@ export const proof = {
         assert(subjects.includes('line one\nline two'), ['unexpected subjects', subjects]);
         assert(subjects.includes(''), ['unexpected subjects', subjects]);
     },
+    // The `archived` argument is a pass-through to `Evo.list`'s status filter:
+    // omitted lists the active subjects, `true` the archived ones.
+    evoListForwardsTheArchivedFilter: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const [state1, add] = virtual(state0)(e.add({ parents: [], subject: 'gone', snapshot: vecToCBase32(vec8(0x2cn)), archived: true }));
+        assert(add[0] === 'ok', ['expected add ok', add]);
+        const entry = findEntry(evoToolRegistry(e), 'evo_list');
+        const [state2, active] = virtual(state1)(entry.handle({}));
+        assert(!active.isError);
+        assertEq(textOf(active), '[]');
+        const [, archived] = virtual(state2)(entry.handle({ archived: true }));
+        assert(!archived.isError);
+        assertEq(textOf(archived), '["gone"]');
+    },
     evoHeadReflectsTheCache: () => {
         const c = fileCas(sha256)(home);
         const [state0, cacheKey] = virtual(emptyState)(initEvo(c));

package/fjs/mcp/module.f.d.ts

@@ -14,7 +14,7 @@
  * | `cas_add`      | `{ content, type? }`                          | `c.write(...)`   | hash (cBase32)                      |
  * | `cas_get`      | `{ hash, content?: boolean }`                 | `c.read(key)`    | JSON `{length,mimeType,type[,uri][,text\|blob]}` |
  * | `cas_list`     | `{}`                                          | `c.list()`       | hashes, one per line                |
- * | `evo_list`     | `{}`                                          | `e.list()`       | subjects, one per line              |
+ * | `evo_list`     | `{ archived? }`                               | `e.list(...)`    | subjects, as a JSON array of strings |
  * | `evo_head`     | `{ subject }`                                 | `e.head(...)`    | head hashes, one per line           |
  * | `evo_revision` | `{ hash }`                                    | `e.revision(...)`| the revision, as JSON               |
  * | `evo_add`      | `{ parents, snapshot?, subject?, archived? }` | `e.add(...)`     | hash (cBase32)                      |

package/fjs/mcp/module.f.js

@@ -14,7 +14,7 @@
  * | `cas_add`      | `{ content, type? }`                          | `c.write(...)`   | hash (cBase32)                      |
  * | `cas_get`      | `{ hash, content?: boolean }`                 | `c.read(key)`    | JSON `{length,mimeType,type[,uri][,text\|blob]}` |
  * | `cas_list`     | `{}`                                          | `c.list()`       | hashes, one per line                |
- * | `evo_list`     | `{}`                                          | `e.list()`       | subjects, one per line              |
+ * | `evo_list`     | `{ archived? }`                               | `e.list(...)`    | subjects, as a JSON array of strings |
  * | `evo_head`     | `{ subject }`                                 | `e.head(...)`    | head hashes, one per line           |
  * | `evo_revision` | `{ hash }`                                    | `e.revision(...)`| the revision, as JSON               |
  * | `evo_add`      | `{ parents, snapshot?, subject?, archived? }` | `e.add(...)`     | hash (cBase32)                      |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functionalscript",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "type": "module",
   "files": [
     "**/*.js",