@graview/core 0.1.2 → 0.1.4

package/dist/store.js

@@ -1,5 +1,5 @@
-import { readingOf, seenBy, seesId } from "./seen.js";
-import { Graph, GraphError } from "./graph/graph.js";
+import { hidesFrom, readingOf, seatLens, seenBy, seesId } from "./seen.js";
+import { Graph, GraphError, MissingRecordError } from "./graph/graph.js";
 import { resolveModules } from "./modules.js";
 import { diffSnapshots, EMPTY_DIFF, isEmptyDiff } from "./graph/diff.js";
 import { invert, normalise, writesOf } from "./graph/primitives.js";
@@ -7,17 +7,20 @@ import { LabelIndex, refusalFor } from "./labels.js";
 import { nodeRefArgs } from "./mutations/node-ref.js";
 import { verifyFold } from "./integrity.js";
 import { evaluate } from "./invariants/engine.js";
-import { compileMutation } from "./mutations/define-mutation.js";
+import { compileMutation, READ_BEFORE_REFUSING } from "./mutations/define-mutation.js";
 import { deriveMutations, derivedVia } from "./mutations/derive-edits.js";
 import { OperationLog } from "./ops/log.js";
 import { actingAs, isSystem, permits, permittedMutations } from "./permissions/policy.js";
-import { redact } from "./ops/withheld.js";
+import { namesUnseen, redact } from "./ops/withheld.js";
 import { nounOf } from "./schema/define-node.js";
+import { creatorsBefore } from "./permissions/sight.js";
 import { PermissionDeniedError } from "./permissions/types.js";
 import { checkUndo, UndoBlockedError, undoPrimitives } from "./ops/undo.js";
 import { validateGraph } from "./validate-graph.js";
 import { tellTheWatchItsNames, tellTheWatchOfAStore, tellTheWatchOfAnAuthor, tellTheWatchOfARefusal } from "./watched.js";
 const HUMAN = { kind: "human" };
+/** The host itself, which sees what it keeps: the principal a question is asked as when no seat is named. */
+const SYSTEM = { kind: "system" };
 /** Who turns a module off or on: the workspace itself, `system · modules` (FR-12). */
 export const MODULES_AUTHOR = { kind: "system", id: "modules", name: "Modules" };
 /**
@@ -58,6 +61,19 @@ export class ReceiveError extends Error {
         this.name = "ReceiveError";
     }
 }
+/**
+ * A CALL NAMES AN ACT THE APP DOES NOT HAVE. Its message lists every act
+ * the store has, for the developer reading it; `mutation` is the name the
+ * call gave, so a surface that tells a person can say only that (FR-46).
+ */
+export class UnknownMutationError extends GraphError {
+    mutation;
+    constructor(mutation, registered) {
+        super(`Unknown mutation "${mutation}"`, `Registered: ${registered.join(", ") || "(none)"}`);
+        this.mutation = mutation;
+        this.name = "UnknownMutationError";
+    }
+}
 /**
  * A tag nobody else's store is using, for this store's batch ids. Drawn
  * from the platform's random source where there is one, which every page
@@ -100,7 +116,16 @@ export class Store {
     now;
     validate;
     mintBatch;
+    /**
+     * THE TAG THIS STORE MINTS ITS OWN BATCHES UNDER — `batch:<tag>:<n>` —
+     * when it mints them its default way; undefined when `batchIds` says
+     * otherwise. A server that takes batch ids from clients refuses this tag
+     * from one, so nothing the store lands later joins a client's batch.
+     */
+    batchTag;
     counter = 0;
+    /** The default op id generator's count. */
+    opCount = 0;
     /** Above zero while a rebase applies its pending calls again: they are told as one change at the end. */
     quiet = 0;
     listeners = new Set();
@@ -116,11 +141,11 @@ export class Store {
         }
         this.declaredModules = options.modules;
         this.startingModules = options.enabledModules;
