functionalscript 0.39.0 → 0.41.0

package/fjs/{cas/evo/mcp → 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)                       |
@@ -27,7 +27,7 @@
  * content, so the JSON-RPC serializer escapes it a second time on the way
  * out and a modest result can encode to a much longer line (a subject of
  * quote characters is the worst case). A response whose encoded line exceeds
- * the transport cap is not lost: `fjs/mcp/stdio` retries with a small
+ * the transport cap is not lost: `fjs/protocol/mcp/stdio` retries with a small
  * `-32603` body carrying the request's `id`, so every request still gets a
  * response and the process never crashes. That is the transport's contract
  * for every tool — `cas_get` has proofs for the same double-escaping path —
@@ -35,7 +35,7 @@
  * known only by encoding it, which is the transport's job, and guessing from
  * an unencoded size is exactly the size estimate that must never be made.
  *
- * These tools are not served by their own process: `fjs/cas/mcp` (the same
+ * These tools are not served by their own process: `fjs/mcp` (the same
  * server as `cas_add`/`cas_get`/`cas_list`) builds one `Evo<O>` from its own
  * `Cas<O>` and cache slot, concatenates `evoToolRegistry` onto its own
  * registry, and serves everything from that single process — one `~/.cas/`
@@ -43,16 +43,21 @@
  *
  * @module
  */
-import { string, option, array } from '../../../types/rtti/module.f.js';
-import { pure, step } from '../../../effects/module.f.js';
-import {} from '../../../effects/memory/module.f.js';
-import { toolEntry, errorResult, okResult, } from '../../../mcp/module.f.js';
-import { stringify } from '../../../media/json/module.f.js';
-import { identity } from '../../../types/function/module.f.js';
-import {} from '../module.f.js';
+import { string, option, array } from '../../types/rtti/module.f.js';
+import { pure, step } from '../../effects/module.f.js';
+import {} from '../../effects/memory/module.f.js';
+import { toolEntry, errorResult, okResult, } from '../../protocol/mcp/module.f.js';
+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/{cas/evo/mcp → 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/{cas/evo/mcp → mcp/evo}/proof.f.js

@@ -1,10 +1,10 @@
-import { assert, assertEq } from '../../../asserts/module.f.js';
-import { fileCas } from '../../module.f.js';
-import { sha256 } from '../../../crypto/sha2/module.f.js';
-import { emptyState, virtual } from '../../../effects/node/virtual/module.f.js';
-import { vec8 } from '../../../types/bit_vec/module.f.js';
-import { vecToCBase32 } from '../../../basen/cbase32/module.f.js';
-import { initEvo, evo } from '../module.f.js';
+import { assert, assertEq } from '../../asserts/module.f.js';
+import { fileCas } from '../../cas/module.f.js';
+import { sha256 } from '../../crypto/sha2/module.f.js';
+import { emptyState, virtual } from '../../effects/node/virtual/module.f.js';
+import { vec8 } from '../../types/bit_vec/module.f.js';
+import { vecToCBase32 } from '../../basen/cbase32/module.f.js';
+import { initEvo, evo } from '../../cas/evo/module.f.js';
 import { evoToolRegistry } from './module.f.js';
 const home = '/home/user';
 const findEntry = (registry, name) => {
@@ -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

@@ -1,239 +1,56 @@
-import { unknown, type Unknown } from '../media/json/module.f.ts';
-import type { Ts } from '../types/rtti/ts/module.f.ts';
-import { type Operation, type Effect } from '../effects/module.f.ts';
-import { type Key, type MemOp } from '../effects/memory/module.f.ts';
-import { type Response } from '../media/json/rpc/module.f.ts';
-import type { Type } from '../types/rtti/module.f.ts';
-/** Name + version pair sent in `initialize` requests and responses. */
-export declare const implementation: {
-    readonly name: import("../types/rtti/module.f.ts").String;
-    readonly version: import("../types/rtti/module.f.ts").String;
-};
-export type Implementation = Ts<typeof implementation>;
-/** Server capabilities advertised in the `initialize` response. */
-export declare const serverCapabilities: {
-    readonly tools: import("../types/rtti/module.f.ts").Or<readonly [{
-        readonly listChanged: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").Boolean, undefined]>;
-    }, undefined]>;
-};
-export type ServerCapabilities = Ts<typeof serverCapabilities>;
-/** Params for the `initialize` request. */
-export declare const initializeParams: {
-    readonly protocolVersion: import("../types/rtti/module.f.ts").String;
-    readonly capabilities: typeof unknown;
-    readonly clientInfo: {
-        readonly name: import("../types/rtti/module.f.ts").String;
-        readonly version: import("../types/rtti/module.f.ts").String;
-    };
-};
-export type InitializeParams = Ts<typeof initializeParams>;
-/** Result for the `initialize` request. */
-export declare const initializeResult: {
-    readonly protocolVersion: import("../types/rtti/module.f.ts").String;
-    readonly capabilities: {
-        readonly tools: import("../types/rtti/module.f.ts").Or<readonly [{
-            readonly listChanged: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").Boolean, undefined]>;
-        }, undefined]>;
-    };
-    readonly serverInfo: {
-        readonly name: import("../types/rtti/module.f.ts").String;
-        readonly version: import("../types/rtti/module.f.ts").String;
-    };
-    readonly instructions: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").String, undefined]>;
-};
-export type InitializeResult = Ts<typeof initializeResult>;
-/** Plain-text content item returned by a tool call. */
-export declare const textContent: {
-    readonly type: 'text';
-    readonly text: import("../types/rtti/module.f.ts").String;
-};
-export type TextContent = Ts<typeof textContent>;
-/**
- * A binary resource carried inside an {@link embeddedResource}: a base64
- * `blob`, an addressing `uri`, and an optional `mimeType`. This is MCP's
- * `BlobResource` shape — the idiomatic way to return typed binary content so a
- * `mimeType` travels alongside the bytes and clients know how to route them.
- */
-export declare const blobResource: {
-    readonly uri: import("../types/rtti/module.f.ts").String;
-    readonly mimeType: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").String, undefined]>;
-    readonly blob: import("../types/rtti/module.f.ts").String;
-};
-export type BlobResource = Ts<typeof blobResource>;
-/** An `EmbeddedResource` content item wrapping a {@link blobResource}. */
-export declare const embeddedResource: {
-    readonly type: 'resource';
-    readonly resource: {
-        readonly uri: import("../types/rtti/module.f.ts").String;
-        readonly mimeType: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").String, undefined]>;
-        readonly blob: import("../types/rtti/module.f.ts").String;
-    };
-};
-export type EmbeddedResource = Ts<typeof embeddedResource>;
-/**
- * A single item in a `tools/call` result's `content` array: either plain
- * {@link textContent} or an {@link embeddedResource} for typed binary. The
- * `image` and `audio` variants are not modelled yet.
- */
-export declare const contentItem: import("../types/rtti/module.f.ts").Or<[{
-    readonly type: 'text';
-    readonly text: import("../types/rtti/module.f.ts").String;
-}, {
-    readonly type: 'resource';
-    readonly resource: {
-        readonly uri: import("../types/rtti/module.f.ts").String;
-        readonly mimeType: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").String, undefined]>;
-        readonly blob: import("../types/rtti/module.f.ts").String;
-    };
-}]>;
-export type ContentItem = Ts<typeof contentItem>;
-/**
- * A tool descriptor returned by `tools/list`.
- * `inputSchema` is a JSON Schema object — use `toJsonSchema` to derive it from
- * an rtti schema.
- */
-export declare const tool: {
-    readonly name: import("../types/rtti/module.f.ts").String;
-    readonly description: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").String, undefined]>;
-    readonly inputSchema: typeof unknown;
-};
-export type Tool = Ts<typeof tool>;
-/**
- * Params for the `tools/list` request. `cursor` is an opaque pagination token
- * from a previous `ToolsListResult.nextCursor`.
- */
-export declare const toolsListParams: {
-    readonly cursor: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").String, undefined]>;
-};
-export type ToolsListParams = Ts<typeof toolsListParams>;
-export declare const toolsListResult: {
-    readonly tools: import("../types/rtti/module.f.ts").Type1<"array", {
-        readonly name: import("../types/rtti/module.f.ts").String;
-        readonly description: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").String, undefined]>;
-        readonly inputSchema: typeof unknown;
-    }>;
-    readonly nextCursor: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").String, undefined]>;
-};
-export type ToolsListResult = Ts<typeof toolsListResult>;
-export declare const toolsCallParams: {
-    readonly name: import("../types/rtti/module.f.ts").String;
-    readonly arguments: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").Type1<"record", typeof unknown>, undefined]>;
-};
-export type ToolsCallParams = Ts<typeof toolsCallParams>;
-export declare const toolsCallResult: {
-    readonly content: import("../types/rtti/module.f.ts").Type1<"array", import("../types/rtti/module.f.ts").Or<[{
-        readonly type: 'text';
-        readonly text: import("../types/rtti/module.f.ts").String;
-    }, {
-        readonly type: 'resource';
-        readonly resource: {
-            readonly uri: import("../types/rtti/module.f.ts").String;
-            readonly mimeType: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").String, undefined]>;
-            readonly blob: import("../types/rtti/module.f.ts").String;
-        };
-    }]>>;
-    readonly isError: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").Boolean, undefined]>;
-};
-export type ToolsCallResult = Ts<typeof toolsCallResult>;
-/** Per-method handlers for a hello-world MCP tool server. */
-export type McpHandlers<O extends Operation> = {
-    readonly toolsList: (params: ToolsListParams) => Effect<O, ToolsListResult>;
-    readonly toolsCall: (params: ToolsCallParams) => Effect<O, ToolsCallResult>;
-};
 /**
- * A single declarative tool entry combining metadata, input schema, and type-safe handler.
- *
- * The handler receives pre-validated arguments of type `Ts<inputRtti>`, eliminating the need
- * for manual validation or type casting. All validation is encapsulated in the entry.
- */
-export type ToolEntry<O extends Operation> = {
-    readonly name: string;
-    readonly description: string;
-    readonly inputRtti: Type;
-    readonly handle: (args: Unknown) => Effect<O, ToolsCallResult>;
+ * The FJS MCP server: the composition root the `fjs mcp` / `m` CLI command
+ * runs. Session configuration (`McpConfig`), the top-level entry point
+ * (`casMcpServer`, wiring `mcpStep` + `stdioTransport` from
+ * `fjs/protocol/mcp/`), and the composed tool registry — nothing CAS- or
+ * Evo-specific lives here, it only knows about tool *registries*, not what is
+ * in them, so a future non-CAS tool set can land as a new sibling of
+ * `fjs/mcp/cas/` and `fjs/mcp/evo/` without touching either of them.
+ *
+ * ## Tools
+ *
+ * | Tool           | args                                          | action           | result                              |
+ * |----------------|------------------------------------------------|------------------|--------------------------------------|
+ * | `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`     | `{ 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)                      |
+ *
+ * `cas_add`/`cas_get`/`cas_list` are `fjs/mcp/cas` — see that module for tool
+ * documentation (input encoding, output shape, error convention). `evo_*` is
+ * `fjs/mcp/evo`. Both tool sets run in one process, sharing one `~/.cas/`
+ * store and one in-memory Evo cache scanned once at startup (`initEvo`).
+ *
+ * @module
+ */
+import { type Effect } from '../effects/module.f.ts';
+import { type MemOp } from '../effects/memory/module.f.ts';
+import { type Read, type Write } from '../effects/node/module.f.ts';
+import { type McpConfig, type McpHandlers } from '../protocol/mcp/module.f.ts';
+import { type FileCasOperation } from '../cas/module.f.ts';
+import { type Cache } from '../cas/evo/module.f.ts';
+import type { Key } from '../effects/memory/module.f.ts';
+/**
+ * MCP handlers for `FileCas` (`fjs/mcp/cas`) plus the Evo API (`fjs/mcp/evo`)
+ * layered on it, bound to `home` and an already-built Evo cache slot (see
+ * `initEvo`).
+ */
+export declare const casMcpHandlers: (home: string) => (cacheKey: Key<Cache>) => McpHandlers<FileCasOperation | MemOp>;
+/**
+ * Static MCP configuration for the CAS server: advertises the `tools`
+ * capability, identifies the server, and pins the protocol version.
+ */
+export declare const casConfig: McpConfig;
+/**
+ * Runs the combined CAS + Evo MCP server over stdio: scans `~/.cas/` once to
+ * build the Evo subject/head cache (`initEvo`), allocates the session-state
+ * slot, builds the `mcpStep` for the merged tool registry, and drives the
+ * read → parse → dispatch → write loop until stdin EOF.
+ */
+export declare const casMcpServer: (home: string) => Effect<Read | Write | MemOp | FileCasOperation, void>;
+export declare const proof: {
+    casMcpServer: () => void;
 };
-/**
- * Creates a type-safe tool entry that binds an RTTI schema with a handler.
- *
- * The builder validates arguments at runtime using the RTTI and passes pre-validated
- * arguments (typed as `Ts<T>`) to the handler. This eliminates manual validation
- * boilerplate and type assertions.
- *
- * @param name - The tool name (used in `tools/call` requests)
- * @param description - Human-readable description for `tools/list`
- * @param inputRtti - Runtime type info for input validation
- * @param handle - Handler receiving validated arguments of type `Ts<inputRtti>`
- * @returns A `ToolEntry` ready to be added to a registry
- */
-export declare const toolEntry: <T extends Type, O extends Operation>(name: string, description: string, inputRtti: T, handle: (args: Ts<T>) => Effect<O, ToolsCallResult>) => ToolEntry<O>;
-/**
- * Helper to create a successful single-text-block tool result.
- *
- * @param text - The text to return to the client
- * @returns A `ToolsCallResult` with the text content
- */
-export declare const okResult: (text: string) => ToolsCallResult;
-/**
- * Helper to create a tool-level error result with plain text explanation.
- *
- * @param text - The error message to return to the client
- * @returns A `ToolsCallResult` with `isError: true` and the text explanation
- */
-export declare const errorResult: (text: string) => ToolsCallResult;
-/**
- * Builds `McpHandlers` from a registry of tool entries.
- *
- * This factory generates `toolsList` and `toolsCall` handlers that work with a
- * declarative registry, eliminating boilerplate. The `toolsList` handler converts
- * entries into MCP `Tool` descriptors, and `toolsCall` dispatches by name and
- * delegates to the appropriate handler.
- *
- * @param registry - Array of tool entries
- * @returns Complete `McpHandlers` ready for use with `mcpStep`
- */
-export declare const fromRegistry: <O extends Operation>(registry: readonly ToolEntry<O>[]) => McpHandlers<O>;
-/** Top-level handler: maps a raw JSON value to a JSON-RPC response (or `null` for notifications). */
-export type Handle<O extends Operation> = (value: Unknown) => Effect<O, Response | null>;
-/** MCP error -32002: the client called a method before `initialize`. */
-export declare const notInitialized: import("../types/rtti/ts/module.f.ts").StructTs<{
-    readonly code: import("../types/rtti/module.f.ts").Number;
-    readonly message: import("../types/rtti/module.f.ts").String;
-    readonly data: import("../types/rtti/module.f.ts").Or<readonly [typeof unknown, undefined]>;
-}>;
-/** State carried before the peer sends `initialize`. */
-export type Uninitialized = readonly ['uninitialized'];
-/** State after `initialize` response was sent but before `notifications/initialized` arrives. */
-export type Initializing = readonly ['initializing'];
-/** State carried after a successful `initialize` exchange. */
-export type InitializedState = true;
-/** The three phases of an MCP session. */
-export type McpSessionState = Uninitialized | Initializing | readonly ['initialized', InitializedState];
-/** Initial session state — always start here. */
-export declare const uninitializedState: McpSessionState;
-/** Static configuration supplied by the server implementer. */
-export type McpConfig = {
-    readonly serverInfo: Implementation;
-    readonly capabilities: ServerCapabilities;
-    readonly protocolVersion: string;
-};
-/**
- * State-machine step for an MCP session using memory effects.
- *
- * Given configuration, handlers, and a memory key holding the session state,
- * returns a function `(value) => Effect<MemOp | O, Response | null>`.
- *
- * Rules:
- * - `ping` returns an empty success regardless of session state; non-object
- *   params → -32602.
- * - `initialize` is accepted only while uninitialized; a second call returns -32600.
- *   On success the state moves to `initializing`, not `initialized`.
- * - `notifications/initialized` (no `id`) transitions `initializing` → `initialized`;
- *   a malformed one (non-object params) is ignored and the session stays gated;
- *   other notifications are silently ignored in any state.
- * - Any other method before `notifications/initialized` → error -32002 (not initialized).
- * - Methods gated by a capability (e.g. `tools/list`) → -32601 when the capability
- *   is absent.
- * - `tools/list` params (an optional pagination `cursor`) are validated and passed
- *   to the handler; invalid params → -32602.
- */
-export declare const mcpStep: ({ protocolVersion, capabilities, serverInfo, }: McpConfig) => <O extends Operation>(handlers: McpHandlers<O>) => (stateKey: Key<McpSessionState>) => (value: Unknown) => Effect<MemOp | O, Response | null>;