functionalscript 0.44.0 → 0.46.0

package/fjs/media/note/proof.f.mjs

@@ -0,0 +1,150 @@
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+import { dialect, mediaType, decodeText, encodeText, noteDialect, priorities, validate } from './module.f.mjs'
+import { dialect as lockDialect } from '../lock/module.f.mjs'
+
+export const proof = {
+    dialectAndMediaType: () => {
+        assertEq(dialect, 'vnd.fjs.note')
+        assertEq(mediaType, 'application/vnd.fjs.note+json')
+    },
+
+    // The published scale, most urgent first — `todo/README.md`'s vocabulary.
+    priorityScale: () => {
+        assertEq(priorities.join(','), 'P1,P2,P3,P4,P5')
+    },
+
+    validate: {
+        // The ordinary case: the tag and the text.
+        minimalNoteAccepted: () => {
+            const r = validate({ dialect, text: 'buy milk' })
+            assert(r[0] === 'ok', ['expected ok', r])
+            assertEq(r[1].text, 'buy milk')
+        },
+
+        // `text` may be empty — required rather than optional, so an absent
+        // text and an empty one are not two spellings of one blob.
+        emptyTextAccepted: () => {
+            const [t] = validate({ dialect, text: '' })
+            assertEq(t, 'ok')
+        },
+
+        // `text` is required: a blob carrying only the tag is not a note.
+        missingTextRejected: () => {
+            const [t] = validate({ dialect })
+            assertEq(t, 'error')
+        },
+
+        // The text is a string, nothing else.
+        nonStringTextRejected: () => {
+            const [t] = validate({ dialect, text: 42 })
+            assertEq(t, 'error')
+        },
+
+        // Dependencies are subject identity strings, unconstrained like
+        // `vnd.fjs.revision`'s `subject` — no semantic check applies. The
+        // text may reference them by index (`[0]`, `[1]`), which is a
+        // reading convention, not a validation rule: this blob validates the
+        // same with any text.
+        dependenciesAccepted: () => {
+            const r = validate({ dialect, text: 'ship it once [0] and [1] land', dependencies: ['write the spec', 'review'] })
+            assert(r[0] === 'ok', ['expected ok', r])
+            assertEq(r[1].dependencies?.length, 2)
+        },
+
+        // `[]` and an absent field both say "depends on nothing"; the format
+        // does not distinguish them, and both validate.
+        emptyDependenciesAccepted: () => {
+            const [t] = validate({ dialect, text: 'hi', dependencies: [] })
+            assertEq(t, 'ok')
+        },
+
+        // The field is a list of strings, nothing else.
+        nonArrayDependenciesRejected: () => {
+            const [t] = validate({ dialect, text: 'hi', dependencies: 'write the spec' })
+            assertEq(t, 'error')
+        },
+        nonStringDependencyRejected: () => {
+            const [t] = validate({ dialect, text: 'hi', dependencies: [42] })
+            assertEq(t, 'error')
+        },
+
+        // A priority is one of the closed `priorities` literals — the
+        // author's urgency decision, enforced entirely structurally.
+        priorityAccepted: () => {
+            const r = validate({ dialect, text: 'fix the build', priority: 'P1' })
+            assert(r[0] === 'ok', ['expected ok', r])
+            assertEq(r[1].priority, 'P1')
+        },
+
+        // The scale is closed: an unknown rank fails structurally rather than
+        // passing as a free-form string — the fail-closed widening path.
+        unknownPriorityRejected: () => {
+            const [t] = validate({ dialect, text: 'hi', priority: 'P0' })
+            assertEq(t, 'error')
+        },
+
+        // The rank is a literal, not a number: `1` is not `'P1'`.
+        numericPriorityRejected: () => {
+            const [t] = validate({ dialect, text: 'hi', priority: 1 })
+            assertEq(t, 'error')
+        },
+
+        // rtti structs are open, so unknown fields are ignored rather than
+        // rejected — the additive forward-compatibility path every future
+        // extension (title, tags, dates, …) relies on.
+        unknownFieldsIgnored: () => {
+            const [t] = validate({ dialect, text: 'call Bob', title: 'todo', done: true })
+            assertEq(t, 'ok')
+        },
+
+        // Another dialect's blob is not a note: the tag is matched as an
+        // exact literal.
+        otherDialectRejected: () => {
+            const [t] = validate({ dialect: lockDialect, text: 'hi' })
+            assertEq(t, 'error')
+        },
+    },
+
+    decodeText: {
+        validJson: () => {
+            const r = decodeText(`{"dialect":"${dialect}","text":"buy milk"}`)
+            assert(r[0] === 'ok', ['expected ok', r])
+            assertEq(r[1].text, 'buy milk')
+        },
+
+        // Key order carries no meaning: the JSON is parsed and the parsed
+        // value validated, so `dialect` need not come first.
+        keyOrderIndependent: () => {
+            const [t] = decodeText(`{"text":"hi","dialect":"${dialect}"}`)
+            assertEq(t, 'ok')
+        },
+
+        malformedJsonRejected: () => {
+            const [t] = decodeText('{not json')
+            assertEq(t, 'error')
+        },
+
+        ordinaryJsonRejected: () => {
+            const [t] = decodeText('{"hello":"world"}')
+            assertEq(t, 'error')
+        },
+    },
+
+    encodeText: {
+        // Two blobs differing only in property order converge on one byte
+        // sequence, so they address the same CAS blob. `dependencies` sorts
+        // ahead of `dialect`, and its array order is preserved — arrays retain
+        // their declared order under canonical serialization.
+        sortsPropertiesLexicographically: () => {
+            const decoded = decodeText(`{"text":"hi","dependencies":["b","a"],"dialect":"${dialect}"}`)
+            assert(decoded[0] === 'ok', ['expected ok', decoded])
+            assertEq(encodeText(decoded[1]), `{"dependencies":["b","a"],"dialect":"${dialect}","text":"hi"}`)
+        },
+    },
+
+    // The registry entry carries the schema's own tag; matching is exercised
+    // end to end through `detect` in `fjs/media/proof.f.mjs`.
+    noteDialectTag: () => {
+        assertEq(noteDialect.dialect, dialect)
+    },
+}