-        let n = 0;
-        this.nextId = options.ids ?? (() => `op${++n}`);
+        this.nextId = options.ids ?? (() => `op${++this.opCount}`);
         this.now = options.now ?? (() => new Date().toISOString());
         this.validate = options.validate ?? true;
         const tag = storeTag();
+        this.batchTag = options.batchIds ? undefined : tag;
         this.mintBatch = options.batchIds ?? ((kind) => `${kind}:${tag}:${++this.counter}`);
         for (const mutation of options.mutations ?? []) {
             if (this.mutations.has(mutation.name)) {
@@ -174,18 +199,22 @@ export class Store {
          * Only the DEFAULT generators are wound forward; an app that supplies
          * its own `ids` owns their uniqueness.
          */
+        this.countPastTheLog();
+        tellTheWatchOfAStore(this);
+    }
+    /** Winds the default op and batch counters past every id the log holds, and past the horizon (FR-23). */
+    countPastTheLog() {
         const trailing = (value) => {
             const digits = /(\d+)$/.exec(value);
             return digits ? Number(digits[1]) : 0;
         };
         for (const op of this.log.all()) {
             this.counter = Math.max(this.counter, trailing(op.batch));
-            n = Math.max(n, trailing(op.id));
+            this.opCount = Math.max(this.opCount, trailing(op.id));
         }
         // Behind an undo horizon (FR-23) are ids the log no longer holds: count on past them all.
         if (this.log.horizon > 0)
-            n = Math.max(n, this.log.length);
-        tellTheWatchOfAStore(this);
+            this.opCount = Math.max(this.opCount, this.log.length);
     }
     /**
      * What the enabled modules work out to; every surface reads this one answer.
@@ -266,7 +295,7 @@ export class Store {
     mutation(name) {
         const found = this.mutations.get(name);
         if (!found) {
-            throw new GraphError(`Unknown mutation "${name}"`, `Registered: ${[...this.mutations.keys()].join(", ") || "(none)"}`);
+            throw new UnknownMutationError(name, [...this.mutations.keys()]);
         }
         // A refusal is a result: the mutation exists, and this workspace has its
         // module off — which is a different sentence from "unknown".
@@ -323,10 +352,10 @@ export class Store {
          * repair as the starter seat, which may only add, and the press met
          * "starter may not take-off here" (W-110).
          */
-        const narrowed = this.refusesAgent(call, principal) ?? this.namesTurnedOff(call) ?? this.namesUnseen(call, principal);
+        const narrowed = this.refusesAgent(call, principal) ?? this.namesTurnedOff(call, principal);
         if (narrowed)
             return { ok: false, refusal: narrowed };
-        return permits(this.policy, principal, call.name, this.subjectKindOf(call), this.viaOf(this.mutations.get(call.name)), this.subjectIdOf(call), this.words);
+        return permits(this.policy, principal, call.name, this.subjectKindOf(call, principal), this.viaOf(this.mutations.get(call.name)), this.subjectIdOf(call), this.words);
     }
     /** How the policy's refusals name an act and a kind: by title and noun, never by id. */
     get words() {
@@ -362,10 +391,13 @@ export class Store {
      * the core owns — a rename that takes any kind — must not reach into a
      * district the workspace does not have. The sentence names the act.
      */
-    namesTurnedOff(call) {
+    namesTurnedOff(call, principal = SYSTEM) {
         const off = this.modules.disabledKinds;
         if (off.size === 0)
             return undefined;
+        // A seat the module's records are kept from is not told they are there: naming one is naming nothing (FR-55).
+        if (!isSystem(principal))
+            return undefined;
         const mutation = this.mutations.get(call.name);
         if (!mutation)
             return undefined;
@@ -384,16 +416,53 @@ export class Store {
         };
     }
     /**
-     * A CALL THAT NAMES A RECORD THE CALLER MAY NOT SEE IS REFUSED (FR-02),
-     * before any grant is read: an act on a record is a way of reading it —
-     * its preview, its refusal, what its rules say after — and a seat that
-     * could act on what it may not see could learn it that way. Only a
-     * record that is there is judged; an id that names nothing is the act's
-     * own to refuse. The sentence names the act, never the record or its kind.
+     * AN ACT'S SENTENCE IS WORDED FROM ITS AUTHOR'S VIEW (FR-55). `describe`
+     * reads the graph to name what the act touched ("Point at Venue"); read
+     * from the whole store, it named a record the author may not see by its
+     * label, and so told the author whether a guessed id was real. Read from
+     * the store as the author is served it, such a record is named only by
+     * what the author wrote, as one that does not exist is. A reader who sees
+     * more reads the author's sentence as the author would have. With nothing
+     * kept from the author, the store's own graph.
      */
-    namesUnseen(call, principal) {
-        if (!this.policy?.sees?.length || isSystem(principal))
-            return undefined;
+    wordedFor(author) {
+        if (author === undefined || !hidesFrom(this, author))
+            return {};
+        // And a seat that writes a value naming what it may not see has written its own words, though the store held them already.
+        const hidden = seesId(this, author);
+        return { describeWith: seenBy(this, author).graph, keepUnchanged: (value) => namesUnseen(value, hidden) };
+    }
+    /**
+     * AN ACT'S OWN REFUSAL, AS ITS CALLER MAY READ IT (FR-55). An act's body
+     * may refuse in its own words, worded from what it read — "Freya Davies
+     * is already booked" — and what it read may be a record its caller may
+     * not see. Such a refusal is said without its words: the act, and that it
+     * could not be done. The store's own refusals already name nothing.
+     */
+    refusalWordedFor(error, author, calls) {
+        if (!hidesFrom(this, author) || error instanceof PermissionDeniedError || error instanceof MissingRecordError || error === null || typeof error !== "object")
+            return error;
+        const read = error[READ_BEFORE_REFUSING] ?? [];
+        const visible = seesId(this, author);
+        if (!read.some((id) => this.graph.has(id) && !visible(id)))
+            return error;
+        const title = calls.length === 1 ? (this.mutations.get(calls[0].name)?.title ?? calls[0].name) : undefined;
+        return new GraphError(title ? `“${title}” could not be done as asked.` : "This change could not be done as asked.");
+    }
+    /**
+     * A CALL THAT NAMES A RECORD THAT IS NOT THERE FOR ITS CALLER IS REFUSED
+     * AS MISSING (FR-02, FR-55) — one that does not exist, and one the caller
+     * may not see, alike: the same `MissingRecordError`, the same sentence,
+     * reason `missing`. Ids are minted from labels, so a seat can guess one,
+     * and a refusal that told a hidden record from an absent one would tell
+     * it which guesses were real. An act on a record is also a way of reading
+     * it — its preview, what its rules say after — so a hidden one is never
+     * acted on by a seat that may not see it. Asked of each call as it is
+     * about to run, so a record an earlier call in the same gesture made is
+     * there. The sentence names the act, never the id: it says the same of a
+     * hidden record and an absent one, and says back nothing the seat sent.
+     */
+    missingFor(call, principal = HUMAN) {
         const mutation = this.mutations.get(call.name);
         if (!mutation)
             return undefined;
@@ -410,14 +479,15 @@ export class Store {
             add(call.args[mutation.subject.arg]);
         for (const ref of nodeRefArgs(mutation.input))
             add(call.args[ref.name]);
-        const visible = seesId(this, principal);
-        if (![...named].some((id) => this.graph.has(id) && !visible(id)))
+        if (named.size === 0)
             return undefined;
-        return {
-            mutation: call.name,
-            message: `Not permitted: “${mutation.title ?? call.name}” names a record you may not see.`,
-            wouldNeed: [],
-        };
+        const visible = seesId(this, principal);
+        for (const id of named) {
+            if (this.graph.has(id) && visible(id))
+                continue;
+            return new MissingRecordError(id, `“${mutation.title ?? call.name}” names a record that is not there.`);
+        }
+        return undefined;
     }
     /**
      * Whether a principal may run ANY act of a module drawn only for those
@@ -536,7 +606,7 @@ export class Store {
      * refuses that case rather than allowing it: the safe reading of "I could
      * not tell what this acts on" is no.
      */
-    subjectKindOf(call) {
+    subjectKindOf(call, principal = SYSTEM) {
         const definition = this.mutations.get(call.name);
         const subject = definition?.subject;
         if (!subject)
@@ -550,6 +620,9 @@ export class Store {
          */
         if (typeof id !== "string")
             return subject.kinds !== "*" && subject.kinds.length === 1 ? subject.kinds[0] : undefined;
+        // A record the principal may not see is judged as one that is not there: its kind is not the policy's to read aloud (FR-55).
+        if (!isSystem(principal) && !seesId(this, principal)(id))
+            return undefined;
         return this.graph.getNode(id)?.kind;
     }
     /** Current violations, evaluated fresh — nothing is cached or stale. */
@@ -585,9 +658,9 @@ export class Store {
             return true;
         }
     }
-    preview(call, context) {
+    preview(call, context, options = {}) {
         const definition = this.mutation(call.name);
-        const compiled = compileMutation(this.graph, definition, call.args);
+        const compiled = compileMutation(this.graph, definition, call.args, this.wordedFor(options.author));
         return this.previewPrimitives(compiled.primitives, {
             reads: compiled.reads,
             writes: compiled.writes,
@@ -686,6 +759,7 @@ export class Store {
         const intents = [];
         const before = this.violations();
         const rollback = this.graph.snapshot();
+        const kept = this.log.length;
         /*
          * Permission is checked for the WHOLE gesture before any of it runs.
          *
@@ -715,7 +789,7 @@ export class Store {
          * was brought in for, and the narrower of the two wins.
          */
         for (const call of calls) {
-            const refusal = this.refusesAgent(call, author) ?? this.namesTurnedOff(call);
+            const refusal = this.refusesAgent(call, author) ?? this.namesTurnedOff(call, author);
             if (refusal) {
                 tellTheWatchOfARefusal(refusal, author.id);
                 throw new PermissionDeniedError(refusal);
@@ -725,7 +799,10 @@ export class Store {
         try {
             for (const call of calls) {
                 const definition = this.mutation(call.name);
-                const compiled = compileMutation(this.graph, definition, call.args);
+                const missing = this.missingFor(call, author);
+                if (missing)
+                    throw missing;
+                const compiled = compileMutation(this.graph, definition, call.args, this.wordedFor(author));
                 /*
                  * AN ACT THAT DID NOTHING DOES NOT GO IN THE HISTORY.
                  *
@@ -763,6 +840,8 @@ export class Store {
                     inverse: [...compiled.primitives].reverse().map(normalise).map(invert),
                     reads: compiled.reads,
                     writes: compiled.writes,
+                    // Which records its sentence read, so a reader who may not see one is not handed the sentence (FR-55).
+                    ...(definition.describe !== undefined && compiled.described && compiled.described.length > 0 ? { described: compiled.described } : {}),
                     at: this.now(),
                     ...(options.via !== undefined ? { via: options.via } : {}),
                 };
@@ -778,13 +857,15 @@ export class Store {
             }
         }
         catch (error) {
-            this.graph.load(rollback);
-            throw error;
+            // A batch refused part way keeps none of it: the graph, and the ops it had logged before the refusal.
+            this.putBack(rollback, kept);
+            throw this.refusalWordedFor(error, author, calls);
         }
+        const diff = diffSnapshots(rollback, this.graph.snapshot());
+        this.admitted(options, ops, allPrimitives, diff, rollback, kept);
         const after = this.violations();
         const beforeKeys = new Set(before.map(violationKey));
         const afterKeys = new Set(after.map(violationKey));
-        const diff = diffSnapshots(rollback, this.graph.snapshot());
         this.notify(diff, ops);
         return {
             batch,
@@ -1051,7 +1132,7 @@ export class Store {
          */
         const sighted = (this.policy?.sees?.length ?? 0) > 0 && !isSystem(author);
         if (sighted) {
-            const seen = checkUndo(readingOf(redact(this.log.all(), seesId(this, author)), () => this.log.epochs()), ids);
+            const seen = checkUndo(readingOf(redact(this.log.all(), seatLens(this, author)), () => this.log.epochs()), ids);
             if (!seen.ok)
                 throw new UndoBlockedError(seen);
         }
@@ -1089,6 +1170,7 @@ export class Store {
         const rollback = this.graph.snapshot();
         const before = this.violations();
         const ops = [];
+        const kept = this.log.length;
         for (const target of [...check.ops].sort((a, b) => b.seq - a.seq)) {
             const op = {
                 id: this.nextId(),
@@ -1110,10 +1192,11 @@ export class Store {
             this.log.append(op);
             ops.push(op);
         }
+        const diff = diffSnapshots(rollback, this.graph.snapshot());
+        this.admitted(options, ops, ops.flatMap((op) => [...op.primitives]), diff, rollback, kept);
         const after = this.violations();
         const beforeKeys = new Set(before.map(violationKey));
         const afterKeys = new Set(after.map(violationKey));
-        const diff = diffSnapshots(rollback, this.graph.snapshot());
         this.notify(diff, ops);
         return {
             batch,
@@ -1128,6 +1211,33 @@ export class Store {
             violationsAfter: after,
         };
     }
+    /** A change not kept: the graph as it was, and the log cut back to where it stood. */
+    putBack(rollback, kept) {
+        this.graph.load(rollback);
+        if (this.log.length > kept)
+            this.log.truncate(kept);
+    }
+    /** Asks the host's `admit`, when there is one, with the change as planned; one it refuses is put back, and its word goes on up. */
+    admitted(options, ops, primitives, diff, rollback, kept) {
+        if (!options.admit || ops.length === 0)
+            return;
+        const size = this.graph.size;
+        try {
+            options.admit({
+                ops,
+                primitives,
+                added: { nodes: diff.addedNodes.length, edges: diff.addedEdges.length },
+                removed: { nodes: diff.removedNodes.length, edges: diff.removedEdges.length },
+                changed: { nodes: diff.changedNodes.length },
+                nodesAfter: size.nodes,
+                edgesAfter: size.edges,
+            });
+        }
+        catch (error) {
+            this.putBack(rollback, kept);
+            throw error;
+        }
+    }
     /** Redo is the undo of an undo — no separate stack exists. */
     redo(undoBatchId, options = {}) {
         return this.undo(undoBatchId, options);
@@ -1253,6 +1363,78 @@ export class Store {
         this.notify(diff, ops);
         return { diff, confirmed: landed, pending: replayed, refused };
     }
+    /**
+     * A CLIENT THAT RESYNCED TAKES THE SERVER'S WHOLE STATE (FR-53).
+     *
+     * `rebase` lands the server's ops on the confirmed prefix this store
+     * holds. When that prefix cannot be trusted — this copy drifted, and an
+     * op of the server's no longer fits it, or the server compacted past
+     * where this client left off, so `/graview/since` cannot bring the ops in
+     * between — the client takes the server's graph and log as they are:
+     *
+     * 1. the ops of the `pending` batches are read off the log as it stands;
+     * 2. the log becomes `log` (with its `epochs` and `horizon`, checked as
+     *    `OperationLog.from` checks them; one that is not intact is refused
+     *    before anything moves) and the graph becomes `snapshot`, in the
+     *    server's order — not put back op by op, as `rebase` puts it;
+     * 3. the `pending` batches are applied again on top, in the order given,
+     *    exactly as `rebase` applies them: under the same batch ids, judged
+     *    and compiled afresh. One that no longer applies is said in `refused`.
+     *
+     * `drop` names the batches the server has answered or refused: they are
+     * not applied again (nor is any batch left unnamed: the log is the
+     * server's). Subscribers hear ONE change, the net diff, with the ops this
+     * store did not hold before and the re-applied ones.
+     */
+    adopt(state) {
+        const dropped = new Set(state.drop ?? []);
+        const pending = (state.pending ?? []).filter((batch) => !dropped.has(batch));
+        const held = this.log.all();
+        const before = this.graph.snapshot();
+        const was = { ops: [...held], epochs: [...this.log.epochs()], horizon: this.log.horizon };
+        const known = new Set(held.map((op) => op.id));
+        const tails = new Map(pending.map((batch) => [batch, held.filter((op) => op.batch === batch)]));
+        // A log that is not intact is refused here, before the graph moves.
+        if (state.log.length > 0)
+            this.log.replace(state.log, state.epochs, state.horizon !== undefined ? { horizon: state.horizon } : {});
+        else {
+            const at = state.horizon ?? 0;
+            this.log.replace([], state.epochs ?? [{ seq: at, base: state.snapshot }], { horizon: at });
+        }
+        const replayed = [];
+        const refused = [];
+        this.quiet++;
+        try {
+            this.graph.load(state.snapshot);
+            this.projected = undefined;
+            this.countPastTheLog();
+            for (const batch of pending) {
+                const ops = tails.get(batch) ?? [];
+                if (ops.length === 0)
+                    continue;
+                try {
+                    replayed.push(...this.replay(batch, ops));
+                }
+                catch (error) {
+                    refused.push({ batch, error });
+                }
+            }
+        }
+        catch (error) {
+            // A store that could not adopt is the store it was.
+            this.log.replace(was.ops, was.epochs, { horizon: was.horizon });
+            this.graph.load(before);
+            this.projected = undefined;
+            throw error;
+        }
+        finally {
+            this.quiet--;
+        }
+        const adopted = this.log.all().filter((op) => !known.has(op.id) && !replayed.includes(op));
+        const diff = diffSnapshots(before, this.graph.snapshot());
+        this.notify(diff, [...adopted, ...replayed]);
+        return { diff, adopted, pending: replayed, refused };
+    }
     /** One pending batch, applied again as it was made: its calls, its undo, or its primitives. */
     replay(batch, ops) {
         const head = ops[0];
@@ -1300,6 +1482,9 @@ export class Store {
      * 1000). It is moved back to the start of the gesture it would split, so
      * a batch is never half behind it.
      *
+     * The checkpoint keeps who made each record behind it (`creators`), so a
+     * store opened on it knows a record's maker without the archived ops.
+     *
      * Nothing moves until `compact` is handed the checkpoint, so a host can
      * archive what is behind it first. A store whose graph does not verify
      * against its log is not compacted: the checkpoint would vouch for a
@@ -1327,7 +1512,10 @@ export class Store {
         const verified = this.verify();
         if (!verified.ok)
             throw new GraphError(`Cannot compact a store that does not verify: ${verified.reason}`);
-        return this.log.checkpointAt(this.schema, seq, { validate: this.validate });
+        const checkpoint = this.log.checkpointAt(this.schema, seq, { validate: this.validate });
+        // Who made each record behind it, so a store opened on it still knows (an `own` sight reads the log for it).
+        const creators = creatorsBefore(this.log, seq);
+        return Object.keys(creators).length > 0 ? { ...checkpoint, creators } : checkpoint;
     }
     /**
      * MOVES THE UNDO HORIZON TO `checkpoint` (FR-23): the ops and epochs