functionalscript 0.43.0 → 0.43.1

package/fjs/cas/evo/module.f.d.ts

@@ -45,7 +45,7 @@
 import { type Effect, type Operation } from '../../effects/module.f.ts';
 import { type Key, type MemOp } from '../../effects/memory/module.f.ts';
 import { type Cas } from '../module.f.ts';
-import { type Revision } from '../../media/revision/module.f.ts';
+import { type LockMap, type Revision } from '../../media/revision/module.f.ts';
 import { type Result } from '../../types/result/module.f.ts';
 import { type StringMap } from '../../types/object/module.f.ts';
 import type { Vec } from '../../types/bit_vec/module.f.ts';
@@ -98,6 +98,7 @@ export type RevisionData = {
     readonly subject?: Subject | undefined;
     readonly archived?: true | undefined;
     readonly generation?: number | undefined;
+    readonly lock?: LockMap | undefined;
 };
 /**
  * Per-subject bookkeeping: every revision hash seen for the subject, every

package/fjs/cas/evo/module.f.js

@@ -49,9 +49,7 @@ import { collectRead } from '../module.f.js';
 import { cBase32ToVec, vecToCBase32 } from '../../basen/cbase32/module.f.js';
 import { fromVec } from '../../text/utf8/module.f.js';
 import { tryUtf8 } from '../../text/module.f.js';
-import { decodeText, dialect, checkReferences, isHash } from '../../media/revision/module.f.js';
-import { stringify } from '../../media/json/module.f.js';
-import { identity } from '../../types/function/module.f.js';
+import { decodeText, encodeText, dialect, checkReferences, isHash } from '../../media/revision/module.f.js';
 import { ok, error } from '../../types/result/module.f.js';
 import { nonEmpty, empty as elEmpty } from '../../effects/list/module.f.js';
 import { at, definedEntries } from '../../types/object/module.f.js';
@@ -59,8 +57,6 @@ import { unwrap } from '../../types/nullable/module.f.js';
 import { isNotFound } from '../../effects/node/module.f.js';
 /** A cache with no known subjects yet — the starting point for {@link buildCache}. */
 export const emptyCache = { bySubject: {} };
-/** Canonical JSON encoder for a `Revision` — key order carries no meaning for detection. */
-const toJson = stringify(identity);
 const emptySubjectState = { hashes: [], parents: [], archived: [] };
 /** Adds every item of `items` to `set` that isn't already there, preserving `set`'s existing order. */
 const union = (set) => (items) => items.reduce((acc, h) => acc.includes(h) ? acc : [...acc, h], set);
