functionalscript 0.44.0 → 0.46.0

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

@@ -0,0 +1,196 @@
+/**
+ * @import { Object as JsonObject } from '../json/types.ts'
+ * @import { LockMap } from './types.ts'
+ */
+
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+import { dialect, mediaType, checkReferences, validate, decodeText, encodeText } from './module.f.mjs'
+import {
+    dialect as revisionDialect,
+    encodeText as revisionEncodeText,
+    validate as revisionValidate,
+} from '../revision/module.f.mjs'
+import { stringify } from '../json/module.f.mjs'
+import { sort } from '../../types/object/module.f.mjs'
+
+// Valid cbase32 hashes (round-tripped in fjs/basen/cbase32/proof.f.mjs): single
+// cbase32 symbols, cheap to write inline here.
+const h1 = '8'
+const h2 = 'r'
+
+/** A shape-valid lock blob holding `lock`.
+ * @type {(lock: JsonObject) => JsonObject}
+ */
+const lockOf = lock => ({ dialect, lock })
+
+/**
+ * The one map both forms are asked to carry — nested, so the claim covers
+ * every depth rather than just the top level.
+ * @type {LockMap}
+ */
+const sharedMap = { C: { D: h2, C: h1 }, B: { D: h1 } }
+
+/** The canonical rendering of a lock map on its own, independent of either blob. */
+const canonicalMap = stringify(sort)
+
+export const proof = {
+    dialectAndMediaType: () => {
+        assertEq(dialect, 'vnd.fjs.lock')
+        assertEq(mediaType, 'application/vnd.fjs.lock+json')
+    },
+
+    validate: {
+        // The ordinary case: a flat map of subject-to-content bindings.
+        flatMapAccepted: () => {
+            const r = validate(lockOf({ dependency: h1 }))
+            assert(r[0] === 'ok', ['expected ok', r])
+            assertEq(r[1].lock.dependency, h1)
+        },
+
+        // An empty map is a lock blob that records no bindings — distinct from
+        // a revision omitting `lock`, and the reason the field is required.
+        emptyMapAccepted: () => {
+            const r = validate(lockOf({}))
+            assert(r[0] === 'ok', ['expected ok', r])
+            assertEq(Object.keys(r[1].lock).length, 0)
+        },
+
+        // Nesting is the revision dialect's, unchanged: scopes to any depth.
+        nestedMapAccepted: () => {
+            const [t] = validate(lockOf({ B: { C: { D: { E: h1 } } }, empty: {} }))
+            assertEq(t, 'ok')
+        },
+
+        // `lock` is required: a blob carrying only the tag is not one.
+        missingLockRejected: () => {
+            const [t] = validate({ dialect })
+            assertEq(t, 'error')
+        },
+
+        // The field is a map, never a hash — a lock blob does not reference
+        // further lock blobs, so following a reference terminates in one step.
+        referenceLockRejected: () => {
+            const [t] = validate({ dialect, lock: h1 })
+            assertEq(t, 'error')
+        },
+
+        // A value must be a string or a map: a number fails structurally.
+        malformedMapRejected: () => {
+            const [t] = validate(lockOf({ dependency: 1 }))
+            assertEq(t, 'error')
+        },
+
+        // The semantic check is the revision dialect's own, so a non-hash
+        // string is rejected here with the same path-naming message.
+        invalidHashRejected: () => {
+            const r = validate(lockOf({ B: { D: 'https://example.com/x' } }))
+            assert(r[0] === 'error', ['expected error', r])
+            assertEq(r[1], 'lock value for B/D is not a valid hash: https://example.com/x')
+        },
+
+        // No `subject`, `parents`, `generation` or `archived`: this dialect is
+        // a value, not a step. rtti structs are open, so such fields are
+        // ignored rather than rejected — the additive forward-compatibility
+        // path, the same one the revision dialect relies on.
+        revisionFieldsIgnored: () => {
+            const [t] = validate({ dialect, lock: {}, subject: h1, parents: [], generation: 0 })
+            assertEq(t, 'ok')
+        },
+
+        // A revision blob is not a lock blob: the tag is matched as an exact
+        // literal, so the two dialects never validate each other's content.
+        revisionBlobRejected: () => {
+            const [t] = validate({
+                dialect: revisionDialect,
+                subject: h1,
+                parents: [],
+                snapshot: h2,
+                generation: 0,
+                lock: {},
+            })
+            assertEq(t, 'error')
+        },
+    },
+
+    // The already-typed entry point, for callers that assembled a `Lock`
+    // themselves and need only the semantic half.
+    checkReferences: {
+        valid: () => {
+            const [t] = checkReferences({ dialect, lock: { dependency: h1 } })
+            assertEq(t, 'ok')
+        },
+        invalid: () => {
+            const [t] = checkReferences({ dialect, lock: { dependency: 'not a hash!' } })
+            assertEq(t, 'error')
+        },
+    },
+
+    decodeText: {
+        validJson: () => {
+            const r = decodeText(JSON.stringify(lockOf({ dependency: h1 })))
+            assert(r[0] === 'ok', ['expected ok', r])
+            assertEq(r[1].lock.dependency, h1)
+        },
+
+        // Key order carries no meaning: the JSON is parsed and the parsed
+        // value validated, so `dialect` need not come first.
+        keyOrderIndependent: () => {
+            const [t] = decodeText(`{"lock":{"dependency":"${h1}"},"dialect":"${dialect}"}`)
+            assertEq(t, 'ok')
+        },
+
+        malformedJsonRejected: () => {
+            const [t] = decodeText('{not json')
+            assertEq(t, 'error')
+        },
+
+        ordinaryJsonRejected: () => {
+            const [t] = decodeText('{"hello":"world"}')
+            assertEq(t, 'error')
+        },
+    },
+
+    encodeText: {
+        recursivelySortsObjectsLexicographically: () => {
+            const decoded = validate(lockOf({ scope: { '2': h2, '10': h1 }, '2': h2, '10': h1 }))
+            assert(decoded[0] === 'ok', ['expected ok', decoded])
+            assertEq(
+                encodeText(decoded[1]),
+                `{"dialect":"${dialect}","lock":{"10":"${h1}","2":"${h2}","scope":{"10":"${h1}","2":"${h2}"}}}`,
+            )
+        },
+
+        // Two blobs differing only in property order converge on one byte
+        // sequence, so they address the same CAS blob — which is the whole
+        // point of sharing one.
+        equivalentOrdersConverge: () => {
+            const a = validate(lockOf({ B: { B: h1, D: h2 }, C: { D: h1 } }))
+            const b = validate(lockOf({ C: { D: h1 }, B: { D: h2, B: h1 } }))
+            assert(a[0] === 'ok', ['expected ok', a])
+            assert(b[0] === 'ok', ['expected ok', b])
+            assertEq(encodeText(a[1]), encodeText(b[1]))
+        },
+    },
+
+    // The point of importing `lock` rather than restating it: one map, one
+    // canonical rendering, whether it is held inline by a revision or shared
+    // as a blob of its own. The two dialects have different field sets, so the
+    // surrounding bytes differ — the map's do not, and a resolver reading
+    // either form sees the identical bytes under `lock`.
+    inlineAndSharedSerializeIdentically: () => {
+        const fragment = `"lock":${canonicalMap(sharedMap)}`
+        const shared = validate(lockOf(sharedMap))
+        assert(shared[0] === 'ok', ['expected ok', shared])
+        const inline = revisionValidate({
+            dialect: revisionDialect,
+            subject: h1,
+            parents: [],
+            snapshot: h2,
+            generation: 0,
+            lock: sharedMap,
+        })
+        assert(inline[0] === 'ok', ['expected ok', inline])
+        assert(encodeText(shared[1]).includes(fragment), encodeText(shared[1]))
+        assert(revisionEncodeText(inline[1]).includes(fragment), revisionEncodeText(inline[1]))
+    },
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Type-level API for `fjs/media/lock/module.f.mjs`: `Lock` and `LockError`.
+ *
+ * The map type itself is not restated here — it is `fjs/media/revision`'s
+ * `LockMap`, re-exported so a consumer of the shared form needs only one
+ * import, and so nothing can define a second, drifting spelling of it.
+ */
+import type { ValidationError } from '../../types/rtti/common/types.ts';
+import type { Ts } from '../../types/rtti/ts/types.ts';
+import type { lockSchema } from './module.f.mjs';
+export type { LockMap } from '../revision/types.ts';
+/** The TypeScript type derived from `lockSchema` — the single source of truth. */
+export type Lock = Ts<typeof lockSchema>;
+/** Either a structural validation error or a semantic (hash) error message. */
+export type LockError = ValidationError | string;

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

@@ -12,11 +12,12 @@
  * `fjs/media/type` verdict unchanged.
  *
  * The dialect set is a **parameter**, not an import: `detect(dialects)(bytes)`.
- * This module therefore knows no dialect of its own — `fjs/media/revision`
- * exports its own {@link DialectEntry} (`revisionDialect`), and a caller passes
- * the list it wants recognized. Any format following the `vnd.fjs.<name>`
- * convention (see `fjs/media/revision/README.md`), in this repo or downstream,
- * is registerable the same way.
+ * This module therefore knows no dialect of its own — `fjs/media/revision`,
+ * `fjs/media/lock`, and `fjs/media/note` each export their own
+ * {@link DialectEntry} (`revisionDialect`, `lockDialect`, `noteDialect`), and
+ * a caller passes the list it wants recognized. Any format following the `vnd.fjs.<name>` convention (see
+ * `fjs/media/revision/README.md`), in this repo or downstream, is registerable
+ * the same way.
  *
  * Detection is semantic, not syntactic: any JSON that satisfies a dialect's
  * schema is recognized regardless of key order, whitespace, or any other

package/fjs/media/module.f.mjs

@@ -12,11 +12,12 @@
  * `fjs/media/type` verdict unchanged.
  *
  * The dialect set is a **parameter**, not an import: `detect(dialects)(bytes)`.
- * This module therefore knows no dialect of its own — `fjs/media/revision`
- * exports its own {@link DialectEntry} (`revisionDialect`), and a caller passes
- * the list it wants recognized. Any format following the `vnd.fjs.<name>`
- * convention (see `fjs/media/revision/README.md`), in this repo or downstream,
- * is registerable the same way.
+ * This module therefore knows no dialect of its own — `fjs/media/revision`,
+ * `fjs/media/lock`, and `fjs/media/note` each export their own
+ * {@link DialectEntry} (`revisionDialect`, `lockDialect`, `noteDialect`), and
+ * a caller passes the list it wants recognized. Any format following the `vnd.fjs.<name>` convention (see
+ * `fjs/media/revision/README.md`), in this repo or downstream, is registerable
+ * the same way.
  *
  * Detection is semantic, not syntactic: any JSON that satisfies a dialect's
  * schema is recognized regardless of key order, whitespace, or any other
@@ -53,7 +54,7 @@ import { fromVec } from '../text/utf8/module.f.mjs'
 import { detectVec } from './type/module.f.mjs'
 import { parse } from './json/module.f.mjs'
 import { assert, assertNotNullish } from '../asserts/module.f.mjs'
-import { validate } from '../types/rtti/validate/module.f.mjs'
+import { parse as rttiParse } from '../types/rtti/parse/module.f.mjs'
 
 /** The default refinement: structural validation alone decides the match. */
 const always = () => true
@@ -119,7 +120,7 @@ const matchWith = v => extraValidate => u => {
 export const dialectEntry = (type, extraValidate = always) => {
     const { dialect } = type
     assert(typeof dialect === 'string', 'dialectEntry: schema has no direct string `dialect` member')
-    return { dialect, match: matchWith(validate(type))(extraValidate) }
+    return { dialect, match: matchWith(rttiParse(type))(extraValidate) }
 }
 
 /**

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

@@ -1,3 +1,16 @@
+/**
+ * A minimal, checked eDSL for constructing and serializing Nix expressions.
+ *
+ * The tree deliberately models syntax rather than evaluated Nix values. String
+ * expressions are escaped double-quoted strings; the other supported forms are
+ * represented by tagged tuples. See `./types.ts` for the `Expression`
+ * type-level API.
+ *
+ * @module
+ *
+ * @import { List as ChunkList } from '../../types/list/types.ts'
+ * @import { Expression, _AttributePath, _Binding, _Reference, _AttributeSet, _NixList, _Application, _OpenSetPattern, _Lambda, _Let, _Chunks } from './types.ts'
+ */
 import type { List as ChunkList } from '../../types/list/types.ts';
 import type { Expression } from './types.ts';
 /**

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

@@ -7,8 +7,11 @@
  * type-level API.
  *
  * @module
+ *
+ * @import { List as ChunkList } from '../../types/list/types.ts'
+ * @import { Expression, _AttributePath, _Binding, _Reference, _AttributeSet, _NixList, _Application, _OpenSetPattern, _Lambda, _Let, _Chunks } from './types.ts'
  */
-/** @import { List as ChunkList } from '../../types/list/types.ts' */
+
 import { toArray } from '../../types/list/module.f.mjs'
 import { concat } from '../../types/string/module.f.mjs'
 import { includes } from '../../types/array/module.f.mjs'
@@ -19,7 +22,6 @@ import {
     range,
 } from '../../text/ascii/module.f.mjs'
 import { fromRange, get, merge } from '../../types/range_set/module.f.mjs'
-/** @import { Expression, _AttributePath, _Binding, _Reference, _AttributeSet, _NixList, _Application, _OpenSetPattern, _Lambda, _Let, _Chunks } from './types.ts' */
 
 const reservedWords = /** @type {const} */ ([
     'assert',

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

@@ -1,3 +1,6 @@
+/**
+ * @import { Expression } from './types.ts'
+ */
 export declare const proof: {
     strings: () => void;
     reference: () => void;

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

@@ -1,7 +1,10 @@
+/**
+ * @import { Expression } from './types.ts'
+ */
+
 import { assert, assertEq } from '../../asserts/module.f.mjs'
 import { toArray } from '../../types/list/module.f.mjs'
 import { nix, nixToString } from './module.f.mjs'
-/** @import { Expression } from './types.ts' */
 
 /** @type {(nodePackage: string, shellHook: boolean) => Expression} */
 const nodeFlake = (nodePackage, shellHook) => ['set',

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;
+};