artifacty 0.12.0 → 0.13.0

package/CLAUDE.md

@@ -18,7 +18,7 @@ For English and Korean documentation, follow the [writing style guide](docs/writ
 - `node src/mcp-server.js` or `npm run mcp` — run the MCP stdio server.
 - `node src/cli.js help` — inspect CLI usage.
 
-Run `npm run release:check` before claiming a release-ready change. There is no build step; this is plain ESM run directly by Node `>=22.5`.
+Run `npm run release:check` before claiming a release-ready change. There is no build step; this is plain ESM run directly by Node `>=22.12.0`.
 
 ## Architecture
 
@@ -43,6 +43,8 @@ The store lives at `ARTIFACTY_HOME` or `~/.artifacty` by default.
 
 Versions are append-only. To correct a historical version, use the admin repair (`replaceArtifactVersion`) or delete (`deleteArtifactVersion`) path. These paths record every change in the audit log. Do not modify prior content files through other paths.
 
+Before changing upgrade behavior, read [upgrade snapshots and recovery](docs/upgrade-backups.md). `src/lib/upgrade-backup.js` protects schema migrations with a mandatory verified snapshot. Optional application-update snapshots use `ARTIFACTY_BACKUP_ON_UPDATE=true`. Keep recovery commands independent of normal storage initialization so they cannot trigger migration. Stop every server and MCP process before restoring a store. Test recovery only with temporary stores.
+
 ### Security Model
 
 - The HTTP server binds to `127.0.0.1` by default.
@@ -55,6 +57,8 @@ Versions are append-only. To correct a historical version, use the admin repair
 
 The create/import/edit screens use CodeMirror 6 for Markdown, HTML, JSON, and text editing. CodeMirror assets are served locally through allowlisted `/vendor/npm/*` routes, not from a CDN. UI text defaults to English and supports Korean with `?lang=ko`. Keep each document in its existing language unless a translation is requested.
 
+Mermaid uses version 12.1.0 with the existing `classic` look, `dagre` layout, and `default` theme. Its browser code requires ES2024 support, such as Safari 17.4 or newer. The optional Babel 8 React renderer requires Node `^22.18.0 || >=24.11.0`.
+
 ### MCP Server
 
 The MCP server is a hand-rolled line-delimited JSON-RPC 2.0 implementation using protocol version `2025-06-18`. Tool results include both `content[].text` and `structuredContent`. Keep `artifacty_publish` as a backwards-compatible alias for `artifacty_create`.

package/README.md

@@ -3,7 +3,7 @@
 [![Publish](https://github.com/raeseoklee/artifacty/actions/workflows/publish.yml/badge.svg)](https://github.com/raeseoklee/artifacty/actions/workflows/publish.yml)
 [![npm version](https://img.shields.io/npm/v/artifacty.svg)](https://www.npmjs.com/package/artifacty)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Node.js >=22.5](https://img.shields.io/badge/node-%3E%3D22.5-339933.svg)](package.json)
+[![Node.js >=22.12.0](https://img.shields.io/badge/node-%3E%3D22.12.0-339933.svg)](package.json)
 
 Artifacty gives AI-generated artifacts a local home that agents can share. Claude, Codex, Gemini, GitHub Copilot, Cursor, and other MCP tools can publish artifacts to the same store. Other agents can find, read, and update them without copying content through chat.
 
@@ -15,11 +15,13 @@ Artifacts turn session output into shareable, versioned pages. Artifacty keeps t
 
 ## Installation
 
-Artifacty requires Node.js 22.5 or newer.
+Artifacty requires Node.js 22.12.0 or newer.
 
 The optional React renderer uses Babel 8. Its supported Node.js versions are
 `^22.18.0 || >=24.11.0`. Use a compatible version if you enable that renderer.
 
+The browser renderer uses Mermaid 12.1.0. Use a current browser with ES2024 support, such as Safari 17.4 or newer. Mermaid keeps the `classic` look, `dagre` layout, and `default` theme.
+
 Install the CLI globally from npm:
 
 ```bash
@@ -298,6 +300,16 @@ artifacty index rebuild
 artifacty integrity
 ```
 
+### Upgrade Snapshots
+
+Before an existing store needs a schema migration, Artifacty creates and verifies a mandatory local snapshot. The snapshot includes the raw SQLite database, referenced version files, and legacy index. If snapshot verification fails, migration stops.
+
+Set `ARTIFACTY_BACKUP_ON_UPDATE=true` to also snapshot application-version changes. If an existing store has no recorded application version, its first open with this setting creates a baseline snapshot. `ARTIFACTY_UPGRADE_BACKUP_KEEP` retains the latest three automatic snapshots by default (valid range: 1–1000).
+
+Use `artifacty backups list`, `artifacty backups verify <id>`, and `artifacty backups restore <id> --confirm restore-store`. Stop every server and MCP process before an upgrade or restore. Restore creates a recovery snapshot before replacing the store. It also restores credentials and security state; previously revoked sessions, tokens, and links can become valid again.
+
+These local snapshots are separate from portable `artifacty backup`/`export` JSON bundles. See [upgrade snapshots and recovery](docs/upgrade-backups.md) for verification, corrupt-store recovery, and interrupted-restore procedures.
+
 ### Semantic Search
 
 `?mode=keyword|semantic|hybrid` on `GET /api/artifacts`, the dashboard, `artifacty list --mode`, and the MCP `artifacty_list` tool add optional natural-language search on top of FTS5, without any bundled model or mandatory dependency:
@@ -705,6 +717,8 @@ The table lists every `ARTIFACTY_*` variable that Artifacty reads. `node src/cli
 | Variable | Purpose | Default |
 | --- | --- | --- |
 | `ARTIFACTY_HOME` | Storage directory | `~/.artifacty` |
+| `ARTIFACTY_BACKUP_ON_UPDATE` | Snapshot existing stores before application-version changes; schema-migration snapshots are always required | `false` |
+| `ARTIFACTY_UPGRADE_BACKUP_KEEP` | Automatic upgrade snapshots to retain; integer from 1 to 1000 | `3` |
 | `ARTIFACTY_URL` | Public URL override; otherwise CLI/MCP read the last running server URL | — |
 | `ARTIFACTY_HOST` | Bind host for the HTTP server | `127.0.0.1` |
 | `ARTIFACTY_PORT` | Bind port for the HTTP server | `8787` |

package/docs/integrations.md

@@ -2,6 +2,8 @@
 
 Artifacty exposes one shared MCP stdio server and one local browser server.
 
+Use Node.js 22.12.0 or newer. The optional Babel 8 React renderer requires Node `^22.18.0 || >=24.11.0`. Mermaid 12.1.0 requires an ES2024-capable browser, such as Safari 17.4 or newer.
+
 ## Start the Browser Server
 
 ```bash
@@ -418,3 +420,5 @@ in one JSON bundle. It excludes users, sessions, API token records, and audit
 logs. A store import replaces the target artifact records and removes
 unreferenced version files. Before importing, select a new or intended
 `ARTIFACTY_HOME`.
+
+Upgrade snapshots protect schema migrations and optionally application updates. They preserve raw database security state and differ from JSON export backups. Stop all server and MCP processes before recovery. See [upgrade snapshots and recovery](upgrade-backups.md).

package/docs/release-checklist.md

@@ -23,6 +23,11 @@ Run the local diagnostics pass:
 artifacty doctor
 ```
 
+- Verify recovery commands against temporary stores only. See [upgrade snapshots and recovery](upgrade-backups.md).
+- Confirm mandatory schema snapshots complete before migrations change the store.
+- Check the Node.js 22.12.0 minimum. The optional Babel 8 renderer requires Node `^22.18.0 || >=24.11.0`.
+- Check Mermaid 12.1.0 in an ES2024-capable browser. Preserve its `classic` look, `dagre` layout, and `default` theme.
+
 ## Packaging
 
 - Confirm `package.json` `version` and `files` are intentional.

package/docs/upgrade-backups.md

@@ -0,0 +1,89 @@
+# Upgrade Snapshots and Recovery
+
+Artifacty creates a local snapshot before it migrates an existing store to a newer schema. This snapshot is mandatory. If snapshot creation or verification fails, Artifacty stops before migration.
+
+Use upgrade snapshots to recover the original store state. Use `artifacty backup` and `artifacty export` for portable JSON backups and store transfers. These are separate backup systems. `artifacty restore <id>` restores an archived artifact; it does not restore a store snapshot.
+
+## When Artifacty Creates a Snapshot
+
+- **Schema migration:** Artifacty always snapshots an existing store before migration. This includes a legacy `index.json` store. A new empty store needs no snapshot.
+- **Application update:** Set `ARTIFACTY_BACKUP_ON_UPDATE=true` to also snapshot an existing store when the application version changes. This setting is off by default.
+- **Unknown application version:** With the update setting enabled, the first open of an existing store without an application-version marker creates a baseline snapshot. Its source application version is unknown. Later opens with the same version do not repeat it.
+- **Restore:** Before replacing a store, Artifacty creates and verifies a recovery snapshot of its current state.
+
+Stop every HTTP server and MCP process that uses the store before an upgrade or restore. This includes services, foreground servers, and local stdio MCP clients. Artifacty checks managed server PID markers, but these markers cannot identify every process with an open store.
+
+Snapshots are stored at `ARTIFACTY_HOME/upgrade-backups/<id>/`. The default home is `~/.artifacty`.
+
+## Snapshot Contents
+
+Each snapshot contains a manifest with file sizes and SHA-256 hashes. It also contains:
+
+- A consistent raw SQLite database, including all tables and security state.
+- Every version file referenced by the database or an authoritative legacy index.
+- The legacy `index.json`, if it exists.
+
+Verification checks the file hashes, SQLite integrity, and version-file references. Snapshots do not include unrelated files, process markers, logs, or the complete installation directory. Keep snapshots private: they contain credentials and security records.
+
+`ARTIFACTY_UPGRADE_BACKUP_KEEP` controls automatic snapshot retention. The default is `3`; valid values are integers from `1` through `1000`. Artifacty prunes older automatic schema/update snapshots after a successful upgrade. It does not prune manual or recovery snapshots with this setting.
+
+## Inspect Snapshots
+
+List snapshots without opening or migrating the store:
+
+```bash
+artifacty backups list --home /path/to/store
+```
+
+Copy an `id` from the output. Verify that snapshot:
+
+```bash
+artifacty backups verify <id> --home /path/to/store
+```
+
+A successful response includes `valid: true`. Listing checks manifests; it does not replace full verification. From a repository checkout, use `node src/cli.js` in place of `artifacty`.
+
+## Restore a Snapshot
+
+A restore replaces the current database, version files, and legacy index. Changes made after the snapshot are no longer current. Artifacty keeps the pre-restore state in a separate recovery snapshot.
+
+**Security state also rolls back.** Old passwords, permissions, network rules, sessions, API tokens, and share-link records can become current again. A session, token, or link revoked after the snapshot can become valid again if it has not expired. Review the restored security state before allowing users to reconnect.
+
+1. Stop all server, service, and MCP processes that use this store.
+2. Select a snapshot from `backups list`.
+3. Verify it with `backups verify`.
+4. Restore it with explicit confirmation:
+
+```bash
+artifacty backups restore <id> --confirm restore-store --home /path/to/store
+```
+
+5. Save the returned `recoveryBackupId`.
+6. Review the restored security settings before reconnecting clients.
+
+Restore does not migrate the selected snapshot. Opening it with the current application can trigger another protected migration. A build that does not support the restored schema rejects the store.
+
+## Recover When the Current Store Is Corrupt
+
+If Artifacty cannot verify the current store for its recovery snapshot, it returns `RECOVERY_BACKUP_FAILED`. It does not overwrite the damaged store.
+
+1. Keep the damaged home and its snapshots unchanged.
+2. Create a new empty home directory.
+3. Copy the selected snapshot directory into the new home's `upgrade-backups/` directory. Preserve its original snapshot ID and directory contents.
+4. Run `backups verify <id> --home /path/to/new-home`.
+5. Run `backups restore <id> --confirm restore-store --home /path/to/new-home`.
+6. Review the restored data and security settings before using the new home.
+
+Do not copy the damaged database over the new home. The selected snapshot supplies the database and referenced version files.
+
+## Recover an Interrupted Restore
+
+If a `.restore-<uuid>` directory remains, Artifacty stops with `RESTORE_INCOMPLETE`.
+
+1. Preserve that directory and the entire affected home.
+2. Read `.restore-<uuid>/restore.json`.
+3. Find its `recoveryBackupId`. This identifies the snapshot of the state before the interrupted restore.
+4. Copy that recovery snapshot into a new empty home's `upgrade-backups/` directory.
+5. Verify and restore it there with the commands above.
+
+Do not remove the interrupted restore directory to bypass the check. It contains recovery evidence and can contain the previous database and files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artifacty",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Local artifact exchange for heterogeneous LLM agents via HTTP and MCP.",
   "type": "module",
   "keywords": [
@@ -44,6 +44,7 @@
     "docs/roadmap-design.md",
     "docs/sarif-csv-artifact-plan.md",
     "docs/threat-model.md",
+    "docs/upgrade-backups.md",
     "docs/writing-style.md",
     "scripts/lint.mjs",
     "scripts/smoke.sh",
@@ -55,7 +56,7 @@
     "CLAUDE.md"
   ],
   "engines": {
-    "node": ">=22.5"
+    "node": ">=22.12"
   },
   "license": "MIT",
   "dependencies": {
@@ -64,7 +65,7 @@
     "@codemirror/lang-json": "^6.0.2",
     "@codemirror/lang-markdown": "^6.5.0",
     "codemirror": "^6.0.2",
-    "mermaid": "^11.15.0"
+    "mermaid": "^12.1.0"
   },
   "optionalDependencies": {
     "@babel/standalone": "^8.0.4",

package/src/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { generateToken } from "./lib/token.js";
 import { parseSseFrames } from "./lib/sse.js";
@@ -32,6 +33,27 @@ async function main() {
     return;
   }
 
+  // Recovery must work before loading storage or triggering a schema migration.
+  if (command === "backups") {
+    const { listUpgradeBackups, verifyUpgradeBackup, restoreUpgradeBackup } = await import("./lib/upgrade-backup.js");
+    const store = { home: path.resolve(options.home || process.env.ARTIFACTY_HOME || path.join(homedir(), ".artifacty")) };
+    const [action, id, ...extra] = options._;
+    if (extra.length || !["list", "verify", "restore"].includes(action) || (action === "list" ? Boolean(id) : !id)) {
+      throw new Error("Usage: artifacty backups list | verify <id> | restore <id> --confirm restore-store");
+    }
+    if (action === "list") {
+      printJson({ backups: listUpgradeBackups(store) });
+    } else if (action === "verify") {
+      printJson(verifyUpgradeBackup(store, id));
+    } else {
+      if (options.confirm !== "restore-store") {
+        throw new Error("Store recovery requires --confirm restore-store. Stop all server and MCP processes before restoring.");
+      }
+      printJson(restoreUpgradeBackup(store, id, { confirm: options.confirm }));
+    }
+    return;
+  }
+
   const {
     addComment,
     addRelation,
@@ -982,6 +1004,9 @@ Usage:
   artifacty retention run [--dry-run] [--allow-purge]
   artifacty export --file <path> [--full]
   artifacty backup [--file <path>] [--full]
+  artifacty backups list [--home <path>]
+  artifacty backups verify <id> [--home <path>]
+  artifacty backups restore <id> --confirm restore-store [--home <path>]
   artifacty import-store --file <path> [--confirm replace-all] [--force-users]
   artifacty users import --file <path.csv> [--no-password-reset]
   artifacty service plist|unit|task|install|uninstall [--platform macos|linux|windows] [--dry-run] [--path <path>] [--mcp-http]
@@ -1000,8 +1025,17 @@ Usage:
   artifacty diff <id> [--from N] [--to M] [--structured] [--json]
   artifacty watch [--tag tag] [--artifact <id>] [--type artifact.updated] [--json] [--once] [--exec "<cmd>"]
 
+Upgrade recovery:
+  Existing stores receive a mandatory snapshot before a schema migration.
+  Set ARTIFACTY_BACKUP_ON_UPDATE=true to also snapshot before app-version changes.
+  backups list and verify do not migrate the store.
+  Stop all server and MCP processes before backups restore. Restore preserves a recovery snapshot.
+  artifacty restore <id> restores an archived artifact, not a store backup.
+
 Environment:
   ARTIFACTY_HOME           Storage directory. Defaults to ~/.artifacty
+  ARTIFACTY_BACKUP_ON_UPDATE  Set true for optional app-version snapshots; schema backups are mandatory
+  ARTIFACTY_UPGRADE_BACKUP_KEEP  Automatic snapshots to retain after a successful upgrade (default: 3)
   ARTIFACTY_URL            Public URL override. Otherwise CLI/MCP read the last running server URL
   ARTIFACTY_HOST           Bind host for the HTTP server. Defaults to 127.0.0.1
   ARTIFACTY_PORT           Bind port for the HTTP server. Defaults to 8787

package/src/lib/doctor.js

@@ -9,7 +9,7 @@ import { securityConfig, validateServerExposure, exposureWarning } from "./secur
 import { serviceCommand } from "./service.js";
 import { checkStoreIntegrity, createStore } from "./storage.js";
 
-const MIN_NODE_VERSION = "22.5.0";
+const MIN_NODE_VERSION = "22.12.0";
 
 export async function runDoctor(options = {}) {
   const packageRoot = path.resolve(options.packageRoot || process.cwd());

package/src/lib/render.js

@@ -3346,7 +3346,7 @@ function mermaidFrameContent(content) {
       parent.postMessage({ __artifactyHeight: height }, "*");
     }
     try {
-      mermaid.initialize({ startOnLoad: false, securityLevel: "strict" });
+      mermaid.initialize({ startOnLoad: false, securityLevel: "strict", layout: "dagre", theme: "default", look: "classic" });
       const result = await mermaid.render("artifacty-mermaid-svg", source);
       target.innerHTML = result.svg;
     } catch (error) {

package/src/lib/sample-content.js

@@ -12,7 +12,7 @@ Artifacty keeps agent outputs in one versioned store. You can use the store thro
 
 ## Start locally
 
-Use Node.js 22.5 or newer. From the repository, run:
+Use Node.js 22.12.0 or newer. The optional Babel 8 React renderer requires Node 22.18.x or newer within Node 22, or Node 24.11.0 or newer. Use an ES2024-capable browser, such as Safari 17.4 or newer, for Mermaid 12.1.0 diagrams. The classic look, dagre layout, and default theme stay unchanged. From the repository, run:
 
 \`\`\`sh
 npm install
@@ -50,7 +50,13 @@ A share link is a separate read-only capability with an expiry time. It does not
 
 \`node src/cli.js samples install\` installs these four manuals once per installation scope. Repeating installation skips active manuals. \`samples remove\` archives managed samples. It preserves their content and versions. Installing again restores them without replacing your edits. Matching titles or tags do not make your own artifacts managed samples.
 
-Back up before maintenance. This build uses store schema 10. Older builds refuse newer stores. This manual describes the implemented repository behavior, not a package release announcement.`
+Back up before maintenance. This build uses store schema 10. Older builds refuse newer stores. This manual describes the implemented repository behavior, not a package release announcement.
+
+Before migrating an existing schema, Artifacty creates a mandatory verified snapshot of the raw SQLite database, referenced version files, and legacy index. Set ARTIFACTY_BACKUP_ON_UPDATE=true to also snapshot application-version changes. If the old application version is unknown, the first open creates a baseline snapshot. ARTIFACTY_UPGRADE_BACKUP_KEEP defaults to 3 automatic snapshots and accepts 1–1000.
+
+Use \`artifacty backups list\`, \`artifacty backups verify <id>\`, and \`artifacty backups restore <id> --confirm restore-store\`. Stop every server and MCP process first. Restore creates a recovery snapshot before replacing the store. It also restores credentials and security state, so previously revoked sessions, tokens, and links can become valid again. These snapshots differ from portable JSON export backups.
+
+If the current store is corrupt, preserve it and copy the selected snapshot to a new empty home before restoring there. If a restore leaves a .restore-* directory, preserve it. Read its restore.json recoveryBackupId and restore that recovery snapshot into a new empty home. See docs/upgrade-backups.md in the repository for the full procedure.`
   },
   {
     key: "feature-guide",
@@ -61,13 +67,13 @@ Back up before maintenance. This build uses store schema 10. Older builds refuse
     content: `<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Artifacty feature guide</title>
 <style>body{font-family:system-ui,sans-serif;line-height:1.65;color:#172b3a;background:#f5f7fa;margin:0}main{max-width:900px;margin:auto;padding:40px 24px}h1,h2{line-height:1.2}h1{font-size:2.4rem}section{background:white;border:1px solid #dce4ec;border-radius:12px;padding:24px;margin:20px 0}code{background:#edf2f7;padding:2px 5px;border-radius:4px}li{margin:6px 0}a{color:#175aa3}footer{color:#526475}</style></head><body><main>
-<header><p>ARTIFACTY / REFERENCE</p><h1>From an agent output to a shared record</h1><p>Use this inventory to choose the right publishing, review, access, and maintenance workflow. Use Node.js 22.5 or newer. The current store schema is 10.</p></header>
+<header><p>ARTIFACTY / REFERENCE</p><h1>From an agent output to a shared record</h1><p>Use this inventory to choose the right publishing, review, access, and maintenance workflow. Use Node.js 22.12.0 or newer. The current store schema is 10. Mermaid 12.1.0 keeps the classic look, dagre layout, and default theme. Use an ES2024-capable browser, such as Safari 17.4 or newer. The optional Babel 8 React renderer requires Node ^22.18.0 or &gt;=24.11.0.</p></header>
 <nav aria-label="Guide sections"><a href="#formats">Formats</a> · <a href="#history">History and discovery</a> · <a href="#collaboration">Collaboration</a> · <a href="#access">Access</a> · <a href="#operations">Operations</a></nav>
 <section id="formats"><h2>Formats and imports</h2><p>The 13 formats are HTML, Markdown, text, JSON, code, SVG, Mermaid, React, SARIF, CSV, image, video, and notebook. Choose an artifact type separately: a document, handoff, code review, test report, dashboard, diagram, component, table, or another supported type.</p><p>Bundles group multiple files under one artifact. Supported binary bundle assets include PDF, DOCX, XLSX, and ZIP. Importers normalize outputs from Claude, Codex, Gemini, GitHub Copilot, Cursor, and generic inputs. Use the browser import screen or <code>artifacty import --agent codex --file handoff.md</code>.</p><p>Artifact content is untrusted. Browser previews use constrained rendering. A public HTML share preview is static. It blocks scripts and external resource loading. Share links show other active formats as source. Do not expect those previews to preserve interactive application behavior.</p></section>
 <section id="history"><h2>Versions, discovery, and retrieval</h2><ul><li>Updates create versions with immutable content files. You can read a historical version and compare versions with a diff. To avoid overwriting a concurrent edit, use an expected-version check.</li><li>Archive and restore artifacts instead of losing their history. Integrity checks verify stored files, hashes, and orphaned files.</li><li>Search by keyword and filter by tags, source agent, artifact type, publisher, dates, review status, relationships, and archive state. Pagination and grouping help you use large lists. To reuse a set of filters, save it as a view.</li><li>When available, SQLite FTS5 accelerates keyword search. Otherwise, search uses metadata. Optional embeddings enable semantic and hybrid search. Without a configured provider, those modes use keyword search. Rebuild search or embedding indexes after configuration changes.</li></ul></section>
 <section id="collaboration"><h2>Relationships, comments, review, and notifications</h2><p>Connect artifacts using derived-from, supersedes, reviews, references, or part-of relations. Comments support threads and anchors. After you address a thread, resolve it. Review status progresses among none, pending, changes-requested, and approved.</p><p>The inbox at <code>/inbox</code> collects relevant shares, comments, review activity, and new versions. Notifications depend on the user and current artifact access. You can mark items read individually or together. A notification does not grant access.</p><p>Audit records support investigation. Event polling and server-sent events expose authorized activity streams. Webhooks deliver configured events to validated destinations. Use event filters, replay cursors, and webhook administration for integrations.</p></section>
 <section id="access"><h2>Accounts, permissions, share links, and network rules</h2><p>Create the initial administrator at <code>/login</code>. Administrators manage accounts at <code>/admin/users</code>. The Access page links to that page. Administrators manage teams, access mode, and network rules at <code>/admin/access</code>. The artifact <strong>Sharing</strong> panel shows effective access and its sources. Direct-user and team grants support read, comment, and edit. Where grants overlap, the strongest permission wins. Ownership and administrator management are separate from grants. Token scopes limit token actions. They do not grant artifact access.</p><p>Private mode requires an active personal account. Server-wide tokens do not authorize ordinary artifact reads or creation in private mode. Administrator APIs have their own authorization rules. Personal tokens remain constrained by both their scopes and the user's artifact permissions. Trusted local CLI operations can administer the local store directly.</p><p>Read-only share links default to seven days and can target the latest version or a pinned version. Share links while the server is in private mode require explicit administrator opt-in. In public mode, owners may link private-visibility artifacts without that site toggle. Links can be revoked, and owner changes invalidate them. A valid capability permits only its read-only shared surface.</p><p>Network allow rules accept IP addresses and CIDRs. First, stage a change. Next, verify access from the intended peer. Then confirm the change within 120 seconds or roll it back. Pending state survives a restart. Before the next access, the server checks for expiry. If the change has expired, the server restores the previous rules. Rules use the socket peer address, not forwarded proxy headers.</p></section>
-<section id="operations"><h2>Interfaces and maintenance</h2><ul><li>The browser supports creation, import, viewing, editing, discovery, review, inbox, and administration.</li><li>The CLI supports serve/start/stop/status, publish/import/update/read/list, history and diff, relations/comments/review, saved views, event watching, account import, backup, retention, indexes, integrity, and diagnostics. Run <code>artifacty help</code> for exact flags.</li><li>The JSON API exposes artifacts and operational endpoints under <code>/api/</code>. MCP exposes agent tools through stdio and optional HTTP transport. Use <code>artifacty install claude --dry-run</code> to inspect integration configuration and <code>artifacty check</code> to verify tool discovery.</li><li>Export and import backups to move or recover a store. Retention supports archive rules, archived-item purge, audit/event history limits, and protected tags. Before an intentional purge, inspect a dry run.</li><li><code>artifacty samples install</code> installs these manuals idempotently. <code>artifacty samples remove</code> archives only managed samples in the current scope. Reinstallation restores existing versions and user edits.</li></ul><p>Keep ARTIFACTY_HOME private. Older builds refuse schema-10 stores. Before changing builds, preserve a backup. Consult repository integration documentation for concrete agent and API examples.</p></section>
+<section id="operations"><h2>Interfaces and maintenance</h2><ul><li>The browser supports creation, import, viewing, editing, discovery, review, inbox, and administration.</li><li>The CLI supports serve/start/stop/status, publish/import/update/read/list, history and diff, relations/comments/review, saved views, event watching, account import, backup, retention, indexes, integrity, and diagnostics. Run <code>artifacty help</code> for exact flags.</li><li>The JSON API exposes artifacts and operational endpoints under <code>/api/</code>. MCP exposes agent tools through stdio and optional HTTP transport. Use <code>artifacty install claude --dry-run</code> to inspect integration configuration and <code>artifacty check</code> to verify tool discovery.</li><li>Export and import JSON backups to move a store. Upgrade snapshots separately preserve raw SQLite, referenced versions, and any legacy index. Schema migrations always require a verified snapshot. Set <code>ARTIFACTY_BACKUP_ON_UPDATE=true</code> for application-version snapshots, including an unknown-version baseline. <code>ARTIFACTY_UPGRADE_BACKUP_KEEP</code> defaults to 3 and accepts 1–1000.</li><li>Use <code>artifacty backups list</code>, <code>artifacty backups verify &lt;id&gt;</code>, and <code>artifacty backups restore &lt;id&gt; --confirm restore-store</code>. Stop every server and MCP process first. Restore saves a recovery snapshot and rolls back credentials and security state. Revoked sessions, tokens, or links can become valid again. For a corrupt store, copy the snapshot to a new empty home and restore there. Preserve interrupted <code>.restore-*</code> directories and use their <code>restore.json</code> recoveryBackupId. See <code>docs/upgrade-backups.md</code>.</li><li>Retention supports archive rules, archived-item purge, audit/event history limits, and protected tags. Before an intentional purge, inspect a dry run.</li><li><code>artifacty samples install</code> installs these manuals idempotently. <code>artifacty samples remove</code> archives only managed samples in the current scope. Reinstallation restores existing versions and user edits.</li></ul><p>Keep ARTIFACTY_HOME private. Older builds refuse schema-10 stores. Before changing builds, preserve a backup. Consult repository integration documentation for concrete agent and API examples.</p></section>
 <footer><p>This guide is a managed sample artifact. Editing it creates your own version. Reinstalling samples preserves that work.</p></footer>
 </main></body></html>`
   },

package/src/lib/storage.js

@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, s
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
-import { DatabaseSync } from "node:sqlite";
+import { openProtectedDatabase } from "./upgrade-backup.js";
 import { isUnknownSourceAgent, normalizeSourceAgent } from "./agents.js";
 import { assertNoSecrets, normalizeTokenScopes, securityConfig } from "./security.js";
 import { EVENT_TYPES, eventFromAudit, eventHistoryLimit, eventVisibleTo, matchesFilter, publish as publishEvent } from "./events.js";
@@ -3630,11 +3630,7 @@ export function normalizeArtifactType(value = "document") {
 // same connection setup (PRAGMAs, schema init/migration) instead of opening
 // a second, differently-configured DatabaseSync against the same file.
 export function openDatabase(store) {
-  mkdirSync(store.home, { recursive: true });
-  mkdirSync(store.artifactsDir, { recursive: true });
-
-  const db = new DatabaseSync(store.dbPath);
-  try {
+  return openProtectedDatabase(store, STORE_VERSION, (db) => {
     db.exec(`
       PRAGMA journal_mode = WAL;
       PRAGMA foreign_keys = ON;
@@ -3644,13 +3640,7 @@ export function openDatabase(store) {
     migrateJsonIndex(db, store);
     normalizeStoredSourceAgents(db, store);
     syncSearchIndexIfEmpty(db, store);
-  } catch (error) {
-    // Never leak an open handle when initialization fails (for example the
-    // store_version guard); on Windows an open handle blocks file removal.
-    db.close();
-    throw error;
-  }
-  return db;
+  });
 }
 
 function initializeSchema(db) {

package/src/lib/upgrade-backup.js

@@ -0,0 +1,417 @@
+import { randomUUID, createHash } from "node:crypto";
+import {
+  closeSync, copyFileSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync,
+  readFileSync, readdirSync, renameSync, rmSync, writeFileSync, chmodSync
+} from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+
+const APP_VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+const KIND = "artifacty-upgrade-backup";
+const ID_PATTERN = /^(auto|manual|recovery)-[0-9T-]+-[a-f0-9-]{36}$/;
+const wait = new Int32Array(new SharedArrayBuffer(4));
+
+function error(message, code = "UPGRADE_BACKUP_FAILED") {
+  return Object.assign(new Error(message), { code });
+}
+
+function paths(store) {
+  const home = path.resolve(store.home);
+  return { home, dbPath: path.join(home, "artifacty.sqlite"), indexPath: path.join(home, "index.json"), artifactsDir: path.join(home, "artifacts"), backups: path.join(home, "upgrade-backups") };
+}
+
+function safePath(root, relative) {
+  if (typeof relative !== "string" || !relative || path.isAbsolute(relative) || relative.includes("\\") || relative.split("/").some((part) => !part || part === "." || part === "..")) {
+    throw error(`Unsafe snapshot path: ${relative}`);
+  }
+  const target = path.resolve(root, relative);
+  if (!target.startsWith(`${path.resolve(root)}${path.sep}`)) throw error("Snapshot path escapes its root");
+  let current = root;
+  for (const part of relative.split("/")) {
+    current = path.join(current, part);
+    try {
+      if (lstatSync(current).isSymbolicLink()) throw error(`Snapshot paths must not contain symbolic links: ${current}`);
+    } catch (cause) { if (cause.code !== "ENOENT") throw cause; }
+  }
+  return target;
+}
+
+function privateDirectory(directory) {
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const stat = lstatSync(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw error(`Expected a real directory: ${directory}`);
+  chmodSync(directory, 0o700);
+}
+
+function alive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (cause) { return cause.code !== "ESRCH"; }
+}
+
+function assertOffline(store, allowOwnPid = false) {
+  for (const filename of ["server.pid", "server.json"]) {
+    const file = safePath(store.home, filename);
+    if (!existsSync(file)) continue;
+    let pid;
+    try {
+      const text = readFileSync(file, "utf8");
+      pid = filename.endsWith(".json") ? JSON.parse(text).pid : Number(text.trim());
+    } catch { throw error(`Cannot inspect ${filename}; stop the server and repair this marker first`, "STORE_NOT_OFFLINE"); }
+    if (alive(pid) && !(allowOwnPid && pid === process.pid)) throw error("Stop the managed Artifacty server before upgrading or restoring this store", "STORE_NOT_OFFLINE");
+  }
+}
+
+function durableWrite(file, content) {
+  const fd = openSync(file, "wx", 0o600);
+  try { writeFileSync(fd, content); fsyncSync(fd); } finally { closeSync(fd); }
+}
+
+function syncDirectory(directory) {
+  if (process.platform === "win32") return;
+  const fd = openSync(directory, "r");
+  try { fsyncSync(fd); } finally { closeSync(fd); }
+}
+
+function syncTree(directory) {
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const file = path.join(directory, entry.name);
+    if (entry.isDirectory()) syncTree(file);
+    else {
+      const fd = openSync(file, "r+");
+      try { fsyncSync(fd); } finally { closeSync(fd); }
+    }
+  }
+  syncDirectory(directory);
+}
+
+// A separate reaper guard serializes removal of dead-owner locks. A malformed
+// lock or an abandoned reaper fails closed; it is never guessed to be stale.
+function lockStore(store) {
+  privateDirectory(store.home);
+  const lock = safePath(store.home, ".upgrade.lock");
+  const reaper = safePath(store.home, ".upgrade-reaper");
+  const token = randomUUID();
+  const deadline = Date.now() + 5000;
+  const acquire = () => {
+    durableWrite(lock, JSON.stringify({ pid: process.pid, token, createdAt: new Date().toISOString() }));
+    return () => {
+      const current = JSON.parse(readFileSync(lock, "utf8"));
+      if (current.token !== token) throw error("Store lock ownership changed");
+      rmSync(lock);
+    };
+  };
+  while (true) {
+    if (!existsSync(reaper)) {
+      try { return acquire(); } catch (cause) { if (cause.code !== "EEXIST") throw cause; }
+      let owner;
+      try { owner = JSON.parse(readFileSync(lock, "utf8")); }
+      catch (cause) {
+        if (cause.code === "ENOENT") continue;
+        if (Date.now() >= deadline) throw error("Unreadable upgrade lock; inspect .upgrade.lock before retrying", "STORE_LOCKED");
+        Atomics.wait(wait, 0, 0, 25);
+        continue;
+      }
+      if (!Number.isInteger(owner.pid) || !owner.token) throw error("Invalid upgrade lock; inspect .upgrade.lock before retrying", "STORE_LOCKED");
+      if (!alive(owner.pid)) {
+        try { mkdirSync(reaper, { mode: 0o700 }); }
+        catch (cause) { if (cause.code === "EEXIST") continue; throw cause; }
+        try {
+          if (existsSync(lock)) {
+            const current = JSON.parse(readFileSync(lock, "utf8"));
+            if (current.token === owner.token && !alive(current.pid)) rmSync(lock);
+          }
+          if (!existsSync(lock)) return acquire();
+        } finally { rmSync(reaper, { recursive: true }); }
+      }
+    }
+    if (Date.now() >= deadline) throw error("Store upgrade or restore is already running; inspect .upgrade.lock and .upgrade-reaper if its owner has stopped", "STORE_LOCKED");
+    Atomics.wait(wait, 0, 0, 25);
+  }
+}
+
+function rawState(store) {
+  safePath(store.home, "artifacty.sqlite");
+  safePath(store.home, "index.json");
+  if (!existsSync(store.dbPath) || lstatSync(store.dbPath).size === 0) return { schemaVersion: null, appVersion: null, hasDatabase: false, hasData: existsSync(store.indexPath) };
+  safePath(store.home, "artifacty.sqlite");
+  const db = new DatabaseSync(store.dbPath, { readOnly: true });
+  try {
+    const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'").all();
+    const hasMeta = tables.some((table) => table.name === "meta");
+    const schema = hasMeta ? db.prepare("SELECT value FROM meta WHERE key='store_version'").get()?.value : null;
+    const app = hasMeta ? db.prepare("SELECT value FROM meta WHERE key='application_version'").get()?.value : null;
+    if (schema != null && (!/^\d+$/.test(String(schema)) || !Number.isSafeInteger(Number(schema)))) throw error("Invalid stored schema version");
+    return { schemaVersion: schema == null ? null : Number(schema), appVersion: app || null, hasDatabase: true, hasData: tables.length > 0 || existsSync(store.indexPath) };
+  } finally { db.close(); }
+}
+
+function fileInfo(file) {
+  const stat = lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw error(`Expected a regular file: ${file}`);
+  return { sizeBytes: stat.size, sha256: createHash("sha256").update(readFileSync(file)).digest("hex") };
+}
+
+function references(database, indexFile) {
+  const refs = new Map();
+  const add = (row) => {
+    const versionPath = typeof row.path === "string" ? row.path.replaceAll("\\", "/") : "";
+    if (!versionPath.startsWith("artifacts/")) throw error("Version path must be inside artifacts/");
+    const expected = { path: versionPath, sizeBytes: row.size_bytes ?? row.sizeBytes, sha256: row.sha256 };
+    if (!Number.isSafeInteger(expected.sizeBytes) || expected.sizeBytes < 0 || !/^[a-f0-9]{64}$/i.test(expected.sha256 || "")) throw error(`Invalid version size or hash: ${row.path}`);
+    const previous = refs.get(versionPath);
+    if (previous && (previous.sha256 !== expected.sha256 || previous.sizeBytes !== expected.sizeBytes)) throw error("Conflicting version file references");
+    refs.set(versionPath, expected);
+  };
+  let legacyAlreadyImported = false;
+  if (database) {
+    const db = new DatabaseSync(database, { readOnly: true });
+    try {
+      const result = db.prepare("PRAGMA integrity_check").all();
+      if (result.length !== 1 || Object.values(result[0])[0] !== "ok") throw error("Snapshot SQLite integrity check failed");
+      if (db.prepare("SELECT name FROM sqlite_master WHERE name='artifact_versions'").get()) {
+        for (const row of db.prepare("SELECT path, size_bytes, sha256 FROM artifact_versions").all()) add(row);
+      }
+      if (db.prepare("SELECT name FROM sqlite_master WHERE name='artifacts'").get()) {
+        legacyAlreadyImported = db.prepare("SELECT COUNT(*) AS count FROM artifacts").get().count > 0;
+      }
+      if (db.prepare("SELECT name FROM sqlite_master WHERE name='meta'").get()) {
+        legacyAlreadyImported ||= db.prepare("SELECT value FROM meta WHERE key='json_index_migrated'").get()?.value === "true";
+      }
+    } finally { db.close(); }
+  }
+  // A legacy index is authoritative only before its import into SQLite.
+  if (indexFile && !legacyAlreadyImported) {
+    const index = JSON.parse(readFileSync(indexFile, "utf8"));
+    if (!Array.isArray(index.artifacts)) throw error("Invalid legacy index");
+    for (const artifact of index.artifacts) for (const version of artifact.versions || []) add(version);
+  }
+  return [...refs.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+
+function compareFile(root, expected) {
+  const actual = fileInfo(safePath(root, expected.path));
+  if (actual.sizeBytes !== expected.sizeBytes || actual.sha256 !== expected.sha256) throw error(`Snapshot file verification failed: ${expected.path}`);
+}
+
+function snapshotDirectory(store, id) {
+  if (!ID_PATTERN.test(id || "")) throw error("Invalid snapshot id");
+  return safePath(store.home, `upgrade-backups/${id}`);
+}
+
+function manifestAt(store, id) {
+  const directory = snapshotDirectory(store, id);
+  const manifest = JSON.parse(readFileSync(safePath(directory, "manifest.json"), "utf8"));
+  if (manifest.kind !== KIND || manifest.manifestVersion !== 1 || manifest.id !== id || !Array.isArray(manifest.files)) throw error("Invalid snapshot manifest");
+  const seen = new Set();
+  for (const file of manifest.files) {
+    if (!file || (file.path !== "artifacty.sqlite" && file.path !== "index.json" && !file.path?.startsWith("artifacts/")) || seen.has(file.path)) throw error("Invalid snapshot file entry");
+    safePath(directory, file.path);
+    if (!Number.isSafeInteger(file.sizeBytes) || file.sizeBytes < 0 || !/^[a-f0-9]{64}$/i.test(file.sha256 || "")) throw error("Invalid snapshot file hash or size");
+    seen.add(file.path);
+  }
+  return { directory, manifest };
+}
+
+export function verifyUpgradeBackup(input, id) {
+  const store = paths(input);
+  const { directory, manifest } = manifestAt(store, id);
+  for (const file of manifest.files) compareFile(directory, file);
+  const database = manifest.files.some((file) => file.path === "artifacty.sqlite") ? safePath(directory, "artifacty.sqlite") : null;
+  const index = manifest.files.some((file) => file.path === "index.json") ? safePath(directory, "index.json") : null;
+  if (!database && !index && !manifest.emptyStore) throw error("Snapshot has no database or legacy index");
+  const refs = references(database, index);
+  const listed = manifest.files.filter((file) => file.path.startsWith("artifacts/"));
+  if (JSON.stringify(refs) !== JSON.stringify(listed)) throw error("Snapshot manifest does not match database file references");
+  return { id, valid: true, filesVerified: manifest.files.length, ...manifest, path: directory };
+}
+
+export function listUpgradeBackups(input) {
+  const store = paths(input);
+  safePath(store.home, "upgrade-backups");
+  if (!existsSync(store.backups)) return [];
+  return readdirSync(store.backups).filter((id) => ID_PATTERN.test(id)).map((id) => {
+    try { const { directory, manifest } = manifestAt(store, id); return { ...manifest, path: directory }; }
+    catch (cause) { return { id, valid: false, error: cause.message }; }
+  }).sort((a, b) => String(b.createdAt || b.id).localeCompare(String(a.createdAt || a.id)));
+}
+
+function retentionCount() {
+  const value = process.env.ARTIFACTY_UPGRADE_BACKUP_KEEP || "3";
+  if (!/^\d+$/.test(value) || Number(value) < 1 || Number(value) > 1000) throw error("ARTIFACTY_UPGRADE_BACKUP_KEEP must be from 1 to 1000");
+  return Number(value);
+}
+
+function pruneAutomatic(store) {
+  const keep = retentionCount();
+  const automatic = listUpgradeBackups(store).filter((item) => item.id.startsWith("auto-") && item.kind === KIND && ["schema-upgrade", "application-update"].includes(item.reason));
+  for (const item of automatic.slice(keep)) {
+    verifyUpgradeBackup(store, item.id);
+    rmSync(snapshotDirectory(store, item.id), { recursive: true });
+  }
+}
+
+function createSnapshot(store, options = {}) {
+  const state = rawState(store);
+  const reason = options.reason || "manual";
+  const prefix = reason === "recovery" ? "recovery" : ["schema-upgrade", "application-update"].includes(reason) ? "auto" : "manual";
+  const id = `${prefix}-${new Date().toISOString().replace(/[:.Z]/g, "-")}-${randomUUID()}`;
+  privateDirectory(safePath(store.home, "upgrade-backups"));
+  const pending = safePath(store.backups, `.pending-${randomUUID()}`);
+  privateDirectory(pending);
+  let guard;
+  let published;
+  let complete = false;
+  try {
+    const files = [];
+    if (state.hasDatabase) {
+      guard = new DatabaseSync(store.dbPath);
+      guard.exec("PRAGMA busy_timeout=5000; BEGIN IMMEDIATE");
+      const source = new DatabaseSync(store.dbPath, { readOnly: true });
+      try { source.prepare("VACUUM INTO ?").run(path.join(pending, "artifacty.sqlite")); }
+      finally { source.close(); }
+      chmodSync(path.join(pending, "artifacty.sqlite"), 0o600);
+      files.push({ path: "artifacty.sqlite", ...fileInfo(path.join(pending, "artifacty.sqlite")) });
+    }
+    if (existsSync(store.indexPath)) {
+      const original = safePath(store.home, "index.json");
+      copyFileSync(original, path.join(pending, "index.json"));
+      chmodSync(path.join(pending, "index.json"), 0o600);
+      files.push({ path: "index.json", ...fileInfo(path.join(pending, "index.json")) });
+    }
+    const refs = references(state.hasDatabase ? path.join(pending, "artifacty.sqlite") : null, existsSync(path.join(pending, "index.json")) ? path.join(pending, "index.json") : null);
+    for (const ref of refs) {
+      const source = safePath(store.home, ref.path);
+      const target = safePath(pending, ref.path);
+      privateDirectory(path.dirname(target));
+      copyFileSync(source, target);
+      chmodSync(target, 0o600);
+      compareFile(pending, ref);
+      files.push(ref);
+    }
+    if (prefix === "auto") {
+      const previous = listUpgradeBackups(store).find((item) => item.reason === reason
+        && item.sourceSchemaVersion === state.schemaVersion && item.targetSchemaVersion === (options.targetSchemaVersion ?? null)
+        && item.sourceAppVersion === state.appVersion && item.targetAppVersion === (options.targetAppVersion ?? null)
+        && JSON.stringify(item.files) === JSON.stringify(files));
+      if (previous) {
+        try { return verifyUpgradeBackup(store, previous.id); } catch { /* Keep damaged backups for inspection; create a verified replacement. */ }
+      }
+    }
+    const manifest = { kind: KIND, manifestVersion: 1, id, reason, createdAt: new Date().toISOString(), sourceSchemaVersion: state.schemaVersion, targetSchemaVersion: options.targetSchemaVersion ?? null, sourceAppVersion: state.appVersion, targetAppVersion: options.targetAppVersion ?? null, emptyStore: !state.hasData && !state.hasDatabase, files };
+    durableWrite(path.join(pending, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+    syncTree(pending);
+    const destination = snapshotDirectory(store, id);
+    renameSync(pending, destination);
+    published = destination;
+    syncDirectory(store.backups);
+    const verified = verifyUpgradeBackup(store, id);
+    complete = true;
+    return verified;
+  } finally {
+    if (guard) { try { guard.exec("ROLLBACK"); } finally { guard.close(); } }
+    if (existsSync(pending)) rmSync(pending, { recursive: true, force: true });
+    if (published && !complete) rmSync(published, { recursive: true, force: true });
+  }
+}
+
+function assertNoInterruptedRestore(store) {
+  const pending = readdirSync(store.home).find((name) => /^\.restore-[a-f0-9-]{36}$/.test(name));
+  if (pending) throw error(`Interrupted restore found at ${path.join(store.home, pending)}. Preserve this directory and the damaged store. Use its restore.json recoveryBackupId to restore into a new empty home.`, "RESTORE_INCOMPLETE");
+}
+
+export function createUpgradeBackup(input, options = {}) {
+  const store = paths(input);
+  const release = lockStore(store);
+  try { assertNoInterruptedRestore(store); assertOffline(store); return createSnapshot(store, options); }
+  finally { release(); }
+}
+
+// The lock spans the snapshot, migrations, and application-version marker.
+// Existing application handles must be stopped separately before an upgrade.
+export function openProtectedDatabase(input, targetVersion, initialize) {
+  const store = paths(input);
+  const release = lockStore(store);
+  let db;
+  try {
+    assertNoInterruptedRestore(store);
+    const state = rawState(store);
+    if (state.schemaVersion > targetVersion) throw error(`Artifacty store was written by a newer version (store_version ${state.schemaVersion}) than this build supports (STORE_VERSION ${targetVersion}). Upgrade artifacty before opening this store.`, "NEWER_STORE_VERSION");
+    const schemaUpgrade = state.hasData && (state.schemaVersion == null || state.schemaVersion < targetVersion);
+    const appUpdate = state.hasData && process.env.ARTIFACTY_BACKUP_ON_UPDATE === "true" && state.appVersion !== APP_VERSION;
+    if (schemaUpgrade || appUpdate) {
+      retentionCount();
+      assertOffline(store, true);
+      createSnapshot(store, { reason: schemaUpgrade ? "schema-upgrade" : "application-update", targetSchemaVersion: targetVersion, targetAppVersion: APP_VERSION });
+    }
+    privateDirectory(store.artifactsDir);
+    db = new DatabaseSync(store.dbPath);
+    initialize(db);
+    if (state.appVersion !== APP_VERSION) db.prepare("INSERT OR REPLACE INTO meta (key,value) VALUES ('application_version', ?)").run(APP_VERSION);
+    if (schemaUpgrade || appUpdate) pruneAutomatic(store);
+    return db;
+  } catch (cause) { db?.close(); throw cause; }
+  finally { release(); }
+}
+
+export function restoreUpgradeBackup(input, id, { confirm } = {}) {
+  if (confirm !== "restore-store") throw error('Restore requires confirm: "restore-store"', "RESTORE_CONFIRMATION_REQUIRED");
+  const store = paths(input);
+  const release = lockStore(store);
+  let stage;
+  let preserveStage = false;
+  try {
+    assertNoInterruptedRestore(store);
+    assertOffline(store);
+    const snapshot = verifyUpgradeBackup(store, id);
+    let recovery;
+    try { recovery = createSnapshot(store, { reason: "recovery" }); }
+    catch (cause) {
+      throw error(`Cannot verify the current store for a recovery snapshot: ${cause.message}. Preserve the damaged store and copy the selected snapshot into a new empty home's upgrade-backups directory, then restore there.`, "RECOVERY_BACKUP_FAILED");
+    }
+    stage = safePath(store.home, `.restore-${randomUUID()}`);
+    privateDirectory(stage);
+    privateDirectory(path.join(stage, "artifacts"));
+    for (const file of snapshot.files) {
+      const target = safePath(stage, file.path);
+      privateDirectory(path.dirname(target));
+      copyFileSync(safePath(snapshot.path, file.path), target);
+      chmodSync(target, 0o600);
+      compareFile(stage, file);
+    }
+    const previous = path.join(stage, "previous");
+    privateDirectory(previous);
+    const names = ["artifacty.sqlite", "artifacty.sqlite-wal", "artifacty.sqlite-shm", "index.json", "artifacts"];
+    const moved = [];
+    const installed = [];
+    durableWrite(path.join(stage, "restore.json"), JSON.stringify({ snapshotId: id, recoveryBackupId: recovery.id, createdAt: new Date().toISOString() }));
+    syncTree(stage);
+    syncDirectory(store.home);
+    try {
+      for (const name of names) {
+        const current = safePath(store.home, name);
+        if (existsSync(current)) { renameSync(current, path.join(previous, name)); moved.push(name); }
+      }
+      for (const name of ["artifacty.sqlite", "index.json", "artifacts"]) {
+        const source = path.join(stage, name);
+        if (existsSync(source)) { renameSync(source, path.join(store.home, name)); installed.push(name); }
+      }
+      syncDirectory(previous);
+      syncDirectory(store.home);
+    } catch (cause) {
+      try {
+        for (const name of installed.reverse()) rmSync(path.join(store.home, name), { recursive: true, force: true });
+        for (const name of moved.reverse()) renameSync(path.join(previous, name), path.join(store.home, name));
+        syncDirectory(store.home);
+      } catch (rollbackError) {
+        preserveStage = true;
+        throw error(`Restore and rollback failed. Preserve ${stage}; recovery snapshot ${recovery.id}. Original error: ${cause.message}; rollback error: ${rollbackError.message}`, "RESTORE_INCOMPLETE");
+      }
+      throw cause;
+    }
+    return { restored: id, recoveryBackupId: recovery.id };
+  } finally {
+    if (stage && !preserveStage && existsSync(stage)) rmSync(stage, { recursive: true, force: true });
+    release();
+  }
+}

package/src/server.js

@@ -24,6 +24,7 @@ import {
   deleteComment,
   deleteSavedView,
   deleteWebhook,
+  ensureStore,
   getArtifact,
   getAccessMode,
   canReadArtifactEvent,
@@ -192,6 +193,9 @@ export async function startServer(options = {}) {
   const mcpHttp = Boolean(options.mcpHttp || process.env.ARTIFACTY_MCP_HTTP === "true");
   validateServerExposure({ host, config: security });
 
+  // Finish protected store upgrades before accepting requests or recording a live server.
+  await ensureStore(store);
+
   const { server, actualPort } = await listenWithFallback({
     host,
     requestedPort,