@@ -77,6 +73,8 @@ const union = (set) => (items) => items.reduce((acc, h) => acc.includes(h) ? acc
  * (`fjs/media/revision` `checkReferences`), so decoding here cannot fail.
  */
 const canonicalHash = (h) => vecToCBase32(unwrap(cBase32ToVec(h)));
+/** Canonicalizes every direct hash in a structurally validated flat lock map. */
+const canonicalLock = (lock) => Object.fromEntries(definedEntries(lock).map(([subject, hash]) => [subject, canonicalHash(hash)]));
 /** A subject's current heads: revision hashes seen that no other revision of the same subject names as a parent. */
 const headsOf = (state) => state.hashes.filter(h => !state.parents.includes(h));
 /**
@@ -325,6 +323,7 @@ export const addRevision = (cas) => (cacheKey) => (input) => eff(resolveParents(
         snapshot: snapshotResult[1],
         generation: computeGeneration(parentsResult[1]),
         archived: input.archived,
+        lock: input.lock,
     };
     const referencesResult = checkReferences(revision);
     if (referencesResult[0] === 'error') {
@@ -341,8 +340,9 @@ export const addRevision = (cas) => (cacheKey) => (input) => eff(resolveParents(
         ...revision,
         parents: revision.parents.map(canonicalHash),
         snapshot: canonicalHash(revision.snapshot),
+        lock: revision.lock === undefined ? undefined : canonicalLock(revision.lock),
     };
-    const bytes = tryUtf8(toJson(canonicalRevision));
+    const bytes = tryUtf8(encodeText(canonicalRevision));
     if (bytes === null) {
         return pure(error('revision too large to encode'));
     }
@@ -370,12 +370,13 @@ export const addRevision = (cas) => (cacheKey) => (input) => eff(resolveParents(
  * inside `canonicalHash` is safe. Field order follows the stored blob's
  * (minus `dialect`), which is what a JSON encoding of the result shows.
  */
-const toRevisionData = ({ subject, parents, snapshot, generation, archived }) => ({
+const toRevisionData = ({ subject, parents, snapshot, generation, archived, lock }) => ({
     subject,
     parents: parents.map(canonicalHash),
     snapshot: canonicalHash(snapshot),
     generation,
     archived,
+    lock: lock === undefined ? undefined : canonicalLock(lock),
 });
 /**
  * Second stage of {@link readRevision}: interprets an already-performed read

package/fjs/cas/evo/proof.f.d.ts

@@ -35,6 +35,10 @@ export declare const proof: {
     revisionNonRevisionBlobIsError: () => void;
     revisionCanonicalizesReferenceSpellings: () => void;
     revisionRoundTripsThroughAdd: () => void;
+    revisionLockRoundTripsAndCanonicalizes: () => void;
+    revisionAbsentAndEmptyLocksRemainDistinct: () => void;
+    revisionInvalidLockValueIsRejected: () => void;
+    equivalentLockOrdersReuseOneCasAddress: () => void;
     syncRevisionFoldsValidRevisionIntoCache: () => void;
     syncRevisionIgnoresNonRevisionContent: () => void;
     evoHeadUnknownSubjectIsEmpty: () => void;

package/fjs/cas/evo/proof.f.js

@@ -596,6 +596,60 @@ export const proof = {
         assert(readded[0] === 'ok', ['expected re-add ok', readded]);
         assertEq(readded[1], child[1]);
     },
+    revisionLockRoundTripsAndCanonicalizes: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const canonical = vecToCBase32(vec8(0xffn));
+        const alias = canonical.toUpperCase();
+        const [state1, added] = virtual(state0)(e.add({
+            parents: [], subject: 'doc', snapshot: canonical,
+            lock: { dependency: alias },
+        }));
+        assert(added[0] === 'ok', ['expected add ok', added]);
+        const [, result] = virtual(state1)(e.revision(added[1]));
+        assert(result[0] === 'ok', ['expected revision ok', result]);
+        assertEq(result[1].lock?.dependency, canonical);
+    },
+    revisionAbsentAndEmptyLocksRemainDistinct: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const snapshot = vecToCBase32(vec8(0x42n));
+        const [state1, absent] = virtual(state0)(e.add({ parents: [], subject: 'absent', snapshot }));
+        assert(absent[0] === 'ok', ['expected add ok', absent]);
+        const [state2, empty] = virtual(state1)(e.add({ parents: [], subject: 'empty', snapshot, lock: {} }));
+        assert(empty[0] === 'ok', ['expected add ok', empty]);
+        const [state3, absentRead] = virtual(state2)(e.revision(absent[1]));
+        assert(absentRead[0] === 'ok', ['expected revision ok', absentRead]);
+        const [, emptyRead] = virtual(state3)(e.revision(empty[1]));
+        assert(emptyRead[0] === 'ok', ['expected revision ok', emptyRead]);
+        assertEq(absentRead[1].lock, undefined);
+        assertEq(Object.keys(emptyRead[1].lock ?? {}).length, 0);
+    },
+    revisionInvalidLockValueIsRejected: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const [, result] = virtual(state0)(e.add({
+            parents: [], subject: 'doc', snapshot: vecToCBase32(vec8(0x42n)),
+            lock: { dependency: 'not a hash!' },
+        }));
+        assertEq(result[0], 'error');
+    },
+    equivalentLockOrdersReuseOneCasAddress: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const a = vecToCBase32(vec8(0x1an));
+        const b = vecToCBase32(vec8(0x2bn));
+        const snapshot = vecToCBase32(vec8(0x3cn));
+        const [state1, first] = virtual(state0)(e.add({ parents: [], subject: 'doc', snapshot, lock: { '2': b, '10': a } }));
+        assert(first[0] === 'ok', ['expected add ok', first]);
+        const [, second] = virtual(state1)(e.add({ lock: { '10': a, '2': b }, snapshot, subject: 'doc', parents: [] }));
+        assert(second[0] === 'ok', ['expected add ok', second]);
+        assertEq(second[1], first[1]);
+    },
     // A raw CAS write (e.g. `cas_add`) of valid revision content is folded
     // into the cache exactly as `addRevision` would, without going through
     // `evo.add` — this is what keeps `cas_add` and `evo_add` writes to the

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

@@ -20,6 +20,10 @@ export declare const mediaType: "application/vnd.fjs.revision+json";
  * not by this schema on its own.
  */
 export declare const hash: import("../../types/rtti/module.f.ts").String;
+/** Structural schema for a Stage 1 flat lock map. */
+declare const lock: import("../../types/rtti/module.f.ts").Type1<"record", import("../../types/rtti/module.f.ts").String>;
+/** A flat set of subject-to-snapshot bindings supplied to dependency resolvers. */
+export type LockMap = Ts<typeof lock>;
 /**
  * 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
@@ -32,9 +36,12 @@ export declare const revisionSchema: {
     readonly snapshot: import("../../types/rtti/module.f.ts").String;
     readonly generation: import("../../types/rtti/module.f.ts").Number;
     readonly archived: import("../../types/rtti/module.f.ts").Or<readonly [true, undefined]>;
+    readonly lock: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Type1<"record", import("../../types/rtti/module.f.ts").String>, undefined]>;
 };
 /** The TypeScript type derived from {@link revisionSchema} — the single source of truth. */
 export type Revision = Ts<typeof revisionSchema>;
+/** Serializes a revision canonically, recursively sorting every object's property names. */
+export declare const encodeText: (revision: Revision) => string;
 /** True when `s` decodes as a cbase32 CAS hash (rejects `https://` and any other non-cbase32 string). */
 export declare const isHash: (s: string) => boolean;
 /** Either a structural validation error or a semantic (hash / generation) error message. */
@@ -84,3 +91,4 @@ export declare const decodeText: (text: string) => Result<Revision, RevisionErro
  * `snapshot` is not a cbase32 hash is not one.
  */
 export declare const revisionDialect: DialectEntry;
+export {};

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

@@ -14,12 +14,14 @@
  *
  * @module
  */
-import { array, number, option, string } from '../../types/rtti/module.f.js';
+import { array, number, option, record, string } from '../../types/rtti/module.f.js';
 import { validate as rttiValidate } from '../../types/rtti/validate/module.f.js';
 import { parse as parseJson } from '../json/module.f.js';
 import { cBase32ToVec } from '../../basen/cbase32/module.f.js';
 import { error, ok } from '../../types/result/module.f.js';
 import { dialectEntry } from '../module.f.js';
+import { definedEntries, sort } from '../../types/object/module.f.js';
+import { stringify } from '../json/module.f.js';
 /**
  * Format tag: names the dialect of this BLOB. The media type it is served
  * with is derived mechanically: `application/` + `dialect` + `+json`.
@@ -37,6 +39,8 @@ export const mediaType = `application/${dialect}+json`;
  * not by this schema on its own.
  */
 export const hash = string;
+/** Structural schema for a Stage 1 flat lock map. */
+const lock = record(string);
 /**
  * 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
@@ -49,7 +53,10 @@ export const revisionSchema = {
     snapshot: hash,
     generation: number,
     archived: option(true),
+    lock: option(lock),
 };
+/** Serializes a revision canonically, recursively sorting every object's property names. */
+export const encodeText = stringify(sort);
 /** Structural-only validator: checks the shape, not the hash / generation semantics. */
 const validateShape = rttiValidate(revisionSchema);
 /** True when `s` decodes as a cbase32 CAS hash (rejects `https://` and any other non-cbase32 string). */
@@ -89,6 +96,11 @@ export const checkReferences = (r) => {
     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}`);
+        }
+    }
     if (!Number.isSafeInteger(r.generation) || r.generation < 0) {
         return error(`generation must be a non-negative safe integer: ${r.generation}`);
     }

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

@@ -18,6 +18,12 @@ export declare const proof: {
         positiveGenerationAccepted: () => void;
         httpsRejectedInParents: () => void;
         archivedAccepted: () => void;
+        lockAbsentAccepted: () => void;
+        emptyLockAccepted: () => void;
+        validLockAccepted: () => void;
+        malformedLockRejected: () => void;
+        invalidHashLockRejected: () => void;
+        aliasHashLockAccepted: () => void;
         wrongDialectRejected: () => void;
         missingSubjectRejected: () => void;
         extraFieldsAccepted: () => void;
@@ -28,4 +34,9 @@ export declare const proof: {
         malformedJsonRejected: () => void;
         ordinaryJsonRejected: () => void;
     };
+    encodeText: {
+        recursivelySortsObjectsLexicographically: () => void;
+        preservesArrayOrder: () => void;
+        parsedEquivalentSourcesConverge: () => void;
+    };
 };

package/fjs/media/revision/proof.f.js

@@ -1,9 +1,12 @@
 import { assert, assertEq } from '../../asserts/module.f.js';
-import { dialect, mediaType, isHash, validate, decodeText } from './module.f.js';
+import { dialect, mediaType, isHash, validate, decodeText, encodeText } from './module.f.js';
 // Valid cbase32 hashes (round-tripped in fjs/basen/cbase32/proof.f.ts): single
 // cbase32 symbols, cheap to write inline here.
 const h1 = '8';
 const h2 = 'r';
+// `I` is accepted as an alias spelling of canonical cBase32 `1`.
+const alias = 'I';
+const _lockMapAllowsMissingSubjects = {};
 // A shape-valid revision: every required field present (`snapshot` and
 // `generation` included), with `extra` overriding or adding fields per test.
 const revisionOf = (extra) => ({
@@ -95,6 +98,32 @@ export const proof = {
             const [t] = validate(revisionOf({ archived: true }));
             assertEq(t, 'ok');
         },
+        lockAbsentAccepted: () => {
+            const r = validate(revisionOf({}));
+            assert(r[0] === 'ok', ['expected ok', r]);
+            assertEq(r[1].lock, undefined);
+        },
+        emptyLockAccepted: () => {
+            const r = validate(revisionOf({ lock: {} }));
+            assert(r[0] === 'ok', ['expected ok', r]);
+            assertEq(Object.keys(r[1].lock ?? {}).length, 0);
+        },
+        validLockAccepted: () => {
+            const [t] = validate(revisionOf({ lock: { dependency: h1 } }));
+            assertEq(t, 'ok');
+        },
+        malformedLockRejected: () => {
+            const [t] = validate(revisionOf({ lock: { dependency: 1 } }));
+            assertEq(t, 'error');
+        },
+        invalidHashLockRejected: () => {
+            const [t] = validate(revisionOf({ lock: { dependency: 'https://example.com/x' } }));
+            assertEq(t, 'error');
+        },
+        aliasHashLockAccepted: () => {
+            const [t] = validate(revisionOf({ lock: { dependency: alias } }));
+            assertEq(t, 'ok');
+        },
         // Wrong dialect tag: structural validation rejects it outright.
         wrongDialectRejected: () => {
             const [t] = validate({ dialect: 'vnd.fjs.other', subject: h1, parents: [], snapshot: h2, generation: 0 });
@@ -137,4 +166,25 @@ export const proof = {
             assertEq(t, 'error');
         },
     },
+    encodeText: {
+        recursivelySortsObjectsLexicographically: () => {
+            const revision = revisionOf({ lock: { '2': h2, '10': h1 } });
+            const decoded = validate(revision);
+            assert(decoded[0] === 'ok', ['expected ok', decoded]);
+            assertEq(encodeText(decoded[1]), `{"dialect":"${dialect}","generation":0,"lock":{"10":"${h1}","2":"${h2}"},"parents":[],"snapshot":"${h2}","subject":"${h1}"}`);
+        },
+        preservesArrayOrder: () => {
+            const decoded = validate(revisionOf({ parents: [h2, h1] }));
+            assert(decoded[0] === 'ok', ['expected ok', decoded]);
+            assert(encodeText(decoded[1]).includes(`"parents":["${h2}","${h1}"]`));
+        },
+        parsedEquivalentSourcesConverge: () => {
+            const a = decodeText(` { "subject":"${h1}", "snapshot":"${h2}", "parents":[], "generation":0, "dialect":"${dialect}" } `);
+            const b = decodeText(`{"dialect":"${dialect}","generation":0,"parents":[],"snapshot":"${h2}","subject":"${h1}"}`);
+            assert(a[0] === 'ok', ['expected ok', a]);
+            assert(b[0] === 'ok', ['expected ok', b]);
+            assertEq(encodeText(a[1]), encodeText(b[1]));
+        },
+    },
 };
+void _lockMapAllowsMissingSubjects;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functionalscript",
-  "version": "0.43.0",
+  "version": "0.43.1",
   "type": "module",
   "files": [
     "**/*.js",