@getbourdon/participants 0.5.6 → 0.6.0

package/dist/skill-proposals.js

@@ -0,0 +1,757 @@
+// SPDX-License-Identifier: BUSL-1.1
+/**
+ * Skill proposals: the approval gate in front of the shared skill library.
+ * Port of the engine's `core/skill_proposals.py` (plan 005, phase 4).
+ *
+ * An agent *proposes* one of the skills it advertises; a person *approves* it;
+ * only then does {@link promoteSkill} write it into `<library>/skills`.
+ *
+ * Layout (interoperable with the engine: either side reads what the other wrote):
+ *
+ *     <library>/.skill-proposals/<proposal_id>/
+ *         proposal.yaml     the record: what was proposed, by whom, and the decision
+ *         content/          a snapshot of the skill folder, taken at proposal time
+ *
+ * Load-bearing rules:
+ *
+ *  - **The snapshot is what gets approved.** Proposing copies the skill's files
+ *    into `content/` and records their `content_sha256`. Approval re-reads that
+ *    snapshot, re-checks every text-only rule and refuses unless it still hashes
+ *    to the recorded value, so editing the agent's folder after proposing cannot
+ *    change what lands in the library.
+ *  - **One human-confirmed approval promotes.** Nothing in this module is
+ *    reachable over MCP except {@link createProposal}. Approval, rejection,
+ *    retirement and rollback are called by the operator's terminal command,
+ *    which asks the person at the keyboard to confirm. Consensus votes on a
+ *    proposal's ballot are advisory: they are shown to the approver and recorded
+ *    beside the decision, and never promote anything on their own.
+ *  - **Every decision is audited before it happens, fail-closed**, in the same
+ *    federation audit log the quarantine staging decisions use.
+ *
+ * Nothing here performs caller authorization; the callers (the MCP tool for
+ * proposing, the CLI for deciding) are the gates.
+ */
+import { randomBytes } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { ConsensusEngine, DECISION_ALLOW, DECISION_DENY, withManifestLock, } from "@getbourdon/federation";
+import { parse as yamlParse, stringify as yamlStringify } from "yaml";
+import { computeContentSha256, isPathLinkOrReparse, readSkillFolder, } from "./skill-index.js";
+import { SkillIndexError, SkillNotFoundError, getSkillRow, promoteSkill, readSharedSkill, setSkillValidTo, suggestAvailableName, validateSkillName, } from "./skill-store.js";
+export const PROPOSALS_DIRNAME = ".skill-proposals";
+export const RECORD_NAME = "proposal.yaml";
+export const CONTENT_DIRNAME = "content";
+const CREATE_LOCK_STEM = ".create";
+const TMP_PREFIX = ".tmp-";
+export const STATUS_PENDING = "pending";
+export const STATUS_APPROVED = "approved";
+export const STATUS_REJECTED = "rejected";
+const STATUSES = new Set([STATUS_PENDING, STATUS_APPROVED, STATUS_REJECTED]);
+export const PROPOSER_TRUSTED = "trusted";
+export const PROPOSER_QUARANTINED = "quarantined";
+/** The advisory ballot's options. A ballot only informs the person deciding. */
+export const BALLOT_OPTIONS = ["approve", "reject"];
+/** Tunable limits. `maxPendingPerProposer`: pending proposals one proposer may
+ * hold at once, so a caller cannot fill the library with snapshots nobody
+ * asked for. */
+export const SKILL_PROPOSAL_LIMITS = {
+    maxPendingPerProposer: 50,
+    maxReasonChars: 500,
+};
+const ID_RE = /^sp-[0-9a-f]{12}$/;
+// -- errors -------------------------------------------------------------------
+/** Base class for refusals raised by the proposal gate. */
+export class SkillProposalError extends SkillIndexError {
+    constructor(message) {
+        super(message);
+        this.name = "SkillProposalError";
+    }
+}
+/** No proposal with that id. */
+export class ProposalNotFoundError extends SkillProposalError {
+    constructor(message) {
+        super(message);
+        this.name = "ProposalNotFoundError";
+    }
+}
+/** The proposal is not pending (it was already decided). */
+export class ProposalStateError extends SkillProposalError {
+    constructor(message) {
+        super(message);
+        this.name = "ProposalStateError";
+    }
+}
+/** The snapshot no longer hashes to what was proposed, or to what the approver saw. */
+export class ProposalDigestMismatchError extends SkillProposalError {
+    constructor(message) {
+        super(message);
+        this.name = "ProposalDigestMismatchError";
+    }
+}
+/** `datetime.now(timezone.utc).isoformat(timespec="seconds")`. */
+function nowIso() {
+    return `${new Date().toISOString().slice(0, 19)}+00:00`;
+}
+function today() {
+    return new Date().toISOString().slice(0, 10);
+}
+function isDict(value) {
+    return (value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date));
+}
+/** Python `str()` of a scalar read from YAML. */
+function pyStr(value) {
+    if (value === null || value === undefined)
+        return "None";
+    if (value === true)
+        return "True";
+    if (value === false)
+        return "False";
+    return String(value);
+}
+/** Python truthiness of a YAML value. */
+function truthy(value) {
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (isDict(value))
+        return Object.keys(value).length > 0;
+    return Boolean(value);
+}
+/** The record as written: the engine's key order, absent optionals omitted. */
+export function proposalToDict(proposal) {
+    const out = {
+        proposal_id: proposal.proposal_id,
+        status: proposal.status,
+        name: proposal.name,
+        description: proposal.description,
+        content_sha256: proposal.content_sha256,
+        source_agent: proposal.source_agent,
+        path_hint: proposal.path_hint,
+        scope: proposal.scope,
+    };
+    if (proposal.project !== null)
+        out.project = proposal.project;
+    if (proposal.origin !== null)
+        out.origin = { ...proposal.origin };
+    out.visibility = proposal.visibility;
+    out.proposed_by = proposal.proposed_by;
+    out.proposer_tier = proposal.proposer_tier;
+    out.created_at = proposal.created_at;
+    out.files = proposal.files.map((item) => ({ ...item }));
+    out.ballot = proposal.ballot;
+    if (proposal.decision !== null)
+        out.decision = { ...proposal.decision };
+    return out;
+}
+/** Parse a record; throws {@link SkillProposalError} on anything malformed. */
+export function proposalFromDict(data) {
+    if (!isDict(data))
+        throw new SkillProposalError("proposal record is not a mapping");
+    const required = [
+        "proposal_id",
+        "name",
+        "description",
+        "content_sha256",
+        "source_agent",
+        "proposed_by",
+        "proposer_tier",
+        "created_at",
+        "path_hint",
+        "scope",
+    ];
+    // Python evaluates the constructor's keyword arguments in order, so the
+    // first missing key (or the invalid name) is the one reported.
+    for (const key of required) {
+        if (!Object.hasOwn(data, key)) {
+            throw new SkillProposalError(`proposal record is missing '${key}'`);
+        }
+        if (key === "name")
+            validateSkillName(data.name);
+    }
+    const proposal = {
+        proposal_id: pyStr(data.proposal_id),
+        name: data.name,
+        description: pyStr(data.description),
+        content_sha256: pyStr(data.content_sha256),
+        source_agent: pyStr(data.source_agent),
+        proposed_by: pyStr(data.proposed_by),
+        proposer_tier: pyStr(data.proposer_tier),
+        created_at: pyStr(data.created_at),
+        path_hint: pyStr(data.path_hint),
+        scope: pyStr(data.scope),
+        visibility: truthy(data.visibility) ? pyStr(data.visibility) : "team",
+        project: data.project ?? null,
+        origin: isDict(data.origin) ? { ...data.origin } : null,
+        files: Array.isArray(data.files) ? data.files.filter(isDict).map((item) => ({ ...item })) : [],
+        ballot: truthy(data.ballot ?? false),
+        status: truthy(data.status) ? pyStr(data.status) : STATUS_PENDING,
+        decision: isDict(data.decision) ? { ...data.decision } : null,
+    };
+    if (!isProposalId(proposal.proposal_id) || !STATUSES.has(proposal.status)) {
+        throw new SkillProposalError("proposal record is malformed");
+    }
+    return proposal;
+}
+/** The row a listing shows: no file list, no decision detail. */
+export function proposalSummary(proposal) {
+    const out = {
+        proposal_id: proposal.proposal_id,
+        status: proposal.status,
+        name: proposal.name,
+        description: proposal.description,
+        content_sha256: proposal.content_sha256,
+        source_agent: proposal.source_agent,
+        proposed_by: proposal.proposed_by,
+        proposer_tier: proposal.proposer_tier,
+        created_at: proposal.created_at,
+        file_count: Math.max(0, proposal.files.length - 1),
+    };
+    if (proposal.origin !== null)
+        out.origin = { ...proposal.origin };
+    return out;
+}
+export function isProposalId(value) {
+    return typeof value === "string" && ID_RE.test(value);
+}
+/** `<library>/.skill-proposals`. */
+export function proposalsRoot(libraryPath) {
+    return join(libraryPath, PROPOSALS_DIRNAME);
+}
+function proposalDir(libraryPath, proposalId) {
+    if (!isProposalId(proposalId)) {
+        throw new ProposalNotFoundError(`not a proposal id: '${String(proposalId)}'`);
+    }
+    return join(proposalsRoot(libraryPath), proposalId);
+}
+/** An existing proposal's folder; the lock beside its record never creates one. */
+function existingProposalDir(libraryPath, proposalId) {
+    const folder = proposalDir(libraryPath, proposalId);
+    if (!isDirectory(folder) || isPathLinkOrReparse(folder)) {
+        throw new ProposalNotFoundError(`no skill proposal '${proposalId}'`);
+    }
+    return folder;
+}
+function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function writeRecord(folder, proposal) {
+    // YAML 1.1 quoting, so a timestamp stays a string for the engine's reader.
+    const text = yamlStringify(proposalToDict(proposal), {
+        version: "1.1",
+        sortMapEntries: false,
+        singleQuote: true,
+        lineWidth: 0,
+    });
+    const target = join(folder, RECORD_NAME);
+    const temp = join(folder, `.${RECORD_NAME}.${randomBytes(6).toString("hex")}.tmp`);
+    try {
+        const fd = openSync(temp, "wx");
+        try {
+            writeSync(fd, Buffer.from(text, "utf8"));
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(temp, target);
+    }
+    finally {
+        if (existsSync(temp))
+            rmSync(temp, { force: true });
+    }
+}
+const UTF8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+/** Read one proposal; throws {@link ProposalNotFoundError} or {@link SkillProposalError}. */
+export function loadProposal(libraryPath, proposalId) {
+    const folder = proposalDir(libraryPath, proposalId);
+    const record = join(folder, RECORD_NAME);
+    // A record that is a file implies its folder exists (the link checks lstat).
+    if (!isFile(record) || isPathLinkOrReparse(folder) || isPathLinkOrReparse(record)) {
+        throw new ProposalNotFoundError(`no skill proposal '${proposalId}'`);
+    }
+    let data;
+    try {
+        data = yamlParse(UTF8.decode(readFileSync(record)), {
+            version: "1.1",
+            uniqueKeys: false,
+            logLevel: "silent",
+        });
+    }
+    catch {
+        throw new SkillProposalError(`proposal '${proposalId}' cannot be read`);
+    }
+    const proposal = proposalFromDict(data);
+    if (proposal.proposal_id !== proposalId) {
+        throw new SkillProposalError(`proposal '${proposalId}' does not match its folder`);
+    }
+    return proposal;
+}
+/** Every readable proposal (optionally of one `status`), oldest first. */
+export function listProposals(libraryPath, status = null) {
+    const root = proposalsRoot(libraryPath);
+    if (!isDirectory(root) || isPathLinkOrReparse(root))
+        return [];
+    const found = [];
+    for (const child of readdirSync(root)) {
+        if (!isProposalId(child))
+            continue;
+        let proposal;
+        try {
+            proposal = loadProposal(libraryPath, child);
+        }
+        catch (err) {
+            if (err instanceof SkillIndexError)
+                continue;
+            throw err;
+        }
+        if (status === null || proposal.status === status)
+            found.push(proposal);
+    }
+    return found.sort((a, b) => a.created_at !== b.created_at
+        ? a.created_at < b.created_at
+            ? -1
+            : 1
+        : a.proposal_id < b.proposal_id
+            ? -1
+            : a.proposal_id > b.proposal_id
+                ? 1
+                : 0);
+}
+// -- proposing ----------------------------------------------------------------
+function writeSnapshot(folder, content) {
+    const targetRoot = join(folder, CONTENT_DIRNAME);
+    mkdirSync(targetRoot);
+    for (const [rel, data] of content.files) {
+        const target = join(targetRoot, ...rel.split("/"));
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, data);
+    }
+}
+/**
+ * Snapshot `content` into a new pending proposal.
+ *
+ * `content` must come from `readSkillFolder` over the folder the agent's own
+ * reader resolved for `ref` (the advertised SkillRef). Returns
+ * `{ proposal, created }`: proposing the same bytes of the same skill again
+ * while a proposal is pending returns that proposal unchanged.
+ */
+export function createProposal(libraryPath, content, options) {
+    const { ref, sourceAgent, proposedBy, proposerTier } = options;
+    if (proposerTier !== PROPOSER_TRUSTED && proposerTier !== PROPOSER_QUARANTINED) {
+        throw new SkillProposalError(`unknown proposer tier '${proposerTier}'`);
+    }
+    const name = validateSkillName(content.frontMatter.name);
+    const digest = computeContentSha256(content.files);
+    const root = proposalsRoot(libraryPath);
+    mkdirSync(root, { recursive: true });
+    if (isPathLinkOrReparse(root)) {
+        throw new SkillProposalError(`${PROPOSALS_DIRNAME}/ must not be a link`);
+    }
+    return withManifestLock(join(root, CREATE_LOCK_STEM), () => {
+        const pending = listProposals(libraryPath, STATUS_PENDING);
+        for (const existing of pending) {
+            if (existing.source_agent === sourceAgent &&
+                existing.name === name &&
+                existing.content_sha256 === digest) {
+                return { proposal: existing, created: false };
+            }
+        }
+        const mine = pending.filter((p) => p.proposed_by === proposedBy).length;
+        const limit = SKILL_PROPOSAL_LIMITS.maxPendingPerProposer;
+        if (mine >= limit) {
+            throw new SkillProposalError(`'${proposedBy}' already has ${mine} pending skill proposals ` +
+                `(limit ${limit}); wait for some to be decided`);
+        }
+        let proposalId = `sp-${randomBytes(6).toString("hex")}`;
+        while (existsSync(join(root, proposalId))) {
+            proposalId = `sp-${randomBytes(6).toString("hex")}`;
+        }
+        const visibility = ref.visibility;
+        const origin = ref.origin;
+        const proposal = {
+            proposal_id: proposalId,
+            name,
+            description: content.frontMatter.description,
+            content_sha256: digest,
+            source_agent: sourceAgent,
+            proposed_by: proposedBy,
+            proposer_tier: proposerTier,
+            created_at: options.createdAt || nowIso(),
+            path_hint: truthy(ref.path_hint) ? String(ref.path_hint) : "",
+            scope: truthy(ref.scope) ? String(ref.scope) : "",
+            visibility: visibility === "public" || visibility === "team" || visibility === "private"
+                ? visibility
+                : "team",
+            project: typeof ref.project === "string" ? ref.project : null,
+            origin: isDict(origin) ? { ...origin } : null,
+            files: content.files.map(([rel, data]) => ({ file: rel, bytes: data.length })),
+            ballot: false,
+            status: STATUS_PENDING,
+            decision: null,
+        };
+        const staging = join(root, `${TMP_PREFIX}${randomBytes(6).toString("hex")}`);
+        try {
+            mkdirSync(staging);
+            writeSnapshot(staging, content);
+            writeRecord(staging, proposal);
+            renameSync(staging, join(root, proposalId));
+        }
+        finally {
+            if (existsSync(staging))
+                rmSync(staging, { recursive: true, force: true });
+        }
+        return { proposal, created: true };
+    });
+}
+/** The snapshot, re-checked against every content rule and its recorded hash. */
+export function readProposalContent(libraryPath, proposal) {
+    const folder = join(proposalDir(libraryPath, proposal.proposal_id), CONTENT_DIRNAME);
+    const content = readSkillFolder(folder);
+    if (computeContentSha256(content.files) !== proposal.content_sha256) {
+        throw new ProposalDigestMismatchError(`proposal ${proposal.proposal_id}: the snapshot no longer matches ` +
+            `content_sha256 ${proposal.content_sha256.slice(0, 12)}`);
+    }
+    return content;
+}
+/** The shared skill already using `name`, if any (retired included). */
+export function collisionFor(libraryPath, name) {
+    try {
+        return getSkillRow(libraryPath, name);
+    }
+    catch (err) {
+        if (err instanceof SkillNotFoundError)
+            return null;
+        throw err;
+    }
+}
+// -- the advisory ballot ------------------------------------------------------
+function engine(libraryPath) {
+    return new ConsensusEngine(join(libraryPath, ".consensus"));
+}
+/** A Node filesystem error (Python's `OSError`) or a plain `Error` the engine
+ * raises for bad input (Python's `ValueError`). */
+function isOsOrValueError(err) {
+    return err instanceof Error;
+}
+/**
+ * Open a consensus ballot under the proposal's id. Votes on it only advise.
+ *
+ * Returns false (and leaves the proposal without a ballot) when one cannot be
+ * opened; a proposal never fails over its advisory ballot.
+ */
+export function openAdvisoryBallot(libraryPath, proposal) {
+    try {
+        engine(libraryPath).propose({
+            topic: `Promote skill '${proposal.name}' into the shared library (advisory)`,
+            options: [...BALLOT_OPTIONS],
+            proposedBy: proposal.proposed_by,
+            proposalId: proposal.proposal_id,
+            metadata: {
+                kind: "skill_proposal",
+                advisory: true,
+                content_sha256: proposal.content_sha256,
+                source_agent: proposal.source_agent,
+            },
+        });
+    }
+    catch (err) {
+        if (isOsOrValueError(err))
+            return false;
+        throw err;
+    }
+    const folder = proposalDir(libraryPath, proposal.proposal_id);
+    withManifestLock(join(folder, RECORD_NAME), () => {
+        const current = loadProposal(libraryPath, proposal.proposal_id);
+        current.ballot = true;
+        writeRecord(folder, current);
+    });
+    proposal.ballot = true;
+    return true;
+}
+/** Vote counts and voters on the proposal's ballot; null without one. */
+export function advisoryTally(libraryPath, proposal) {
+    if (!proposal.ballot)
+        return null;
+    let tally;
+    try {
+        tally = engine(libraryPath).tally(proposal.proposal_id);
+    }
+    catch {
+        return null;
+    }
+    const summary = isDict(tally.options_summary) ? tally.options_summary : {};
+    const out = {};
+    for (const option of BALLOT_OPTIONS) {
+        const entry = isDict(summary[option]) ? summary[option] : {};
+        const voters = Array.isArray(entry.voters) ? entry.voters : [];
+        out[option] = {
+            votes: Math.trunc(Number(entry.votes ?? 0)),
+            voters: voters
+                .map((v) => String(isDict(v) ? v.agent_id : undefined))
+                .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
+        };
+    }
+    return out;
+}
+function closeBallot(libraryPath, proposal, status, outcome) {
+    if (!proposal.ballot)
+        return;
+    // The decision already landed; the ballot only advised it.
+    try {
+        engine(libraryPath).close(proposal.proposal_id, status, {
+            decided_by_gate: "skill approval",
+            outcome,
+        });
+    }
+    catch {
+        // best effort
+    }
+}
+function tallyText(tally) {
+    if (tally === null)
+        return "advisory=none";
+    return "advisory=" + BALLOT_OPTIONS.map((opt) => `${opt}:${tally[opt].votes}`).join(",");
+}
+// -- audit --------------------------------------------------------------------
+/** Audit row BEFORE the mutation, fail-closed (`required: true`). */
+function record(audit, actor, op, namespace, detail) {
+    if (!audit)
+        return;
+    audit.record(actor, op, namespace, DECISION_ALLOW, detail, { required: true });
+}
+function recordFailure(audit, actor, op, namespace, exc) {
+    if (!audit)
+        return;
+    // Best effort: the original error is the one to surface.
+    try {
+        const kind = exc instanceof Error ? exc.name : typeof exc;
+        audit.record(actor, op, namespace, DECISION_DENY, `failed: ${kind}`);
+    }
+    catch {
+        // ignored
+    }
+}
+function checkExpected(proposal, expectedSha256) {
+    if (expectedSha256 === null || expectedSha256 === undefined)
+        return;
+    const prefix = expectedSha256.trim().toLowerCase();
+    if (prefix.length < 8 || !proposal.content_sha256.startsWith(prefix)) {
+        throw new ProposalDigestMismatchError(`proposal ${proposal.proposal_id} has content_sha256 ` +
+            `${proposal.content_sha256.slice(0, 12)}, not the ${prefix.slice(0, 12)} that was reviewed`);
+    }
+}
+/**
+ * Promote a pending proposal's snapshot into the shared library.
+ *
+ * This is the one human-confirmed approval. It is not exposed over MCP; the
+ * operator's terminal command calls it after asking the person at the keyboard
+ * to confirm (`channel` records how).
+ *
+ * Naming: the skill's own name by default, or `name`. When that name is taken,
+ * `update: true` promotes the snapshot as the next version of the existing
+ * skill; otherwise the skill is renamed to a free name and the original name is
+ * reported in `renamedFrom`.
+ */
+export function approveProposal(libraryPath, proposalId, options) {
+    const { approvedBy, channel, audit } = options;
+    const folder = existingProposalDir(libraryPath, proposalId);
+    const outcome = withManifestLock(join(folder, RECORD_NAME), () => {
+        const proposal = loadProposal(libraryPath, proposalId);
+        if (proposal.status !== STATUS_PENDING) {
+            throw new ProposalStateError(`proposal ${proposalId} is already ${proposal.status}`);
+        }
+        checkExpected(proposal, options.expectedSha256);
+        const content = readProposalContent(libraryPath, proposal);
+        let target = validateSkillName(options.name ?? proposal.name);
+        const existing = collisionFor(libraryPath, target);
+        let expectedVersion = null;
+        let renamedFrom = null;
+        if (existing !== null) {
+            if (options.update) {
+                expectedVersion = existing.version;
+            }
+            else {
+                const suggestion = suggestAvailableName(libraryPath, target);
+                if (suggestion === null) {
+                    throw new SkillProposalError(`no free name derived from '${target}'`);
+                }
+                renamedFrom = target;
+                target = suggestion;
+            }
+        }
+        else if (options.update) {
+            throw new SkillNotFoundError(`no shared skill named '${target}' to update`);
+        }
+        const tally = advisoryTally(libraryPath, proposal);
+        const visibility = options.visibility || proposal.visibility;
+        let detail = `proposal=${proposalId} name=${target} content_sha256=${proposal.content_sha256} ` +
+            `source_agent=${proposal.source_agent} proposed_by=${proposal.proposed_by} ` +
+            `proposer_tier=${proposal.proposer_tier} channel=${channel} ${tallyText(tally)}`;
+        if (renamedFrom !== null)
+            detail += ` renamed_from=${renamedFrom}`;
+        record(audit, approvedBy, "skill.approve", proposal.source_agent, detail);
+        let result;
+        try {
+            result = promoteSkill(libraryPath, content, {
+                sourceAgent: proposal.source_agent,
+                promotedBy: approvedBy,
+                name: target,
+                expectedVersion,
+                visibility,
+                proposalId,
+            });
+        }
+        catch (exc) {
+            recordFailure(audit, approvedBy, "skill.approve", proposal.source_agent, exc);
+            throw exc;
+        }
+        proposal.status = STATUS_APPROVED;
+        const decision = {
+            by: approvedBy,
+            at: nowIso(),
+            channel,
+            promoted_name: result.row.name,
+            promoted_version: result.row.version,
+            changed: result.changed,
+        };
+        if (renamedFrom !== null)
+            decision.renamed_from = renamedFrom;
+        if (tally !== null) {
+            decision.advisory = Object.fromEntries(BALLOT_OPTIONS.map((opt) => [opt, tally[opt].votes]));
+        }
+        proposal.decision = decision;
+        writeRecord(folder, proposal);
+        return { proposal, result, renamedFrom, tally };
+    });
+    closeBallot(libraryPath, outcome.proposal, "resolved", "approved");
+    return {
+        proposal: outcome.proposal,
+        row: outcome.result.row,
+        changed: outcome.result.changed,
+        renamedFrom: outcome.renamedFrom,
+        advisory: outcome.tally,
+    };
+}
+// str.isspace() characters, as str.split() with no argument splits on them.
+const PY_WHITESPACE_RUN = 
+// eslint-disable-next-line no-control-regex
+/[\t\n\v\f\r\x1c-\x1f \x85\xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]+/;
+/** Python `" ".join(text.split())`. */
+function collapseWhitespace(text) {
+    return text
+        .split(PY_WHITESPACE_RUN)
+        .filter((part) => part !== "")
+        .join(" ");
+}
+/** Mark a pending proposal rejected. The snapshot is kept for the record. */
+export function rejectProposal(libraryPath, proposalId, options) {
+    const { rejectedBy, channel, audit } = options;
+    const folder = existingProposalDir(libraryPath, proposalId);
+    const reason = [...collapseWhitespace(options.reason ?? "")]
+        .slice(0, SKILL_PROPOSAL_LIMITS.maxReasonChars)
+        .join("");
+    const proposal = withManifestLock(join(folder, RECORD_NAME), () => {
+        const current = loadProposal(libraryPath, proposalId);
+        if (current.status !== STATUS_PENDING) {
+            throw new ProposalStateError(`proposal ${proposalId} is already ${current.status}`);
+        }
+        checkExpected(current, options.expectedSha256);
+        const tally = advisoryTally(libraryPath, current);
+        record(audit, rejectedBy, "skill.reject", current.source_agent, `proposal=${proposalId} name=${current.name} ` +
+            `content_sha256=${current.content_sha256} channel=${channel} ${tallyText(tally)}`);
+        current.status = STATUS_REJECTED;
+        const decision = { by: rejectedBy, at: nowIso(), channel };
+        if (reason)
+            decision.reason = reason;
+        if (tally !== null) {
+            decision.advisory = Object.fromEntries(BALLOT_OPTIONS.map((opt) => [opt, tally[opt].votes]));
+        }
+        current.decision = decision;
+        writeRecord(folder, current);
+        return current;
+    });
+    closeBallot(libraryPath, proposal, "rejected", "rejected");
+    return proposal;
+}
+// -- retirement and rollback ----------------------------------------------------
+/**
+ * Retire the live version (`valid_to`, default today). Versions are kept.
+ *
+ * A retired skill leaves the default index and `get_skill` without a version;
+ * every version stays fetchable by number, and {@link rollbackSharedSkill}
+ * brings one back.
+ */
+export function retireSharedSkill(libraryPath, name, options) {
+    const { retiredBy, channel, audit } = options;
+    const live = getSkillRow(libraryPath, validateSkillName(name));
+    const when = options.validTo || today();
+    record(audit, retiredBy, "skill.retire", live.sourceAgent, `name=${name} version=${live.version} valid_to=${when} channel=${channel}`);
+    try {
+        return setSkillValidTo(libraryPath, name, when, { expectedVersion: live.version });
+    }
+    catch (exc) {
+        recordFailure(audit, retiredBy, "skill.retire", live.sourceAgent, exc);
+        throw exc;
+    }
+}
+/**
+ * Make version `toVersion`'s content current again, as a NEW version.
+ *
+ * History is never rewritten: rolling back to version 2 of a skill at version 4
+ * writes version 5 with version 2's files (re-hashed before they are used), so
+ * every version stays fetchable. Rolling back a retired skill also lifts the
+ * retirement; rolling back to the live version of a retired skill only lifts it.
+ */
+export function rollbackSharedSkill(libraryPath, name, toVersion, options) {
+    const { promotedBy, channel, audit } = options;
+    validateSkillName(name);
+    const live = getSkillRow(libraryPath, name);
+    const { row: targetRow, content } = readSharedSkill(libraryPath, name, toVersion);
+    if (computeContentSha256(content.files) !== targetRow.contentSha256) {
+        throw new ProposalDigestMismatchError(`stored files of '${name}' v${toVersion} do not match their content_sha256`);
+    }
+    const retired = live.validTo !== null;
+    if (toVersion === live.version && !retired) {
+        throw new SkillProposalError(`'${name}' is already at version ${toVersion}`);
+    }
+    record(audit, promotedBy, "skill.rollback", targetRow.sourceAgent, `name=${name} from_version=${live.version} to_version=${toVersion} ` +
+        `content_sha256=${targetRow.contentSha256} channel=${channel}`);
+    try {
+        let changed = false;
+        let row = live;
+        if (toVersion !== live.version) {
+            const result = promoteSkill(libraryPath, content, {
+                sourceAgent: targetRow.sourceAgent,
+                promotedBy,
+                name,
+                expectedVersion: live.version,
+                visibility: targetRow.visibility,
+                proposalId: targetRow.proposalId,
+            });
+            changed = result.changed;
+            row = result.row;
+        }
+        let restored = false;
+        if (row.validTo !== null) {
+            row = setSkillValidTo(libraryPath, name, null, { expectedVersion: row.version });
+            restored = true;
+        }
+        return { row, changed, restored };
+    }
+    catch (exc) {
+        recordFailure(audit, promotedBy, "skill.rollback", targetRow.sourceAgent, exc);
+        throw exc;
+    }
+}