functionalscript 0.45.0 → 0.46.1

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

@@ -0,0 +1,121 @@
+/**
+ * `vnd.fjs.note` — a human-authored text item (a note, todo, issue, calendar
+ * event, …) as a BLOB of its own.
+ *
+ * The format is deliberately minimal: the dialect tag, the text, and
+ * optionally the subjects the item depends on and a priority. Everything
+ * else a richer item needs — a title, tags, dates, a status — is a future
+ * **optional** field:
+ * rtti structs are open, so additive extension keeps the tag (see the
+ * versioning rule in `fjs/media/revision/README.md`), and starting minimal is
+ * what keeps every extension additive.
+ *
+ * Like `vnd.fjs.lock`, a note is a **value**, not a step: no timestamps, no
+ * author, no history of its own. Edits over time are ordinary
+ * `vnd.fjs.revision` steps whose `subject` identifies the note and whose
+ * `snapshot` is one of these blobs, so no second history mechanism appears
+ * and `revision` stays the only one.
+ *
+ * This module is the pure format only: the rtti schema, the `dialect` tag,
+ * and decode/validate. Unlike its CAS siblings it has no hash fields, so
+ * there is no semantic refinement stage — structural validation is the whole
+ * check.
+ *
+ * See `README.md` for the full spec.
+ *
+ * @module
+ *
+ * @import { Unknown } from '../json/types.ts'
+ * @import { Result } from '../../types/result/types.ts'
+ * @import { ValidationError } from '../../types/rtti/common/types.ts'
+ * @import { DialectEntry } from '../types.ts'
+ * @import { Note, NoteError } from './types.ts'
+ */
+import type { Unknown } from '../json/types.ts';
+import type { Result } from '../../types/result/types.ts';
+import type { ValidationError } from '../../types/rtti/common/types.ts';
+import type { DialectEntry } from '../types.ts';
+import type { Note, NoteError } from './types.ts';
+/**
+ * Format tag: names the dialect of this BLOB. The media type it is served
+ * with is derived mechanically: `application/` + `dialect` + `+json`.
+ */
+export declare const dialect: 'vnd.fjs.note';
+/** The media type derived from {@link dialect}: `application/vnd.fjs.note+json`. */
+export declare const mediaType: "application/vnd.fjs.note+json";
+/**
+ * rtti schema for a `note` BLOB: the dialect tag, the text, and optionally
+ * the subjects the item depends on.
+ *
+ * `text` is **required** and may be `''`: an absent text and an empty one
+ * would otherwise be two spellings of one blob, and a blob whose only purpose
+ * is to hold text has nothing to say when it does not. Any string is valid —
+ * the format records the text and defines no markup for it; how a reader
+ * renders it (e.g. as Markdown) is the reader's decision.
+ *
+ * `dependencies` entries are **subject identity strings** — the vocabulary of
+ * `vnd.fjs.revision`'s `subject` and of lock-map keys — naming the mutable
+ * items this one depends on (a blocked-by todo, an issue's prerequisite).
+ * They are never content hashes: a dependency tracks the live item, and
+ * pinning it to immutable content is the revision layer's `lock`. Like
+ * `subject`, an identity string is unconstrained, so no semantic check
+ * applies. The field is optional because its absent value is the constant
+ * "depends on nothing"; an explicit `[]` says the same thing, and the format
+ * does not distinguish the two.
+ *
+ * `text` may reference an entry by its zero-based index in square brackets —
+ * `[0]` names `dependencies[0]` — so the entry order is **significant**:
+ * reordering or removing entries renumbers references. A bracketed integer
+ * that indexes no entry is ordinary text, not a broken reference, so the
+ * convention adds no validation stage (see the README).
+ *
+ * `priority` is the author's decision about the item's urgency, on the
+ * {@link priorities} scale — a closed literal union, so it too is enforced
+ * entirely structurally (a number would invite scale and range questions
+ * only a semantic check could answer). Absent means **unprioritized** — the
+ * author has not decided — which is the constant default that makes the
+ * field optional, and is deliberately distinct from any rank.
+ */
+/**
+ * The priority scale, most urgent first: `P1` is "drop everything", `P5` is
+ * "someday". The vocabulary of `todo/README.md`'s issue format, reused
+ * rather than invented, so one scale ranks the repository's own issues and a
+ * note blob alike. Widening it later (e.g. a `P0`) follows the fail-closed
+ * path the versioning rule allows: an older reader rejects the new rank
+ * rather than misreading it.
+ */
+export declare const priorities: readonly ['P1', 'P2', 'P3', 'P4', 'P5'];
+export declare const noteSchema: {
+    readonly dialect: "vnd.fjs.note";
+    readonly text: import("../../types/rtti/types.ts")._Type0<"string">;
+    readonly dependencies: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Type1<"array", import("../../types/rtti/types.ts")._Type0<"string">>, undefined]>;
+    readonly priority: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Or<["P1", "P2", "P3", "P4", "P5"]>, undefined]>;
+};
+/** Serializes a note canonically, sorting every object's property names.
+ * @type {(note: Note) => string}
+ */
+export declare const encodeText: (note: Note) => string;
+/**
+ * Validates an already-parsed JSON value as a `note` BLOB. Structural (rtti)
+ * validation is the whole check: a note has no hash fields, so there is no
+ * semantic refinement stage and no `checkReferences` half.
+ *
+ * @type {(value: Unknown) => Result<Note, ValidationError>}
+ */
+export declare const validate: (value: Unknown) => Result<Note, ValidationError>;
+/**
+ * Decodes `text` as a `note` BLOB: JSON-parses it, then validates it per
+ * {@link validate}. Detection is semantic, not syntactic — any JSON that
+ * satisfies the schema is a note, regardless of key order or whitespace.
+ *
+ * @type {(text: string) => Result<Note, NoteError>}
+ */
+export declare const decodeText: (text: string) => Result<Note, NoteError>;
+/**
+ * This dialect as a registry entry for `fjs/media`'s `detect`. Registered
+ * with no refinement — structure alone decides the match — so a blob is
+ * detected as `vnd.fjs.note` exactly when {@link decodeText} would accept it.
+ *
+ * @type {DialectEntry}
+ */
+export declare const noteDialect: DialectEntry;

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

