mdkg 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -4,6 +4,57 @@ All notable changes to mdkg are documented here.
 
 This project follows a pragmatic changelog style inspired by Keep a Changelog. Versions use npm package versions.
 
+mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL contracts may change quickly while the project converges on a stable v1 surface.
+
+## 0.1.4 - Unreleased
+
+### Added
+
+- Added `mdkg subgraph add/list/show/rm/enable/disable/verify/refresh` as the public read-only child graph orchestration command family.
+- Added `subgraphs` config with multi-source bundle transport, advisory visibility, read permissions, source metadata, and a default 60 minute freshness policy.
+- Added `.mdkg/index/subgraphs.json` as the derived subgraph projection and health cache.
+- Added `mdkg capability resolve [query] [--requires <capability>] [--fresh-only] [--json]` for deterministic local plus subgraph capability ranking.
+- Added packed-package `smoke:subgraph` coverage for root, child, and grandchild orchestration flows.
+
+### Changed
+
+- Replaced the public `mdkg bundle import ...` surface with `mdkg subgraph ...`; legacy calls now exit with migration guidance.
+- `mdkg upgrade --apply` migrates legacy `bundle_imports` config into `subgraphs`.
+- Read commands, `pack`, and capability discovery now project enabled child bundles as read-only subgraph qids such as `child_repo:work.example`.
+- `mdkg index`, SQLite cache rebuilds, `doctor`, and `validate` now use subgraph naming and metadata instead of bundle-import naming.
+- Stale subgraphs remain usable for planning reads with warnings, fail `mdkg subgraph verify`, and are excluded from `capability resolve --fresh-only`.
+- Public/internal subgraphs require public bundle profiles and public bundle creation fails closed on private/internal subgraph references.
+
+### Fixed
+
+- Mutation commands now reject subgraph qids with explicit guidance to update the source workspace for the owning subgraph.
+- Seeded init docs, command matrix, and release skills now teach `subgraph` and `capability resolve` instead of onboarding users through `bundle import`.
+
+## 0.1.3 - 2026-05-20
+
+### Added
+
+- Added first-class SQLite access cache support using Node's built-in `node:sqlite`; no third-party SQLite package is introduced.
+- Added `.mdkg/index/mdkg.sqlite` as a rebuildable derived cache for nodes, edges, skills, capabilities, archives, bundle imports, source hashes, and schema metadata when `index.backend` is `sqlite`.
+- Added fresh init defaults for `index.backend: sqlite`, `index.sqlite_path`, `index.sqlite_commit_warning_bytes`, and `index.lock_timeout_ms`.
+- Added a shared mutation lock plus atomic writes for mdkg mutations and index writes.
+- Added SQLite transactional id reservation for numeric node/checkpoint ids in SQLite mode.
+- Added `npm run smoke:sqlite` and `npm run smoke:parallel` packed/temp-repo coverage.
+
+### Changed
+
+- Raised the required Node runtime to `>=24.15.0`.
+- Existing workspaces that are migrated from older configs remain on `index.backend: json` until they explicitly opt in to SQLite.
+- Init ignore policy now keeps JSON indexes, temp files, lock directories, WAL, SHM, and journal files ignored while allowing `.mdkg/index/mdkg.sqlite` to be committed by intentional repo policy.
+- `mdkg index` continues to write JSON compatibility indexes and also rebuilds SQLite when enabled.
+- `mdkg doctor` and `mdkg validate` now report SQLite cache health when SQLite mode is enabled.
+- README and seeded docs now state that mdkg is pre-v1 public alpha software and cache/DAL contracts may churn before v1.
+
+### Fixed
+
+- Removed the accidental self-dependency on `mdkg` from package metadata.
+- Hardened parallel `mdkg new`, checkpoint, task, work, archive, bundle import config, and index writes against naming conflicts and partial cache writes.
+
 ## 0.1.2 - 2026-05-19
 
 ### Added

package/README.md

@@ -9,11 +9,14 @@ It is built for:
 
 mdkg stays deliberately boring:
 - repo-native under `.mdkg/`
-- TypeScript + Node.js 18+
-- zero runtime dependencies
-- no required sqlite, daemon, hosted index, or vector DB
+- TypeScript + Node.js `>=24.15.0`
+- zero third-party runtime dependencies
+- first-class rebuildable SQLite cache through built-in `node:sqlite`
+- no daemon, hosted index, or vector DB
 
