@martinloop/mcp 0.3.9 → 0.5.0

package/dist/vendor/core/context-handoff.js

@@ -0,0 +1,167 @@
+/**
+ * Context Handoff Verifier — A-CTX-2
+ *
+ * Pure functions for verifying upstream-to-downstream context handoffs and
+ * deciding whether to circuit-break before the downstream agent executes.
+ *
+ * Standing rules:
+ *   - These functions are pure and side-effect-free.
+ *   - verifyContextHandoff fails closed — any ambiguity → not ok.
+ *   - decideContextCircuitBreak is the sole gate before adapter execution.
+ *   - The downstream adapter MUST NOT be called when shouldStop is true.
+ */
+import { HANDOFF_SCHEMA_VERSION } from "../contracts/index.js";
+// ─── Supported schema versions ────────────────────────────────────────────────
+const SUPPORTED_SCHEMAS = new Set([HANDOFF_SCHEMA_VERSION]);
+/**
+ * Deterministically verifies a context handoff.
+ *
+ * Returns ok=false when ANY of the following is true:
+ *   - schemaVersion is not in SUPPORTED_SCHEMAS
+ *   - producerReceiptVerified is false
+ *   - upstreamIntegrity is not "verified"
+ *   - a required artifact is absent from availableArtifacts
+ *   - an artifact sha256 does not appear in availableArtifacts (hash changed)
+ *   - any required claim has state "unverified" or "rejected"
+ *   - any claim has state "unknown"
+ *   - unresolvedAssumptions is non-empty
+ *   - handoffId, chainId, producerRunId, or producerReceiptHash is blank
+ */
+export function verifyContextHandoff(input) {
+    const { handoff, producerReceiptVerified, availableArtifacts } = input;
+    const reasons = [];
+    // ── Schema ──────────────────────────────────────────────────────────────────
+    if (!SUPPORTED_SCHEMAS.has(handoff.schemaVersion)) {
+        return {
+            ok: false,
+            integrity: "unsupported_schema",
+            reasons: [
+                {
+                    code: "unsupported_schema",
+                    message: `Handoff schemaVersion "${handoff.schemaVersion}" is not supported. Supported: ${[...SUPPORTED_SCHEMAS].join(", ")}.`
+                }
+            ]
+        };
+    }
+    // ── Required identity fields ─────────────────────────────────────────────────
+    if (!isPresent(handoff.handoffId)) {
+        reasons.push({ code: "missing_handoff_id", message: "handoffId is required." });
+    }
+    if (!isPresent(handoff.chainId)) {
+        reasons.push({ code: "missing_chain_id", message: "chainId is required." });
+    }
+    if (!isPresent(handoff.producerRunId)) {
+        reasons.push({ code: "missing_producer_run_id", message: "producerRunId is required." });
+    }
+    if (!isPresent(handoff.producerReceiptHash)) {
+        reasons.push({ code: "missing_producer_receipt_hash", message: "producerReceiptHash is required." });
+    }
+    // ── Producer receipt verification ────────────────────────────────────────────
+    if (!producerReceiptVerified) {
+        reasons.push({
+            code: "producer_receipt_unverified",
+            message: "The producer receipt hash could not be independently verified."
+        });
+    }
+    // ── Upstream integrity propagation ───────────────────────────────────────────
+    if (handoff.upstreamIntegrity !== "verified") {
+        reasons.push({
+            code: `upstream_integrity_${handoff.upstreamIntegrity}`,
+            message: `Upstream integrity is "${handoff.upstreamIntegrity}" — cannot proceed.`
+        });
+    }
+    // ── Artifact verification ────────────────────────────────────────────────────
+    for (const artifact of handoff.artifacts) {
+        const present = availableArtifacts.has(artifact.sha256);
+        if (artifact.required && !present) {
+            reasons.push({
+                code: "missing_required_artifact",
+                message: `Required artifact is absent (sha256: ${artifact.sha256}${artifact.label ? `, label: ${artifact.label}` : ""}).`,
+                artifactSha256: artifact.sha256
+            });
+        }
+        else if (!present) {
+            reasons.push({
+                code: "artifact_hash_mismatch",
+                message: `Artifact hash not found in available set (sha256: ${artifact.sha256}${artifact.label ? `, label: ${artifact.label}` : ""}).`,
+                artifactSha256: artifact.sha256
+            });
+        }
+    }
+    // ── Claim verification ────────────────────────────────────────────────────────
+    for (const claim of handoff.claims) {
+        if (claim.verificationState === "rejected") {
+            reasons.push({
+                code: "claim_rejected",
+                message: `Claim "${claim.claimId}" was rejected: ${claim.statement}`,
+                claimId: claim.claimId
+            });
+        }
+        else if (claim.verificationState === "unverified") {
+            reasons.push({
+                code: "claim_unverified",
+                message: `Claim "${claim.claimId}" is unverified: ${claim.statement}`,
+                claimId: claim.claimId
+            });
+        }
+        else if (claim.verificationState === "unknown") {
+            reasons.push({
+                code: "claim_unknown",
+                message: `Claim "${claim.claimId}" has unknown verification state: ${claim.statement}`,
+                claimId: claim.claimId
+            });
+        }
+    }
+    // ── Unresolved assumptions ────────────────────────────────────────────────────
+    if (handoff.unresolvedAssumptions.length > 0) {
+        reasons.push({
+            code: "unresolved_assumptions",
+            message: `${handoff.unresolvedAssumptions.length} assumption(s) remain unresolved: ${handoff.unresolvedAssumptions.slice(0, 3).join("; ")}${handoff.unresolvedAssumptions.length > 3 ? " …" : ""}`
+        });
+    }
+    const ok = reasons.length === 0;
+    const integrity = ok ? "verified" : deriveIntegrity(handoff, reasons);
+    return { ok, integrity, reasons };
+}
+// ─── Circuit breaker ──────────────────────────────────────────────────────────
+/**
+ * Converts a ContextHandoffVerification into a gate decision.
+ *
+ * Healthy:  { shouldStop: false, silent: true }
+ * Broken:   { shouldStop: true, silent: false, reasonCode, message, nextAction }
+ */
+export function decideContextCircuitBreak(verification) {
+    if (verification.ok) {
+        return {
+            shouldStop: false,
+            silent: true,
+            verification
+        };
+    }
+    const first = verification.reasons[0];
+    return {
+        shouldStop: true,
+        silent: false,
+        verification,
+        reasonCode: first?.code ?? "handoff_verification_failed",
+        message: first?.message ?? "Context handoff verification failed.",
+        nextAction: "Repair or replace the upstream handoff receipt, then retry."
+    };
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function isPresent(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function deriveIntegrity(handoff, reasons) {
+    const codes = reasons.map((r) => r.code);
+    if (codes.includes("unsupported_schema"))
+        return "unsupported_schema";
+    if (codes.some((c) => c === "upstream_integrity_tamper_detected" ||
+        c === "artifact_hash_mismatch")) {
+        return "tamper_detected";
+    }
+    if (codes.includes("producer_receipt_unverified") || codes.includes("upstream_integrity_evidence_boundary")) {
+        return "evidence_boundary";
+    }
+    return "incomplete";
+}

package/dist/vendor/core/context-shadow.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Context Shadow Compiler — A-CTX-0
+ *
+ * Deterministic shadow manifest emitter. Observes the compiled prompt and
+ * records what a context-aware selector would have chosen, without altering
+ * the actual provider input in any way.
+ *
+ * Invariants:
+ *   - nowMs is always a captured input; Date.now() is never called internally
+ *   - No source text appears in any output type
+ *   - Required segments are always preferred first
+ *   - required-over-budget is recorded, never thrown
+ *   - Manifest hash covers metadata only (no content)
+ */
+import type { ContextC5EnvelopeV1, ContextEvidence, ContextShadowManifestV1 } from "../contracts/index.js";
+export interface ContextShadowSegment {
+    segmentId: string;
+    kind: string;
+    required: boolean;
+    text: string;
+}
+export interface CompileContextShadowInput {
+    runId: string;
+    taskId?: string;
+    adapter: string;
+    model?: string;
+    /** Milliseconds since epoch — must be explicit. Never call Date.now() here. */
+    nowMs: number;
+    shadowBudgetTokens: number;
+    modelWindowTokens?: number;
+    modelWindowEvidence?: ContextEvidence;
+    segments: readonly ContextShadowSegment[];
+}
+export interface CompileContextShadowResult {
+    manifest: ContextShadowManifestV1;
+    receipt: ContextC5EnvelopeV1;
+}
+export declare function estimateContextTokens(text: string): number;
+export declare function compileContextShadow(input: CompileContextShadowInput): CompileContextShadowResult;

package/dist/vendor/core/context-shadow.js

@@ -0,0 +1,200 @@
+/**
+ * Context Shadow Compiler — A-CTX-0
+ *
+ * Deterministic shadow manifest emitter. Observes the compiled prompt and
+ * records what a context-aware selector would have chosen, without altering
+ * the actual provider input in any way.
+ *
+ * Invariants:
+ *   - nowMs is always a captured input; Date.now() is never called internally
+ *   - No source text appears in any output type
+ *   - Required segments are always preferred first
+ *   - required-over-budget is recorded, never thrown
+ *   - Manifest hash covers metadata only (no content)
+ */
+import { createHash } from "node:crypto";
+import { CONTEXT_SHADOW_MANIFEST_VERSION, CONTEXT_C5_VERSION } from "../contracts/index.js";
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function sha256(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function canonicalize(value) {
+    if (Array.isArray(value)) {
+        return value.map(canonicalize);
+    }
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => [k, canonicalize(v)]));
+    }
+    return value;
+}
+function canonicalJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+export function estimateContextTokens(text) {
+    if (text.length === 0)
+        return 0;
+    return Math.max(1, Math.ceil(Buffer.byteLength(text, "utf8") / 4));
+}
+// ─── Compiler ────────────────────────────────────────────────────────────────
+export function compileContextShadow(input) {
+    const { runId, adapter, nowMs, shadowBudgetTokens, segments } = input;
+    // Validate: all segmentIds must be non-empty and unique
+    const seen = new Set();
+    for (const seg of segments) {
+        if (!seg.segmentId || seg.segmentId.trim() === "") {
+            throw new Error("compileContextShadow: segmentId must be non-empty");
+        }
+        if (seen.has(seg.segmentId)) {
+            throw new Error(`compileContextShadow: duplicate segmentId "${seg.segmentId}"`);
+        }
+        seen.add(seg.segmentId);
+    }
+    // Hash each segment's content — never expose the text itself
+    const hashed = segments.map((seg) => ({
+        segmentId: seg.segmentId,
+        kind: seg.kind,
+        required: seg.required,
+        contentHash: sha256(seg.text),
+        estimatedTokens: estimateContextTokens(seg.text)
+    }));
+    // Compute actualPromptHash from all segments in original order
+    const actualPromptHash = sha256(canonicalJson(hashed.map((h) => ({ segmentId: h.segmentId, contentHash: h.contentHash }))));
+    const actualEstimatedTokens = hashed.reduce((sum, h) => sum + h.estimatedTokens, 0);
+    // Compute compilerInputHash — includes nowMs for cross-run determinism
+    const compilerInputHash = sha256(canonicalJson({
+        adapter,
+        nowMs,
+        segments: hashed.map((h) => ({
+            segmentId: h.segmentId,
+            kind: h.kind,
+            required: h.required,
+            contentHash: h.contentHash,
+            estimatedTokens: h.estimatedTokens
+        })),
+        shadowBudgetTokens,
+        ...(input.taskId === undefined ? {} : { taskId: input.taskId }),
+        ...(input.model === undefined ? {} : { model: input.model })
+    }));
+    // Shadow selection: required first (in original order), then optional
+    const required = hashed.filter((h) => h.required);
+    const optional = hashed.filter((h) => !h.required);
+    let remaining = shadowBudgetTokens;
+    const decisions = [];
+    // Required segments — always included even if over budget
+    let requiredOverBudget = false;
+    const requiredTokens = required.reduce((s, h) => s + h.estimatedTokens, 0);
+    if (requiredTokens > shadowBudgetTokens) {
+        requiredOverBudget = true;
+    }
+    for (const h of required) {
+        const included = !requiredOverBudget;
+        decisions.push({
+            segmentId: h.segmentId,
+            kind: h.kind,
+            contentHash: h.contentHash,
+            estimatedTokens: h.estimatedTokens,
+            actuallyIncluded: true,
+            proposedDecision: included ? "included" : "excluded",
+            reason: requiredOverBudget ? "required_over_budget" : "required"
+        });
+        if (!requiredOverBudget) {
+            remaining -= h.estimatedTokens;
+        }
+    }
+    // Optional segments — include while budget remains
+    for (const h of optional) {
+        if (h.estimatedTokens <= remaining) {
+            decisions.push({
+                segmentId: h.segmentId,
+                kind: h.kind,
+                contentHash: h.contentHash,
+                estimatedTokens: h.estimatedTokens,
+                actuallyIncluded: true,
+                proposedDecision: "included",
+                reason: "within_shadow_budget"
+            });
+            remaining -= h.estimatedTokens;
+        }
+        else {
+            decisions.push({
+                segmentId: h.segmentId,
+                kind: h.kind,
+                contentHash: h.contentHash,
+                estimatedTokens: h.estimatedTokens,
+                actuallyIncluded: true,
+                proposedDecision: "excluded",
+                reason: "shadow_budget_exhausted"
+            });
+        }
+    }
+    // Restore original segment order in decisions list
+    const orderMap = new Map(segments.map((s, i) => [s.segmentId, i]));
+    decisions.sort((a, b) => (orderMap.get(a.segmentId) ?? 0) - (orderMap.get(b.segmentId) ?? 0));
+    const proposedEstimatedTokens = decisions
+        .filter((d) => d.proposedDecision === "included")
+        .reduce((s, d) => s + d.estimatedTokens, 0);
+    const capturedAt = new Date(nowMs).toISOString();
+    const manifestId = sha256(`${runId}:${compilerInputHash}:${capturedAt}`);
+    // Manifest hash covers metadata only — no content
+    const manifestHashInput = canonicalJson({
+        adapter,
+        capturedAt,
+        compilerInputHash,
+        manifestId,
+        mode: "shadow",
+        modelWindowEvidence: input.modelWindowEvidence ?? "unknown",
+        modelWindowTokens: input.modelWindowTokens ?? null,
+        requiredOverBudget,
+        runId,
+        shadowBudgetTokens,
+        ...(input.taskId === undefined ? {} : { taskId: input.taskId }),
+        ...(input.model === undefined ? {} : { model: input.model })
+    });
+    const manifestHash = sha256(manifestHashInput);
+    const includedCount = decisions.filter((d) => d.proposedDecision === "included").length;
+    const excludedCount = decisions.filter((d) => d.proposedDecision === "excluded").length;
+    const manifest = {
+        schemaVersion: CONTEXT_SHADOW_MANIFEST_VERSION,
+        manifestId,
+        manifestHash,
+        compilerInputHash,
+        runId,
+        adapter,
+        capturedAt,
+        mode: "shadow",
+        modelWindowTokens: input.modelWindowTokens ?? null,
+        modelWindowEvidence: input.modelWindowEvidence ?? "unknown",
+        shadowBudgetTokens,
+        actualPromptHash,
+        actualEstimatedTokens,
+        proposedEstimatedTokens,
+        requiredOverBudget,
+        decisions,
+        ...(input.taskId === undefined ? {} : { taskId: input.taskId }),
+        ...(input.model === undefined ? {} : { model: input.model })
+    };
+    const receipt = {
+        schemaVersion: CONTEXT_C5_VERSION,
+        resource: "context",
+        event: "shadow_compiled",
+        runId,
+        manifestId,
+        manifestHash,
+        mode: "shadow",
+        adapter,
+        actualEstimatedTokens,
+        proposedEstimatedTokens,
+        candidateCount: decisions.length,
+        includedCount,
+        excludedCount,
+        requiredOverBudget,
+        modelWindowTokens: input.modelWindowTokens ?? null,
+        modelWindowEvidence: input.modelWindowEvidence ?? "unknown",
+        createdAt: capturedAt,
+        ...(input.taskId === undefined ? {} : { taskId: input.taskId }),
+        ...(input.model === undefined ? {} : { model: input.model })
+    };
+    return { manifest, receipt };
+}

