@getbourdon/participants 0.5.5 → 0.6.0

package/dist/skill-index.js

@@ -0,0 +1,470 @@
+// SPDX-License-Identifier: BUSL-1.1
+/**
+ * Reader-side skill folder scan (plan 005). Port of the parts of the engine's
+ * `core/skill_index.py` a participant needs to advertise a local skill: the
+ * text-only content rules, the no-follow folder walk, front-matter parsing,
+ * the `content_sha256` framing and `scan_local_skill` (skip and flag).
+ *
+ * `readSkillFolder` is the promotion-side twin of `scanLocalSkill`: it refuses
+ * a folder that breaks any rule instead of skipping files. The library-level
+ * shared store (index rows, versions, promotion) is in `skill-store.ts`. Both
+ * use the same limits and name rule, so a hash computed here compares
+ * directly with a shared skill's.
+ *
+ * Rules a v1 shared skill must meet (anything else is skipped and flagged):
+ *  - `SKILL.md` plus markdown, plain text and template files only;
+ *  - no links, no hidden entries, bounded depth and path length, no paths that
+ *    differ only in case;
+ *  - UTF-8 text without NUL bytes, no interpreter line, no credential-like text;
+ *  - per-file and total size caps, at most {@link MAX_REFERENCE_FILES} reference files.
+ */
+import { createHash } from "node:crypto";
+import { lstatSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { l5Schema } from "@getbourdon/l5";
+import { containsSecret } from "@getbourdon/redaction";
+import { parse as yamlParse } from "yaml";
+export const SKILL_BODY_NAME = "SKILL.md";
+/** Reference-file types a v1 shared skill may carry: markdown, plain text and templates. */
+export const TEXT_FILE_SUFFIXES = new Set([
+    ".md",
+    ".markdown",
+    ".txt",
+    ".tmpl",
+    ".tpl",
+    ".template",
+    ".j2",
+    ".jinja",
+    ".jinja2",
+    ".mustache",
+]);
+export const MAX_SKILL_BODY_BYTES = 128 * 1024;
+export const MAX_REFERENCE_FILE_BYTES = 256 * 1024;
+export const MAX_REFERENCE_FILES = 64;
+export const MAX_SKILL_TOTAL_BYTES = 2 * 1024 * 1024;
+const MAX_PATH_DEPTH = 8;
+const MAX_REL_PATH_CHARS = 255;
+const FRONT_MATTER_FENCE = "---";
+/**
+ * Why a reader left a file out of an advertised skill. `limit` means the
+ * file-count or total-size cap was reached; every other code names the content
+ * rule the file breaks.
+ */
+export const SKIP_REASONS = new Set([
+    "credential",
+    "duplicate_case",
+    "file_type",
+    "hidden",
+    "limit",
+    "link",
+    "not_text",
+    "path",
+    "script",
+    "too_large",
+    "unreadable",
+]);
+// The skill name and description rules, read from the L5 schema's SkillRef
+// (the same values as the shared skill index schema's).
+function skillRefProp(name) {
+    const skillRef = l5Schema.$defs.SkillRef;
+    const found = skillRef?.properties?.[name];
+    if (found === undefined)
+        throw new Error(`L5 schema: SkillRef is missing ${name}`);
+    return found;
+}
+const NAME_PATTERN = String(skillRefProp("name").pattern);
+const NAME_RE = new RegExp(`^(?:${NAME_PATTERN})$`);
+const NAME_MAX = Number(skillRefProp("name").maxLength);
+const DESCRIPTION_MAX = Number(skillRefProp("description").maxLength);
+/** Longest skill name, in code points. */
+export const SKILL_NAME_MAX = NAME_MAX;
+/** Longest front-matter description, in code points. */
+export const SKILL_DESCRIPTION_MAX = DESCRIPTION_MAX;
+// -- errors -------------------------------------------------------------------
+/**
+ * A skill folder cannot be advertised (or shared) as it stands. `problems`
+ * lists every offending path with the reason; content is never echoed back.
+ */
+export class SkillContentError extends Error {
+    problems;
+    constructor(problems) {
+        super(`skill folder cannot be shared: ${problems.join("; ")}`);
+        this.name = "SkillContentError";
+        this.problems = [...problems];
+    }
+}
+// -- Python string semantics ----------------------------------------------------
+// str.isspace() characters, for str.strip().
+const PY_SPACE = "\\t\\n\\v\\f\\r\\x1c-\\x1f \\x85\\xa0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000";
+const PY_STRIP_RE = new RegExp(`^[${PY_SPACE}]+|[${PY_SPACE}]+$`, "g");
+// str.splitlines() boundaries.
+// eslint-disable-next-line no-control-regex
+const PY_LINE_BREAK_RE = /\r\n|[\n\r\v\f\x1c\x1d\x1e\x85\u2028\u2029]/;
+/** Python `str.strip()` with no argument. */
+export function pyStrip(text) {
+    return text.replace(PY_STRIP_RE, "");
+}
+/** Length in code points, as Python's `len(str)`. */
+export function codePointLength(text) {
+    let n = 0;
+    for (const _ of text)
+        n += 1;
+    return n;
+}
+/** The first `limit` code points, as Python's `text[:limit]`. */
+export function codePointSlice(text, limit) {
+    if (text.length <= limit)
+        return text;
+    return Array.from(text).slice(0, limit).join("");
+}
+/** Approximates Python `str.casefold()` (full case folding, e.g. ß -> ss). */
+function casefold(text) {
+    return text.toUpperCase().toLowerCase();
+}
+/** Code-point order (Python's str order), via the UTF-8 bytes. */
+export function compareUtf8(a, b) {
+    return Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
+}
+const UTF8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+function decodeUtf8(data) {
+    try {
+        return UTF8.decode(data);
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether `path` is a symbolic link (on Windows, a junction or symlink reparse point). */
+export function isPathLinkOrReparse(path, stats) {
+    const inspected = stats ?? lstatSync(path);
+    return inspected.isSymbolicLink();
+}
+/** Why `value` is not a valid skill name (`label` names the field), or null. */
+export function skillNameError(value, label = "name") {
+    if (typeof value !== "string")
+        return `${label} must be a string`;
+    const length = codePointLength(value);
+    if (length < 1 || length > NAME_MAX)
+        return `${label} must be 1..${NAME_MAX} characters`;
+    if (!NAME_RE.test(value))
+        return `${label} must match ${NAME_PATTERN}`;
+    return null;
+}
+/** Extract `name` and `description` from a `SKILL.md` body. Throws {@link SkillContentError}. */
+export function parseFrontMatter(body) {
+    let text;
+    if (typeof body === "string") {
+        text = body;
+    }
+    else {
+        const decoded = decodeUtf8(body);
+        if (decoded === null)
+            throw new SkillContentError([`${SKILL_BODY_NAME}: not UTF-8 text`]);
+        text = decoded;
+    }
+    if (text.startsWith("\ufeff"))
+        text = text.slice(1);
+    const lines = text.split(PY_LINE_BREAK_RE);
+    if (lines.length === 0 || pyStrip(lines[0] ?? "") !== FRONT_MATTER_FENCE) {
+        throw new SkillContentError([`${SKILL_BODY_NAME}: missing YAML front matter`]);
+    }
+    let end = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (pyStrip(lines[i] ?? "") === FRONT_MATTER_FENCE) {
+            end = i;
+            break;
+        }
+    }
+    if (end === -1)
+        throw new SkillContentError([`${SKILL_BODY_NAME}: front matter is not closed`]);
+    let meta;
+    try {
+        meta = yamlParse(lines.slice(1, end).join("\n"), {
+            version: "1.1",
+            uniqueKeys: false,
+            logLevel: "silent",
+        });
+    }
+    catch {
+        throw new SkillContentError([`${SKILL_BODY_NAME}: front matter is not valid YAML`]);
+    }
+    if (meta === null || typeof meta !== "object" || Array.isArray(meta) || meta instanceof Date) {
+        throw new SkillContentError([`${SKILL_BODY_NAME}: front matter must be a mapping`]);
+    }
+    const record = meta;
+    const problems = [];
+    const name = record.name;
+    const error = skillNameError(name);
+    if (error !== null)
+        problems.push(`${SKILL_BODY_NAME}: front matter ${error}`);
+    let description = record.description;
+    if (typeof description === "string")
+        description = pyStrip(description);
+    if (typeof description !== "string" ||
+        codePointLength(description) < 1 ||
+        codePointLength(description) > DESCRIPTION_MAX) {
+        problems.push(`${SKILL_BODY_NAME}: front matter description must be 1..${DESCRIPTION_MAX} characters`);
+    }
+    if (problems.length > 0)
+        throw new SkillContentError(problems);
+    return { name: name, description: description };
+}
+// -- content hash -------------------------------------------------------------
+/**
+ * Hash a skill's files as the schema's `content_sha256` defines: entries sorted
+ * by the UTF-8 bytes of their POSIX path relative to the skill folder, each
+ * framed as `path \0 len(bytes) \0 bytes`.
+ */
+export function computeContentSha256(entries) {
+    const digest = createHash("sha256");
+    const sorted = [...entries].sort(([a], [b]) => compareUtf8(a, b));
+    for (const [path, data] of sorted) {
+        digest.update(Buffer.from(path, "utf8"));
+        digest.update(Buffer.from([0]));
+        digest.update(Buffer.from(String(data.length), "ascii"));
+        digest.update(Buffer.from([0]));
+        digest.update(data);
+    }
+    return digest.digest("hex");
+}
+function textProblems(data) {
+    const text = decodeUtf8(data);
+    if (text === null)
+        return [["not_text", "not UTF-8 text"]];
+    if (text.includes("\x00"))
+        return [["not_text", "contains NUL bytes"]];
+    const found = [];
+    const unprefixed = text.startsWith("\ufeff") ? text.slice(1) : text;
+    if (unprefixed.startsWith("#!")) {
+        found.push(["script", "starts with an interpreter line; scripts are not shared"]);
+    }
+    if (containsSecret(text))
+        found.push(["credential", "contains credential-like text"]);
+    return found;
+}
+/**
+ * List a skill folder's regular files without following any link. `found` holds
+ * every regular file that passed the structural rules; `problems` names every
+ * entry that did not.
+ */
+function walkSkillFolder(root) {
+    const problems = [];
+    const found = [];
+    const seenCasefold = new Map();
+    const walk = (directory, parts) => {
+        let entries;
+        try {
+            entries = readdirSync(directory, { withFileTypes: true });
+        }
+        catch {
+            problems.push({ rel: parts.join("/") || ".", code: "unreadable", message: "cannot be listed" });
+            return;
+        }
+        entries.sort((a, b) => compareUtf8(a.name, b.name));
+        for (const entry of entries) {
+            const relParts = [...parts, entry.name];
+            const rel = relParts.join("/");
+            const path = join(directory, entry.name);
+            let info;
+            try {
+                info = lstatSync(path);
+            }
+            catch {
+                problems.push({ rel, code: "unreadable", message: "cannot be read" });
+                continue;
+            }
+            if (isPathLinkOrReparse(path, info)) {
+                problems.push({ rel, code: "link", message: "links are not shared" });
+                continue;
+            }
+            if (entry.name.startsWith(".")) {
+                problems.push({ rel, code: "hidden", message: "hidden files and folders are not shared" });
+                continue;
+            }
+            if (relParts.length > MAX_PATH_DEPTH || codePointLength(rel) > MAX_REL_PATH_CHARS) {
+                problems.push({ rel, code: "path", message: "path is too deep or too long" });
+                continue;
+            }
+            const folded = casefold(rel);
+            const previous = seenCasefold.get(folded);
+            if (previous !== undefined) {
+                problems.push({
+                    rel,
+                    code: "duplicate_case",
+                    message: `differs only in case from ${previous}`,
+                });
+                continue;
+            }
+            seenCasefold.set(folded, rel);
+            if (info.isDirectory()) {
+                walk(path, relParts);
+            }
+            else if (info.isFile()) {
+                found.push({ rel, path, size: info.size });
+            }
+            else {
+                problems.push({ rel, code: "file_type", message: "not a regular file" });
+            }
+        }
+    };
+    walk(root, []);
+    return { found, problems };
+}
+/** Python `PurePosixPath(rel).suffix`. */
+function posixSuffix(rel) {
+    const name = rel.slice(rel.lastIndexOf("/") + 1);
+    const i = name.lastIndexOf(".");
+    return i > 0 && i < name.length - 1 ? name.slice(i) : "";
+}
+/**
+ * Read one listed file under the type and size rules, then check its text.
+ * `data` is null when the file is refused before reading.
+ */
+function readCandidate(rel, path, size) {
+    const isBody = rel === SKILL_BODY_NAME;
+    if (!isBody && !TEXT_FILE_SUFFIXES.has(posixSuffix(rel).toLowerCase())) {
+        return {
+            data: null,
+            problems: [
+                ["file_type", "file type is not shared in v1 (markdown, text and templates only)"],
+            ],
+        };
+    }
+    const cap = isBody ? MAX_SKILL_BODY_BYTES : MAX_REFERENCE_FILE_BYTES;
+    if (size > cap) {
+        return { data: null, problems: [["too_large", `${size} bytes exceeds the ${cap}-byte limit`]] };
+    }
+    let data;
+    try {
+        data = readFileSync(path);
+    }
+    catch {
+        return { data: null, problems: [["unreadable", "cannot be read"]] };
+    }
+    if (data.length > cap) {
+        return {
+            data: null,
+            problems: [["too_large", `${data.length} bytes exceeds the ${cap}-byte limit`]],
+        };
+    }
+    return { data, problems: textProblems(data) };
+}
+function isRealDirectory(path) {
+    let info;
+    try {
+        info = lstatSync(path);
+    }
+    catch {
+        return false;
+    }
+    return !isPathLinkOrReparse(path, info) && info.isDirectory();
+}
+/**
+ * Scan one local skill folder for discovery: skip and flag, don't refuse.
+ *
+ * A disallowed reference file (a script, a binary, a link, a hidden file,
+ * credential-like text) is left out and reported in `skipped` instead of making
+ * the whole skill disappear. Only a `SKILL.md` that is missing, unreadable or
+ * itself breaks a content rule throws {@link SkillContentError}, because then
+ * there is nothing safe to advertise. Nothing is followed through a link and
+ * nothing is modified.
+ */
+export function scanLocalSkill(folder) {
+    if (!isRealDirectory(folder)) {
+        throw new SkillContentError([`${basename(folder) || folder}: not a real directory`]);
+    }
+    const { found, problems } = walkSkillFolder(folder);
+    const skipped = problems.map((p) => ({ path: p.rel, reason: p.code }));
+    const bodyEntry = found.find((item) => item.rel === SKILL_BODY_NAME);
+    if (bodyEntry === undefined)
+        throw new SkillContentError([`${SKILL_BODY_NAME}: missing`]);
+    const body = readCandidate(bodyEntry.rel, bodyEntry.path, bodyEntry.size);
+    if (body.data === null || body.problems.length > 0) {
+        throw new SkillContentError(body.problems.map(([, message]) => `${SKILL_BODY_NAME}: ${message}`));
+    }
+    const frontMatter = parseFrontMatter(body.data);
+    const files = [[SKILL_BODY_NAME, body.data]];
+    let total = body.data.length;
+    for (const { rel, path, size } of found) {
+        if (rel === SKILL_BODY_NAME)
+            continue;
+        if (files.length - 1 >= MAX_REFERENCE_FILES) {
+            skipped.push({ path: rel, reason: "limit" });
+            continue;
+        }
+        const candidate = readCandidate(rel, path, size);
+        if (candidate.data === null || candidate.problems.length > 0) {
+            skipped.push({ path: rel, reason: candidate.problems[0]?.[0] ?? "unreadable" });
+            continue;
+        }
+        if (total + candidate.data.length > MAX_SKILL_TOTAL_BYTES) {
+            skipped.push({ path: rel, reason: "limit" });
+            continue;
+        }
+        total += candidate.data.length;
+        files.push([rel, candidate.data]);
+    }
+    files.sort(([a], [b]) => compareUtf8(a, b));
+    skipped.sort((a, b) => compareUtf8(a.path, b.path));
+    return { frontMatter, files, skipped, contentSha256: computeContentSha256(files) };
+}
+/** The `SKILL.md` bytes of `content`. */
+export function skillContentBody(content) {
+    const body = content.files.find(([rel]) => rel === SKILL_BODY_NAME);
+    if (body === undefined)
+        throw new SkillContentError([`${SKILL_BODY_NAME}: missing`]);
+    return body[1];
+}
+/**
+ * Read a skill folder and enforce every v1 content rule (the oracle's
+ * `read_skill_folder`). Throws {@link SkillContentError} listing every problem
+ * found. The folder is read in place and never modified; links are reported,
+ * never followed.
+ */
+export function readSkillFolder(folder) {
+    if (!isRealDirectory(folder)) {
+        throw new SkillContentError([`${basename(folder) || folder}: not a real directory`]);
+    }
+    const { found, problems: walkProblems } = walkSkillFolder(folder);
+    const problems = walkProblems.map((p) => `${p.rel}: ${p.message}`);
+    if (!found.some((item) => item.rel === SKILL_BODY_NAME)) {
+        problems.push(`${SKILL_BODY_NAME}: missing`);
+    }
+    const references = found.filter((item) => item.rel !== SKILL_BODY_NAME);
+    if (references.length > MAX_REFERENCE_FILES) {
+        problems.push(`${references.length} reference files exceed the limit of ${MAX_REFERENCE_FILES}`);
+    }
+    let total = 0;
+    const files = [];
+    for (const { rel, path, size } of found) {
+        const candidate = readCandidate(rel, path, size);
+        for (const [, message] of candidate.problems)
+            problems.push(`${rel}: ${message}`);
+        if (candidate.data === null)
+            continue;
+        total += candidate.data.length;
+        files.push([rel, candidate.data]);
+    }
+    if (total > MAX_SKILL_TOTAL_BYTES) {
+        problems.push(`skill totals ${total} bytes, over the ${MAX_SKILL_TOTAL_BYTES}-byte limit`);
+    }
+    let frontMatter = null;
+    const body = files.find(([rel]) => rel === SKILL_BODY_NAME)?.[1];
+    if (body !== undefined) {
+        try {
+            frontMatter = parseFrontMatter(body);
+        }
+        catch (err) {
+            if (!(err instanceof SkillContentError))
+                throw err;
+            // A body that is not UTF-8 was already reported by the text check.
+            if (decodeUtf8(body) !== null)
+                problems.push(...err.problems);
+        }
+    }
+    if (problems.length > 0 || frontMatter === null) {
+        throw new SkillContentError(problems.length > 0 ? problems : [`${SKILL_BODY_NAME}: unreadable`]);
+    }
+    files.sort(([a], [b]) => compareUtf8(a, b));
+    return { frontMatter, files };
+}

package/dist/skill-proposals.d.ts

@@ -0,0 +1,212 @@
+/**
+ * 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 { type FederationAudit } from "@getbourdon/federation";
+import { type SkillContent } from "./skill-index.js";
+import { type SkillIndexRow, SkillIndexError } from "./skill-store.js";
+type Dict = Record<string, unknown>;
+export declare const PROPOSALS_DIRNAME = ".skill-proposals";
+export declare const RECORD_NAME = "proposal.yaml";
+export declare const CONTENT_DIRNAME = "content";
+export declare const STATUS_PENDING = "pending";
+export declare const STATUS_APPROVED = "approved";
+export declare const STATUS_REJECTED = "rejected";
+export declare const PROPOSER_TRUSTED = "trusted";
+export declare const PROPOSER_QUARANTINED = "quarantined";
+/** The advisory ballot's options. A ballot only informs the person deciding. */
+export declare const BALLOT_OPTIONS: readonly ["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 declare const SKILL_PROPOSAL_LIMITS: {
+    maxPendingPerProposer: number;
+    maxReasonChars: number;
+};
+/** Base class for refusals raised by the proposal gate. */
+export declare class SkillProposalError extends SkillIndexError {
+    constructor(message: string);
+}
+/** No proposal with that id. */
+export declare class ProposalNotFoundError extends SkillProposalError {
+    constructor(message: string);
+}
+/** The proposal is not pending (it was already decided). */
+export declare class ProposalStateError extends SkillProposalError {
+    constructor(message: string);
+}
+/** The snapshot no longer hashes to what was proposed, or to what the approver saw. */
+export declare class ProposalDigestMismatchError extends SkillProposalError {
+    constructor(message: string);
+}
+/** One proposal record (`proposal.yaml`). Field names follow the on-disk keys. */
+export interface SkillProposal {
+    proposal_id: string;
+    name: string;
+    description: string;
+    content_sha256: string;
+    source_agent: string;
+    proposed_by: string;
+    proposer_tier: string;
+    created_at: string;
+    path_hint: string;
+    scope: string;
+    visibility: string;
+    project: string | null;
+    origin: Dict | null;
+    files: Dict[];
+    ballot: boolean;
+    status: string;
+    decision: Dict | null;
+}
+/** The record as written: the engine's key order, absent optionals omitted. */
+export declare function proposalToDict(proposal: SkillProposal): Dict;
+/** Parse a record; throws {@link SkillProposalError} on anything malformed. */
+export declare function proposalFromDict(data: unknown): SkillProposal;
+/** The row a listing shows: no file list, no decision detail. */
+export declare function proposalSummary(proposal: SkillProposal): Dict;
+export declare function isProposalId(value: unknown): value is string;
+/** `<library>/.skill-proposals`. */
+export declare function proposalsRoot(libraryPath: string): string;
+/** Read one proposal; throws {@link ProposalNotFoundError} or {@link SkillProposalError}. */
+export declare function loadProposal(libraryPath: string, proposalId: string): SkillProposal;
+/** Every readable proposal (optionally of one `status`), oldest first. */
+export declare function listProposals(libraryPath: string, status?: string | null): SkillProposal[];
+export interface CreateProposalOptions {
+    /** The advertised SkillRef, as it sits in the agent's manifest. */
+    ref: Readonly<Dict>;
+    sourceAgent: string;
+    proposedBy: string;
+    proposerTier: string;
+    createdAt?: string | null;
+}
+/**
+ * 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 declare function createProposal(libraryPath: string, content: SkillContent, options: CreateProposalOptions): {
+    proposal: SkillProposal;
+    created: boolean;
+};
+/** The snapshot, re-checked against every content rule and its recorded hash. */
+export declare function readProposalContent(libraryPath: string, proposal: SkillProposal): SkillContent;
+/** The shared skill already using `name`, if any (retired included). */
+export declare function collisionFor(libraryPath: string, name: string): SkillIndexRow | null;
+/**
+ * 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 declare function openAdvisoryBallot(libraryPath: string, proposal: SkillProposal): boolean;
+export type AdvisoryTally = Record<(typeof BALLOT_OPTIONS)[number], {
+    votes: number;
+    voters: string[];
+}>;
+/** Vote counts and voters on the proposal's ballot; null without one. */
+export declare function advisoryTally(libraryPath: string, proposal: SkillProposal): AdvisoryTally | null;
+export interface ApprovalResult {
+    proposal: SkillProposal;
+    row: SkillIndexRow;
+    changed: boolean;
+    renamedFrom: string | null;
+    advisory: AdvisoryTally | null;
+}
+export interface ApproveProposalOptions {
+    approvedBy: string;
+    channel: string;
+    /** At least 8 hex characters: pins the decision to the bytes reviewed. */
+    expectedSha256?: string | null;
+    name?: string | null;
+    update?: boolean;
+    visibility?: string | null;
+    audit?: FederationAudit | null;
+}
+/**
+ * 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 declare function approveProposal(libraryPath: string, proposalId: string, options: ApproveProposalOptions): ApprovalResult;
+export interface RejectProposalOptions {
+    rejectedBy: string;
+    channel: string;
+    reason?: string;
+    expectedSha256?: string | null;
+    audit?: FederationAudit | null;
+}
+/** Mark a pending proposal rejected. The snapshot is kept for the record. */
+export declare function rejectProposal(libraryPath: string, proposalId: string, options: RejectProposalOptions): SkillProposal;
+/**
+ * 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 declare function retireSharedSkill(libraryPath: string, name: string, options: {
+    retiredBy: string;
+    channel: string;
+    validTo?: string | null;
+    audit?: FederationAudit | null;
+}): SkillIndexRow;
+export interface RollbackResult {
+    row: SkillIndexRow;
+    /** True when a new version was written. */
+    changed: boolean;
+    /** True when a retirement was lifted. */
+    restored: boolean;
+}
+/**
+ * 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 declare function rollbackSharedSkill(libraryPath: string, name: string, toVersion: number, options: {
+    promotedBy: string;
+    channel: string;
+    audit?: FederationAudit | null;
+}): RollbackResult;
+export {};