@getbourdon/participants 0.5.5 → 0.6.0

package/dist/skill-store.js

@@ -0,0 +1,750 @@
+// SPDX-License-Identifier: BUSL-1.1
+/**
+ * Shared skill store: the library-level home of federated procedural memory.
+ * Port of the store half of the engine's `core/skill_index.py` (plan 005,
+ * phase 1); the content rules it relies on are in `skill-index.ts`.
+ *
+ * Layout (one folder per shared skill, beside the per-agent manifests):
+ *
+ *     <library>/skills/<name>/
+ *         SKILL.md          verbatim body, as promoted
+ *         skill.yaml        index row (the skill index schema)
+ *         files/...         reference files, verbatim, text-only, size-capped
+ *         .versions/<n>/    the same three entries for each replaced version
+ *
+ * Load-bearing rules:
+ *
+ *  - **Org-tier write semantics.** The store is readable by every caller allowed
+ *    to read the federation and writable only through {@link promoteSkill}. The
+ *    ordinary federation write path never touches `<library>/skills`.
+ *  - **One namespace, rename at promotion.** A shared name belongs to one skill.
+ *    Promoting under a taken name throws {@link SkillNameCollisionError} with a
+ *    free suggestion, unless the caller updates that skill by passing the
+ *    current version as `expectedVersion` (also the compare-and-swap that stops
+ *    two promotions from silently overwriting each other). A renamed skill keeps
+ *    its front-matter name in `source_name`.
+ *  - **Fail closed on reads.** A row that does not validate is not served.
+ */
+import { randomBytes } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { WRITE_POLICY_READ_ONLY, withManifestLock } from "@getbourdon/federation";
+import { parse as yamlParse, stringify as yamlStringify } from "yaml";
+import { SKILL_BODY_NAME, SKILL_DESCRIPTION_MAX, codePointLength, compareUtf8, computeContentSha256, isPathLinkOrReparse, parseFrontMatter, skillContentBody, skillNameError, } from "./skill-index.js";
+export const SKILL_INDEX_SPEC_VERSION = "0.1";
+export const SKILLS_DIRNAME = "skills";
+export const INDEX_ROW_NAME = "skill.yaml";
+export const FILES_DIRNAME = "files";
+export const VERSIONS_DIRNAME = ".versions";
+const STAGING_PREFIX = ".staging-";
+const PROMOTION_LOCK_STEM = ".promotion";
+/** The shared store behaves as org-tier memory: readable by every federation
+ * reader, writable by no one through the ordinary write API. */
+export const SKILL_STORE_WRITE_POLICY = WRITE_POLICY_READ_ONLY;
+/** Promotion widens nothing unless the promoting caller asks it to. */
+export const DEFAULT_SKILL_VISIBILITY = "private";
+export const MAX_INDEX_ROW_BYTES = 16 * 1024;
+// The skill index schema's rules (spec/skill_index_schema.json in the engine).
+const ROW_FIELDS = new Set([
+    "spec_version",
+    "name",
+    "source_name",
+    "description",
+    "version",
+    "content_sha256",
+    "source_agent",
+    "promoted_by",
+    "promoted_at",
+    "proposal_id",
+    "visibility",
+    "valid_to",
+    "supersedes",
+]);
+const REQUIRED_FIELDS = [
+    "spec_version",
+    "name",
+    "description",
+    "version",
+    "content_sha256",
+    "source_agent",
+    "promoted_by",
+    "promoted_at",
+    "visibility",
+];
+const AGENT_ID_PATTERN = "^[a-z0-9][a-z0-9_-]*$";
+const AGENT_ID_RE = new RegExp(AGENT_ID_PATTERN);
+const AGENT_ID_MAX = 64;
+const PROPOSAL_ID_MAX = 128;
+const PROMOTED_AT_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(\.\d+)?(Z|([+-])(\d{2}):(\d{2}))$/;
+const VISIBILITIES = new Set(["public", "team", "private"]);
+const DATE_RE = /^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/;
+const SHA256_RE = /^[0-9a-f]{64}$/;
+const NAME_LIMIT = 64;
+// -- errors -------------------------------------------------------------------
+/** Base class for every refusal the skill store raises. */
+export class SkillIndexError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SkillIndexError";
+    }
+}
+/** An index row does not conform to the skill index schema. */
+export class InvalidSkillRowError extends SkillIndexError {
+    errors;
+    constructor(errors) {
+        super(`invalid skill index row: ${errors.join("; ")}`);
+        this.name = "InvalidSkillRowError";
+        this.errors = [...errors];
+    }
+}
+/** The shared name is already taken and the caller did not ask to update it. */
+export class SkillNameCollisionError extends SkillIndexError {
+    skillName;
+    existingVersion;
+    suggestedName;
+    constructor(name, existingVersion, suggestedName) {
+        const hint = suggestedName
+            ? `; promote under another name (for example '${suggestedName}')`
+            : "; promote under another name";
+        super(`shared skill '${name}' already exists at version ${existingVersion}` +
+            `${hint}, or pass expected_version=${existingVersion} to replace it`);
+        this.name = "SkillNameCollisionError";
+        this.skillName = name;
+        this.existingVersion = existingVersion;
+        this.suggestedName = suggestedName;
+    }
+}
+/** `expectedVersion` does not match what is in the store. */
+export class SkillVersionConflictError extends SkillIndexError {
+    skillName;
+    expected;
+    current;
+    constructor(name, expected, current) {
+        super(`shared skill '${name}': expected version ${expected === null ? "None" : expected}, ` +
+            `store has ${current !== null ? current : "no such skill"}`);
+        this.name = "SkillVersionConflictError";
+        this.skillName = name;
+        this.expected = expected;
+        this.current = current;
+    }
+}
+/** No shared skill (or no such version of it) exists. */
+export class SkillNotFoundError extends SkillIndexError {
+    constructor(message) {
+        super(message);
+        this.name = "SkillNotFoundError";
+    }
+}
+// -- validation -----------------------------------------------------------------
+/** Return `name` if it is a valid shared skill name, else throw {@link SkillIndexError}. */
+export function validateSkillName(name) {
+    const error = skillNameError(name);
+    if (error !== null)
+        throw new SkillIndexError(error);
+    return name;
+}
+function isInt(value) {
+    return typeof value === "number" && Number.isInteger(value);
+}
+function isDict(value) {
+    return (value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date));
+}
+function daysInMonth(year, month) {
+    return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+function validDate(value) {
+    if (typeof value !== "string")
+        return false;
+    const match = DATE_RE.exec(value);
+    if (match === null)
+        return false;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    return year >= 1 && Number(match[3]) <= daysInMonth(year, month);
+}
+function validTimestamp(value) {
+    if (typeof value !== "string")
+        return false;
+    const match = PROMOTED_AT_RE.exec(value);
+    if (match === null)
+        return false;
+    const [, y, mo, d, h, mi, s] = match.map(Number);
+    if (y < 1 || mo < 1 || mo > 12 || d < 1 || d > daysInMonth(y, mo))
+        return false;
+    if (h > 23 || mi > 59 || s > 59)
+        return false;
+    if (match[8] !== "Z" && (Number(match[10]) > 23 || Number(match[11]) > 59))
+        return false;
+    return true;
+}
+/**
+ * Check a parsed `skill.yaml` mapping against the schema's rules. Returns every
+ * violation found (empty means valid), in the oracle's order and wording.
+ */
+export function validateIndexRow(row) {
+    if (!isDict(row))
+        return ["row must be a mapping"];
+    const errors = [];
+    const keys = Object.keys(row);
+    const has = (key) => Object.hasOwn(row, key);
+    const unknown = keys.filter((key) => !ROW_FIELDS.has(key)).sort(compareUtf8);
+    if (unknown.length > 0)
+        errors.push(`unknown fields: ${unknown.join(", ")}`);
+    const missing = REQUIRED_FIELDS.filter((key) => !has(key));
+    if (missing.length > 0)
+        errors.push(`missing required fields: ${missing.join(", ")}`);
+    if (has("spec_version") && row.spec_version !== SKILL_INDEX_SPEC_VERSION) {
+        errors.push(`spec_version must be '${SKILL_INDEX_SPEC_VERSION}'`);
+    }
+    if (has("name")) {
+        const err = skillNameError(row.name);
+        if (err !== null)
+            errors.push(err);
+    }
+    if (has("source_name")) {
+        const err = skillNameError(row.source_name, "source_name");
+        if (err !== null)
+            errors.push(err);
+    }
+    const description = row.description;
+    if (has("description") &&
+        (typeof description !== "string" ||
+            codePointLength(description) < 1 ||
+            codePointLength(description) > SKILL_DESCRIPTION_MAX)) {
+        errors.push(`description must be a string of 1..${SKILL_DESCRIPTION_MAX} characters`);
+    }
+    const version = row.version;
+    if (has("version") && (!isInt(version) || version < 1)) {
+        errors.push("version must be an integer >= 1");
+    }
+    const digest = row.content_sha256;
+    if (has("content_sha256") && (typeof digest !== "string" || !SHA256_RE.test(digest))) {
+        errors.push("content_sha256 must be 64 lowercase hex characters");
+    }
+    for (const key of ["source_agent", "promoted_by"]) {
+        const value = row[key];
+        if (has(key) &&
+            (typeof value !== "string" ||
+                codePointLength(value) < 1 ||
+                codePointLength(value) > AGENT_ID_MAX ||
+                !AGENT_ID_RE.test(value))) {
+            errors.push(`${key} must be an agent id matching ${AGENT_ID_PATTERN}`);
+        }
+    }
+    if (has("promoted_at") && !validTimestamp(row.promoted_at)) {
+        errors.push("promoted_at must be an ISO 8601 timestamp with a UTC offset");
+    }
+    const proposalId = row.proposal_id;
+    if (has("proposal_id") &&
+        (typeof proposalId !== "string" ||
+            codePointLength(proposalId) < 1 ||
+            codePointLength(proposalId) > PROPOSAL_ID_MAX)) {
+        errors.push(`proposal_id must be a string of 1..${PROPOSAL_ID_MAX} characters`);
+    }
+    if (has("visibility") && !VISIBILITIES.has(row.visibility)) {
+        errors.push("visibility must be one of private, public, team");
+    }
+    if (has("valid_to") && !validDate(row.valid_to)) {
+        errors.push("valid_to must be an ISO 8601 date (YYYY-MM-DD)");
+    }
+    const supersedes = row.supersedes;
+    if (has("supersedes")) {
+        if (!isInt(supersedes) || supersedes < 1) {
+            errors.push("supersedes must be an integer >= 1");
+        }
+        else if (isInt(version) && supersedes !== version - 1) {
+            errors.push("supersedes must equal version - 1");
+        }
+    }
+    else if (isInt(version) && version > 1) {
+        errors.push("supersedes is required when version > 1");
+    }
+    return errors;
+}
+// -- the index row --------------------------------------------------------------
+/** Today's date in UTC, `YYYY-MM-DD`. */
+function utcToday() {
+    return new Date().toISOString().slice(0, 10);
+}
+/** One validated `skill.yaml`. */
+export class SkillIndexRow {
+    specVersion;
+    name;
+    sourceName;
+    description;
+    version;
+    contentSha256;
+    sourceAgent;
+    promotedBy;
+    promotedAt;
+    proposalId;
+    visibility;
+    validTo;
+    supersedes;
+    constructor(data) {
+        this.specVersion = data.spec_version;
+        this.name = data.name;
+        this.sourceName = data.source_name ?? null;
+        this.description = data.description;
+        this.version = data.version;
+        this.contentSha256 = data.content_sha256;
+        this.sourceAgent = data.source_agent;
+        this.promotedBy = data.promoted_by;
+        this.promotedAt = data.promoted_at;
+        this.proposalId = data.proposal_id ?? null;
+        this.visibility = data.visibility;
+        this.validTo = data.valid_to ?? null;
+        this.supersedes = data.supersedes ?? null;
+    }
+    /** Validate `data` and build a row; throws {@link InvalidSkillRowError}. */
+    static fromDict(data) {
+        const errors = validateIndexRow(data);
+        if (errors.length > 0)
+            throw new InvalidSkillRowError(errors);
+        return new SkillIndexRow(data);
+    }
+    /** Serialize in schema order, omitting absent optional fields. */
+    toDict() {
+        const out = { spec_version: this.specVersion, name: this.name };
+        if (this.sourceName !== null)
+            out.source_name = this.sourceName;
+        out.description = this.description;
+        out.version = this.version;
+        out.content_sha256 = this.contentSha256;
+        out.source_agent = this.sourceAgent;
+        out.promoted_by = this.promotedBy;
+        out.promoted_at = this.promotedAt;
+        if (this.proposalId !== null)
+            out.proposal_id = this.proposalId;
+        out.visibility = this.visibility;
+        if (this.validTo !== null)
+            out.valid_to = this.validTo;
+        if (this.supersedes !== null)
+            out.supersedes = this.supersedes;
+        return out;
+    }
+    /** False once `valid_to` is on or before `today` (UTC today by default, `YYYY-MM-DD`). */
+    isActive(today) {
+        if (this.validTo === null)
+            return true;
+        return this.validTo > (today ?? utcToday());
+    }
+}
+/** Python's `yaml.safe_load` reads YAML 1.1 (so an unquoted timestamp is not a string). */
+function parseYaml11(text) {
+    return yamlParse(text, { version: "1.1", uniqueKeys: false, logLevel: "silent" });
+}
+const UTF8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+/** Read and validate one `skill.yaml`. */
+export function loadIndexRow(path) {
+    if (isPathLinkOrReparse(path)) {
+        throw new InvalidSkillRowError([`${INDEX_ROW_NAME} must not be a link`]);
+    }
+    const raw = readFileSync(path);
+    if (raw.length > MAX_INDEX_ROW_BYTES) {
+        throw new InvalidSkillRowError([`${INDEX_ROW_NAME} exceeds ${MAX_INDEX_ROW_BYTES} bytes`]);
+    }
+    let data;
+    try {
+        data = parseYaml11(UTF8.decode(raw));
+    }
+    catch {
+        throw new InvalidSkillRowError([`${INDEX_ROW_NAME} is not readable YAML`]);
+    }
+    return SkillIndexRow.fromDict(data);
+}
+function atomicWriteBytes(path, data) {
+    const temp = join(dirname(path), `.${basename(path)}.${randomBytes(6).toString("hex")}.tmp`);
+    try {
+        const fd = openSync(temp, "wx");
+        try {
+            writeSync(fd, data);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(temp, path);
+    }
+    finally {
+        if (existsSync(temp))
+            rmSync(temp, { force: true });
+    }
+}
+function renderRow(row) {
+    const errors = validateIndexRow(row.toDict());
+    if (errors.length > 0)
+        throw new InvalidSkillRowError(errors);
+    // YAML 1.1 quoting, so a timestamp or a date stays a string for any reader.
+    const text = yamlStringify(row.toDict(), {
+        version: "1.1",
+        sortMapEntries: false,
+        singleQuote: true,
+    });
+    return Buffer.from(text, "utf8");
+}
+/** Validate `row` and write it atomically to `path`. */
+export function writeIndexRow(path, row) {
+    atomicWriteBytes(path, renderRow(row));
+}
+// -- library layout ---------------------------------------------------------------
+/** `<library>/skills` -- the shared skill store. */
+export function skillsRoot(libraryPath) {
+    return join(libraryPath, SKILLS_DIRNAME);
+}
+/** The folder of one shared skill; `name` is validated first. */
+export function skillDir(libraryPath, name) {
+    return join(skillsRoot(libraryPath), validateSkillName(name));
+}
+function versionDir(libraryPath, name, version) {
+    return join(skillDir(libraryPath, name), VERSIONS_DIRNAME, String(version));
+}
+/** `path` is a regular file, following links (Python `Path.is_file()`). */
+function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The index row for `name` (the live one, or an archived `version`). Throws
+ * {@link SkillNotFoundError} when absent and {@link InvalidSkillRowError} when
+ * present but invalid.
+ */
+export function getSkillRow(libraryPath, name, version = null) {
+    const live = join(skillDir(libraryPath, name), INDEX_ROW_NAME);
+    if (!isFile(live))
+        throw new SkillNotFoundError(`no shared skill named '${name}'`);
+    const row = loadIndexRow(live);
+    if (row.name !== name) {
+        throw new InvalidSkillRowError([`row name '${row.name}' does not match its folder '${name}'`]);
+    }
+    if (version === null || version === row.version)
+        return row;
+    if (!isInt(version) || version < 1 || version >= row.version) {
+        throw new SkillNotFoundError(`shared skill '${name}' has no version ${version}`);
+    }
+    const archivedPath = join(versionDir(libraryPath, name, version), INDEX_ROW_NAME);
+    if (!isFile(archivedPath)) {
+        throw new SkillNotFoundError(`shared skill '${name}' has no version ${version}`);
+    }
+    const archived = loadIndexRow(archivedPath);
+    if (archived.name !== name || archived.version !== version) {
+        throw new InvalidSkillRowError([`archived row for '${name}' v${version} is inconsistent`]);
+    }
+    return archived;
+}
+function sortedEntries(directory) {
+    return readdirSync(directory, { withFileTypes: true }).sort((a, b) => compareUtf8(a.name, b.name));
+}
+/**
+ * Every valid live index row, sorted by name. Retired rows are omitted unless
+ * `includeRetired`. Rows that fail validation are skipped (and logged) rather
+ * than served.
+ */
+export function listSkillRows(libraryPath, options = {}) {
+    const root = skillsRoot(libraryPath);
+    if (!isDirectory(root))
+        return [];
+    const rows = [];
+    for (const child of sortedEntries(root)) {
+        if (child.name.startsWith(".") || skillNameError(child.name) !== null)
+            continue;
+        const path = join(root, child.name);
+        if (isPathLinkOrReparse(path) || !isDirectory(path))
+            continue;
+        let row;
+        try {
+            row = getSkillRow(libraryPath, child.name);
+        }
+        catch (err) {
+            if (err instanceof SkillNotFoundError)
+                continue;
+            if (err instanceof InvalidSkillRowError || isOsError(err)) {
+                console.warn(`[bourdon.skill_index] skipping ${child.name} (${String(err)})`);
+                continue;
+            }
+            throw err;
+        }
+        if (options.includeRetired || row.isActive(options.today))
+            rows.push(row);
+    }
+    return rows;
+}
+/** Every version number on disk for `name`, oldest first. */
+export function listSkillVersions(libraryPath, name) {
+    const live = getSkillRow(libraryPath, name);
+    const archive = join(skillDir(libraryPath, name), VERSIONS_DIRNAME);
+    const versions = new Set([live.version]);
+    if (isDirectory(archive)) {
+        for (const child of readdirSync(archive)) {
+            if (/^[0-9]+$/.test(child) && isFile(join(archive, child, INDEX_ROW_NAME))) {
+                versions.add(Number(child));
+            }
+        }
+    }
+    return [...versions].sort((a, b) => a - b);
+}
+/** A Node filesystem error (Python's `OSError`). */
+export function isOsError(err) {
+    return err instanceof Error && typeof err.code === "string";
+}
+function readStoredFiles(folder) {
+    const entries = [
+        [SKILL_BODY_NAME, readFileSync(join(folder, SKILL_BODY_NAME))],
+    ];
+    const filesRoot = join(folder, FILES_DIRNAME);
+    if (!isDirectory(filesRoot))
+        return entries;
+    // os.walk(followlinks=False): a directory's files first, then its sorted
+    // subdirectories; a link to a directory is listed but never entered, a link
+    // to anything else is refused.
+    const walk = (directory, parts) => {
+        const subdirs = [];
+        for (const entry of sortedEntries(directory)) {
+            const path = join(directory, entry.name);
+            if (entry.isDirectory() || (entry.isSymbolicLink() && isDirectory(path))) {
+                if (!entry.isSymbolicLink())
+                    subdirs.push(entry.name);
+                continue;
+            }
+            if (entry.isSymbolicLink() || isPathLinkOrReparse(path)) {
+                throw new InvalidSkillRowError([`stored file '${entry.name}' is a link`]);
+            }
+            entries.push([[...parts, entry.name].join("/"), readFileSync(path)]);
+        }
+        for (const name of subdirs)
+            walk(join(directory, name), [...parts, name]);
+    };
+    walk(filesRoot, []);
+    return entries;
+}
+/** The row and the stored files of one shared skill version. */
+export function readSharedSkill(libraryPath, name, version = null) {
+    const row = getSkillRow(libraryPath, name, version);
+    const live = getSkillRow(libraryPath, name);
+    const folder = row.version === live.version
+        ? skillDir(libraryPath, name)
+        : versionDir(libraryPath, name, row.version);
+    const files = readStoredFiles(folder);
+    const body = files.find(([rel]) => rel === SKILL_BODY_NAME)[1];
+    const content = {
+        frontMatter: parseFrontMatter(body),
+        files: [...files].sort(([a], [b]) => compareUtf8(a, b)),
+    };
+    return { row, content };
+}
+/** Whether the stored files still hash to the row's `content_sha256`. */
+export function verifySharedSkill(libraryPath, name, version = null) {
+    const { row, content } = readSharedSkill(libraryPath, name, version);
+    return computeContentSha256(content.files) === row.contentSha256;
+}
+// -- naming -----------------------------------------------------------------------
+/** Python `str.rstrip("-")`. */
+function rstripDash(text) {
+    return text.replace(/-+$/, "");
+}
+/**
+ * A free shared name derived from `name` (`name-2`, `name-3`...). Returns null
+ * only if no candidate within the length limit is free.
+ */
+export function suggestAvailableName(libraryPath, name) {
+    validateSkillName(name);
+    for (let n = 2; n < 1000; n++) {
+        const suffix = `-${n}`;
+        const base = rstripDash(name.slice(0, NAME_LIMIT - suffix.length)) || name.slice(0, 1);
+        const candidate = base + suffix;
+        if (!existsSync(join(skillsRoot(libraryPath), candidate)))
+            return candidate;
+    }
+    return null;
+}
+/** `datetime.now(timezone.utc).isoformat(timespec="seconds")`. */
+function nowIso() {
+    return `${new Date().toISOString().slice(0, 19)}+00:00`;
+}
+function writeTree(folder, content, row) {
+    mkdirSync(folder);
+    writeFileSync(join(folder, SKILL_BODY_NAME), skillContentBody(content));
+    for (const [rel, data] of content.files) {
+        if (rel === SKILL_BODY_NAME)
+            continue;
+        const target = join(folder, FILES_DIRNAME, ...rel.split("/"));
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, data);
+    }
+    writeFileSync(join(folder, INDEX_ROW_NAME), renderRow(row));
+}
+function pathExists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Write `content` into the shared store as a new skill or a new version.
+ *
+ * This is the store's only write path and performs no authorization: the
+ * caller (the promotion gate) must already have established that a trusted
+ * caller approved it. `content` must come from `readSkillFolder`.
+ *
+ *  - `name` defaults to the front-matter name. Another name renames at
+ *    promotion; the front-matter name is then kept as `source_name`.
+ *  - If the name is free, `expectedVersion` must be null.
+ *  - If the name is taken, `expectedVersion` must equal the live version; null
+ *    throws {@link SkillNameCollisionError} (with a free name to suggest) and
+ *    any other value throws {@link SkillVersionConflictError}.
+ *  - Content identical to the live version is a no-op (`changed: false`).
+ *
+ * The previous version moves to `.versions/<n>/`. `skill.yaml` is moved out
+ * first and written last, so a reader never sees a row next to the wrong body;
+ * an interrupted promotion leaves the skill unlisted, with the old version
+ * intact under `.versions/`.
+ */
+export function promoteSkill(libraryPath, content, options) {
+    const frontName = content.frontMatter.name;
+    const target = validateSkillName(options.name ?? frontName);
+    const digest = computeContentSha256(content.files);
+    const rowFields = {
+        spec_version: SKILL_INDEX_SPEC_VERSION,
+        name: target,
+        description: content.frontMatter.description,
+        content_sha256: digest,
+        source_agent: options.sourceAgent,
+        promoted_by: options.promotedBy,
+        promoted_at: options.promotedAt || nowIso(),
+        visibility: options.visibility ?? DEFAULT_SKILL_VISIBILITY,
+    };
+    if (target !== frontName)
+        rowFields.source_name = frontName;
+    if (options.proposalId !== undefined && options.proposalId !== null) {
+        rowFields.proposal_id = options.proposalId;
+    }
+    const expected = options.expectedVersion ?? null;
+    if (expected !== null && (!isInt(expected) || expected < 1)) {
+        throw new SkillIndexError("expected_version must be an integer >= 1 or None");
+    }
+    const root = skillsRoot(libraryPath);
+    mkdirSync(root, { recursive: true });
+    if (isPathLinkOrReparse(root))
+        throw new SkillIndexError(`${SKILLS_DIRNAME}/ must not be a link`);
+    return withManifestLock(join(root, PROMOTION_LOCK_STEM), () => {
+        const folder = join(root, target);
+        let current = null;
+        if (pathExists(folder)) {
+            if (isPathLinkOrReparse(folder) || !isDirectory(folder)) {
+                throw new SkillIndexError(`shared skill folder '${target}' is not a real directory`);
+            }
+            try {
+                current = getSkillRow(libraryPath, target);
+            }
+            catch (err) {
+                if (!(err instanceof SkillNotFoundError))
+                    throw err;
+                throw new SkillIndexError(`shared skill folder '${target}' has no ${INDEX_ROW_NAME}; ` +
+                    "restore it from .versions/ before promoting again");
+            }
+        }
+        if (current === null) {
+            if (expected !== null)
+                throw new SkillVersionConflictError(target, expected, null);
+            rowFields.version = 1;
+        }
+        else {
+            if (expected === null) {
+                throw new SkillNameCollisionError(target, current.version, suggestAvailableName(libraryPath, target));
+            }
+            if (expected !== current.version) {
+                throw new SkillVersionConflictError(target, expected, current.version);
+            }
+            if (current.contentSha256 === digest)
+                return { row: current, changed: false };
+            rowFields.version = current.version + 1;
+            rowFields.supersedes = current.version;
+        }
+        const row = SkillIndexRow.fromDict(rowFields);
+        mkdirSync(folder, { recursive: true });
+        const staging = join(folder, `${STAGING_PREFIX}${randomBytes(6).toString("hex")}`);
+        try {
+            writeTree(staging, content, row);
+            if (current !== null) {
+                const archive = versionDir(libraryPath, target, current.version);
+                if (pathExists(archive)) {
+                    throw new SkillIndexError(`archive for '${target}' v${current.version} already exists`);
+                }
+                mkdirSync(archive, { recursive: true });
+                renameSync(join(folder, INDEX_ROW_NAME), join(archive, INDEX_ROW_NAME));
+                renameSync(join(folder, SKILL_BODY_NAME), join(archive, SKILL_BODY_NAME));
+                if (pathExists(join(folder, FILES_DIRNAME))) {
+                    renameSync(join(folder, FILES_DIRNAME), join(archive, FILES_DIRNAME));
+                }
+            }
+            renameSync(join(staging, SKILL_BODY_NAME), join(folder, SKILL_BODY_NAME));
+            if (pathExists(join(staging, FILES_DIRNAME))) {
+                renameSync(join(staging, FILES_DIRNAME), join(folder, FILES_DIRNAME));
+            }
+            renameSync(join(staging, INDEX_ROW_NAME), join(folder, INDEX_ROW_NAME));
+        }
+        finally {
+            if (pathExists(staging))
+                rmSync(staging, { recursive: true, force: true });
+            if (current === null && !pathExists(join(folder, INDEX_ROW_NAME))) {
+                rmSync(folder, { recursive: true, force: true });
+            }
+        }
+        return { row, changed: true };
+    });
+}
+// -- retirement -----------------------------------------------------------------
+/** The live `skill.yaml` of `name`. */
+function liveRowPath(libraryPath, name) {
+    return join(skillDir(libraryPath, name), INDEX_ROW_NAME);
+}
+/**
+ * Set (retire) or clear (restore) the live row's `valid_to`.
+ *
+ * Retirement is a row edit, not a new version: the body and its hash are
+ * untouched, so every version stays fetchable by number. Like
+ * {@link promoteSkill} this performs no authorization; the caller is the gate.
+ * `expectedVersion` must equal the live version (compare-and-swap, under the
+ * same lock promotion writes under).
+ */
+export function setSkillValidTo(libraryPath, name, validTo, options) {
+    if (validTo !== null && !validDate(validTo)) {
+        throw new SkillIndexError("valid_to must be an ISO 8601 date (YYYY-MM-DD)");
+    }
+    const expected = options.expectedVersion;
+    if (!isInt(expected) || expected < 1) {
+        throw new SkillIndexError("expected_version must be an integer >= 1");
+    }
+    const root = skillsRoot(libraryPath);
+    if (!isDirectory(root) || isPathLinkOrReparse(root)) {
+        throw new SkillNotFoundError(`no shared skill named '${name}'`);
+    }
+    return withManifestLock(join(root, PROMOTION_LOCK_STEM), () => {
+        const current = getSkillRow(libraryPath, name);
+        if (current.version !== expected) {
+            throw new SkillVersionConflictError(name, expected, current.version);
+        }
+        const fields = current.toDict();
+        delete fields.valid_to;
+        if (validTo !== null)
+            fields.valid_to = validTo;
+        const row = SkillIndexRow.fromDict(fields);
+        writeIndexRow(liveRowPath(libraryPath, name), row);
+        return row;
+    });
+}