@graview/core 0.1.62 → 0.1.64

package/dist/store.js

@@ -4,6 +4,7 @@ import { Graph, GraphError, MissingRecordError } from "./graph/graph.js";
 import { resolveModules } from "./modules.js";
 import { diffSnapshots, diffTouched, EMPTY_DIFF, isEmptyDiff } from "./graph/diff.js";
 import { normalize, writesOf } from "./graph/primitives.js";
+import { keepLinked, keepsLinked } from "./keep-linked.js";
 import { bareOp, inverseOf } from "./ops/inverse.js";
 import { LabelIndex, refusalFor } from "./labels.js";
 import { nodeRefArgs } from "./mutations/node-ref.js";
@@ -19,11 +20,12 @@ 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 { advisoryVoterOf, signedOutSeat, SIGN_IN_TO_VOTE, 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";
-import { actingAs, grantsTo, isSystem, permits, permittedMutations, subjectKinds } from "./permissions/policy.js";
+import { actingAs, grantsTo, isSystem, permits, permittedMutations, proposes, subjectKinds } from "./permissions/policy.js";
+import { MOST_PROPOSED, PROPOSE_CHANGES, proposeChangesMutation } from "./mutations/propose-changes.js";
 import { namesUnseen, redact } from "./ops/withheld.js";
 import { writersBehind } from "./ops/writers.js";
 import { nounOf } from "./schema/define-node.js";
@@ -187,6 +189,8 @@ export class Store {
     typer;
     /** "Vote on a suggestion" (Roadmap f-suggestion-votes), when the app declared no act by that name. */
     voter;
+    /** "Propose changes" (Roadmap f-proposals-for-review), when the app declared no act by that name. */
+    proposer;
     invariants;
     invariantOptions;
     policy;
@@ -194,6 +198,8 @@ export class Store {
     publishing;
     /** What the declaration says of suggestions as a whole (`StoreOptions.tidying`). */
     tidying;
+    /** What the host says of votes from a shared or signed-out seat (`StoreOptions.votes`). */
+    votes;
     /**
      * The intelligence the app declared, so a surface can read the DOORS.
      *
@@ -230,6 +236,8 @@ export class Store {
     rehearsing = false;
     /** True of a rehearsal for a suggestion: the actor is held to what a person said, not to the declaration's `tidying`, since a person decides it. */
     suggesting = false;
+    /** True of a rehearsal for a proposal (Roadmap f-proposals-for-review): an act its author may propose is let through, as it will be for whoever accepts it. */
+    proposing = false;
     /**
      * The day a host last ticked this store to (FR-176), and the day the clock
      * read when it did: what its rules are judged on, where nothing pins one,
@@ -257,6 +265,7 @@ export class Store {
         this.policy = options.policy;
         this.publishing = options.publishing;
         this.tidying = options.tidying;
+        this.votes = options.votes;
         this.by = options.principal ?? HUMAN;
         this.intelligence = options.intelligence ?? [];
         for (const provider of options.intelligence ?? []) {
@@ -299,6 +308,11 @@ export class Store {
             this.voter = voteSuggestionMutation();
             this.mutations.set(VOTE_SUGGESTION, this.voter);
         }
+        // "Propose changes" (Roadmap f-proposals-for-review): answered by every store, offered by no list.
+        if (!options.past && !this.mutations.has(PROPOSE_CHANGES)) {
+            this.proposer = proposeChangesMutation();
+            this.mutations.set(PROPOSE_CHANGES, this.proposer);
+        }
         const horizon = given("horizon", options.horizon);
         const validate = { validate: this.validate };
         if (options.log) {
@@ -507,7 +521,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 && mutation !== this.voter && !this.mutationDisabled(mutation));
+        return [...this.mutations.values(), ...(this.publisher ? [this.publisher] : [])].filter((mutation) => mutation !== this.keeper && mutation !== this.typer && mutation !== this.voter && mutation !== this.proposer && !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) {
@@ -560,6 +574,23 @@ export class Store {
      * action withheld by permission is stated rather than hidden, and stating
      * it needs the same answer the enforcement uses. One source, two readings.
      */
+    /**
+     * Whether a change to a derived record may go back to its source
+     * (Roadmap f-keep-linked): when the store judges a policy, only when its
+     * author may make the source's own edit with that value.
+     */
+    writesBack(principal) {
+        if (!this.policy)
+            return undefined;
+        return (source, field, value) => {
+            try {
+                return this.permits({ name: `edit-${source.kind}`, args: { id: source.id, [field]: value } }, principal).ok;
+            }
+            catch {
+                return false;
+            }
+        };
+    }
     permits(call, principal = HUMAN) {
         call = this.spelledCall(call);
         /*
@@ -578,9 +609,20 @@ 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)
+        /*
+         * 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.
+         * But not a seat that is nobody in particular (Roadmap f-votes-shared-seat): every signed-out stranger served as one `anonymous`
+         * cast one shared vote that any of them could flip. Refused, unless the host keeps such votes as advisory and said whose this is.
+         */
+        if (mutation && mutation === this.voter) {
+            if (signedOutSeat(principal) && (this.votes?.advisory !== "visitors" || advisoryVoterOf(principal) === undefined)) {
+                return { ok: false, refusal: { mutation: call.name, wouldNeed: [], message: SIGN_IN_TO_VOTE } };
+            }
             return { ok: true };
+        }
+        // A proposal is its author's to make where each call it holds is one they may run or may propose (Roadmap f-proposals-for-review).
+        if (mutation && mutation === this.proposer)
+            return this.permitsProposal(call, principal);
         /*
          * 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
@@ -635,6 +677,82 @@ 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);
     }
+    /**
+     * WHETHER THIS PRINCIPAL MAY PROPOSE THIS CALL AND MAY NOT RUN IT (Roadmap
+     * f-proposals-for-review): the policy refuses them the act and a grant's
+     * `propose` names it, on the kind the call is on. What turns an act's
+     * form's button into "Propose", and what a proposal's rehearsal lets
+     * through.
+     */
+    mayPropose(call, principal = HUMAN) {
+        if (!this.policy || this.past || signedOutSeat(principal))
+            return false;
+        call = this.spelledCall(call);
+        const mutation = this.mutations.get(call.name);
+        if (!mutation || mutation === this.proposer || mutation === this.voter || this.refusesAgent(call, principal) || this.namesTurnedOff(call, principal))
+            return false;
+        return !this.permits(call, principal).ok && proposes(this.policy, principal, call.name, this.subjectKindOf(call, principal));
+    }
+    /**
+     * A PROPOSAL'S OP (Roadmap f-proposals-for-review): the calls a "Propose
+     * changes" call holds, rehearsed as its author with the grant to propose
+     * standing in for the grant to run, kept as `suggest` keeps a suggestion
+     * — no primitives, each call's sentence, the records they name — with
+     * the author as its maker and a lineage naming them (`proposedBy`), its
+     * basis the proposal in their own words, else "Proposed by Ada"; or
+     * undefined when the calls would change nothing. Made here, so a store
+     * answers a proposal over the wire whatever else it loaded.
+     */
+    proposal(call, batch, author, via) {
+        const { calls, intent } = call.args;
+        if (calls.length === 0 || calls.length > MOST_PROPOSED || calls.some((one) => !one.args || typeof one.args !== "object" || Array.isArray(one.args)))
+            throw new GraphError(`A proposal holds 1 to ${MOST_PROPOSED} changes, each an act's name and its arguments.`);
+        const by = actingAs(author).id ?? author.session;
+        if (by === undefined)
+            throw new GraphError("A proposal is somebody's: sign in to propose a change.");
+        const lineage = lineageOf({ basis: (intent ?? `Proposed by ${author.name ?? by}`).slice(0, 500), proposedBy: by.slice(0, 120) });
+        const rehearsal = this.rehearsal();
+        rehearsal.proposing = true;
+        const planned = rehearsal.applying(calls, { author, lineage, ...given("via", via) });
+        if (planned.ops.length === 0)
+            return undefined;
+        const described = [...new Set(planned.ops.flatMap((op) => op.described ?? []))];
+        const own = planned.ops.filter((one) => one.mutation !== null && one.author === author);
+        return {
+            id: this.nextId(),
+            seq: this.log.length,
+            batch,
+            author,
+            intent: planned.ops.map((one) => one.intent).join("; "),
+            ...given("batchIntent", intent),
+            mutation: null,
+            primitives: [],
+            reads: [],
+            writes: [],
+            ...(described.length > 0 ? { described } : {}),
+            at: this.now(),
+            ...given("via", via),
+            lineage,
+            suggests: calls,
+            ...given("suggestsSaid", calls.length > 1 && own.length === calls.length ? own.map((one) => one.intent) : undefined),
+        };
+    }
+    /** A "Propose changes" call, judged: every call it holds one this principal may run or may propose, from a seat that is somebody. */
+    permitsProposal(call, principal) {
+        const no = (message) => ({ ok: false, refusal: { mutation: call.name, wouldNeed: [], message } });
+        if (signedOutSeat(principal))
+            return no("Sign in to propose a change.");
+        const calls = Array.isArray(call.args["calls"]) ? call.args["calls"] : [];
+        for (const one of calls) {
+            if (typeof one?.name !== "string")
+                continue;
+            const verdict = this.permits(one, principal);
+            if (verdict.ok || this.mayPropose(one, principal))
+                continue;
+            return no(`Not permitted to propose this: ${verdict.refusal.message.replace(/^Not permitted: /, "")}`);
+        }
+        return { ok: true };
+    }
     /**
      * 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);
@@ -1123,7 +1241,15 @@ export class Store {
         call = this.spelledCall(call);
         const definition = this.mutation(call.name);
         const compiled = compileMutation(this.graph, definition, call.args, this.sighted(options.author));
-        return this.previewPrimitives(this.asSplices(compiled.primitives), {
+        const made = this.asSplices(compiled.primitives);
+        // And what would follow it (Roadmap f-keep-linked), worked out on a copy.
+        let following = [];
+        if (keepsLinked(this.schema)) {
+            const trial = Graph.from(this.schema, this.graph.snapshot());
+            trial.applyPrimitives(made);
+            following = keepLinked(this.schema, trial, made, { mayWriteBack: this.writesBack(options.author ?? this.by) });
+        }
+        return this.previewPrimitives([...made, ...following], {
             reads: compiled.reads,
             writes: compiled.writes,
             intent: compiled.intent,
@@ -1261,8 +1387,11 @@ export class Store {
          * was brought in for, and the narrower of the two wins.
          */
         const permitted = (call, as = author) => {
-            const verdict = this.policy || (this.publisher && call.name === PUBLISH) ? this.permits(call, as) : undefined;
-            if (verdict && !verdict.ok)
+            // A vote is judged with no policy too: a shared seat's vote is refused whether or not the app says who may do what (Roadmap f-votes-shared-seat).
+            const voting = this.voter !== undefined && this.mutations.get(call.name) === this.voter;
+            const verdict = this.policy || (this.publisher && call.name === PUBLISH) || voting || this.mutations.get(call.name) === this.proposer ? this.permits(call, as) : undefined;
+            // Rehearsing a proposal, an act its author may propose stands as the reviewer's would (Roadmap f-proposals-for-review).
+            if (verdict && !verdict.ok && !(this.proposing && this.mayPropose(call, as)))
                 this.refuse(verdict.refusal, as.id);
         };
         const declared = (call, as = author) => {
@@ -1337,6 +1466,16 @@ export class Store {
                             queue.push({ sent: made, as: accept.author, lineage: lineageOf(accept.lineage), decided: true });
                     continue;
                 }
+                if (definition === this.proposer) {
+                    // A proposal (Roadmap f-proposals-for-review): a suggestion with its author as its maker, and nothing of the graph until it is accepted.
+                    const op = this.proposal(call, batch, as, options.via);
+                    if (!op)
+                        continue;
+                    this.log.append(op);
+                    ops.push(op);
+                    intents.push(op.intent);
+                    continue;
+                }
                 const missing = this.missingFor(call, as);
                 if (missing)
                     throw missing;
@@ -1371,6 +1510,15 @@ export class Store {
                 if (compiled.primitives.length === 0)
                     continue;
                 minted[at] = compiled.firstMinted;
+                /*
+                 * WHAT FOLLOWS IT (Roadmap f-keep-linked): the records that derive
+                 * from what this changed take their values from it, and a change
+                 * to one of those goes back to its source — in this op, so one undo
+                 * takes both back. Applied to the graph as they are worked out.
+                 */
+                const made = this.asSplices(compiled.primitives, options.base).map(normalize);
+                this.graph.applyPrimitives(made);
+                const following = keepsLinked(this.schema) ? keepLinked(this.schema, this.graph, made, { mayWriteBack: this.writesBack(as) }).map(normalize) : [];
                 madeIds[at] = compiled.primitives.find((primitive) => primitive.op === "add-node")?.node.id;
                 const op = {
                     id: this.nextId(),
@@ -1392,9 +1540,9 @@ export class Store {
                      * instruction is lost the moment the op is written to JSON and the
                      * inverse quietly does nothing. See `normalize` in primitives.ts.
                      */
-                    primitives: this.asSplices(compiled.primitives, options.base).map(normalize),
+                    primitives: [...made, ...following],
                     reads: compiled.reads,
-                    writes: compiled.writes,
+                    writes: following.length > 0 ? [...new Set([...compiled.writes, ...following.flatMap(writesOf)])] : 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 } : {}),
                     ...given("mergedInto", compiled.mergedInto),
@@ -1402,7 +1550,6 @@ export class Store {
                     ...given("via", options.via),
                     ...given("lineage", lined),
                 };
-                this.graph.applyPrimitives(op.primitives);
                 this.log.append(op);
                 ops.push(op);
                 allPrimitives.push(...op.primitives);
@@ -1549,6 +1696,8 @@ export class Store {
                 ...given("undoes", made.undoes),
                 ...given("via", made.via),
                 ...given("lineage", lineageOf(made.lineage)),
+                ...given("described", made.described),
+                ...given("sentOut", made.sentOut),
             };
             if (taken.has(op.id))
                 throw new GraphError(`Op "${op.id}" (${op.intent}) is already in the log`, "A host-made op needs an id of its own; leave `id` out and the store mints one.");
@@ -1592,7 +1741,18 @@ export class Store {
         const rollback = this.graph.snapshot();
         const intent = options.intent ?? "Apply a change";
         const lineage = lineageOf(options.lineage);
-        const recorded = this.asSplices(primitives, options.base).map(normalize);
+        const handed = this.asSplices(primitives, options.base).map(normalize);
+        // What follows it (Roadmap f-keep-linked), worked out on the graph as it lands: the host's change keeps derived records in step too.
+        this.graph.applyPrimitives(handed);
+        let recorded = handed;
+        try {
+            if (keepsLinked(this.schema))
+                recorded = [...handed, ...keepLinked(this.schema, this.graph, handed, { mayWriteBack: this.writesBack(author) }).map(normalize)];
+        }
+        catch (error) {
+            this.putBack(rollback, this.log.length);
+            throw error;
+        }
         const ops = [];
         if (recorded.length > 0) {
             const op = {
@@ -1609,7 +1769,6 @@ export class Store {
                 ...given("via", options.via),
                 ...given("lineage", lineage),
             };
-            this.graph.applyPrimitives(op.primitives);
             this.log.append(op);
             ops.push(op);
             tellTheWatchOfAnAuthor(author.id);
@@ -1789,6 +1948,10 @@ export class Store {
                 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) {
+                    // An advisory vote is its visitor's, not the shared seat's (Roadmap f-votes-shared-seat): another stranger on the same seat may not take it back.
+                    if (judged.vote.advisory && !isSystem(author) && advisoryVoterOf(author) !== judged.vote.voter && !(this.policy && this.grantsEveryAct(author))) {
+                        return { mutation: "undo", wouldNeed: [], message: `Not permitted to undo "${target.intent}": only whoever voted takes their vote back.` };
+                    }
                     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.` };
                     }