functionalscript 0.45.0 → 0.46.0

package/fjs/mcp/cas/proof.f.mjs

@@ -0,0 +1,174 @@
+/**
+ * @import { Effect } from '../../effects/types.ts'
+ * @import { Result } from '../../types/result/types.ts'
+ * @import { FileCasOperation } from '../../cas/types.ts'
+ * @import { MemOp } from '../../effects/memory/types.ts'
+ * @import { Cache } from '../../cas/evo/types.ts'
+ * @import { Key } from '../../effects/memory/types.ts'
+ * @import { ToolsCallResult } from '../../protocol/mcp/types.ts'
+ */
+
+import { casToolRegistry } from './module.f.mjs'
+import { match } from '../../effects/module.f.mjs'
+import { error, ok } from '../../types/result/module.f.mjs'
+import { ioError } from '../../effects/node/module.f.mjs'
+import { vec, vec8 } from '../../types/bit_vec/module.f.mjs'
+import { vecToCBase32 } from '../../basen/cbase32/module.f.mjs'
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+import { number as rttiNumber, string as rttiString } from '../../types/rtti/module.f.mjs'
+import { parse as rttiParse } from '../../types/rtti/parse/module.f.mjs'
+import { unwrap } from '../../types/result/module.f.mjs'
+import { parse as parseJson } from '../../media/json/module.f.mjs'
+
+// A harmless "always succeeds" response for a command, used by `drive` once a
+// test's overrides for that command are exhausted — same technique as
+// `fjs/cas/proof.f.mjs`'s `drive`, extended with `MemOp` since `cas_add` also
+// touches the Evo cache on its success path.
+/** @type {(cmd: string) => unknown} */
+const defaultResponse = cmd => {
+    switch (cmd) {
+        case 'now': return ok(0)
+        case 'randomInt': return ok(0)
+        case 'mkdir': case 'createExclusive': case 'rename': case 'rm':
+        case 'writeBytes': case 'access':
+            return ok(undefined)
+        case 'readdir': return ok(/** @type {readonly unknown[]} */ ([]))
+        case 'stat': return ok({ size: 0 })
+        // An empty chunk reads as end-of-stream, so a `readBytes` call with no
+        // override reads as an immediately-empty file by default.
+        case 'readBytes': return ok(vec(0n)(0n))
+        case 'memCreate': return ok(/** @type {unknown} */ ('mem-key'))
+        case 'memRead': return ok(undefined)
+        case 'memWrite': return ok(undefined)
+        default: return ok(undefined)
+    }
+}
+
+/**
+ * Drives a `FileCasOperation | MemOp` effect to completion with synthetic op
+ * responses instead of a filesystem. `overrides[cmd]` is a queue consumed in
+ * call order; once a command's queue is empty (or was never given),
+ * `defaultResponse` supplies an always-succeeds value.
+ *
+ * `cas_add`'s write-failure branch and `cas_get`'s "hash vanished between
+ * reads" branches are real only under a race (a failing disk, a concurrent
+ * writer, a GC sweep) between two of the tool's own steps — the same shape of
+ * branch `fjs/cas/proof.f.mjs` reaches with its own `drive` helper, applied
+ * here one layer up at the MCP tool boundary.
+ *
+ * The result is unwrapped: a tool handler answers
+ * `Effect<…, ToolsCallResult, never>`, having absorbed its failures into
+ * `isError`, so callers want the answer rather than the `ok` around it. The
+ * `never` channel is what makes that unwrap total.
+ *
+ * @type {(overrides: Partial<Record<string, unknown[]>>) => (e: Effect<FileCasOperation | MemOp, unknown, never>) => unknown}
+ */
+const drive = overrides => {
+    /** @type {(cmd: string) => unknown} */
+    const next = cmd => {
+        const queue = overrides[cmd]
+        return queue !== undefined && queue.length > 0 ? queue.shift() : defaultResponse(cmd)
+    }
+    const handlers = /** @type {Parameters<typeof match>[0]} */ ({
+        access: () => next('access'),
+        createExclusive: () => next('createExclusive'),
+        mkdir: () => next('mkdir'),
+        now: () => next('now'),
+        randomInt: () => next('randomInt'),
+        readBytes: () => next('readBytes'),
+        readdir: () => next('readdir'),
+        rename: () => next('rename'),
+        rm: () => next('rm'),
+        stat: () => next('stat'),
+        writeBytes: () => next('writeBytes'),
+        memCreate: () => next('memCreate'),
+        memRead: () => next('memRead'),
+        memWrite: () => next('memWrite'),
+    })
+    const matcher = match(handlers)
+    /** @type {(e: Effect<FileCasOperation | MemOp, unknown, unknown>) => Result<unknown, unknown>} */
+    const run_ = e => {
+        const m = matcher(e)
+        return m[0] === 'done' ? m[1] : run_(m[2](/** @type {any} */ (m[1])))
+    }
+    return e => unwrap(run_(e))
+}
+
+// `syncRevision` is only reached on a *successful* write, which none of these
+// cases exercise, so the cache key's actual identity never matters — only its
+// type does.
+const cacheKey = /** @type {Key<Cache>} */ (/** @type {any} */ ('unused-cache-key'))
+
+const registry = casToolRegistry('.')(cacheKey)
+
+/** @type {(name: string) => (args: any) => Effect<FileCasOperation | MemOp, ToolsCallResult, never>} */
+const toolHandle = name => {
+    const entry = registry.find(t => t.name === name)
+    assert(entry !== undefined, `no such tool: ${name}`)
+    return /** @type {NonNullable<typeof entry>} */ (entry).handle
+}
+
+// Any well-formed cBase32 hash works: none of these cases resolve it against a
+// real store, since every filesystem op is driven synthetically.
+const someHash = vecToCBase32(vec(256n)(0n))
+
+const meta = /** @type {const} */ ({
+    length: rttiNumber,
+    mimeType: rttiString,
+    type: rttiString,
+    uri: rttiString,
+})
+const parseMeta = rttiParse(meta)
+
+export const proof = {
+    // cas_list: a store that exists but cannot be walked is a tool-level error
+    // carrying the host's own words — neither a panic (which is what it used
+    // to be, one `unwrap` deep) nor an empty listing, which would tell the
+    // client the store holds nothing.
+    casListStorageErrorReturnsError: () => {
+        const result = /** @type {ToolsCallResult} */ (
+            drive({ access: [error(ioError({ code: 'EACCES', message: 'permission denied' }))] })(toolHandle('cas_list')({}))
+        )
+        assert(result.isError === true, ['expected isError', result])
+    },
+    // cas_add: a writeBytes failure mid-upload (disk full, permissions) is
+    // reported as a tool-level error, not a thrown exception or a silent
+    // success.
+    casAddWriteErrorReturnsError: () => {
+        const result = /** @type {ToolsCallResult} */ (
+            drive({ writeBytes: [error(ioError({ message: 'disk full' }))] })(toolHandle('cas_add')({ content: 'hello' }))
+        )
+        assert(result.isError === true, ['expected isError', result])
+    },
+    // cas_get, content:false: the streaming metadata pass finds a small
+    // whole-blob-text hash, so it starts a second, independent read to refine
+    // `mimeType` via the dialect-aware detector. If that second read finds the
+    // hash gone (a GC sweep raced it away), the code falls back to the
+    // streaming verdict rather than fail the whole request.
+    casGetMetadataRefineHashVanishesFallsBackToStreamingVerdict: () => {
+        const result = /** @type {ToolsCallResult} */ (
+            drive({ readBytes: [ok(vec8(0x41n)), ok(vec(0n)(0n)), error(ioError({ message: 'vanished' }))] })
+                (toolHandle('cas_get')({ hash: someHash, content: false }))
+        )
+        assert(result.isError !== true, ['expected ok result', result])
+        const text = result.content[0]
+        assert(text.type === 'text', ['expected text content', text])
+        const parsed = unwrap(parseMeta(unwrap(parseJson(text.text))))
+        assertEq(parsed.type, 'text')
+        assertEq(parsed.mimeType, 'text/plain')
+        assertEq(parsed.length, 1)
+    },
+    // cas_get, content:true: the streaming metadata pass succeeds and the blob
+    // fits inline, so a second read materializes it. If that second read finds
+    // the hash gone, the whole request fails — there is no streaming verdict
+    // to fall back to once inline content was actually promised.
+    casGetContentFetchHashVanishesReturnsError: () => {
+        const result = /** @type {ToolsCallResult} */ (
+            drive({ readBytes: [ok(vec8(0x41n)), ok(vec(0n)(0n)), error(ioError({ message: 'vanished' }))] })
+                (toolHandle('cas_get')({ hash: someHash, content: true }))
+        )
+        assert(result.isError === true, ['expected isError', result])
+        const text = result.content[0]
+        assert(text.type === 'text' && text.text.includes('no such hash'), ['expected no-such-hash message', text])
+    },
+}

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