-Current package version in source: `0.1.2`
+Current package version in source: `0.1.4`
+
+mdkg is still pre-v1 public alpha software. The public package is usable, but graph, cache, bundle, and DAL contracts may continue to change quickly while the project converges on a stable v1 surface.
 
 ## The product shape
 
@@ -107,20 +110,21 @@ mdkg bundle verify .mdkg/bundles/private/all.mdkg.zip
 mdkg bundle list --json
 ```
 
-Bundles are explicit graph transport artifacts, separate from task context packs. Before a commit in repos that track archives or bundles, refresh compressed archive caches first, then create the private bundle so the committed graph state is self-consistent. Private bundles are the default and may be committed in private repos when configured. Public bundles require at least one selected workspace with `visibility: public` and include only public workspace content and public archive sidecars; bundle creation fails if public content points at private graph, archive, or imported bundle records.
+Bundles are explicit graph transport artifacts, separate from task context packs. Before a commit in repos that track archives or bundles, refresh compressed archive caches first, then create the private bundle so the committed graph state is self-consistent. Private bundles are the default and may be committed in private repos when configured. Public bundles require at least one selected workspace with `visibility: public` and include only public workspace content and public archive sidecars; bundle creation fails if public content points at private graph, archive, or subgraph records.
 
-Import a child repo bundle as a read-only planning view:
+Register a child repo bundle as a read-only subgraph planning view:
 
 ```bash
-mdkg bundle import add child_repo child-repo/.mdkg/bundles/private/all.mdkg.zip --source-path child-repo
-mdkg bundle import list --json
+mdkg subgraph add child_repo child-repo/.mdkg/bundles/private/all.mdkg.zip --source-path child-repo
+mdkg subgraph list --json
 mdkg search "child capability"
 mdkg show child_repo:work.example
 mdkg pack child_repo:work.example --dry-run --stats
-mdkg bundle import verify child_repo --json
+mdkg capability resolve "child capability" --json
+mdkg subgraph verify child_repo --json
 ```
 
-Imported bundle nodes are projected under the import alias, for example `child_repo:task-1`. They are available to `list`, `search`, `show`, `pack`, and capability discovery, but remain read-only; mutate the child repo and refresh its bundle to change imported content. Stale imports warn during planning reads and fail `mdkg bundle import verify`. Public or internal imports must be backed by public bundle profiles; private imports stay private planning context.
+Subgraph nodes are projected under the subgraph alias, for example `child_repo:task-1`. They are available to `list`, `search`, `show`, `pack`, capability discovery, and `capability resolve`, but remain read-only; mutate the child repo and refresh its bundle to change subgraph content. Stale subgraphs warn during planning reads and fail `mdkg subgraph verify`. Public or internal subgraphs must be backed by public bundle profiles; private subgraphs stay private planning context.
 
 Validate before handoff or commit:
 
@@ -155,7 +159,7 @@ mdkg work artifact add receipt.generate-image-1 ./outputs/image.png --id archive
 ```
 
 Receipt statuses are `recorded`, `verified`, `rejected`, and `superseded`.
-Update and artifact commands accept local ids or local qids; imported bundle qids are read-only and must be changed in their source workspace.
+Update and artifact commands accept local ids or local qids; subgraph qids are read-only and must be changed in their source workspace.
 
 Update structured task state and evidence while keeping body and narrative edits in markdown:
 
@@ -202,10 +206,11 @@ mdkg lives under a hidden root directory:
 - `.mdkg/skills/` Agent Skills packages
 - `.mdkg/archive/` sidecar metadata plus deterministic compressed source/artifact caches
 - `.mdkg/bundles/` optional committed full graph snapshot bundles
-- `.mdkg/index/imports.json` generated read-only bundle import cache
+- `.mdkg/index/mdkg.sqlite` optional committed, rebuildable SQLite access cache
+- `.mdkg/index/subgraphs.json` generated read-only subgraph projection cache
 - `.agents/skills/` Codex/OpenAI-facing mirrored skills
 - `.claude/skills/` Claude-facing mirrored skills
