@martinloop/mcp 0.3.8 → 0.5.0

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

@@ -0,0 +1,53 @@
+/**
+ * Context Compiler — A-CTX-1
+ *
+ * Deterministic working-set selector. Given a set of ContextObject candidates,
+ * a budget, a policy, and an explicit nowMs, produces a ContextManifest whose
+ * hash is identical for identical inputs on any platform.
+ *
+ * Shadow mode: the manifest is computed and emitted but the original provider
+ * packet is returned byte-for-byte unchanged.
+ *
+ * Standing invariants:
+ *   - nowMs is ALWAYS a captured input — never Date.now() internally
+ *   - No raw source text in manifest or ledger receipt — hashes and counts only
+ *   - No confidence float, no outcome_delta — both permanently banned
+ *   - Fault budget accumulates by taskId, not runId
+ *   - required-over-budget is an explicit failure, never a silent drop
+ *   - MAX_RENDER_PASSES = 5 — hard constant
+ */
+import type { ContextBudget, ContextLedgerEntry, ContextManifest, ContextObject, ContextPolicy } from "../contracts/index.js";
+export declare const MAX_RENDER_PASSES = 5;
+/**
+ * Minimal adapter interface for token recounting.
+ * Implementations may call the provider SDK's token counter.
+ * Must not make network calls to the provider inference endpoint.
+ */
+export interface ContextAdapter {
+    readonly version: string;
+    /** Recount the actual rendered tokens for a serialized text segment. */
+    recountTokens(text: string): number;
+}
+/** Fallback adapter: char÷4 heuristic, no external calls. */
+export declare const HEURISTIC_ADAPTER: ContextAdapter;
+export interface CompileContextInput {
+    taskId: string;
+    runId: string;
+    /** Must be a captured value — never call Date.now() inside the compiler. */
+    nowMs: number;
+    candidates: readonly ContextObject[];
+    budget: ContextBudget;
+    policy: ContextPolicy;
+    adapter: ContextAdapter;
+}
+export type CompileContextOutput = {
+    ok: true;
+    manifest: ContextManifest;
+    ledgerEntry: ContextLedgerEntry;
+} | {
+    ok: false;
+    reason: "required_over_budget" | "recount_exceeded_passes";
+    manifest: null;
+    ledgerEntry: null;
+};
+export declare function compileContext(input: CompileContextInput): CompileContextOutput;

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

