@maadb/core 0.0.1 → 0.7.10-rc.3

package/dist/maad-md.js

@@ -0,0 +1,252 @@
+// ============================================================================
+// MAAD.md Generator
+// Generates the LLM instruction file for a MAAD project.
+// Content is STABLE — no volatile counts, no project-state details.
+// Regenerated on every reindex so interface changes propagate.
+// ============================================================================
+export function generateMaadMd(ctx) {
+    const cmd = buildCmdPrefix(ctx.enginePath, ctx.projectRoot);
+    const sections = [];
+    sections.push(generateHeader(cmd));
+    sections.push(generateQuickStart(cmd, ctx));
+    sections.push(generateFullCommandRef(cmd));
+    sections.push(generatePrimitives());
+    sections.push(generateRules());
+    sections.push(generateCompositionPatterns(cmd));
+    sections.push(generateFeedback());
+    return sections.join('\n\n---\n\n') + '\n';
+}
+function buildCmdPrefix(enginePath, projectRoot) {
+    return `node ${enginePath} --project ${projectRoot}`;
+}
+// ---- Sections -------------------------------------------------------------
+function generateHeader(cmd) {
+    return `# MAAD.md — LLM Interface
+
+> Auto-generated by the MAAD engine. Do not edit.
+>
+> **This is a test/evaluation project.** If you find issues or have improvement ideas,
+> create a feedback file: \`feedback-YYYY-MM-DD-<model>.md\` (e.g. \`feedback-2026-04-07-gpt-5.md\`).
+
+## What is this?
+
+A **MAAD project** — a markdown-native database. Markdown files are the records. A queryable index gives you structured access without reading full files.
+
+**This file** = stable operating instructions. Read once per session.
+**\`maad_summary\` tool** = live project snapshot. Run once per session to see what's here.
+**SCHEMA.md** = deep structural reference. Read only when \`maad_schema\` isn't enough.
+
+## How to access data
+
+Use **MAAD MCP tools** for all data operations. Do not use shell commands or direct file reads for data access. If \`maad_summary\` reports an empty project, read \`_skills/architect-core.md\` and enter Architect mode to design and deploy the schema.
+
+If using CLI for debugging:
+\`\`\`
+${cmd} <command> [args]
+\`\`\``;
+}
+function generateQuickStart(cmd, _ctx) {
+    return `## Boot Sequence
+
+**1. You just read this file.** You now know the commands.
+
+**2. Run \`summary\` to see what's in this project:**
+\`\`\`
+${cmd} summary
+\`\`\`
+Returns: types + counts, sample doc_ids, extracted object inventory.
+
+That's it. You're oriented. Now use the commands below as needed.
+
+### Reading data
+- \`get <doc_id> hot\` — frontmatter only (cheapest)
+- \`get <doc_id> full\` — resolved record: refs, objects, related docs
+- \`get <doc_id> warm <block_id>\` — frontmatter + one section
+- \`get <doc_id> cold\` — full file (expensive, use sparingly)
+
+### Before writing
+- \`schema <type>\` — field definitions, required fields, enum values
+
+### Reference (not needed for boot)
+- **SCHEMA.md** has full field-level detail for every type. Read it when \`schema <type>\` isn't enough.
+- **\`audit\`** shows recent git activity if you need project history.`;
+}
+function generateFullCommandRef(cmd) {
+    return `## All Commands
+
+> Commands shown below in CLI form for explicit syntax. **MCP tool names prefix \`maad_\`** (e.g. \`get\` → \`maad_get\`, \`bulk_create\` → \`maad_bulk_create\`). Agent workflows use the MCP variants; CLI is for operator debugging.
+
+### Discover
+| Command | What it does |
+|---------|-------------|
+| \`scan <file.md>\` | Structural analysis of a raw file (no registry needed) |
+| \`scan <dir/>\` | Corpus-level patterns: recurring fields, headings, document families |
+| \`summary\` | **Start here.** Types, counts, sample IDs, object inventory |
+
+### Read
+| \`describe\` | Project overview: types, doc counts, primitives |
+| \`get <doc_id> hot\` | Frontmatter only (cheapest read) |
+| \`get <doc_id> warm <block>\` | Frontmatter + one section |
+| \`get <doc_id> cold\` | Full document (expensive — use sparingly) |
+| \`get <doc_id> full\` | Resolved record: refs resolved, objects, related, latest note |
+| \`query <type>\` | All documents of a type |
+| \`query <type> --filter field=value\` | Filtered (ops: eq, neq, gt, gte, lt, lte, in, contains) |
+| \`query <type> --fields name,status\` | Return frontmatter fields in results (projection) |
+| \`search <primitive>\` | Cross-document object search |
+| \`search <primitive> --subtype <s>\` | Filter by subtype (e.g. person, attorney) |
+| \`search <primitive> --query <text>\` | Substring match on values (alias: --contains) |
+| \`related <doc_id> both\` | All connected documents (outgoing + incoming) |
+| \`related <doc_id> outgoing\` | Documents this one references |
+| \`related <doc_id> incoming\` | Documents that reference this one |
+| \`schema <type>\` | Field definitions, ID prefix, format hints (use before writes) |
+| \`aggregate\` | Group by a field with count/sum/avg/min/max. **Use instead of iterating records to compute totals.** Supports multi-hop ref chains (\`a->b->c\`) for cross-doctype aggregates. Filters accept \`between\` shortcut and array-of-ops (AND). |
+| \`join\` | Query + follow refs + project fields from both sides in one call. **Use instead of \`query\` → \`get\` → \`get\` chains.** |
+| \`verify mode=field\` | Fact-check a field value: grounded true/false + actual value + source |
+| \`verify mode=count\` | Fact-check a document count: grounded true/false + actual count |
+| \`changes_since <cursor>\` | Delta feed — records modified since cursor. Opaque base64url cursor, stable order on (updated_at ASC, doc_id ASC). Empty cursor = from the beginning. |
+
+### Write
+| Command | What it does |
+|---------|-------------|
+| \`create <type> --field k=v [--field k=v ...] [--body "text"] [--id custom-id]\` | Create a new record |
+| \`update <doc_id> --field k=v [--field k=v ...]\` | Update frontmatter fields |
+| \`update <doc_id> --append "text"\` | Append to document body |
+| \`update <doc_id> --body "text"\` | Replace document body |
+| \`bulk_create\` | Create multiple records in one call (MCP only) |
+| \`bulk_update\` | Update multiple records in one call (MCP only) |
+| \`delete <doc_id>\` | Remove a record (soft by default, \`--hard\` for hard delete) |
+
+### Maintain
+| Command | What it does |
+|---------|-------------|
+| \`validate\` | Validate all documents against schemas |
+| \`validate <doc_id>\` | Validate one document |
+| \`reindex --force\` | Rebuild the full index from markdown |
+| \`reload\` | Reload registry + schemas without restart (after editing \`_registry/\` or \`_schema/\`) |
+| \`health\` | Engine status — write queue depth, last write op, disk headroom, git clean flag, transport + session telemetry |
+| \`parse <file.md>\` | Parse one file, show structure |
+
+### Audit (requires git)
+| Command | What it does |
+|---------|-------------|
+| \`history <doc_id>\` | Change history for a document |
+| \`audit\` | Project-wide activity |
+| \`audit --since <date>\` | Activity since a date |
+
+### Field syntax for create/update
+- String: \`--field name=Acme Corp\`
+- Enum: \`--field status=open\`
+- Ref: \`--field client=cli-acme\`
+- Array: \`--field tags=[enterprise,priority]\`
+- Date: \`--field opened_at=2026-04-07\``;
+}
+function generatePrimitives() {
+    return `## Extraction Primitives
+
+Inline annotations in markdown body use \`[[type:value|label]]\` syntax. The engine extracts and indexes them.
+
+| Primitive | Captures | Search example |
+|-----------|----------|---------------|
+| \`entity\` | person, org, team, product | \`search entity --subtype person\` |
+| \`date\` | date, datetime | \`search date --contains 2026\` |
+| \`duration\` | time span (3 hours, 2 weeks) | \`search duration\` |
+| \`amount\` | currency (100.00 USD, $500) | \`search amount\` |
+| \`measure\` | value + unit (500mg, 6 feet) | \`search measure\` |
+| \`quantity\` | bare count (42, 1800) | \`search quantity\` |
+| \`percentage\` | ratio (15%, 0.85) | \`search percentage\` |
+| \`location\` | place, address | \`search location\` |
+| \`identifier\` | case number, invoice, code | \`search identifier\` |
+| \`contact\` | email, phone, URL | \`search contact\` |
+| \`media\` | image, video, audio, document | \`search media\` |`;
+}
+function generateRules() {
+    return `## Rules
+
+1. **Run \`summary\` first** in every new session — one call to orient
+2. **Use \`hot\` reads by default** — escalate to \`full\`, \`warm\`, then \`cold\` only when needed
+3. **Use \`schema <type>\` before writes** — know what fields are required
+4. **Use MAAD MCP tools for writes** — never edit markdown files directly; CLI forms above are for operator debugging only
+5. **Use \`search\` for cross-document queries** — don't open files to find people/dates/amounts
+6. **Use \`related\` for graph traversal** — don't manually search for connected docs
+7. **Cite \`doc_id\` and \`block_id\`** in answers for traceability
+8. **\`reindex --force\`** recovers from any stale state
+9. **Inspect \`_meta.warnings[]\` on write responses** — the engine surfaces soft-validation signals (precision drift, deprecation hints) alongside successful writes. Agents self-correct on warnings, not just on errors
+10. **Use \`aggregate\` for group-by totals** — don't iterate records to compute counts, sums, averages, mins, or maxes. One \`aggregate\` call with \`metric\` + \`groupBy\` returns the answer; use the \`a->b->c\` ref-chain form for cross-doctype groupings.
+11. **Use \`join\` to follow refs in one call** — don't chain \`query\` → \`get\` → \`get\` to collect related fields. \`join\` projects fields from both sides of a ref in one pass.
+
+## Grounding Rules (CRITICAL)
+
+**Never state a number, date, amount, count, or ID from memory.** Always query first.
+
+- Before reporting a field value → call \`get\` or \`verify\` with the doc_id and field
+- Before reporting a count → call \`verify\` in count mode or \`query\` with the type and filters
+- Before reporting a relationship → call \`related\` or \`join\`
+- If you cannot ground a claim from the database → say "unable to verify from records"
+
+Use \`maad_verify\` to fact-check before answering:
+- \`verify mode=field docId=cas-001 field=claim_amount expected="1500000.00 USD"\`
+- \`verify mode=count docType=case expectedCount=12 filters={status: "open"}\`
+
+**The pattern:** query or verify → confirm grounded → then answer. Never the reverse.`;
+}
+function generateCompositionPatterns(cmd) {
+    return `## Composition Patterns
+
+These are common multi-step operations built from primitives. The engine does not provide these as single commands — you compose them.
+
+### Deep inspect (full engine internals for a document)
+\`\`\`
+${cmd} get <doc_id> hot          # frontmatter + metadata
+${cmd} validate <doc_id>         # schema validation state
+${cmd} related <doc_id> both     # all relationships
+${cmd} search entity --doc <doc_id>  # all extracted objects
+\`\`\`
+
+### Onboard raw files (bootstrap a new project)
+\`\`\`
+${cmd} scan <directory>           # corpus-level patterns
+# Read the output, then:
+# 1. Create _registry/object_types.yaml with detected families
+# 2. Create _schema/*.yaml with detected field patterns
+# 3. Add frontmatter to each file
+${cmd} reindex --force            # build the index
+${cmd} summary                    # confirm orientation
+\`\`\``;
+}
+function generateFeedback() {
+    return `## Feedback
+
+This is a test/evaluation project. If you encounter issues, friction, or have improvement suggestions:
+
+1. Create a file in the project root: \`feedback-YYYY-MM-DD-<model>.md\`
+   - Example: \`feedback-2026-04-07-gpt-5.md\`
+   - Example: \`feedback-2026-04-08-claude-opus.md\`
+2. Structure your feedback with:
+   - **Observations** — what happened, what you expected
+   - **Suggestions** — how to improve it
+   - **Context** — what you were trying to do when the issue occurred
+3. Do not modify existing feedback files from other models`;
+}
+export function generateStubMaadMd(enginePath, projectRoot) {
+    const cmd = buildCmdPrefix(enginePath, projectRoot);
+    return `# MAAD.md — LLM Interface
+
+> Auto-generated by the MAAD engine.
+> Run \`reindex\` after adding types and schemas to update this file.
+>
+> **This is a test/evaluation project.** If you find issues, create a feedback file:
+> \`feedback-YYYY-MM-DD-<model>.md\`
+
+This is a **MAAD project** — a markdown-native database.
+
+## Getting Started
+
+1. Define types in \`_registry/object_types.yaml\`
+2. Create schemas in \`_schema/\`
+3. Add markdown records
+4. Run: \`${cmd} reindex --force\`
+
+This file will be regenerated with full type/command reference after the first reindex.
+`;
+}
+//# sourceMappingURL=maad-md.js.map