-- `.mdkg/index/` generated cache files
+- `.mdkg/index/*.json` generated JSON compatibility cache files
 
 ## Primary commands
 
@@ -292,6 +297,14 @@ The capability cache is not the full graph and is not source of truth. Normal ta
 
 Capability records aggregate enabled registered workspaces and include deterministic source metadata such as `workspace`, `visibility`, `kind`, `id`, `qid`, `path`, headings, refs, source hash, and `indexed_at`. Workspace `visibility` also feeds mdkg's export safety checks for public/internal packs and public bundles. This is a CLI safety layer, not secret scanning, body redaction, or a replacement for private git hosting.
 
+## Index backends and parallel safety
+
+Fresh `mdkg init` workspaces default to `index.backend: sqlite`, which writes `.mdkg/index/mdkg.sqlite` as a rebuildable access cache using Node's built-in `node:sqlite`. Existing workspaces that are migrated from older configs default to `index.backend: json` until they opt in. Markdown files, archive sidecars, bundle manifests, and config remain source of truth in both modes.
+
+`mdkg index` still writes JSON compatibility caches (`global.json`, `skills.json`, `capabilities.json`, and subgraph projections when configured). In SQLite mode it also rebuilds the SQLite cache with nodes, edges, skills, capabilities, archive metadata, subgraphs, source hashes, and schema metadata. Deleting the SQLite file is recoverable with `mdkg index`.
+
+Mutating commands use a workspace mutation lock plus atomic writes. SQLite mode additionally reserves numeric ids in a SQLite transaction before writing Markdown so parallel `mdkg new` and checkpoint calls avoid naming conflicts. Skipped ids after failed writes are acceptable because Markdown remains canonical.
+
 ## Agent workflow files
 
 mdkg recognizes a small set of canonical agent workflow documents:
