sfora-cli 0.15.0 → 0.17.0

package/dist/local-core/skill-review.js

@@ -0,0 +1,132 @@
+import { randomUUID } from 'node:crypto';
+import { readSkillBundle, inspectSkillTarget } from './skills.js';
+import { SkillBindingService, planSkillInstallation, planSkillTransfer } from './skill-sync.js';
+import { SkillOperationExecutor } from './skill-executor.js';
+/** Read-only previews become durable operations only when the person confirms.
+ * Ephemeral review IDs are capability tokens owned by the desktop main process. */
+export class SkillReviewService {
+    store;
+    journal;
+    connect;
+    now;
+    reviews = new Map();
+    constructor(store, journal, connect, now = Date.now) {
+        this.store = store;
+        this.journal = journal;
+        this.connect = connect;
+        this.now = now;
+    }
+    remember(entry) {
+        for (const [id, item] of this.reviews)
+            if (item.expiresAt < this.now() && (!item.operationId || item.result) && !item.running)
+                this.reviews.delete(id);
+        if (this.reviews.size >= 50)
+            throw new Error('Too many open reviews. Finish existing transfers or reopen the app.');
+        this.reviews.set(entry.view.id, { ...entry, expiresAt: this.now() + 10 * 60_000 });
+        return structuredClone(entry.view);
+    }
+    view(remote, path, action) {
+        return { id: randomUUID(), action, outcome: 'reviewable', name: remote.locator.name, project: remote.locator.project,
+            scope: `${remote.remote.deployment} · ${remote.remote.organizationId} · ${remote.accountId}`, path, version: remote.revision.cloudVersion, files: [], blockers: [] };
+    }
+    async transfer(input) {
+        if (!['push', 'pull'].includes(input.direction))
+            throw new Error('Choose Push to Sfora or Update local copy.');
+        const catalog = await this.store.read();
+        const location = catalog.locations.find(l => l.id === input.locationId);
+        if (!location)
+            throw new Error('This local skill is no longer tracked. Refresh and choose it again.');
+        const local = await readSkillBundle(location.path);
+        const cloud = await this.connect(input.connection);
+        const names = [...new Set(catalog.bindings.filter(b => b.localSkillId === location.skillId && b.remote.projectId === input.projectId).map(b => b.locator.name))];
+        let remote;
+        try {
+            remote = await cloud.snapshot(input.projectId, names.length === 1 ? names[0] : local.name);
+        }
+        catch (error) {
+            const code = error?.code;
+            if (names.length || !['SKILL_NOT_FOUND', 'SKILL_NOT_PUBLISHED'].includes(code ?? ''))
+                throw error;
+            if (input.direction === 'pull')
+                throw new Error('This skill has no published version to install. Open its project to review or publish a draft.');
+            return this.remember({ connection: input.connection, view: { id: randomUUID(), action: 'push', outcome: 'draft-needed', name: local.name, project: input.projectId, scope: input.connection, path: location.path,
+                    files: local.files.map(file => ({ path: file.path, kind: 'added' })), blockers: ['For the first publication, review these local files in the project editor, save a draft, then publish it for your team.'] } });
+        }
+        if (remote.remote.projectId !== input.projectId)
+            throw new Error('The selected project resolved to a different identity.');
+        const binding = catalog.bindings.find(b => b.localSkillId === location.skillId && b.accountId === remote.accountId && b.remote.deployment === remote.remote.deployment && b.remote.organizationId === remote.remote.organizationId && b.remote.projectId === remote.remote.projectId);
+        const view = this.view(remote, location.path, input.direction);
+        if (!binding) {
+            if (local.hash !== remote.revision.hash) {
+                view.outcome = 'blocked';
+                view.blockers = ['These copies have not been linked and their contents differ. Open the project to review its existing skill, or install it into a new folder.'];
+                return this.remember({ view, connection: input.connection });
+            }
+            view.action = 'link';
+            return this.remember({ view, connection: input.connection, link: { localSkillId: location.skillId, locationId: location.id, snapshot: remote } });
+        }
+        const target = await inspectSkillTarget(location.path);
+        const plan = planSkillTransfer({ direction: input.direction, binding, location, local: { state: 'available', bundle: local }, remote, ownership: target.ownership });
+        view.outcome = plan.outcome;
+        view.files = plan.files.map(f => ({ path: f.path, kind: f.kind }));
+        view.blockers = plan.blockers;
+        return this.remember({ view, connection: input.connection, plan });
+    }
+    async install(input) {
+        const remote = await (await this.connect(input.connection)).snapshot(input.projectId, input.name);
+        if (remote.remote.projectId !== input.projectId)
+            throw new Error('The selected project resolved to a different identity.');
+        const plan = planSkillInstallation(remote, input.destination, await inspectSkillTarget(input.destination));
+        const view = this.view(remote, input.destination, 'install');
+        view.outcome = plan.outcome;
+        view.files = plan.files.map(f => ({ path: f.path, kind: f.kind }));
+        view.blockers = plan.blockers;
+        return this.remember({ view, connection: input.connection, plan });
+    }
+    async confirm(id) {
+        const entry = this.reviews.get(id);
+        if (!entry || (!entry.operationId && entry.expiresAt < this.now()))
+            throw new Error('This review expired. Review the current changes again.');
+        if (entry.view.outcome !== 'reviewable')
+            throw new Error('There are no applicable changes in this review.');
+        if (entry.result)
+            return entry.result;
+        if (entry.running)
+            return entry.running;
+        entry.running = this.apply(entry).then(result => { if (result.status === 'succeeded') {
+            entry.result = result;
+            delete entry.plan;
+            delete entry.link;
+        } return result; }).finally(() => { entry.running = undefined; });
+        return entry.running;
+    }
+    async apply(entry) {
+        const cloud = await this.connect(entry.connection);
+        if (entry.link) {
+            const { snapshot, locationId, localSkillId } = entry.link;
+            const location = (await this.store.read()).locations.find(l => l.id === locationId && l.skillId === localSkillId);
+            if (!location || location.path !== entry.view.path)
+                throw new Error('Local location changed. Review the copies again.');
+            const remote = await cloud.snapshot(snapshot.locator.project, snapshot.locator.name);
+            if (JSON.stringify(remote.remote) !== JSON.stringify(snapshot.remote) || remote.accountId !== snapshot.accountId || JSON.stringify(remote.revision) !== JSON.stringify(snapshot.revision))
+                throw new Error('Cloud identity or revision changed. Review the copies again.');
+            const local = await readSkillBundle(location.path);
+            if (local.hash !== remote.revision.hash)
+                throw new Error('Local files changed. Review the copies again.');
+            await new SkillBindingService(this.store).adopt(localSkillId, remote, local);
+            return { status: 'succeeded' };
+        }
+        if (!entry.plan)
+            throw new Error('Review has no applicable changes.');
+        const recovering = !!entry.operationId;
+        if (!entry.operationId)
+            entry.operationId = (await this.journal.create(entry.plan)).id;
+        try {
+            const operation = await new SkillOperationExecutor(this.store, this.journal, cloud).apply(entry.operationId, recovering);
+            return { status: operation.status, operationId: operation.id };
+        }
+        catch (error) {
+            throw new Error(`${error.message} The result is saved in Transfers for recovery.`);
+        }
+    }
+}