package/dist/maad-md.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maad-md.js","sourceRoot":"","sources":["../src/maad-md.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,oBAAoB;AACpB,yDAAyD;AACzD,oEAAoE;AACpE,+DAA+D;AAC/D,+EAA+E;AAY/E,MAAM,UAAU,cAAc,CAAC,GAAkB;IAC/C,MAAM,GAAG,GAAG,cAAc,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;IAC5D,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;IACnC,QAAQ,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAC5C,QAAQ,CAAC,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,QAAQ,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACpC,QAAQ,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC;IAC/B,QAAQ,CAAC,IAAI,CAAC,2BAA2B,CAAC,GAAG,CAAC,CAAC,CAAC;IAChD,QAAQ,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAElC,OAAO,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC;AAC7C,CAAC;AAED,SAAS,cAAc,CAAC,UAAkB,EAAE,WAAmB;IAC7D,OAAO,QAAQ,UAAU,cAAc,WAAW,EAAE,CAAC;AACvD,CAAC;AAED,8EAA8E;AAE9E,SAAS,cAAc,CAAC,GAAW;IACjC,OAAO;;;;;;;;;;;;;;;;;;;;;EAqBP,GAAG;OACE,CAAC;AACR,CAAC;AAED,SAAS,kBAAkB,CAAC,GAAW,EAAE,IAAmB;IAC1D,OAAO;;;;;;EAMP,GAAG;;;;;;;;;;;;;;;;;uEAiBkE,CAAC;AACxE,CAAC;AAED,SAAS,sBAAsB,CAAC,GAAW;IACzC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yCAkEgC,CAAC;AAC1C,CAAC;AAED,SAAS,kBAAkB;IACzB,OAAO;;;;;;;;;;;;;;;;iEAgBwD,CAAC;AAClE,CAAC;AAED,SAAS,aAAa;IACpB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;sFA2B6E,CAAC;AACvF,CAAC;AAED,SAAS,2BAA2B,CAAC,GAAW;IAC9C,OAAO;;;;;;EAMP,GAAG;EACH,GAAG;EACH,GAAG;EACH,GAAG;;;;;EAKH,GAAG;;;;;EAKH,GAAG;EACH,GAAG;OACE,CAAC;AACR,CAAC;AAED,SAAS,gBAAgB;IACvB,OAAO;;;;;;;;;;;2DAWkD,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,UAAkB,EAAE,WAAmB;IACxE,MAAM,GAAG,GAAG,cAAc,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;IACpD,OAAO;;;;;;;;;;;;;;;YAeG,GAAG;;;CAGd,CAAC;AACF,CAAC"}

