mdkg 0.1.10 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,32 @@ 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.2.0 - Unreleased
+
+Release numbering note: future project DB materializer/profile release planning
+should follow `0.1.9 -> 0.2.0` rather than continuing the line as `0.1.10`
+when the release represents a capability-track boundary.
+
+### Added
+
+- Added public `mdkg db queue ...` commands for local project DB queue
+  create/pause/resume/enqueue/claim/ack/fail/dead-letter/release-expired/stats/list/show.
+- Added `mdkg.project_db.queue_control.v1` / `005_mdkg_project_db_queue_control.sql`
+  for first-class queue active/paused state and migration backfill from existing
+  queue messages.
+- Added queue-aware snapshot sealing policies: default `--queue-policy drain`
+  blocks ready/leased messages, while `--queue-policy paused` allows ready
+  messages only in paused queues and always blocks leased messages.
+- Added packed CLI-only `smoke:db-queue-cli` coverage that exercises public
+  queue commands and pause/drain snapshot behavior from an installed tarball.
+
+### Changed
+
+- Source release line now targets `0.2.0` for the next project DB
+  materializer/profile capability track.
+- Project DB queue support is now public under `mdkg db queue`; event, reducer,
+  writer lease, and materializer command surfaces remain internal-only.
+
 ## 0.1.10 - 2026-06-05
 
 ### 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.10`
+Current package version in source: `0.2.0`
 
 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.
 
@@ -349,16 +349,16 @@ 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`; built-in migrations write
-mdkg-owned generic foundation tables, then the internal local node:sqlite queue
-foundation, then internal local event/receipt/reducer and writer lease/CAS
-foundations, and record migration order, checksums, and applied timestamps.
-Queue state is durable local delivery infrastructure, not canonical event
-history. Event rows are the durable local history for project DB state
-transitions, receipts provide audit/review artifacts, reducers gate writes,
-writer leases coordinate snapshot-hash compare-and-swap commits, and
-materializers run local queue-backed reducer passes. These capabilities are
-available only through internal helper modules in this release; there is no
-public `mdkg db queue`, `mdkg db event`, `mdkg db reducer`, `mdkg db lease`, or
+mdkg-owned generic foundation tables, public local node:sqlite queue delivery
+tables, internal local event/receipt/reducer tables, writer lease/CAS tables,
+and queue control state, then record migration order, checksums, and applied
+timestamps. Queue state is durable local delivery infrastructure, not canonical
+event history. Use `mdkg db queue create|pause|resume|enqueue|claim|ack|fail|dead-letter|release-expired|stats|list|show`
+to operate local project queues. Paused queues reject enqueue/claim while still
+allowing ack/fail/dead-letter/release-expired so leased work can settle. Event
+rows are durable local project DB history; receipts, reducers, writer leases,
+and materializers remain internal helper surfaces in this release, with no
+public `mdkg db event`, `mdkg db reducer`, `mdkg db lease`, or
 `mdkg db materializer` CLI yet.
 Use `mdkg db verify` for non-mutating health checks over config, layout,
 runtime SQLite integrity, migration metadata, and transient runtime files. Use
@@ -366,6 +366,9 @@ runtime SQLite integrity, migration metadata, and transient runtime files. Use
 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`.
+The default queue policy is `--queue-policy drain`, which requires no ready or
+leased queue messages. Use `--queue-policy paused` only when ready messages are
+intentionally preserved in paused queues; leased messages always block sealing.
 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

package/dist/cli.js