package/fjs/media/note/types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Type-level API for `fjs/media/note/module.f.mjs`: `Note` and `NoteError`.
+ */
+import type { ValidationError } from '../../types/rtti/common/types.ts';
+import type { Ts } from '../../types/rtti/ts/types.ts';
+import type { noteSchema } from './module.f.mjs';
+/** The TypeScript type derived from `noteSchema` — the single source of truth. */
+export type Note = Ts<typeof noteSchema>;
+/** Either a structural validation error or a JSON parse error message. */
+export type NoteError = ValidationError | string;

package/fjs/media/proof.f.d.mts

@@ -4,7 +4,10 @@ export declare const proof: {
     keyOrderIndependent: () => void;
     invalidRevisionFallsThrough: () => void;
     nonHashSnapshotFallsThrough: () => void;
-    secondDialect: () => void;
+    validLock: () => void;
+    lockAndRevisionDoNotOverlap: () => void;
+    nonHashLockValueFallsThrough: () => void;
+    validNote: () => void;
     nonVndDialectName: () => void;
     firstMatchWins: () => void;
     noDialects: () => void;

package/fjs/media/proof.f.mjs

@@ -6,6 +6,8 @@ import { assertEq } from '../asserts/module.f.mjs'
 import { msb, u8ListToVec, repeat, vec8 } from '../types/bit_vec/module.f.mjs'
 import { detect, dialectEntry } from './module.f.mjs'
 import { dialect, revisionDialect } from './revision/module.f.mjs'
+import { dialect as lockDialectName, lockDialect } from './lock/module.f.mjs'
+import { dialect as noteDialectName, noteDialect } from './note/module.f.mjs'
 import { number, string } from '../types/rtti/module.f.mjs'
 
 // All test strings here are ASCII, so char code === UTF-8 byte value.
@@ -14,22 +16,12 @@ const utf8Bytes = s => u8ListToVec(msb)([...s].map(c => c.charCodeAt(0)))
 
 const revisionJson = `{"dialect":"${dialect}","subject":"8","parents":[],"snapshot":"8","generation":0}`
 
-/** @type {readonly DialectEntry[]} */
-const dialects = [revisionDialect]
-
-const detectRevision = detect(dialects)
-
-/**
- * A second dialect following the same `vnd.fjs.<name>` convention, registered
- * with no refinement: structure alone decides the match.
+/** The three dialects `fjs/media` itself ships, in the order `fjs/mcp` registers them.
+ * @type {readonly DialectEntry[]}
  */
-const noteSchema = /** @type {const} */ ({
-    dialect: 'vnd.fjs.note',
-    text: string,
-})
+const dialects = [revisionDialect, lockDialect, noteDialect]
 
-/** @type {DialectEntry} */
-const noteDialect = dialectEntry(noteSchema)
+const detectRevision = detect(dialects)
 
 /** A dialect name outside `vnd.fjs.*` — registerable, and detected as itself. */
 const gadgetSchema = /** @type {const} */ ({
@@ -83,14 +75,41 @@ export const proof = {
         assertEq(m.mime_type, 'text/plain')
     },
 
-    // A second dialect, registered by the caller, is recognized alongside the
-    // first — and an entry with no refinement matches on structure alone.
-    secondDialect: () => {
-        const d = detect([revisionDialect, noteDialect])
-        assertEq(d(utf8Bytes('{"dialect":"vnd.fjs.note","text":"hi"}')).mime_type, 'application/vnd.fjs.note+json')
-        assertEq(d(utf8Bytes(revisionJson)).mime_type, 'application/vnd.fjs.revision+json')
+    // A valid shared-lock blob is recognized as its own dialect, alongside the
+    // revision one, and reported under the derived media type.
+    validLock: () => {
+        const m = detectRevision(utf8Bytes(`{"dialect":"${lockDialectName}","lock":{"dependency":"8"}}`))
+        assertEq(m.type, 'text')
+        assertEq(m.mime_type, 'application/vnd.fjs.lock+json')
+    },
+
+    // The two dialects never claim each other's blobs: each schema matches its
+    // own `dialect` literal, so a revision carrying an inline `lock` is still a
+    // revision, and a lock blob is never a revision.
+    lockAndRevisionDoNotOverlap: () => {
+        const withLock = `{"dialect":"${dialect}","subject":"8","parents":[],"snapshot":"8","generation":0,"lock":{"d":"8"}}`
+        assertEq(detectRevision(utf8Bytes(withLock)).mime_type, 'application/vnd.fjs.revision+json')
+        assertEq(detectRevision(utf8Bytes(revisionJson)).mime_type, 'application/vnd.fjs.revision+json')
+    },
+
+    // `lockDialect` carries the semantic check too: a structurally valid lock
+    // blob whose binding is not a cbase32 hash is not detected as one, exactly
+    // as its `decodeText` would say.
+    nonHashLockValueFallsThrough: () => {
+        const text = `{"dialect":"${lockDialectName}","lock":{"dependency":"not a hash"}}`
+        const m = detectRevision(utf8Bytes(text))
+        assertEq(m.type, 'text')
+        assertEq(m.mime_type, 'text/plain')
+    },
+
+    // The note dialect is registered with no refinement, so structure alone
+    // decides the match — a valid note is recognized alongside its siblings.
+    validNote: () => {
+        const m = detectRevision(utf8Bytes(`{"dialect":"${noteDialectName}","text":"hi"}`))
+        assertEq(m.type, 'text')
+        assertEq(m.mime_type, 'application/vnd.fjs.note+json')
         // Same tag, wrong shape: no entry matches.
-        assertEq(d(utf8Bytes('{"dialect":"vnd.fjs.note","text":42}')).mime_type, 'text/plain')
+        assertEq(detectRevision(utf8Bytes(`{"dialect":"${noteDialectName}","text":42}`)).mime_type, 'text/plain')
     },
 
     // The name is neither grammar-checked nor allowlisted: a dialect outside

package/fjs/media/revision/module.f.d.mts

@@ -17,12 +17,13 @@
  * @import { Unknown } from '../json/types.ts'
  * @import { Result } from '../../types/result/types.ts'
  * @import { DialectEntry } from '../types.ts'
- * @import { Revision, RevisionError } from './types.ts'
+ * @import { String as RttiString } from '../../types/rtti/types.ts'
+ * @import { LockField, LockFieldSchema, LockMap, LockSchema, Revision, RevisionError } from './types.ts'
  */
 import type { Unknown } from '../json/types.ts';
 import type { Result } from '../../types/result/types.ts';
 import type { DialectEntry } from '../types.ts';
-import type { Revision, RevisionError } from './types.ts';
+import type { LockField, LockFieldSchema, LockMap, LockSchema, Revision, RevisionError } from './types.ts';
 /**
  * Format tag: names the dialect of this BLOB. The media type it is served
  * with is derived mechanically: `application/` + `dialect` + `+json`.
@@ -40,8 +41,52 @@ export declare const mediaType: "application/vnd.fjs.revision+json";
  * not by this schema on its own.
  */
 export declare const hash: import("../../types/rtti/types.ts")._Type0<"string">;
-/** Structural schema for a Stage 1 flat lock map. */
-export declare const _lock: import("../../types/rtti/types.ts").Type1<"record", import("../../types/rtti/types.ts")._Type0<"string">>;
+/**
+ * rtti schema for a lock map: an open map whose every value is either a
+ * direct hash string or a nested lock map, to any depth.
+ *
+ * Self-referential through {@link lockValue}, which is a module-level
+ * constant rather than a union rebuilt inside the thunk: the rtti data form
+ * (`fjs/types/rtti/data`, which `toJsonSchema` routes through) closes
+ * reference cycles by *identity*, so a schema handing out a fresh union thunk
+ * on every call would present an infinite graph and never terminate.
+ *
+ * The named `@type` — rather than `@type {const}` — is what a self-referential
+ * schema needs twice over: a `const` cannot reference itself in its own
+ * initializer at all, and naming the recursive position is also what keeps
+ * declaration emit from inlining the structure and giving up at depth (see
+ * `fjs/AGENTS.md` §3.2 and `../json/rtti/module.f.mjs`).
+ *
+ * Like `hash`, this is `string` at the structural level; cbase32 decodability
+ * of every direct value, at every depth, is enforced by
+ * {@link checkReferences}.
+ *
+ * @type {LockSchema}
+ */
+export declare const lock: LockSchema;
+/**
+ * rtti schema for a revision's `lock` **field**: the bindings inline as a lock
+ * map, or a hash naming a `vnd.fjs.lock` blob (`fjs/media/lock`) that holds
+ * one to share — see [Shared lock references](./README.md#shared-lock-references).
+ *
+ * Structurally identical to {@link lockValue}, and deliberately a separate
+ * name: the two positions mean different things. A string *inside* a map is a
+ * dependency's content hash; a string in this position is a lock blob's hash,
+ * i.e. where the whole map lives. Only the top level is widened, so a nested
+ * string keeps meaning exactly what it always did and no position is
+ * ambiguous.
+ *
+ * Widening the field rather than adding a `lockRef` sibling is what keeps this
+ * dialect: an older reader validates `lock` as a map and rejects a string
+ * outright, whereas an unknown sibling field would validate and be read as
+ * "no bindings were recorded" — the fail-open misread the versioning rule
+ * exists to prevent. It also makes "inline map *and* reference" unstatable, so
+ * the format defines no precedence between them, consistent with its refusal
+ * to define overlay or inheritance for nested maps.
+ *
+ * @type {LockFieldSchema}
+ */
+export declare const lockField: LockFieldSchema;
 /**
  * rtti schema for a `revision` BLOB. See the README for the full semantics of
  * each field; `dialect` is the type discriminant, matched here as an exact
@@ -54,7 +99,7 @@ export declare const revisionSchema: {
     readonly snapshot: import("../../types/rtti/types.ts")._Type0<"string">;
     readonly generation: import("../../types/rtti/types.ts")._Type0<"number">;
     readonly archived: import("../../types/rtti/types.ts").Or<readonly [true, undefined]>;
-    readonly lock: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Type1<"record", import("../../types/rtti/types.ts")._Type0<"string">>, undefined]>;
+    readonly lock: import("../../types/rtti/types.ts").Or<readonly [LockFieldSchema, undefined]>;
 };
 /** Serializes a revision canonically, recursively sorting every object's property names.
  * @type {(revision: Revision) => string}
@@ -64,12 +109,38 @@ export declare const encodeText: (revision: Revision) => string;
  * @type {(s: string) => boolean}
  */
 export declare const isHash: (s: string) => boolean;
+/**
+ * The first reason a structurally valid lock map is not a valid one, or `null`
+ * — {@link lockError} rooted at the empty scope, so a reported path is
+ * relative to the map itself.
+ *
+ * Exported because `fjs/media/lock` validates the very same map as a
+ * standalone blob: one recursive schema and one semantic check, so a map means
+ * the same thing inline and shared, and the two forms cannot drift.
+ *
+ * @type {(lock: LockMap) => string | null}
+ */
+export declare const lockMapError: (lock: LockMap) => string | null;
+/**
+ * The first reason a structurally valid `lock` field is not a valid one, or
+ * `null`. A map is checked entry by entry ({@link lockMapError}); a string is
+ * a reference to a `vnd.fjs.lock` blob and is checked as a cbase32 hash and
+ * nothing more — this module is pure format with no store access, so whether
+ * the blob exists, and what its bindings mean once fetched, stay a resolver's
+ * business exactly as they do for `snapshot`.
+ *
+ * @type {(value: LockField) => string | null}
+ */
+export declare const lockFieldError: (value: LockField) => string | null;
 /**
  * Checks the semantic refinements the structural schema can't express on an
  * already shape-valid revision: every `parents` entry and the `snapshot` must
- * decode as a cbase32 hash ({@link isHash}), and `generation` must be a
+ * decode as a cbase32 hash ({@link isHash}), the `lock` field must too —
+ * every direct value at every depth of an inline map, or the shared-lock
+ * reference itself ({@link lockFieldError}) — and `generation` must be a
  * non-negative *safe* integer. `subject` is not checked — it is an identity
- * string, never a snapshot reference, so any string is valid.
+ * string, never a snapshot reference, so any string is valid, and the same
+ * goes for a lock map's keys, which are subjects.
  *
  * `generation` uses `Number.isSafeInteger`, not `Number.isInteger`: a value at
  * or above `2 ** 53` passes `isInteger` but is no longer uniquely
@@ -97,6 +168,11 @@ export declare const checkReferences: (r: Revision) => Result<Revision, string>;
  * Validates an already-parsed JSON value as a `revision` BLOB: structural
  * (rtti) validation followed by the hash / generation semantic checks.
  *
+ * `RevisionError` is the union of the two stages' own error types, so each
+ * failure reaches the caller as it was raised — `ValidationError` from the
+ * schema, `string` from {@link checkReferences} — which is exactly what
+ * `okThen` produces here.
+ *
  * @type {(value: Unknown) => Result<Revision, RevisionError>}
  */
 export declare const validate: (value: Unknown) => Result<Revision, RevisionError>;

package/fjs/media/revision/module.f.mjs

@@ -17,14 +17,15 @@
  * @import { Unknown } from '../json/types.ts'
  * @import { Result } from '../../types/result/types.ts'
  * @import { DialectEntry } from '../types.ts'
- * @import { Revision, RevisionError } from './types.ts'
+ * @import { String as RttiString } from '../../types/rtti/types.ts'
+ * @import { LockField, LockFieldSchema, LockMap, LockSchema, Revision, RevisionError } from './types.ts'
  */
 
-import { array, number, option, record, string } from '../../types/rtti/module.f.mjs'
-import { validate as rttiValidate } from '../../types/rtti/validate/module.f.mjs'
+import { array, number, option, string } from '../../types/rtti/module.f.mjs'
+import { parse as rttiParse } from '../../types/rtti/parse/module.f.mjs'
 import { parse as parseJson } from '../json/module.f.mjs'
 import { cBase32ToVec } from '../../basen/cbase32/module.f.mjs'
-import { error, ok } from '../../types/result/module.f.mjs'
+import { error, ok, okThen } from '../../types/result/module.f.mjs'
 import { dialectEntry } from '../module.f.mjs'
 import { definedEntries, sort } from '../../types/object/module.f.mjs'
 import { stringify } from '../json/module.f.mjs'
@@ -49,8 +50,64 @@ export const mediaType = /** @type {const} */ (`application/${dialect}+json`)
  */
 export const hash = string
 
-/** Structural schema for a Stage 1 flat lock map. */
-export const _lock = record(string)
+/**
+ * rtti schema for a lock map: an open map whose every value is either a
+ * direct hash string or a nested lock map, to any depth.
+ *
+ * Self-referential through {@link lockValue}, which is a module-level
+ * constant rather than a union rebuilt inside the thunk: the rtti data form
+ * (`fjs/types/rtti/data`, which `toJsonSchema` routes through) closes
+ * reference cycles by *identity*, so a schema handing out a fresh union thunk
+ * on every call would present an infinite graph and never terminate.
+ *
+ * The named `@type` — rather than `@type {const}` — is what a self-referential
+ * schema needs twice over: a `const` cannot reference itself in its own
+ * initializer at all, and naming the recursive position is also what keeps
+ * declaration emit from inlining the structure and giving up at depth (see
+ * `fjs/AGENTS.md` §3.2 and `../json/rtti/module.f.mjs`).
+ *
+ * Like `hash`, this is `string` at the structural level; cbase32 decodability
+ * of every direct value, at every depth, is enforced by
+ * {@link checkReferences}.
+ *
+ * @type {LockSchema}
+ */
+export const lock = () => ['record', lockValue]
+
+/**
+ * One lock-map value: a direct hash, or a nested lock map. Written as the
+ * union tuple rather than as `or(string, lock)` so the thunk carries the name
+ * `lockValue`: this is where the reference cycle closes, and the data form
+ * names a rule after its defining function — an anonymous thunk would publish
+ * the recursion as `$defs: { '': … }` in every derived JSON Schema.
+ *
+ * @type {() => readonly['or', RttiString, LockSchema]}
+ */
+const lockValue = () => ['or', string, lock]
+
+/**
+ * rtti schema for a revision's `lock` **field**: the bindings inline as a lock
+ * map, or a hash naming a `vnd.fjs.lock` blob (`fjs/media/lock`) that holds
+ * one to share — see [Shared lock references](./README.md#shared-lock-references).
+ *
+ * Structurally identical to {@link lockValue}, and deliberately a separate
+ * name: the two positions mean different things. A string *inside* a map is a
+ * dependency's content hash; a string in this position is a lock blob's hash,
+ * i.e. where the whole map lives. Only the top level is widened, so a nested
+ * string keeps meaning exactly what it always did and no position is
+ * ambiguous.
+ *
+ * Widening the field rather than adding a `lockRef` sibling is what keeps this
+ * dialect: an older reader validates `lock` as a map and rejects a string
+ * outright, whereas an unknown sibling field would validate and be read as
+ * "no bindings were recorded" — the fail-open misread the versioning rule
+ * exists to prevent. It also makes "inline map *and* reference" unstatable, so
+ * the format defines no precedence between them, consistent with its refusal
+ * to define overlay or inheritance for nested maps.
+ *
+ * @type {LockFieldSchema}
+ */
+export const lockField = () => ['or', hash, lock]
 
 /**
  * rtti schema for a `revision` BLOB. See the README for the full semantics of
@@ -64,7 +121,7 @@ export const revisionSchema = /** @type {const} */ ({
     snapshot: hash,
     generation: number,
     archived: option(true),
-    lock: option(_lock),
+    lock: option(lockField),
 })
 
 /** Serializes a revision canonically, recursively sorting every object's property names.
@@ -73,19 +130,70 @@ export const revisionSchema = /** @type {const} */ ({
 export const encodeText = stringify(sort)
 
 /** Structural-only validator: checks the shape, not the hash / generation semantics. */
-const validateShape = rttiValidate(revisionSchema)
+const validateShape = rttiParse(revisionSchema)
 
 /** True when `s` decodes as a cbase32 CAS hash (rejects `https://` and any other non-cbase32 string).
  * @type {(s: string) => boolean}
  */
 export const isHash = s => cBase32ToVec(s) !== null
 
+/**
+ * The first reason a structurally valid lock map is not a valid one, or
+ * `null` when every direct value at every depth is a cbase32 hash
+ * ({@link isHash}). Nested maps are scopes, not references, so only the
+ * strings are checked; `scope` names the path walked to reach the offending
+ * value, so a failure deep in a nested map still says where it is.
+ *
+ * @type {(scope: readonly string[]) => (lock: LockMap) => string | null}
+ */
+const lockError = scope => lock => {
+    for (const [subject, value] of definedEntries(lock)) {
+        const path = [...scope, subject]
+        const message = typeof value === 'string'
+            ? (isHash(value) ? null : `lock value for ${path.join('/')} is not a valid hash: ${value}`)
+            : lockError(path)(value)
+        if (message !== null) { return message }
+    }
+    return null
+}
+
+/**
+ * The first reason a structurally valid lock map is not a valid one, or `null`
+ * — {@link lockError} rooted at the empty scope, so a reported path is
+ * relative to the map itself.
+ *
+ * Exported because `fjs/media/lock` validates the very same map as a
+ * standalone blob: one recursive schema and one semantic check, so a map means
+ * the same thing inline and shared, and the two forms cannot drift.
+ *
+ * @type {(lock: LockMap) => string | null}
+ */
+export const lockMapError = lockError([])
+
+/**
+ * The first reason a structurally valid `lock` field is not a valid one, or
+ * `null`. A map is checked entry by entry ({@link lockMapError}); a string is
+ * a reference to a `vnd.fjs.lock` blob and is checked as a cbase32 hash and
+ * nothing more — this module is pure format with no store access, so whether
+ * the blob exists, and what its bindings mean once fetched, stay a resolver's
+ * business exactly as they do for `snapshot`.
+ *
+ * @type {(value: LockField) => string | null}
+ */
+export const lockFieldError = value =>
+    typeof value === 'string'
+        ? (isHash(value) ? null : `lock reference is not a valid hash: ${value}`)
+        : lockMapError(value)
+
 /**
  * Checks the semantic refinements the structural schema can't express on an
  * already shape-valid revision: every `parents` entry and the `snapshot` must
- * decode as a cbase32 hash ({@link isHash}), and `generation` must be a
+ * decode as a cbase32 hash ({@link isHash}), the `lock` field must too —
+ * every direct value at every depth of an inline map, or the shared-lock
+ * reference itself ({@link lockFieldError}) — and `generation` must be a
  * non-negative *safe* integer. `subject` is not checked — it is an identity
- * string, never a snapshot reference, so any string is valid.
+ * string, never a snapshot reference, so any string is valid, and the same
+ * goes for a lock map's keys, which are subjects.
  *
  * `generation` uses `Number.isSafeInteger`, not `Number.isInteger`: a value at
  * or above `2 ** 53` passes `isInteger` but is no longer uniquely
@@ -113,9 +221,8 @@ export const checkReferences = r => {
         if (!isHash(p)) { return error(`parent is not a valid hash: ${p}`) }
     }
     if (!isHash(r.snapshot)) { return error(`snapshot is not a valid hash: ${r.snapshot}`) }
-    for (const [subject, snapshot] of definedEntries(r.lock ?? {})) {
-        if (!isHash(snapshot)) { return error(`lock value for ${subject} is not a valid hash: ${snapshot}`) }
-    }
+    const lockMessage = r.lock === undefined ? null : lockFieldError(r.lock)
+    if (lockMessage !== null) { return error(lockMessage) }
     if (!Number.isSafeInteger(r.generation) || r.generation < 0) {
         return error(`generation must be a non-negative safe integer: ${r.generation}`)
     }
@@ -126,13 +233,14 @@ export const checkReferences = r => {
  * Validates an already-parsed JSON value as a `revision` BLOB: structural
  * (rtti) validation followed by the hash / generation semantic checks.
  *
+ * `RevisionError` is the union of the two stages' own error types, so each
+ * failure reaches the caller as it was raised — `ValidationError` from the
+ * schema, `string` from {@link checkReferences} — which is exactly what
+ * `okThen` produces here.
+ *
  * @type {(value: Unknown) => Result<Revision, RevisionError>}
  */
-export const validate = value => {
-    const [t, v] = validateShape(value)
-    if (t === 'error') { return error(v) }
-    return checkReferences(v)
-}
+export const validate = value => okThen(checkReferences)(validateShape(value))
 
 /**
  * Decodes `text` as a `revision` BLOB: JSON-parses it, then validates it per
@@ -141,11 +249,7 @@ export const validate = value => {
  *
  * @type {(text: string) => Result<Revision, RevisionError>}
  */
-export const decodeText = text => {
-    const [t, v] = parseJson(text)
-    if (t === 'error') { return error(v) }
-    return validate(v)
-}
+export const decodeText = text => okThen(validate)(parseJson(text))
 
 /** {@link checkReferences} as the `boolean` refinement a {@link DialectEntry} takes.
  * @type {(r: Revision) => boolean}

package/fjs/media/revision/proof.f.d.mts

@@ -1,3 +1,7 @@
+/**
+ * @import { Object as JsonObject } from '../json/types.ts'
+ * @import { LockMap } from './types.ts'
+ */
 export declare const proof: {
     dialectAndMediaType: () => void;
     isHash: {
@@ -24,6 +28,13 @@ export declare const proof: {
         malformedLockRejected: () => void;
         invalidHashLockRejected: () => void;
         aliasHashLockAccepted: () => void;
+        nestedLockAccepted: () => void;
+        deeplyNestedLockAccepted: () => void;
+        malformedNestedLockRejected: () => void;
+        invalidNestedHashLockRejected: () => void;
+        sharedLockReferenceAccepted: () => void;
+        invalidSharedLockReferenceRejected: () => void;
+        nestedValueIsStillNotAReference: () => void;
         wrongDialectRejected: () => void;
         missingSubjectRejected: () => void;
         extraFieldsAccepted: () => void;
@@ -36,6 +47,9 @@ export declare const proof: {
     };
     encodeText: {
         recursivelySortsObjectsLexicographically: () => void;
+        sortsNestedLockKeys: () => void;
+        equivalentNestedLockOrdersConverge: () => void;
+        serializesSharedLockReferenceAsAString: () => void;
         preservesArrayOrder: () => void;
         parsedEquivalentSourcesConverge: () => void;
     };