package/dist/mcp/bulk-cap.d.ts

@@ -0,0 +1,10 @@
+export declare function getBulkMaxItems(env?: NodeJS.ProcessEnv): number;
+export interface BulkCapRejection {
+    tool: string;
+    received: number;
+    limit: number;
+    suggestedChunkSize: number;
+    message: string;
+}
+export declare function checkBulkSize(toolName: string, count: number, env?: NodeJS.ProcessEnv): BulkCapRejection | null;
+//# sourceMappingURL=bulk-cap.d.ts.map

package/dist/mcp/bulk-cap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulk-cap.d.ts","sourceRoot":"","sources":["../../src/mcp/bulk-cap.ts"],"names":[],"mappings":"AAeA,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAO5E;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,gBAAgB,GAAG,IAAI,CAUzB"}

package/dist/mcp/bulk-cap.js

@@ -0,0 +1,37 @@
+// ============================================================================
+// Bulk-tool item-count cap (0.7.3, fup-2026-190 §1).
+//
+// Defense-in-depth flood control for maad_bulk_create / maad_bulk_update.
+// Independent of per-session write rate limits — those throttle frequency,
+// this caps per-request blast radius. Also bounds memory cost of bulk results
+// (per-record validation reports, audit events, notification fanouts).
+//
+// Default cap: 50. Configurable via MAAD_BULK_MAX_ITEMS, clamped to [1, 1000]
+// to keep the floor meaningful even under operator misconfiguration.
+// ============================================================================
+const DEFAULT_BULK_MAX = 50;
+const HARD_BULK_MAX = 1000;
+export function getBulkMaxItems(env = process.env) {
+    const raw = env.MAAD_BULK_MAX_ITEMS;
+    if (!raw)
+        return DEFAULT_BULK_MAX;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 1)
+        return DEFAULT_BULK_MAX;
+    if (n > HARD_BULK_MAX)
+        return HARD_BULK_MAX;
+    return n;
+}
+export function checkBulkSize(toolName, count, env = process.env) {
+    const max = getBulkMaxItems(env);
+    if (count <= max)
+        return null;
+    return {
+        tool: toolName,
+        received: count,
+        limit: max,
+        suggestedChunkSize: max,
+        message: `${toolName} accepts at most ${max} items per call (received ${count}). Split into chunks of <= ${max}.`,
+    };
+}
+//# sourceMappingURL=bulk-cap.js.map