@@ -8,16 +8,16 @@
  *
  * | Tool           | args                                          | action            | result                               |
  * |----------------|-----------------------------------------------|-------------------|--------------------------------------|
- * | `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)                       |
+ * | `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?, lock? }`  | `e.add(...)`      | hash (cBase32)                       |
  *
  * `evo_add` and `evo_revision` speak the same structure — `fjs/cas/evo`'s
  * `RevisionData` — in opposite directions, so a revision read back can be
- * added again as-is. `evo_add`'s advertised arguments stay as they are: the
- * one field `evo_revision` returns that `evo_add` does not accept is
- * `generation`, which the server computes, and rtti's struct validation
+ * added again as-is, `lock` scopes and all. The one field `evo_revision`
+ * returns that `evo_add` does not accept is `generation`, which the server
+ * computes, and rtti's struct validation
  * ignores properties the schema does not name, so a whole `evo_revision`
  * result can be passed straight back to `evo_add`.
  *
@@ -43,11 +43,10 @@
  *
  * @module
  *
- * @import { Effect, Operation } from '../../effects/types.ts'
+ * @import { Operation } from '../../effects/types.ts'
  * @import { MemOp } from '../../effects/memory/types.ts'
- * @import { ToolEntry, ToolsCallResult } from '../../protocol/mcp/types.ts'
+ * @import { ToolEntry } from '../../protocol/mcp/types.ts'
  * @import { Evo } from '../../cas/evo/types.ts'
- * @import { Ts } from '../../types/rtti/ts/types.ts'
  */
 import type { Operation } from '../../effects/types.ts';
 import type { MemOp } from '../../effects/memory/types.ts';
@@ -72,12 +71,22 @@ export declare const evoRevisionArgs: {
  * Arguments for `evo_add`: a new revision, per `fjs/cas/evo`'s
  * `RevisionData` — every field of it the caller supplies, i.e. all but
  * `generation`, which the server computes.
+ *
+ * `lock` is the media format's own field schema
+ * (`fjs/media/revision`'s `lockField`), not a restatement of it, so the
+ * advertised `inputSchema` and what the server accepts cannot drift apart. It
+ * therefore accepts either form the format does — the bindings inline, or the
+ * hash of a `vnd.fjs.lock` blob holding them. The map half is recursive, which
+ * makes it the one argument whose JSON Schema reaches a named `$defs` rule
+ * through a local `$ref` rather than being inlined whole — see
+ * `fjs/media/json/schema`.
  */
 export declare const evoAddArgs: {
     readonly parents: import("../../types/rtti/types.ts").Type1<"array", import("../../types/rtti/types.ts")._Type0<"string">>;
     readonly snapshot: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
     readonly subject: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
     readonly archived: import("../../types/rtti/types.ts").Or<readonly [true, undefined]>;
+    readonly lock: import("../../types/rtti/types.ts").Or<readonly [import("../../media/revision/types.ts").LockFieldSchema, undefined]>;
 };
 /**
  * Registry of all Evo tools, bound to an `Evo<O>`.

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

@@ -8,16 +8,16 @@
  *
  * | Tool           | args                                          | action            | result                               |
  * |----------------|-----------------------------------------------|-------------------|--------------------------------------|
- * | `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)                       |
+ * | `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?, lock? }`  | `e.add(...)`      | hash (cBase32)                       |
  *
  * `evo_add` and `evo_revision` speak the same structure — `fjs/cas/evo`'s
  * `RevisionData` — in opposite directions, so a revision read back can be
