mdkg 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -6,7 +6,43 @@ This project follows a pragmatic changelog style inspired by Keep a Changelog. V
 
 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.5 - Unreleased
+## 0.1.7 - 2026-06-04
+
+### Added
+
+- Added `mdkg db` as the project database command namespace for the pre-v1 DB foundation.
+- Added `mdkg db index rebuild/status/verify` while keeping `mdkg index` as the compatibility shortcut for graph index rebuilds.
+- Added generic project DB config and `.mdkg/db/{schema,runtime,state,receipts}` layout support, separate from the rebuildable `.mdkg/index` graph cache.
+- Added `mdkg db init` to create the generic project DB scaffold, write `.mdkg/db/project-db.json`, and enable `db.enabled` without creating an active runtime SQLite database.
+- Added `mdkg db migrate` using Node's built-in `node:sqlite` for mdkg-owned generic foundation migrations with migration keys, order, checksums, and applied timestamps.
+- Added `mdkg db verify` and `mdkg db stats` for non-mutating project DB health checks and deterministic summaries.
+- Added `mdkg db snapshot seal/verify/status/dump/diff` for opt-in sealed SQLite checkpoints, manifests, canonical dumps, and deterministic review diffs.
+- Added prefix-based cross-subgraph graph references so root-authored nodes can point at configured child graph qids such as `child_repo:work.example`.
+- Added `mdkg subgraph sync [alias|--all] [--dry-run] [--allow-dirty] [--json]` to rebuild root-owned child bundle snapshots from configured clean child Git repo `source_path` entries.
+- Added `mdkg subgraph materialize [alias|--all] --target <path> [--clean] [--gitignore] [--json]` for generated read-only inspection trees extracted from configured subgraph bundles.
+- Added unit and packed-package smoke coverage for subgraph sync dry-runs, child Git cleanliness checks, root-owned bundle refresh, materialization marker safety, and cross-subgraph refs.
+- Added unit, packed-package init, dedicated `smoke:db`, and `smoke:db-snapshot` coverage for project DB runtime and sealed snapshot workflows.
+
+### Changed
+
+- Init, upgrade, README, command matrix, and agent-start docs now distinguish `.mdkg/index` as rebuildable graph cache state from `.mdkg/db` as project application database state.
+- Project DB runtime SQLite files, WAL/SHM/journal files, locks, and temp files remain ignored by default; schema files, manifests, receipts, and opt-in sealed snapshots remain policy-driven.
+- `mdkg subgraph refresh` remains reload-only; `mdkg subgraph sync` is now the explicit command that builds child bundles.
+- Init and upgrade ignore guidance now treats `.mdkg/subgraphs/` as local generated inspection state.
+- Bundle creation, local graph indexing, search, validate, pack, and SQLite hydration keep ignoring materialized subgraph trees so extracted child files never become root-owned graph nodes.
+
+### Fixed
+
+- Relationship and reference fields now preserve `alias:id` qids while still treating `scheme://...` values as external URI refs.
+- Local ownership fields such as `epic`, `parent`, `prev`, and `next` reject subgraph qids, preserving child graph ownership boundaries.
+
+## 0.1.6 - 2026-06-01
+
+### Fixed
+
+- Treat `feat` nodes as task-like for `mdkg task start/update/done`, closing the selected-goal loop when `mdkg goal next` returns a feature as the next scoped work item.
+
+## 0.1.5 - 2026-06-01
 
 ### Added
 
@@ -24,7 +60,7 @@ mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL con
 - Goal required checks are report-only guidance in this release. Agents run commands themselves and record evidence back into mdkg.
 - Skill self-improvement during goal execution is recorded as candidates or proposal work unless the active node is explicit skill-maintenance.
 
-## 0.1.4 - Unreleased
+## 0.1.4 - 2026-06-01
 
 ### Added
 

package/README.md

@@ -14,7 +14,7 @@ mdkg stays deliberately boring:
 - first-class rebuildable SQLite cache through built-in `node:sqlite`
 - no daemon, hosted index, or vector DB
 
-Current package version in source: `0.1.5`
+Current package version in source: `0.1.7`
 
 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.
 