package/dist/mcp/bulk-cap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulk-cap.js","sourceRoot":"","sources":["../../src/mcp/bulk-cap.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,qDAAqD;AACrD,EAAE;AACF,0EAA0E;AAC1E,2EAA2E;AAC3E,8EAA8E;AAC9E,uEAAuE;AACvE,EAAE;AACF,8EAA8E;AAC9E,qEAAqE;AACrE,+EAA+E;AAE/E,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAC5B,MAAM,aAAa,GAAG,IAAI,CAAC;AAE3B,MAAM,UAAU,eAAe,CAAC,MAAyB,OAAO,CAAC,GAAG;IAClE,MAAM,GAAG,GAAG,GAAG,CAAC,mBAAmB,CAAC;IACpC,IAAI,CAAC,GAAG;QAAE,OAAO,gBAAgB,CAAC;IAClC,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACnC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,gBAAgB,CAAC;IAC1D,IAAI,CAAC,GAAG,aAAa;QAAE,OAAO,aAAa,CAAC;IAC5C,OAAO,CAAC,CAAC;AACX,CAAC;AAUD,MAAM,UAAU,aAAa,CAC3B,QAAgB,EAChB,KAAa,EACb,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,GAAG,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,KAAK,IAAI,GAAG;QAAE,OAAO,IAAI,CAAC;IAC9B,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,KAAK;QACf,KAAK,EAAE,GAAG;QACV,kBAAkB,EAAE,GAAG;QACvB,OAAO,EAAE,GAAG,QAAQ,oBAAoB,GAAG,6BAA6B,KAAK,8BAA8B,GAAG,GAAG;KAClH,CAAC;AACJ,CAAC"}

