mdkg 0.1.6 → 0.1.7

package/dist/graph/validate_graph.js

@@ -34,7 +34,15 @@ function validateEdgeTargets(index, allowMissing, knownSkillSlugs, externalWorks
         }
         for (const [edgeKey, values] of edgeLists) {
             for (const value of values) {
-                if (!nodes[value]) {
+                const targetNode = nodes[value];
+                if (targetNode &&
+                    ["epic", "parent", "prev", "next"].includes(edgeKey) &&
+                    !node.source?.imported &&
+                    targetNode.source?.imported) {
+                    pushError(errors, `${qid}: ${edgeKey} cannot target read-only subgraph node ${value}`);
+                    continue;
+                }
+                if (!targetNode) {
                     const [workspace] = value.split(":");
                     if (workspace && externalWorkspaces?.has(workspace)) {
                         continue;
@@ -106,6 +114,18 @@ function pathEndsWithContractRef(nodePath, contractRef) {
     return (normalizedNodePath === normalizedContractRef ||
         normalizedNodePath.endsWith(`/${normalizedContractRef}`));
 }
+function resolveNodeRef(index, ws, value) {
+    const qid = value.includes(":") ? value : `${ws}:${value}`;
+    return index.nodes[qid];
+}
+function resolveTypedNodeRef(index, ws, value, type) {
+    const node = resolveNodeRef(index, ws, value);
+    return node?.type === type ? node : undefined;
+}
+function isExternalWorkspaceRef(value, externalWorkspaces) {
+    const [workspace] = value.split(":");
+    return Boolean(workspace && value.includes(":") && externalWorkspaces?.has(workspace));
+}
 function validateAgentWorkflowSpecWorkContracts(index, allowMissing, errors) {
     const workNodesByWorkspace = {};
     for (const node of Object.values(index.nodes)) {
@@ -156,20 +176,7 @@ function validateAgentWorkflowSpecWorkContracts(index, allowMissing, errors) {
         }
     }
 }
-function validateAgentWorkflowWorkOrderWorkRefs(index, allowMissing, errors) {
-    const workNodesByWorkspaceAndId = {};
-    for (const node of Object.values(index.nodes)) {
-        if (node.type !== "work") {
-            continue;
-        }
-        if (!workNodesByWorkspaceAndId[node.ws]) {
-            workNodesByWorkspaceAndId[node.ws] = {};
-        }
-        workNodesByWorkspaceAndId[node.ws][node.id] = {
-            qid: node.qid,
-            version: typeof node.attributes.version === "string" ? node.attributes.version : undefined,
-        };
-    }
+function validateAgentWorkflowWorkOrderWorkRefs(index, allowMissing, externalWorkspaces, errors) {
     for (const [qid, node] of Object.entries(index.nodes)) {
         if (node.type !== "work_order") {
             continue;
@@ -178,8 +185,11 @@ function validateAgentWorkflowWorkOrderWorkRefs(index, allowMissing, errors) {
         if (typeof workId !== "string") {
             continue;
         }
-        const workNode = workNodesByWorkspaceAndId[node.ws]?.[workId];
+        const workNode = resolveTypedNodeRef(index, node.ws, workId, "work");
         if (!workNode) {
+            if (isExternalWorkspaceRef(workId, externalWorkspaces)) {
+                continue;
+            }
             if (allowMissing) {
                 continue;
             }
@@ -188,23 +198,13 @@ function validateAgentWorkflowWorkOrderWorkRefs(index, allowMissing, errors) {
         }
         const workVersion = node.attributes.work_version;
         if (typeof workVersion === "string" &&
-            workNode.version !== undefined &&
-            workVersion !== workNode.version) {
-            pushError(errors, `${qid}: work_version ${workVersion} does not match ${workNode.qid} version ${workNode.version}`);
+            typeof workNode.attributes.version === "string" &&
+            workVersion !== workNode.attributes.version) {
+            pushError(errors, `${qid}: work_version ${workVersion} does not match ${workNode.qid} version ${workNode.attributes.version}`);
         }
     }
 }
-function validateAgentWorkflowReceiptWorkOrderRefs(index, allowMissing, errors) {
-    const workOrderIdsByWorkspace = {};
-    for (const node of Object.values(index.nodes)) {
-        if (node.type !== "work_order") {
-            continue;
-        }
-        if (!workOrderIdsByWorkspace[node.ws]) {
-            workOrderIdsByWorkspace[node.ws] = new Set();
-        }
-        workOrderIdsByWorkspace[node.ws].add(node.id);
-    }
+function validateAgentWorkflowReceiptWorkOrderRefs(index, allowMissing, externalWorkspaces, errors) {
     for (const [qid, node] of Object.entries(index.nodes)) {
         if (node.type !== "receipt") {
             continue;
@@ -213,7 +213,10 @@ function validateAgentWorkflowReceiptWorkOrderRefs(index, allowMissing, errors)
         if (typeof workOrderId !== "string") {
             continue;
         }
-        if (workOrderIdsByWorkspace[node.ws]?.has(workOrderId)) {
+        if (resolveTypedNodeRef(index, node.ws, workOrderId, "work_order")) {
+            continue;
+        }
+        if (isExternalWorkspaceRef(workOrderId, externalWorkspaces)) {
             continue;
         }
         if (allowMissing) {
@@ -238,7 +241,17 @@ function buildSpecRolesByWorkspace(index) {
     }
     return specRolesByWorkspace;
 }
-function validateAgentWorkflowSubagentRefs(index, allowMissing, errors) {
+function resolveSpecRole(index, ws, value) {
+    const node = resolveTypedNodeRef(index, ws, value, "spec");
+    if (!node) {
+        return undefined;
+    }
+    return {
+        qid: node.qid,
+        role: typeof node.attributes.role === "string" ? node.attributes.role : undefined,
+    };
+}
+function validateAgentWorkflowSubagentRefs(index, allowMissing, externalWorkspaces, errors) {
     const specRolesByWorkspace = buildSpecRolesByWorkspace(index);
     for (const [qid, node] of Object.entries(index.nodes)) {
         if (node.type !== "spec" && node.type !== "work") {
@@ -252,8 +265,13 @@ function validateAgentWorkflowSubagentRefs(index, allowMissing, errors) {
             if (typeof value !== "string") {
                 continue;
             }
-            const specNode = specRolesByWorkspace[node.ws]?.[value];
+            const specNode = value.includes(":")
+                ? resolveSpecRole(index, node.ws, value)
+                : specRolesByWorkspace[node.ws]?.[value];
             if (!specNode) {
+                if (isExternalWorkspaceRef(value, externalWorkspaces)) {
+                    continue;
+                }
                 if (allowMissing) {
                     continue;
                 }
@@ -266,28 +284,7 @@ function validateAgentWorkflowSubagentRefs(index, allowMissing, errors) {
         }
     }
 }
-function validateAgentWorkflowDisputeRefs(index, allowMissing, errors) {
-    const workOrderIdsByWorkspace = {};
-    const receiptNodesByWorkspaceAndId = {};
-    for (const node of Object.values(index.nodes)) {
-        if (node.type === "work_order") {
-            if (!workOrderIdsByWorkspace[node.ws]) {
-                workOrderIdsByWorkspace[node.ws] = new Set();
-            }
-            workOrderIdsByWorkspace[node.ws].add(node.id);
-        }
-        if (node.type === "receipt") {
-            if (!receiptNodesByWorkspaceAndId[node.ws]) {
-                receiptNodesByWorkspaceAndId[node.ws] = {};
-            }
-            receiptNodesByWorkspaceAndId[node.ws][node.id] = {
-                qid: node.qid,
-                workOrderId: typeof node.attributes.work_order_id === "string"
-                    ? node.attributes.work_order_id
-                    : undefined,
-            };
-        }
-    }
+function validateAgentWorkflowDisputeRefs(index, allowMissing, externalWorkspaces, errors) {
     for (const [qid, node] of Object.entries(index.nodes)) {
         if (node.type !== "dispute") {
             continue;
@@ -296,23 +293,35 @@ function validateAgentWorkflowDisputeRefs(index, allowMissing, errors) {
         if (typeof workOrderId !== "string") {
             continue;
         }
-        if (!workOrderIdsByWorkspace[node.ws]?.has(workOrderId) && !allowMissing) {
+        if (!resolveTypedNodeRef(index, node.ws, workOrderId, "work_order") &&
+            !isExternalWorkspaceRef(workOrderId, externalWorkspaces) &&
+            !allowMissing) {
             pushError(errors, `${qid}: work_order_id references missing WORK_ORDER.md ${workOrderId}`);
         }
         const receiptId = node.attributes.receipt_id;
         if (typeof receiptId !== "string") {
             continue;
         }
-        const receiptNode = receiptNodesByWorkspaceAndId[node.ws]?.[receiptId];
+        const receiptNode = resolveTypedNodeRef(index, node.ws, receiptId, "receipt");
         if (!receiptNode) {
+            if (isExternalWorkspaceRef(receiptId, externalWorkspaces)) {
+                continue;
+            }
             if (allowMissing) {
                 continue;
             }
             pushError(errors, `${qid}: receipt_id references missing RECEIPT.md ${receiptId}`);
             continue;
         }
-        if (receiptNode.workOrderId !== undefined && receiptNode.workOrderId !== workOrderId) {
-            pushError(errors, `${qid}: receipt_id ${receiptId} belongs to work_order_id ${receiptNode.workOrderId}, not ${workOrderId}`);
+        const receiptWorkOrderId = typeof receiptNode.attributes.work_order_id === "string"
+            ? receiptNode.attributes.work_order_id
+            : undefined;
+        const receiptWorkOrderQid = receiptWorkOrderId
+            ? receiptWorkOrderId.includes(":") ? receiptWorkOrderId : `${receiptNode.ws}:${receiptWorkOrderId}`
+            : undefined;
+        const disputeWorkOrderQid = workOrderId.includes(":") ? workOrderId : `${node.ws}:${workOrderId}`;
+        if (receiptWorkOrderQid !== undefined && receiptWorkOrderQid !== disputeWorkOrderQid) {
+            pushError(errors, `${qid}: receipt_id ${receiptId} belongs to work_order_id ${receiptWorkOrderId}, not ${workOrderId}`);
         }
     }
 }
@@ -331,6 +340,9 @@ function validateAgentWorkflowNodeIdRef(qid, ws, field, value, nodeIdsByWorkspac
     if (workspace && value.includes(":") && externalWorkspaces?.has(workspace)) {
         return;
     }
+    if (value.includes(":") && nodeIdsByWorkspace[workspace]?.has(value.split(":").slice(1).join(":"))) {
+        return;
+    }
     if (nodeIdsByWorkspace[ws]?.has(value)) {
         return;
     }
@@ -514,10 +526,10 @@ function collectGraphErrors(index, options = {}) {
     validateEdgeTargets(index, allowMissing, knownSkillSlugs, externalWorkspaces, errors);
     validatePrevNextSymmetry(index, allowMissing, errors);
     validateAgentWorkflowSpecWorkContracts(index, allowMissing, errors);
-    validateAgentWorkflowWorkOrderWorkRefs(index, allowMissing, errors);
-    validateAgentWorkflowReceiptWorkOrderRefs(index, allowMissing, errors);
-    validateAgentWorkflowSubagentRefs(index, allowMissing, errors);
-    validateAgentWorkflowDisputeRefs(index, allowMissing, errors);
+    validateAgentWorkflowWorkOrderWorkRefs(index, allowMissing, externalWorkspaces, errors);
+    validateAgentWorkflowReceiptWorkOrderRefs(index, allowMissing, externalWorkspaces, errors);
+    validateAgentWorkflowSubagentRefs(index, allowMissing, externalWorkspaces, errors);
+    validateAgentWorkflowDisputeRefs(index, allowMissing, externalWorkspaces, errors);
     validateAgentWorkflowFeedbackProposalRefs(index, allowMissing, knownSkillSlugs, externalWorkspaces, errors);
     validateArchiveUriRefs(index, allowMissing, errors);
     validateGoalRefs(index, allowMissing, errors);

package/dist/init/AGENT_START.md

@@ -31,13 +31,25 @@ Agent operating prompt:
 - Use `mdkg skill list`, `mdkg skill search`, and `mdkg skill show <slug>` for skill discovery.
 - Use `mdkg capability list/search/show` for deterministic skills, `SPEC.md`, `WORK.md`, core-doc, and design-doc capability discovery.
 - Use `mdkg index` to refresh JSON compatibility caches and `.mdkg/index/mdkg.sqlite` when SQLite mode is enabled.
+- Treat `.mdkg/db` as project application state; use `mdkg db init` to create
+  the generic scaffold and enable `db.enabled` without creating an active
+  runtime SQLite database. Use `mdkg db migrate` after init to create or update
+  the runtime SQLite database with mdkg-owned generic foundation migrations.
+  Use `mdkg db verify` and `mdkg db stats` for non-mutating health and summary
+  receipts. Use `mdkg db snapshot seal` for explicit sealed checkpoints,
+  `mdkg db snapshot verify/status` for checkpoint health, and
+  `mdkg db snapshot dump/diff` for deterministic review aids. Keep
+  `.mdkg/db/runtime/` and WAL/SHM/journal/lock/temp files ignored unless a
+  sealed artifact policy explicitly says otherwise.
 - Use `mdkg archive add/list/show/verify/compress` for committed source and artifact sidecars under `.mdkg/archive`.
 - Use `mdkg work ...` helpers for semantic mirror contracts, work orders, receipts, and artifact registration.
 - Treat work contracts, orders, and receipts as committed semantic mirrors only; never store raw secrets, credentials, live payment state, ledger mutations, or canonical marketplace state in mdkg.
 - Use `artifact://...` for external/runtime-managed artifacts and `archive://...` for committed mdkg archive sidecars.
 - Use `mdkg bundle create/list/show/verify` for explicit full `.mdkg` graph snapshot bundles.
-- Use `mdkg subgraph add/list/verify` to register child bundle snapshots as read-only planning context.
+- Use `mdkg subgraph add/list/verify/sync/materialize` to register child bundle snapshots as read-only planning context, refresh root-owned child bundle snapshots, and optionally generate ignored inspection trees.
 - Use `mdkg capability resolve` to rank local and subgraph capabilities for orchestration planning.
+- Use `mdkg subgraph sync --dry-run --json` before refreshing root-owned child bundle snapshots, then `mdkg subgraph sync --json` when the receipt is acceptable.
+- Use `mdkg subgraph materialize ... --target .mdkg/subgraphs --gitignore` only for generated read-only inspection trees; never mutate materialized files.
 - Use `mdkg pack <id> --visibility public|internal` only when you need a public-safe or internal-safe pack; no flag remains private-capable local behavior.
 - Mark archive sidecars public only with explicit `mdkg archive add --visibility public` intent.
 - Treat sidecar `.md` plus deterministic `.zip` caches as the commit-eligible archive record; validation and `mdkg archive verify` both check ZIP payload integrity.

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -27,6 +27,39 @@ Index backend:
 - fresh mdkg workspaces default to `index.backend: sqlite`
 - `.mdkg/index/mdkg.sqlite` is rebuildable and commit-eligible when intentionally tracked
 - JSON compatibility caches remain generated and ignored by default
+- `mdkg db index rebuild` writes the same derived caches as `mdkg index`
+- `mdkg db index status` reports graph cache health without mutating files
+- `mdkg db index verify` fails on missing, stale, corrupt, schema-mismatched, or SQLite source-fingerprint-mismatched cache state
+
+Project database commands:
+- `mdkg db index rebuild [--tolerant] [--json]`
+- `mdkg db index status [--json]`
+- `mdkg db index verify [--json]`
+- `mdkg db init [--json]`
+- `mdkg db migrate [--json]`
+- `mdkg db verify [--json]`
+- `mdkg db stats [--json]`
+- `mdkg db snapshot seal [--json]`
+- `mdkg db snapshot verify [--json]`
+- `mdkg db snapshot status [--json]`
+- `mdkg db snapshot dump [--snapshot <path>] [--output <path>] [--json]`
+- `mdkg db snapshot diff <left-snapshot> <right-snapshot> [--json]`
+- `.mdkg/db` is project application state, separate from `.mdkg/index`
+- `mdkg db init` creates the generic `.mdkg/db` scaffold, writes
+  `.mdkg/db/project-db.json`, enables `db.enabled`, and does not create an
+  active runtime SQLite database
+- `mdkg db migrate` creates or updates the configured active runtime SQLite
+  database and applies mdkg-owned generic foundation migrations only
+- `mdkg db migrate` records migration order, checksums, and applied timestamps
+  in the configured migration table
+- `mdkg db verify` checks config, layout, runtime SQLite integrity, migration
+  metadata, receipt directory policy, and transient runtime files
+- `mdkg db stats` reports table counts, database size, migration state,
+  transient runtime files, receipt-file count, and state snapshot presence
+- `mdkg db snapshot seal` writes an opt-in sealed checkpoint and manifest under
+  `.mdkg/db/state`; `snapshot verify/status/dump/diff` inspect and review that
+  checkpoint without treating raw binary diffs as human-readable truth
+- active `.mdkg/db/runtime/` files and `.mdkg/db` WAL/SHM/journal/lock/temp files are ignored by default
 
 Validation commands:
 - `mdkg validate [--out <path>] [--quiet] [--json]`
@@ -133,8 +166,12 @@ Subgraph orchestration:
 - `mdkg subgraph disable <alias> [--json]`
 - `mdkg subgraph verify [alias|--all] [--json]`
 - `mdkg subgraph refresh [alias|--all] [--json]`
+- `mdkg subgraph sync [alias|--all] [--dry-run] [--allow-dirty] [--json]`
+- `mdkg subgraph materialize [alias|--all] --target <path> [--clean] [--gitignore] [--json]`
 - subgraphs are read-only planning views and use subgraph-alias qids such as `child_repo:task-1`
 - subgraph refresh reloads configured bundle sources only and never mutates child repos
+- subgraph sync builds root-owned bundle snapshots from configured clean child Git repo `source_path` entries
+- subgraph materialize extracts generated inspection trees under a target directory; `.mdkg/subgraphs/` is local generated state
 - public/internal subgraphs require public bundle profiles
 
 Work semantic mirrors:

package/dist/init/README.md

@@ -13,6 +13,7 @@ mdkg is pre-v1 public alpha software. Graph, cache, bundle, and DAL contracts ma
 - `archive/`: sidecar metadata and deterministic compressed source/artifact caches
 - `bundles/`: optional committed full graph snapshot bundles
 - `index/`: generated JSON caches plus optional commit-eligible `mdkg.sqlite`
+- `db/`: future project application database layout and receipts
 - `pack/`: generated context packs (do not commit)
 
 ## Next Commands
@@ -59,11 +60,31 @@ Ensure ignore files include:
 - `.mdkg/index/*.sqlite-wal`
 - `.mdkg/index/*.sqlite-shm`
 - `.mdkg/index/*.sqlite-journal`
+- `.mdkg/db/runtime/`
+- `.mdkg/db/**/*.sqlite-wal`
+- `.mdkg/db/**/*.sqlite-shm`
+- `.mdkg/db/**/*.sqlite-journal`
+- `.mdkg/db/**/*.lock`
+- `.mdkg/db/**/*.tmp`
 - `.mdkg/pack/`
 - `.mdkg/archive/**/source/`
 
 Fresh mdkg workspaces default to `index.backend: sqlite`; `.mdkg/index/mdkg.sqlite` is a rebuildable cache and may be committed when the repo intentionally tracks it and it stays reasonably small.
 
+`.mdkg/db` is reserved for project application database state, separate from
+`.mdkg/index`. Run `mdkg db init` to create the generic scaffold, write
+`.mdkg/db/project-db.json`, and enable `db.enabled`; it does not create an
+active runtime SQLite database. Run `mdkg db migrate` after init to create or
+update the active runtime SQLite database with mdkg-owned generic foundation
+migrations. Use `mdkg db verify` for non-mutating health checks and
+`mdkg db stats` for table counts, DB size, migration state, and receipt-file
+counts. Use `mdkg db snapshot seal` to create an opt-in sealed checkpoint under
+`.mdkg/db/state`, then use `mdkg db snapshot verify/status` for integrity and
+freshness checks. Use `mdkg db snapshot dump/diff` as deterministic review aids
+for SQLite snapshots. Keep active runtime DB files and transient
+WAL/SHM/journal, lock, and temp files ignored. Commit schema files, manifests,
+receipts, and sealed state snapshots only by explicit repo policy.
+
 Recommended:
 
 ```bash
@@ -97,6 +118,10 @@ mdkg capability resolve "child capability" --json
 mdkg subgraph verify child_repo --json
 ```
 
+Use `mdkg subgraph sync child_repo --dry-run --json` before writing a refreshed root-owned child bundle snapshot, then `mdkg subgraph sync child_repo --json` when the receipt is acceptable. `sync` inspects the configured child Git repo `source_path`, refuses dirty tracked changes by default, verifies the new bundle, and records `source_repo` as `<branch>@<sha>` without committing, pulling, pushing, checking out, resetting, or mutating child mdkg Markdown.
+
+Use `mdkg subgraph materialize child_repo --target .mdkg/subgraphs --gitignore --json` only when you need a generated read-only inspection tree. Materialized views are local generated state and are not root graph nodes.
+
 Subgraph nodes use the subgraph alias as their qid prefix and can be inspected or packed, but mutations must happen in the owning child repo.
 
 ## Archive and Work Mirrors

package/dist/init/config.json

@@ -21,6 +21,17 @@
     "output_dir": ".mdkg/bundles",
     "default_profile": "private"
   },
+  "db": {
+    "enabled": false,
+    "schema_version": 1,
+    "root_path": ".mdkg/db",
+    "schema_path": ".mdkg/db/schema",
+    "migrations_path": ".mdkg/db/schema/migrations",
+    "runtime_path": ".mdkg/db/runtime/project.sqlite",
+    "state_path": ".mdkg/db/state/project.sqlite",
+    "receipts_path": ".mdkg/db/receipts",
+    "migration_table": "mdkg_schema_migration"
+  },
   "subgraphs": {},
   "pack": {
     "default_depth": 2,

package/dist/init/core/rule-3-cli-contract.md

@@ -254,8 +254,15 @@ Common flags:
   - `mdkg subgraph disable <alias> [--json]`
   - `mdkg subgraph verify [alias|--all] [--json]`
   - `mdkg subgraph refresh [alias|--all] [--json]`
+  - `mdkg subgraph sync [alias|--all] [--dry-run] [--allow-dirty] [--json]`
+  - `mdkg subgraph materialize [alias|--all] --target <path> [--clean] [--gitignore] [--json]`
   - subgraphs are read-only projected graph views; child repos remain owners of real mutations and commits
   - `subgraph refresh` reloads configured bundle sources only and never builds or mutates child repos
+  - `subgraph sync` is the explicit child-bundle build command; it uses configured root-relative `source_path`, requires a contained child Git repo with `.mdkg`, refuses dirty tracked child changes unless `--allow-dirty` is supplied, writes configured root-owned bundle paths, verifies bundles, and updates `source_repo` to `<branch>@<sha>`
+  - `subgraph sync --dry-run` writes no bundles, config, or indexes and reports intended paths, bundle hashes, dirty state, and source repo
+  - `subgraph materialize` extracts configured bundles into generated read-only inspection trees under `<target>/<alias>`, writes `.mdkg-materialized.json`, and only cleans existing alias directories with both `--clean` and a materialization marker
+  - `.mdkg/subgraphs/` materialized views are ignored by local graph scanning, search, validation, packing, bundle creation, and SQLite hydration
+  - root-authored relationship/reference fields may point at configured subgraph qids; local ownership fields (`epic`, `parent`, `prev`, `next`) remain local-only
   - `subgraph verify` exits nonzero for stale, missing, corrupt, profile-mismatched, or duplicate-id subgraphs
   - public/internal subgraphs require `expected_profile: public`; private bundle profiles cannot be promoted through subgraph visibility
   - legacy `mdkg bundle import ...` exits with guidance to run `mdkg upgrade --apply` and use `mdkg subgraph ...`

package/dist/init/core/rule-4-repo-safety-and-ignores.md

@@ -10,7 +10,7 @@ relates: []
 refs: []
 aliases: []
 created: 2026-01-06
-updated: 2026-01-14
+updated: 2026-06-03
 ---
 
 # Repo safety and ignores
@@ -23,6 +23,8 @@ mdkg content may contain sensitive notes and internal project planning. This rul
 - `.mdkg/` must not be published to npm.
 - Generated JSON index, temp, lock, WAL, SHM, and journal files under `.mdkg/index/` must not be committed.
 - `.mdkg/index/mdkg.sqlite` is a rebuildable access cache and may be committed when the repo intentionally tracks it and it stays reasonably small.
+- `.mdkg/db/runtime/` active project database files and `.mdkg/db` transient WAL, SHM, journal, lock, and temp files must not be committed.
+- `.mdkg/db/schema/`, `.mdkg/db/receipts/`, manifests, and sealed state snapshots are commit-eligible only by explicit repo policy.
 - `.mdkg/state/` stores local workflow convenience state and must not be committed.
 - `.mdkg/bundles/` may be committed only when the repo intentionally tracks private or public snapshot bundles.
 
@@ -38,6 +40,12 @@ The repo MUST ignore at minimum:
 - `.mdkg/index/*.sqlite-wal`
 - `.mdkg/index/*.sqlite-shm`
 - `.mdkg/index/*.sqlite-journal`
+- `.mdkg/db/runtime/`
+- `.mdkg/db/**/*.sqlite-wal`
+- `.mdkg/db/**/*.sqlite-shm`
+- `.mdkg/db/**/*.sqlite-journal`
+- `.mdkg/db/**/*.lock`
+- `.mdkg/db/**/*.tmp`
 - `.mdkg/state/`
 - `.mdkg/pack/`
 - `.mdkg/archive/**/source/`
@@ -49,6 +57,12 @@ Recommended `.gitignore` entries:
 - `.mdkg/index/*.sqlite-wal`
 - `.mdkg/index/*.sqlite-shm`
 - `.mdkg/index/*.sqlite-journal`
+- `.mdkg/db/runtime/`
+- `.mdkg/db/**/*.sqlite-wal`
+- `.mdkg/db/**/*.sqlite-shm`
+- `.mdkg/db/**/*.sqlite-journal`
+- `.mdkg/db/**/*.lock`
+- `.mdkg/db/**/*.tmp`
 - `.mdkg/state/`
 - `.mdkg/pack/`
 - `.mdkg/archive/**/source/`
@@ -79,6 +93,12 @@ If the repo is containerized:
   - `.mdkg/index/*.sqlite-wal`
   - `.mdkg/index/*.sqlite-shm`
   - `.mdkg/index/*.sqlite-journal`
+  - `.mdkg/db/runtime/`
+  - `.mdkg/db/**/*.sqlite-wal`
+  - `.mdkg/db/**/*.sqlite-shm`
+  - `.mdkg/db/**/*.sqlite-journal`
+  - `.mdkg/db/**/*.lock`
+  - `.mdkg/db/**/*.tmp`
   - `node_modules/`
   - `dist/` (if built in container)
   - any other local artifacts
@@ -90,7 +110,7 @@ For application builds:
 
 `mdkg init` updates ignore files by default for safety:
 
-- `.gitignore` appends generated index cache/temp/lock patterns, `.mdkg/state/`, `.mdkg/pack/`, and raw archive source ignores.
+- `.gitignore` appends generated index cache/temp/lock patterns, project DB runtime/transient patterns, `.mdkg/state/`, `.mdkg/pack/`, and raw archive source ignores.
 - `.npmignore` appends `.mdkg/`, generated index cache/temp/lock patterns, and `.mdkg/pack/`.
 - `--no-update-ignores` disables these default writes
 
@@ -108,6 +128,19 @@ Explicit flags remain available and take precedence:
 - `.mdkg/state/` contains local workflow convenience state such as selected goals and MUST stay ignored.
 - Index rebuild should be deterministic and safe to regenerate at any time.
 
+## Project DB safety
+
+- `.mdkg/db/` is reserved for project application database state, separate from
+  the rebuildable `.mdkg/index/` graph cache.
+- The generic layout is `.mdkg/db/schema/`, `.mdkg/db/runtime/`,
+  `.mdkg/db/state/`, and `.mdkg/db/receipts/`.
+- Active runtime DB files under `.mdkg/db/runtime/` and transient WAL, SHM,
+  journal, lock, and temp files under `.mdkg/db/` stay ignored by default.
+- Schema files, manifests, receipt artifacts, and opt-in sealed snapshots are
+  commit-eligible only by explicit repo policy.
+- `mdkg doctor` should warn when active project DB runtime/transient files are
+  present so they are not mistaken for sealed state.
+
 ## Bundle safety
 
 - `.mdkg/bundles/` stores explicit snapshot artifacts and is not ignored by default.

package/dist/init/init-manifest.json

@@ -1,12 +1,12 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "mdkg_version": "0.1.6",
+  "mdkg_version": "0.1.7",
   "files": [
     {
       "path": ".mdkg/config.json",
       "category": "config",
-      "sha256": "5d2cf5e773353a59178fe86f8528413a00a73e2879fb1e020d01b49c0715a9ce"
+      "sha256": "8055c72aa3c55f8a49d532a735bc29e3baa2e2bf478e9d092b83bec9e46fa78c"
     },
     {
       "path": ".mdkg/core/core.md",
@@ -36,12 +36,12 @@
     {
       "path": ".mdkg/core/rule-3-cli-contract.md",
       "category": "core",
-      "sha256": "0b72a2448cc91779278fed6e011c3936c31c5b11a7365a4145941dcc90f805a3"
+      "sha256": "f61b84ff6e5abae91365c4f623ccbd78f25dfcfef09822fefb3abf0119d65739"
     },
     {
       "path": ".mdkg/core/rule-4-repo-safety-and-ignores.md",
       "category": "core",
-      "sha256": "d8aff39af7a00e63db51831d4324856bbf49d3e3434141416903bad42c7d5380"
+      "sha256": "3c7a4e34febf05b3202af4bb21cbbbeb430c2b872e3a7030920bbc6b045bd0b8"
     },
     {
       "path": ".mdkg/core/rule-5-release-and-versioning.md",
@@ -61,7 +61,7 @@
     {
       "path": ".mdkg/README.md",
       "category": "mdkg_doc",
-      "sha256": "f733792daa2b0f3318fd7b39fa2f812c61b8a3f5f630dba2f271cdcb10af9927"
+      "sha256": "57a55e0f3743415f5ba1d166d3abf61b2ad868cc11d0e7083b7fd8075dae95a1"
     },
     {
       "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
@@ -186,7 +186,7 @@
     {
       "path": "AGENT_START.md",
       "category": "startup_doc",
-      "sha256": "7676e534b2f161a19764de666d9362b9ee1c6cdec6ec9fdfacab2eb52ce0e80d"
+      "sha256": "d9ba16476749bd96c986f356b40a7abe4b1321b10260f61f85198220c11ac994"
     },
     {
       "path": "AGENTS.md",
@@ -201,7 +201,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "a2f59afae403fff7335b0cf0109ee550c7a864b9ef6744b39a645096432e5206"
+      "sha256": "51c8f3e6fff4c2a0c385e39c2c41a0b26136ca9d2efcd4593f0099c3cdc0a4a8"
     },
     {
       "path": "llms.txt",

package/dist/util/argparse.js

@@ -84,6 +84,8 @@ const VALUE_FLAGS = new Set([
     "--source-repo",
     "--max-stale-seconds",
     "--requires",
+    "--target",
+    "--snapshot",
 ]);
 const BOOLEAN_FLAGS = new Set([
     "--tolerant",
@@ -118,6 +120,9 @@ const BOOLEAN_FLAGS = new Set([
     "--clear-blocked-by",
     "--all",
     "--fresh-only",
+    "--allow-dirty",
+    "--clean",
+    "--gitignore",
 ]);
 const FLAG_ALIASES = {
     "--o": "--out",

package/dist/util/refs.js

@@ -27,7 +27,7 @@ function isSha256Ref(value) {
     return SHA256_RE.test(value);
 }
 function isPortableOrUriRef(value) {
-    return (0, id_1.isPortableId)(value.toLowerCase()) || isUriRef(value);
+    return (0, id_1.isPortableIdRef)(value.toLowerCase()) || isUriRef(value);
 }
 function validatePortableOrUriRef(value) {
     if (isUriRef(value)) {
@@ -36,5 +36,5 @@ function validatePortableOrUriRef(value) {
         }
         return true;
     }
-    return value === value.toLowerCase() && (0, id_1.isPortableId)(value);
+    return value === value.toLowerCase() && (0, id_1.isPortableIdRef)(value);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdkg",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Markdown Knowledge Graph",
   "license": "MIT",
   "bin": {
@@ -16,6 +16,8 @@
     "smoke:upgrade": "npm run build && node scripts/smoke-upgrade.js",
     "smoke:init": "npm run build && node scripts/smoke-init.js",
     "smoke:capabilities": "npm run build && node scripts/smoke-capabilities.js",
+    "smoke:db": "npm run build && node scripts/smoke-db.js",
+    "smoke:db-snapshot": "npm run build && node scripts/smoke-db-snapshot.js",
     "smoke:archive-work": "npm run build && node scripts/smoke-archive-work.js",
     "smoke:bundle": "npm run build && node scripts/smoke-bundle.js",
     "smoke:bundle-import": "npm run smoke:subgraph",
@@ -26,7 +28,7 @@
     "cli:snapshot": "npm run build && node scripts/cli_help_snapshot.js",
     "cli:check": "npm run build && node scripts/cli_help_snapshot.js --check",
     "prepack": "npm run build && node scripts/assert-publish-ready.js",
-    "prepublishOnly": "npm run test && npm run cli:check && node dist/cli.js validate && npm run smoke:consumer && npm run smoke:matrix && npm run smoke:upgrade && npm run smoke:init && npm run smoke:capabilities && npm run smoke:archive-work && npm run smoke:bundle && npm run smoke:subgraph && npm run smoke:visibility && npm run smoke:sqlite && npm run smoke:parallel && npm run smoke:goal && node scripts/assert-publish-ready.js",
+    "prepublishOnly": "npm run test && npm run cli:check && node dist/cli.js validate && npm run smoke:consumer && npm run smoke:matrix && npm run smoke:upgrade && npm run smoke:init && npm run smoke:capabilities && npm run smoke:db && npm run smoke:db-snapshot && npm run smoke:archive-work && npm run smoke:bundle && npm run smoke:subgraph && npm run smoke:visibility && npm run smoke:sqlite && npm run smoke:parallel && npm run smoke:goal && node scripts/assert-publish-ready.js",
     "postinstall": "node scripts/postinstall.js",
     "smoke:subgraph": "npm run build && node scripts/smoke-subgraph.js"
   },