@@ -0,0 +1,261 @@
+/**
+ * Context Compiler — A-CTX-1
+ *
+ * Deterministic working-set selector. Given a set of ContextObject candidates,
+ * a budget, a policy, and an explicit nowMs, produces a ContextManifest whose
+ * hash is identical for identical inputs on any platform.
+ *
+ * Shadow mode: the manifest is computed and emitted but the original provider
+ * packet is returned byte-for-byte unchanged.
+ *
+ * Standing invariants:
+ *   - nowMs is ALWAYS a captured input — never Date.now() internally
+ *   - No raw source text in manifest or ledger receipt — hashes and counts only
+ *   - No confidence float, no outcome_delta — both permanently banned
+ *   - Fault budget accumulates by taskId, not runId
+ *   - required-over-budget is an explicit failure, never a silent drop
+ *   - MAX_RENDER_PASSES = 5 — hard constant
+ */
+import { createHash } from "node:crypto";
+import { CONTEXT_LEDGER_VERSION, CONTEXT_MANIFEST_VERSION } from "../contracts/index.js";
+// ─── Constants ────────────────────────────────────────────────────────────────
+export const MAX_RENDER_PASSES = 5;
+/** Fallback adapter: char÷4 heuristic, no external calls. */
+export const HEURISTIC_ADAPTER = {
+    version: "heuristic@1",
+    recountTokens: (text) => text.length === 0 ? 0 : Math.max(1, Math.ceil(Buffer.byteLength(text, "utf8") / 4))
+};
+// ─── 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));
+}
+/** Priority order for selection: required → pinned → high → normal → low */
+const PRIORITY_RANK = {
+    required: 0,
+    high: 2,
+    normal: 3,
+    low: 4
+};
+/** Pinned objects slot between required and high. */
+function selectionRank(obj) {
+    if (obj.priority === "required")
+        return 0;
+    if (obj.pinnedBy !== undefined)
+        return 1;
+    return PRIORITY_RANK[obj.priority];
+}
+// ─── Compiler ────────────────────────────────────────────────────────────────
+export function compileContext(input) {
+    const { taskId, runId, nowMs, candidates, budget, policy, adapter } = input;
+    // ── Eligibility filter — policy-denied objects become governed exclusion records ──
+    //
+    // A-CTX-2 fix: denied objects must NOT silently disappear. They enter decisions[]
+    // as "excluded" with a reason code so the exclusion is visible as governed evidence.
+    // executableContext = admittedObjects only; ledgerDecisions = admitted + excluded.
+    const policyExcluded = [];
+    const eligibleList = [];
+    for (const obj of candidates) {
+        if (policy.deniedSensitivities.includes(obj.sensitivity)) {
+            policyExcluded.push({
+                objectId: obj.id,
+                decision: "excluded",
+                reason: `sensitivity_denied:${obj.sensitivity}`
+            });
+        }
+        else if (policy.deniedTrustLevels.includes(obj.trust)) {
+            policyExcluded.push({
+                objectId: obj.id,
+                decision: "excluded",
+                reason: `trust_denied:${obj.trust}`
+            });
+        }
+        else {
+            eligibleList.push(obj);
+        }
+    }
+    const eligible = eligibleList;
+    // ── Compute compilerInputHash ────────────────────────────────────────────
+    const inputFingerprint = {
+        taskId,
+        runId,
+        nowMs,
+        adapterVersion: adapter.version,
+        policyHash: policy.policyHash,
+        budget: {
+            modelWindowTokens: budget.modelWindowTokens,
+            maxWorkingSetTokens: budget.maxWorkingSetTokens,
+            pinnedTokensMax: budget.pinnedTokensMax
+        },
+        candidateIds: eligible.map((o) => o.id).sort()
+    };
+    // ── Pinned token cap ─────────────────────────────────────────────────────
+    const pinnedTokensTotal = eligible
+        .filter((o) => o.pinnedBy !== undefined)
+        .reduce((s, o) => s + o.estimatedTokens, 0);
+    if (pinnedTokensTotal > budget.pinnedTokensMax) {
+        // Fail-closed: reject the entire batch, not individual pins
+        return { ok: false, reason: "required_over_budget", manifest: null, ledgerEntry: null };
+    }
+    // ── Sort by selection rank, then objectId as stable tie-breaker ──────────
+    const sorted = [...eligible].sort((a, b) => {
+        const rankDiff = selectionRank(a) - selectionRank(b);
+        if (rankDiff !== 0)
+            return rankDiff;
+        // Stable tie-breaker: objectId lexicographic
+        return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+    });
+    // ── Selection pass ───────────────────────────────────────────────────────
+    let remaining = budget.maxWorkingSetTokens;
+    const decisions = [];
+    let requiredOverBudget = false;
+    // Required objects total token check first
+    const requiredTokens = sorted
+        .filter((o) => o.priority === "required")
+        .reduce((s, o) => s + o.estimatedTokens, 0);
+    if (requiredTokens > remaining) {
+        requiredOverBudget = true;
+        if (policy.requiredOverBudgetAction === "fail_closed") {
+            return { ok: false, reason: "required_over_budget", manifest: null, ledgerEntry: null };
+        }
+        // explicit_escalation: record and continue — all required marked excluded
+    }
+    for (const obj of sorted) {
+        const isRequired = obj.priority === "required";
+        if (requiredOverBudget && isRequired) {
+            decisions.push({
+                objectId: obj.id,
+                decision: "excluded",
+                reason: "required_over_budget"
+            });
+            continue;
+        }
+        if (obj.estimatedTokens <= remaining) {
+            decisions.push({
+                objectId: obj.id,
+                decision: "included",
+                reason: isRequired ? "required" : obj.pinnedBy !== undefined ? "pinned" : "within_budget"
+            });
+            remaining -= obj.estimatedTokens;
+        }
+        else {
+            // Attempt truncation for required/pinned, exclude otherwise
+            if (isRequired || obj.pinnedBy !== undefined) {
+                decisions.push({
+                    objectId: obj.id,
+                    decision: "included_truncated",
+                    truncatedFromTokens: obj.estimatedTokens,
+                    reason: isRequired ? "required_truncated" : "pinned_truncated"
+                });
+                // Truncated objects consume whatever is left
+                remaining = 0;
+            }
+            else {
+                decisions.push({
+                    objectId: obj.id,
+                    decision: "excluded",
+                    reason: "budget_exhausted"
+                });
+            }
+        }
+    }
+    // ── Adapter recount (up to MAX_RENDER_PASSES) ────────────────────────────
+    const includedDecisions = decisions.filter((d) => d.decision === "included" || d.decision === "included_truncated");
+    let totalRenderedTokens = 0;
+    let renderPasses = 0;
+    let recountConverged = false;
+    const includedObjects = new Map(eligible.map((o) => [o.id, o]));
+    for (let pass = 0; pass < MAX_RENDER_PASSES; pass++) {
+        renderPasses = pass + 1;
+        let passTotal = 0;
+        for (const d of includedDecisions) {
+            const obj = includedObjects.get(d.objectId);
+            if (!obj)
+                continue;
+            // In shadow mode we use the contentHash as a proxy text for recounting
+            const recounted = adapter.recountTokens(obj.contentHash);
+            d.renderedTokens = recounted;
+            passTotal += recounted;
+        }
+        if (passTotal === totalRenderedTokens && pass > 0) {
+            recountConverged = true;
+            break;
+        }
+        totalRenderedTokens = passTotal;
+        if (pass === 0)
+            recountConverged = false;
+    }
+    if (!recountConverged && renderPasses >= MAX_RENDER_PASSES) {
+        return { ok: false, reason: "recount_exceeded_passes", manifest: null, ledgerEntry: null };
+    }
+    // ── Merge policy exclusions — excluded objects precede selection decisions ──
+    //
+    // A-CTX-2: executableContext = admittedObjects (decisions[]);
+    //          ledgerDecisions   = [...policyExcluded, ...decisions]
+    // Policy-excluded objects never enter the admitted working set, but their
+    // exclusion is visible as governed evidence in the manifest and ledger.
+    const allDecisions = [...policyExcluded, ...decisions];
+    // ── Manifest hash ────────────────────────────────────────────────────────
+    const manifestHashInput = canonicalJson({
+        adapterVersion: adapter.version,
+        budget: inputFingerprint.budget,
+        decisions: allDecisions.map((d) => ({
+            decision: d.decision,
+            objectId: d.objectId,
+            reason: d.reason,
+            ...(d.truncatedFromTokens !== undefined
+                ? { truncatedFromTokens: d.truncatedFromTokens }
+                : {})
+        })),
+        nowMs,
+        policyHash: policy.policyHash,
+        runId,
+        taskId,
+        totalRenderedTokens
+    });
+    const manifestHash = sha256(manifestHashInput);
+    const compilationDurationMs = 0; // In shadow mode: nowMs is frozen; duration is metadata-only
+    const manifest = {
+        schemaVersion: CONTEXT_MANIFEST_VERSION,
+        manifestHash,
+        taskId,
+        runId,
+        nowMs,
+        adapterVersion: adapter.version,
+        policyHash: policy.policyHash,
+        budget,
+        decisions: allDecisions,
+        totalRenderedTokens,
+        renderPasses,
+        compilationDurationMs
+    };
+    const totalIncluded = allDecisions.filter((d) => d.decision === "included" || d.decision === "included_truncated").length;
+    const totalExcluded = allDecisions.filter((d) => d.decision === "excluded").length;
+    const totalFaultLoaded = allDecisions.filter((d) => d.decision === "fault_loaded").length;
+    const ledgerEntry = {
+        schemaVersion: CONTEXT_LEDGER_VERSION,
+        entryType: "context",
+        taskId,
+        runId,
+        manifestHash,
+        totalIncluded,
+        totalExcluded,
+        totalFaultLoaded,
+        overflowCount: requiredOverBudget ? 1 : 0,
+        faultBudgetUsed: 0,
+        adapterVersion: adapter.version
+    };
+    return { ok: true, manifest, ledgerEntry };
+}

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

@@ -0,0 +1,42 @@
+/**
+ * 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 type { ContextCircuitBreakResult, ContextHandoffReceipt, ContextHandoffVerification } from "../contracts/index.js";
+export interface VerifyContextHandoffInput {
+    handoff: ContextHandoffReceipt;
+    /** true when the producer receipt file hash has been independently confirmed */
+    producerReceiptVerified: boolean;
+    /** Map of sha256 → true for every artifact hash available to the verifier */
+    availableArtifacts: ReadonlyMap<string, true>;
+}
+/**
+ * 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 declare function verifyContextHandoff(input: VerifyContextHandoffInput): ContextHandoffVerification;
+/**
+ * Converts a ContextHandoffVerification into a gate decision.
+ *
+ * Healthy:  { shouldStop: false, silent: true }
+ * Broken:   { shouldStop: true, silent: false, reasonCode, message, nextAction }
+ */
+export declare function decideContextCircuitBreak(verification: ContextHandoffVerification): ContextCircuitBreakResult;

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;