@@ -194,18 +194,41 @@ function printDbHelp(log, subcommand) {
             return;
         case "snapshot":
             log("Usage:");
-            log("  mdkg db snapshot seal [--json]");
+            log("  mdkg db snapshot seal [--queue-policy drain|paused] [--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("  - default queue policy is drain: no ready or leased queue messages");
+            log("  - paused queue policy allows ready messages only in paused queues and never leased messages");
             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;
+        case "queue":
+            log("Usage:");
+            log("  mdkg db queue create <queue> [--paused] [--reason <text>] [--json]");
+            log("  mdkg db queue pause <queue> [--reason <text>] [--json]");
+            log("  mdkg db queue resume <queue> [--json]");
+            log("  mdkg db queue enqueue <queue> <message-id> --payload-json <json>|--payload-file <path> [--dedupe-key <key>] [--available-at-ms <ms>] [--max-attempts <n>] [--json]");
+            log("  mdkg db queue claim <queue> --lease-owner <owner> --lease-ms <ms> [--json]");
+            log("  mdkg db queue ack <queue> <message-id> --lease-owner <owner> [--json]");
+            log("  mdkg db queue fail <queue> <message-id> --lease-owner <owner> --error <text> [--retry-after-ms <ms>] [--json]");
+            log("  mdkg db queue dead-letter <queue> <message-id> --lease-owner <owner> --error <text> [--json]");
+            log("  mdkg db queue release-expired [queue] [--json]");
+            log("  mdkg db queue stats [queue] [--json]");
+            log("  mdkg db queue list <queue> [--status ready|leased|acked|dead_letter|all] [--limit <n>] [--json]");
+            log("  mdkg db queue show <queue> <message-id> [--json]");
+            log("\nSemantics:");
+            log("  - queues are durable local delivery state, not canonical event history");
+            log("  - paused queues reject enqueue and claim");
+            log("  - ack, fail, dead-letter, and release-expired are allowed while paused so leased work can settle");
+            log("  - no raw SQL or hosted queue dependency is exposed");
+            printGlobalOptions(log);
+            return;
         default:
             log("Usage:");
             log("  mdkg db index rebuild [--tolerant] [--json]");
@@ -215,7 +238,13 @@ function printDbHelp(log, subcommand) {
             log("  mdkg db migrate [--json]");
             log("  mdkg db verify [--json]");
             log("  mdkg db stats [--json]");
-            log("  mdkg db snapshot seal [--json]");
+            log("  mdkg db queue create <queue> [--paused] [--reason <text>] [--json]");
+            log("  mdkg db queue enqueue <queue> <message-id> --payload-json <json>|--payload-file <path> [--json]");
+            log("  mdkg db queue claim <queue> --lease-owner <owner> --lease-ms <ms> [--json]");
+            log("  mdkg db queue ack|fail|dead-letter <queue> <message-id> --lease-owner <owner> [--json]");
+            log("  mdkg db queue pause|resume <queue> [--json]");
+            log("  mdkg db queue stats|list|show ... [--json]");
+            log("  mdkg db snapshot seal [--queue-policy drain|paused] [--json]");
             log("  mdkg db snapshot verify [--json]");
             log("  mdkg db snapshot status [--json]");
             log("  mdkg db snapshot dump [--snapshot <path>] [--output <path>] [--json]");
@@ -227,14 +256,15 @@ function printDbHelp(log, subcommand) {
             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 foundation plus internal queue, event, receipt, reducer, and lease migrations");
-            log("  - queue tables are internal local delivery state; no public `mdkg db queue` CLI is exposed");
+            log("  - `mdkg db queue ...` exposes local durable queue delivery operations");
+            log("  - paused queues reject enqueue/claim and can be sealed with explicit paused snapshot policy");
             log("  - event rows are durable local history; receipts, reducers, and writer leases remain internal helper surfaces");
             log("  - no public `mdkg db event`, `mdkg db reducer`, or `mdkg db lease` CLI is exposed");
             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/event store, profile, public queue/event/reducer/lease command, or publish behavior is exposed here");
+            log("  - no raw SQL, hosted queue/event store, profile, public event/reducer/lease command, or publish behavior is exposed here");
             printGlobalOptions(log);
     }
 }
@@ -922,6 +952,16 @@ function parseNumberFlag(flag, value) {
     }
     return parsed;
 }
+function parseQueuePolicyFlag(value) {
+    const raw = requireFlagValue("--queue-policy", value);
+    if (raw === undefined) {
+        return undefined;
+    }
+    if (raw === "drain" || raw === "paused") {
+        return raw;
+    }
+    throw new errors_1.UsageError("--queue-policy must be drain or paused");
+}
 function parseEdgesFlag(value) {
     if (value === undefined) {
         return undefined;
@@ -1109,6 +1149,107 @@ function runDbSubcommand(parsed, root) {
             (0, db_1.runDbStatsCommand)({ root, json: parseBooleanFlag("--json", parsed.flags["--json"]) });
             return 0;
         }
+        case "queue": {
+            const action = (parsed.positionals[2] ?? "").toLowerCase();
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            const queueName = parsed.positionals[3];
+            const messageId = parsed.positionals[4];
+            const common = {
+                root,
+                json,
+                queueName,
+                messageId,
+                leaseOwner: requireFlagValue("--lease-owner", parsed.flags["--lease-owner"]),
+                leaseMs: parseNumberFlag("--lease-ms", parsed.flags["--lease-ms"]),
+                payloadJson: requireFlagValue("--payload-json", parsed.flags["--payload-json"]),
+                payloadFile: requireFlagValue("--payload-file", parsed.flags["--payload-file"]),
+                dedupeKey: requireFlagValue("--dedupe-key", parsed.flags["--dedupe-key"]),
+                availableAtMs: parseNumberFlag("--available-at-ms", parsed.flags["--available-at-ms"]),
+                maxAttempts: parseNumberFlag("--max-attempts", parsed.flags["--max-attempts"]),
+                retryAfterMs: parseNumberFlag("--retry-after-ms", parsed.flags["--retry-after-ms"]),
+                error: requireFlagValue("--error", parsed.flags["--error"]),
+                paused: parseBooleanFlag("--paused", parsed.flags["--paused"]),
+                reason: requireFlagValue("--reason", parsed.flags["--reason"]),
+                status: requireFlagValue("--status", parsed.flags["--status"]),
+                limit: parseNumberFlag("--limit", parsed.flags["--limit"]),
+            };
+            switch (action) {
+                case "create":
+                    if (!queueName || parsed.positionals.length > 4) {
+                        throw new errors_1.UsageError("mdkg db queue create requires <queue>");
+                    }
+                    (0, db_1.runDbQueueCreateCommand)(common);
+                    return 0;
+                case "pause":
+                    if (!queueName || parsed.positionals.length > 4) {
+                        throw new errors_1.UsageError("mdkg db queue pause requires <queue>");
+                    }
+                    (0, db_1.runDbQueuePauseCommand)(common);
+                    return 0;
+                case "resume":
+                    if (!queueName || parsed.positionals.length > 4) {
+                        throw new errors_1.UsageError("mdkg db queue resume requires <queue>");
+                    }
+                    (0, db_1.runDbQueueResumeCommand)(common);
+                    return 0;
+                case "enqueue":
+                    if (!queueName || !messageId || parsed.positionals.length > 5) {
+                        throw new errors_1.UsageError("mdkg db queue enqueue requires <queue> <message-id>");
+                    }
+                    (0, db_1.runDbQueueEnqueueCommand)(common);
+                    return 0;
+                case "claim":
+                    if (!queueName || parsed.positionals.length > 4) {
+                        throw new errors_1.UsageError("mdkg db queue claim requires <queue>");
+                    }
+                    (0, db_1.runDbQueueClaimCommand)(common);
+                    return 0;
+                case "ack":
+                    if (!queueName || !messageId || parsed.positionals.length > 5) {
+                        throw new errors_1.UsageError("mdkg db queue ack requires <queue> <message-id>");
+                    }
+                    (0, db_1.runDbQueueAckCommand)(common);
+                    return 0;
+                case "fail":
+                    if (!queueName || !messageId || parsed.positionals.length > 5) {
+                        throw new errors_1.UsageError("mdkg db queue fail requires <queue> <message-id>");
+                    }
+                    (0, db_1.runDbQueueFailCommand)(common);
+                    return 0;
+                case "dead-letter":
+                    if (!queueName || !messageId || parsed.positionals.length > 5) {
+                        throw new errors_1.UsageError("mdkg db queue dead-letter requires <queue> <message-id>");
+                    }
+                    (0, db_1.runDbQueueDeadLetterCommand)(common);
+                    return 0;
+                case "release-expired":
+                    if (parsed.positionals.length > 4) {
+                        throw new errors_1.UsageError("mdkg db queue release-expired accepts at most one queue");
+                    }
+                    (0, db_1.runDbQueueReleaseExpiredCommand)(common);
+                    return 0;
+                case "stats":
+                    if (parsed.positionals.length > 4) {
+                        throw new errors_1.UsageError("mdkg db queue stats accepts at most one queue");
+                    }
+                    (0, db_1.runDbQueueStatsCommand)(common);
+                    return 0;
+                case "list":
+                    if (!queueName || parsed.positionals.length > 4) {
+                        throw new errors_1.UsageError("mdkg db queue list requires <queue>");
+                    }
+                    (0, db_1.runDbQueueListCommand)(common);
+                    return 0;
+                case "show":
+                    if (!queueName || !messageId || parsed.positionals.length > 5) {
+                        throw new errors_1.UsageError("mdkg db queue show requires <queue> <message-id>");
+                    }
+                    (0, db_1.runDbQueueShowCommand)(common);
+                    return 0;
+                default:
+                    throw new errors_1.UsageError("mdkg db queue requires create/pause/resume/enqueue/claim/ack/fail/dead-letter/release-expired/stats/list/show");
+            }
+        }
         case "snapshot": {
             const action = (parsed.positionals[2] ?? "").toLowerCase();
             const json = parseBooleanFlag("--json", parsed.flags["--json"]);
@@ -1117,7 +1258,7 @@ function runDbSubcommand(parsed, root) {
                     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 });
+                    (0, db_1.runDbSnapshotSealCommand)({ root, json, queuePolicy: parseQueuePolicyFlag(parsed.flags["--queue-policy"]) });
                     return 0;
                 case "verify":
                     if (parsed.positionals.length > 3) {
@@ -1154,7 +1295,7 @@ function runDbSubcommand(parsed, root) {
             }
         }
         default:
-            throw new errors_1.UsageError("mdkg db requires index/init/migrate/verify/stats/snapshot");
+            throw new errors_1.UsageError("mdkg db requires index/init/migrate/verify/stats/queue/snapshot");
     }
 }
 function runCapabilitySubcommand(parsed, root) {

package/dist/commands/db.js

@@ -8,6 +8,18 @@ exports.runDbInitCommand = runDbInitCommand;
 exports.runDbMigrateCommand = runDbMigrateCommand;
 exports.runDbVerifyCommand = runDbVerifyCommand;
 exports.runDbStatsCommand = runDbStatsCommand;
+exports.runDbQueueCreateCommand = runDbQueueCreateCommand;
+exports.runDbQueuePauseCommand = runDbQueuePauseCommand;
+exports.runDbQueueResumeCommand = runDbQueueResumeCommand;
+exports.runDbQueueEnqueueCommand = runDbQueueEnqueueCommand;
+exports.runDbQueueClaimCommand = runDbQueueClaimCommand;
+exports.runDbQueueAckCommand = runDbQueueAckCommand;
+exports.runDbQueueFailCommand = runDbQueueFailCommand;
+exports.runDbQueueDeadLetterCommand = runDbQueueDeadLetterCommand;
+exports.runDbQueueReleaseExpiredCommand = runDbQueueReleaseExpiredCommand;
+exports.runDbQueueStatsCommand = runDbQueueStatsCommand;
+exports.runDbQueueListCommand = runDbQueueListCommand;
+exports.runDbQueueShowCommand = runDbQueueShowCommand;
 exports.runDbSnapshotSealCommand = runDbSnapshotSealCommand;
 exports.runDbSnapshotVerifyCommand = runDbSnapshotVerifyCommand;
 exports.runDbSnapshotStatusCommand = runDbSnapshotStatusCommand;
@@ -23,6 +35,7 @@ const paths_1 = require("../core/paths");
 const project_db_1 = require("../core/project_db");
 const project_db_migrations_1 = require("../core/project_db_migrations");
 const project_db_snapshot_1 = require("../core/project_db_snapshot");
+const project_db_queue_1 = require("../core/project_db_queue");
 const version_1 = require("../core/version");
 const index_1 = require("./index");
 const capabilities_indexer_1 = require("../graph/capabilities_indexer");
@@ -449,6 +462,177 @@ function runDbStatsCommand(options) {
         }
     }
 }
