mdkg 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -8,6 +8,45 @@ mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL con
 
 ## Unreleased
 
+## 0.5.2 - 2026-07-15
+
+### Added
+
+- Added `mdkg git materialize --request <file|-> --json` with strict
+  `mdkg.git.materialize.request.v1` parsing, full-ref accepted-revision
+  verification, SHA-1/SHA-256 support, bounded auth capability checks, explicit
+  submodule/project-memory policies, and atomic contained publication.
+- Added bounded `mdkg.git.materialize.receipt.v1` success and failure evidence,
+  installed-tarball consumer coverage, generated CLI contract metadata, and a
+  dedicated docs.mdkg.dev advanced-alpha guide.
+
+### Security
+
+- Disabled Git prompts, repository hooks, push, and recursive submodules during
+  materialization; candidate project-memory validation does not index or execute
+  repository-controlled scripts, hooks, skills, or commands.
+- Redacted credentials, environment values, helper output, socket paths, raw Git
+  output, repository contents, and absolute local paths from materialization
+  receipts while preserving bounded identity, policy, destination, and cleanup
+  evidence.
+
+## 0.5.1 - 2026-07-14
+
+### Changed
+
+- Archive compression now derives writable ownership from enabled local
+  workspaces. `archive compress --all --ws <local-alias>` limits bulk selection,
+  and exact workspace-qualified archive qids are supported for direct targets.
+- Archive compression JSON receipts preserve existing fields and add selected
+  workspace and read-only imported-projection exclusion evidence.
+
+### Fixed
+
+- Fixed `archive compress --all` traversing imported subgraph ZIP-fragment paths
+  and potentially mutating earlier local archives before a later invalid target
+  failed. Imported archives remain discoverable but fail closed for direct
+  compression, and the complete local selection is preflighted before writes.
+
 ## 0.5.0 - 2026-07-11
 
 ### Added

package/CLI_COMMAND_MATRIX.md

@@ -1,7 +1,7 @@
 # CLI Command Matrix
 
-as_of: 2026-07-11
-package_version_in_source: 0.5.0
+as_of: 2026-07-15
+package_version_in_source: 0.5.2
 source: live help from `src/cli.ts`, runtime command handlers, and `dec-15`..`dec-18`
 status: canonical single-source command and flag reference for mdkg
 
@@ -657,9 +657,9 @@ Usage:
 - `mdkg archive show <id-or-archive-uri> [--ws <alias>] [--json]`
 - `mdkg archive verify [id-or-archive-uri] [--json]`
 - `mdkg archive verify [id-or-archive-uri] [--ws <alias>] [--json]`
-- `mdkg archive compress <id-or-archive-uri|--all> [--json]`
-- `mdkg archive compress <id-or-archive-uri> [--ws <alias>] [--json]`
-- `mdkg archive compress --all [--json]`
+- `mdkg archive compress <id-or-archive-uri-or-qid|--all> [--ws <local-alias>] [--json]`
+- `mdkg archive compress <id-or-archive-uri-or-qid> [--ws <local-alias>] [--json]`
+- `mdkg archive compress --all [--ws <local-alias>] [--json]`
 
 Fields:
 - archive sidecars use `type: archive`
@@ -673,6 +673,18 @@ Notes:
 - archive visibility defaults to `private`
 - `archive://<archive.id>` refs are validated against local archive sidecars
 - `archive verify` and `validate` both check the ZIP hash, ZIP readability, payload SHA-256, and payload byte size
+- archive compression is owned exclusively by enabled local workspaces; imported
+  archive projections remain visible to list/show/search but are read-only
+- `archive compress --all` selects every locally writable archive, while
+  `--all --ws <local-alias>` limits selection to one enabled local workspace
+- direct workspace-qualified qids such as `root:archive.example` are supported;
+  imported qids and `--ws <imported-alias>` fail before filesystem path
+  construction with source-workspace and bundle-refresh guidance
+- compression preflights ownership, identity, containment, symlinks, raw input,
+  and destinations for the complete selected set before the first write
+- JSON keeps `action`, `count`, and `archives`, and adds
+  `selection: { requested_workspace, selected_workspaces,
+  excluded_read_only: [{ workspace, qid, reason }] }`
 - `archive verify` passes when the raw local source file is missing but the committed sidecar and ZIP cache are valid
 - generated raw source copies live under `.mdkg/archive/**/source/` and are ignored by default
 - `doctor` warns when archive ZIP caches exceed `archive.large_cache_warning_bytes` (default `26214400`; `0` disables)