package/dist/vendor/core/delivery/index.d.ts

@@ -0,0 +1,6 @@
+export { fetchSelectedMessage } from "./message-client.js";
+export type { MessageClientOptions, MessageSelectRequest } from "./message-client.js";
+export { cacheMessage, isCooldownExpired, isDismissed, loadDeliveryRecord, recordDismissed, recordShown, resolveDefaultLedgerPath, saveDeliveryRecord, } from "./message-ledger.js";
+export { parseMessageSelectionResponse } from "./message-schema.js";
+export type { ParseFailure, ParseResult, ValidationError } from "./message-schema.js";
+export { getCliInstalledVersion, getMcpInstalledVersion, isNewerVersion } from "./update-check.js";

package/dist/vendor/core/delivery/index.js

@@ -0,0 +1,4 @@
+export { fetchSelectedMessage } from "./message-client.js";
+export { cacheMessage, isCooldownExpired, isDismissed, loadDeliveryRecord, recordDismissed, recordShown, resolveDefaultLedgerPath, saveDeliveryRecord, } from "./message-ledger.js";
+export { parseMessageSelectionResponse } from "./message-schema.js";
+export { getCliInstalledVersion, getMcpInstalledVersion, isNewerVersion } from "./update-check.js";

package/dist/vendor/core/delivery/message-client.d.ts