@@ -0,0 +1,131 @@
+/**
+ * `vnd.fjs.note` — a human-authored text item (a note, todo, issue, calendar
+ * event, …) as a BLOB of its own.
+ *
+ * The format is deliberately minimal: the dialect tag, the text, and
+ * optionally the subjects the item depends on and a priority. Everything
+ * else a richer item needs — a title, tags, dates, a status — is a future
+ * **optional** field:
+ * rtti structs are open, so additive extension keeps the tag (see the
+ * versioning rule in `fjs/media/revision/README.md`), and starting minimal is
+ * what keeps every extension additive.
+ *
+ * Like `vnd.fjs.lock`, a note is a **value**, not a step: no timestamps, no
+ * author, no history of its own. Edits over time are ordinary
+ * `vnd.fjs.revision` steps whose `subject` identifies the note and whose
+ * `snapshot` is one of these blobs, so no second history mechanism appears
+ * and `revision` stays the only one.
+ *
+ * This module is the pure format only: the rtti schema, the `dialect` tag,
+ * and decode/validate. Unlike its CAS siblings it has no hash fields, so
+ * there is no semantic refinement stage — structural validation is the whole
+ * check.
+ *
+ * See `README.md` for the full spec.
+ *
+ * @module
+ *
+ * @import { Unknown } from '../json/types.ts'
+ * @import { Result } from '../../types/result/types.ts'
+ * @import { ValidationError } from '../../types/rtti/common/types.ts'
+ * @import { DialectEntry } from '../types.ts'
+ * @import { Note, NoteError } from './types.ts'
+ */
+
+import { array, option, or, string } from '../../types/rtti/module.f.mjs'
+import { parse as rttiParse } from '../../types/rtti/parse/module.f.mjs'
+import { parse as parseJson, stringify } from '../json/module.f.mjs'
+import { okThen } from '../../types/result/module.f.mjs'
+import { dialectEntry } from '../module.f.mjs'
+import { sort } from '../../types/object/module.f.mjs'
+
+/**
+ * Format tag: names the dialect of this BLOB. The media type it is served
+ * with is derived mechanically: `application/` + `dialect` + `+json`.
+ */
+export const dialect = /** @type {const} */ ('vnd.fjs.note')
+
+/** The media type derived from {@link dialect}: `application/vnd.fjs.note+json`. */
+export const mediaType = /** @type {const} */ (`application/${dialect}+json`)
+
+/**
+ * rtti schema for a `note` BLOB: the dialect tag, the text, and optionally
+ * the subjects the item depends on.
+ *
+ * `text` is **required** and may be `''`: an absent text and an empty one
+ * would otherwise be two spellings of one blob, and a blob whose only purpose
+ * is to hold text has nothing to say when it does not. Any string is valid —
+ * the format records the text and defines no markup for it; how a reader
+ * renders it (e.g. as Markdown) is the reader's decision.
+ *
+ * `dependencies` entries are **subject identity strings** — the vocabulary of
+ * `vnd.fjs.revision`'s `subject` and of lock-map keys — naming the mutable
+ * items this one depends on (a blocked-by todo, an issue's prerequisite).
+ * They are never content hashes: a dependency tracks the live item, and
+ * pinning it to immutable content is the revision layer's `lock`. Like
+ * `subject`, an identity string is unconstrained, so no semantic check
+ * applies. The field is optional because its absent value is the constant
+ * "depends on nothing"; an explicit `[]` says the same thing, and the format
+ * does not distinguish the two.
+ *
+ * `text` may reference an entry by its zero-based index in square brackets —
+ * `[0]` names `dependencies[0]` — so the entry order is **significant**:
+ * reordering or removing entries renumbers references. A bracketed integer
+ * that indexes no entry is ordinary text, not a broken reference, so the
+ * convention adds no validation stage (see the README).
+ *
+ * `priority` is the author's decision about the item's urgency, on the
+ * {@link priorities} scale — a closed literal union, so it too is enforced
+ * entirely structurally (a number would invite scale and range questions
+ * only a semantic check could answer). Absent means **unprioritized** — the
+ * author has not decided — which is the constant default that makes the
+ * field optional, and is deliberately distinct from any rank.
+ */
+/**
+ * The priority scale, most urgent first: `P1` is "drop everything", `P5` is
+ * "someday". The vocabulary of `todo/README.md`'s issue format, reused
+ * rather than invented, so one scale ranks the repository's own issues and a
+ * note blob alike. Widening it later (e.g. a `P0`) follows the fail-closed
+ * path the versioning rule allows: an older reader rejects the new rank
+ * rather than misreading it.
+ */
+export const priorities = /** @type {const} */ (['P1', 'P2', 'P3', 'P4', 'P5'])
+
+export const noteSchema = /** @type {const} */ ({
+    dialect,
+    text: string,
+    dependencies: option(array(string)),
+    priority: option(or(...priorities)),
+})
+
+/** Serializes a note canonically, sorting every object's property names.
+ * @type {(note: Note) => string}
+ */
+export const encodeText = stringify(sort)
+
+/**
+ * Validates an already-parsed JSON value as a `note` BLOB. Structural (rtti)
+ * validation is the whole check: a note has no hash fields, so there is no
+ * semantic refinement stage and no `checkReferences` half.
+ *
+ * @type {(value: Unknown) => Result<Note, ValidationError>}
+ */
+export const validate = rttiParse(noteSchema)
+
+/**
+ * Decodes `text` as a `note` BLOB: JSON-parses it, then validates it per
+ * {@link validate}. Detection is semantic, not syntactic — any JSON that
+ * satisfies the schema is a note, regardless of key order or whitespace.
+ *
+ * @type {(text: string) => Result<Note, NoteError>}
+ */
+export const decodeText = text => okThen(validate)(parseJson(text))
+
+/**
+ * This dialect as a registry entry for `fjs/media`'s `detect`. Registered
+ * with no refinement — structure alone decides the match — so a blob is
+ * detected as `vnd.fjs.note` exactly when {@link decodeText} would accept it.
+ *
+ * @type {DialectEntry}
+ */
+export const noteDialect = dialectEntry(noteSchema)

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

@@ -0,0 +1,29 @@
+export declare const proof: {
+    dialectAndMediaType: () => void;
+    priorityScale: () => void;
+    validate: {
+        minimalNoteAccepted: () => void;
+        emptyTextAccepted: () => void;
+        missingTextRejected: () => void;
+        nonStringTextRejected: () => void;
+        dependenciesAccepted: () => void;
+        emptyDependenciesAccepted: () => void;
+        nonArrayDependenciesRejected: () => void;
+        nonStringDependencyRejected: () => void;
+        priorityAccepted: () => void;
+        unknownPriorityRejected: () => void;
+        numericPriorityRejected: () => void;
+        unknownFieldsIgnored: () => void;
+        otherDialectRejected: () => void;
+    };
+    decodeText: {
+        validJson: () => void;
+        keyOrderIndependent: () => void;
+        malformedJsonRejected: () => void;
+        ordinaryJsonRejected: () => void;
+    };
+    encodeText: {
+        sortsPropertiesLexicographically: () => void;
+    };
+    noteDialectTag: () => void;
+};

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