- * added again as-is. `evo_add`'s advertised arguments stay as they are: the
- * one field `evo_revision` returns that `evo_add` does not accept is
- * `generation`, which the server computes, and rtti's struct validation
+ * added again as-is, `lock` scopes and all. The one field `evo_revision`
+ * returns that `evo_add` does not accept is `generation`, which the server
+ * computes, and rtti's struct validation
  * ignores properties the schema does not name, so a whole `evo_revision`
  * result can be passed straight back to `evo_add`.
  *
@@ -43,15 +43,16 @@
  *
  * @module
  *
- * @import { Effect, Operation } from '../../effects/types.ts'
+ * @import { Operation } from '../../effects/types.ts'
  * @import { MemOp } from '../../effects/memory/types.ts'
- * @import { ToolEntry, ToolsCallResult } from '../../protocol/mcp/types.ts'
+ * @import { ToolEntry } from '../../protocol/mcp/types.ts'
  * @import { Evo } from '../../cas/evo/types.ts'
- * @import { Ts } from '../../types/rtti/ts/types.ts'
  */
 
 import { string, option, array } from '../../types/rtti/module.f.mjs'
-import { pure, step } from '../../effects/module.f.mjs'
+import { lockField } from '../../media/revision/module.f.mjs'
+import { pureOk, resultStep } from '../../effects/module.f.mjs'
+import { evoSummary } from '../../cas/evo/module.f.mjs'
 import {
     toolEntry, errorResult, okResult,
 } from '../../protocol/mcp/module.f.mjs'