@@ -767,12 +779,14 @@ JSON receipts:
 
 When to use:
 - inspect the current Git-backed mdkg project and accepted revision evidence
+- materialize a strict caller-selected Git ref only after commit, tree, and policy verification
 - clone or fetch real Git remotes through the system Git CLI with external auth
 - close out mdkg state to static receipts before an agent checkpoint commit
 - prove push readiness before any approval-gated real remote push
 
 Usage:
 - `mdkg git inspect [--json]`
+- `mdkg git materialize --request <file|-> [--json]`
 - `mdkg git clone <repository-ref> --target <path> [--branch <name>] [--json]`
 - `mdkg git fetch [--remote <name>] [--branch <name>] [--json]`
 - `mdkg git closeout [--queue-policy drain|paused] [--output <path>] [--json]`
@@ -782,6 +796,7 @@ Usage:
 - `mdkg git push --remote <name> --branch <name> [--stage-all --message <text>] [--json]`
 
 Flags:
+- `--request <file|->`
 - `--target <path>`
 - `--branch <name>`
 - `--remote <name>`
@@ -796,6 +811,10 @@ Notes:
 - v1 uses the system Git CLI; authentication stays external through credential helpers, SSH, `gh`, CI/runtime env, or shell state
 - mdkg rejects repository refs and push remotes with embedded URL credentials; inspected remotes with userinfo are redacted before receipts are printed
 - `git inspect` is read-only and emits sanitized source descriptors plus accepted-revision hashes
+- `git materialize` accepts only `mdkg.git.materialize.request.v1` JSON, rejects unsafe input before Git, verifies a full ref and exact commit/tree, and atomically renames a same-parent temporary tree into a contained destination
+- materialization disables prompts, repository hooks, push, and recursive submodules; project-memory checks do not index or execute repository-controlled behavior
+- `deny|ignore` controls submodule acceptance and `required|optional|forbidden` controls project-memory presence
+- materialization receipts never retain credentials, environment values, helper output, socket paths, raw Git output, repository contents, or absolute local paths
 - `git clone` writes only to an empty or absent contained `--target`; use `mdkg graph clone|fork` for bundle/template graph transport
 - `git closeout` validates mdkg state and writes static JSON and Markdown receipts under `.mdkg/git/closeouts` by default
 - when the project DB participated, `git closeout` also seals `.mdkg/db/state/project.sqlite` and writes a deterministic dump
@@ -805,6 +824,7 @@ Notes:
 
 JSON receipts:
 - `inspect`: `{ action: "git.inspect", ok, root, inside_work_tree, branch, head_sha, tree_hash, remotes, status, source_descriptor, accepted_revision, warnings }`
+- `materialize`: `{ schema: "mdkg.git.materialize.receipt.v1", action: "git.materialize", ok, reason_code, request_hash, repository, source_ref, access_ref, correlation_ref, evidence_refs, target_ref, expected_revision, observed_revision, policies, destination, cleanup, warnings }`
 - `clone`: `{ action: "git.clone", ok, repository_ref, target, branch, source_descriptor, accepted_revision, inspect, warnings }`
 - `fetch`: `{ action: "git.fetch", ok, remote, branch, fetch_output, inspect, warnings }`
 - `closeout`: `{ action: "git.closeout", ok, root, output_dir, generated_at, git, validation, db_participated, db_snapshot_status, db_snapshot_seal, db_snapshot_dump, static_receipts, warnings }`

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.5.0`
+Current package version in source: `0.5.2`
 
 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.
 
@@ -242,11 +242,13 @@ Subgraph nodes are projected under the subgraph alias, for example `child_repo:t
 
 Use `mdkg graph refs <id-or-qid> --json` to inspect inbound and outbound scope, context, evidence, blocker, related, and structural links for local or read-only subgraph qids without mutating either graph.
 