package/dist/local-core/skill-service.d.ts

@@ -0,0 +1,96 @@
+import { discoverSkills, type SkillSource } from './skill-discovery.js';
+import { type RegisteredSkillRoot, type SkillStore } from './skill-store.js';
+import { readSkillBundle } from './skills.js';
+export declare const pathWithin: (root: string, path: string) => boolean;
+export interface SkillServicePorts {
+    discover: typeof discoverSkills;
+    resolveDirectory(path: string): Promise<string>;
+    inspect: typeof readSkillBundle;
+}
+/** Node service shared by CLI and desktop. Its IDs are identity, not renderer grants. */
+export declare class SkillService {
+    readonly store: SkillStore;
+    readonly sources: () => SkillSource[];
+    readonly ports: SkillServicePorts;
+    constructor(store?: SkillStore, sources?: () => SkillSource[], ports?: SkillServicePorts);
+    registerRoot(path: string, label?: string, scope?: "custom" | "project"): Promise<{
+        id: string;
+        path: string;
+        label: string;
+        depth: number;
+        scope?: "custom" | "project";
+    }>;
+    roots(): Promise<RegisteredSkillRoot[]>;
+    removeRoot(id: string): Promise<void>;
+    inventory(): Promise<{
+        skills: {
+            skillId: string;
+            locationId: string;
+            path: string;
+            name: string;
+            sources: string[];
+            aliases: import("./skill-domain.js").SkillAlias[];
+            hash: string | undefined;
+            fileCount: number | undefined;
+            error: string | undefined;
+            availability: "available" | "unavailable";
+        }[];
+        warnings: string[];
+    }>;
+    /** Warm reads use persisted observations; explicit inventory remains a full reconciliation. */
+    cachedInventory(): Promise<{
+        skills: {
+            skillId: string;
+            locationId: string;
+            path: string;
+            name: string;
+            sources: string[];
+            aliases: import("./skill-domain.js").SkillAlias[];
+            hash: string | undefined;
+            fileCount: number | undefined;
+            error: string | undefined;
+            availability: "available" | "unavailable";
+        }[];
+        warnings: string[];
+    }>;
+    discoverySources(): Promise<SkillSource[]>;
+    /** Re-read only affected known locations, preserving identity and last known bytes on failure. */
+    refreshLocations(ids: string[]): Promise<{
+        skills: {
+            skillId: string;
+            locationId: string;
+            path: string;
+            name: string;
+            sources: string[];
+            aliases: import("./skill-domain.js").SkillAlias[];
+            hash: string | undefined;
+            fileCount: number | undefined;
+            error: string | undefined;
+            availability: "available" | "unavailable";
+        }[];
+        warnings: string[];
+    }>;
+    /** Metadata-only explicit relocation. Never guesses identity from a name/hash or moves files. */
+    relocateLocation(id: string, path: string): Promise<{
+        id: string;
+        skillId: string;
+        path: string;
+        aliases: import("./skill-domain.js").SkillAlias[];
+        createdAt: number;
+    }>;
+    rebuild(): Promise<{
+        skills: {
+            skillId: string;
+            locationId: string;
+            path: string;
+            name: string;
+            sources: string[];
+            aliases: import("./skill-domain.js").SkillAlias[];
+            hash: string | undefined;
+            fileCount: number | undefined;
+            error: string | undefined;
+            availability: "available" | "unavailable";
+        }[];
+        warnings: string[];
+    }>;
+}

