@graview/core 0.1.60 → 0.1.62

package/dist/store.js

@@ -13,12 +13,13 @@ import { compileMutation } from "./mutations/define-mutation.js";
 import { wouldRun } from "./mutations/would-run.js";
 import { actSpelledAs, nearestAct } from "./mutations/act-spelling.js";
 import { InvalidArguments } from "./mutations/invalid-arguments.js";
-import { deriveMutations, derivedVia, removeVia } from "./mutations/derive-edits.js";
+import { deriveMutations, derivedVia, editMutationName, editVia, removeVia } from "./mutations/derive-edits.js";
 import { repeatingFields, repeatMakes } from "./mutations/derive-repeats.js";
 import { namesMade, resolveMade } from "./mutations/made.js";
 import { OperationLog } from "./ops/log.js";
 import { lineageOf } from "./ops/lineage.js";
 import { KEEP_LINK, keepLinkMutation, keepLinkVia } from "./mutations/keep-link.js";
+import { VOTE_SUGGESTION, VOTING, voteSuggestionMutation } from "./mutations/vote-suggestion.js";
 import { TYPE_TEXT, TYPING } from "./text/typing-hook.js";
 import { declinedIn, isAutomated, tidyingRefusal } from "./ops/tidying.js";
 import { nameOfAuthor } from "./who.js";
@@ -36,6 +37,8 @@ import { dayOf } from "./clock.js";
 import { pluralOf } from "./schema/define-node.js";
 import { linkedReaderOf } from "./schema/linked.js";
 import { onPublish, PUBLISH, PUBLISHING } from "./publish.js";
