functionalscript 0.39.0 → 0.41.0

package/README.md

@@ -60,7 +60,7 @@ The CAS is also exposed as an [MCP](https://modelcontextprotocol.io/) server so
 claude mcp add cas -- npx functionalscript m
 ```
 
-See [`fjs/cas/mcp/README.md`](fjs/cas/mcp/README.md) for details on the `cas_add`, `cas_get`, and `cas_list` tools.
+See [`fjs/mcp/README.md`](fjs/mcp/README.md) for details on the `cas_add`, `cas_get`, and `cas_list` tools.
 
 ## Vision
 

package/fjs/bnf/descent/module.f.d.ts

@@ -7,9 +7,14 @@
  * AST ({@link AstRuleMeta}). Nullability (which rule can match empty input) is
  * computed once by {@link emptyTagMap} in `fjs/bnf/data`.
  *
+ * A failed result also carries a {@link DescentFailure}: the furthest position a
+ * terminal was rejected at, which — unlike the result's own index — never
+ * rewinds and is what diagnostics should be built from.
+ *
  * @module
  */
 import { type CodePoint } from '../../text/utf16/module.f.ts';
+import { type TerminalRange } from '../module.f.ts';
 import { type Rule as FRule } from '../module.f.ts';
 export type AstTag = string | true | undefined;
 /**
@@ -17,9 +22,45 @@ export type AstTag = string | true | undefined;
  */
 export type DescentMatchRule<T> = (name: string, tag: AstTag, s: readonly CodePointMeta<T>[], idx: number) => DescentMatchResult<T>;
 /**
- * Result tuple of a descent match operation: AST node, success flag, and next index.
+ * Where a match ran out of road, for diagnostics.
+ *
+ * `idx` is the furthest position any terminal was tried at and rejected, and
+ * `expected` holds the terminals that would have allowed progress there, in the
+ * order the grammar tried them and without repeats.
+ *
+ * Unlike a failed result's own index, this never rewinds: a failing sequence
+ * item rewinds the result to the sequence's start, while the furthest failure is
+ * a high-water mark over the whole match — including branches the grammar
+ * backtracked out of. That is what makes "expected X or Y at N" possible.
+ *
+ * `idx` is `0` with an empty `expected` when the match failed without ever
+ * rejecting a terminal, as an empty variant does.
  */
-export type DescentMatchResult<T> = readonly [AstRuleMeta<T>, boolean, number];
+export type DescentFailure = {
+    readonly idx: number;
+    readonly expected: readonly TerminalRange[];
+};
+/**
+ * Result of a descent match operation.
+ *
+ * `failure` is present exactly when `success` is `false`: a successful match has
+ * nothing to diagnose, and its `idx` already says where matching stopped. Note
+ * the consequence for a match that succeeds *without consuming all input* —
+ * `idx` still locates the position it stopped at, but the terminals that would
+ * have let it continue are not reported.
+ *
+ * On failure `idx` has rewound to the start of the enclosing sequence and
+ * locates nothing; read `failure.idx` instead.
+ *
+ * The same type describes a match in progress, where `failure` is likewise
+ * absent until the match ends.
+ */
+export type DescentMatchResult<T> = {
+    readonly ast: AstRuleMeta<T>;
+    readonly success: boolean;
+    readonly idx: number;
+    readonly failure?: DescentFailure;
+};
 /**
  * Entry-point recursive descent matcher.
  */

package/fjs/bnf/descent/module.f.js

@@ -7,6 +7,10 @@
  * AST ({@link AstRuleMeta}). Nullability (which rule can match empty input) is
  * computed once by {@link emptyTagMap} in `fjs/bnf/data`.
  *
+ * A failed result also carries a {@link DescentFailure}: the furthest position a
+ * terminal was rejected at, which — unlike the result's own index — never
+ * rewinds and is what diagnostics should be built from.
+ *
  * @module
  */
 import {} from '../../text/utf16/module.f.js';
@@ -15,6 +19,20 @@ import { contains as rangeContains } from '../../types/range/module.f.js';
 import { definedEntries } from '../../types/object/module.f.js';
 import { emptyTagMap, toData } from '../data/module.f.js';
 import {} from '../module.f.js';
+/**
+ * Folds one rejected terminal into the furthest-failure record: further along
+ * replaces, the same position accumulates (ignoring repeats), earlier is
+ * discarded.
+ */
+const recordFailure = (failure, idx, terminal) => {
+    if (idx > failure.idx) {
+        return { idx, expected: [terminal] };
+    }
+    if (idx < failure.idx || failure.expected.includes(terminal)) {
+        return failure;
+    }
+    return { idx, expected: [...failure.expected, terminal] };
+};
 /**
  * Creates a recursive descent parser that preserves metadata for each consumed
  * code point.
@@ -29,11 +47,14 @@ export const descentParser = (fr) => {
     // grammar recursion depth — right-recursive rules (e.g. repeat0Plus chains) no longer
     // overflow on long input (see the longInput proof group).
     const f = (name, tag, cp, idx) => {
-        const mrSuccess = (tag, sequence, idx) => [{ tag, sequence }, true, idx];
-        const mrFail = (tag, sequence, idx) => [{ tag, sequence }, false, idx];
+        const mrSuccess = (tag, sequence, idx) => ({ ast: { tag, sequence }, success: true, idx });
+        const mrFail = (tag, sequence, idx) => ({ ast: { tag, sequence }, success: false, idx });
         let stack = null;
         let task = { name, tag, idx };
         let result = mrFail(undefined, [], idx);
+        // High-water mark across the whole match, so it survives the rewinds a
+        // failing sequence item does to `result`.
+        let furthest = { idx: 0, expected: [] };
         while (true) {
             if (task !== null) {
                 const { name, tag, idx } = task;
@@ -43,14 +64,17 @@ export const descentParser = (fr) => {
                 // later `task` assignments that `name`'s narrowing depends on.
                 const rule = data[0][name];
                 if (typeof rule === 'number') {
-                    const emptyTag = emptyTags[name];
-                    if (idx >= cp.length) {
-                        result = emptyTag === undefined ? mrFail(emptyTag, [], idx) : mrSuccess(emptyTag, [], idx);
+                    // No nullable case: `emptyTagOf` in `bnf/data` returns `undefined`
+                    // for every terminal, so `emptyTags[name]` here is always
+                    // `undefined` and a terminal either consumes one symbol or fails.
+                    if (idx < cp.length && rangeContains(...rangeDecode(rule))(cp[idx][0])) {
+                        result = mrSuccess(tag, [cp[idx]], idx + 1);
                     }
                     else {
-                        const cpi = cp[idx];
-                        const range = rangeDecode(rule);
-                        result = rangeContains(...range)(cpi[0]) ? mrSuccess(tag, [cpi], idx + 1) : mrFail(emptyTag, [], idx);
+                        // The only place a terminal is rejected, so the only place
+                        // the furthest failure can advance.
+                        furthest = recordFailure(furthest, idx, rule);
+                        result = mrFail(undefined, [], idx);
                     }
                 }
                 else if (rule instanceof Array) {
@@ -78,12 +102,13 @@ export const descentParser = (fr) => {
                 continue;
             }
             if (stack === null) {
-                return result;
+                // A success has nothing to diagnose; only a failure carries it.
+                return result.success ? result : { ...result, failure: furthest };
             }
             const frame = stack.top;
             stack = stack.rest;
             if (frame.kind === 'seq') {
-                const [astRule, success, nidx] = result;
+                const { ast: astRule, success, idx: nidx } = result;
                 if (success === false) {
                     result = mrFail(frame.tag, [], frame.startIdx);
                 }
@@ -102,8 +127,8 @@ export const descentParser = (fr) => {
             else {
                 // success that consumed input wins immediately: the frame stays popped and
                 // `result` propagates to the frame below, matching the recursive `return m`.
-                if (!(result[1] && frame.idx !== result[2])) {
-                    const emptyResult = result[1] ? result : frame.emptyResult;
+                if (!(result.success && frame.idx !== result.idx)) {
+                    const emptyResult = result.success ? result : frame.emptyResult;
                     const entryIndex = frame.entryIndex + 1;
                     if (entryIndex < frame.entries.length) {
                         stack = { top: { ...frame, entryIndex, emptyResult }, rest: stack };

package/fjs/bnf/descent/proof.f.d.ts

@@ -3,4 +3,5 @@ export declare const proof: {
     descentParser: (() => void)[];
     longInput: (() => void)[];
     descentParserWithMeta: (() => void)[];
+    furthestFailure: (() => void)[];
 };

package/fjs/bnf/descent/proof.f.js

@@ -4,8 +4,12 @@ import { commaJoin0Plus, option, range, repeat0Plus, set } from '../module.f.js'
 import { deterministic } from '../testlib.f.js';
 import { emptyTagMap, toData } from '../data/module.f.js';
 import { descentParser } from './module.f.js';
-import { assertEq } from '../../asserts/module.f.js';
+import { assertEq, assertNotNullish } from '../../asserts/module.f.js';
 const mapCodePoint = (cp) => [cp, undefined];
+// The code point of a one-character string, for expectations that would
+// otherwise spell it as a bare number. Goes through the module's own
+// conversion, the same one that builds the parser's input.
+const cp1 = (s) => toArray(stringToCodePointList(s))[0];
 const descentParserCpOnly = (m, name, cp) => {
     const cpm = toArray(map(mapCodePoint)(cp));
     return m(name, cpm);
@@ -83,52 +87,59 @@ export const proof = {
             const m = descentParser(emptyRule);
             const mr = m("", []);
             const result = JSON.stringify(mr);
-            if (result !== '[{"sequence":[]},true,0]') {
+            if (result !== '{"ast":{"sequence":[]},"success":true,"idx":0}') {
                 throw result;
             }
         },
         () => {
             const emptyRule = '';
             const m = descentParser(emptyRule);
-            const mr = descentParserCpOnly(m, "", [65, 70]);
+            const mr = descentParserCpOnly(m, "", toArray(stringToCodePointList('AF')));
             const result = JSON.stringify(mr);
-            if (result !== '[{"sequence":[]},true,0]') {
+            if (result !== '{"ast":{"sequence":[]},"success":true,"idx":0}') {
                 throw result;
             }
         },
         () => {
+            // Literal code point on purpose. Elsewhere both sides of the
+            // assertion come from `stringToCodePointList` — the input is built
+            // with it and the expectation interpolates `cp1`, which calls it
+            // too — so a change to the conversion would move both sides
+            // together and the test would still pass. Pinning `A` to 65 here
+            // covers the conversion itself.
             const terminalRangeRule = range('AF');
             const m = descentParser(terminalRangeRule);
-            const mr = descentParserCpOnly(m, "", [65]);
+            const mr = descentParserCpOnly(m, "", toArray(stringToCodePointList('A')));
             const result = JSON.stringify(mr);
-            if (result !== '[{"sequence":[[65,null]]},true,1]') {
+            if (result !== '{"ast":{"sequence":[[65,null]]},"success":true,"idx":1}') {
                 throw result;
             }
         },
         () => {
             const terminalRangeRule = range('AF');
             const m = descentParser(terminalRangeRule);
-            const mr = descentParserCpOnly(m, "", [64]);
+            const mr = descentParserCpOnly(m, "", toArray(stringToCodePointList('@')));
             const result = JSON.stringify(mr);
-            if (result !== '[{"sequence":[]},false,0]') {
+            if (result !== `{"ast":{"sequence":[]},"success":false,"idx":0,"failure":{"idx":0,"expected":[${range('AF')}]}}`) {
                 throw result;
             }
         },
         () => {
             const variantRule = { 'a': range('AA'), 'b': range('BB') };
             const m = descentParser(variantRule);
-            const mr = descentParserCpOnly(m, "", [65]);
+            const mr = descentParserCpOnly(m, "", toArray(stringToCodePointList('A')));
             const result = JSON.stringify(mr);
-            if (result !== '[{"tag":"a","sequence":[[65,null]]},true,1]') {
+            if (result !== `{"ast":{"tag":"a","sequence":[[${cp1('A')},null]]},"success":true,"idx":1}`) {
                 throw result;
             }
         },
         () => {
             const variantRule = { 'a': range('AA'), 'b': range('BB') };
             const m = descentParser(variantRule);
-            const mr = descentParserCpOnly(m, "", [64]);
+            const mr = descentParserCpOnly(m, "", toArray(stringToCodePointList('@')));
             const result = JSON.stringify(mr);
-            if (result !== '[{"sequence":[]},false,0]') {
+            // Both branches were rejected at 0, so both terminals are expected there.
+            if (result !== `{"ast":{"sequence":[]},"success":false,"idx":0,"failure":{"idx":0,"expected":[${range('AA')},${range('BB')}]}}`) {
                 throw result;
             }
         },
@@ -138,7 +149,7 @@ export const proof = {
             const m = descentParser(variantRule);
             const mr = m("", []);
             const result = JSON.stringify(mr);
-            if (result !== '[{"tag":"e","sequence":[]},true,0]') {
+            if (result !== '{"ast":{"tag":"e","sequence":[]},"success":true,"idx":0}') {
                 throw result;
             }
         },
@@ -146,9 +157,9 @@ export const proof = {
             const emptyRule = '';
             const variantRule = { 'e': emptyRule, 'a': range('AA') };
             const m = descentParser(variantRule);
-            const mr = descentParserCpOnly(m, "", [64]);
+            const mr = descentParserCpOnly(m, "", toArray(stringToCodePointList('@')));
             const result = JSON.stringify(mr);
-            if (result !== '[{"tag":"e","sequence":[]},true,0]') {
+            if (result !== '{"ast":{"tag":"e","sequence":[]},"success":true,"idx":0}') {
                 throw result;
             }
         },
@@ -157,25 +168,29 @@ export const proof = {
             const m = descentParser(emptyVariantRule);
             const mr = m("", []);
             const result = JSON.stringify(mr);
-            if (result !== '[{"sequence":[]},false,0]') {
+            // A variant with no branches fails without ever trying a terminal,
+            // so there is nothing to expect.
+            if (result !== '{"ast":{"sequence":[]},"success":false,"idx":0,"failure":{"idx":0,"expected":[]}}') {
                 throw result;
             }
         },
         () => {
             const stringRule = 'AB';
             const m = descentParser(stringRule);
-            const mr = descentParserCpOnly(m, "", [65, 66]);
+            const mr = descentParserCpOnly(m, "", toArray(stringToCodePointList('AB')));
             const result = JSON.stringify(mr);
-            if (result !== '[{"sequence":[{"sequence":[[65,null]]},{"sequence":[[66,null]]}]},true,2]') {
+            if (result !== `{"ast":{"sequence":[{"sequence":[[${cp1('A')},null]]},{"sequence":[[${cp1('B')},null]]}]},"success":true,"idx":2}`) {
                 throw result;
             }
         },
         () => {
             const stringRule = 'AB';
             const m = descentParser(stringRule);
-            const mr = descentParserCpOnly(m, "", [65, 67]);
+            const mr = descentParserCpOnly(m, "", toArray(stringToCodePointList('AC')));
             const result = JSON.stringify(mr);
-            if (result !== '[{"sequence":[]},false,0]') {
+            // The result index rewound to the sequence's start, but the furthest
+            // failure kept the position where 'B' was actually rejected.
+            if (result !== `{"ast":{"sequence":[]},"success":false,"idx":0,"failure":{"idx":1,"expected":[${range('BB')}]}}`) {
                 throw result;
             }
         },
@@ -186,9 +201,9 @@ export const proof = {
             const digitRule = range('09');
             const numberRule = [optionalMinusRule, digitRule];
             const m = descentParser(numberRule);
-            const mr = descentParserCpOnly(m, "", [50]);
+            const mr = descentParserCpOnly(m, "", toArray(stringToCodePointList('2')));
             const result = JSON.stringify(mr);
-            if (result !== '[{"sequence":[{"tag":"none","sequence":[]},{"sequence":[[50,null]]}]},true,1]') {
+            if (result !== `{"ast":{"sequence":[{"tag":"none","sequence":[]},{"sequence":[[${cp1('2')},null]]}]},"success":true,"idx":1}`) {
                 throw result;
             }
         },
@@ -199,9 +214,9 @@ export const proof = {
             const digitRule = range('09');
             const numberRule = [optionalMinusRule, digitRule];
             const m = descentParser(numberRule);
-            const mr = descentParserCpOnly(m, "", [45, 50]);
+            const mr = descentParserCpOnly(m, "", toArray(stringToCodePointList('-2')));
             const result = JSON.stringify(mr);
-            if (result !== '[{"sequence":[{"tag":"minus","sequence":[[45,null]]},{"sequence":[[50,null]]}]},true,2]') {
+            if (result !== `{"ast":{"sequence":[{"tag":"minus","sequence":[[${cp1('-')},null]]},{"sequence":[[${cp1('2')},null]]}]},"success":true,"idx":2}`) {
                 throw result;
             }
         },
@@ -214,7 +229,8 @@ export const proof = {
             const m = descentParser(numberRule);
             const mr = m("", []);
             const result = JSON.stringify(mr);
-            if (result !== '[{"sequence":[]},false,0]') {
+            // Past the end: '-' and then the digit range were both rejected at 0.
+            if (result !== `{"ast":{"sequence":[]},"success":false,"idx":0,"failure":{"idx":0,"expected":[${range('--')},${range('09')}]}}`) {
                 throw result;
             }
         },
@@ -223,7 +239,7 @@ export const proof = {
             const expect = (s, expected) => {
                 const cp = toArray(stringToCodePointList(s));
                 const mr = descentParserCpOnly(m, '', cp);
-                const success = mr[1] && mr[2] === cp.length;
+                const success = mr.success && mr.idx === cp.length;
                 assertEq(success, expected, mr);
             };
             expect('a', true);
@@ -243,7 +259,7 @@ export const proof = {
             const expect = (s, expected) => {
                 const cp = toArray(stringToCodePointList(s));
                 const mr = descentParserCpOnly(m, 'value', cp);
-                const success = mr[1] && mr[2] === cp.length;
+                const success = mr.success && mr.idx === cp.length;
                 assertEq(success, expected, mr);
             };
             expect('', false);
@@ -257,7 +273,7 @@ export const proof = {
             const expect = (s, expected) => {
                 const cp = toArray(stringToCodePointList(s));
                 const mr = descentParserCpOnly(m, '', cp);
-                const success = mr[1] && mr[2] === cp.length;
+                const success = mr.success && mr.idx === cp.length;
                 assertEq(success, expected, mr);
             };
             expect('   true   ', true);
@@ -293,7 +309,7 @@ export const proof = {
             const name = toData(rule)[1];
             const m = descentParser(rule);
             const cp = toArray(stringToCodePointList(' '.repeat(10000)));
-            const [, ok, idx] = descentParserCpOnly(m, name, cp);
+            const { success: ok, idx } = descentParserCpOnly(m, name, cp);
             assertEq(ok, true);
             assertEq(idx, 10000);
         },
@@ -304,7 +320,7 @@ export const proof = {
             const m = descentParser(deterministic());
             const n = 5000;
             const cp = toArray(stringToCodePointList('['.repeat(n) + ']'.repeat(n)));
-            const [, ok, idx] = descentParserCpOnly(m, '', cp);
+            const { success: ok, idx } = descentParserCpOnly(m, '', cp);
             assertEq(ok, true);
             assertEq(idx, n * 2);
         },
@@ -317,11 +333,36 @@ export const proof = {
             const digitRule = range('09');
             const numberRule = [optionalMinusRule, digitRule];
             const m = descentParser(numberRule);
-            const mr = m("", [[45, 'minus'], [50, 'two']]);
+            const mr = m("", [[cp1('-'), 'minus'], [cp1('2'), 'two']]);
             const result = JSON.stringify(mr);
-            if (result !== '[{"sequence":[{"tag":"minus","sequence":[[45,"minus"]]},{"sequence":[[50,"two"]]}]},true,2]') {
+            if (result !== `{"ast":{"sequence":[{"tag":"minus","sequence":[[${cp1('-')},"minus"]]},{"sequence":[[${cp1('2')},"two"]]}]},"success":true,"idx":2}`) {
                 throw result;
             }
         },
     ],
+    furthestFailure: [
+        () => {
+            // A branch rejected *before* the high-water mark must not pull it back:
+            // `x` gets to index 1 before failing, then `y` fails at 0.
+            const m = descentParser({ x: ['A', 'B'], y: 'B' });
+            const { success: ok, idx, failure } = descentParserCpOnly(m, '', toArray(stringToCodePointList('AC')));
+            assertEq(ok, false);
+            assertEq(idx, 0);
+            // A failed match always carries a failure; that is the contract.
+            const f = assertNotNullish(failure);
+            assertEq(f.idx, 1);
+            assertEq(f.expected.length, 1);
+            assertEq(f.expected[0], range('BB'));
+        },
+        () => {
+            // The same terminal rejected at the same index by two branches is
+            // expected once, not twice.
+            const m = descentParser({ x: ['A', 'B'], y: ['A', 'B', 'C'] });
+            const { failure } = descentParserCpOnly(m, '', toArray(stringToCodePointList('AC')));
+            const f = assertNotNullish(failure);
+            assertEq(f.idx, 1);
+            assertEq(f.expected.length, 1);
+            assertEq(f.expected[0], range('BB'));
+        },
+    ],
 };

package/fjs/bnf/ll1/module.f.js

@@ -55,7 +55,7 @@ export const dispatchMap = (ruleSet) => {
         const rule = ruleSet[name];
         if (typeof rule === 'number') {
             const range = rangeDecode(rule);
-            const dispatch = dispatchOp.fromRange(range)({ tag: undefined, rules: [] });
+            const dispatch = dispatchOp.fromRange({ tag: undefined, rules: [] })(range);
             const dr = { emptyTag: undefined, rangeMap: dispatch };
             return { ...dm, [name]: dr };
         }
@@ -126,7 +126,7 @@ export const parserRuleSet = (ruleSet) => {
             return mrSuccess(emptyTag, [], emptyTag === undefined ? null : cp);
         }
         const [cp0] = cp;
-        const dr = dispatchOp.get(cp0)(rangeMap);
+        const dr = dispatchOp.get(rangeMap)(cp0);
         if (dr === null) {
             return emptyTag === undefined
                 ? mrFail(emptyTag, [], cp)

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 = {
@@ -137,7 +148,7 @@ export declare const initEvo: <O extends Operation>(cas: Cas<O>) => Effect<O | M
  * Folds `value` — bytes already written to a `Cas` at `hash` by some other
  * caller — into the cache at `cacheKey` if it decodes as a `vnd.fjs.revision`
  * ({@link decodeRevisionVec}); a no-op otherwise. `cas_add`/`evo_add`
- * (`fjs/cas/mcp`) are two ways to reach the same store — a plain `cas_add`
+ * (`fjs/mcp`) are two ways to reach the same store — a plain `cas_add`
  * call can store a revision blob without going through {@link addRevision},
  * and this is what keeps the cache honest about it without rescanning the
  * whole store.
@@ -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 } };
 };
@@ -141,7 +170,7 @@ const foldIntoCache = (cacheKey) => (hash) => (revision) => eff(read(cacheKey))
  * Folds `value` — bytes already written to a `Cas` at `hash` by some other
  * caller — into the cache at `cacheKey` if it decodes as a `vnd.fjs.revision`
  * ({@link decodeRevisionVec}); a no-op otherwise. `cas_add`/`evo_add`
- * (`fjs/cas/mcp`) are two ways to reach the same store — a plain `cas_add`
+ * (`fjs/mcp`) are two ways to reach the same store — a plain `cas_add`
  * call can store a revision blob without going through {@link addRevision},
  * and this is what keeps the cache honest about it without rescanning the
  * whole store.
@@ -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;