package/dist/local-core/skill-service.js

@@ -0,0 +1,157 @@
+import { randomUUID } from 'node:crypto';
+import { realpath, stat } from 'node:fs/promises';
+import { basename, relative, isAbsolute } from 'node:path';
+import { discoverSkills, defaultSkillSources } from './skill-discovery.js';
+import { projectSkillSources } from './skill-adapters.js';
+import { SQLiteSkillStore } from './skill-store.js';
+import { readSkillBundle } from './skills.js';
+import { LocalConflictError } from './files.js';
+export const pathWithin = (root, path) => { const rel = relative(root, path); return rel === '' || (rel !== '..' && !rel.startsWith('../') && !rel.startsWith('..\\') && !isAbsolute(rel)); };
+const filesystemPorts = {
+    discover: discoverSkills,
+    resolveDirectory: async (path) => { const canonical = await realpath(path); if (!(await stat(canonical)).isDirectory())
+        throw new Error('Choose a directory for skill discovery.'); return canonical; },
+    inspect: readSkillBundle,
+};
+function rootSources(roots) {
+    return roots.flatMap(root => root.scope === 'project'
+        ? projectSkillSources(root.path).map(source => ({ ...source, id: `${root.id}:${source.id}`, label: `${root.label} · ${source.label}` }))
+        : [{ ...root, kind: 'custom' }]);
+}
+/** Node service shared by CLI and desktop. Its IDs are identity, not renderer grants. */
+export class SkillService {
+    store;
+    sources;
+    ports;
+    constructor(store = new SQLiteSkillStore(), sources = defaultSkillSources, ports = filesystemPorts) {
+        this.store = store;
+        this.sources = sources;
+        this.ports = ports;
+    }
+    async registerRoot(path, label, scope = "custom") {
+        const canonical = await this.ports.resolveDirectory(path);
+        const name = label?.trim() || basename(canonical) || canonical;
+        if (name.length > 200)
+            throw new Error('Folder label must be at most 200 characters.');
+        return this.store.transaction(c => {
+            const found = c.roots.find(r => r.path === canonical);
+            if (found) {
+                found.label = name;
+                found.scope = scope;
+                return { ...found };
+            }
+            const root = { id: randomUUID(), path: canonical, label: name, depth: 4, scope };
+            c.roots.push(root);
+            return root;
+        });
+    }
+    async roots() { return (await this.store.read()).roots; }
+    async removeRoot(id) {
+        return this.store.transaction(c => { if (!c.roots.some(r => r.id === id))
+            throw new Error('Registered folder not found.'); c.roots = c.roots.filter(r => r.id !== id); });
+    }
+    async inventory() {
+        const before = await this.store.read();
+        const sources = [...this.sources(), ...rootSources(before.roots)];
+        const result = await this.ports.discover(sources);
+        const now = Date.now();
+        return this.store.transaction(c => {
+            // Scanning happens outside the lock. Do not commit results for a changed root set,
+            // or let an older scan overwrite observations from a concurrent newer transaction.
+            if (c.revision !== before.revision)
+                throw new LocalConflictError('Skill catalog changed during discovery. Refresh to use the latest inventory.');
+            const active = new Set(sources.map(s => s.id ?? s.path));
+            for (const found of result.skills) {
+                let location = c.locations.find(l => l.path === found.path);
+                if (!location) {
+                    const identity = { id: randomUUID(), createdAt: now };
+                    c.identities.push(identity);
+                    location = { id: randomUUID(), skillId: identity.id, path: found.path, aliases: [], createdAt: now };
+                    c.locations.push(location);
+                }
+                // Retain provenance aliases, but only active roots contribute to the displayed view.
+                for (const alias of found.aliases) {
+                    const old = location.aliases.find(a => a.sourceId === alias.sourceId && a.path === alias.path);
+                    if (old)
+                        Object.assign(old, alias);
+                    else
+                        location.aliases.push(alias);
+                }
+                c.observations = c.observations.filter(o => o.locationId !== location.id);
+                c.observations.push({ locationId: location.id, name: found.name, observedAt: now, hash: found.hash, fileCount: found.fileCount, error: found.error, availability: 'available' });
+            }
+            const observed = new Set(result.skills.map(s => s.path));
+            const locations = c.locations.filter(l => l.aliases.some(a => active.has(a.sourceId)));
+            for (const location of locations) {
+                if (observed.has(location.path))
+                    continue;
+                const old = c.observations.find(o => o.locationId === location.id);
+                if (old) {
+                    old.availability = 'unavailable';
+                    old.error = 'Not observed in this scan. The folder may be missing or inaccessible; its last known metadata is retained.';
+                }
+            }
+            const skills = locations.map(l => {
+                const o = c.observations.find(o => o.locationId === l.id);
+                const aliases = l.aliases.filter(a => active.has(a.sourceId));
+                return { skillId: l.skillId, locationId: l.id, path: l.path, name: o?.name ?? basename(l.path), sources: [...new Set(aliases.map(a => a.label))], aliases, hash: o?.hash, fileCount: o?.fileCount, error: o?.error ?? (!o ? 'Observation needs refresh.' : undefined), availability: o?.availability ?? 'unavailable' };
+            }).sort((a, b) => a.name.localeCompare(b.name) || a.path.localeCompare(b.path));
+            return { skills, warnings: result.warnings };
+        });
+    }
+    /** Warm reads use persisted observations; explicit inventory remains a full reconciliation. */
+    async cachedInventory() {
+        const c = await this.store.read();
+        const active = new Set([...this.sources(), ...rootSources(c.roots)].map(s => s.id ?? s.path));
+        const skills = c.locations.filter(l => l.aliases.some(a => active.has(a.sourceId))).map(l => {
+            const o = c.observations.find(o => o.locationId === l.id);
+            const aliases = l.aliases.filter(a => active.has(a.sourceId));
+            return { skillId: l.skillId, locationId: l.id, path: l.path, name: o?.name ?? basename(l.path), sources: [...new Set(aliases.map(a => a.label))], aliases, hash: o?.hash, fileCount: o?.fileCount, error: o?.error ?? (!o ? 'Observation needs refresh.' : undefined), availability: o?.availability ?? 'unavailable' };
+        }).sort((a, b) => a.name.localeCompare(b.name) || a.path.localeCompare(b.path));
+        return { skills, warnings: [] };
+    }
+    async discoverySources() { return [...this.sources(), ...rootSources((await this.store.read()).roots)]; }
+    /** Re-read only affected known locations, preserving identity and last known bytes on failure. */
+    async refreshLocations(ids) {
+        const before = await this.store.read();
+        const updates = await Promise.all(before.locations.filter(l => ids.includes(l.id)).map(async (l) => {
+            try {
+                const bundle = await this.ports.inspect(l.path);
+                return { locationId: l.id, name: bundle.name, hash: bundle.hash, fileCount: bundle.files.length, observedAt: Date.now(), availability: 'available' };
+            }
+            catch (error) {
+                return { ...before.observations.find(o => o.locationId === l.id), locationId: l.id, name: basename(l.path), observedAt: Date.now(), availability: 'unavailable', error: error.message };
+            }
+        }));
+        await this.store.transaction(c => {
+            if (c.revision !== before.revision)
+                throw new LocalConflictError('Skill catalog changed during refresh.');
+            for (const update of updates) {
+                c.observations = c.observations.filter(o => o.locationId !== update.locationId);
+                c.observations.push(update);
+            }
+        });
+        return this.cachedInventory();
+    }
+    /** Metadata-only explicit relocation. Never guesses identity from a name/hash or moves files. */
+    async relocateLocation(id, path) {
+        const canonical = await this.ports.resolveDirectory(path);
+        await this.ports.inspect(canonical);
+        return this.store.transaction(c => {
+            const location = c.locations.find(l => l.id === id);
+            if (!location)
+                throw new Error('Skill location not found.');
+            if (c.locations.some(l => l.path === canonical && l.id !== id))
+                throw new Error('Destination is already associated with another skill location.');
+            const sources = [...this.sources(), ...rootSources(c.roots)];
+            const scopes = sources.filter(s => pathWithin(s.path, canonical));
+            if (!scopes.length)
+                throw new Error('Register the destination folder before relocating this skill.');
+            location.path = canonical;
+            location.aliases = scopes.map(s => ({ sourceId: ('id' in s && s.id) || s.path, path: canonical, label: s.label, kind: ('kind' in s && s.kind) || 'custom' }));
+            c.observations = c.observations.filter(o => o.locationId !== id);
+            return { ...location };
+        });
+    }
+    async rebuild() { await this.store.transaction(c => { c.observations = []; }); return this.inventory(); }
+}

