@getbourdon/participants 0.5.6 → 0.6.0

package/dist/skill-shares.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Per-skill share approvals: which local skills a participant may list. Port
+ * of the engine's `core/skill_shares.py`.
+ *
+ * Like approving a hook, a skill is listed in an agent's L5 manifest only
+ * after the person at this machine approves that one skill (`bourdon skills
+ * share`). Each approval pins the exact content approved: a skill whose folder
+ * has changed since is not listed again until it is re-approved.
+ *
+ * Layout (interoperable with the engine: either side reads what the other wrote):
+ *
+ *     <library>/.skill-shares.json
+ *
+ *     {
+ *       "version": 1,
+ *       "approvals": [
+ *         {
+ *           "kind": "skill",
+ *           "source": {
+ *             "agent": "alice",            // null: any reader of a cross-agent store skill
+ *             "store": "agent",            // "agent" | "cross_agent"
+ *             "scope": "user",             // "user" | "project"
+ *             "project": null,             // the project's folder name, for scope "project"
+ *             "path_hint": "~/.alice/skills/release-checklist"
+ *           },
+ *           "item": "release-checklist",
+ *           "content_sha256": "<64 hex>",
+ *           "approved_at": "2026-10-15T08:00:00Z",
+ *           "actor": "operator"
+ *         }
+ *       ]
+ *     }
+ *
+ * An approval is identified by `(kind, source, item, content_sha256)`. Only
+ * `kind: "skill"` is written today; an entry of a kind this version does not
+ * know is kept untouched on rewrite (and never treated as an approval).
+ * Approving an item again from the same source replaces its earlier approval,
+ * so a re-approved edit does not leave the old content approved.
+ *
+ * Load-bearing rules:
+ *
+ *  - **Local only.** The file sits beside the library's other local state and
+ *    is never synced: nothing in this package stages a library for the network,
+ *    and the engine's sync stages only `agents/*.l5.yaml`.
+ *  - **No absolute paths.** A share names its folder by the reader's symbolic
+ *    `path_hint` (`~/...`, `$ENV_VAR/...` or project-relative), never by where
+ *    it sits on disk.
+ *  - **Corruption means no approvals.** A missing, linked, oversized or
+ *    unparseable file reads as no shares at all, and a malformed entry is
+ *    dropped; reading never throws, so an export never fails here.
+ *  - **Writes are locked** with the same cross-process lock the library's other
+ *    writers use, and replace the file atomically.
+ *
+ * Nothing here is reachable over MCP; the terminal commands are the only
+ * writers, and they ask the person at the keyboard to confirm.
+ */
+export declare const SHARES_FILENAME = ".skill-shares.json";
+export declare const SHARES_VERSION = 1;
+/** The only approval kind written by this version. */
+export declare const KIND_SKILL = "skill";
+/** Who approved a share. Only the operator's terminal writes this file. */
+export declare const SHARE_ACTOR = "operator";
+/** A shares file larger than this is not read (it then holds no approvals). */
+export declare const MAX_SHARES_BYTES: number;
+type Dict = Record<string, unknown>;
+/** A share cannot be recorded (the file is unsafe to write, or the share is invalid). */
+export declare class SkillShareError extends Error {
+    constructor(message: string);
+}
+/** One approval: this skill folder, with exactly this content, may be listed. */
+export interface SkillShare {
+    name: string;
+    agent: string | null;
+    store: string;
+    scope: string;
+    project: string | null;
+    pathHint: string;
+    contentSha256: string;
+    approvedAt: string;
+    actor: string;
+}
+/** The skill folder a share is about, whoever reads it (a comparable key). */
+export declare function shareFolderKey(share: SkillShare): string;
+/** The reader source: the same folder as read by the same reader. */
+export declare function shareSourceKey(share: SkillShare): string;
+/** The approval's identity: `(kind, source, item, content_sha256)`. */
+export declare function shareKey(share: SkillShare): string;
+/**
+ * Whether the participant `agentId` may list the skill under `share`. A share
+ * of an agent's own folder applies to that agent; a share of a cross-agent
+ * store skill with no `agent` applies to every reader of the store.
+ */
+export declare function shareAppliesTo(share: SkillShare, agentId: string): boolean;
+/** The on-disk record, in the engine's key order. */
+export declare function shareToDict(share: SkillShare): Dict;
+/**
+ * The library whose shares the participants' exports read. Resolved at call
+ * time (not import time) so a relocated home is honoured.
+ */
+export declare function defaultSharesLibrary(): string;
+export declare function sharesPath(libraryPath?: string | null): string;
+/**
+ * Every readable approval, in file order. Never throws.
+ *
+ * A missing file is no approvals. So is a file that is a link, not a regular
+ * file, too large, not JSON or of an unknown layout; a malformed entry is
+ * dropped and the rest are kept.
+ */
+export declare function loadShares(libraryPath?: string | null): SkillShare[];
+export interface AddShareOptions {
+    name: string;
+    agent: string | null;
+    store: string;
+    scope: string;
+    project: string | null;
+    pathHint: string;
+    contentSha256: string;
+    approvedAt?: string | null;
+}
+/**
+ * Record one approval, replacing earlier approvals of the same item from the
+ * same source. An unreadable shares file is replaced: it held no usable
+ * approvals.
+ */
+export declare function addShare(libraryPath: string | null | undefined, options: AddShareOptions): SkillShare;
+/** Remove the shares whose {@link shareKey} is in `keys`; how many went. */
+export declare function removeShares(libraryPath: string | null | undefined, keys: Iterable<string>): number;
+export {};

