baesian 0.0.0-stage → 1.0.1

package/dist/routing.js

@@ -0,0 +1,411 @@
+import { pathsLoosening } from "./gate-paths.js";
+// The gate's rules (M8, P14, P16): rows, positions, presets, and how a card's stated facts become an outcome at filing
+// (D144, D145). Pure and deterministic, with nothing from Node and no runtime import but the commit gate's paths, pure
+// too, so the CLI, CI (`baesian verify`), a relay later (D158) and the client all reach the same answer. The store runs it at filing and writes its record;
+// docs/vault/Modules/src-routing.md describes it.
+// ---------------------------------------------------------------- rows and positions
+/** The rows a repo sets, keyed by name in the preference file (`row_<name>`): six sliders, security and privacy (D146). */
+export const ROWS = ["public_api", "schema", "dependency", "infra", "user_facing", "security", "privacy", "other"];
+/** The rows fixed at "never without me", with no key in the preference file (D146). */
+export const FIXED_ROWS = ["publishes", "money", "data_loss"];
+export const ALL_ROWS = [...ROWS, ...FIXED_ROWS];
+/** The five positions, from the loosest (P14's scale). The two lowest hold a card back; the rest show it at a level. */
+export const POSITIONS = ["agent-decides", "sample", "tell-me", "stop-and-ask", "never-without-me"];
+/** What the client calls each row, by its consequence (P14). */
+export const ROW_NAMES = {
+    public_api: "Public interfaces and module boundaries",
+    schema: "Data formats",
+    dependency: "Runtime dependencies",
+    infra: "Delivery and infrastructure",
+    user_facing: "Product behaviour",
+    security: "Security",
+    privacy: "Privacy",
+    other: "Anything else that's hard to undo",
+    publishes: "Publishing",
+    money: "Spending",
+    data_loss: "Destroying data",
+};
+export const POSITION_NAMES = {
+    "agent-decides": "let the agent decide",
+    sample: "check a sample afterwards",
+    "tell-me": "tell me but carry on",
+    "stop-and-ask": "stop and ask",
+    "never-without-me": "never without me",
+};
+/** The level a shown card gets at each position. The two lowest positions hold it back. */
+export const LEVEL_AT = { "tell-me": "provisional", "stop-and-ask": "blocking", "never-without-me": "hard" };
+/** The lowest a row may be set: security, and privacy beside it, no lower than "tell me but carry on" (D146, B-z3agk). */
+export const ROW_FLOOR = { security: "tell-me", privacy: "tell-me" };
+/** The row each of the D11 facts falls in. A card with no fact falls in `other`. */
+export const ROW_OF_FACT = {
+    "public-api": "public_api",
+    schema: "schema",
+    dependency: "dependency",
+    infra: "infra",
+    "user-facing": "user_facing",
+    security: "security",
+    privacy: "privacy",
+    publishes: "publishes",
+    money: "money",
+    "data-loss": "data_loss",
+};
+/** Which row a card counts in when several of its rows sit at the same position: the fixed rows, then security and privacy. */
+const ROW_ORDER = ["publishes", "money", "data_loss", "security", "privacy", "public_api", "schema", "infra", "dependency", "user_facing", "other"];
+export const rank = (p) => POSITIONS.indexOf(p);
+const LEVELS = ["provisional", "blocking", "hard"];
+export const levelRank = (l) => LEVELS.indexOf(l);
+export const higherLevel = (a, b) => (b !== undefined && levelRank(b) > levelRank(a) ? b : a);
+export const isFixed = (row) => FIXED_ROWS.includes(row);
+/** One stop stricter or looser, within the row's floor; undefined at either end (B-y6jn6). */
+export function stop(row, from, dir) {
+    const i = rank(from) + (dir === "up" ? 1 : -1);
+    const floor = ROW_FLOOR[row];
+    if (i < (floor ? rank(floor) : 0) || i >= POSITIONS.length)
+        return undefined;
+    return POSITIONS[i];
+}
+const tellMe = {
+    public_api: "tell-me",
+    schema: "tell-me",
+    dependency: "tell-me",
+    infra: "tell-me",
+    user_facing: "tell-me",
+    security: "never-without-me",
+    privacy: "never-without-me",
+    other: "tell-me",
+};
+/**
+ * What a preference change loosens, against the settings in force before it (D163): each row moved toward held,
+ * enforcing turned on, and a lower audit rate or burn-in (B-shndb), which brings fewer held cards back to you; and a
+ * commit gate that sees less, by its globs (B-qkek1, `pathsLoosening()`). Each lets more past you, so in a hosted repo it
+ * takes your passkey; tightening doesn't.
+ */
+export function loosening(before, after) {
+    const out = [];
+    if (before.mode === "shadow" && after.mode === "enforce")
+        out.push("it turns enforcing on");
+    for (const row of ROWS) {
+        if (rank(after.rows[row]) < rank(before.rows[row]))
+            out.push(`it moves ${row} from ${before.rows[row]} to ${after.rows[row]}`);
+    }
+    const percent = (x) => `${Math.round(x * 1000) / 10}%`;
+    for (const rate of ["rate_agent_decides", "rate_sample"]) {
+        if (after[rate] < before[rate])
+            out.push(`it lowers ${rate} from ${percent(before[rate])} to ${percent(after[rate])}`);
+    }
+    if (after.burn_in < before.burn_in)
+        out.push(`it lowers burn_in from ${before.burn_in} to ${after.burn_in}`);
+    out.push(...pathsLoosening(before.paths, after.paths));
+    return out;
+}
+/** The three presets (B-wwxa3), from P14 section 4's table: security and privacy at "never without me" in all three. */
+export const PRESETS = [
+    { id: "today", name: "Today", summary: "Every card reaches you, as it does now.", rows: tellMe },
+    {
+        id: "fewer-interruptions",
+        name: "Fewer interruptions",
+        summary: "Dependencies, infrastructure and anything else go ahead, and a sample comes back to you.",
+        rows: { ...tellMe, dependency: "sample", infra: "sample", other: "sample" },
+    },
+    {
+        id: "hands-off",
+        name: "Hands-off",
+        summary: "Every row but security and privacy goes ahead; dependencies and anything else are the agent's, with fewer audits.",
+        rows: { ...tellMe, public_api: "sample", schema: "sample", infra: "sample", user_facing: "sample", dependency: "agent-decides", other: "agent-decides" },
+    },
+];
+// ---------------------------------------------------------------- when Baesian proposes moving a row (B-jtsfh)
+/** The miss rate a row is tested against (B-jtsfh): 1 in 10. */
+export const MISS_RATE = 0.1;
+/** How sure the test must be before Baesian proposes a move (B-jtsfh): 95%. */
+export const SURE = 0.95;
+/**
+ * How likely a row's miss rate is under `MISS_RATE`, from `answers` final answers with `misses` among them (B-jtsfh):
+ * the posterior from a uniform prior, Beta(misses + 1, answers - misses + 1). For whole numbers a and b, P(p < x) under
+ * Beta(a, b) is P(Binomial(a + b - 1, x) ≥ a), so it's one minus a binomial's first `misses + 1` terms.
+ */
+export function chanceUnder(answers, misses, x = MISS_RATE) {
+    const n = answers + 1;
+    let log = n * Math.log(1 - x);
+    let below = 0;
+    for (let i = 0; i <= misses && i < n; i++) {
+        below += Math.exp(log);
+        log += Math.log((n - i) / (i + 1)) + Math.log(x / (1 - x));
+    }
+    return Math.max(0, Math.min(1, 1 - below));
+}
+/**
+ * The one test, both ways (B-jtsfh): "down" once Baesian is `SURE` a row's miss rate is under `MISS_RATE`, "up" once it's
+ * as sure it's over, or undefined. Loosening after 28 final answers with no miss, 45 with one, 60 with two, 75 with three;
+ * tightening at a miss in the first two answers, 2 in 3, 3 in 10, 5 in 20, 8 in 42.
+ */
+export function rowTest(answers, misses) {
+    const under = chanceUnder(answers, misses);
+    if (under >= SURE)
+        return "down";
+    if (1 - under >= SURE)
+        return "up";
+    return undefined;
+}
+/** More final answers, all without a miss, before the test proposes a lower stop: 0 once it would. */
+export function toLoosen(answers, misses) {
+    let more = 0;
+    while (chanceUnder(answers + more, misses) < SURE)
+        more++;
+    return more;
+}
+/** Final answers it takes, from none, before the test proposes a lower stop, with `misses` among them: 28 with none. */
+export const loosenAfter = (misses = 0) => toLoosen(misses, misses) + misses;
+/** The most final answers in which a single miss proposes a higher stop: a miss in the first 2. */
+export function oneMissWithin() {
+    let answers = 1;
+    while (rowTest(answers + 1, 1) === "up")
+        answers++;
+    return answers;
+}
+/** The fewest misses in `answers` final answers at which the test proposes a higher stop: 1 in 2, 3 in 10, 5 in 20. */
+export function tightenAt(answers) {
+    let misses = 0;
+    while (misses <= answers && rowTest(answers, misses) !== "up")
+        misses++;
+    return misses;
+}
+/** The audit rates and burn-in every preset starts with (B-fgc4y): 1 in 10, 1 in 3, and each row's first 10 held cards. */
+export const AUDIT_DEFAULTS = { rate_agent_decides: 0.1, rate_sample: 1 / 3, burn_in: 10 };
+/** With no preference file, a repo runs "Today" in shadow, which routes exactly as Baesian did before the gate (P14). */
+export const TODAY = { mode: "shadow", rows: PRESETS[0].rows, ...AUDIT_DEFAULTS, paths: {} };
+// ---------------------------------------------------------------- the rules (rules-1)
+/** The rules' version, in every gate record. */
+export const GATE_VERSION = "rules-1";
+/** The strictest row a card's facts fall in, and its position (P14: strictest wins); `other` for a card with none. */
+export function rowOf(touches, settings) {
+    const positionOf = (row) => (isFixed(row) ? "never-without-me" : settings.rows[row]);
+    const rows = touches.length ? [...new Set(touches.map((f) => ROW_OF_FACT[f]))] : ["other"];
+    let best = rows[0];
+    for (const row of rows.slice(1)) {
+        const d = rank(positionOf(row)) - rank(positionOf(best));
+        if (d > 0 || (d === 0 && ROW_ORDER.indexOf(row) < ROW_ORDER.indexOf(best)))
+            best = row;
+    }
+    return { row: best, position: positionOf(best) };
+}
+/**
+ * The gate's outcome for a card (D145): its strictest row's position, raised by the floors, by the one-way rule (B-yebnn)
+ * and for Baesian's own cards and revisions that follow an answer, each only raising it. "Tell me but carry on" or higher
+ * shows it at that position's level, raised by the agent's (B-chq61: a level is a minimum only when it's shown);
+ * either of the two lowest holds it back, drawn for audit at that position's rate, or always within the row's burn-in
+ * (B-fgc4y). In shadow this is what it would have done (D148).
+ */
+export function route(input, settings) {
+    const { row, position } = rowOf(input.touches, settings);
+    let at = position;
+    let reason = isFixed(row) ? "floor" : "row";
+    const raise = (to, why) => {
+        if (rank(at) < rank(to)) {
+            at = to;
+            reason = why;
+        }
+    };
+    if (!isFixed(row) && ROW_FLOOR[row])
+        raise(ROW_FLOOR[row], "floor");
+    if (input.reverse === "one-way")
+        raise("tell-me", "one-way");
+    if (input.source !== "agent")
+        raise("tell-me", input.source);
+    const shownAt = LEVEL_AT[at];
+    if (shownAt) {
+        const level = higherLevel(shownAt, input.asked);
+        return { row, position, outcome: "shown", level, reason: level !== shownAt ? "agent" : reason };
+    }
+    const p = at === "agent-decides" ? settings.rate_agent_decides : settings.rate_sample;
+    const held_before = input.heldBefore(row);
+    const burn_in = held_before < settings.burn_in;
+    return { row, position, outcome: "held", reason, draw: input.draw, p, held_before, burn_in, drawn: burn_in || input.draw < p };
+}
+/**
+ * The level a card is written with, the level in force locally (P16 section 3): a shown card's level; a held card's
+ * "provisional" when enforcing, since the agent goes ahead with its pick (B-chq61); and in shadow, where nothing is
+ * held, the agent's level or provisional, as Baesian showed it before the gate.
+ */
+export function levelInForce(d, mode, asked) {
+    if (d.outcome === "shown")
+        return d.level;
+    return mode === "enforce" ? "provisional" : higherLevel("provisional", asked);
+}
+// ---------------------------------------------------------------- misses (B-87tkc, B-ab06a)
+/** Answers that end a card one way or the other: a choice, the reviewer's own answer, or a rejection. */
+export const FINAL = new Set(["accept", "alternative", "correction", "reject"]);
+/** Final answers that overturn the agent's pick. */
+export const OVERTURNS = new Set(["alternative", "correction", "reject"]);
+/**
+ * A card's outcome from its verdicts. `preference` is whether its crux is one of preference (`crux_preference`, on its
+ * latest revision): then the blind choice is the answer that counts, since the agent's case can persuade you of what to
+ * value but holds no fact you lacked (B-ab06a). On a crux of fact B-87tkc stands: coming round after the case isn't a miss.
+ */
+export function outcomeOf(verdicts, opts = {}) {
+    const last = [...verdicts].reverse().find((v) => FINAL.has(v.response));
+    const asked = verdicts.some((v) => v.should_have_asked === true);
+    if (!last)
+        return asked ? { miss: true, missBy: "asked", switched: false } : { miss: false, switched: false };
+    const final = { response: last.response, at: last.at, ...(last.first_choice ? { first_choice: last.first_choice } : {}) };
+    const missBy = OVERTURNS.has(last.response) ? "overturn" : asked ? "asked" : opts.preference === true && last.first_choice === "alternative" ? "blind" : undefined;
+    return { final, miss: missBy !== undefined, ...(missBy ? { missBy } : {}), switched: last.response === "accept" && last.first_choice === "alternative" };
+}
+/**
+ * Whether a card was answered in chat (B-hswmx): its latest revision says so, or an answer on an earlier one was marked
+ * seen. Its choice wasn't made blind, so calibration leaves it out of every measure: the report's counts, the replay of
+ * past cards, and the slider proposals. It's in the record, and can become a rule, like any card.
+ */
+export function answeredInChat(c) {
+    return c.meta.answered_in_chat !== undefined || c.verdicts.some((v) => v.seen === true);
+}
+// ---------------------------------------------------------------- Baesian's own cards
+/** The name Baesian files its own cards under: conflict, convention and slider cards. */
+export const BAESIAN = "baesian";
+/**
+ * Baesian's own cards: conflicts (D35), rule drafts (D110), convention cards (D161) and slider proposals (B-y6jn6). The
+ * gate always shows them, and the report, the replay and the proposals leave them out: they're not an agent's decisions.
+ */
+export function isOwnCard(meta) {
+    return meta.source_agent === BAESIAN || meta.rule !== undefined || meta.convention !== undefined || meta.pref_row !== undefined || meta.conflict_of !== undefined;
+}
+/**
+ * A card as `GET /api/state` gives it, as the replay reads it, or undefined for one it leaves out: Baesian's own,
+ * withdrawn ones, and those answered in chat (B-hswmx). So the client can replay any setting itself, a single row moved,
+ * say, as the server does for presets.
+ */
+export function replayCardOf(c) {
+    if (isOwnCard(c.meta) || c.gate?.source === "baesian" || c.status === "withdrawn" || answeredInChat(c))
+        return undefined;
+    return { id: c.meta.id, touches: c.meta.touches, reverse: c.meta.reverse, ...(c.gate?.asked ? { asked: c.gate.asked } : {}), source: c.gate?.source ?? "agent", outcome: outcomeOf(c.verdicts, { preference: c.meta.crux_preference }) };
+}
+/**
+ * What a setting would have done to past cards, by re-running the rules over them (P14 section 4). Under "Today" the
+ * shadow record never shows a card as would-have-held, so this is how the client shows what a looser preset would
+ * hold. Cards in filing order; the audits are an expectation, since the draw needs a hash the client doesn't compute.
+ */
+export function replay(cards, settings) {
+    const empty = () => ({ cards: 0, shown: 0, held: 0, heldMissed: 0, audits: 0 });
+    const rows = {};
+    const total = empty();
+    const heldSoFar = new Map();
+    const held = [];
+    for (const c of cards) {
+        const d = route({ touches: c.touches, reverse: c.reverse, asked: c.asked, source: c.source, draw: 1, heldBefore: (row) => heldSoFar.get(row) ?? 0 }, settings);
+        const r = (rows[d.row] ??= empty());
+        for (const t of [r, total]) {
+            t.cards++;
+            if (d.outcome === "shown")
+                t.shown++;
+            else {
+                t.held++;
+                if (c.outcome.miss)
+                    t.heldMissed++;
+                t.audits += d.burn_in ? 1 : d.p;
+            }
+        }
+        if (d.outcome === "held") {
+            heldSoFar.set(d.row, (heldSoFar.get(d.row) ?? 0) + 1);
+            held.push(c.id);
+        }
+    }
+    return { rows, total, held };
+}
+/** The question every survey card asks, and its two answers. */
+export const SURVEY_QUESTION = {
+    question: "Would you be fine not seeing a decision like this one, and checking a sample afterwards?",
+    see: "Show me ones like it",
+    fine: "Fine not seeing it",
+};
+export const SURVEY = [
+    {
+        row: "dependency",
+        title: "The date-parsing library",
+        question: "Which library should parse dates in the import step?",
+        doing: "writing the CSV import",
+        touches: ["dependency"],
+        reverse: "cheap",
+        proposal: "date-fns",
+        proposal_then: "a small runtime dependency is added to package.json",
+        alternative: "The platform's Intl API",
+        alternative_then: "no dependency, and a little more code to handle formats",
+    },
+    {
+        row: "infra",
+        title: "Caching dependencies in CI",
+        question: "Should the CI workflow cache installed packages between runs?",
+        doing: "speeding up the test workflow",
+        touches: ["infra"],
+        reverse: "cheap",
+        proposal: "Cache them",
+        proposal_then: "the workflow restores packages from a cache keyed on the lockfile",
+        alternative: "Install fresh each run",
+        alternative_then: "runs stay slower, with nothing cached to go stale",
+    },
+    {
+        row: "other",
+        title: "Retrying failed uploads",
+        question: "How should the uploader retry a failed upload?",
+        doing: "making uploads survive a flaky network",
+        touches: [],
+        reverse: "moderate",
+        proposal: "Exponential backoff, five tries",
+        proposal_then: "a failed upload is retried over about a minute, then reported",
+        alternative: "Fail at once",
+        alternative_then: "the user sees the failure straight away and retries by hand",
+    },
+    {
+        row: "user_facing",
+        title: "The empty search page",
+        question: "What should search show when nothing matches?",
+        doing: "building the search page",
+        touches: ["user-facing"],
+        reverse: "cheap",
+        proposal: "Suggestions from recent searches",
+        proposal_then: "the empty page lists the user's last five searches",
+        alternative: "A plain message",
+        alternative_then: "the page says nothing matched, and nothing more",
+    },
+    {
+        row: "schema",
+        title: "Storing tags on a run",
+        question: "How should a run's tags be stored?",
+        doing: "adding tags to runs",
+        touches: ["schema"],
+        reverse: "moderate",
+        proposal: "A tags table",
+        proposal_then: "a migration adds a table joining runs to tags",
+        alternative: "A JSON column on runs",
+        alternative_then: "a migration adds one column; tags can't be indexed",
+    },
+    {
+        row: "public_api",
+        title: "Paging the runs endpoint",
+        question: "How should the runs endpoint page its results?",
+        doing: "adding paging to the API",
+        touches: ["public-api"],
+        reverse: "moderate",
+        proposal: "Cursor tokens",
+        proposal_then: "clients pass an opaque cursor from the last page",
+        alternative: "Page numbers",
+        alternative_then: "clients pass page and size, and can jump to any page",
+    },
+];
+/**
+ * The preset closest to the survey's answers (B-5na1k): the one whose rows agree with the most answers, a "fine" agreeing
+ * with a row that holds cards back and a "see" with one that shows them. A tie goes to the stricter preset.
+ */
+export function suggestPreset(answers) {
+    const held = (p) => rank(p) < rank("tell-me");
+    let best = PRESETS[0];
+    let bestScore = -1;
+    for (const preset of PRESETS) {
+        const score = (answers.fine ?? []).filter((r) => held(preset.rows[r])).length + (answers.see ?? []).filter((r) => !held(preset.rows[r])).length;
+        if (score > bestScore) {
+            best = preset;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+//# sourceMappingURL=routing.js.map