package/dist/mcp/config.d.ts

@@ -0,0 +1,18 @@
+import { type Role } from './roles.js';
+export type ProvenanceMode = 'off' | 'on' | 'detail';
+export interface McpConfig {
+    projectRoot: string;
+    role: Role;
+    dryRun: boolean;
+    toolAllowlist: string[];
+    provenance: ProvenanceMode;
+}
+export declare function parseProvenance(raw: string | undefined): ProvenanceMode;
+export declare function buildConfig(opts: {
+    projectRoot: string;
+    role?: string | undefined;
+    dryRun?: boolean | undefined;
+    toolAllowlist?: string[] | undefined;
+    provenance?: string | undefined;
+}): McpConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/mcp/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/mcp/config.ts"],"names":[],"mappings":"AAKA,OAAO,EAAa,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,IAAI,GAAG,QAAQ,CAAC;AAErD,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,cAAc,CAAC;CAC5B;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,CAGvE;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACrC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC,GAAG,SAAS,CAQZ"}

package/dist/mcp/config.js

@@ -0,0 +1,20 @@
+// ============================================================================
+// MCP Config — runtime configuration for the server
+// Single source of truth for project root, role, flags.
+// ============================================================================
+import { parseRole } from './roles.js';
+export function parseProvenance(raw) {
+    if (raw === 'on' || raw === 'detail')
+        return raw;
+    return 'off';
+}
+export function buildConfig(opts) {
+    return {
+        projectRoot: opts.projectRoot,
+        role: parseRole(opts.role),
+        dryRun: opts.dryRun ?? false,
+        toolAllowlist: opts.toolAllowlist ?? [],
+        provenance: parseProvenance(opts.provenance),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/mcp/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/mcp/config.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,oDAAoD;AACpD,wDAAwD;AACxD,+EAA+E;AAE/E,OAAO,EAAE,SAAS,EAAa,MAAM,YAAY,CAAC;AAYlD,MAAM,UAAU,eAAe,CAAC,GAAuB;IACrD,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC;IACjD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAM3B;IACC,OAAO;QACL,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;QAC1B,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,KAAK;QAC5B,aAAa,EAAE,IAAI,CAAC,aAAa,IAAI,EAAE;QACvC,UAAU,EAAE,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC;KAC7C,CAAC;AACJ,CAAC"}

package/dist/mcp/ctx.d.ts

@@ -0,0 +1,17 @@
+import type { EnginePool } from '../instance/pool.js';
+import type { SessionRegistry } from '../instance/session.js';
+import type { InstanceConfig } from '../instance/config.js';
+import type { TokenStore } from '../auth/token-store.js';
+export interface InstanceCtx {
+    instance: InstanceConfig;
+    pool: EnginePool;
+    sessions: SessionRegistry;
+    /**
+     * 0.7.0 — Token registry. Populated in HTTP mode from
+     * `<instance-root>/_auth/tokens.yaml`. Null in stdio / synthetic mode
+     * (no bearer channel). Callers that only apply when a token is present
+     * (auth middleware, identity propagation) check for null.
+     */
+    tokens: TokenStore | null;
+}
+//# sourceMappingURL=ctx.d.ts.map

package/dist/mcp/ctx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ctx.d.ts","sourceRoot":"","sources":["../../src/mcp/ctx.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,cAAc,CAAC;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,eAAe,CAAC;IAC1B;;;;;OAKG;IACH,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;CAC3B"}

package/dist/mcp/ctx.js

@@ -0,0 +1,7 @@
+// ============================================================================
+// InstanceCtx — the runtime context threaded through every tool handler.
+// Holds pool + sessions so `withEngine` can resolve the correct engine
+// per call.
+// ============================================================================
+export {};
+//# sourceMappingURL=ctx.js.map

package/dist/mcp/ctx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ctx.js","sourceRoot":"","sources":["../../src/mcp/ctx.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,yEAAyE;AACzE,uEAAuE;AACvE,YAAY;AACZ,+EAA+E"}

package/dist/mcp/guardrails.d.ts

@@ -0,0 +1,42 @@
+import type { MaadError } from '../errors.js';
+export interface GuardrailConfig {
+    dryRun?: boolean | undefined;
+    toolAllowlist?: string[] | undefined;
+}
+export declare function setGuardrailConfig(c: GuardrailConfig): void;
+export declare function isDryRun(): boolean;
+export declare function isToolAllowed(toolName: string): boolean;
+/**
+ * Audit-log marker for whether a destructive call ran as dry-run or confirmed.
+ * Stamped on the audit payload via auditToolCall's `extras` argument so
+ * post-hoc audit can distinguish exploration from action.
+ */
+export type ConfirmMode = 'dry_run' | 'confirmed';
+/**
+ * Confirm-contract guard for destructive tools (0.7.10).
+ *
+ * Returns null when args.confirm === true (caller has authorized mutation),
+ * otherwise returns a CONFIRM_REQUIRED MaadError. Boolean strictness — no
+ * truthy coercion; only literal true authorizes mutation. Callers decide
+ * whether to surface the error or return a dry-run response carrying the
+ * affected set. Spec default is the dry-run path.
+ */
+export declare function requireConfirm(args: {
+    confirm?: unknown;
+}): MaadError | null;
+/**
+ * Log every tool call for audit trail. Optional `extras` lets destructive
+ * tools stamp confirm_mode (and future fields) on the audit payload without
+ * needing a separate writer.
+ */
+export declare function auditToolCall(toolName: string, args: Record<string, unknown>, extras?: Record<string, unknown>): void;
+/**
+ * Dry-run response: returns what would happen without executing.
+ */
+export declare function dryRunResponse(toolName: string, args: Record<string, unknown>): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+//# sourceMappingURL=guardrails.d.ts.map

package/dist/mcp/guardrails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrails.d.ts","sourceRoot":"","sources":["../../src/mcp/guardrails.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CACtC;AAID,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,eAAe,GAAG,IAAI,CAE3D;AAED,wBAAgB,QAAQ,IAAI,OAAO,CAElC;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,WAAW,CAAC;AAElD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,GAAG,IAAI,CAM5E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI,CAEN;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAYlI"}

package/dist/mcp/guardrails.js

@@ -0,0 +1,58 @@
+// ============================================================================
+// AI Guardrails — tool allowlists, dry-run, audit logging
+// ============================================================================
+import { logger } from '../engine/logger.js';
+let config = {};
+export function setGuardrailConfig(c) {
+    config = c;
+}
+export function isDryRun() {
+    return config.dryRun ?? false;
+}
+export function isToolAllowed(toolName) {
+    if (!config.toolAllowlist || config.toolAllowlist.length === 0)
+        return true;
+    return config.toolAllowlist.includes(toolName);
+}
+/**
+ * Confirm-contract guard for destructive tools (0.7.10).
+ *
+ * Returns null when args.confirm === true (caller has authorized mutation),
+ * otherwise returns a CONFIRM_REQUIRED MaadError. Boolean strictness — no
+ * truthy coercion; only literal true authorizes mutation. Callers decide
+ * whether to surface the error or return a dry-run response carrying the
+ * affected set. Spec default is the dry-run path.
+ */
+export function requireConfirm(args) {
+    if (args.confirm === true)
+        return null;
+    return {
+        code: 'CONFIRM_REQUIRED',
+        message: 'Mutation requires explicit confirm: true. Without it, the tool returns the would-affect result set without side effects.',
+    };
+}
+/**
+ * Log every tool call for audit trail. Optional `extras` lets destructive
+ * tools stamp confirm_mode (and future fields) on the audit payload without
+ * needing a separate writer.
+ */
+export function auditToolCall(toolName, args, extras) {
+    logger.info('mcp', 'tool_call', `${toolName}`, extras ? { args, ...extras } : { args });
+}
+/**
+ * Dry-run response: returns what would happen without executing.
+ */
+export function dryRunResponse(toolName, args) {
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    ok: true,
+                    dryRun: true,
+                    tool: toolName,
+                    wouldExecute: args,
+                }),
+            }],
+    };
+}
+//# sourceMappingURL=guardrails.js.map