package/dist/skill-shares.js

@@ -0,0 +1,366 @@
+// SPDX-License-Identifier: BUSL-1.1
+/**
+ * Per-skill share approvals: which local skills a participant may list. Port
+ * of the engine's `core/skill_shares.py`.
+ *
+ * Like approving a hook, a skill is listed in an agent's L5 manifest only
+ * after the person at this machine approves that one skill (`bourdon skills
+ * share`). Each approval pins the exact content approved: a skill whose folder
+ * has changed since is not listed again until it is re-approved.
+ *
+ * Layout (interoperable with the engine: either side reads what the other wrote):
+ *
+ *     <library>/.skill-shares.json
+ *
+ *     {
+ *       "version": 1,
+ *       "approvals": [
+ *         {
+ *           "kind": "skill",
+ *           "source": {
+ *             "agent": "alice",            // null: any reader of a cross-agent store skill
+ *             "store": "agent",            // "agent" | "cross_agent"
+ *             "scope": "user",             // "user" | "project"
+ *             "project": null,             // the project's folder name, for scope "project"
+ *             "path_hint": "~/.alice/skills/release-checklist"
+ *           },
+ *           "item": "release-checklist",
+ *           "content_sha256": "<64 hex>",
+ *           "approved_at": "2026-10-15T08:00:00Z",
+ *           "actor": "operator"
+ *         }
+ *       ]
+ *     }
+ *
+ * An approval is identified by `(kind, source, item, content_sha256)`. Only
+ * `kind: "skill"` is written today; an entry of a kind this version does not
+ * know is kept untouched on rewrite (and never treated as an approval).
+ * Approving an item again from the same source replaces its earlier approval,
+ * so a re-approved edit does not leave the old content approved.
+ *
+ * Load-bearing rules:
+ *
+ *  - **Local only.** The file sits beside the library's other local state and
+ *    is never synced: nothing in this package stages a library for the network,
+ *    and the engine's sync stages only `agents/*.l5.yaml`.
+ *  - **No absolute paths.** A share names its folder by the reader's symbolic
+ *    `path_hint` (`~/...`, `$ENV_VAR/...` or project-relative), never by where
+ *    it sits on disk.
+ *  - **Corruption means no approvals.** A missing, linked, oversized or
+ *    unparseable file reads as no shares at all, and a malformed entry is
+ *    dropped; reading never throws, so an export never fails here.
+ *  - **Writes are locked** with the same cross-process lock the library's other
+ *    writers use, and replace the file atomically.
+ *
+ * Nothing here is reachable over MCP; the terminal commands are the only
+ * writers, and they ask the person at the keyboard to confirm.
+ */
+import { randomBytes } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeSync, } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { withManifestLock } from "@getbourdon/federation";
+import { codePointLength, isPathLinkOrReparse } from "./skill-index.js";
+export const SHARES_FILENAME = ".skill-shares.json";
+export const SHARES_VERSION = 1;
+/** The only approval kind written by this version. */
+export const KIND_SKILL = "skill";
+/** Who approved a share. Only the operator's terminal writes this file. */
+export const SHARE_ACTOR = "operator";
+/** A shares file larger than this is not read (it then holds no approvals). */
+export const MAX_SHARES_BYTES = 4 * 1024 * 1024;
+const STORES = new Set(["agent", "cross_agent"]);
+const SCOPES = new Set(["user", "project"]);
+const SHA_RE = /^[0-9a-f]{64}$/;
+const MAX_FIELD_CHARS = 255;
+/** A share cannot be recorded (the file is unsafe to write, or the share is invalid). */
+export class SkillShareError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SkillShareError";
+    }
+}
+/** The skill folder a share is about, whoever reads it (a comparable key). */
+export function shareFolderKey(share) {
+    return JSON.stringify([share.store, share.scope, share.project, share.pathHint]);
+}
+/** The reader source: the same folder as read by the same reader. */
+export function shareSourceKey(share) {
+    return JSON.stringify([share.agent, share.store, share.scope, share.project, share.pathHint]);
+}
+/** The approval's identity: `(kind, source, item, content_sha256)`. */
+export function shareKey(share) {
+    return JSON.stringify([
+        KIND_SKILL,
+        [share.agent, share.store, share.scope, share.project, share.pathHint],
+        share.name,
+        share.contentSha256,
+    ]);
+}
+/** What a new approval replaces: the same item from the same source, any content. */
+function shareReplaces(share) {
+    return JSON.stringify([
+        KIND_SKILL,
+        [share.agent, share.store, share.scope, share.project, share.pathHint],
+        share.name,
+    ]);
+}
+/**
+ * Whether the participant `agentId` may list the skill under `share`. A share
+ * of an agent's own folder applies to that agent; a share of a cross-agent
+ * store skill with no `agent` applies to every reader of the store.
+ */
+export function shareAppliesTo(share, agentId) {
+    return share.agent === null || share.agent === agentId;
+}
+/** The on-disk record, in the engine's key order. */
+export function shareToDict(share) {
+    return {
+        kind: KIND_SKILL,
+        source: {
+            agent: share.agent,
+            store: share.store,
+            scope: share.scope,
+            project: share.project,
+            path_hint: share.pathHint,
+        },
+        item: share.name,
+        content_sha256: share.contentSha256,
+        approved_at: share.approvedAt,
+        actor: share.actor,
+    };
+}
+/**
+ * The library whose shares the participants' exports read. Resolved at call
+ * time (not import time) so a relocated home is honoured.
+ */
+export function defaultSharesLibrary() {
+    return join(homedir(), "agent-library");
+}
+export function sharesPath(libraryPath) {
+    return join(libraryPath ?? defaultSharesLibrary(), SHARES_FILENAME);
+}
+function nowIso() {
+    return `${new Date().toISOString().slice(0, 19)}Z`;
+}
+function isDict(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+class BadEntry extends Error {
+}
+function text(value, optional = false) {
+    if (value === null && optional)
+        return null;
+    if (typeof value !== "string" || !value || codePointLength(value) > MAX_FIELD_CHARS) {
+        throw new BadEntry("bad field");
+    }
+    return value;
+}
+/** One `kind: "skill"` entry; throws for anything malformed. */
+function shareFrom(data) {
+    if (!isDict(data) || data.kind !== KIND_SKILL)
+        throw new BadEntry("not a skill approval");
+    const source = data.source;
+    if (!isDict(source))
+        throw new BadEntry("no source");
+    const store = source.store;
+    const scope = source.scope;
+    const sha = data.content_sha256;
+    if (typeof store !== "string" ||
+        !STORES.has(store) ||
+        typeof scope !== "string" ||
+        !SCOPES.has(scope)) {
+        throw new BadEntry("bad store or scope");
+    }
+    if (typeof sha !== "string" || !SHA_RE.test(sha))
+        throw new BadEntry("bad content hash");
+    const pathHint = text(source.path_hint);
+    if (pathHint.startsWith("/") ||
+        pathHint.startsWith("\\") ||
+        Array.from(pathHint).slice(0, 3).join("").includes(":")) {
+        throw new BadEntry("absolute path");
+    }
+    const agent = text(source.agent ?? null, true);
+    if (agent === null && store !== "cross_agent") {
+        throw new BadEntry("an agent's own folder needs its agent");
+    }
+    const project = text(source.project ?? null, true);
+    if ((scope === "project") !== (project !== null)) {
+        throw new BadEntry("project and scope disagree");
+    }
+    return {
+        name: text(data.item),
+        agent,
+        store,
+        scope,
+        project,
+        pathHint,
+        contentSha256: sha,
+        approvedAt: text(data.approved_at),
+        actor: text(data.actor),
+    };
+}
+/** An entry of an approval kind this version does not write: kept, never used. */
+function isOtherKind(item) {
+    const kind = isDict(item) ? item.kind : undefined;
+    return typeof kind === "string" && kind !== KIND_SKILL;
+}
+function warn(message) {
+    console.warn(`[bourdon.participants] ${message}`);
+}
+const STRICT_UTF8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+/** The `approvals` list, or `null` when the file is missing or cannot be trusted. */
+function readRaw(path) {
+    let info;
+    try {
+        info = lstatSync(path);
+    }
+    catch (exc) {
+        if (exc.code !== "ENOENT") {
+            warn(`skill shares: ${SHARES_FILENAME} cannot be read; listing no skills`);
+        }
+        return null;
+    }
+    try {
+        if (isPathLinkOrReparse(path, info) || !info.isFile())
+            throw new BadEntry("not a regular file");
+        if (info.size > MAX_SHARES_BYTES)
+            throw new BadEntry("too large");
+        const data = JSON.parse(STRICT_UTF8.decode(readFileSync(path)));
+        // Python's `!=`: `1.0` and `true` equal 1 there as well.
+        if (!isDict(data) || (data.version !== SHARES_VERSION && data.version !== true)) {
+            throw new BadEntry("unknown layout");
+        }
+        const approvals = data.approvals;
+        if (!Array.isArray(approvals))
+            throw new BadEntry("no approvals list");
+        return approvals;
+    }
+    catch {
+        warn(`skill shares: ${SHARES_FILENAME} is unreadable; listing no skills`);
+        return null;
+    }
+}
+/**
+ * Every readable approval, in file order. Never throws.
+ *
+ * A missing file is no approvals. So is a file that is a link, not a regular
+ * file, too large, not JSON or of an unknown layout; a malformed entry is
+ * dropped and the rest are kept.
+ */
+export function loadShares(libraryPath) {
+    const raw = readRaw(sharesPath(libraryPath));
+    if (raw === null)
+        return [];
+    const shares = [];
+    for (const item of raw) {
+        if (isOtherKind(item))
+            continue;
+        try {
+            shares.push(shareFrom(item));
+        }
+        catch {
+            warn(`skill shares: dropping a malformed entry in ${SHARES_FILENAME}`);
+        }
+    }
+    return shares;
+}
+function otherKinds(path) {
+    return (readRaw(path) ?? []).filter(isOtherKind);
+}
+/** Python `json.dumps(..., indent=2)`: the default `ensure_ascii` escapes. */
+function pyJsonDumps(value) {
+    return JSON.stringify(value, null, 2).replace(/[\u007f-￿]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+function write(path, shares) {
+    const approvals = [...otherKinds(path), ...shares.map(shareToDict)];
+    const payload = { version: SHARES_VERSION, approvals };
+    const body = `${pyJsonDumps(payload)}\n`;
+    const temp = join(dirname(path), `.${basename(path)}.${randomBytes(6).toString("hex")}.tmp`);
+    try {
+        const fd = openSync(temp, "wx");
+        try {
+            writeSync(fd, Buffer.from(body, "utf8"));
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(temp, path);
+    }
+    finally {
+        if (existsSync(temp))
+            rmSync(temp, { force: true });
+    }
+}
+function checkWritable(path) {
+    let info;
+    try {
+        info = lstatSync(path);
+    }
+    catch (exc) {
+        if (exc.code === "ENOENT")
+            return;
+        throw exc;
+    }
+    if (isPathLinkOrReparse(path, info) || !info.isFile()) {
+        throw new SkillShareError(`${SHARES_FILENAME} must be a regular file, not a link`);
+    }
+}
+/**
+ * Record one approval, replacing earlier approvals of the same item from the
+ * same source. An unreadable shares file is replaced: it held no usable
+ * approvals.
+ */
+export function addShare(libraryPath, options) {
+    let share;
+    try {
+        share = shareFrom(shareToDict({
+            name: options.name,
+            agent: options.agent,
+            store: options.store,
+            scope: options.scope,
+            project: options.project,
+            pathHint: options.pathHint,
+            contentSha256: options.contentSha256,
+            approvedAt: options.approvedAt || nowIso(),
+            actor: SHARE_ACTOR,
+        }));
+    }
+    catch (exc) {
+        throw new SkillShareError(`invalid share: ${exc instanceof Error ? exc.message : String(exc)}`);
+    }
+    const path = sharesPath(libraryPath);
+    mkdirSync(dirname(path), { recursive: true });
+    const replaces = shareReplaces(share);
+    withManifestLock(path, () => {
+        checkWritable(path);
+        const kept = loadShares(dirname(path)).filter((item) => shareReplaces(item) !== replaces);
+        write(path, [...kept, share]);
+    });
+    return share;
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Remove the shares whose {@link shareKey} is in `keys`; how many went. */
+export function removeShares(libraryPath, keys) {
+    const wanted = new Set(keys);
+    const path = sharesPath(libraryPath);
+    if (!isDirectory(dirname(path)))
+        return 0;
+    return withManifestLock(path, () => {
+        checkWritable(path);
+        const current = loadShares(dirname(path));
+        const kept = current.filter((item) => !wanted.has(shareKey(item)));
+        const removed = current.length - kept.length;
+        if (removed)
+            write(path, kept);
+        return removed;
+    });
+}

package/dist/skill-store.d.ts

@@ -0,0 +1,186 @@
+/**
+ * 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 { type SkillContent } from "./skill-index.js";
+type Dict = Record<string, unknown>;
+export declare const SKILL_INDEX_SPEC_VERSION = "0.1";
+export declare const SKILLS_DIRNAME = "skills";
+export declare const INDEX_ROW_NAME = "skill.yaml";
+export declare const FILES_DIRNAME = "files";
+export declare const VERSIONS_DIRNAME = ".versions";
+/** The shared store behaves as org-tier memory: readable by every federation
+ * reader, writable by no one through the ordinary write API. */
+export declare const SKILL_STORE_WRITE_POLICY = "read-only";
+/** Promotion widens nothing unless the promoting caller asks it to. */
+export declare const DEFAULT_SKILL_VISIBILITY = "private";
+export declare const MAX_INDEX_ROW_BYTES: number;
+/** Base class for every refusal the skill store raises. */
+export declare class SkillIndexError extends Error {
+    constructor(message: string);
+}
+/** An index row does not conform to the skill index schema. */
+export declare class InvalidSkillRowError extends SkillIndexError {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+/** The shared name is already taken and the caller did not ask to update it. */
+export declare class SkillNameCollisionError extends SkillIndexError {
+    readonly skillName: string;
+    readonly existingVersion: number;
+    readonly suggestedName: string | null;
+    constructor(name: string, existingVersion: number, suggestedName: string | null);
+}
+/** `expectedVersion` does not match what is in the store. */
+export declare class SkillVersionConflictError extends SkillIndexError {
+    readonly skillName: string;
+    readonly expected: number | null;
+    readonly current: number | null;
+    constructor(name: string, expected: number | null, current: number | null);
+}
+/** No shared skill (or no such version of it) exists. */
+export declare class SkillNotFoundError extends SkillIndexError {
+    constructor(message: string);
+}
+/** Return `name` if it is a valid shared skill name, else throw {@link SkillIndexError}. */
+export declare function validateSkillName(name: unknown): string;
+/**
+ * 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 declare function validateIndexRow(row: unknown): string[];
+/** One validated `skill.yaml`. */
+export declare class SkillIndexRow {
+    readonly specVersion: string;
+    readonly name: string;
+    readonly sourceName: string | null;
+    readonly description: string;
+    readonly version: number;
+    readonly contentSha256: string;
+    readonly sourceAgent: string;
+    readonly promotedBy: string;
+    readonly promotedAt: string;
+    readonly proposalId: string | null;
+    readonly visibility: string;
+    readonly validTo: string | null;
+    readonly supersedes: number | null;
+    private constructor();
+    /** Validate `data` and build a row; throws {@link InvalidSkillRowError}. */
+    static fromDict(data: unknown): SkillIndexRow;
+    /** Serialize in schema order, omitting absent optional fields. */
+    toDict(): Dict;
+    /** False once `valid_to` is on or before `today` (UTC today by default, `YYYY-MM-DD`). */
+    isActive(today?: string): boolean;
+}
+/** Read and validate one `skill.yaml`. */
+export declare function loadIndexRow(path: string): SkillIndexRow;
+/** Validate `row` and write it atomically to `path`. */
+export declare function writeIndexRow(path: string, row: SkillIndexRow): void;
+/** `<library>/skills` -- the shared skill store. */
+export declare function skillsRoot(libraryPath: string): string;
+/** The folder of one shared skill; `name` is validated first. */
+export declare function skillDir(libraryPath: string, name: string): string;
+/**
+ * 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 declare function getSkillRow(libraryPath: string, name: string, version?: number | null): SkillIndexRow;
+/**
+ * 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 declare function listSkillRows(libraryPath: string, options?: {
+    includeRetired?: boolean;
+    today?: string;
+}): SkillIndexRow[];
+/** Every version number on disk for `name`, oldest first. */
+export declare function listSkillVersions(libraryPath: string, name: string): number[];
+/** A Node filesystem error (Python's `OSError`). */
+export declare function isOsError(err: unknown): boolean;
+/** The row and the stored files of one shared skill version. */
+export declare function readSharedSkill(libraryPath: string, name: string, version?: number | null): {
+    row: SkillIndexRow;
+    content: SkillContent;
+};
+/** Whether the stored files still hash to the row's `content_sha256`. */
+export declare function verifySharedSkill(libraryPath: string, name: string, version?: number | null): boolean;
+/**
+ * A free shared name derived from `name` (`name-2`, `name-3`...). Returns null
+ * only if no candidate within the length limit is free.
+ */
+export declare function suggestAvailableName(libraryPath: string, name: string): string | null;
+export interface PromotionResult {
+    row: SkillIndexRow;
+    /** False when the content already matched the live version (nothing written). */
+    changed: boolean;
+}
+export interface PromoteSkillOptions {
+    sourceAgent: string;
+    promotedBy: string;
+    /** Shared name; defaults to the front-matter name. Another name renames at promotion. */
+    name?: string | null;
+    /** The live version when replacing a skill; null/absent for a new one. */
+    expectedVersion?: number | null;
+    visibility?: string;
+    proposalId?: string | null;
+    /** ISO 8601 with a UTC offset; defaults to now, to the second. */
+    promotedAt?: string | null;
+}
+/**
+ * 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 declare function promoteSkill(libraryPath: string, content: SkillContent, options: PromoteSkillOptions): PromotionResult;
+/**
+ * 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 declare function setSkillValidTo(libraryPath: string, name: string, validTo: string | null, options: {
+    expectedVersion: number;
+}): SkillIndexRow;
+export {};