-Use low-level Git lifecycle receipts when an agent run needs to close out local
-mdkg state and prove push readiness before an explicit remote update:
+Use low-level Git lifecycle receipts when an agent run needs to accept an exact
+source revision, close out local mdkg state, or prove push readiness before an
+explicit remote update:
 
 ```bash
 mdkg git inspect --json
+mdkg git materialize --request materialize-request.json --json
 mdkg git clone git@github.com:org/repo.git --target worktrees/repo --branch main --json
 mdkg git fetch --remote origin --branch main --json
 mdkg git closeout --json
@@ -257,7 +259,12 @@ mdkg git push --remote origin --branch main --stage-all --message "agent checkpo
 `mdkg git` uses the system Git CLI. Authentication stays external through SSH,
 credential helpers, `gh`, CI/runtime environment, or shell state; mdkg rejects
 embedded URL credentials and records only sanitized refs, hashes, policy names,
-and receipts. `closeout` validates mdkg state before writing static JSON and
+and receipts. `materialize` accepts only strict
+`mdkg.git.materialize.request.v1` JSON, verifies the full target ref and
+accepted revision, and publishes a contained destination only after all checks
+pass; see the [verified Git materialization
+guide](https://docs.mdkg.dev/advanced-alpha/git-materialization/). `closeout`
+validates mdkg state before writing static JSON and
 Markdown receipts, and when the project DB participated it also seals the
 SQLite state and writes a deterministic dump. Treat real `mdkg git push` as an
 approval-gated operation in agent runtimes.
@@ -653,6 +660,16 @@ When the source passed to `mdkg archive add` is inside the repo, `source_path` i
 
 Archive sidecar visibility defaults to `private`. Use `mdkg archive add --visibility public` only when the sidecar metadata and ZIP cache are safe for public packs or public bundles.
 
+Archive compression follows workspace ownership. `mdkg archive compress --all`
+compresses archives from enabled local workspaces and reports read-only imported
+archive projections as exclusions; it never treats bundle ZIP fragments as
+filesystem paths. Use `--all --ws <local-alias>` to limit bulk compression or a
+workspace-qualified qid such as `root:archive.example` for an exact local
+target. Direct imported qids and imported `--ws` aliases fail before writes with
+guidance to compress in the source workspace and refresh its subgraph bundle.
+The JSON receipt preserves `action`, `count`, and `archives` and adds the
+requested workspace, selected local workspaces, and excluded read-only qids.
+
 By default, init/upgrade ignore generated raw archive source copies with `.mdkg/archive/**/source/`; sidecar `.md` files and compressed `.zip` caches remain commit-eligible. `mdkg doctor` warns when a committed archive ZIP cache exceeds `archive.large_cache_warning_bytes` in `.mdkg/config.json` (default `26214400`; set `0` to disable). Large-cache warnings do not block archive add or validation.
 
 ## Current direction

package/dist/cli.js

@@ -30,6 +30,7 @@ const archive_1 = require("./commands/archive");
 const bundle_1 = require("./commands/bundle");
 const graph_1 = require("./commands/graph");
 const git_1 = require("./commands/git");
+const git_materialize_1 = require("./commands/git_materialize");
 const subgraph_1 = require("./commands/subgraph");
 const checkpoint_1 = require("./commands/checkpoint");
 const init_1 = require("./commands/init");
@@ -79,7 +80,7 @@ function printUsage(log) {
     log("  archive     Add, list, show, verify, and compress archive sidecars");
     log("  bundle      Create, list, show, and verify full graph snapshot bundles");
     log("  graph       Clone, fork, import, and inspect mdkg graph references");
-    log("  git         Clone, fetch, inspect, close out, and push Git-backed mdkg projects");
+    log("  git         Materialize, clone, fetch, inspect, close out, and push Git-backed projects");
     log("  subgraph    Register, audit, plan, sync, materialize, and verify read-only child graph snapshots");
     log("  work        Create and update work contracts, orders, receipts, and artifacts");
     log("  loop        List, show, fork, plan, and inspect first-class loop nodes");
@@ -583,8 +584,13 @@ function printArchiveHelp(log, subcommand) {
             break;
         case "compress":
             log("Usage:");
-            log("  mdkg archive compress <id-or-archive-uri> [--ws <alias>] [--json]");
-            log("  mdkg archive compress --all [--json]");
+            log("  mdkg archive compress <id-or-archive-uri-or-qid> [--ws <local-alias>] [--json]");
+            log("  mdkg archive compress --all [--ws <local-alias>] [--json]");
+            log("\nNotes:");
+            log("  - compression mutates archives owned by enabled local workspaces only");
+            log("  - --all excludes read-only imported archive projections and reports them in the receipt");
+            log("  - direct imported qids and --ws <imported-alias> fail with source-workspace guidance");
+            log("  - all selected archives pass ownership and path preflight before the first write");
             break;
         default:
             log("Usage:");
@@ -592,7 +598,7 @@ function printArchiveHelp(log, subcommand) {
             log("  mdkg archive list [--kind source|artifact] [--visibility private|internal|public] [--json]");
             log("  mdkg archive show <id-or-archive-uri> [--json]");
             log("  mdkg archive verify [id-or-archive-uri] [--json]");
-            log("  mdkg archive compress <id-or-archive-uri|--all> [--json]");
+            log("  mdkg archive compress <id-or-archive-uri-or-qid|--all> [--ws <local-alias>] [--json]");
             log("\nNotes:");
             log("  - archive add copies the source, writes a sidecar, and writes a deterministic zip cache");
             log("  - archive visibility defaults to private");
@@ -704,6 +710,14 @@ function printGitHelp(log, subcommand) {
             log("  - --target must be empty or absent and stay inside the current repo");
             log("  - repository refs must not embed credentials");
             break;
+        case "materialize":
+            log("Usage:");
+            log("  mdkg git materialize --request <file|-> [--json]");
+            log("\nNotes:");
+            log("  - accepts only schema mdkg.git.materialize.request.v1 JSON");
+            log("  - verifies the full target ref, expected commit, optional tree, and policy checks before publishing");
+            log("  - uses external auth and an atomic contained destination; receipts never include credentials or raw Git output");
+            break;
         case "fetch":
             log("Usage:");
             log("  mdkg git fetch [--remote <name>] [--branch <name>] [--json]");
@@ -738,6 +752,7 @@ function printGitHelp(log, subcommand) {
         default:
             log("Usage:");
             log("  mdkg git inspect [--json]");
+            log("  mdkg git materialize --request <file|-> [--json]");
             log("  mdkg git clone <repository-ref> --target <path> [--branch <name>] [--json]");
             log("  mdkg git fetch [--remote <name>] [--branch <name>] [--json]");
             log("  mdkg git closeout [--queue-policy drain|paused] [--output <path>] [--json]");
@@ -2026,6 +2041,8 @@ function runGitSubcommand(parsed, root) {
             (0, git_1.runGitInspectCommand)({ root, json });
             return 0;
         }
+        case "materialize":
+            throw new errors_1.UsageError("git materialize requires the asynchronous CLI entrypoint");
         case "clone": {
             const repository = parsed.positionals[2];
             if (!repository || parsed.positionals.length > 3) {
@@ -2079,7 +2096,44 @@ function runGitSubcommand(parsed, root) {
             return 0;
         }
         default:
-            throw new errors_1.UsageError("git requires inspect/clone/fetch/closeout/push-ready/push");
+            throw new errors_1.UsageError("git requires inspect/materialize/clone/fetch/closeout/push-ready/push");
+    }
+}
+function printGitMaterializeReceipt(receipt, json, runtime) {
+    if (json) {
+        runtime.log(JSON.stringify(receipt, null, 2));
+        return;
+    }
+    if (receipt.ok) {
+        runtime.log("git materialize accepted");
+        runtime.log(`destination: ${receipt.destination.path ?? "(none)"}`);
+        runtime.log(`commit: ${receipt.observed_revision.commit ?? "(none)"}`);
+        runtime.log(`tree: ${receipt.observed_revision.tree ?? "(none)"}`);
+        return;
+    }
+    runtime.error(`git materialize failed: ${receipt.reason_code}`);
+    runtime.error(`destination: ${receipt.destination.state}`);
+    runtime.error(`cleanup: ${receipt.cleanup.state}`);
+}
+async function runGitMaterializeSubcommand(parsed, root, runtime) {
+    if (parsed.positionals.length > 2) {
+        throw new errors_1.UsageError("git materialize does not accept positional arguments");
+    }
+    const request = requireFlagValue("--request", parsed.flags["--request"]);
+    if (!request)
+        throw new errors_1.UsageError("git materialize requires --request <file|->");
+    const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+    try {
+        const receipt = await (0, git_materialize_1.collectGitMaterializeReceipt)({ root, request });
+        printGitMaterializeReceipt(receipt, json, runtime);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof git_materialize_1.GitMaterializeError) {
+            printGitMaterializeReceipt(error.receipt, json, runtime);
+            return 2;
+        }
+        throw error;
     }
 }
 function runSubgraphSubcommand(parsed, root) {
@@ -3407,6 +3461,9 @@ async function runCliAsync(argv, runtime = {}) {
         if (command === "mcp") {
             return await runMcpSubcommand(parsed, root);
         }
+        if (command === "git" && (parsed.positionals[1] ?? "").toLowerCase() === "materialize") {
+            return await runGitMaterializeSubcommand(parsed, root, io);
+        }
         return runCommand(parsed, root, io);
     }
     catch (err) {