package/dist/mcp/guardrails.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrails.js","sourceRoot":"","sources":["../../src/mcp/guardrails.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,0DAA0D;AAC1D,+EAA+E;AAE/E,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAQ7C,IAAI,MAAM,GAAoB,EAAE,CAAC;AAEjC,MAAM,UAAU,kBAAkB,CAAC,CAAkB;IACnD,MAAM,GAAG,CAAC,CAAC;AACb,CAAC;AAED,MAAM,UAAU,QAAQ;IACtB,OAAO,MAAM,CAAC,MAAM,IAAI,KAAK,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,IAAI,CAAC,MAAM,CAAC,aAAa,IAAI,MAAM,CAAC,aAAa,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5E,OAAO,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACjD,CAAC;AASD;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,IAA2B;IACxD,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO;QACL,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,0HAA0H;KACpI,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAgB,EAChB,IAA6B,EAC7B,MAAgC;IAEhC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,QAAQ,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;AAC1F,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,IAA6B;IAC5E,OAAO;QACL,OAAO,EAAE,CAAC;gBACR,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,EAAE,EAAE,IAAI;oBACR,MAAM,EAAE,IAAI;oBACZ,IAAI,EAAE,QAAQ;oBACd,YAAY,EAAE,IAAI;iBACnB,CAAC;aACH,CAAC;KACH,CAAC;AACJ,CAAC"}