@@ -126,7 +126,7 @@ Bundles are explicit graph transport artifacts, separate from task context packs
 Register a child repo bundle as a read-only subgraph planning view:
 
 ```bash
-mdkg subgraph add child_repo child-repo/.mdkg/bundles/private/all.mdkg.zip --source-path child-repo
+mdkg subgraph add child_repo .mdkg/bundles/private/subgraphs/child_repo.mdkg.zip --source-path projects/child_repo
 mdkg subgraph list --json
 mdkg search "child capability"
 mdkg show child_repo:work.example
@@ -135,7 +135,24 @@ mdkg capability resolve "child capability" --json
 mdkg subgraph verify child_repo --json
 ```
 
-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.
+When the child repo is available under a configured root-relative `source_path`, refresh the root-owned bundle snapshot explicitly:
+
+```bash
+mdkg subgraph sync child_repo --dry-run --json
+mdkg subgraph sync child_repo --json
+```
+
+`sync` inspects the child Git repo, refuses dirty tracked changes by default, builds the configured private/public bundle into the root-owned source path, verifies it, and records `<branch>@<sha>` in `source_repo`. It never commits, pulls, pushes, checks out, resets, or mutates child mdkg Markdown. Use `--allow-dirty` only when the dirty state is intentional and must be recorded in the receipt.
+
+Generate a local read-only inspection tree when humans need to browse extracted child graph files:
+
+```bash
+mdkg subgraph materialize child_repo --target .mdkg/subgraphs --clean --gitignore --json
+```
+
+Materialized trees are generated local state, ignored by graph indexing/search/validation/packing/bundles/SQLite hydration, and protected by a `.mdkg-materialized.json` marker before clean replacement.
+
+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 sync its root-owned bundle snapshot to change subgraph content. Root-authored relationship and reference fields can point at configured subgraph qids such as `child_repo:work.example`; local ownership fields such as `epic`, `parent`, `prev`, and `next` stay local-only. 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:
 
@@ -219,6 +236,8 @@ mdkg lives under a hidden root directory:
 - `.mdkg/bundles/` optional committed full graph snapshot bundles
 - `.mdkg/index/mdkg.sqlite` optional committed, rebuildable SQLite access cache
 - `.mdkg/index/subgraphs.json` generated read-only subgraph projection cache
+- `.mdkg/db/` future project application database layout and receipts
+- `.mdkg/subgraphs/` generated materialized subgraph inspection trees
 - `.agents/skills/` Codex/OpenAI-facing mirrored skills
 - `.claude/skills/` Claude-facing mirrored skills
 - `.mdkg/index/*.json` generated JSON compatibility cache files
@@ -317,6 +336,36 @@ Fresh `mdkg init` workspaces default to `index.backend: sqlite`, which writes `.
 
 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.
 
+## Project DB Layout
+
+`.mdkg/db` is reserved for project application database state, separate from
+the rebuildable `.mdkg/index` graph cache. Run `mdkg db init` to create the
+generic scaffold and explicitly enable `db.enabled` in config. The generic
+layout is `.mdkg/db/schema`, `.mdkg/db/runtime`, `.mdkg/db/state`, and
+`.mdkg/db/receipts`; `mdkg db init` also writes a deterministic
+`.mdkg/db/project-db.json` manifest.
+
+Runtime DB files, WAL, SHM, journal, lock, and temp files are ignored by
+default. `mdkg db init` does not create an active runtime SQLite database.
+Run `mdkg db migrate` after init to create or update the active runtime
+SQLite database at the configured `db.runtime_path`; the first migration writes
+only mdkg-owned generic foundation tables and records migration order,
+checksums, and applied timestamps.
+Use `mdkg db verify` for non-mutating health checks over config, layout,
+runtime SQLite integrity, migration metadata, and transient runtime files. Use
+`mdkg db stats` for deterministic table counts, DB size, migration state,
+receipt-file count, and state snapshot presence.
+Use `mdkg db snapshot seal` to create an explicit sealed checkpoint at
+`.mdkg/db/state/project.sqlite` with `.mdkg/db/state/project.manifest.json`.
+Use `mdkg db snapshot verify` and `mdkg db snapshot status` for checkpoint
+health, and use `mdkg db snapshot dump` / `mdkg db snapshot diff` as
+deterministic review aids for SQLite snapshots instead of comparing raw binary
+bytes.
+Schema files, manifests, receipt artifacts, and opt-in sealed snapshots remain
+commit-eligible by explicit repo policy. `mdkg doctor` warns when active runtime
+or transient project DB files are present so they are not accidentally committed
+as sealed state.
+
 ## Goal nodes
 
 Goal nodes are durable recursive objective contracts. Use `mdkg new goal "<objective>"` when a human or agent needs to keep working across multiple concrete nodes until a measurable end condition is achieved.
@@ -400,6 +449,8 @@ mdkg is not a secret store.
 Use these defaults:
 - 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/db/runtime/` and `.mdkg/db` WAL/SHM/journal/lock/temp files gitignored