@@ -323,10 +336,12 @@ By default, init/upgrade ignore generated raw archive source copies with `.mdkg/
 
 This release includes:
 - `init --agent`
-- default ignore updates with `--no-update-ignores` for `.mdkg/index/`, `.mdkg/pack/`, and raw archive source copies
+- default ignore updates with `--no-update-ignores` for generated JSON index/temp/lock files, `.mdkg/pack/`, and raw archive source copies
 - root-only published init seed config
 - skills indexing and search/show/list support
 - JSON capability cache for skills, `SPEC.md`, `WORK.md`, core docs, and design docs
+- SQLite index backend for fresh workspaces using built-in `node:sqlite`
+- mutation locking and atomic writes for parallel mdkg calls
 - optional `skills: [...]` on work items
 - pack-time skill inclusion
 - latest-checkpoint resolver + index hint
@@ -360,7 +375,8 @@ Design and decision records live in the internal graph under `.mdkg/design/`.
 mdkg is not a secret store.
 
 Use these defaults:
-- keep `.mdkg/index/` gitignored
+- keep generated `.mdkg/index/*.json`, temp, lock, WAL, SHM, and journal files gitignored
+- commit `.mdkg/index/mdkg.sqlite` only when the repo intentionally tracks a reasonably sized rebuildable access cache
 - keep `.mdkg/pack/` gitignored
 - keep `.mdkg/archive/**/source/` gitignored unless a repo intentionally commits raw local copies
 - commit archive sidecar `.md` metadata and deterministic `.zip` caches when they are needed for reviewable evidence

package/dist/cli.js

@@ -21,7 +21,7 @@ const doctor_1 = require("./commands/doctor");
 const capability_1 = require("./commands/capability");
 const archive_1 = require("./commands/archive");
 const bundle_1 = require("./commands/bundle");
-const bundle_import_1 = require("./commands/bundle_import");
+const subgraph_1 = require("./commands/subgraph");
 const checkpoint_1 = require("./commands/checkpoint");
 const init_1 = require("./commands/init");
 const new_1 = require("./commands/new");
@@ -60,9 +60,10 @@ function printUsage(log) {
     log("  search      Search nodes by query");
     log("  pack        Generate a context pack");
     log("  skill       Create, list, show, search, and validate skills");
-    log("  capability  List, search, and show cached capability surfaces");
+    log("  capability  List, search, show, and resolve cached capability surfaces");
     log("  archive     Add, list, show, verify, and compress archive sidecars");
     log("  bundle      Create, list, show, and verify full graph snapshot bundles");
+    log("  subgraph    Register and verify read-only child graph snapshots");
     log("  work        Create and update work contracts, orders, receipts, and artifacts");
     log("  task        Start, update, and complete task-like nodes");
     log("  next        Suggest the next work item");
@@ -171,6 +172,8 @@ function printIndexHelp(log) {
     log("  - .mdkg/index/global.json");
     log("  - .mdkg/index/skills.json");
     log("  - .mdkg/index/capabilities.json");
+    log("  - .mdkg/index/subgraphs.json when subgraphs are configured");
+    log("  - .mdkg/index/mdkg.sqlite when index.backend is sqlite");
     printGlobalOptions(log);
 }
 function printShowHelp(log) {
@@ -320,14 +323,23 @@ function printCapabilityHelp(log, subcommand) {
             log("  mdkg capability show <id-or-qid-or-slug> [--json]");
             printGlobalOptions(log);
             return;
+        case "resolve":
+            log("Usage:");
+            log('  mdkg capability resolve [query] [--requires <capability>] [--fresh-only] [--json]');
+            log("\nNotes:");
+            log("  Resolves local and subgraph capabilities with deterministic ranking.");
+            printGlobalOptions(log);
+            return;
         default:
             log("Usage:");
             log("  mdkg capability list [--kind <kind>] [--visibility <level>] [--json]");
             log('  mdkg capability search "<query>" [--kind <kind>] [--visibility <level>] [--json]');
             log("  mdkg capability show <id-or-qid-or-slug> [--json]");
+            log('  mdkg capability resolve [query] [--requires <capability>] [--fresh-only] [--json]');
             log("\nNotes:");
             log("  Capability records are deterministic cache projections from Markdown.");
             log("  Cached kinds: skill, spec, work, core, design.");
+            log("  Resolve includes read-only subgraph capability records when configured.");
             printGlobalOptions(log);
     }
 }
@@ -373,12 +385,8 @@ function printBundleHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "import":
             log("Usage:");
-            log("  mdkg bundle import add <alias> <bundle-path> [--visibility private|internal|public] [--profile private|public] [--source-path <path>] [--source-repo <ref>] [--max-stale-seconds <seconds>] [--json]");
-            log("  mdkg bundle import list [--json]");
-            log("  mdkg bundle import rm <alias> [--json]");
-            log("  mdkg bundle import enable <alias> [--json]");
-            log("  mdkg bundle import disable <alias> [--json]");
-            log("  mdkg bundle import verify [alias|--all] [--json]");
+            log("  mdkg subgraph add/list/show/rm/enable/disable/verify/refresh ...");
+            log("\n`mdkg bundle import` has been replaced by `mdkg subgraph`.");
             break;
         case "create":
             log("Usage:");
@@ -402,15 +410,66 @@ function printBundleHelp(log, subcommand) {
             log("  mdkg bundle verify [bundle-path] [--json]");
             log("  mdkg bundle show <bundle-path> [--json]");
             log("  mdkg bundle list [--json]");
-            log("  mdkg bundle import add/list/rm/enable/disable/verify ...");
             log("\nNotes:");
             log("  - bundles are explicit full .mdkg graph snapshots, not task context packs");
-            log("  - bundle imports are read-only graph views projected under their import alias");
+            log("  - use `mdkg subgraph ...` to register bundle snapshots as read-only planning views");
             log("  - private is the default profile; public bundles fail closed on private refs");
             log("  - .mdkg/bundles/ is commit-eligible when your repo tracks snapshot bundles");
     }
     printGlobalOptions(log);
 }
+function printSubgraphHelp(log, subcommand) {
+    switch ((subcommand ?? "").toLowerCase()) {
+        case "add":
+            log("Usage:");
+            log("  mdkg subgraph add <alias> <bundle-path> [--visibility private|internal|public] [--profile private|public] [--source-path <path>] [--source-repo <ref>] [--max-stale-seconds <seconds>] [--json]");
+            break;
+        case "list":
+            log("Usage:");
+            log("  mdkg subgraph list [--json]");
+            break;
+        case "show":
+            log("Usage:");
+            log("  mdkg subgraph show <alias> [--json]");
+            break;
+        case "rm":
+        case "remove":
+            log("Usage:");
+            log("  mdkg subgraph rm <alias> [--json]");
+            break;
+        case "enable":
+            log("Usage:");
+            log("  mdkg subgraph enable <alias> [--json]");
+            break;
+        case "disable":
+            log("Usage:");
+            log("  mdkg subgraph disable <alias> [--json]");
+            break;
+        case "verify":
+            log("Usage:");
+            log("  mdkg subgraph verify [alias|--all] [--json]");
+            break;
+        case "refresh":
+            log("Usage:");
+            log("  mdkg subgraph refresh [alias|--all] [--json]");
+            break;
+        default:
+            log("Usage:");
+            log("  mdkg subgraph add <alias> <bundle-path> [--visibility private|internal|public] [--profile private|public] [--source-path <path>] [--source-repo <ref>] [--max-stale-seconds <seconds>] [--json]");
+            log("  mdkg subgraph list [--json]");
+            log("  mdkg subgraph show <alias> [--json]");
+            log("  mdkg subgraph rm <alias> [--json]");
+            log("  mdkg subgraph enable <alias> [--json]");
+            log("  mdkg subgraph disable <alias> [--json]");
+            log("  mdkg subgraph verify [alias|--all] [--json]");
+            log("  mdkg subgraph refresh [alias|--all] [--json]");
+            log("\nNotes:");
+            log("  - subgraphs are read-only graph views backed by explicit bundle snapshots");
+            log("  - default permissions are read-only and default freshness is 3600 seconds");
+            log("  - refresh reloads configured bundle sources only; it does not build child bundles");
+    }
+    printGlobalOptions(log);
+}
 function printWorkHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "contract":
@@ -442,7 +501,7 @@ function printWorkHelp(log, subcommand) {
             log("  - production order, receipt, feedback, dispute, payment, ledger, marketplace inventory, fulfillment, and execution state remains canonical outside mdkg");
             log("  - do not store raw secrets, credentials, live payment state, ledger mutations, or canonical marketplace state in work mirrors");
             log("  - artifact:// refs identify external/runtime-managed artifacts; archive:// refs identify committed mdkg archive sidecars");
-            log("  - update and artifact commands accept local ids or local qids; imported bundle qids are read-only");
+            log("  - update and artifact commands accept local ids or local qids; subgraph qids are read-only");
     }
     printGlobalOptions(log);
 }
@@ -544,6 +603,7 @@ function printDoctorHelp(log) {
     log("  - Bundle import health and staleness");
     log("  - Index load/rebuild health");
     log("  - Capability cache load/rebuild health");
+    log("  - SQLite cache health when enabled");
     log("\nOptions:");
     log("  --json                Emit machine-readable JSON output");
     printGlobalOptions(log);
@@ -596,6 +656,9 @@ function printCommandHelp(log, command, subcommand) {
         case "bundle":
             printBundleHelp(log, subcommand);
             return;
+        case "subgraph":
+            printSubgraphHelp(log, subcommand);
+            return;
         case "work":
             printWorkHelp(log, subcommand);
             return;
@@ -868,8 +931,20 @@ function runCapabilitySubcommand(parsed, root) {
             (0, capability_1.runCapabilityShowCommand)({ root, id, json, noCache, noReindex });
             return 0;
         }
+        case "resolve": {
+            const query = parsed.positionals.slice(2).join(" ") || undefined;
+            const kind = requireFlagValue("--kind", parsed.flags["--kind"]);
+            const visibility = requireFlagValue("--visibility", parsed.flags["--visibility"]);
+            const requires = requireFlagValue("--requires", parsed.flags["--requires"]);
+            const freshOnly = parseBooleanFlag("--fresh-only", parsed.flags["--fresh-only"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
+            const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
+            (0, capability_1.runCapabilityResolveCommand)({ root, query, kind, visibility, requires, freshOnly, json, noCache, noReindex });
+            return 0;
+        }
         default:
-            throw new errors_1.UsageError("capability requires list/search/show");
+            throw new errors_1.UsageError("capability requires list/search/show/resolve");
     }
 }
 function runArchiveSubcommand(parsed, root) {
@@ -941,78 +1016,7 @@ function runBundleSubcommand(parsed, root) {
     const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
     switch (subcommand) {
         case "import": {
-            const action = (parsed.positionals[2] ?? "").toLowerCase();
-            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
-            switch (action) {
-                case "add": {
-                    const alias = parsed.positionals[3];
-                    const bundlePath = parsed.positionals[4];
-                    if (!alias || !bundlePath || parsed.positionals.length > 5) {
-                        throw new errors_1.UsageError("bundle import add requires <alias> <bundle-path>");
-                    }
-                    const visibility = requireFlagValue("--visibility", parsed.flags["--visibility"]);
-                    const profile = requireFlagValue("--profile", parsed.flags["--pack-profile"]);
-                    const sourcePath = requireFlagValue("--source-path", parsed.flags["--source-path"]);
-                    const sourceRepo = requireFlagValue("--source-repo", parsed.flags["--source-repo"]);
-                    const maxStaleRaw = requireFlagValue("--max-stale-seconds", parsed.flags["--max-stale-seconds"]);
-                    const maxStaleSeconds = maxStaleRaw === undefined ? undefined : Number.parseInt(maxStaleRaw, 10);
-                    (0, bundle_import_1.runBundleImportAddCommand)({
-                        root,
-                        alias,
-                        bundlePath,
-                        visibility,
-                        profile,
-                        sourcePath,
-                        sourceRepo,
-                        maxStaleSeconds,
-                        json,
-                    });
-                    return 0;
-                }
-                case "list": {
-                    if (parsed.positionals.length > 3) {
-                        throw new errors_1.UsageError("bundle import list does not accept positional arguments");
-                    }
-                    (0, bundle_import_1.runBundleImportListCommand)({ root, json });
-                    return 0;
-                }
-                case "rm":
-                case "remove": {
-                    const alias = parsed.positionals[3];
-                    if (!alias || parsed.positionals.length > 4) {
-                        throw new errors_1.UsageError("bundle import rm requires <alias>");
-                    }
-                    (0, bundle_import_1.runBundleImportRemoveCommand)({ root, alias, json });
-                    return 0;
-                }
-                case "enable": {
-                    const alias = parsed.positionals[3];
-                    if (!alias || parsed.positionals.length > 4) {
-                        throw new errors_1.UsageError("bundle import enable requires <alias>");
-                    }
-                    (0, bundle_import_1.runBundleImportEnableCommand)({ root, alias, json });
-                    return 0;
-                }
-                case "disable": {
-                    const alias = parsed.positionals[3];
-                    if (!alias || parsed.positionals.length > 4) {
-                        throw new errors_1.UsageError("bundle import disable requires <alias>");
-                    }
-                    (0, bundle_import_1.runBundleImportDisableCommand)({ root, alias, json });
-                    return 0;
-                }
-                case "verify": {
-                    if (parsed.positionals.length > 4) {
-                        throw new errors_1.UsageError("bundle import verify accepts at most one alias");
-                    }
-                    const alias = parsed.positionals[3];
-                    const all = parseBooleanFlag("--all", parsed.flags["--all"]);
-                    (0, bundle_import_1.runBundleImportVerifyCommand)({ root, alias, all, json });
-                    return 0;
-                }
-                default:
-                    throw new errors_1.UsageError("bundle import requires add/list/rm/enable/disable/verify");
-            }
+            throw new errors_1.UsageError("mdkg bundle import has been replaced by mdkg subgraph; run `mdkg upgrade --apply` to migrate legacy bundle_imports config");
         }
         case "create": {
             if (parsed.positionals.length > 2) {
@@ -1052,7 +1056,98 @@ function runBundleSubcommand(parsed, root) {
             return 0;
         }
         default:
-            throw new errors_1.UsageError("bundle requires create/list/show/verify/import");
+            throw new errors_1.UsageError("bundle requires create/list/show/verify");
+    }
+}
+function runSubgraphSubcommand(parsed, root) {
+    const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
+    const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+    switch (subcommand) {
+        case "add": {
+            const alias = parsed.positionals[2];
+            const bundlePath = parsed.positionals[3];
+            if (!alias || !bundlePath || parsed.positionals.length > 4) {
+                throw new errors_1.UsageError("subgraph add requires <alias> <bundle-path>");
+            }
+            const visibility = requireFlagValue("--visibility", parsed.flags["--visibility"]);
+            const profile = requireFlagValue("--profile", parsed.flags["--pack-profile"]);
+            const sourcePath = requireFlagValue("--source-path", parsed.flags["--source-path"]);
+            const sourceRepo = requireFlagValue("--source-repo", parsed.flags["--source-repo"]);
+            const maxStaleRaw = requireFlagValue("--max-stale-seconds", parsed.flags["--max-stale-seconds"]);
+            const maxStaleSeconds = maxStaleRaw === undefined ? undefined : Number.parseInt(maxStaleRaw, 10);
+            (0, subgraph_1.runSubgraphAddCommand)({
+                root,
+                alias,
+                bundlePath,
+                visibility,
+                profile,
+                sourcePath,
+                sourceRepo,
+                maxStaleSeconds,
+                json,
+            });
+            return 0;
+        }
+        case "list": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("subgraph list does not accept positional arguments");
+            }
+            (0, subgraph_1.runSubgraphListCommand)({ root, json });
+            return 0;
+        }
+        case "show": {
+            const alias = parsed.positionals[2];
+            if (!alias || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("subgraph show requires <alias>");
+            }
+            (0, subgraph_1.runSubgraphShowCommand)({ root, alias, json });
+            return 0;
+        }
+        case "rm":
+        case "remove": {
+            const alias = parsed.positionals[2];
+            if (!alias || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("subgraph rm requires <alias>");
+            }
+            (0, subgraph_1.runSubgraphRemoveCommand)({ root, alias, json });
+            return 0;
+        }
+        case "enable": {
+            const alias = parsed.positionals[2];
+            if (!alias || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("subgraph enable requires <alias>");
+            }
+            (0, subgraph_1.runSubgraphEnableCommand)({ root, alias, json });
+            return 0;
+        }
+        case "disable": {
+            const alias = parsed.positionals[2];
+            if (!alias || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("subgraph disable requires <alias>");
+            }
+            (0, subgraph_1.runSubgraphDisableCommand)({ root, alias, json });
+            return 0;
+        }
+        case "verify": {
+            if (parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("subgraph verify accepts at most one alias");
+            }
+            const alias = parsed.positionals[2];
+            const all = parseBooleanFlag("--all", parsed.flags["--all"]);
+            (0, subgraph_1.runSubgraphVerifyCommand)({ root, alias, all, json });
+            return 0;
+        }
+        case "refresh": {
+            if (parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("subgraph refresh accepts at most one alias");
+            }
+            const alias = parsed.positionals[2];
+            const all = parseBooleanFlag("--all", parsed.flags["--all"]);
+            (0, subgraph_1.runSubgraphRefreshCommand)({ root, alias, all, json });
+            return 0;
+        }
+        default:
+            throw new errors_1.UsageError("subgraph requires add/list/show/rm/enable/disable/verify/refresh");
     }
 }
 function runWorkSubcommand(parsed, root) {
@@ -1564,6 +1659,8 @@ function runCommand(parsed, root, runtime) {
             return runArchiveSubcommand(parsed, root);
         case "bundle":
             return runBundleSubcommand(parsed, root);
+        case "subgraph":
+            return runSubgraphSubcommand(parsed, root);
         case "work":
             return runWorkSubcommand(parsed, root);
         case "task":

package/dist/commands/archive.js

@@ -3,10 +3,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runArchiveAddCommand = runArchiveAddCommand;
 exports.runArchiveListCommand = runArchiveListCommand;
 exports.runArchiveShowCommand = runArchiveShowCommand;
 exports.runArchiveVerifyCommand = runArchiveVerifyCommand;
+exports.runArchiveAddCommand = runArchiveAddCommand;
 exports.runArchiveCompressCommand = runArchiveCompressCommand;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -15,11 +15,14 @@ const frontmatter_1 = require("../graph/frontmatter");
 const archive_integrity_1 = require("../graph/archive_integrity");
 const indexer_1 = require("../graph/indexer");
 const index_cache_1 = require("../graph/index_cache");
+const reindex_1 = require("../graph/reindex");
 const visibility_1 = require("../graph/visibility");
 const date_1 = require("../util/date");
 const errors_1 = require("../util/errors");
 const id_1 = require("../util/id");
 const refs_1 = require("../util/refs");
+const atomic_1 = require("../util/atomic");
+const lock_1 = require("../util/lock");
 const zip_1 = require("../util/zip");
 const event_support_1 = require("./event_support");
 const ARCHIVE_KINDS = new Set(["source", "artifact"]);
@@ -124,8 +127,7 @@ function maybeReindex(root) {
     if (!config.index.auto_reindex) {
         return;
     }
-    const outputPath = path_1.default.resolve(root, config.index.global_index_path);
-    (0, index_cache_1.writeIndex)(outputPath, (0, indexer_1.buildIndex)(root, config, { tolerant: config.index.tolerant }));
+    (0, reindex_1.writeDerivedIndexes)(root, config, (0, indexer_1.buildIndex)(root, config, { tolerant: config.index.tolerant }));
 }
 function resolveArchiveNode(root, id, ws) {
     const config = (0, config_1.loadConfig)(root);
@@ -174,7 +176,7 @@ function stringAttribute(value) {
 function writeArchiveSidecar(sidecarPath, frontmatter, body) {
     const lines = (0, frontmatter_1.formatFrontmatter)(frontmatter);
     const content = ["---", ...lines, "---", body.trimStart()].join("\n");
-    fs_1.default.writeFileSync(sidecarPath, content.endsWith("\n") ? content : `${content}\n`, "utf8");
+    (0, atomic_1.atomicWriteFile)(sidecarPath, content.endsWith("\n") ? content : `${content}\n`);
 }
 function verifyArchiveSidecar(root, ws, sidecarPath) {
     const relativePath = toPosixPath(path_1.default.relative(root, sidecarPath));
@@ -276,7 +278,7 @@ function loadArchiveVerifyResults(options) {
     }
     return results;
 }
-function runArchiveAddCommand(options) {
+function runArchiveAddCommandLocked(options) {
     const config = (0, config_1.loadConfig)(options.root);
     const ws = normalizeWorkspace(options.ws);
     const workspace = config.workspaces[ws];
@@ -311,7 +313,7 @@ function runArchiveAddCommand(options) {
     fs_1.default.copyFileSync(sourcePath, rawPath);
     const rawData = fs_1.default.readFileSync(rawPath);
     const zipData = (0, zip_1.createDeterministicZip)(basename, rawData);
-    fs_1.default.writeFileSync(zipPath, zipData);
+    (0, atomic_1.atomicWriteFile)(zipPath, zipData);
     const frontmatter = {
         id,
         type: "archive",
@@ -423,7 +425,7 @@ function runArchiveVerifyCommand(options) {
         throw new errors_1.ValidationError("archive verification failed");
     }
 }
-function runArchiveCompressCommand(options) {
+function runArchiveCompressCommandLocked(options) {
     if (!options.all && !options.id) {
         throw new errors_1.UsageError("archive compress requires <id-or-archive-uri> or --all");
     }
@@ -441,7 +443,7 @@ function runArchiveCompressCommand(options) {
         }
         const rawData = fs_1.default.readFileSync(rawPath);
         const zipData = (0, zip_1.createDeterministicZip)(path_1.default.basename(rawPath), rawData);
-        fs_1.default.writeFileSync(zipPath, zipData);
+        (0, atomic_1.atomicWriteFile)(zipPath, zipData);
         const parsed = (0, frontmatter_1.parseFrontmatter)(fs_1.default.readFileSync(sidecarPath, "utf8"), sidecarPath);
         const nextFrontmatter = {
             ...parsed.frontmatter,
@@ -472,3 +474,13 @@ function runArchiveCompressCommand(options) {
     }
     console.log(`archive compressed: ${updated.length}`);
 }
+function withArchiveLock(root, fn) {
+    const config = (0, config_1.loadConfig)(root);
+    return (0, lock_1.withMutationLock)(root, config.index.lock_timeout_ms, fn);
+}
+function runArchiveAddCommand(options) {
+    return withArchiveLock(options.root, () => runArchiveAddCommandLocked(options));
+}
+function runArchiveCompressCommand(options) {
+    return withArchiveLock(options.root, () => runArchiveCompressCommandLocked(options));
+}