@maadb/core 0.12.4 → 0.14.0

package/dist/engine/audit.js

@@ -2,9 +2,16 @@
 // Audit — history, diff, snapshot, audit (git-backed)
 // ============================================================================
 import { ok, singleErr } from '../errors.js';
+function unavailable(ctx) {
+    const mode = ctx.history?.config.effectiveMode;
+    if (mode === 'feed' || mode === 'read') {
+        return singleErr('HISTORY_DISABLED', `Git history is unavailable in history_mode ${mode}`, undefined, { historyMode: mode });
+    }
+    return singleErr('GIT_NOT_INITIALIZED', 'Git is not available in this project');
+}
 export async function history(ctx, id, opts) {
     if (!ctx.gitLayer)
-        return singleErr('GIT_NOT_INITIALIZED', 'Git is not available in this project');
+        return unavailable(ctx);
     const doc = ctx.backend.getDocument(id);
     if (!doc)
         return singleErr('FILE_NOT_FOUND', `Document "${id}" not found`);
@@ -13,7 +20,7 @@ export async function history(ctx, id, opts) {
 }
 export async function diff(ctx, id, from, to) {
     if (!ctx.gitLayer)
-        return singleErr('GIT_NOT_INITIALIZED', 'Git is not available in this project');
+        return unavailable(ctx);
     const doc = ctx.backend.getDocument(id);
     if (!doc)
         return singleErr('FILE_NOT_FOUND', `Document "${id}" not found`);
@@ -24,7 +31,7 @@ export async function diff(ctx, id, from, to) {
 }
 export async function snapshot(ctx, id, at) {
     if (!ctx.gitLayer)
-        return singleErr('GIT_NOT_INITIALIZED', 'Git is not available in this project');
+        return unavailable(ctx);
     const doc = ctx.backend.getDocument(id);
     if (!doc)
         return singleErr('FILE_NOT_FOUND', `Document "${id}" not found`);
@@ -35,7 +42,7 @@ export async function snapshot(ctx, id, at) {
 }
 export async function audit(ctx, opts) {
     if (!ctx.gitLayer)
-        return singleErr('GIT_NOT_INITIALIZED', 'Git is not available in this project');
+        return unavailable(ctx);
     const entries = await ctx.gitLayer.audit(opts);
     return ok(entries);
 }

package/dist/engine/audit.js.map

@@ -1 +1 @@
-{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/engine/audit.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,sDAAsD;AACtD,+EAA+E;AAI/E,OAAO,EAAE,EAAE,EAAE,SAAS,EAAe,MAAM,cAAc,CAAC;AAY1D,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,GAAkB,EAClB,EAAS,EACT,IAAyC;IAEzC,IAAI,CAAC,GAAG,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC,qBAAqB,EAAE,sCAAsC,CAAC,CAAC;IAEnG,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IACxC,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC,gBAAgB,EAAE,aAAa,EAAY,aAAa,CAAC,CAAC;IAErF,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,QAAkB,EAAE,IAAI,CAAC,CAAC;IACzE,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC;AACrB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,GAAkB,EAClB,EAAS,EACT,IAAY,EACZ,EAAW;IAEX,IAAI,CAAC,GAAG,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC,qBAAqB,EAAE,sCAAsC,CAAC,CAAC;IAEnG,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IACxC,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC,gBAAgB,EAAE,aAAa,EAAY,aAAa,CAAC,CAAC;IAErF,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,QAAkB,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;IAC7E,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC,WAAW,EAAE,wBAAwB,CAAC,CAAC;IACrE,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;AACpB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,GAAkB,EAClB,EAAS,EACT,EAAU;IAEV,IAAI,CAAC,GAAG,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC,qBAAqB,EAAE,sCAAsC,CAAC,CAAC;IAEnG,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IACxC,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC,gBAAgB,EAAE,aAAa,EAAY,aAAa,CAAC,CAAC;IAErF,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAkB,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAC3E,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC,WAAW,EAAE,6BAA6B,CAAC,CAAC;IAC1E,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;AACpB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,GAAkB,EAClB,IAA4D;IAE5D,IAAI,CAAC,GAAG,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC,qBAAqB,EAAE,sCAAsC,CAAC,CAAC;IAEnG,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/C,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC;AACrB,CAAC"}
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/engine/audit.ts"],"names":[],"mappings":"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"}

package/dist/engine/context.d.ts

@@ -4,6 +4,7 @@ import type { GitLayer, CommitOptions, CommitOutcome } from '../git/index.js';
 import type { CommitIdentity } from '../git/commit.js';
 import type { OperationJournal } from './journal.js';
 import type { EmbeddingProvider } from './semantic/types.js';
+import type { HistoryRuntime } from '../history/types.js';
 /**
  * 0.6.10 — Mutable counters on the context so a write-path failure in
  * `gitCommit` can be surfaced through `maad_health` without plumbing state
@@ -28,6 +29,8 @@ export interface EngineContext {
     journal: OperationJournal;
     readOnly: boolean;
     commitFailures: CommitFailureTracker;
+    /** Present once the history runtime has been installed for this engine. */
+    history?: HistoryRuntime;
     /**
      * 0.7.0 — Identity snapshot set per-operation by the MCP layer inside the
      * write mutex. When populated AND MAAD_COMMIT_IDENTITY is not "false",
@@ -48,9 +51,9 @@ export interface EngineContext {
     embeddingProvider?: EmbeddingProvider;
 }
 /**
- * Run a git commit and return the outcome. When gitLayer is absent (git not
- * initialized or disabled), returns `noop` — the caller treats that as
- * durable since there's no git to reconcile against. When the commit fails,
+ * Run a history-policy commit and return the outcome. Before a history runtime
+ * is installed, this falls back to the legacy direct Git behavior. If both the
+ * runtime and gitLayer are absent, returns `noop`. When the commit fails,
  * the failure is logged on the ops channel AND tallied on
  * `ctx.commitFailures` so `maad_health` can surface it; the caller gets the
  * outcome back and can stamp `write_durable: false` on the MCP response.

package/dist/engine/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/engine/context.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAI7D;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAAC;IAClD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,wBAAgB,uBAAuB,IAAI,oBAAoB,CAS9D;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,QAAQ,CAAC;IACnB,WAAW,EAAE,WAAW,CAAC;IACzB,OAAO,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,EAAE,oBAAoB,CAAC;IACrC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC;;;;OAIG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CA6B/F"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/engine/context.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI1D;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAAC;IAClD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,wBAAgB,uBAAuB,IAAI,oBAAoB,CAS9D;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,QAAQ,CAAC;IACnB,WAAW,EAAE,WAAW,CAAC;IACzB,OAAO,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,EAAE,oBAAoB,CAAC;IACrC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC;;;;OAIG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAkC/F"}

package/dist/engine/context.js

@@ -14,15 +14,15 @@ export function newCommitFailureTracker() {
     };
 }
 /**
- * Run a git commit and return the outcome. When gitLayer is absent (git not
- * initialized or disabled), returns `noop` — the caller treats that as
- * durable since there's no git to reconcile against. When the commit fails,
+ * Run a history-policy commit and return the outcome. Before a history runtime
+ * is installed, this falls back to the legacy direct Git behavior. If both the
+ * runtime and gitLayer are absent, returns `noop`. When the commit fails,
  * the failure is logged on the ops channel AND tallied on
  * `ctx.commitFailures` so `maad_health` can surface it; the caller gets the
  * outcome back and can stamp `write_durable: false` on the MCP response.
  */
 export async function gitCommit(ctx, opts) {
-    if (!ctx.gitLayer)
+    if (!ctx.history && !ctx.gitLayer)
         return { status: 'noop' };
     // 0.7.0 — Thread commit identity through when set by the MCP layer.
     // Engine-level direct callers (CLI imports, tests) leave ctx.commitIdentity
@@ -30,7 +30,12 @@ export async function gitCommit(ctx, opts) {
     const enriched = ctx.commitIdentity !== undefined
         ? { ...opts, identity: ctx.commitIdentity }
         : opts;
-    const outcome = await ctx.gitLayer.commit(enriched);
+    const outcome = ctx.history
+        ? await ctx.history.commit(enriched)
+        : await ctx.gitLayer.commit(enriched);
+    if (!ctx.history && outcome.status !== 'failed') {
+        ctx.journal.completeMany(ctx.journal.findIndexedByFiles(opts.files).map(entry => entry.id));
+    }
     if (outcome.status === 'failed') {
         ctx.commitFailures.count++;
         ctx.commitFailures.lastAt = new Date().toISOString();

package/dist/engine/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/engine/context.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,6DAA6D;AAC7D,+EAA+E;AAQ/E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAiBjD,MAAM,UAAU,uBAAuB;IACrC,OAAO;QACL,KAAK,EAAE,CAAC;QACR,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,IAAI;QAChB,SAAS,EAAE,IAAI;KAChB,CAAC;AACJ,CAAC;AA+BD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAkB,EAAE,IAAmB;IACrE,IAAI,CAAC,GAAG,CAAC,QAAQ;QAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC7C,oEAAoE;IACpE,4EAA4E;IAC5E,4DAA4D;IAC5D,MAAM,QAAQ,GAAkB,GAAG,CAAC,cAAc,KAAK,SAAS;QAC9D,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,cAAc,EAAE;QAC3C,CAAC,CAAC,IAAI,CAAC;IACT,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACpD,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAChC,GAAG,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC;QAC3B,GAAG,CAAC,cAAc,CAAC,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrD,GAAG,CAAC,cAAc,CAAC,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;QAC3C,GAAG,CAAC,cAAc,CAAC,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;QACjD,GAAG,CAAC,cAAc,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC;QAC5C,GAAG,CAAC,cAAc,CAAC,SAAS,GAAG,IAAI,CAAC,KAAe,CAAC;QACpD,gBAAgB,CAAC;YACf,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,MAAM,EAAE,IAAI,CAAC,KAAe;YAC5B,QAAQ,EAAE,IAAI,CAAC,OAAiB;YAChC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM;SAC9B,CAAC,CAAC;QACH,wEAAwE;QACxE,yDAAyD;QACzD,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,yBAAyB,IAAI,CAAC,KAAe,KAAK,OAAO,CAAC,IAAI,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC5H,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/engine/context.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,6DAA6D;AAC7D,+EAA+E;AAS/E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAiBjD,MAAM,UAAU,uBAAuB;IACrC,OAAO;QACL,KAAK,EAAE,CAAC;QACR,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,IAAI;QAChB,SAAS,EAAE,IAAI;KAChB,CAAC;AACJ,CAAC;AAiCD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAkB,EAAE,IAAmB;IACrE,IAAI,CAAC,GAAG,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ;QAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC7D,oEAAoE;IACpE,4EAA4E;IAC5E,4DAA4D;IAC5D,MAAM,QAAQ,GAAkB,GAAG,CAAC,cAAc,KAAK,SAAS;QAC9D,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,cAAc,EAAE;QAC3C,CAAC,CAAC,IAAI,CAAC;IACT,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO;QACzB,CAAC,CAAC,MAAM,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC;QACpC,CAAC,CAAC,MAAM,GAAG,CAAC,QAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACzC,IAAI,CAAC,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAChD,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9F,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAChC,GAAG,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC;QAC3B,GAAG,CAAC,cAAc,CAAC,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrD,GAAG,CAAC,cAAc,CAAC,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;QAC3C,GAAG,CAAC,cAAc,CAAC,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;QACjD,GAAG,CAAC,cAAc,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC;QAC5C,GAAG,CAAC,cAAc,CAAC,SAAS,GAAG,IAAI,CAAC,KAAe,CAAC;QACpD,gBAAgB,CAAC;YACf,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,MAAM,EAAE,IAAI,CAAC,KAAe;YAC5B,QAAQ,EAAE,IAAI,CAAC,OAAiB;YAChC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM;SAC9B,CAAC,CAAC;QACH,wEAAwE;QACxE,yDAAyD;QACzD,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,yBAAyB,IAAI,CAAC,KAAe,KAAK,OAAO,CAAC,IAAI,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC5H,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/engine/index.d.ts

@@ -2,9 +2,10 @@ import { type Result } from '../errors.js';
 import type { DocId, DocType, FilePath, Registry, SchemaDefinition, ExtractionResult } from '../types.js';
 import type { MaadBackend } from '../backend/index.js';
 import { GitLayer } from '../git/index.js';
+import type { HistoryHealthState } from '../history/types.js';
 import type { EmbeddingProvider } from './semantic/types.js';
 import * as maintenance from './maintenance.js';
-export type { IndexResult, CreateResult, GetResult, UpdateResult, DeleteResult, FindResult, SearchResult, RelatedResult, DescribeResult, SummaryResult, GetFullResult, SchemaInfoResult, ValidationReport, VerifyResult, } from './types.js';
+export type { IndexResult, CreateResult, GetResult, UpdateResult, DeleteResult, FindResult, SearchResult, RelatedResult, RelationshipPathsResult, RelationshipPathQuery, DescribeResult, SummaryResult, GetFullResult, SchemaInfoResult, ValidationReport, VerifyResult, } from './types.js';
 export type { SemanticSearchQuery, SemanticSearchResult, SemanticHit, SearchMode, } from './semantic/types.js';
 export interface HealthReport {
     projectRoot: string;
@@ -40,6 +41,7 @@ export interface HealthReport {
         sha: string;
         createdAt: string;
     } | null;
+    history: HistoryHealthState;
 }
 export declare class MaadEngine {
     private projectRoot;
@@ -48,6 +50,7 @@ export declare class MaadEngine {
     private backend;
     private gitLayer;
     private journal;
+    private historyRuntime;
     private commitFailures;
     private pendingCommitIdentity;
     private initialized;
@@ -85,11 +88,13 @@ export declare class MaadEngine {
     runExclusive<T>(op: string, fn: () => Promise<T>): Promise<T>;
     init(projectRoot: string, opts?: {
         readOnly?: boolean;
+        history?: import('../history/types.js').ResolvedHistoryConfig;
         semantic?: boolean;
         embeddingProvider?: EmbeddingProvider;
         guardEmptyIndex?: boolean;
     }): Promise<Result<void>>;
     isReadOnly(): boolean;
+    private readOnlyMutationError;
     reload(): Promise<Result<void>>;
     /**
      * 0.7.7 — Lightweight in-place reload of registry + schemas.
@@ -167,13 +172,25 @@ export declare class MaadEngine {
     private assertInit;
     indexAll(opts?: {
         force?: boolean;
-    }): Promise<import("./types.js").IndexResult | Result<unknown, import("../errors.js").MaadError[]>>;
-    indexFile(absolutePath: FilePath): Promise<Result<ExtractionResult>>;
+    }): Promise<import("./types.js").IndexResult | Result<never>>;
+    indexFile(absolutePath: FilePath): Promise<{
+        ok: false;
+        errors: import("../errors.js").MaadError[];
+    } | {
+        ok: true;
+        value: ExtractionResult;
+    }>;
     reindex(opts?: {
         docId?: DocId;
         force?: boolean;
         embeddings?: boolean;
-    }): Promise<Result<import("./types.js").IndexResult>>;
+    }): Promise<{
+        ok: false;
+        errors: import("../errors.js").MaadError[];
+    } | {
+        ok: true;
+        value: import("./types.js").IndexResult;
+    }>;
     /**
      * 0.8.0 — await the async embed worker draining the queue to completion, so
      * the vector index is caught up with what's been written. No-op when semantic
@@ -181,6 +198,7 @@ export declare class MaadEngine {
      * hosts needing a consistent vector index, and by tests.
      */
     flushSemanticIndex(): Promise<void>;
+    flushHistory(trigger?: import('../history/types.js').HistoryFlushTrigger): Promise<import("../history/types.js").HistoryFlushResult>;
     /**
      * 0.8.0 — semantic subsystem health for maad_health.embeddings. Always returns
      * a stable shape; `enabled:false` when semantic is off or the index never
@@ -201,6 +219,7 @@ export declare class MaadEngine {
     findDocuments(query: import('../types.js').DocumentQuery): Result<import("./types.js").FindResult>;
     searchObjects(query: import('../types.js').ObjectQuery): Result<import("./types.js").SearchResult>;
     listRelated(id: DocId, direction: 'outgoing' | 'incoming' | 'both', types?: DocType[]): Result<import("./types.js").RelatedResult>;
+    relationshipPaths(query: import('./types.js').RelationshipPathQuery): Result<import("./types.js").RelationshipPathsResult>;
     describe(): import("./types.js").DescribeResult;
     summary(): import("./types.js").SummaryResult;
     getSchema(dt: DocType): SchemaDefinition | undefined;
@@ -215,7 +234,7 @@ export declare class MaadEngine {
         errors: import("../errors.js").MaadError[];
     } | {
         ok: true;
-        value: unknown;
+        value: import("./types.js").BackupTag;
     }>;
     backupList(opts?: import('./types.js').ListBackupsOptions): Promise<Result<import("./types.js").BackupTag[]>>;
     backupDelete(tag: string): Promise<{
@@ -223,7 +242,9 @@ export declare class MaadEngine {
         errors: import("../errors.js").MaadError[];
     } | {
         ok: true;
-        value: unknown;
+        value: {
+            removed: string;
+        };
     }>;
     changesSince(query: import('./types.js').ChangesSinceQuery): Result<import("./types.js").ChangesPage>;
     semanticSearch(query: import('./semantic/types.js').SemanticSearchQuery): Promise<Result<import("./semantic/types.js").SemanticSearchResult>>;
@@ -233,56 +254,56 @@ export declare class MaadEngine {
         errors: import("../errors.js").MaadError[];
     } | {
         ok: true;
-        value: unknown;
+        value: import("./types.js").CreateResult;
     }>;
     updateDocument(id: DocId, fields?: Record<string, unknown>, body?: string, appendBody?: string, expectedVersion?: number): Promise<{
         ok: false;
         errors: import("../errors.js").MaadError[];
     } | {
         ok: true;
-        value: unknown;
+        value: import("./types.js").UpdateResult;
     }>;
     deleteDocument(id: DocId, mode: 'soft' | 'hard'): Promise<{
         ok: false;
         errors: import("../errors.js").MaadError[];
     } | {
         ok: true;
-        value: unknown;
+        value: import("./types.js").DeleteResult;
     }>;
     bulkCreate(records: import('./types.js').BulkCreateInput[]): Promise<{
         ok: false;
         errors: import("../errors.js").MaadError[];
     } | {
         ok: true;
-        value: unknown;
+        value: import("./types.js").BulkResult;
     }>;
     bulkUpdate(updates: import('./types.js').BulkUpdateInput[]): Promise<{
         ok: false;
         errors: import("../errors.js").MaadError[];
     } | {
         ok: true;
-        value: unknown;
+        value: import("./types.js").BulkResult;
     }>;
     bulkDelete(docIds: string[], mode: 'soft' | 'hard'): Promise<{
         ok: false;
         errors: import("../errors.js").MaadError[];
     } | {
         ok: true;
-        value: unknown;
+        value: import("./types.js").BulkDeleteResult;
     }>;
     purgeSoftDeleted(olderThanIso: string, maxRecords: number): Promise<{
         ok: false;
         errors: import("../errors.js").MaadError[];
     } | {
         ok: true;
-        value: unknown;
+        value: import("./types.js").PurgeSoftDeletedResult;
     }>;
     repairWhere(filter: Record<string, import('../types.js').FilterCondition> | undefined, docType: DocType | undefined, repairTypes: import('./types.js').RepairStrategyName[], maxRecords: number): Promise<{
         ok: false;
         errors: import("../errors.js").MaadError[];
     } | {
         ok: true;
-        value: unknown;
+        value: import("./types.js").RepairWhereResult;
     }>;
     validate(docId?: DocId, options?: maintenance.ValidateOptions): Promise<Result<import("./types.js").ValidationReport>>;
     history(id: DocId, opts?: {

package/dist/engine/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"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"}

package/dist/engine/index.js

@@ -23,6 +23,8 @@ import { SqliteBackend } from '../backend/index.js';
 import { GitLayer } from '../git/index.js';
 import { newCommitFailureTracker } from './context.js';
 import { OperationJournal } from './journal.js';
+import { HistoryController } from '../history/controller.js';
+import { resolveHistoryConfig } from '../history/config.js';
 import { isSemanticEnabled, readSemanticEnv } from './semantic/config.js';
 import { resolveEmbeddingProvider } from './semantic/provider.js';
 import { SemanticIndexer } from './semantic/indexer.js';
@@ -98,6 +100,7 @@ export class MaadEngine {
     backend;
     gitLayer = null;
     journal;
+    historyRuntime = null;
     commitFailures = newCommitFailureTracker();
     // 0.7.0 — pending commit identity set per-operation by the MCP `withEngine`
     // wrapper inside the write mutex (safe because write mutex serializes all
@@ -186,7 +189,13 @@ export class MaadEngine {
     }
     async init(projectRoot, opts) {
         this.projectRoot = path.resolve(projectRoot);
-        this._readOnly = opts?.readOnly ?? false;
+        const historyResult = opts?.history !== undefined
+            ? ok(opts.history)
+            : resolveHistoryConfig({}, this.projectRoot);
+        if (!historyResult.ok)
+            return historyResult;
+        const historyConfig = historyResult.value;
+        this._readOnly = (opts?.readOnly ?? false) || historyConfig.effectiveMode === 'read';
         this.bootOpts = opts;
         // Self-heal engine-owned state on empty projects. In read-only mode we
         // refuse to write anything: a missing registry/schema/backend is a hard
@@ -260,7 +269,7 @@ export class MaadEngine {
         }
         // Operation journal — tracks pending writes for crash recovery
         this.journal = new OperationJournal(backendDir);
-        this.startupRecovery = this._readOnly ? [] : this.journal.reconcile();
+        this.startupRecovery = this._readOnly ? [] : this.journal.reconcile({ retainIndexed: true });
         this.gitLayer = new GitLayer(this.projectRoot);
         if (await this.gitLayer.isRepo()) {
             // Git is available — check for stale index.lock from a crashed prior process.
@@ -276,6 +285,13 @@ export class MaadEngine {
         else {
             this.gitLayer = null;
         }
+        this.historyRuntime = new HistoryController(historyConfig, this.gitLayer, this.journal, (op, fn) => this.runExclusive(op, fn));
+        const recovered = await this.historyRuntime.recover();
+        if (recovered) {
+            this.startupRecovery.push(recovered.outcome.status === 'failed'
+                ? `history_recovery_failed:${recovered.outcome.code}`
+                : `history_recovery_completed:${historyConfig.effectiveMode}`);
+        }
         this.initialized = true;
         // Warm the git-clean cache so the first health() call returns real data
         // instead of null. Best-effort — a failure here falls through to null
@@ -320,6 +336,11 @@ export class MaadEngine {
     isReadOnly() {
         return this._readOnly;
     }
+    readOnlyMutationError() {
+        return this.historyRuntime?.config.effectiveMode === 'read'
+            ? singleErr('PROJECT_READ_ONLY', 'Project history_mode is read')
+            : singleErr('READ_ONLY', 'Engine is in read-only mode');
+    }
     async reload() {
         return this.runExclusive('reload', async () => {
             const replacement = new MaadEngine();
@@ -334,6 +355,8 @@ export class MaadEngine {
             this.backend = replacement.backend;
             this.gitLayer = replacement.gitLayer;
             this.journal = replacement.journal;
+            this.historyRuntime = replacement.historyRuntime;
+            this.historyRuntime?.bindSerializer((op, fn) => this.runExclusive(op, fn));
             this.startupRecovery = replacement.startupRecovery;
             this.semanticEnabled = replacement.semanticEnabled;
             this.embeddingProvider = replacement.embeddingProvider;
@@ -342,6 +365,7 @@ export class MaadEngine {
             // Ownership moved to this instance; prevent replacement.close() from
             // touching the adopted backend or worker.
             replacement.semanticIndexer = null;
+            replacement.historyRuntime = null;
             replacement.initialized = false;
             return ok(undefined);
         });
@@ -429,6 +453,7 @@ export class MaadEngine {
             lastIntegritySweepAt: this.backend.getMeta('last_integrity_sweep_at'),
             lastIntegrityFindings: parseStoredJson(this.backend.getMeta('last_integrity_findings')),
             lastBackupTag: parseStoredJson(this.backend.getMeta('last_backup_tag')),
+            history: this.historyRuntime.health(),
         };
     }
     // ---- H8 probes ------------------------------------------------------------
@@ -543,6 +568,8 @@ export class MaadEngine {
     }
     async disposeResources() {
         this.initialized = false;
+        const history = this.historyRuntime;
+        this.historyRuntime = null;
         const indexer = this.semanticIndexer;
         this.semanticIndexer = null;
         if (indexer)
@@ -553,6 +580,11 @@ export class MaadEngine {
             }
             catch { /* idempotent/best-effort teardown */ }
         }
+        // History flushes use the journal and Git only. Close SQLite first so
+        // legacy callers that do not await close() still release the Windows file
+        // handle synchronously, then finish the bounded Git boundary.
+        if (history)
+            await history.close();
     }
     ctx() {
         this.assertInit();
@@ -565,6 +597,7 @@ export class MaadEngine {
             journal: this.journal,
             readOnly: this._readOnly,
             commitFailures: this.commitFailures,
+            ...(this.historyRuntime !== null ? { history: this.historyRuntime } : {}),
             semanticEnabled: this.semanticEnabled,
             ...(this.embeddingProvider !== null ? { embeddingProvider: this.embeddingProvider } : {}),
             ...(this.pendingCommitIdentity !== undefined ? { commitIdentity: this.pendingCommitIdentity } : {}),
@@ -600,13 +633,17 @@ export class MaadEngine {
     // tests) get serialized via the first (outer) acquire.
     async indexAll(opts) {
         if (this._readOnly)
-            return singleErr('READ_ONLY', 'Engine is in read-only mode');
+            return this.readOnlyMutationError();
         return this.kickIndexer(await this.runExclusive('indexAll', () => indexing.indexAll(this.ctx(), opts)));
     }
     async indexFile(absolutePath) {
+        if (this._readOnly)
+            return this.readOnlyMutationError();
         return this.kickIndexer(await this.runExclusive('indexFile', () => indexing.indexFile(this.ctx(), absolutePath)));
     }
     async reindex(opts) {
+        if (this._readOnly)
+            return this.readOnlyMutationError();
         // `embeddings` forces a full reindex (so block_text/FTS are (re)populated for
         // every doc — needed when enabling semantic on an existing project), then
         // re-enqueues all blocks and drains the worker so the rebuild is synchronous.
@@ -638,6 +675,10 @@ export class MaadEngine {
     async flushSemanticIndex() {
         await this.semanticIndexer?.flush();
     }
+    async flushHistory(trigger = 'explicit') {
+        this.assertInit();
+        return this.runExclusive(`history:${trigger}`, () => this.historyRuntime.flush(trigger));
+    }
     /**
      * 0.8.0 — semantic subsystem health for maad_health.embeddings. Always returns
      * a stable shape; `enabled:false` when semantic is off or the index never
@@ -663,6 +704,7 @@ export class MaadEngine {
     findDocuments(query) { return reads.findDocuments(this.ctx(), query); }
     searchObjects(query) { return reads.searchObjects(this.ctx(), query); }
     listRelated(id, direction, types) { return reads.listRelated(this.ctx(), id, direction, types); }
+    relationshipPaths(query) { return reads.relationshipPaths(this.ctx(), query); }
     describe() { return reads.describe(this.ctx()); }
     summary() { return reads.summary(this.ctx()); }
     getSchema(dt) { return reads.getSchema(this.ctx(), dt); }
@@ -674,13 +716,13 @@ export class MaadEngine {
     async verifyIntegrity(query) { return reads.verifyIntegrity(this.ctx(), query); }
     async backupCreate(opts) {
         if (this._readOnly)
-            return singleErr('READ_ONLY', 'Engine is in read-only mode');
+            return this.readOnlyMutationError();
         return backup.createBackup(this.ctx(), opts);
     }
     async backupList(opts) { return backup.listBackups(this.ctx(), opts); }
     async backupDelete(tag) {
         if (this._readOnly)
-            return singleErr('READ_ONLY', 'Engine is in read-only mode');
+            return this.readOnlyMutationError();
         return backup.deleteBackup(this.ctx(), tag);
     }
     changesSince(query) { return reads.changesSince(this.ctx(), query); }
@@ -692,42 +734,42 @@ export class MaadEngine {
     // Self-wrapping. Reentrant under an outer runExclusive scope.
     async createDocument(dt, fields, body, customDocId) {
         if (this._readOnly)
-            return singleErr('READ_ONLY', 'Engine is in read-only mode');
+            return this.readOnlyMutationError();
         return this.kickIndexer(await this.runExclusive('createDocument', () => writes.createDocument(this.ctx(), dt, fields, body, customDocId)));
     }
     async updateDocument(id, fields, body, appendBody, expectedVersion) {
         if (this._readOnly)
-            return singleErr('READ_ONLY', 'Engine is in read-only mode');
+            return this.readOnlyMutationError();
         return this.kickIndexer(await this.runExclusive('updateDocument', () => writes.updateDocument(this.ctx(), id, fields, body, appendBody, expectedVersion)));
     }
     async deleteDocument(id, mode) {
         if (this._readOnly)
-            return singleErr('READ_ONLY', 'Engine is in read-only mode');
+            return this.readOnlyMutationError();
         return this.runExclusive('deleteDocument', () => writes.deleteDocument(this.ctx(), id, mode));
     }
     async bulkCreate(records) {
         if (this._readOnly)
-            return singleErr('READ_ONLY', 'Engine is in read-only mode');
+            return this.readOnlyMutationError();
         return this.kickIndexer(await this.runExclusive('bulkCreate', () => writes.bulkCreate(this.ctx(), records)));
     }
     async bulkUpdate(updates) {
         if (this._readOnly)
-            return singleErr('READ_ONLY', 'Engine is in read-only mode');
+            return this.readOnlyMutationError();
         return this.kickIndexer(await this.runExclusive('bulkUpdate', () => writes.bulkUpdate(this.ctx(), updates)));
     }
     async bulkDelete(docIds, mode) {
         if (this._readOnly)
-            return singleErr('READ_ONLY', 'Engine is in read-only mode');
+            return this.readOnlyMutationError();
         return this.runExclusive('bulkDelete', () => writes.bulkDelete(this.ctx(), docIds, mode));
     }
     async purgeSoftDeleted(olderThanIso, maxRecords) {
         if (this._readOnly)
-            return singleErr('READ_ONLY', 'Engine is in read-only mode');
+            return this.readOnlyMutationError();
         return this.runExclusive('purgeSoftDeleted', () => writes.purgeSoftDeleted(this.ctx(), olderThanIso, maxRecords));
     }
     async repairWhere(filter, docType, repairTypes, maxRecords) {
         if (this._readOnly)
-            return singleErr('READ_ONLY', 'Engine is in read-only mode');
+            return this.readOnlyMutationError();
         return this.kickIndexer(await this.runExclusive('repairWhere', () => repairs.repairWhere(this.ctx(), filter, docType, repairTypes, maxRecords)));
     }
     // --- Maintenance ---