@cruba/crubal 0.1.0 → 0.3.0

package/dist/src/exchange.js

@@ -2,9 +2,13 @@
 // (7.10) and run in seven steps (7.4): trigger and permission, needs, map out, act, map back, rules,
 // record. Runs are idempotent (7.5). Offer and take share between owners, and only the overlap flows
 // (7.8). Data crossing a border is verified against the presenter's published key (8.5.1).
+import { arrive } from "./arrival.js";
 import { serialize } from "./canonical.js";
 import { evaluate, parseCondition } from "./conditions.js";
-import { fieldPath, land, receive, sha256, verifyChain } from "./store.js";
+import { MemoryRecords } from "./records.js";
+import { Engine } from "./rules.js";
+import { isSchedule, readSchedule, ticksDue } from "./schedule.js";
+import { fieldPath, land, receive, sha256, verifyChain, proposeSplit } from "./store.js";
 import { CrubalError, readTree } from "./tree.js";
 const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 export function readRoles(source) {
@@ -25,16 +29,25 @@ export function readRoles(source) {
     }
     return out;
 }
-/** What a caller is, for `who` (7.6): its values, the classes it wears, and its roles' grants. */
-function callerStates(caller, roles) {
+/**
+ * What a caller is, for `who` (7.6): the classes it wears, its roles' grants, and the menu items it holds
+ * on the record by its edges (14.6) when the run has access to consult. A caller with no record of its own
+ * here (a hosted person, 14.8) is still what its edges make it.
+ */
+function callerStates(caller, roles, held, asked = []) {
     return (path) => {
         const s = new Set();
-        if (path !== "caller" || !caller)
+        if (path !== "caller")
+            return s;
+        if (held)
+            for (const q of asked)
+                if (held(q.slice(0, q.indexOf(" ")), q.slice(q.indexOf(" ") + 1)))
+                    s.add(`may:${q}`);
+        if (!caller)
             return s;
         for (const w of caller.wears ?? [])
             s.add(`wears:${w}`);
-        const held = caller.values.roles;
-        const names = (Array.isArray(held) ? held : held ? [held] : []).map((r) => (isObj(r) && "$link" in r ? String(r.$link) : String(r)));
+        const names = (Array.isArray(caller.values.roles) ? caller.values.roles : caller.values.roles ? [caller.values.roles] : []).map((r) => (isObj(r) && "$link" in r ? String(r.$link) : String(r)));
         for (const r of roles.filter((x) => names.includes(x.name))) {
             for (const [verb, targets] of Object.entries(r.may))
                 for (const t of targets)
@@ -45,29 +58,49 @@ function callerStates(caller, roles) {
 }
 // ─── Publish checks (7.10) ───────────────────────────────────────────────────
 const PARTS = {
-    send: ["needs", "gives", "writes", "reads", "when", "who", "auth", "scope", "credential", "retry", "undo", "for", "label", "describe", "version"],
-    receive: ["needs", "gives", "reads", "when", "who", "origin", "lands", "evidence", "absorb", "ignore", "keep-raw", "prefix", "auth", "scope", "credential", "retry", "undo", "for", "label", "describe", "version"],
-    store: ["needs", "stores", "when", "who", "for", "label", "describe", "version"],
-    form: ["needs", "gives", "writes", "reads", "when", "who", "origin", "lands", "for", "label", "describe", "version"],
-    offer: ["needs", "gives", "to", "mode", "terms", "for", "when", "who", "label", "describe", "version"],
-    take: ["needs", "from", "reads", "mode", "lands", "origin", "absorb", "ignore", "keep-raw", "prefix", "when", "who", "for", "label", "describe", "version"],
+    send: ["needs", "gives", "writes", "reads", "stream", "to", "when", "missed", "who", "audience", "auth", "scope", "credential", "retry", "undo", "for", "label", "describe", "version"],
+    receive: ["needs", "gives", "reads", "when", "missed", "who", "audience", "origin", "lands", "evidence", "absorb", "ignore", "keep-raw", "prefix", "ref", "relation", "auth", "scope", "credential", "retry", "undo", "for", "label", "describe", "version"],
+    store: ["needs", "stores", "origin", "when", "who", "audience", "for", "label", "describe", "version"],
+    form: ["needs", "gives", "writes", "reads", "when", "who", "audience", "origin", "lands", "ref", "relation", "for", "label", "describe", "version"],
+    offer: ["needs", "gives", "to", "mode", "terms", "for", "when", "who", "audience", "label", "describe", "version"],
+    take: ["needs", "from", "offer", "reads", "mode", "lands", "origin", "absorb", "ignore", "keep-raw", "prefix", "ref", "when", "who", "audience", "for", "label", "describe", "version"],
 };
+const AUDIENCES = ["public", "member", "staff", "owner"];
+/**
+ * The lowest audience that may run a contract (7.2): what it says; else public for one that grants the
+ * consumer's edge (a sign-up, a first order: how one becomes a member, 14.4), member for any other form,
+ * public otherwise.
+ */
+const audienceOf = (c) => c.parts.audience ?? (c.kind === "form" && !c.parts.relation ? "member" : "public");
 function ourKey(address) {
     return address.replace(/^\w+::/, "").split(/[.[]/)[0];
 }
-/** Check contracts against a dictionary (7.10). Throws the first problem. */
-export function checkContracts(contracts, dict, ownPrefix = "") {
+/** Check contracts against a dictionary (7.10). Throws the first problem. `views` lets stream contracts be checked. */
+export function checkContracts(contracts, dict, ownPrefix = "", views) {
     const names = new Set(contracts.map((c) => c.name));
     for (const c of contracts) {
         const allowed = PARTS[c.kind];
         if (!allowed)
             throw new CrubalError(`unknown contract kind ${c.kind}`, c.line);
+        if (c.parts.audience && !AUDIENCES.includes(c.parts.audience))
+            throw new CrubalError(`${c.name}: audience is public, member, staff or owner, not ${c.parts.audience}`, c.partLines.audience ?? c.line);
         for (const [part, line] of Object.entries(c.partLines)) {
             if (part === "kind" || part.includes(":"))
                 continue;
             if (!allowed.includes(part))
                 throw new CrubalError(`a ${c.kind} contract has no part ${part}`, line);
         }
+        // A stream contract (12.6.2) carries projection entries: nothing is mapped and nothing is needed.
+        if (c.stream.length) {
+            if (c.writes.length || c.needs.length)
+                throw new CrubalError(`${c.name} carries a stream, so it has no writes and no needs`, c.partLines.stream);
+            if (!c.parts.to)
+                throw new CrubalError(`${c.name} carries a stream, so it names who it goes to`, c.partLines.stream);
+            if (views)
+                for (const v of c.stream)
+                    if (!views.has(v))
+                        throw new CrubalError(`${c.name} streams ${v}, which isn't a view`, c.partLines.stream);
+        }
         for (const l of c.needs)
             if (!dict.facets.has(l.facet))
                 throw new CrubalError(`${l.facet} is not a defined facet`, l.line);
@@ -93,9 +126,23 @@ export function checkContracts(contracts, dict, ownPrefix = "") {
                 throw new CrubalError(of ? `${v} is an alias of ${of.value}; a value map must name the real value` : `${v} is not a value of ${key}`, s.valueLines[i] ?? s.line);
             });
         }
-        for (const cond of [c.who, c.when])
-            if (cond && cond !== "asked")
-                parseCondition(cond, c.line);
+        // `when` is a condition, `asked` (a caller starts it), `entry` (a stream contract runs as its views
+        // publish) or a schedule (7.11).
+        if (c.who)
+            parseCondition(c.who, c.line);
+        if (c.when && c.when !== "asked" && c.when !== "entry") {
+            if (isSchedule(c.when))
+                readSchedule(c.when, c.partLines.when);
+            else
+                parseCondition(c.when, c.line);
+        }
+        if (c.when === "entry" && !c.stream.length)
+            throw new CrubalError(`${c.name} runs on entry but carries no stream`, c.partLines.when);
+        const missed = c.parts.missed;
+        if (missed && !["once", "all", "skip"].includes(missed))
+            throw new CrubalError(`${c.name}: missed is once, all or skip`, c.partLines.missed);
+        if (missed && !isSchedule(c.when))
+            throw new CrubalError(`${c.name}: missed belongs to a scheduled contract`, c.partLines.missed);
         if (c.undo && !names.has(c.undo))
             throw new CrubalError(`${c.name}'s undo names ${c.undo}, which isn't a contract here`, c.partLines.undo);
         const cred = c.parts.credential;
@@ -137,16 +184,214 @@ export class Exchange {
     dict;
     contracts;
     roles;
-    records = new Map();
+    /** The records, shared with the Access that decides over them (chapter 14). */
+    records = new MemoryRecords();
+    bindings = new Map();
+    /** Set to make the border consult access: `run` needs the caller's `run` item, gated access suggests. */
+    access;
+    /** The owner whose records these are, when the caller knows it: a store's border names it, so no run looks at a record to learn it. */
+    owner;
+    /**
+     * How an arrival's new record is named (9.2a). A persistent store sets this to mint the next id of the
+     * owner (`P-2` after `P-1`), since an Exchange is built per run and its own counter would start again.
+     * Without it the memory border's `<L>-NEW<n>` stands.
+     */
+    mint;
+    /** Set to make every run a transaction (8.5): the border works on the journal's draft and commits each run. */
+    journal;
+    /** Set to let stream contracts (12.6.2) carry the views' projection streams. */
+    views;
+    /** Per stream contract, the cursor each view's index has acknowledged, with the version it was for. */
+    cursors = new Map();
+    /** The rules a run's step 6 applies (7.4): the package's, plus the facet shortcuts the engine adds. */
+    engine;
+    /** Idempotency keys acted on (7.5); a store that outlives the instance seeds and keeps them. */
     sent = new Set();
+    /** Runs so far, which numbers the next run's log; a store continues the count across instances. */
     runs = 0;
-    constructor(dict, contracts, roles = []) {
+    /** Records minted by arrivals (9.2a), likewise. */
+    minted = 0;
+    /** The versions a run uses (7.4 step 7, 8.5): the package's, set by a store; the contract's is added per run. */
+    versions = {};
+    /** The review queue the border writes to (a dead run, an answer naming no run); the journal's draft list. */
+    review = [];
+    /** Observations this instance made (9.7); a store keeps every one in its state. */
+    observations = [];
+    observed = 0;
+    /** The package's thresholds (11.1): instances to propose a version split, witnesses to confirm. */
+    thresholds = {};
+    /** Review items already open in the store, for a border that loads them apart from the draft's list. */
+    knownReview = [];
+    /** Mapped-out payloads kept beside the log, by run (docs/design/runs.md): a store keeps them in outtake. */
+    outtake = new Map();
+    /** Runs the store knows beyond this instance's entries (a border over a store seeds them): run → contract and record. */
+    runsKnown = new Map();
+    /** Runs started and not yet acted or failed, by run: what a restarted host asks the adapter about. */
+    started = new Map();
+    constructor(dict, contracts, roles = [], rules = []) {
         this.dict = dict;
         this.contracts = new Map(contracts.map((c) => [c.name, c]));
         this.roles = roles;
+        this.engine = new Engine(dict, rules, () => this.records);
+    }
+    /**
+     * Step 6 of a run (7.4): what came in runs through the rules (chapter 6). A `must` the write breaks
+     * refuses it and nothing changes; a hold takes the value out of the current values; a fill or derivation
+     * lands with `origin: derived` and the rule as its `via`. Returns the record to keep, or the refusal.
+     */
+    applyRules(landed, touched) {
+        const results = this.engine.write({ ...landed, values: touched });
+        const refused = results.find((r) => r.result === "refused");
+        if (refused)
+            return { refused };
+        const after = this.engine.get(landed.id);
+        if (!after)
+            return { record: landed, summary: {} };
+        const values = { ...landed.values };
+        const sources = { ...(landed.sources ?? {}) };
+        const summary = {};
+        const held = { ...(landed.held ?? {}) };
+        for (const r of results) {
+            if ((r.result === "filled" || r.result === "derived") && r.address && r.value !== undefined && r.rule) {
+                values[r.address] = r.value;
+                sources[r.address] = { origin: "derived", via: r.rule };
+                const bag = (summary[r.result] ?? {});
+                bag[r.address] = r.value;
+                summary[r.result] = bag;
+            }
+            if (r.result === "held" && r.address && r.rule) {
+                const v = values[r.address];
+                if (v !== undefined) {
+                    const src = sources[r.address];
+                    held[r.address] = { value: v, rule: r.rule, ...(src ? { source: src } : {}) };
+                    delete values[r.address];
+                    delete sources[r.address];
+                }
+                summary.held = [...(summary.held ?? []), r.address];
+            }
+            if (r.result === "released" && r.address && held[r.address]) {
+                // The held value comes back as it was (6.7).
+                const h = held[r.address];
+                values[r.address] = h.value;
+                if (isObj(h.source))
+                    sources[r.address] = h.source;
+                delete held[r.address];
+                summary.released = [...(summary.released ?? []), r.address];
+            }
+            if (r.result === "flagged" && r.rule)
+                summary.flagged = [...(summary.flagged ?? []), r.rule];
+        }
+        // The held bag is rebuilt from what stayed held: a released key leaves it.
+        const { held: _was, ...base } = landed;
+        const record = { ...base, values, sources, ...(Object.keys(held).length ? { held } : {}) };
+        this.engine.put(record);
+        // 6b. What the ancestors derive from below is recomputed now (6.4), nearest first, each landing before
+        // the next reads it; the record itself is in the set first, so a rollup over it sees this write.
+        if (this.engine.readsLowerLevels) {
+            this.records.set(record.id, record);
+            const recomputed = this.reproduceAncestors(record.id);
+            if (recomputed.length)
+                summary.recomputed = recomputed;
+        }
+        return { record, summary };
+    }
+    /** Run the ancestors' productions again after a write below them; the ids whose values changed. */
+    reproduceAncestors(id) {
+        const changed = [];
+        for (const upId of this.engine.ancestorsOf(id)) {
+            const up = this.records.get(upId);
+            if (!up)
+                break;
+            this.engine.put(up);
+            const derived = this.engine.reproduce(upId).filter((r) => (r.result === "derived" || r.result === "filled") && r.address && r.value !== undefined && r.rule);
+            if (!derived.length)
+                continue;
+            const values = { ...up.values };
+            const sources = { ...(up.sources ?? {}) };
+            let moved = false;
+            for (const r of derived) {
+                const address = r.address;
+                if (serialize(values[address] ?? "∅") === serialize(r.value))
+                    continue;
+                values[address] = r.value;
+                sources[address] = { origin: "derived", via: r.rule };
+                moved = true;
+            }
+            if (!moved)
+                continue;
+            const next = { ...up, values, sources };
+            this.records.set(upId, next);
+            this.engine.put(next);
+            changed.push(upId);
+        }
+        return changed;
+    }
+    /** Work on a journal's draft, so every run the border makes is one logged entry (8.5). */
+    useJournal(journal) {
+        this.journal = journal;
+        for (const [id, r] of this.records)
+            journal.draft.records.set(id, r);
+        for (const [k, v] of this.bindings)
+            journal.draft.bindings.set(k, v);
+        this.records = journal.draft.records;
+        this.bindings = journal.draft.bindings;
+        if (this.access) {
+            for (const [k, e] of this.access.edges)
+                journal.draft.edges.set(k, e);
+            this.access.edges = journal.draft.edges;
+        }
+        this.review = journal.draft.review;
+    }
+    /** Log a run's transaction: what it changed on the draft, the run's own state, and any observations (8.5). */
+    commit(by, log, run, more = []) {
+        this.journal?.commit(by, () => { }, `2026-01-01T00:00:${String(this.runs).padStart(2, "0")}Z`, [{ run: log, ...run }, ...more]);
+    }
+    /** Step 1 of a run (7.4): the menu is the permission (14.6); `who` only narrows. */
+    permitted(c, recordId, callerId, arrival = false) {
+        // A run needs `run` on the record (14.6); an arrival has no record yet, so it needs `run` anywhere by an
+        // admin or control edge, or to be an admitted member taking part (14.4), on the parent when it has one.
+        const may = (verb, target) => {
+            if (!this.access || !callerId)
+                return true;
+            if (!arrival || recordId)
+                return this.access.may(callerId, verb, target, recordId);
+            return this.access.mayAnywhere(callerId, verb, target) || (verb === "run" && (audienceOf(c) === "public" || this.access.audienceOf(callerId) !== "public"));
+        };
+        if (this.access && callerId && !may("run", c.name))
+            return "permission";
+        // The contract's audience (7.2, 14.4): consume opens only what the package opens to consumers.
+        if (this.access && callerId && AUDIENCES.indexOf(this.access.audienceOf(callerId)) < AUDIENCES.indexOf(audienceOf(c)))
+            return "permission";
+        if (c.who) {
+            const caller = callerId ? this.records.get(callerId) : undefined;
+            // `caller may edit Deployment`: held by the caller's edges and the menu on this record (14.6).
+            const asked = [...c.who.matchAll(/\bcaller may (\w+) (\S+)/g)].map((m) => `${m[1]} ${m[2]}`);
+            const held = this.access && callerId ? (verb, target) => may(verb, target) : undefined;
+            const ok = evaluate(parseCondition(c.who), caller ? { ...caller.values } : {}, callerStates(caller, this.roles, held, asked));
+            if (ok !== true)
+                return "who";
+        }
+        return null;
+    }
+    /** The gated edge a caller's access comes through, if every granting edge is gated (14.7). */
+    gate(recordId, callerId) {
+        return this.access && callerId ? this.access.gated(callerId, recordId) : null;
+    }
+    /**
+     * A contract that creates a record for a caller grants their edge on it (14.4): `mode: consume`, the
+     * contract's `relation`, under the owner's grant.
+     */
+    grantConsumer(c, recordId, callerId) {
+        const relation = c.parts.relation;
+        if (!this.access || !relation)
+            return null;
+        const edge = { edge: `E-${c.name}-${recordId}`, who: callerId, relation, mode: "consume", on: recordId, grants: [], by: "owner", line: c.line };
+        this.access.edges.set(edge.edge, edge);
+        return edge;
     }
     put(r) {
         this.records.set(r.id, r);
+        this.engine.put(r);
     }
     get(id) {
         return this.records.get(id);
@@ -168,8 +413,24 @@ export class Exchange {
         this.runs += 1;
         return `L-R${this.runs}`;
     }
-    /** Steps 1–4 of a send (or form) contract: permission, needs, map out, act once. */
+    /**
+     * A send (or form) contract's run with no act between (the memory border, docs/design/runs.md): prepare,
+     * then acted, in two entries. A host puts its adapter between `prepare` and `acted` or `failed`.
+     */
     run(name, recordId, callerId) {
+        const p = this.prepare(name, recordId, callerId);
+        if (p.started !== true)
+            return p;
+        this.acted(String(p.log));
+        const { started: _s, ...rest } = p;
+        return { ...rest, acted: true };
+    }
+    /**
+     * Steps 1–3 of a send (7.4): permission, needs, map out; then the run is `started`, its idempotency key
+     * and the payload's hash logged, the payload itself kept beside the log. A key already started or acted
+     * is never sent again (7.5).
+     */
+    prepare(name, recordId, callerId, cause) {
         const c = this.contracts.get(name);
         if (!c)
             throw new Error(`no contract ${name}`);
@@ -178,13 +439,10 @@ export class Exchange {
             throw new Error(`no record ${recordId}`);
         const head = { contract: name, record: recordId, ...(callerId ? { caller: callerId } : {}) };
         const log = this.nextLog();
-        // 1. Trigger and permission.
-        if (c.who) {
-            const caller = callerId ? this.records.get(callerId) : undefined;
-            const ok = evaluate(parseCondition(c.who), caller ? { ...caller.values } : {}, callerStates(caller, this.roles));
-            if (ok !== true)
-                return { ...head, stopped: "who" };
-        }
+        // 1. Permission and trigger.
+        const stopped = this.permitted(c, recordId, callerId);
+        if (stopped)
+            return { ...head, stopped };
         // 2. Needs: an unnamed class over the record.
         const missing = [];
         const unfit = [];
@@ -215,53 +473,428 @@ export class Exchange {
             const mapped = typeof v === "string" ? (m.values.find(([ours]) => ours === v)?.[1] ?? v) : v;
             put(payload, m.to, wire(mapped));
         }
-        // 4. Act, at most once per contract, record and payload.
+        // 4 begins: at most once per contract, record and payload; a started run is not started again.
         const key = `${name}|${recordId}|${sha256(serialize(payload))}`;
+        const open = [...this.started].find(([, s]) => s.key === key);
+        if (open)
+            return { ...head, started: false, reason: "a run with this payload is already started", run: open[0] };
         if (this.sent.has(key))
             return { ...head, acted: false, reason: "the same payload was already sent" };
         this.sent.add(key);
-        return { ...head, acted: true, payload, key, log };
+        this.outtake.set(log, payload);
+        this.started.set(log, { contract: name, record: recordId, key, attempts: 0, ...(cause ? { cause } : {}) });
+        const versions = { ...this.versions, ...(c.parts.version ? { contract: c.parts.version } : {}) };
+        this.commit({ contract: name, run: log }, log, { contract: name, record: recordId, key, state: "started", payload: `sha256:${sha256(serialize(payload))}`, ...(Object.keys(versions).length ? { versions } : {}), ...(cause ? { cause } : {}) });
+        return { ...head, started: true, payload, key, log, ...(cause ? { cause } : {}) };
+    }
+    /** The act succeeded: the run is `acted` (docs/design/runs.md). */
+    acted(run, at) {
+        const s = this.started.get(run);
+        if (!s)
+            throw new Error(`no started run ${run}`);
+        this.started.delete(run);
+        this.commit({ contract: s.contract, run }, run, { contract: s.contract, record: s.record, key: s.key, state: "acted", ...(at ? { at } : {}) });
+        return { contract: s.contract, record: s.record, run, acted: true };
+    }
+    /** How many attempts a contract allows (7.5 `retry: N every D`): one without it. */
+    attemptsAllowed(c) {
+        const m = (c.parts.retry ?? "").match(/^(\d+)\s+every\s+/);
+        return m ? 1 + Number(m[1]) : 1;
+    }
+    /**
+     * The act failed: a `failed` entry with the attempt; after the last attempt the contract allows, a
+     * review item `run:<contract>` opens, grouped by contract across records, and the run stays failed.
+     */
+    failed(run, reason) {
+        const s = this.started.get(run);
+        if (!s)
+            throw new Error(`no started run ${run}`);
+        const c = this.contracts.get(s.contract);
+        s.attempts += 1;
+        const allowed = c ? this.attemptsAllowed(c) : 1;
+        const dead = s.attempts >= allowed;
+        if (dead) {
+            this.started.delete(run);
+            this.review.push({ key: `run:${s.contract}`, run, record: s.record, reason, attempts: s.attempts });
+        }
+        this.commit({ contract: s.contract, run }, run, { contract: s.contract, record: s.record, key: s.key, state: "failed", reason, attempt: s.attempts });
+        return { contract: s.contract, record: s.record, run, failed: true, attempt: s.attempts, ...(dead ? { dead: true, review: `run:${s.contract}` } : { retry: allowed - s.attempts }) };
+    }
+    /**
+     * A decision on a dead run (runs.md): `retry` releases its key and starts a new run from the record as it
+     * now is; `drop` closes the item. Either is a review write.
+     */
+    decideRun(run, decision, callerId) {
+        const w = this.runOf(run);
+        if (!w)
+            throw new Error(`no run ${run}`);
+        const item = this.review.find((it) => it.run === run && it.key === `run:${w.contract}` && it.decision === undefined);
+        const key = [...this.sent].find((k) => k.startsWith(`${w.contract}|${w.record}|`));
+        if (decision === "retry" && key)
+            this.sent.delete(key);
+        this.review.push({ ...(item ?? { key: `run:${w.contract}`, run, record: w.record }), decision, ...(decision === "retry" && key ? { releases: key } : {}), ...(callerId ? { by: callerId } : {}) });
+        if (decision === "drop")
+            return { contract: w.contract, run, decision };
+        return { ...this.prepare(w.contract, w.record, callerId), decision, retried: run };
+    }
+    /** Run the contract that reverses a run (7.5 `undo`): an ordinary send naming its cause. */
+    /** The contract and record of a run this instance or its store knows. */
+    runOf(run) {
+        const known = this.runsKnown.get(run);
+        if (known)
+            return known;
+        for (const x of this.journal?.entries ?? []) {
+            const w = Array.isArray(x.writes) ? x.writes.find((y) => isObj(y) && y.run === run) : undefined;
+            if (w)
+                return { contract: String(w.contract), record: String(w.record ?? "") };
+        }
+        return undefined;
+    }
+    undo(run, callerId) {
+        const w = this.runOf(run);
+        const contract = w ? this.contracts.get(w.contract) : undefined;
+        if (!w || !contract)
+            throw new Error(`no run ${run}`);
+        if (!contract.undo)
+            return { contract: contract.name, run, stopped: "undo", reason: `${contract.name} names no undo` };
+        return this.prepare(contract.undo, w.record, callerId, run);
     }
     needsOf(c) {
         return c.needs;
     }
-    /** Steps 5–6 for a receive contract: map the answer back, compare with the record, and land it. */
-    receiveRun(name, recordId, body) {
+    /**
+     * Steps 5–6 for a receive contract: map the answer back, compare with the record, and land it. Under a
+     * gated edge (14.7) the values land as suggestions for the edge's reviewer, whatever the contract says.
+     */
+    receiveRun(name, recordId, body, callerId, forRun) {
         const c = this.contracts.get(name);
         const r = this.records.get(recordId);
         if (!c || !r)
             throw new Error(`no contract ${name} or record ${recordId}`);
-        const log = this.nextLog();
+        const head = { contract: name, record: recordId, ...(callerId ? { caller: callerId } : {}) };
+        // An answer that names a run the store doesn't know is never guessed onto a record (docs/design/runs.md).
+        if (forRun !== undefined) {
+            const known = this.runOf(forRun)?.contract === name;
+            if (!known) {
+                this.review.push({ key: `run:${name}`, run: forRun, record: recordId, reason: "an answer named a run the store doesn't know" });
+                const l = this.nextLog();
+                this.commit({ contract: name, run: l }, l, { contract: name, record: recordId, state: "closed", answerFor: forRun });
+                return { ...head, stopped: "run", reason: `no run ${forRun}`, log: l };
+            }
+        }
+        const stopped = this.permitted(c, recordId, callerId);
+        if (stopped)
+            return { ...head, stopped };
+        const log = forRun ?? this.nextLog();
         const intake = receive(c, body, recordId, this.dict, `I-${log.slice(2)}`);
         const outcomes = intake.outcomes.map((o) => {
             if (o.outcome !== "absorbed" || !o.to)
                 return o;
+            // A value a must rule won't have is a contradiction citing the rule (9.3): parked, never landed.
+            const broken = this.engine.probe({ ...r, values: { [o.to]: o.value } });
+            if (broken)
+                return { ...o, outcome: "contradiction", cites: { rule: broken.rule ?? "" } };
             const current = r.values[o.to];
             if (current === undefined || (isObj(current) && "$empty" in current))
                 return o;
-            return serialize(current) === serialize(o.value) ? o : { ...o, outcome: "conflict" };
+            if (serialize(current) === serialize(o.value))
+                return o;
+            // A state facet moves (4.2, 9.3): a later value of equal or higher trust is absorbed, not disputed.
+            // Equal trust is the common case here (a form of the same origin); the landing decides the rest.
+            if (this.dict.facets.get(o.to)?.transitions && (c.origin === "declared" || callerId))
+                return o;
+            return { ...o, outcome: "conflict" };
         });
         const source = { origin: c.origin, via: log };
-        if (c.lands === "suggestion")
+        const gate = this.gate(recordId, callerId);
+        let summary = {};
+        if (c.lands === "observation") {
+            // Evidence (9.7): each reading is an observation on this instance, supporting the record that stores
+            // the value; the first observation fills an empty value with origin observed.
+            const docs = [];
+            let filled;
+            for (const o of outcomes) {
+                if (!o.to || o.value === undefined || !["absorbed", "conflict", "new"].includes(o.outcome))
+                    continue;
+                const up = r.of ? this.records.get(r.of) : undefined;
+                const supports = up && r.values[o.to] === undefined && (up.values[o.to] !== undefined || !this.dict.vary.get(r.level)?.has(o.to)) ? up.id : r.id;
+                const doc = { obs: `O-${++this.observed}`, on: recordId, address: o.to, value: o.value, "evidence-type": c.parts.evidence ?? "reading", reading: intake.intake, supports };
+                docs.push(doc);
+                const target = filled ?? (supports === r.id ? r : up);
+                const cur = target.values[o.to];
+                if (cur === undefined || (isObj(cur) && "$empty" in cur)) {
+                    filled = { ...target, values: { ...target.values, [o.to]: o.value }, sources: { ...(target.sources ?? {}), [o.to]: { origin: "observed", via: log } } };
+                }
+            }
+            this.observed = Math.max(this.observed, ...this.observations.map((o) => Number(String(o.obs).replace(/^O-/, "")) || 0));
+            for (const d of docs)
+                d.obs = `O-${++this.observed}`;
+            this.observations.push(...docs);
+            if (filled)
+                this.put(filled);
+            // The version split proposed (9.7.3): at the threshold, a review item names the instances that agree.
+            const proposed = [];
+            const supported = [...new Set(docs.map((d) => String(d.supports)))].flatMap((id) => { const rec = this.records.get(id); return rec ? [rec] : []; });
+            for (const item of proposeSplit(supported, this.observations, this.thresholds.split ?? 3)) {
+                const same = (it) => it.key === item.key && it.address === item.address && serialize(it.value) === serialize(item.value) && it.decision === undefined;
+                if (!this.review.some(same) && !this.knownReview.some(same)) {
+                    this.review.push(item);
+                    proposed.push(item);
+                }
+            }
+            this.commit({ contract: name, run: log }, log, { contract: name, record: recordId, state: "closed" }, docs.map((d) => ({ observation: d })));
+            return { ...head, outcomes: outcomes, log, landed: "observation", observations: docs, ...(filled ? { filled: filled.id } : {}), ...(proposed.length ? { proposed } : {}) };
+        }
+        if (c.lands === "suggestion" || gate)
             this.put(suggest(r, outcomes, source));
-        else
-            this.put(land(r, { outcomes, contract: name }, source, this.dict.trust, this.dict.facetTrust));
-        return { contract: name, record: recordId, outcomes: outcomes, sources: { origin: c.origin }, log };
+        else {
+            // A form run by a caller is a person's write (11.3): it ranks as `person`, ahead of what a contract or an earlier declaration left.
+            const landed = land(r, { outcomes, contract: name, ...(c.kind === "form" && callerId ? { person: true } : {}) }, source, this.dict.trust, this.dict.facetTrust, new Set([...this.dict.facets.values()].filter((f) => f.transitions).map((f) => f.key)));
+            // 6. Rules, over what this run changed.
+            const touched = {};
+            for (const [k, v] of Object.entries(landed.values))
+                if (serialize(r.values[k] ?? "∅") !== serialize(v))
+                    touched[k] = v;
+            const ruled = this.applyRules(landed, touched);
+            if ("refused" in ruled)
+                return { ...head, stopped: "rule", rule: ruled.refused.rule ?? "", address: ruled.refused.address ?? "", log };
+            this.put(ruled.record);
+            summary = ruled.summary;
+        }
+        // A form run by a caller is that person's entry (8.5), as an arrival's is; the run write still names the contract.
+        this.commit(callerId && c.kind === "form" ? { person: callerId } : { contract: name, run: log }, log, { contract: name, record: recordId, state: "closed" });
+        return { ...head, outcomes: outcomes, sources: { origin: c.origin }, log, landed: gate || c.lands === "suggestion" ? "suggestion" : "value", ...(gate ? { gated: gate.edge, reviewer: gate.reviewer ?? gate.by } : {}), ...(Object.keys(summary).length ? { rules: summary } : {}) };
+    }
+    /**
+     * An arrival through a contract (9.2a): the payload finds or makes its record; a new record made for a
+     * caller gets their consumer edge (14.4).
+     */
+    arriveRun(name, body, level, callerId, of, within) {
+        const c = this.contracts.get(name);
+        if (!c)
+            throw new Error(`no contract ${name}`);
+        const log = this.nextLog();
+        const domain = this.owner ?? this.access?.owner ?? this.journal?.owner ?? this.records.all()[0]?.owner ?? "";
+        // A person owns what the package lets a person own (14.1): the record is theirs, written as `domain:id`.
+        const kind = this.dict.levels.get(level) ?? level;
+        // Permitted on the record the new one sits under or within (14.2), else anywhere (7.4 step 1).
+        const refused = this.permitted(c, of ?? within ?? "", callerId, true);
+        if (refused)
+            return { contract: name, ...(callerId ? { caller: callerId } : {}), stopped: refused, log };
+        const person = callerId && !callerId.includes(":") && (this.access?.perms.ownership.get("person") ?? []).includes(kind);
+        const owner = person ? `${domain}:${callerId}` : domain;
+        // A refusal by the rules puts everything back: the arrival never happened.
+        const prevRecords = new Map(this.records);
+        const prevBindings = new Map(this.bindings);
+        const { arrival, record } = arrive(c, body, level, this, this.dict, { mint: () => (this.mint ? this.mint(level) : `${level.charAt(0).toUpperCase()}-NEW${++this.minted}`), owner, ...(of ? { of } : {}), ...(within ? { within } : {}), intakeId: `I-${log.slice(2)}` });
+        const out = { contract: name, ...(callerId ? { caller: callerId } : {}), arrival: arrival, log };
+        if (record) {
+            // 6. Rules, over what landed (everything, for a new record).
+            const was = prevRecords.get(record.id);
+            const touched = {};
+            for (const [k, v] of Object.entries(record.values))
+                if (!was || serialize(was.values[k] ?? "∅") !== serialize(v))
+                    touched[k] = v;
+            const ruled = this.applyRules(record, touched);
+            if ("refused" in ruled) {
+                this.records.clear();
+                for (const [k, v] of prevRecords)
+                    this.records.set(k, v);
+                this.bindings.clear();
+                for (const [k, v] of prevBindings)
+                    this.bindings.set(k, v);
+                if (was)
+                    this.engine.put(was);
+                return { contract: name, ...(callerId ? { caller: callerId } : {}), stopped: "rule", rule: ruled.refused.rule ?? "", address: ruled.refused.address ?? "", log };
+            }
+            this.put(ruled.record);
+            if (Object.keys(ruled.summary).length)
+                out.rules = ruled.summary;
+        }
+        if (record && arrival.outcome === "new" && callerId) {
+            const edge = this.grantConsumer(c, record.id, callerId);
+            if (edge)
+                out.granted = { edge: edge.edge, relation: edge.relation, mode: edge.mode, on: edge.on };
+        }
+        this.commit(callerId && c.kind === "form" ? { person: callerId } : { contract: name, run: log }, log, { contract: name, ...(record ? { record: record.id } : {}), state: arrival.outcome === "held" ? "started" : "closed" });
+        return out;
+    }
+    /** The arrival type, re-exported for callers that read `arrival`. */
+    static arrivalOf(r) {
+        return r.arrival;
+    }
+    /**
+     * A stream contract's run (12.6.2): the entries of each view since the cursor, in order. Pushed (the
+     * stored cursor, acknowledged by the index) or pulled (the caller's cursor). A view above `public` goes
+     * only to a party holding `run` for the contract.
+     */
+    streamRun(name, callerId, cursor) {
+        const c = this.contracts.get(name);
+        if (!c)
+            throw new Error(`no contract ${name}`);
+        if (!c.stream.length)
+            throw new Error(`${name} carries no stream`);
+        if (!this.views)
+            throw new Error("no views to stream from");
+        const party = callerId ?? c.parts.to ?? "";
+        const head = { contract: name, caller: party };
+        for (const v of c.stream) {
+            const view = this.views.set.views.get(v);
+            if (view && view.show !== "public" && !this.access?.mayAnywhere(party, "run", name))
+                return { ...head, stopped: "permission", view: v };
+        }
+        const log = this.nextLog();
+        const stored = this.cursors.get(name) ?? {};
+        const entries = {};
+        const out = {};
+        const batches = [];
+        for (const v of c.stream) {
+            this.views.stream(v);
+            const version = this.views.versionOf(v);
+            const held = stored[v];
+            const since = cursor?.[v] ?? (held && held.version === version ? held.seq : 0);
+            const list = this.views.entriesSince(v, since);
+            entries[v] = list;
+            out[v] = list.at(-1)?.seq ?? since;
+            if (list.length)
+                batches.push(`${name}|${v}|${version}|${list[0]?.seq}-${list.at(-1)?.seq}`);
+        }
+        return { ...head, entries, cursor: out, ...(batches.length ? { key: batches.join(" ") } : {}), log };
+    }
+    lastTick = new Map();
+    /**
+     * A scheduled contract's tick (7.11): the host offers its clock as `now`; every tick due since the last
+     * one runs (or only the latest, or none, by `missed`), each run keyed by the contract and the tick so a
+     * restarted host never runs a tick twice. A send contract with `for` runs over every record it selects;
+     * a stream contract pushes; any other runs once with no record.
+     */
+    tick(name, now, callerId) {
+        const c = this.contracts.get(name);
+        if (!c)
+            throw new Error(`no contract ${name}`);
+        if (!isSchedule(c.when))
+            throw new Error(`${name} isn't scheduled`);
+        const sch = readSchedule(c.when);
+        // A schedule begins when its contract is published (7.11): here, at the first clock reading.
+        if (!this.lastTick.has(name)) {
+            this.lastTick.set(name, now);
+            return { contract: name, now, ticks: [], runs: [], began: now };
+        }
+        const due = ticksDue(sch, this.lastTick.get(name), now);
+        const missed = c.parts.missed ?? "once";
+        const run = missed === "all" ? due : missed === "once" ? due.slice(-1) : [];
+        const skipped = due.filter((t) => !run.includes(t));
+        const results = [];
+        for (const tick of run) {
+            const key = `${name}|${tick}`;
+            if (this.sent.has(key))
+                continue;
+            this.sent.add(key);
+            if (c.stream.length) {
+                const r = this.streamRun(name, callerId);
+                results.push({ tick, ...r });
+                continue;
+            }
+            const targets = c.parts.for ? this.records.forTarget(c.parts.for).map((r) => r.id) : [];
+            if (!targets.length) {
+                const log = this.nextLog();
+                this.commit({ contract: name, run: log }, log, { contract: name, tick, key, state: "acted" });
+                results.push({ tick, log, acted: true });
+                continue;
+            }
+            for (const id of targets)
+                results.push({ tick, ...this.run(name, id, callerId) });
+        }
+        if (due.length)
+            this.lastTick.set(name, due[due.length - 1]);
+        return { contract: name, now, ticks: run, ...(skipped.length ? { skipped } : {}), runs: results };
+    }
+    /** The index acknowledges what it holds: the store resumes from there (12.6.2). */
+    ack(name, cursor) {
+        const stored = this.cursors.get(name) ?? {};
+        for (const [v, seq] of Object.entries(cursor))
+            stored[v] = { version: this.views?.versionOf(v) ?? "", seq };
+        this.cursors.set(name, stored);
+        return { contract: name, acked: cursor };
+    }
+    /** The classes a record wears, those of the records above it included (5.5). */
+    wearsOf(r) {
+        const up = r.of ? this.records.get(r.of) : undefined;
+        return [...(up ? this.wearsOf(up) : []), ...(r.wears ?? [])];
     }
-    /** Offer and take (7.8): only what the offer gives and the take reads flows. */
-    take(takeName, offerName, recordId, presenter) {
+    /**
+     * An offer (7.8): the records the contract's `for` selects, with only the facets it gives, each value with
+     * its source; the mode and terms ride along. A value the owner took under `reshare: no` never flows on.
+     * Who may see it is the host's decision from `to`.
+     */
+    offer(name, owner, only) {
+        const c = this.contracts.get(name);
+        if (!c || c.kind !== "offer")
+            throw new Error(`no offer ${name}`);
+        const wears = c.parts.for;
+        // What the contract is `for` is asked for by target, never the whole catalog (brief 18, the scale rule).
+        const pool = only ? only.flatMap((id) => this.records.get(id) ?? []) : wears ? this.records.forTarget(wears) : this.records.all();
+        const records = [];
+        for (const r of pool) {
+            if (r.status?.state === "archived")
+                continue;
+            if (wears && !this.wearsOf(r).includes(wears))
+                continue;
+            const values = {};
+            const sources = {};
+            for (const key of c.gives) {
+                const v = r.values[key];
+                if (v === undefined || (isObj(v) && "$empty" in v))
+                    continue;
+                const s = r.sources?.[key] ?? r.sources?.["*"];
+                if (s?.reshare === false)
+                    continue;
+                values[key] = v;
+                if (s)
+                    sources[key] = { origin: s.origin, via: s.via, ...(s.owner ? { owner: s.owner } : {}) };
+            }
+            if (!Object.keys(values).length)
+                continue;
+            records.push({ id: r.id, kind: r.kind, level: r.level, owner: r.owner, values, sources, ...(r.of ? { of: r.of } : {}) });
+        }
+        return { contract: name, owner, to: c.to ?? "private", mode: c.mode ?? "gathered", terms: { ...c.terms }, gives: [...c.gives], records };
+    }
+    /**
+     * Offer and take (7.8): only what the offer gives and the take reads flows, by the offer's mode.
+     * `dump` copies once and never updates; `observed` stores a link and no value; `gathered` copies and
+     * takes the presenter's updates as intake, never over a value the consumer entered; `controlled` copies
+     * under the presenter's terms, which do override, expire and withdraw. The entry names the presenter's
+     * entry the values came from (8.5.1).
+     */
+    take(takeName, offer, recordId, presenter) {
         const t = this.contracts.get(takeName);
-        const o = this.contracts.get(offerName);
+        const o = typeof offer === "string" ? this.localOffer(offer) : offer;
         const r = this.records.get(recordId);
         if (!t || !o || !r)
             throw new Error("a take needs its take contract, the offer and the record");
         if (t.from && t.from !== presenter.owner)
             return { contract: takeName, record: recordId, stopped: "from" };
+        const mode = o.mode;
+        if (t.mode && t.mode !== mode)
+            return { contract: takeName, record: recordId, stopped: "mode", offered: mode };
         const log = this.nextLog();
         const values = { ...r.values };
         const sources = { ...(r.sources ?? {}) };
         const alternatives = { ...(r.alternatives ?? {}) };
         const flows = [];
+        let from;
+        const fromPresenter = (a) => sources[a]?.owner === presenter.owner;
+        if (mode === "observed") {
+            // A read-through is never stored (7.8): the record links to the presenter's, naming what it reads.
+            for (const m of t.reads)
+                if (o.gives.includes(m.from) && presenter.values[m.from] !== undefined)
+                    flows.push(m.from);
+            values["crubal:observes"] = { $link: `${presenter.owner}/${presenter.id}` };
+            sources["crubal:observes"] = { origin: "reported", via: log, owner: presenter.owner };
+            this.put({ ...r, values, sources });
+            this.commit({ take: takeName, from: presenter.owner }, log, { contract: takeName, record: recordId, state: "closed" });
+            return { contract: takeName, record: recordId, mode, observes: flows, log };
+        }
         for (const m of t.reads) {
             const theirs = m.from;
             if (!o.gives.includes(theirs))
@@ -269,22 +902,84 @@ export class Exchange {
             const v = presenter.values[theirs];
             if (v === undefined)
                 continue;
-            flows.push(theirs);
             const theirSource = presenter.sources?.[theirs] ?? presenter.sources?.["*"];
+            from ??= theirSource?.via ? `${presenter.owner}/${theirSource.via}` : presenter.owner;
             const src = { origin: theirSource?.origin ?? "reported", via: log, owner: presenter.owner };
+            if (mode === "controlled") {
+                if (o.terms.expires)
+                    src.until = o.terms.expires;
+                if (o.terms.reshare === "no")
+                    src.reshare = false;
+                if (o.terms.revocable === "yes")
+                    src.revocable = true;
+            }
             const current = values[m.to];
-            if (current === undefined || (isObj(current) && "$empty" in current)) {
+            const empty = current === undefined || (isObj(current) && "$empty" in current);
+            if (empty) {
+                values[m.to] = v;
+                sources[m.to] = src;
+                flows.push(theirs);
+            }
+            else if (serialize(current) === serialize(v)) {
+                if (mode !== "dump" && fromPresenter(m.to))
+                    sources[m.to] = { ...sources[m.to], ...src, via: sources[m.to]?.via ?? log };
+            }
+            else if (mode === "dump") {
+                // Copied once, never updated.
+            }
+            else if (mode === "controlled" || fromPresenter(m.to)) {
+                // The presenter's update: under controlled terms it wins; gathered, it replaces only its own earlier value.
                 values[m.to] = v;
                 sources[m.to] = src;
+                flows.push(theirs);
             }
-            else if (serialize(current) !== serialize(v)) {
-                // A presenter never overrides the consumer's value unless the consumer took controlled terms.
+            else {
+                // A presenter never overrides a value a person entered on the consumer's side.
                 alternatives[m.to] = [...(alternatives[m.to] ?? []), { value: v, origin: src.origin, via: log, owner: presenter.owner }];
             }
         }
+        // Withdrawal under revocable terms: a value this presenter gave and no longer offers or holds is removed.
+        const withdrawn = [];
+        for (const [a, s] of Object.entries(sources)) {
+            if (!fromPresenter(a) || !s.revocable)
+                continue;
+            const line = t.reads.find((m) => m.to === a);
+            const still = line && o.gives.includes(line.from) && presenter.values[line.from] !== undefined;
+            if (still)
+                continue;
+            delete values[a];
+            delete sources[a];
+            withdrawn.push(a);
+        }
         const next = { ...r, values, sources, ...(Object.keys(alternatives).length ? { alternatives } : {}) };
         this.put(next);
-        return { contract: takeName, record: recordId, flows, log };
+        this.commit({ take: takeName, from: from ?? presenter.owner }, log, { contract: takeName, record: recordId, state: "closed" });
+        return { contract: takeName, record: recordId, mode, flows, ...(withdrawn.length ? { withdrawn } : {}), log };
+    }
+    /** A local offer contract as an offer object, for a take run against a presenter record at hand. */
+    localOffer(name) {
+        const o = this.contracts.get(name);
+        return o ? { contract: name, owner: "", to: o.to ?? "private", mode: o.mode ?? "gathered", terms: { ...o.terms }, gives: [...o.gives], records: [] } : undefined;
+    }
+    /** Taken values past their terms' `expires` (7.8) are removed, each record one entry; the ids changed. */
+    expire(now) {
+        const out = [];
+        for (const r of this.records.all()) {
+            const gone = Object.entries(r.sources ?? {}).filter(([, s]) => typeof s.until === "string" && s.until <= now).map(([a]) => a);
+            if (!gone.length)
+                continue;
+            const values = { ...r.values };
+            const sources = { ...(r.sources ?? {}) };
+            for (const a of gone) {
+                delete values[a];
+                delete sources[a];
+            }
+            this.put({ ...r, values, sources });
+            const log = this.nextLog();
+            this.commit({ take: "expired", at: now }, log, { contract: "expired", record: r.id, state: "closed" });
+            out.push(r.id);
+        }
+        return out;
     }
 }
 function suggest(r, outcomes, source) {
@@ -296,6 +991,28 @@ function suggest(r, outcomes, source) {
     }
     return { ...r, suggestions: s };
 }
+/**
+ * The version gate at a border (10.1): what a receiver does with data written under another version of a
+ * package it holds. Newer than ours: hold until we upgrade. Older: restamp through the recipes between.
+ * The same, or a package we don't hold, or no version on the wire: take as is.
+ */
+export function versionGate(theirs, installed) {
+    if (!theirs)
+        return { kind: "take" };
+    const at = theirs.lastIndexOf(" /");
+    if (at < 0)
+        return { kind: "take" };
+    const pkg = theirs.slice(0, at).trim();
+    const version = theirs.slice(at + 2).trim();
+    const ours = installed.filter((i) => i.package === pkg).map((i) => i.version).sort().at(-1);
+    if (!ours)
+        return { kind: "take" };
+    if (version > ours)
+        return { kind: "hold", package: pkg, theirs: version, ours };
+    if (version < ours)
+        return { kind: "restamp", package: pkg, theirs: version, ours };
+    return { kind: "take" };
+}
 // ─── Borders (8.5.1) ─────────────────────────────────────────────────────────
 /** Verify a border wrapper from another owner: its log against the owner's key, and its values against the log. */
 export function verifyBorder(w, keys) {