mdkg 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -6,6 +6,23 @@ 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.9 - Unreleased
+
+### Added
+
+- Added internal local project DB event, receipt, typed reducer, and writer
+  lease/CAS foundations after the queue migration.
+- Added packed `smoke:db-events` coverage for event idempotency, conflict
+  receipts, reducer application/replay, writer lease CAS conflicts, snapshots,
+  stats, index, and validate.
+
+### Changed
+
+- Project DB migration order now includes events/receipts and writer leases
+  after the `0.1.8` queue foundation.
+- Publish readiness now requires the compiled event helper and seeded docs that
+  keep event/reducer/lease support internal-only.
+
 ## 0.1.8 - 2026-06-04
 
 ### 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.8`
+Current package version in source: `0.1.9`
 
 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.
 
@@ -350,10 +350,15 @@ 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, and record migration order, checksums, and applied timestamps.
+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. It is available only through internal helper modules in this release;
-there is no public `mdkg db queue` CLI yet.
+history. Event rows are the durable local history for project DB state
+transitions, receipts provide audit/review artifacts, reducers gate writes, and
+writer leases coordinate snapshot-hash compare-and-swap commits. 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`, or
+`mdkg db lease` CLI yet.
 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,

package/dist/cli.js

@@ -226,13 +226,15 @@ function printDbHelp(log, subcommand) {
             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 foundation and internal queue migrations");
+            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("  - 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, profile, public queue command, or publish behavior is exposed here");
+            log("  - no raw SQL, hosted queue/event store, profile, public queue/event/reducer/lease command, or publish behavior is exposed here");
             printGlobalOptions(log);
     }
 }

package/dist/core/project_db_events.js

@@ -0,0 +1,599 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeProjectDbReceipt = writeProjectDbReceipt;
+exports.recordProjectDbEvent = recordProjectDbEvent;
+exports.applyProjectDbReducer = applyProjectDbReducer;
+exports.replayProjectDbEvents = replayProjectDbEvents;
+exports.acquireProjectWriterLease = acquireProjectWriterLease;
+exports.commitProjectWriterLease = commitProjectWriterLease;
+exports.releaseProjectWriterLease = releaseProjectWriterLease;
+exports.releaseExpiredProjectWriterLeases = releaseExpiredProjectWriterLeases;
+exports.readProjectWriterLeaseStats = readProjectWriterLeaseStats;
+const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function loadDatabaseCtor() {
+    try {
+        const loaded = require("node:sqlite");
+        if (!loaded.DatabaseSync) {
+            throw new Error("node:sqlite DatabaseSync is unavailable");
+        }
+        return loaded.DatabaseSync;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`node:sqlite is required for mdkg project DB events: ${message}`);
+    }
+}
+function nowMs(input) {
+    if (input !== undefined) {
+        assertInteger(input, "now_ms");
+        return input;
+    }
+    return Date.now();
+}
+function assertNonEmpty(value, field) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`${field} must be a non-empty string`);
+    }
+}
+function assertInteger(value, field) {
+    if (!Number.isInteger(value)) {
+        throw new Error(`${field} must be an integer`);
+    }
+}
+function assertPositiveInteger(value, field) {
+    assertInteger(value, field);
+    if (value <= 0) {
+        throw new Error(`${field} must be greater than 0`);
+    }
+}
+function stableJson(value) {
+    if (value === undefined || typeof value === "function" || typeof value === "symbol" || typeof value === "bigint") {
+        throw new Error("value must be JSON-serializable");
+    }
+    if (value === null || typeof value !== "object") {
+        if (typeof value === "number" && !Number.isFinite(value)) {
+            throw new Error("value must be JSON-serializable");
+        }
+        const encoded = JSON.stringify(value);
+        if (encoded === undefined) {
+            throw new Error("value must be JSON-serializable");
+        }
+        return encoded;
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableJson(item)).join(",")}]`;
+    }
+    const object = value;
+    return `{${Object.keys(object)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableJson(object[key])}`)
+        .join(",")}}`;
+}
+function hashJson(payloadJson) {
+    return `sha256:${crypto_1.default.createHash("sha256").update(payloadJson).digest("hex")}`;
+}
+function safeSegment(value) {
+    return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "receipt";
+}
+function toMessage(row) {
+    return row ?? null;
+}
+function toEvent(row) {
+    return {
+        event_id: String(row.event_id),
+        project_id: String(row.project_id),
+        branch_id: String(row.branch_id),
+        event_type: String(row.event_type),
+        schema_version: Number(row.schema_version),
+        idempotency_key: String(row.idempotency_key),
+        payload_json: String(row.payload_json),
+        payload_hash: String(row.payload_hash),
+        actor: String(row.actor),
+        status: String(row.status),
+        occurred_at_ms: Number(row.occurred_at_ms),
+        created_at_ms: Number(row.created_at_ms),
+        updated_at_ms: Number(row.updated_at_ms),
+        last_error: row.last_error === null || row.last_error === undefined ? null : String(row.last_error),
+    };
+}
+function toReceipt(row) {
+    return {
+        receipt_id: String(row.receipt_id),
+        project_id: String(row.project_id),
+        branch_id: String(row.branch_id),
+        kind: String(row.kind),
+        status: String(row.status),
+        event_id: row.event_id === null || row.event_id === undefined ? null : String(row.event_id),
+        idempotency_key: row.idempotency_key === null || row.idempotency_key === undefined ? null : String(row.idempotency_key),
+        payload_hash: row.payload_hash === null || row.payload_hash === undefined ? null : String(row.payload_hash),
+        base_snapshot_hash: row.base_snapshot_hash === null || row.base_snapshot_hash === undefined ? null : String(row.base_snapshot_hash),
+        result_snapshot_hash: row.result_snapshot_hash === null || row.result_snapshot_hash === undefined ? null : String(row.result_snapshot_hash),
+        reducer_name: row.reducer_name === null || row.reducer_name === undefined ? null : String(row.reducer_name),
+        reducer_version: row.reducer_version === null || row.reducer_version === undefined ? null : String(row.reducer_version),
+        lease_id: row.lease_id === null || row.lease_id === undefined ? null : String(row.lease_id),
+        actor: row.actor === null || row.actor === undefined ? null : String(row.actor),
+        artifact_path: String(row.artifact_path),
+        artifact_hash: String(row.artifact_hash),
+        details_json: String(row.details_json),
+        created_at_ms: Number(row.created_at_ms),
+    };
+}
+function toLease(row) {
+    return {
+        project_id: String(row.project_id),
+        branch_id: String(row.branch_id),
+        lease_id: String(row.lease_id),
+        lease_owner: String(row.lease_owner),
+        base_snapshot_hash: String(row.base_snapshot_hash),
+        status: String(row.status),
+        lease_deadline_ms: Number(row.lease_deadline_ms),
+        result_snapshot_hash: row.result_snapshot_hash === null || row.result_snapshot_hash === undefined ? null : String(row.result_snapshot_hash),
+        receipt_id: row.receipt_id === null || row.receipt_id === undefined ? null : String(row.receipt_id),
+        created_at_ms: Number(row.created_at_ms),
+        updated_at_ms: Number(row.updated_at_ms),
+        last_error: row.last_error === null || row.last_error === undefined ? null : String(row.last_error),
+    };
+}
+function withDb(databasePath, fn) {
+    const DatabaseSync = loadDatabaseCtor();
+    const db = new DatabaseSync(databasePath);
+    try {
+        db.exec("PRAGMA foreign_keys = ON;");
+        return fn(db);
+    }
+    finally {
+        db.close();
+    }
+}
+function withImmediateTransaction(db, fn) {
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        const result = fn();
+        db.exec("COMMIT");
+        return result;
+    }
+    catch (err) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            // ignore rollback failures when no transaction is active
+        }
+        throw err;
+    }
+}
+function receiptRoot(databasePath, receiptsPath) {
+    if (receiptsPath) {
+        return receiptsPath;
+    }
+    return path_1.default.join(path_1.default.dirname(path_1.default.dirname(databasePath)), "receipts");
+}
+function relativeArtifactPath(databasePath, artifactPath) {
+    const dbRoot = path_1.default.dirname(path_1.default.dirname(databasePath));
+    return artifactPath.split(path_1.default.sep).join("/").startsWith(".")
+        ? artifactPath
+        : path_1.default.relative(dbRoot, artifactPath).split(path_1.default.sep).join("/");
+}
+function ensureReceiptId(input, detailsJson) {
+    if (input.receipt_id !== undefined) {
+        assertNonEmpty(input.receipt_id, "receipt_id");
+        return input.receipt_id;
+    }
+    const hash = crypto_1.default
+        .createHash("sha256")
+        .update([
+        input.project_id,
+        input.branch_id,
+        input.kind,
+        input.status,
+        input.event_id ?? "",
+        input.idempotency_key ?? "",
+        input.payload_hash ?? "",
+        input.base_snapshot_hash ?? "",
+        input.result_snapshot_hash ?? "",
+        input.reducer_name ?? "",
+        input.reducer_version ?? "",
+        input.lease_id ?? "",
+        detailsJson,
+        String(input.now_ms ?? ""),
+    ].join("\n"))
+        .digest("hex")
+        .slice(0, 16);
+    return `receipt-${safeSegment(input.project_id)}-${safeSegment(input.branch_id)}-${safeSegment(input.kind)}-${hash}`;
+}
+function writeReceiptWithDb(db, databasePath, input) {
+    assertNonEmpty(input.project_id, "project_id");
+    assertNonEmpty(input.branch_id, "branch_id");
+    assertNonEmpty(input.kind, "kind");
+    const currentNow = nowMs(input.now_ms);
+    const detailsJson = stableJson(input.details ?? {});
+    const receiptId = ensureReceiptId(input, detailsJson);
+    const root = receiptRoot(databasePath, input.receipts_path);
+    fs_1.default.mkdirSync(root, { recursive: true });
+    const artifactPath = path_1.default.join(root, `${safeSegment(receiptId)}.json`);
+    const artifact = {
+        receipt_id: receiptId,
+        project_id: input.project_id,
+        branch_id: input.branch_id,
+        kind: input.kind,
+        status: input.status,
+        event_id: input.event_id ?? null,
+        idempotency_key: input.idempotency_key ?? null,
+        payload_hash: input.payload_hash ?? null,
+        base_snapshot_hash: input.base_snapshot_hash ?? null,
+        result_snapshot_hash: input.result_snapshot_hash ?? null,
+        reducer_name: input.reducer_name ?? null,
+        reducer_version: input.reducer_version ?? null,
+        lease_id: input.lease_id ?? null,
+        actor: input.actor ?? null,
+        details: JSON.parse(detailsJson),
+        created_at_ms: currentNow,
+    };
+    const artifactJson = `${stableJson(artifact)}\n`;
+    fs_1.default.writeFileSync(artifactPath, artifactJson, "utf8");
+    const artifactHash = hashJson(artifactJson);
+    const artifactRelative = relativeArtifactPath(databasePath, artifactPath);
+    db
+        .prepare([
+        "INSERT INTO project_receipt",
+        "(receipt_id, project_id, branch_id, kind, status, event_id, idempotency_key, payload_hash, base_snapshot_hash, result_snapshot_hash, reducer_name, reducer_version, lease_id, actor, artifact_path, artifact_hash, details_json, created_at_ms)",
+        "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+        "ON CONFLICT(receipt_id) DO UPDATE SET",
+        "artifact_path = excluded.artifact_path, artifact_hash = excluded.artifact_hash, details_json = excluded.details_json",
+    ].join(" "))
+        .run(receiptId, input.project_id, input.branch_id, input.kind, input.status, input.event_id ?? null, input.idempotency_key ?? null, input.payload_hash ?? null, input.base_snapshot_hash ?? null, input.result_snapshot_hash ?? null, input.reducer_name ?? null, input.reducer_version ?? null, input.lease_id ?? null, input.actor ?? null, artifactRelative, artifactHash, detailsJson, currentNow);
+    const row = db.prepare("SELECT * FROM project_receipt WHERE receipt_id = ?").get(receiptId);
+    if (!row) {
+        throw new Error("receipt could not be reloaded after insert");
+    }
+    return toReceipt(row);
+}
+function getEvent(db, eventId) {
+    const row = db.prepare("SELECT * FROM project_event WHERE event_id = ?").get(eventId);
+    return row ? toEvent(row) : null;
+}
+function getLease(db, projectId, branchId, leaseId) {
+    const row = db
+        .prepare("SELECT * FROM project_writer_lease WHERE project_id = ? AND branch_id = ? AND lease_id = ?")
+        .get(projectId, branchId, leaseId);
+    return row ? toLease(row) : null;
+}
+function writeProjectDbReceipt(databasePath, input) {
+    return withDb(databasePath, (db) => withImmediateTransaction(db, () => writeReceiptWithDb(db, databasePath, input)));
+}
+function recordProjectDbEvent(databasePath, input) {
+    assertNonEmpty(input.event_id, "event_id");
+    assertNonEmpty(input.project_id, "project_id");
+    assertNonEmpty(input.branch_id, "branch_id");
+    assertNonEmpty(input.event_type, "event_type");
+    assertPositiveInteger(input.schema_version, "schema_version");
+    assertNonEmpty(input.idempotency_key, "idempotency_key");
+    assertNonEmpty(input.actor, "actor");
+    const currentNow = nowMs(input.now_ms);
+    const occurredAt = input.occurred_at_ms ?? currentNow;
+    assertInteger(occurredAt, "occurred_at_ms");
+    const payloadJson = stableJson(input.payload);
+    const payloadHash = hashJson(payloadJson);
+    return withDb(databasePath, (db) => withImmediateTransaction(db, () => {
+        const duplicateRow = db
+            .prepare("SELECT * FROM project_event WHERE project_id = ? AND branch_id = ? AND idempotency_key = ?")
+            .get(input.project_id, input.branch_id, input.idempotency_key);
+        if (duplicateRow) {
+            const duplicate = toEvent(duplicateRow);
+            if (duplicate.payload_hash === payloadHash) {
+                return { created: false, duplicate: true, conflict: false, event: duplicate, receipt: null };
+            }
+            const receipt = writeReceiptWithDb(db, databasePath, {
+                project_id: input.project_id,
+                branch_id: input.branch_id,
+                kind: "event-conflict",
+                status: "conflict",
+                event_id: duplicate.event_id,
+                idempotency_key: input.idempotency_key,
+                payload_hash: payloadHash,
+                actor: input.actor,
+                details: {
+                    existing_event_id: duplicate.event_id,
+                    existing_payload_hash: duplicate.payload_hash,
+                    incoming_event_id: input.event_id,
+                    incoming_payload_hash: payloadHash,
+                },
+                now_ms: currentNow,
+                receipts_path: input.receipts_path,
+            });
+            return { created: false, duplicate: false, conflict: true, event: duplicate, receipt };
+        }
+        db
+            .prepare([
+            "INSERT INTO project_event",
+            "(event_id, project_id, branch_id, event_type, schema_version, idempotency_key, payload_json, payload_hash, actor, status, occurred_at_ms, created_at_ms, updated_at_ms, last_error)",
+            "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'received', ?, ?, ?, NULL)",
+        ].join(" "))
+            .run(input.event_id, input.project_id, input.branch_id, input.event_type, input.schema_version, input.idempotency_key, payloadJson, payloadHash, input.actor, occurredAt, currentNow, currentNow);
+        const event = getEvent(db, input.event_id);
+        if (!event) {
+            throw new Error("event could not be reloaded after insert");
+        }
+        return { created: true, duplicate: false, conflict: false, event, receipt: null };
+    }));
+}
+function parseProjectMetaSet(event) {
+    if (event.event_type !== "project_meta.set") {
+        throw new Error(`unsupported event_type for reducer project_meta.set: ${event.event_type}`);
+    }
+    const payload = JSON.parse(event.payload_json);
+    if (typeof payload.key !== "string" || payload.key.trim() === "") {
+        throw new Error("project_meta.set payload.key must be a non-empty string");
+    }
+    if (typeof payload.value !== "string") {
+        throw new Error("project_meta.set payload.value must be a string");
+    }
+    return { key: payload.key, value: payload.value };
+}
+function applyProjectMetaSet(db, event) {
+    const payload = parseProjectMetaSet(event);
+    db
+        .prepare("INSERT INTO project_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value WHERE value <> excluded.value")
+        .run(payload.key, payload.value);
+    return payload;
+}
+function applyProjectDbReducer(databasePath, input) {
+    assertNonEmpty(input.event_id, "event_id");
+    assertNonEmpty(input.actor, "actor");
+    const currentNow = nowMs(input.now_ms);
+    return withDb(databasePath, (db) => withImmediateTransaction(db, () => {
+        const event = getEvent(db, input.event_id);
+        if (!event) {
+            throw new Error(`project DB event not found: ${input.event_id}`);
+        }
+        if (event.status === "applied") {
+            const receipt = writeReceiptWithDb(db, databasePath, {
+                project_id: event.project_id,
+                branch_id: event.branch_id,
+                kind: "event-duplicate",
+                status: "duplicate",
+                event_id: event.event_id,
+                idempotency_key: event.idempotency_key,
+                payload_hash: event.payload_hash,
+                reducer_name: input.reducer_name,
+                reducer_version: input.reducer_version,
+                actor: input.actor,
+                details: { reason: "event already applied" },
+                now_ms: currentNow,
+                receipts_path: input.receipts_path,
+            });
+            return { applied: false, event, receipt };
+        }
+        try {
+            const change = applyProjectMetaSet(db, event);
+            db
+                .prepare("UPDATE project_event SET status = 'applied', updated_at_ms = ?, last_error = NULL WHERE event_id = ?")
+                .run(currentNow, event.event_id);
+            const updated = getEvent(db, event.event_id);
+            if (!updated) {
+                throw new Error("event could not be reloaded after reducer apply");
+            }
+            const receipt = writeReceiptWithDb(db, databasePath, {
+                project_id: event.project_id,
+                branch_id: event.branch_id,
+                kind: "event-applied",
+                status: "applied",
+                event_id: event.event_id,
+                idempotency_key: event.idempotency_key,
+                payload_hash: event.payload_hash,
+                reducer_name: input.reducer_name,
+                reducer_version: input.reducer_version,
+                actor: input.actor,
+                details: { change },
+                now_ms: currentNow,
+                receipts_path: input.receipts_path,
+            });
+            return { applied: true, event: updated, receipt };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            db
+                .prepare("UPDATE project_event SET status = 'rejected', updated_at_ms = ?, last_error = ? WHERE event_id = ?")
+                .run(currentNow, message, event.event_id);
+            const updated = getEvent(db, event.event_id);
+            if (!updated) {
+                throw new Error("event could not be reloaded after reducer reject");
+            }
+            const receipt = writeReceiptWithDb(db, databasePath, {
+                project_id: event.project_id,
+                branch_id: event.branch_id,
+                kind: "event-rejected",
+                status: "rejected",
+                event_id: event.event_id,
+                idempotency_key: event.idempotency_key,
+                payload_hash: event.payload_hash,
+                reducer_name: input.reducer_name,
+                reducer_version: input.reducer_version,
+                actor: input.actor,
+                details: { error: message },
+                now_ms: currentNow,
+                receipts_path: input.receipts_path,
+            });
+            return { applied: false, event: updated, receipt };
+        }
+    }));
+}
+function replayProjectDbEvents(databasePath, input) {
+    assertNonEmpty(input.project_id, "project_id");
+    assertNonEmpty(input.branch_id, "branch_id");
+    assertNonEmpty(input.actor, "actor");
+    const currentNow = nowMs(input.now_ms);
+    return withDb(databasePath, (db) => withImmediateTransaction(db, () => {
+        const rows = db
+            .prepare("SELECT * FROM project_event WHERE project_id = ? AND branch_id = ? AND event_type = ? AND status IN ('received', 'validated', 'applied') ORDER BY occurred_at_ms ASC, event_id ASC")
+            .all(input.project_id, input.branch_id, input.reducer_name);
+        for (const row of rows) {
+            applyProjectMetaSet(db, toEvent(row));
+        }
+        const receipt = writeReceiptWithDb(db, databasePath, {
+            project_id: input.project_id,
+            branch_id: input.branch_id,
+            kind: "event-replay",
+            status: "replay",
+            reducer_name: input.reducer_name,
+            reducer_version: input.reducer_version,
+            actor: input.actor,
+            details: { replayed_event_ids: rows.map((row) => String(row.event_id)) },
+            now_ms: currentNow,
+            receipts_path: input.receipts_path,
+        });
+        return { replayed_count: rows.length, receipt };
+    }));
+}
+function requireActiveLease(db, input) {
+    assertNonEmpty(input.project_id, "project_id");
+    assertNonEmpty(input.branch_id, "branch_id");
+    assertNonEmpty(input.lease_id, "lease_id");
+    assertNonEmpty(input.lease_owner, "lease_owner");
+    const lease = getLease(db, input.project_id, input.branch_id, input.lease_id);
+    if (!lease) {
+        throw new Error(`writer lease not found: ${input.project_id}/${input.branch_id}/${input.lease_id}`);
+    }
+    if (lease.status !== "active") {
+        throw new Error(`writer lease ${input.lease_id} is not active`);
+    }
+    if (lease.lease_owner !== input.lease_owner) {
+        throw new Error(`writer lease ${input.lease_id} is not owned by ${input.lease_owner}`);
+    }
+    return lease;
+}
+function acquireProjectWriterLease(databasePath, input) {
+    assertNonEmpty(input.project_id, "project_id");
+    assertNonEmpty(input.branch_id, "branch_id");
+    assertNonEmpty(input.lease_id, "lease_id");
+    assertNonEmpty(input.lease_owner, "lease_owner");
+    assertNonEmpty(input.base_snapshot_hash, "base_snapshot_hash");
+    assertPositiveInteger(input.lease_ms, "lease_ms");
+    const currentNow = nowMs(input.now_ms);
+    return withDb(databasePath, (db) => withImmediateTransaction(db, () => {
+        db
+            .prepare("UPDATE project_writer_lease SET status = 'expired', updated_at_ms = ?, last_error = 'lease expired' WHERE status = 'active' AND lease_deadline_ms <= ?")
+            .run(currentNow, currentNow);
+        db
+            .prepare("INSERT INTO project_branch_state (project_id, branch_id, current_snapshot_hash, updated_at_ms) VALUES (?, ?, ?, ?) ON CONFLICT(project_id, branch_id) DO NOTHING")
+            .run(input.project_id, input.branch_id, input.base_snapshot_hash, currentNow);
+        db
+            .prepare([
+            "INSERT INTO project_writer_lease",
+            "(project_id, branch_id, lease_id, lease_owner, base_snapshot_hash, status, lease_deadline_ms, result_snapshot_hash, receipt_id, created_at_ms, updated_at_ms, last_error)",
+            "VALUES (?, ?, ?, ?, ?, 'active', ?, NULL, NULL, ?, ?, NULL)",
+        ].join(" "))
+            .run(input.project_id, input.branch_id, input.lease_id, input.lease_owner, input.base_snapshot_hash, currentNow + input.lease_ms, currentNow, currentNow);
+        const lease = getLease(db, input.project_id, input.branch_id, input.lease_id);
+        if (!lease) {
+            throw new Error("writer lease could not be reloaded after insert");
+        }
+        return lease;
+    }));
+}
+function commitProjectWriterLease(databasePath, input) {
+    assertNonEmpty(input.result_snapshot_hash, "result_snapshot_hash");
+    const currentNow = nowMs(input.now_ms);
+    return withDb(databasePath, (db) => withImmediateTransaction(db, () => {
+        const lease = requireActiveLease(db, input);
+        const state = toMessage(db
+            .prepare("SELECT * FROM project_branch_state WHERE project_id = ? AND branch_id = ?")
+            .get(input.project_id, input.branch_id));
+        const currentSnapshotHash = state ? String(state.current_snapshot_hash) : lease.base_snapshot_hash;
+        if (currentSnapshotHash !== lease.base_snapshot_hash) {
+            const receipt = writeReceiptWithDb(db, databasePath, {
+                project_id: input.project_id,
+                branch_id: input.branch_id,
+                kind: "writer-conflict",
+                status: "conflict",
+                base_snapshot_hash: lease.base_snapshot_hash,
+                result_snapshot_hash: input.result_snapshot_hash,
+                lease_id: input.lease_id,
+                actor: input.lease_owner,
+                details: { current_snapshot_hash: currentSnapshotHash },
+                now_ms: currentNow,
+                receipts_path: input.receipts_path,
+            });
+            db
+                .prepare("UPDATE project_writer_lease SET status = 'conflict', result_snapshot_hash = ?, receipt_id = ?, updated_at_ms = ?, last_error = ? WHERE project_id = ? AND branch_id = ? AND lease_id = ?")
+                .run(input.result_snapshot_hash, receipt.receipt_id, currentNow, `snapshot hash mismatch: current ${currentSnapshotHash}, base ${lease.base_snapshot_hash}`, input.project_id, input.branch_id, input.lease_id);
+            const updated = getLease(db, input.project_id, input.branch_id, input.lease_id);
+            if (!updated) {
+                throw new Error("writer lease could not be reloaded after conflict");
+            }
+            return { committed: false, lease: updated, receipt };
+        }
+        const receipt = writeReceiptWithDb(db, databasePath, {
+            project_id: input.project_id,
+            branch_id: input.branch_id,
+            kind: "writer-commit",
+            status: "applied",
+            base_snapshot_hash: lease.base_snapshot_hash,
+            result_snapshot_hash: input.result_snapshot_hash,
+            lease_id: input.lease_id,
+            actor: input.lease_owner,
+            details: { committed: true },
+            now_ms: currentNow,
+            receipts_path: input.receipts_path,
+        });
+        db
+            .prepare("UPDATE project_branch_state SET current_snapshot_hash = ?, updated_at_ms = ? WHERE project_id = ? AND branch_id = ?")
+            .run(input.result_snapshot_hash, currentNow, input.project_id, input.branch_id);
+        db
+            .prepare("UPDATE project_writer_lease SET status = 'committed', result_snapshot_hash = ?, receipt_id = ?, updated_at_ms = ?, last_error = NULL WHERE project_id = ? AND branch_id = ? AND lease_id = ?")
+            .run(input.result_snapshot_hash, receipt.receipt_id, currentNow, input.project_id, input.branch_id, input.lease_id);
+        const updated = getLease(db, input.project_id, input.branch_id, input.lease_id);
+        if (!updated) {
+            throw new Error("writer lease could not be reloaded after commit");
+        }
+        return { committed: true, lease: updated, receipt };
+    }));
+}
+function releaseProjectWriterLease(databasePath, input) {
+    const currentNow = nowMs(input.now_ms);
+    return withDb(databasePath, (db) => withImmediateTransaction(db, () => {
+        requireActiveLease(db, input);
+        db
+            .prepare("UPDATE project_writer_lease SET status = 'released', updated_at_ms = ?, last_error = NULL WHERE project_id = ? AND branch_id = ? AND lease_id = ?")
+            .run(currentNow, input.project_id, input.branch_id, input.lease_id);
+        const updated = getLease(db, input.project_id, input.branch_id, input.lease_id);
+        if (!updated) {
+            throw new Error("writer lease could not be reloaded after release");
+        }
+        return updated;
+    }));
+}
+function releaseExpiredProjectWriterLeases(databasePath, input = {}) {
+    const currentNow = nowMs(input.now_ms);
+    return withDb(databasePath, (db) => withImmediateTransaction(db, () => {
+        const result = db
+            .prepare("UPDATE project_writer_lease SET status = 'expired', updated_at_ms = ?, last_error = 'lease expired' WHERE status = 'active' AND lease_deadline_ms <= ?")
+            .run(currentNow, currentNow);
+        return { released_count: Number(result.changes ?? 0) };
+    }));
+}
+function readProjectWriterLeaseStats(databasePath, input = {}) {
+    const currentNow = nowMs(input.now_ms);
+    return withDb(databasePath, (db) => {
+        const byStatus = {
+            active: 0,
+            committed: 0,
+            released: 0,
+            expired: 0,
+            conflict: 0,
+        };
+        for (const row of db.prepare("SELECT status, COUNT(*) AS count FROM project_writer_lease GROUP BY status").all()) {
+            byStatus[String(row.status)] = Number(row.count ?? 0);
+        }
+        const active = Number(db.prepare("SELECT COUNT(*) AS count FROM project_writer_lease WHERE status = 'active'").get()?.count ?? 0);
+        const expired = Number(db
+            .prepare("SELECT COUNT(*) AS count FROM project_writer_lease WHERE status = 'active' AND lease_deadline_ms <= ?")
+            .get(currentNow)?.count ?? 0);
+        return { active, expired, by_status: byStatus };
+    });
+}

package/dist/core/project_db_migrations.js

@@ -53,6 +53,90 @@ 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 EVENTS_RECEIPTS_MIGRATION_SQL = `
+CREATE TABLE IF NOT EXISTS project_event (
+  event_id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL,
+  branch_id TEXT NOT NULL,
+  event_type TEXT NOT NULL,
+  schema_version INTEGER NOT NULL CHECK(schema_version > 0),
+  idempotency_key TEXT NOT NULL,
+  payload_json TEXT NOT NULL,
+  payload_hash TEXT NOT NULL,
+  actor TEXT NOT NULL,
+  status TEXT NOT NULL CHECK(status IN ('received', 'validated', 'applied', 'rejected', 'dead_letter')),
+  occurred_at_ms INTEGER NOT NULL,
+  created_at_ms INTEGER NOT NULL,
+  updated_at_ms INTEGER NOT NULL,
+  last_error TEXT
+) STRICT;
+
+CREATE UNIQUE INDEX IF NOT EXISTS project_event_idempotency_unique
+ON project_event(project_id, branch_id, idempotency_key);
+
+CREATE INDEX IF NOT EXISTS project_event_branch_status_idx
+ON project_event(project_id, branch_id, status, occurred_at_ms, event_id);
+
+CREATE TABLE IF NOT EXISTS project_receipt (
+  receipt_id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL,
+  branch_id TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  status TEXT NOT NULL CHECK(status IN ('applied', 'rejected', 'duplicate', 'conflict', 'replay', 'dead_letter')),
+  event_id TEXT,
+  idempotency_key TEXT,
+  payload_hash TEXT,
+  base_snapshot_hash TEXT,
+  result_snapshot_hash TEXT,
+  reducer_name TEXT,
+  reducer_version TEXT,
+  lease_id TEXT,
+  actor TEXT,
+  artifact_path TEXT NOT NULL,
+  artifact_hash TEXT NOT NULL,
+  details_json TEXT NOT NULL,
+  created_at_ms INTEGER NOT NULL
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS project_receipt_branch_status_idx
+ON project_receipt(project_id, branch_id, status, created_at_ms, receipt_id);
+
+CREATE INDEX IF NOT EXISTS project_receipt_event_idx
+ON project_receipt(event_id, created_at_ms, receipt_id)
+WHERE event_id IS NOT NULL;
+`;
+const WRITER_LEASES_MIGRATION_SQL = `
+CREATE TABLE IF NOT EXISTS project_branch_state (
+  project_id TEXT NOT NULL,
+  branch_id TEXT NOT NULL,
+  current_snapshot_hash TEXT NOT NULL,
+  updated_at_ms INTEGER NOT NULL,
+  PRIMARY KEY (project_id, branch_id)
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS project_writer_lease (
+  project_id TEXT NOT NULL,
+  branch_id TEXT NOT NULL,
+  lease_id TEXT NOT NULL,
+  lease_owner TEXT NOT NULL,
+  base_snapshot_hash TEXT NOT NULL,
+  status TEXT NOT NULL CHECK(status IN ('active', 'committed', 'released', 'expired', 'conflict')),
+  lease_deadline_ms INTEGER NOT NULL,
+  result_snapshot_hash TEXT,
+  receipt_id TEXT,
+  created_at_ms INTEGER NOT NULL,
+  updated_at_ms INTEGER NOT NULL,
+  last_error TEXT,
+  PRIMARY KEY (project_id, branch_id, lease_id)
+) STRICT;
+
+CREATE UNIQUE INDEX IF NOT EXISTS project_writer_lease_active_unique
+ON project_writer_lease(project_id, branch_id)
+WHERE status = 'active';
+
+CREATE INDEX IF NOT EXISTS project_writer_lease_status_idx
+ON project_writer_lease(project_id, branch_id, status, lease_deadline_ms, lease_id);
+`;
 const BUILTIN_MIGRATIONS = [
     {
         ordinal: 1,
@@ -66,6 +150,18 @@ const BUILTIN_MIGRATIONS = [
         filename: "002_mdkg_project_db_queue.sql",
         sql: QUEUE_MIGRATION_SQL.trim(),
     },
+    {
+        ordinal: 3,
+        key: "mdkg.project_db.events_receipts.v1",
+        filename: "003_mdkg_project_db_events_receipts.sql",
+        sql: EVENTS_RECEIPTS_MIGRATION_SQL.trim(),
+    },
+    {
+        ordinal: 4,
+        key: "mdkg.project_db.writer_leases.v1",
+        filename: "004_mdkg_project_db_writer_leases.sql",
+        sql: WRITER_LEASES_MIGRATION_SQL.trim(),
+    },
 ];
 function loadDatabaseCtor() {
     try {
@@ -207,7 +303,7 @@ function checkMigrationFiles(root, config) {
         ok: errors.length === 0,
         level: errors.length === 0 ? "ok" : "fail",
         path: rel(root, layout.migrations),
-        detail: errors.length === 0 ? "migration files match mdkg-owned foundation migrations" : "migration file issues found",
+        detail: errors.length === 0 ? "migration files match mdkg-owned built-in migrations" : "migration file issues found",
         errors,
         warnings: [],
     };

package/dist/init/AGENT_START.md

@@ -34,10 +34,13 @@ Agent operating prompt:
 - 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 foundation and internal local
-  node:sqlite queue foundation migrations. Queue state is delivery
-  infrastructure, not canonical event history, and there is no public
-  `mdkg db queue` CLI yet. Use `mdkg db verify` and `mdkg db stats` for
+  the runtime SQLite database with mdkg-owned foundation plus internal local
+  node:sqlite queue, event/receipt/reducer, and writer lease/CAS foundation
+  migrations. Queue state is delivery infrastructure, not canonical event
+  history. Event rows are durable local project DB history; receipts, reducers,
+  and writer leases are internal local helper surfaces, and there is no public
+  `mdkg db queue`, `mdkg db event`, `mdkg db reducer`, or `mdkg db lease` CLI
+  yet. 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

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -50,11 +50,15 @@ Project database commands:
   active runtime SQLite database
 - `mdkg db migrate` creates or updates the configured active runtime SQLite
   database and applies mdkg-owned foundation plus internal local node:sqlite
-  queue foundation migrations
+  queue, event/receipt/reducer, and writer lease/CAS foundation migrations
 - `mdkg db migrate` records migration order, checksums, and applied timestamps
   in the configured migration table
 - queue tables are durable local delivery state, not canonical event history;
   there is no public `mdkg db queue` CLI yet
+- event tables are durable local history for project DB state transitions;
+  receipts, typed reducers, and writer leases remain internal helper surfaces in
+  this release, with no public `mdkg db event`, `mdkg db reducer`, or
+  `mdkg db lease` CLI yet
 - `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,

package/dist/init/README.md

@@ -75,10 +75,13 @@ Fresh mdkg workspaces default to `index.backend: sqlite`; `.mdkg/index/mdkg.sqli
 `.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 foundation and
-internal local node:sqlite queue foundation migrations. Queue state is delivery
-infrastructure, not canonical event history, and there is no public
-`mdkg db queue` CLI yet. Use `mdkg db verify` for non-mutating health checks and
+update the active runtime SQLite database with mdkg-owned foundation plus
+internal local node:sqlite queue, event/receipt/reducer, and writer lease/CAS
+foundation migrations. Queue state is delivery infrastructure, not canonical
+event history. Event rows are durable local project DB history; receipts,
+reducers, and writer leases are internal local helper surfaces, and there is no
+public `mdkg db queue`, `mdkg db event`, `mdkg db reducer`, or `mdkg db lease`
+CLI yet. 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

package/dist/init/init-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "mdkg_version": "0.1.8",
+  "mdkg_version": "0.1.9",
   "files": [
     {
       "path": ".mdkg/config.json",
@@ -61,7 +61,7 @@
     {
       "path": ".mdkg/README.md",
       "category": "mdkg_doc",
-      "sha256": "6967c433a9a2d63f0fa4680107a318a75af358873f65326678873986a2fe619d"
+      "sha256": "b692c05fcfa1eaaa90edcd3f7a39042615f90e8915c7d447801c93284ed7463e"
     },
     {
       "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
@@ -186,7 +186,7 @@
     {
       "path": "AGENT_START.md",
       "category": "startup_doc",
-      "sha256": "e14276e5b8e6e004997cc93eab7dff468322f01fb203e44007594d67bc2ba149"
+      "sha256": "1e1d9d94e2aa761b1a7978ab4b44e8bb7c3f0d33e94ed2d98cb06d641f4c42c6"
     },
     {
       "path": "AGENTS.md",
@@ -201,7 +201,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "a942886a2ef48eb895ecaae491d8841d11ee446b5879e4fe48fd2a1ac82c8f53"
+      "sha256": "9f90882d698d0ad1b16bad0fbe37065e4ff9f2b79b27373ef7dce74b78e99265"
     },
     {
       "path": "llms.txt",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdkg",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Markdown Knowledge Graph",
   "license": "MIT",
   "bin": {
@@ -18,6 +18,7 @@
     "smoke:capabilities": "npm run build && node scripts/smoke-capabilities.js",
     "smoke:db": "npm run build && node scripts/smoke-db.js",
     "smoke:db-queue": "npm run build && node scripts/smoke-db-queue.js",
+    "smoke:db-events": "npm run build && node scripts/smoke-db-events.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",
@@ -29,7 +30,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:db && npm run smoke:db-queue && 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",
+    "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-queue && npm run smoke:db-events && 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"
   },