package/dist/local-core/skill-store.d.ts

@@ -0,0 +1,34 @@
+import type { SkillCloudBinding, SkillIdentity, SkillLocation, SkillObservation } from './skill-domain.js';
+export interface RegisteredSkillRoot {
+    id: string;
+    path: string;
+    label: string;
+    depth: number;
+    scope?: "custom" | "project";
+}
+export interface SkillCatalog {
+    schemaVersion: 2;
+    revision: number;
+    roots: RegisteredSkillRoot[];
+    identities: SkillIdentity[];
+    locations: SkillLocation[];
+    observations: SkillObservation[];
+    bindings: SkillCloudBinding[];
+}
+export interface SkillStore {
+    read(): Promise<SkillCatalog>;
+    transaction<T>(change: (catalog: SkillCatalog) => T): Promise<T>;
+}
+export declare const defaultSkillCatalogPath: () => string;
+/** Fail closed rather than silently dropping durable records from a malformed/future store. */
+export declare function validateSkillCatalog(value: unknown): asserts value is SkillCatalog;
+/** SQLite owns cross-process locking and crash rollback; no persistent lock directories. */
+export declare class SQLiteSkillStore implements SkillStore {
+    readonly path: string;
+    constructor(path?: string);
+    private exists;
+    private version;
+    private readDatabase;
+    read(): Promise<SkillCatalog>;
+    transaction<T>(change: (catalog: SkillCatalog) => T): Promise<T>;
+}