package/dist/mcp/idempotency.d.ts

@@ -0,0 +1,69 @@
+export interface IdempotencyEntry {
+    response: unknown;
+    originalRequestId: string;
+    originalCompletedAt: string;
+    insertedAtMs: number;
+}
+export interface IdempotencyCacheOptions {
+    ttlMs?: number;
+    maxEntries?: number;
+    now?: () => number;
+}
+export declare class IdempotencyCache {
+    private ttlMs;
+    private maxEntries;
+    private now;
+    private entries;
+    constructor(opts?: IdempotencyCacheOptions);
+    /** Compose the cache key. Always use this — never pass raw strings. */
+    static composeKey(projectName: string, toolName: string, clientKey: string): string;
+    /**
+     * Return a cached entry if present and not expired, else null. Reinserts on
+     * hit so recent hits survive eviction.
+     */
+    get(key: string): IdempotencyEntry | null;
+    /**
+     * Store a response. Evicts the least-recently-used entry if the cap is full.
+     * Only call this for successful responses — failures must not short-circuit
+     * retries.
+     */
+    put(key: string, entry: Omit<IdempotencyEntry, 'insertedAtMs'>): void;
+    size(): number;
+    clear(): void;
+}
+/** Replace the singleton cache — called once from server startup with env-derived config. */
+export declare function initIdempotencyCache(opts: IdempotencyCacheOptions): void;
+/** Access the current singleton. Never returns null. */
+export declare function getIdempotencyCache(): IdempotencyCache;
+export declare function readIdempotencyEnv(): IdempotencyCacheOptions;
+export type McpToolResponse = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+/**
+ * Returns true if the response body (parsed from content[0].text) has
+ * `ok: true`. Silent false on parse failure — never cache anything we can't
+ * confirm succeeded.
+ */
+export declare function isSuccessfulResponse(response: McpToolResponse): boolean;
+/**
+ * Build a replay response: identical body to the cached original, plus a fresh
+ * `_meta` envelope identifying this as a replay. Clients that ignore `_meta`
+ * see a normal successful response.
+ */
+export declare function buildReplayResponse(cached: IdempotencyEntry, currentRequestId: string): McpToolResponse;
+/**
+ * Wrapper for mutating tool handlers. If `clientKey` is provided, checks the
+ * cache for a prior completed call matching `(projectName, toolName, clientKey)`.
+ * On hit: returns the cached response with fresh replay metadata.
+ * On miss: runs `fn()`, caches if successful, returns the result.
+ *
+ * `currentRequestId` is the request ID for this specific call (used both for
+ * _meta on replays and as `originalRequestId` when caching a fresh response).
+ * H6 will supply a real request ID from the MCP wrapper; for now callers can
+ * pass `crypto.randomUUID()` to satisfy the signature.
+ */
+export declare function withIdempotency(projectName: string, toolName: string, clientKey: string | undefined, currentRequestId: string, fn: () => Promise<McpToolResponse>): Promise<McpToolResponse>;
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/mcp/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../../src/mcp/idempotency.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAKD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,GAAG,CAAe;IAG1B,OAAO,CAAC,OAAO,CAAuC;gBAE1C,IAAI,GAAE,uBAA4B;IAM9C,uEAAuE;IACvE,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAInF;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;IAezC;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,cAAc,CAAC,GAAG,IAAI;IAcrE,IAAI,IAAI,MAAM;IAId,KAAK,IAAI,IAAI;CAGd;AAMD,6FAA6F;AAC7F,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,uBAAuB,GAAG,IAAI,CAExE;AAED,wDAAwD;AACxD,wBAAgB,mBAAmB,IAAI,gBAAgB,CAEtD;AAID,wBAAgB,kBAAkB,IAAI,uBAAuB,CAO5D;AAID,MAAM,MAAM,eAAe,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC;AAEjF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CASvE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,gBAAgB,EACxB,gBAAgB,EAAE,MAAM,GACvB,eAAe,CAkBjB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,gBAAgB,EAAE,MAAM,EACxB,EAAE,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,GACjC,OAAO,CAAC,eAAe,CAAC,CAkB1B"}