@graview/core 0.1.3 → 0.1.5

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,22 @@ 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";
+/** The batch a preview's ops are under when it was given none: no store mints it. */
+export const PREVIEW_BATCH = "preview";
 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 +63,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,11 +118,20 @@ 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;
+    /** True of a rehearsal (`previewAll`): what it does is told to nobody. */
+    rehearsing = false;
     listeners = new Set();
     constructor(options) {
         this.schema = options.schema;
@@ -122,6 +149,7 @@ export class Store {
         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)) {
@@ -271,7 +299,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".
@@ -328,10 +356,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() {
@@ -367,10 +395,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;
@@ -389,16 +420,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;
@@ -415,14 +483,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
@@ -541,7 +610,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)
@@ -555,6 +624,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. */
@@ -590,9 +662,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,
@@ -601,51 +673,52 @@ export class Store {
         });
     }
     /**
-     * What several calls would do as one gesture, without doing any of it
-     * (FR-18): each compiles on the graph the one before it left, as
-     * `applyAll` would run them, on a copy. The diff is the net of them all,
-     * and `introduces` and `resolves` judge the end state against today's.
-     * A call that cannot compile throws, as it would on applying; nothing is
-     * written, logged or heard either way.
+     * WHAT SEVERAL CALLS WOULD DO AS ONE GESTURE, JUDGED AS IT WOULD BE, WITHOUT
+     * DOING ANY OF IT (FR-18, FR-56).
+     *
+     * Not a second path beside `applyAll` but `applyAll`'s own, run on a
+     * rehearsal of this store — its graph and its log copied, nobody
+     * listening — so it cannot drift from it: it refuses exactly when the
+     * apply would, in the same words, for the same author, channel and batch
+     * — the policy, the seat's sight (a record the batch made earlier is its
+     * maker's for the calls after, read off the rehearsal's log as it goes),
+     * a declared agent's `may`, an act's own guard, and whatever `admit`
+     * throws, asked with the change as planned. Otherwise it answers what the
+     * apply would: the ops as the log would hold them, marked not kept (ids
+     * `preview:<n>`, `kept: false`), the net diff, and the problems after,
+     * judged in `context`. Nothing is written, logged, told to a subscriber
+     * of the store or its graph, or told to a watching harness; no id or
+     * batch this store would mint next is spent.
+     *
+     * Why not `applyAll(calls, { dryRun: true })`: a host wraps `applyAll` —
+     * `openRemote` sends every call down the wire — and a flag on it would
+     * travel with the call; and an answer that says `kept: false` in its type
+     * cannot be mistaken for one that was.
      */
-    previewAll(calls, context) {
-        const before = this.violations(context);
-        const start = this.graph.snapshot();
-        const trial = Graph.from(this.schema, start, { validate: this.validate });
-        const primitives = [];
-        const reads = new Set();
-        const writes = new Set();
-        const intents = [];
-        for (const call of calls) {
-            const compiled = compileMutation(trial, this.mutation(call.name), call.args);
-            // An act that does nothing leaves no trace when applied, nor here.
-            if (compiled.primitives.length === 0)
-                continue;
-            const recorded = compiled.primitives.map(normalise);
-            trial.applyPrimitives(recorded);
-            primitives.push(...recorded);
-            for (const id of compiled.reads)
-                reads.add(id);
-            for (const id of compiled.writes)
-                writes.add(id);
-            intents.push(compiled.intent);
-        }
-        const after = evaluate(trial, this.allInvariants(), {
-            ...this.invariantOptions,
-            ...(context === undefined ? {} : { context }),
+    previewAll(calls, options = {}) {
+        const { context, ...applying } = options;
+        const result = this.rehearsal().applying(calls, applying, context);
+        return { ...result, kept: false };
+    }
+    /**
+     * THIS STORE, TO REHEARSE ON (FR-56): its declaration, policy, modules and
+     * clock as they are, its graph and log copied, and nobody listening. Its
+     * op ids are `preview:<n>` and its batch `preview`, so nothing this store
+     * would mint next is spent; it tells a watching harness nothing.
+     */
+    rehearsal() {
+        const twin = Object.assign(Object.create(Store.prototype), this);
+        let made = 0;
+        Object.assign(twin, {
+            graph: Graph.from(this.schema, this.graph.snapshot(), { validate: this.validate }),
+            log: OperationLog.from(this.log.all(), this.log.epochs(), { horizon: this.log.horizon }),
+            listeners: new Set(),
+            labels: undefined,
+            nextId: () => `${PREVIEW_BATCH}:${++made}`,
+            mintBatch: () => PREVIEW_BATCH,
+            rehearsing: true,
         });
-        const beforeKeys = new Set(before.map(violationKey));
-        const afterKeys = new Set(after.map(violationKey));
-        return {
-            diff: diffSnapshots(start, trial.snapshot()),
-            primitives,
-            reads: [...reads],
-            writes: [...writes],
-            intent: intents.join("; "),
-            introduces: after.filter((v) => !beforeKeys.has(violationKey(v))),
-            resolves: before.filter((v) => !afterKeys.has(violationKey(v))),
-            violationsAfter: after,
-        };
+        return twin;
     }
     previewPrimitives(primitives, meta) {
         const before = this.violations(meta.context);
@@ -681,7 +754,7 @@ export class Store {
      * through the store's own path, whatever a host has wrapped `applyAll` in
      * (`openRemote` sends each one down the wire).
      */
-    applying(calls, options) {
+    applying(calls, options, context) {
         const batch = options.batch ?? this.mintBatch("batch");
         const author = options.author ?? HUMAN;
         const ops = [];
@@ -689,8 +762,9 @@ export class Store {
         const reads = new Set();
         const writes = new Set();
         const intents = [];
-        const before = this.violations();
+        const before = this.violations(context);
         const rollback = this.graph.snapshot();
+        const kept = this.log.length;
         /*
          * Permission is checked for the WHOLE gesture before any of it runs.
          *
@@ -704,7 +778,8 @@ export class Store {
             for (const call of calls) {
                 const verdict = this.permits(call, author);
                 if (!verdict.ok) {
-                    tellTheWatchOfARefusal(verdict.refusal, author.id);
+                    if (!this.rehearsing)
+                        tellTheWatchOfARefusal(verdict.refusal, author.id);
                     throw new PermissionDeniedError(verdict.refusal);
                 }
             }
@@ -720,17 +795,22 @@ 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);
+                if (!this.rehearsing)
+                    tellTheWatchOfARefusal(refusal, author.id);
                 throw new PermissionDeniedError(refusal);
             }
         }
-        tellTheWatchOfAnAuthor(author.id);
+        if (!this.rehearsing)
+            tellTheWatchOfAnAuthor(author.id);
         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.
                  *
@@ -768,6 +848,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 } : {}),
                 };
@@ -783,13 +865,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 after = this.violations();
+        const diff = diffSnapshots(rollback, this.graph.snapshot());
+        this.admitted(options, ops, allPrimitives, diff, rollback, kept);
+        const after = this.violations(context);
         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,
@@ -1056,7 +1140,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);
         }
@@ -1094,6 +1178,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(),
@@ -1115,10 +1200,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,
@@ -1133,6 +1219,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);
@@ -1377,6 +1490,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
@@ -1404,7 +1520,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