@@ -0,0 +1,18 @@
+import { type DeliveryMessage } from "../../contracts/index.js";
+export interface MessageSelectRequest {
+    installId?: string;
+    clientVersion: string;
+    clientKind: "cli" | "mcp";
+    /** Enum signal — never a transcript or raw content */
+    trigger?: "first_verified_run" | "milestone_reached" | "version_check";
+}
+export interface MessageClientOptions {
+    endpoint?: string;
+    timeoutMs?: number;
+}
+/**
+ * Fetch a server-selected message from the Control Plane.
+ * Returns null on any network failure, timeout, or validation error.
+ * Never throws — the primary command must never be affected.
+ */
+export declare function fetchSelectedMessage(request: MessageSelectRequest, options?: MessageClientOptions): Promise<DeliveryMessage | null>;

package/dist/vendor/core/delivery/message-client.js

@@ -0,0 +1,38 @@
+import { parseMessageSelectionResponse } from "./message-schema.js";
+const DEFAULT_ENDPOINT = "https://api.martinloop.com/v1/messages/select";
+const REQUEST_TIMEOUT_MS = 4_000;
+/**
+ * Fetch a server-selected message from the Control Plane.
+ * Returns null on any network failure, timeout, or validation error.
+ * Never throws — the primary command must never be affected.
+ */
+export async function fetchSelectedMessage(request, options = {}) {
+    const endpoint = options.endpoint ?? process.env["MARTIN_MESSAGE_ENDPOINT"] ?? DEFAULT_ENDPOINT;
+    const timeoutMs = options.timeoutMs ?? REQUEST_TIMEOUT_MS;
+    let controller;
+    let timeoutId;
+    try {
+        controller = new AbortController();
+        timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+        const response = await fetch(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", "Accept": "application/json" },
+            body: JSON.stringify(request),
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            return null;
+        const raw = await response.text();
+        const result = parseMessageSelectionResponse(raw);
+        if (!result.ok)
+            return null;
+        return result.message ?? null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (timeoutId !== undefined)
+            clearTimeout(timeoutId);
+    }
+}

package/dist/vendor/core/delivery/message-ledger.d.ts

@@ -0,0 +1,35 @@
+import { type DeliveryMessage, type DeliveryRecord } from "../../contracts/index.js";
+/**
+ * Load DeliveryRecord from disk. Returns empty record on any read/parse failure — never throws.
+ */
+export declare function loadDeliveryRecord(ledgerPath: string): DeliveryRecord;
+/**
+ * Persist DeliveryRecord atomically via temp-file + rename.
+ */
+export declare function saveDeliveryRecord(ledgerPath: string, record: DeliveryRecord): void;
+/**
+ * Returns true when the cooldown period has elapsed and the message should be shown.
+ * Clock-skew safe: if now < lastShownAtEpochMs (clock jumped back), treat cooldown as expired.
+ */
+export declare function isCooldownExpired(record: DeliveryRecord, nowMs: number): boolean;
+/**
+ * Returns true if this message id was permanently dismissed.
+ */
+export declare function isDismissed(record: DeliveryRecord, messageId: string): boolean;
+/**
+ * Record that a message was shown. Updates cooldown window.
+ */
+export declare function recordShown(record: DeliveryRecord, message: DeliveryMessage, nowMs: number): DeliveryRecord;
+/**
+ * Record that a message was permanently dismissed.
+ */
+export declare function recordDismissed(record: DeliveryRecord, messageId: string): DeliveryRecord;
+/**
+ * Cache a fetched message for offline use.
+ */
+export declare function cacheMessage(record: DeliveryRecord, message: DeliveryMessage, nowMs: number): DeliveryRecord;
+/**
+ * Resolve the default ledger path: $MARTIN_STATE_DIR/delivery-record.json
+ * or ~/.martin/delivery-record.json.
+ */
+export declare function resolveDefaultLedgerPath(): string;

package/dist/vendor/core/delivery/message-ledger.js

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { DELIVERY_RECORD_SCHEMA_VERSION } from "../../contracts/index.js";
+const EMPTY_RECORD = {
+    schemaVersion: DELIVERY_RECORD_SCHEMA_VERSION,
+    dismissedIds: [],
+};
+/**
+ * Load DeliveryRecord from disk. Returns empty record on any read/parse failure — never throws.
+ */
+export function loadDeliveryRecord(ledgerPath) {
+    try {
+        const raw = fs.readFileSync(ledgerPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            !Array.isArray(parsed) &&
+            parsed["schemaVersion"] === DELIVERY_RECORD_SCHEMA_VERSION) {
+            return parsed;
+        }
+    }
+    catch {
+        // file missing or corrupt — start fresh
+    }
+    return { ...EMPTY_RECORD, dismissedIds: [] };
+}
+/**
+ * Persist DeliveryRecord atomically via temp-file + rename.
+ */
+export function saveDeliveryRecord(ledgerPath, record) {
+    const dir = path.dirname(ledgerPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = path.join(os.tmpdir(), `martin-dlv-${process.pid}-${Date.now()}.json`);
+    fs.writeFileSync(tmp, JSON.stringify(record, null, 2), "utf8");
+    fs.renameSync(tmp, ledgerPath);
+}
+/**
+ * Returns true when the cooldown period has elapsed and the message should be shown.
+ * Clock-skew safe: if now < lastShownAtEpochMs (clock jumped back), treat cooldown as expired.
+ */
+export function isCooldownExpired(record, nowMs) {
+    const until = record.cooldownUntilEpochMs;
+    if (until === undefined)
+        return true;
+    const last = record.lastShownAtEpochMs ?? 0;
+    // If clock appears to have gone backwards past last-shown, treat as expired
+    if (nowMs < last)
+        return true;
+    return nowMs >= until;
+}
+/**
+ * Returns true if this message id was permanently dismissed.
+ */
+export function isDismissed(record, messageId) {
+    return record.dismissedIds.includes(messageId);
+}
+/**
+ * Record that a message was shown. Updates cooldown window.
+ */
+export function recordShown(record, message, nowMs) {
+    return {
+        ...record,
+        lastMessageId: message.id,
+        lastShownAtEpochMs: nowMs,
+        cooldownUntilEpochMs: nowMs + message.cooldownHours * 60 * 60 * 1000,
+    };
+}
+/**
+ * Record that a message was permanently dismissed.
+ */
+export function recordDismissed(record, messageId) {
+    if (record.dismissedIds.includes(messageId))
+        return record;
+    return {
+        ...record,
+        dismissedIds: [...record.dismissedIds, messageId],
+    };
+}
+/**
+ * Cache a fetched message for offline use.
+ */
+export function cacheMessage(record, message, nowMs) {
+    return {
+        ...record,
+        cachedMessage: message,
+        cachedAtEpochMs: nowMs,
+    };
+}
+/**
+ * Resolve the default ledger path: $MARTIN_STATE_DIR/delivery-record.json
+ * or ~/.martin/delivery-record.json.
+ */
+export function resolveDefaultLedgerPath() {
+    const stateDir = process.env["MARTIN_STATE_DIR"] ?? path.join(os.homedir(), ".martin");
+    return path.join(stateDir, "delivery-record.json");
+}

package/dist/vendor/core/delivery/message-schema.d.ts

@@ -0,0 +1,16 @@
+import { type DeliveryMessage } from "../../contracts/index.js";
+export type ValidationError = "schema_version_unknown" | "schema_unknown_kind" | "schema_unknown_action_type" | "schema_invalid_id" | "schema_invalid_date" | "schema_invalid_cooldown" | "schema_url_not_https" | "schema_text_too_long" | "schema_response_too_large" | "schema_malformed";
+export interface ParseResult {
+    ok: true;
+    message: DeliveryMessage | undefined;
+}
+export interface ParseFailure {
+    ok: false;
+    error: ValidationError;
+    detail?: string;
+}
+/**
+ * Parse and validate a raw response body from the message selection endpoint.
+ * Returns ok:false on any violation — caller must render nothing and log the error.
+ */
+export declare function parseMessageSelectionResponse(raw: string): ParseResult | ParseFailure;