+import { FORMATS } from "./format-error.js";
+import { formatStamp } from "./formats.js";
 /** A change asked of a store of the past (Roadmap f-playback): the past is read, never changed. */
 export class PastError extends GraphError {
     constructor(at) {
@@ -182,11 +185,15 @@ export class Store {
     keeper;
     /** "Type text", when the store answers to its own (Roadmap f-collab-text). */
     typer;
+    /** "Vote on a suggestion" (Roadmap f-suggestion-votes), when the app declared no act by that name. */
+    voter;
     invariants;
     invariantOptions;
     policy;
     /** When edits reach readers (`StoreOptions.publishing`). */
     publishing;
+    /** What the declaration says of suggestions as a whole (`StoreOptions.tidying`). */
+    tidying;
     /**
      * The intelligence the app declared, so a surface can read the DOORS.
      *
@@ -249,6 +256,7 @@ export class Store {
             this.ticked = { day: isoToday(this.timeZone), on: isoToday(this.timeZone) };
         this.policy = options.policy;
         this.publishing = options.publishing;
+        this.tidying = options.tidying;
         this.by = options.principal ?? HUMAN;
         this.intelligence = options.intelligence ?? [];
         for (const provider of options.intelligence ?? []) {
@@ -286,6 +294,11 @@ export class Store {
             this.keeper = keepLinkMutation(options.schema);
             this.mutations.set(KEEP_LINK, this.keeper);
         }
+        // "Vote on a suggestion" (Roadmap f-suggestion-votes): answered by every store, offered by no list. An app's own `vote-suggestion` keeps its name.
+        if (!options.past && !this.mutations.has(VOTE_SUGGESTION)) {
+            this.voter = voteSuggestionMutation();
+            this.mutations.set(VOTE_SUGGESTION, this.voter);
+        }
         const horizon = given("horizon", options.horizon);
         const validate = { validate: this.validate };
         if (options.log) {
@@ -494,7 +507,7 @@ export class Store {
         return mutation.derived !== undefined && this.modules.disabledKinds.has(mutation.derived.kind);
     }
     allMutations() {
-        return [...this.mutations.values(), ...(this.publisher ? [this.publisher] : [])].filter((mutation) => mutation !== this.keeper && mutation !== this.typer && !this.mutationDisabled(mutation));
+        return [...this.mutations.values(), ...(this.publisher ? [this.publisher] : [])].filter((mutation) => mutation !== this.keeper && mutation !== this.typer && mutation !== this.voter && !this.mutationDisabled(mutation));
     }
     /** The declared acts a derived act resolves its permission through; keeping a link, those that make or break its relation. */
     viaOf(mutation, call, principal) {
@@ -565,6 +578,9 @@ export class Store {
         // Publishing is the declaration's `publishers`, not a grant's.
         if (mutation && mutation === this.publisher)
             return PUBLISHING.verdict(this, principal);
+        // A vote on a suggestion is anybody's who may see it (Roadmap f-suggestion-votes): whether they do is judged where the op is made.
+        if (mutation && mutation === this.voter)
+            return { ok: true };
         /*
          * KEEPING A LINK ONLY THE DERIVED ACTS MAKE is judged as they are: on
          * the record it leaves, so riding everybody's grant it reaches only the
@@ -598,6 +614,17 @@ export class Store {
         mutation !== undefined && (mutation.derived !== undefined || mutation === this.typer || keeping) ? () => this.madeBy(mutation, call, id) : undefined, 
         // Taking a record out, or folding it away, rides the making of the kind only over what this principal made (W-201).
         mutation?.derived !== undefined && UNMAKING.has(mutation.derived.act));
+        /*
+         * A VALUE CARRIED ACROSS A LINK (Roadmap f-acts-update-linked) is each
+         * far record's own edit: the act is refused, naming the record, where
+         * this principal may not change one of the records its subject is
+         * linked to — judged here, before `apply`, as every grant is.
+         */
+        if (verdict.ok && mutation?.writesLinked && typeof id === "string") {
+            const refused = this.refusesLinked(mutation, id, principal);
+            if (refused)
+                return refused;
+        }
         if (!verdict.ok || !mutation?.derived || !this.repeatMakes(mutation, call, id, principal))
             return verdict;
         /*
@@ -608,6 +635,44 @@ export class Store {
          */
         return permits(this.policy, principal, call.name, kind, removeVia([...this.mutations.values()], mutation.derived.kind), typeof id === "string" ? id : undefined, this.words);
     }
+    /**
+     * The first record linked to the subject that this principal may not
+     * change, as a refusal of the act naming it (Roadmap f-acts-update-linked);
+     * undefined when every record the act would carry a value to is theirs to
+     * edit. Each is judged as its kind's own edit is — the grants, the acts the
+     * edit rides, what the principal made — over the graph as they see it.
+     */
+    refusesLinked(mutation, subjectId, principal) {
+        const served = isSystem(principal) ? this.graph : seenBy(this, principal).graph;
+        const subject = served.getNode(subjectId);
+        if (!subject)
+            return undefined;
+        const all = [...this.mutations.values()];
+        for (const relation of Object.keys(mutation.writesLinked ?? {})) {
+            const declaredHere = this.schema.tryDefinition(subject.kind)?.edges?.[relation] !== undefined;
+            const far = declaredHere ? served.out(subject.id, relation) : served.in(subject.id, relation);
+            for (const node of far) {
+                const edit = editMutationName(node.kind);
+                const own = this.mutations.get(edit);
+                const verdict = own ? this.permits({ name: edit, args: { [own.subject?.arg ?? "id"]: node.id } }, principal) : permits(this.policy, principal, edit, node.kind, editVia(this.schema, all, node.kind), node.id, this.words);
+                if (verdict.ok)
+                    continue;
+                const title = this.words.act?.(mutation.name) ?? mutation.name;
+                const label = (this.labels ??= new LabelIndex(this.graph)).labelOf(node.id) ?? node.id;
+                const noun = this.words.noun?.(node.kind) ?? node.kind;
+                return {
+                    ok: false,
+                    refusal: {
+                        mutation: mutation.name,
+                        kind: subject.kind,
+                        wouldNeed: verdict.refusal.wouldNeed,
+                        message: `Not permitted: “${title}” would change “${label}”, ${/^[aeiou]/i.test(noun) ? "an" : "a"} ${noun} that is not yours to change. ${verdict.refusal.message}`,
+                    },
+                };
+            }
+        }
+        return undefined;
+    }
     /** Whether a call of a repeat act makes a record (`repeatMakes`), read off the series as this principal is served it. */
     repeatMakes(mutation, call, id, principal) {
         const act = mutation.derived.act;
@@ -1116,6 +1181,23 @@ export class Store {
         Object.assign(twin, { typer, mutations: typer ? new Map(this.mutations).set(TYPE_TEXT, typer) : new Map(this.mutations) });
         return twin;
     }
+    /**
+     * Whether these calls, as this author with this lineage, would be kept
+     * rather than refused — rehearsed, told to nobody. What a vote asks
+     * before it has the app's own actor make a suggestion that reached
+     * `autoAcceptAt` (Roadmap f-suggestion-votes): a record a person said to
+     * leave alone, or a change a person declined meanwhile, leaves the
+     * suggestion waiting for someone who may, and the vote stands.
+     */
+    wouldKeep(calls, author, lineage) {
+        try {
+            this.rehearsal().applying(calls, { author, lineage });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     previewPrimitives(primitives, meta) {
         const before = this.violations(meta.context);
         const trial = Graph.from(this.schema, this.graph.snapshot());
@@ -1178,20 +1260,29 @@ export class Store {
          * seat holds say what it may do at all; `may` narrows what THIS provider
          * was brought in for, and the narrower of the two wins.
          */
-        const permitted = (call) => {
-            const verdict = this.policy || (this.publisher && call.name === PUBLISH) ? this.permits(call, author) : undefined;
+        const permitted = (call, as = author) => {
+            const verdict = this.policy || (this.publisher && call.name === PUBLISH) ? this.permits(call, as) : undefined;
             if (verdict && !verdict.ok)
-                this.refuse(verdict.refusal, author.id);
+                this.refuse(verdict.refusal, as.id);
         };
-        const declared = (call) => {
-            const refusal = this.refusesAgent(call, author) ?? this.namesTurnedOff(call, author);
+        const declared = (call, as = author) => {
+            const refusal = this.refusesAgent(call, as) ?? this.namesTurnedOff(call, as);
             if (refusal)
-                this.refuse(refusal, author.id);
+                this.refuse(refusal, as.id);
         };
         /* A call that names a record an earlier call makes (`{ $made: n }`, FR-193) is asked once that record is there to name. */
         const naming = calls.map(namesMade);
         calls.forEach((call, at) => naming[at] || permitted(call));
         calls.forEach((call, at) => naming[at] || declared(call));
+        /*
+         * THE GESTURE'S CALLS, AND WHAT ONE OF THEM HAS THE APP'S OWN ACTOR MAKE
+         * (Roadmap f-suggestion-votes): a vote that brings a suggestion to the
+         * declaration's `autoAcceptAt` queues the suggestion's calls behind it,
+         * as the actor, in this same gesture — one batch, one undo, one answer
+         * to whoever sent it — and the people who voted decided it, so the
+         * declaration's `tidying` does not stand in the actor's way (`decided`).
+         */
+        const queue = calls.map((sent) => ({ sent, as: author, lineage, decided: false }));
         /*
          * THE APP'S OWN ACTOR IS HELD TO WHAT PEOPLE SAID: a change a person
          * declined is not made again, a record a person said to leave alone is
@@ -1216,38 +1307,55 @@ export class Store {
         const renamed = new Map();
         const rename = (value) => (typeof value === "string" ? (renamed.get(value) ?? value) : Array.isArray(value) ? value.map(rename) : value);
         try {
-            for (const [at, sent] of calls.entries()) {
+            for (let at = 0; at < queue.length; at++) {
+                const { sent, as, lineage: lined, decided } = queue[at];
+                const named = at < naming.length ? naming[at] : namesMade(sent);
                 const { mintedHint: hint, ...plain } = sent;
                 const asked = renamed.size ? { ...plain, args: Object.fromEntries(Object.entries(plain.args).map(([key, value]) => [key, rename(value)])) } : plain;
-                const call = naming[at] ? resolveMade(asked, madeIds, at) : asked;
-                if (naming[at])
-                    (permitted(call), declared(call));
+                const call = named ? resolveMade(asked, madeIds, at) : asked;
+                if (named || decided)
+                    (permitted(call, as), declared(call, as));
                 const definition = this.mutation(call.name);
                 if (definition === this.publisher) {
-                    const op = PUBLISHING.op(this, { id: this.nextId(), at: this.now() }, call, batch, author, options);
+                    const op = PUBLISHING.op(this, { id: this.nextId(), at: this.now() }, call, batch, as, options);
                     ops.push(op);
                     intents.push(op.intent);
                     continue;
                 }
-                const missing = this.missingFor(call, author);
+                if (definition === this.voter) {
+                    // A vote on a suggestion (Roadmap f-suggestion-votes): its op, judged as the voter sees the suggestion, and nothing of the graph.
+                    if (!VOTING.op)
+                        throw new GraphError("Load @graview/core/tidying to vote on a suggestion.");
+                    const op = VOTING.op(this, { id: this.nextId(), at: this.now() }, call, batch, as, options);
+                    this.log.append(op);
+                    ops.push(op);
+                    intents.push(op.intent);
+                    // At the declaration's `autoAcceptAt`, the suggestion is made here, in the same gesture, by the app's own actor — when the actor would be let.
+                    const accept = VOTING.accepting?.(this, op);
+                    if (accept && this.wouldKeep(accept.calls, accept.author, accept.lineage))
+                        for (const made of accept.calls)
+                            queue.push({ sent: made, as: accept.author, lineage: lineageOf(accept.lineage), decided: true });
+                    continue;
+                }
+                const missing = this.missingFor(call, as);
                 if (missing)
                     throw missing;
                 let compiled;
                 try {
-                    compiled = compileMutation(this.graph, definition, call.args, { ...this.sighted(author), hint });
+                    compiled = compileMutation(this.graph, definition, call.args, { ...this.sighted(as), hint });
                 }
                 catch (error) {
                     // A press the act's own input refused: the watch tells a form filled wrongly from an act offered whole.
                     if (error instanceof InvalidArguments && !this.rehearsing)
-                        tellTheWatchOfAnInputRefusal(error, author.id);
+                        tellTheWatchOfAnInputRefusal(error, as.id);
                     throw error;
                 }
                 if (hint !== undefined && compiled.firstMinted !== undefined && compiled.firstMinted !== hint)
                     renamed.set(hint, compiled.firstMinted);
-                if (automated) {
-                    const refused = tidyingRefusal(this.schema, this.graph, compiled.primitives, this.authorName(author), { declaration: !this.suggesting });
+                if (isAutomated(as)) {
+                    const refused = tidyingRefusal(this.schema, this.graph, compiled.primitives, this.authorName(as), { declaration: !this.suggesting && !decided });
                     if (refused)
-                        this.refuse({ mutation: call.name, message: refused, wouldNeed: [] }, author.id);
+                        this.refuse({ mutation: call.name, message: refused, wouldNeed: [] }, as.id);
                 }
                 /*
                  * AN ACT THAT DID NOTHING DOES NOT GO IN THE HISTORY.
@@ -1268,7 +1376,7 @@ export class Store {
                     id: this.nextId(),
                     seq: this.log.length,
                     batch,
-                    author,
+                    author: as,
                     /*
                      * THE ACT'S OWN SENTENCE, kept; what the gesture was for goes
                      * beside it (FR-18). An act with no `describe` has no sentence of
@@ -1292,7 +1400,7 @@ export class Store {
                     ...given("mergedInto", compiled.mergedInto),
                     at: this.now(),
                     ...given("via", options.via),
-                    ...given("lineage", lineage),
+                    ...given("lineage", lined),
                 };
                 this.graph.applyPrimitives(op.primitives);
                 this.log.append(op);
@@ -1679,6 +1787,13 @@ export class Store {
                  */
                 const judged = this.rootOf(target);
                 const by = actingAs(judged.author).id;
+                // A vote is its voter's to take back (Roadmap f-suggestion-votes), the system's, or a seat's the policy grants every act.
+                if (judged.vote !== undefined) {
+                    if (this.policy && !isSystem(author) && by !== actingAs(author).id && !this.grantsEveryAct(author)) {
+                        return { mutation: "undo", wouldNeed: [], message: `Not permitted to undo "${target.intent}": only whoever voted takes their vote back.` };
+                    }
+                    continue;
+                }
                 if (!judged.mutation) {
                     // A change that changed nothing (a suggestion, an announcement) is anybody's who sees it to take back: declining a suggestion is one.
                     if (judged.primitives.length === 0)
@@ -2053,19 +2168,44 @@ export class Store {
         const pinned = [...(options.pins ?? []), ...readers].filter((pin) => Number.isInteger(pin));
         if (pinned.length > 0)
             seq = Math.min(seq, ...pinned);
-        seq = Math.min(Math.max(seq, this.log.horizon), this.log.length);
-        // Never inside a gesture: back to where the batch it would split began.
-        while (seq > this.log.horizon && seq < this.log.length && ops[seq - this.log.horizon].batch === ops[seq - 1 - this.log.horizon].batch)
-            seq--;
+        const format = options.format ?? FORMATS.snapshot;
+        if (!Number.isInteger(format) || format < 1 || format > FORMATS.snapshot) {
+            throw new RangeError(`Cannot write a checkpoint in snapshot format ${String(format)}: this build writes formats 1 to ${FORMATS.snapshot}.`);
+        }
+        // Never past the head or behind the horizon, and never inside a gesture: back to where the batch it would split began.
+        const settled = (asked) => {
+            let at = Math.min(Math.max(asked, this.log.horizon), this.log.length);
+            while (at > this.log.horizon && at < this.log.length && ops[at - this.log.horizon].batch === ops[at - 1 - this.log.horizon].batch)
+                at--;
+            return at;
+        };
+        seq = settled(seq);
         if (seq <= this.log.horizon)
             return undefined;
         const verified = this.verify();
         if (!verified.ok)
             throw new GraphError(`Cannot compact a store that does not verify: ${verified.reason}`);
+        let checkpoint = this.checkpointWithPublished(seq);
         /*
-         * And the app as readers were served it at each published seq behind it they may be served again: folded here where the
-         * log still holds it, carried from the checkpoint before where it does not, so a horizon past old publishes loses none.
+         * READABLE AS THE FORMAT ASKED FOR (FR-31): a checkpoint keeping the app as readers are served at a seq behind it
+         * (`published`) is snapshot format 2, which a build before it would misread (`formatStamp`). Asked for format 1,
+         * the horizon is held at the earliest such seq instead — and again where that lands past another — until the stamp
+         * says 1; the checkpoint's seq says where it stopped, and none is made when that is the horizon already.
          */
+        while (formatStamp(checkpoint).formats.snapshot > format) {
+            seq = settled(Math.min(...checkpoint.published.map((kept) => kept.seq)));
+            if (seq <= this.log.horizon)
+                return undefined;
+            checkpoint = this.checkpointWithPublished(seq);
+        }
+        return checkpoint;
+    }
+    /**
+     * The checkpoint at `seq`, and the app as readers were served it at each published seq behind it they may be served
+     * again: folded here where the log still holds it, carried from the checkpoint before where it does not, so a horizon
+     * past old publishes loses none.
+     */
+    checkpointWithPublished(seq) {
         const carried = this.log.horizonEpoch()?.published ?? [];
         const published = (PUBLISHING.behind?.(this, seq) ?? []).flatMap((at) => (at >= this.log.horizon ? [this.epochAt(at)] : carried.filter((one) => one.seq === at)));
         return { ...this.epochAt(seq), ...(published.length > 0 && { published }) };