+function requireQueueName(options) {
+    if (!options.queueName) {
+        throw new errors_1.UsageError("queue name is required");
+    }
+    return options.queueName;
+}
+function requireMessageId(options) {
+    if (!options.messageId) {
+        throw new errors_1.UsageError("message id is required");
+    }
+    return options.messageId;
+}
+function requireLeaseOwner(options) {
+    if (!options.leaseOwner) {
+        throw new errors_1.UsageError("--lease-owner is required");
+    }
+    return options.leaseOwner;
+}
+function requireLeaseMs(options) {
+    if (options.leaseMs === undefined) {
+        throw new errors_1.UsageError("--lease-ms is required");
+    }
+    return options.leaseMs;
+}
+function loadQueueDatabasePath(root) {
+    const config = (0, config_1.loadConfig)(root);
+    const verification = (0, project_db_migrations_1.verifyProjectDb)(root, config);
+    if (!verification.ok) {
+        throw new errors_1.ValidationError(`db queue requires a valid project DB; run mdkg db verify`);
+    }
+    return (0, project_db_1.resolveConfiguredProjectDbLayout)(root, config.db).runtimeFile;
+}
+function parseQueuePayload(options) {
+    const hasPayloadJson = options.payloadJson !== undefined;
+    const hasPayloadFile = options.payloadFile !== undefined;
+    if (hasPayloadJson === hasPayloadFile) {
+        throw new errors_1.UsageError("mdkg db queue enqueue requires exactly one of --payload-json or --payload-file");
+    }
+    const raw = hasPayloadJson
+        ? options.payloadJson
+        : fs_1.default.readFileSync(path_1.default.resolve(options.root, String(options.payloadFile)), "utf8");
+    try {
+        return JSON.parse(String(raw));
+    }
+    catch (err) {
+        throw new errors_1.UsageError(`queue payload must be valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function writeQueueJsonOrText(action, payload, json) {
+    if (json) {
+        console.log(JSON.stringify({ action, ok: true, ...payload }, null, 2));
+        return;
+    }
+    console.log(action);
+    for (const [key, value] of Object.entries(payload)) {
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === null) {
+            console.log(`${key}: ${value}`);
+        }
+        else {
+            console.log(`${key}: ${JSON.stringify(value)}`);
+        }
+    }
+}
+function runQueueMutation(options, fn, action) {
+    const config = (0, config_1.loadConfig)(options.root);
+    (0, lock_1.withMutationLock)(options.root, config.index.lock_timeout_ms, () => {
+        const databasePath = loadQueueDatabasePath(options.root);
+        writeQueueJsonOrText(action, fn(databasePath), options.json);
+    });
+}
+function runDbQueueCreateCommand(options) {
+    runQueueMutation(options, (databasePath) => (0, project_db_queue_1.createProjectQueue)(databasePath, {
+        queue_name: requireQueueName(options),
+        paused: options.paused,
+        reason: options.reason,
+    }), "db-queue-create");
+}
+function runDbQueuePauseCommand(options) {
+    runQueueMutation(options, (databasePath) => ({ queue: (0, project_db_queue_1.pauseProjectQueue)(databasePath, { queue_name: requireQueueName(options), reason: options.reason }) }), "db-queue-pause");
+}
+function runDbQueueResumeCommand(options) {
+    runQueueMutation(options, (databasePath) => ({ queue: (0, project_db_queue_1.resumeProjectQueue)(databasePath, { queue_name: requireQueueName(options) }) }), "db-queue-resume");
+}
+function runDbQueueEnqueueCommand(options) {
+    runQueueMutation(options, (databasePath) => (0, project_db_queue_1.enqueueProjectQueueMessage)(databasePath, {
+        queue_name: requireQueueName(options),
+        message_id: requireMessageId(options),
+        dedupe_key: options.dedupeKey,
+        payload: parseQueuePayload(options),
+        available_at_ms: options.availableAtMs,
+        max_attempts: options.maxAttempts,
+    }), "db-queue-enqueue");
+}
+function runDbQueueClaimCommand(options) {
+    runQueueMutation(options, (databasePath) => ({
+        message: (0, project_db_queue_1.claimProjectQueueMessage)(databasePath, {
+            queue_name: requireQueueName(options),
+            lease_owner: requireLeaseOwner(options),
+            lease_ms: requireLeaseMs(options),
+        }),
+    }), "db-queue-claim");
+}
+function runDbQueueAckCommand(options) {
+    runQueueMutation(options, (databasePath) => ({
+        message: (0, project_db_queue_1.ackProjectQueueMessage)(databasePath, {
+            queue_name: requireQueueName(options),
+            message_id: requireMessageId(options),
+            lease_owner: requireLeaseOwner(options),
+        }),
+    }), "db-queue-ack");
+}
+function runDbQueueFailCommand(options) {
+    if (!options.error) {
+        throw new errors_1.UsageError("--error is required");
+    }
+    runQueueMutation(options, (databasePath) => ({
+        message: (0, project_db_queue_1.failProjectQueueMessage)(databasePath, {
+            queue_name: requireQueueName(options),
+            message_id: requireMessageId(options),
+            lease_owner: requireLeaseOwner(options),
+            error: String(options.error),
+            retry_after_ms: options.retryAfterMs,
+        }),
+    }), "db-queue-fail");
+}
+function runDbQueueDeadLetterCommand(options) {
+    if (!options.error) {
+        throw new errors_1.UsageError("--error is required");
+    }
+    runQueueMutation(options, (databasePath) => ({
+        message: (0, project_db_queue_1.deadLetterProjectQueueMessage)(databasePath, {
+            queue_name: requireQueueName(options),
+            message_id: requireMessageId(options),
+            lease_owner: requireLeaseOwner(options),
+            error: String(options.error),
+        }),
+    }), "db-queue-dead-letter");
+}
+function runDbQueueReleaseExpiredCommand(options) {
+    runQueueMutation(options, (databasePath) => (0, project_db_queue_1.releaseExpiredProjectQueueLeases)(databasePath, { queue_name: options.queueName }), "db-queue-release-expired");
+}
+function runDbQueueStatsCommand(options) {
+    const databasePath = loadQueueDatabasePath(options.root);
+    const stats = (0, project_db_queue_1.readProjectQueueStats)(databasePath, { queue_name: options.queueName });
+    const queue = options.queueName ? (0, project_db_queue_1.readProjectQueue)(databasePath, options.queueName) : null;
+    writeQueueJsonOrText("db-queue-stats", {
+        queue,
+        stats,
+        queues: options.queueName ? undefined : (0, project_db_queue_1.listProjectQueues)(databasePath),
+        snapshot_summary: (0, project_db_queue_1.readProjectQueueSnapshotSummary)(databasePath),
+    }, options.json);
+}
+function runDbQueueListCommand(options) {
+    const databasePath = loadQueueDatabasePath(options.root);
+    const messages = (0, project_db_queue_1.listProjectQueueMessages)(databasePath, {
+        queue_name: requireQueueName(options),
+        status: (options.status ?? "all"),
+        limit: options.limit,
+    });
+    writeQueueJsonOrText("db-queue-list", { queue_name: requireQueueName(options), count: messages.length, messages }, options.json);
+}
+function runDbQueueShowCommand(options) {
+    const databasePath = loadQueueDatabasePath(options.root);
+    const queueName = requireQueueName(options);
+    const messageId = requireMessageId(options);
+    const message = (0, project_db_queue_1.readProjectQueueMessage)(databasePath, queueName, messageId);
+    if (!message) {
+        throw new errors_1.NotFoundError(`queue message not found: ${queueName}/${messageId}`);
+    }
+    writeQueueJsonOrText("db-queue-show", { message }, options.json);
+}
 function printSnapshotChecks(payload) {
     for (const check of payload.checks) {
         const location = check.path ? ` (${path_1.default.isAbsolute(check.path) ? rel(process.cwd(), check.path) : check.path})` : "";
@@ -457,7 +641,7 @@ function printSnapshotChecks(payload) {
 }
 function runDbSnapshotSealCommandLocked(options) {
     const config = (0, config_1.loadConfig)(options.root);
-    const payload = (0, project_db_snapshot_1.sealProjectDbSnapshot)(options.root, config);
+    const payload = (0, project_db_snapshot_1.sealProjectDbSnapshot)(options.root, config, options.queuePolicy ?? "drain");
     if (options.json) {
         console.log(JSON.stringify(payload, null, 2));
         return;

package/dist/core/project_db_migrations.js

@@ -53,6 +53,24 @@ ON project_queue_message(queue_name, status, available_at_ms, created_at_ms, mes
 CREATE INDEX IF NOT EXISTS project_queue_message_lease_idx
 ON project_queue_message(queue_name, status, lease_deadline_ms, created_at_ms, message_id);
 `;
+const QUEUE_CONTROL_MIGRATION_SQL = `
+CREATE TABLE IF NOT EXISTS project_queue (
+  queue_name TEXT PRIMARY KEY,
+  status TEXT NOT NULL CHECK(status IN ('active', 'paused')),
+  paused_reason TEXT,
+  created_at_ms INTEGER NOT NULL,
+  updated_at_ms INTEGER NOT NULL
+) STRICT;
+
+INSERT OR IGNORE INTO project_queue (queue_name, status, paused_reason, created_at_ms, updated_at_ms)
+SELECT DISTINCT
+  queue_name,
+  'active',
+  NULL,
+  CAST((julianday('now') - 2440587.5) * 86400000 AS INTEGER),
+  CAST((julianday('now') - 2440587.5) * 86400000 AS INTEGER)
+FROM project_queue_message;
+`;
 const EVENTS_RECEIPTS_MIGRATION_SQL = `
 CREATE TABLE IF NOT EXISTS project_event (
   event_id TEXT PRIMARY KEY,
@@ -162,6 +180,12 @@ const BUILTIN_MIGRATIONS = [
         filename: "004_mdkg_project_db_writer_leases.sql",
         sql: WRITER_LEASES_MIGRATION_SQL.trim(),
     },
+    {
+        ordinal: 5,
+        key: "mdkg.project_db.queue_control.v1",
+        filename: "005_mdkg_project_db_queue_control.sql",
+        sql: QUEUE_CONTROL_MIGRATION_SQL.trim(),
+    },
 ];
 function loadDatabaseCtor() {
     try {