package/dist/local-core/skill-store.js

@@ -0,0 +1,187 @@
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { DatabaseSync } from 'node:sqlite';
+import { lstat, mkdir, open } from 'node:fs/promises';
+import { dirname, join, isAbsolute } from 'node:path';
+import { homedir } from 'node:os';
+export const defaultSkillCatalogPath = () => join(homedir(), '.sfora/skills/catalog.sqlite');
+const empty = () => ({ schemaVersion: 2, revision: 0, roots: [], identities: [], locations: [], observations: [], bindings: [] });
+const string = (value) => typeof value === 'string' && value.length > 0 && value.length <= 8192;
+const time = (value) => Number.isSafeInteger(value) && Number(value) >= 0;
+/** Fail closed rather than silently dropping durable records from a malformed/future store. */
+export function validateSkillCatalog(value) {
+    const c = value;
+    if (!c || c.schemaVersion !== 2)
+        throw new Error('Unsupported skill catalog schema. Keep this file and use a compatible Sfora version.');
+    if (!time(c.revision) || ![c.roots, c.identities, c.locations, c.observations, c.bindings].every(v => Array.isArray(v) && v.length <= 10000))
+        throw new Error('Invalid skill catalog structure. Original catalog was preserved.');
+    const unique = (values) => new Set(values).size === values.length;
+    if (!c.roots.every(r => r && string(r.id) && string(r.path) && isAbsolute(r.path) && string(r.label) && Number.isInteger(r.depth) && r.depth >= 0 && r.depth <= 6 && (r.scope === undefined || ["custom", "project"].includes(r.scope))) || !unique(c.roots.map(r => r.id)) || !unique(c.roots.map(r => r.path)))
+        throw new Error('Invalid registered skill roots.');
+    if (!c.identities.every(i => i && string(i.id) && time(i.createdAt)) || !unique(c.identities.map(i => i.id)))
+        throw new Error('Invalid skill identities.');
+    const identities = new Set(c.identities.map(i => i.id));
+    if (!c.locations.every(l => l && string(l.id) && identities.has(l.skillId) && string(l.path) && isAbsolute(l.path) && time(l.createdAt) && Array.isArray(l.aliases) && l.aliases.length <= 1000 && l.aliases.every(a => a && string(a.sourceId) && string(a.path) && isAbsolute(a.path) && string(a.label) && ['agent', 'cache', 'custom'].includes(a.kind))) || !unique(c.locations.map(l => l.id)) || !unique(c.locations.map(l => l.path)))
+        throw new Error('Invalid skill locations.');
+    const deployment = (value) => {
+        if (!string(value))
+            return false;
+        try {
+            const url = new URL(value);
+            return ['https:', 'http:'].includes(url.protocol) && !url.username && !url.password && url.origin === value;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (!c.bindings.every(b => b && string(b.id) && identities.has(b.localSkillId) && string(b.accountId)
+        && b.remote && deployment(b.remote.deployment) && string(b.remote.organizationId) && string(b.remote.projectId) && string(b.remote.skillId)
+        && b.locator && string(b.locator.project) && string(b.locator.name)
+        && (b.baseline === undefined || (b.baseline && b.baseline.contentPolicy === 'bundle-v1' && /^[a-f0-9]{64}$/.test(b.baseline.hash)
+            && Number.isSafeInteger(b.baseline.cloudVersion) && Number(b.baseline.cloudVersion) > 0)))
+        || !unique(c.bindings.map(b => b.id))
+        || !unique(c.bindings.map(b => JSON.stringify([b.localSkillId, b.accountId, b.remote.deployment, b.remote.organizationId, b.remote.projectId]))))
+        throw new Error('Invalid skill cloud bindings.');
+    const locations = new Set(c.locations.map(l => l.id));
+    if (!c.observations.every(o => o && locations.has(o.locationId) && string(o.name) && time(o.observedAt) && ['available', 'unavailable'].includes(o.availability) && (o.hash === undefined || /^[a-f0-9]{64}$/.test(o.hash)) && (o.fileCount === undefined || time(o.fileCount)) && (o.error === undefined || typeof o.error === 'string')) || !unique(c.observations.map(o => o.locationId)))
+        throw new Error('Invalid skill observations.');
+}
+/** SQLite owns cross-process locking and crash rollback; no persistent lock directories. */
+export class SQLiteSkillStore {
+    path;
+    constructor(path = defaultSkillCatalogPath()) {
+        this.path = path;
+    }
+    async exists() {
+        const info = await lstat(this.path).catch(error => { if (error.code === 'ENOENT')
+            return null; throw error; });
+        if (!info)
+            return false;
+        if (!info.isFile() || info.isSymbolicLink())
+            throw new Error('Skill catalog must be a regular file, not a symbolic link.');
+        if (info.size > 64 * 1024 * 1024)
+            throw new Error('Skill catalog exceeds supported size.');
+        return true;
+    }
+    version(db) { return Number(db.prepare('PRAGMA user_version').get().user_version); }
+    readDatabase(db) {
+        if (this.version(db) === 0 && db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().length === 0)
+            return empty();
+        if (![1, 2].includes(this.version(db)))
+            throw new Error('Unsupported skill catalog schema. Keep this file and use a compatible Sfora version.');
+        const rows = (table) => db.prepare(`SELECT data FROM ${table} ORDER BY rowid`).all().map(row => JSON.parse(String(row.data)));
+        const catalog = { schemaVersion: 2, revision: Number(db.prepare("SELECT value FROM metadata WHERE key='revision'").get().value), roots: rows('roots'), identities: rows('identities'), locations: rows('locations'), observations: rows('observations'), bindings: this.version(db) === 1 ? [] : rows('bindings') };
+        validateSkillCatalog(catalog);
+        return catalog;
+    }
+    async read() {
+        if (!await this.exists())
+            return empty();
+        const db = new DatabaseSync(this.path, { readOnly: true });
+        try {
+            db.exec('PRAGMA busy_timeout=5000; BEGIN');
+            const catalog = this.readDatabase(db);
+            db.exec('COMMIT');
+            return catalog;
+        }
+        finally {
+            db.close();
+        }
+    }
+    async transaction(change) {
+        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        const exists = await this.exists();
+        if (!exists) {
+            const handle = await open(this.path, 'ax', 0o600).catch(error => { if (error.code === 'EEXIST')
+                return null; throw error; });
+            await handle?.close();
+        }
+        await this.exists();
+        const db = new DatabaseSync(this.path);
+        try {
+            db.exec('PRAGMA busy_timeout=5000; PRAGMA foreign_keys=ON;');
+            // Changing journal mode on first open can return SQLITE_BUSY without using
+            // busy_timeout. Retry only before any user mutation or transaction has begun.
+            const deadline = Date.now() + 5000;
+            for (;;) {
+                try {
+                    const version = this.version(db);
+                    if (![0, 1, 2].includes(version))
+                        throw new Error('Unsupported skill catalog schema. Keep this file and use a compatible Sfora version.');
+                    // VACUUM INTO includes committed WAL pages. Reserve private permissions
+                    // before SQLite writes the backup; never copy a live database file.
+                    if (version === 1) {
+                        this.readDatabase(db);
+                        const backupPath = `${this.path}.v1-${randomUUID()}.sqlite`;
+                        const backup = await open(backupPath, 'ax', 0o600);
+                        await backup.close();
+                        db.prepare('VACUUM INTO ?').run(backupPath);
+                    }
+                    db.exec('PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; BEGIN IMMEDIATE;');
+                    break;
+                }
+                catch (error) {
+                    if (![5, 6].includes(Number(error.errcode)) || Date.now() >= deadline)
+                        throw error;
+                    await delay(25);
+                }
+            }
+            if (this.version(db) === 0) {
+                if (db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().length)
+                    throw new Error('Unrecognized skill catalog; existing tables were preserved.');
+                db.exec(`CREATE TABLE metadata (key TEXT PRIMARY KEY, value INTEGER NOT NULL);
+          INSERT INTO metadata VALUES ('revision',0);
+          CREATE TABLE roots (id TEXT PRIMARY KEY, data TEXT NOT NULL);
+          CREATE TABLE identities (id TEXT PRIMARY KEY, data TEXT NOT NULL);
+          CREATE TABLE locations (id TEXT PRIMARY KEY, skill_id TEXT NOT NULL REFERENCES identities(id), data TEXT NOT NULL);
+          CREATE TABLE observations (id TEXT PRIMARY KEY REFERENCES locations(id), data TEXT NOT NULL);
+          PRAGMA user_version=1;`);
+            }
+            if (this.version(db) === 1) {
+                db.exec(`CREATE TABLE bindings (id TEXT PRIMARY KEY, skill_id TEXT NOT NULL REFERENCES identities(id), data TEXT NOT NULL);
+          PRAGMA user_version=2;`);
+            }
+            const catalog = this.readDatabase(db);
+            const result = change(catalog);
+            if (result && typeof result.then === "function")
+                throw new Error("Skill catalog transactions must be synchronous.");
+            catalog.revision++;
+            validateSkillCatalog(catalog);
+            // Metadata tables are small; synchronize changed rows under one transaction.
+            // The service never removes durable identities during observation rebuilds.
+            const sync = (table, values) => {
+                const ids = new Set(values.map(v => v.id));
+                const remove = db.prepare(`DELETE FROM ${table} WHERE id=?`);
+                for (const row of db.prepare(`SELECT id FROM ${table}`).all())
+                    if (!ids.has(String(row.id)))
+                        remove.run(String(row.id));
+                const statement = db.prepare((table === 'locations' || table === 'bindings')
+                    ? `INSERT INTO ${table}(id,skill_id,data) VALUES (?,?,?) ON CONFLICT(id) DO UPDATE SET skill_id=excluded.skill_id,data=excluded.data WHERE data!=excluded.data`
+                    : `INSERT INTO ${table}(id,data) VALUES (?,?) ON CONFLICT(id) DO UPDATE SET data=excluded.data WHERE data!=excluded.data`);
+                for (const row of values)
+                    if ((table === 'locations' || table === 'bindings'))
+                        statement.run(row.id, row.skillId, row.data);
+                    else
+                        statement.run(row.id, row.data);
+            };
+            sync('roots', catalog.roots.map(r => ({ id: r.id, data: JSON.stringify(r) })));
+            sync('identities', catalog.identities.map(r => ({ id: r.id, data: JSON.stringify(r) })));
+            sync('locations', catalog.locations.map(r => ({ id: r.id, skillId: r.skillId, data: JSON.stringify(r) })));
+            sync('observations', catalog.observations.map(r => ({ id: r.locationId, data: JSON.stringify(r) })));
+            sync('bindings', catalog.bindings.map(r => ({ id: r.id, skillId: r.localSkillId, data: JSON.stringify(r) })));
+            db.prepare("UPDATE metadata SET value=? WHERE key='revision'").run(catalog.revision);
+            db.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { }
+            throw error;
+        }
+        finally {
+            db.close();
+        }
+    }
+}