+- commit `.mdkg/db/schema`, manifests, receipts, and sealed state snapshots only by explicit repo policy
 - 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

@@ -18,6 +18,7 @@ const next_1 = require("./commands/next");
 const validate_1 = require("./commands/validate");
 const format_1 = require("./commands/format");
 const doctor_1 = require("./commands/doctor");
+const db_1 = require("./commands/db");
 const capability_1 = require("./commands/capability");
 const archive_1 = require("./commands/archive");
 const bundle_1 = require("./commands/bundle");
@@ -64,13 +65,14 @@ function printUsage(log) {
     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("  subgraph    Register, sync, materialize, and verify read-only child graph snapshots");
     log("  work        Create and update work contracts, orders, receipts, and artifacts");
     log("  goal        Inspect and advance recursive goal nodes");
     log("  task        Start, update, and complete task-like nodes");
     log("  next        Suggest the next work item");
     log("  validate    Validate frontmatter + graph");
     log("\nAdvanced / maintenance commands:");
+    log("  db          Project database and index-cache commands");
     log("  event       Enable or append episodic event logs");
     log("  checkpoint  Create a checkpoint node");
     log("  index       Build the global index");
@@ -178,6 +180,61 @@ function printIndexHelp(log) {
     log("  - .mdkg/index/mdkg.sqlite when index.backend is sqlite");
     printGlobalOptions(log);
 }
+function printDbHelp(log, subcommand) {
+    switch ((subcommand ?? "").toLowerCase()) {
+        case "index":
+            log("Usage:");
+            log("  mdkg db index rebuild [--tolerant] [--json]");
+            log("  mdkg db index status [--json]");
+            log("  mdkg db index verify [--json]");
+            log("\nNotes:");
+            log("  - `mdkg index` remains the compatibility shortcut for index rebuilds");
+            log("  - `.mdkg/index` is the rebuildable graph cache, not project application state");
+            printGlobalOptions(log);
+            return;
+        case "snapshot":
+            log("Usage:");
+            log("  mdkg db snapshot seal [--json]");
+            log("  mdkg db snapshot verify [--json]");
+            log("  mdkg db snapshot status [--json]");
+            log("  mdkg db snapshot dump [--snapshot <path>] [--output <path>] [--json]");
+            log("  mdkg db snapshot diff <left-snapshot> <right-snapshot> [--json]");
+            log("\nBoundaries:");
+            log("  - snapshot seal writes a clean opt-in sealed project DB checkpoint");
+            log("  - snapshot verify/status read `.mdkg/db/state/project.sqlite` and its manifest");
+            log("  - snapshot dump/diff are deterministic review aids, not source of truth");
+            log("  - active runtime/WAL files remain ignored by default");
+            printGlobalOptions(log);
+            return;
+        default:
+            log("Usage:");
+            log("  mdkg db index rebuild [--tolerant] [--json]");
+            log("  mdkg db index status [--json]");
+            log("  mdkg db index verify [--json]");
+            log("  mdkg db init [--json]");
+            log("  mdkg db migrate [--json]");
+            log("  mdkg db verify [--json]");
+            log("  mdkg db stats [--json]");
+            log("  mdkg db snapshot seal [--json]");
+            log("  mdkg db snapshot verify [--json]");
+            log("  mdkg db snapshot status [--json]");
+            log("  mdkg db snapshot dump [--snapshot <path>] [--output <path>] [--json]");
+            log("  mdkg db snapshot diff <left-snapshot> <right-snapshot> [--json]");
+            log("\nBoundaries:");
+            log("  - `.mdkg/index` is the rebuildable graph cache");
+            log("  - `.mdkg/db` is future project application state");
+            log("  - `mdkg db init` creates the generic layout and enables db config");
+            log("  - `mdkg db init` does not create an active runtime SQLite database");
+            log("  - `mdkg db migrate` creates/updates the active runtime SQLite database");
+            log("  - `mdkg db migrate` applies mdkg-owned generic foundation migrations only");
+            log("  - `mdkg db verify` checks config, layout, SQLite integrity, migrations, and transient files");
+            log("  - `mdkg db stats` reports table counts, migration state, DB size, and receipt counts");
+            log("  - `mdkg db snapshot ...` manages opt-in sealed checkpoints and review dumps");
+            log("  - active `.mdkg/db/runtime` and transient DB files are ignored by default");
+            log("  - no raw SQL, hosted queue, profile, or publish behavior is exposed here");
+            printGlobalOptions(log);
+    }
+}
 function printShowHelp(log) {
     log("Usage:");
     log("  mdkg show <id-or-qid> [--ws <alias>] [--meta] [--json|--xml|--toon|--md]");
@@ -387,7 +444,7 @@ function printBundleHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "import":
             log("Usage:");
-            log("  mdkg subgraph add/list/show/rm/enable/disable/verify/refresh ...");
+            log("  mdkg subgraph add/list/show/rm/enable/disable/verify/refresh/sync/materialize ...");
             log("\n`mdkg bundle import` has been replaced by `mdkg subgraph`.");
             break;
         case "create":
@@ -455,6 +512,14 @@ function printSubgraphHelp(log, subcommand) {
             log("Usage:");
             log("  mdkg subgraph refresh [alias|--all] [--json]");
             break;
+        case "sync":
+            log("Usage:");
+            log("  mdkg subgraph sync [alias|--all] [--dry-run] [--allow-dirty] [--json]");
+            break;
+        case "materialize":
+            log("Usage:");
+            log("  mdkg subgraph materialize [alias|--all] --target <path> [--clean] [--gitignore] [--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]");
@@ -465,10 +530,14 @@ function printSubgraphHelp(log, subcommand) {
             log("  mdkg subgraph disable <alias> [--json]");
             log("  mdkg subgraph verify [alias|--all] [--json]");
             log("  mdkg subgraph refresh [alias|--all] [--json]");
+            log("  mdkg subgraph sync [alias|--all] [--dry-run] [--allow-dirty] [--json]");
+            log("  mdkg subgraph materialize [alias|--all] --target <path> [--clean] [--gitignore] [--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");
+            log("  - sync builds root-owned bundles from clean configured child source_path repos");
+            log("  - materialize extracts bundle contents into generated inspection trees");
     }
     printGlobalOptions(log);
 }
@@ -542,7 +611,7 @@ function printTaskHelp(log, subcommand) {
             log("  mdkg task update <id-or-qid> [options] [--json]");
             log('  mdkg task done <id-or-qid> [--checkpoint "<title>"] [options] [--json]');
             log("\nNotes:");
-            log("  `mdkg task ...` only supports task, bug, and test nodes in this wave.");
+            log("  `mdkg task ...` only supports feat, task, bug, and test nodes.");
             log("  Feat and epic closeout remain checkpoint-first guidance plus manual parent updates.");
             printGlobalOptions(log);
     }
@@ -714,6 +783,9 @@ function printCommandHelp(log, command, subcommand) {
         case "index":
             printIndexHelp(log);
             return;
+        case "db":
+            printDbHelp(log, subcommand);
+            return;
         case "show":
             printShowHelp(log);
             return;
@@ -977,6 +1049,111 @@ function runWorkspaceSubcommand(parsed, root) {
             throw new errors_1.UsageError("workspace requires ls/add/rm/enable/disable");
     }
 }
+function runDbSubcommand(parsed, root) {
+    const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
+    switch (subcommand) {
+        case "index": {
+            const action = (parsed.positionals[2] ?? "").toLowerCase();
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            const tolerant = parseBooleanFlag("--tolerant", parsed.flags["--tolerant"]);
+            switch (action) {
+                case "rebuild":
+                    if (parsed.positionals.length > 3) {
+                        throw new errors_1.UsageError(`mdkg db index ${action} does not accept positional arguments`);
+                    }
+                    (0, db_1.runDbIndexRebuildCommand)({ root, tolerant, json });
+                    return 0;
+                case "status":
+                    if (parsed.positionals.length > 3) {
+                        throw new errors_1.UsageError(`mdkg db index ${action} does not accept positional arguments`);
+                    }
+                    (0, db_1.runDbIndexStatusCommand)({ root, tolerant, json });
+                    return 0;
+                case "verify":
+                    if (parsed.positionals.length > 3) {
+                        throw new errors_1.UsageError(`mdkg db index ${action} does not accept positional arguments`);
+                    }
+                    (0, db_1.runDbIndexVerifyCommand)({ root, tolerant, json });
+                    return 0;
+                default:
+                    throw new errors_1.UsageError("mdkg db index requires rebuild/status/verify");
+            }
+        }
+        case "init": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("mdkg db init does not accept positional arguments");
+            }
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, db_1.runDbInitCommand)({ root, json });
+            return 0;
+        }
+        case "migrate":
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("mdkg db migrate does not accept positional arguments");
+            }
+            (0, db_1.runDbMigrateCommand)({ root, json: parseBooleanFlag("--json", parsed.flags["--json"]) });
+            return 0;
+        case "verify":
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("mdkg db verify does not accept positional arguments");
+            }
+            (0, db_1.runDbVerifyCommand)({ root, json: parseBooleanFlag("--json", parsed.flags["--json"]) });
+            return 0;
+        case "stats": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("mdkg db stats does not accept positional arguments");
+            }
+            (0, db_1.runDbStatsCommand)({ root, json: parseBooleanFlag("--json", parsed.flags["--json"]) });
+            return 0;
+        }
+        case "snapshot": {
+            const action = (parsed.positionals[2] ?? "").toLowerCase();
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            switch (action) {
+                case "seal":
+                    if (parsed.positionals.length > 3) {
+                        throw new errors_1.UsageError("mdkg db snapshot seal does not accept positional arguments");
+                    }
+                    (0, db_1.runDbSnapshotSealCommand)({ root, json });
+                    return 0;
+                case "verify":
+                    if (parsed.positionals.length > 3) {
+                        throw new errors_1.UsageError("mdkg db snapshot verify does not accept positional arguments");
+                    }
+                    (0, db_1.runDbSnapshotVerifyCommand)({ root, json });
+                    return 0;
+                case "status":
+                    if (parsed.positionals.length > 3) {
+                        throw new errors_1.UsageError("mdkg db snapshot status does not accept positional arguments");
+                    }
+                    (0, db_1.runDbSnapshotStatusCommand)({ root, json });
+                    return 0;
+                case "dump": {
+                    if (parsed.positionals.length > 3) {
+                        throw new errors_1.UsageError("mdkg db snapshot dump does not accept positional arguments");
+                    }
+                    const snapshot = requireFlagValue("--snapshot", parsed.flags["--snapshot"]);
+                    const output = requireFlagValue("--output", parsed.flags["--out"]);
+                    (0, db_1.runDbSnapshotDumpCommand)({ root, snapshot, output, json });
+                    return 0;
+                }
+                case "diff": {
+                    const left = parsed.positionals[3];
+                    const right = parsed.positionals[4];
+                    if (!left || !right || parsed.positionals.length > 5) {
+                        throw new errors_1.UsageError("mdkg db snapshot diff requires <left-snapshot> <right-snapshot>");
+                    }
+                    (0, db_1.runDbSnapshotDiffCommand)({ root, left, right, json });
+                    return 0;
+                }
+                default:
+                    throw new errors_1.UsageError("mdkg db snapshot requires seal/verify/status/dump/diff");
+            }
+        }
+        default:
+            throw new errors_1.UsageError("mdkg db requires index/init/migrate/verify/stats/snapshot");
+    }
+}
 function runCapabilitySubcommand(parsed, root) {
     const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
     switch (subcommand) {
@@ -1231,8 +1408,34 @@ function runSubgraphSubcommand(parsed, root) {
             (0, subgraph_1.runSubgraphRefreshCommand)({ root, alias, all, json });
             return 0;
         }
+        case "sync": {
+            if (parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("subgraph sync accepts at most one alias");
+            }
+            const alias = parsed.positionals[2];
+            const all = parseBooleanFlag("--all", parsed.flags["--all"]);
+            const dryRun = parseBooleanFlag("--dry-run", parsed.flags["--dry-run"]);
+            const allowDirty = parseBooleanFlag("--allow-dirty", parsed.flags["--allow-dirty"]);
+            (0, subgraph_1.runSubgraphSyncCommand)({ root, alias, all, dryRun, allowDirty, json });
+            return 0;
+        }
+        case "materialize": {
+            if (parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("subgraph materialize accepts at most one alias");
+            }
+            const alias = parsed.positionals[2];
+            const all = parseBooleanFlag("--all", parsed.flags["--all"]);
+            const target = requireFlagValue("--target", parsed.flags["--target"]);
+            if (!target) {
+                throw new errors_1.UsageError("subgraph materialize requires --target <path>");
+            }
+            const clean = parseBooleanFlag("--clean", parsed.flags["--clean"]);
+            const gitignore = parseBooleanFlag("--gitignore", parsed.flags["--gitignore"]);
+            (0, subgraph_1.runSubgraphMaterializeCommand)({ root, alias, all, target, clean, gitignore, json });
+            return 0;
+        }
         default:
-            throw new errors_1.UsageError("subgraph requires add/list/show/rm/enable/disable/verify/refresh");
+            throw new errors_1.UsageError("subgraph requires add/list/show/rm/enable/disable/verify/refresh/sync/materialize");
     }
 }
 function runWorkSubcommand(parsed, root) {
@@ -1822,6 +2025,8 @@ function runCommand(parsed, root, runtime) {
         }
         case "workspace":
             return runWorkspaceSubcommand(parsed, root);
+        case "db":
+            return runDbSubcommand(parsed, root);
         case "skill":
             return runSkillSubcommand(parsed, root);
         case "capability":

package/dist/commands/bundle.js

@@ -3,6 +3,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.sha256Buffer = sha256Buffer;
+exports.buildBundle = buildBundle;
+exports.parseBundle = parseBundle;
+exports.verifyBundle = verifyBundle;
 exports.runBundleCreateCommand = runBundleCreateCommand;
 exports.runBundleVerifyCommand = runBundleVerifyCommand;
 exports.runBundleShowCommand = runBundleShowCommand;
@@ -119,6 +123,8 @@ function isExcludedRelativePath(relative) {
         normalized.startsWith(".mdkg/pack/") ||
         normalized.includes("/.mdkg/bundles/") ||
         normalized.startsWith(".mdkg/bundles/") ||
+        normalized.includes("/.mdkg/subgraphs/") ||
+        normalized.startsWith(".mdkg/subgraphs/") ||
         normalized.includes("/.mdkg/index/") ||
         normalized.startsWith(".mdkg/index/") ||
         ((normalized.includes("/.mdkg/archive/") || normalized.startsWith(".mdkg/archive/")) &&

package/dist/commands/checkpoint.js

@@ -35,7 +35,7 @@ function normalizeId(value, key) {
 }
 function normalizeIdRef(value, key) {
     const normalized = value.toLowerCase();
-    if (!(0, id_1.isCanonicalIdRef)(normalized)) {
+    if (!(0, id_1.isPortableIdRef)(normalized)) {
         throw new errors_1.UsageError(`${key} entries must match <id> or <ws>:<id>: ${value}`);
     }
     return normalized;