@@ -82,12 +83,22 @@ export const evoRevisionArgs = /** @type {const} */ ({
  * Arguments for `evo_add`: a new revision, per `fjs/cas/evo`'s
  * `RevisionData` — every field of it the caller supplies, i.e. all but
  * `generation`, which the server computes.
+ *
+ * `lock` is the media format's own field schema
+ * (`fjs/media/revision`'s `lockField`), not a restatement of it, so the
+ * advertised `inputSchema` and what the server accepts cannot drift apart. It
+ * therefore accepts either form the format does — the bindings inline, or the
+ * hash of a `vnd.fjs.lock` blob holding them. The map half is recursive, which
+ * makes it the one argument whose JSON Schema reaches a named `$defs` rule
+ * through a local `$ref` rather than being inlined whole — see
+ * `fjs/media/json/schema`.
  */
 export const evoAddArgs = /** @type {const} */ ({
     parents: array(string),
     snapshot: option(string),
     subject: option(string),
     archived: option(true),
+    lock: option(lockField),
 })
 
 // ── Tool registry ────────────────────────────────────────────────────────────────
@@ -110,44 +121,54 @@ export const evoToolRegistry = e => [
         // 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.
-        /** @type {(args: Ts<typeof evoListArgs>) => Effect<MemOp, ToolsCallResult>} */
-        (({ archived }) => step(
+
+        // A cache slot the runner cannot reach is a tool-level error, not a
+        // panic: the client asked a question the server could not answer, and
+        // saying so is an ordinary `isError` result.
+        (({ archived }) => resultStep(
             e.list(archived),
-            subjects => pure(okResult(toJson(subjects)))
+            r => pureOk(r[0] === 'error'
+                ? errorResult(evoSummary(r[1]))
+                : okResult(toJson(r[1])))
         )),
     ),
     toolEntry(
         'evo_head',
         'List the current head hashes (cBase32) of a subject, one per line. Empty when the subject is unknown.',
         evoHeadArgs,
-        /** @type {(args: Ts<typeof evoHeadArgs>) => Effect<MemOp, ToolsCallResult>} */
-        (({ subject }) => step(
+        ({ subject }) => resultStep(
             e.head(subject),
-            heads => pure(okResult(heads.join('\n'))),
-        )),
+            r => pureOk(r[0] === 'error'
+                ? errorResult(evoSummary(r[1]))
+                : okResult(r[1].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.',
+        'Read one revision by hash, as JSON: `{ subject, parents, snapshot, generation, archived?, lock? }`. `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
         // `evo_list`'s. An encoded response that outgrows the transport cap is
         // the transport's `-32603`, not a tool-level error — see "Result size"
         // in the module doc.
-        /** @type {(args: Ts<typeof evoRevisionArgs>) => Effect<O | MemOp, ToolsCallResult>} */
-        (({ hash }) => step(
+
+        (({ hash }) => resultStep(
             e.revision(hash),
-            result => pure(result[0] === 'error' ? errorResult(result[1]) : okResult(toJson(result[1])))
+            r => pureOk(r[0] === 'error' ? errorResult(evoSummary(r[1])) : okResult(toJson(r[1])))
         )),
     ),
     toolEntry(
         'evo_add',
-        'Add a new revision (a `vnd.fjs.revision` blob) and return its hash (cBase32). `subject` is required unless there is exactly one parent, from which it is inherited. `snapshot`, when omitted, is resolved from the parents (zero parents → `subject`, one parent → the parent\'s snapshot; a merge requires an explicit `snapshot`) and written explicitly. `generation` is computed by the server.',
+        'Add a new revision (a `vnd.fjs.revision` blob) and return its hash (cBase32). `subject` is required unless there is exactly one parent, from which it is inherited. `snapshot`, when omitted, is resolved from the parents (zero parents → `subject`, one parent → the parent\'s snapshot; a merge requires an explicit `snapshot`) and written explicitly. `generation` is computed by the server. `lock` is optional resolver input: a map from dependency subject to the cBase32 hash of the content it resolves to, or to a nested map scoping further bindings under that subject (use nesting only for conflicting choices a flat map cannot express, e.g. two dependencies needing different versions of a third). Pass a cBase32 hash instead of a map to share one already stored as a `vnd.fjs.lock` blob; the server records the reference and does not follow it.',
         evoAddArgs,
-        /** @type {(input: Ts<typeof evoAddArgs>) => Effect<O | MemOp, ToolsCallResult>} */
-        (input => step(
+        // Two failures, one MCP shape: a rejected revision and an unreachable
+        // cache slot are both `isError` to the client, and both carry a message
+        // it can read. They stay distinguishable by tag — `evoSummary` is the
+        // renderer that switches on it — so telling them apart never needed
+        // them to arrive in separate layers.
+        input => resultStep(
             e.add(input),
-            result => pure(result[0] === 'error' ? errorResult(result[1]) : okResult(result[1]))
-        )),
+            r => pureOk(r[0] === 'error' ? errorResult(evoSummary(r[1])) : okResult(r[1]))
+        ),
     ),
 ]

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

@@ -1,9 +1,12 @@
 /**
  * @import { Evo } from '../../cas/evo/types.ts'
  * @import { ToolEntry, ToolsCallResult } from '../../protocol/mcp/types.ts'
- * @import { Operation } from '../../effects/types.ts'
+ * @import { NotImplemented, Operation } from '../../effects/types.ts'
+ * @import { Result } from '../../types/result/types.ts'
+ * @import { State } from '../../effects/node/virtual/types.ts'
  */
 export declare const proof: {
+    channelFailureIsToolError: () => void;
     toolNamesMatchTheDesign: () => void;
     evoListReflectsTheCache: () => void;
     evoListEncodesArbitrarySubjectsAsJson: () => void;
@@ -13,5 +16,7 @@ export declare const proof: {
     evoRevisionReturnsRevisionJson: () => void;
     evoRevisionDomainErrorIsError: () => void;
     evoAddSuccessReturnsHash: () => void;
+    evoAddAndRevisionCarryNestedLocks: () => void;
+    evoAddInputSchemaPublishesTheLockRecursion: () => void;
     evoAddDomainErrorIsError: () => void;
 };