@mcp-index/sdk 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -3,6 +3,42 @@
 All notable changes to the TypeScript SDK. Versioning is semver (0.x: minor =
 additive feature, patch = fix). Backward-compatible additions only in 0.2.0.
 
+## [Unreleased]
+
+Staged for the next publish — `npm publish` packs the current `README.md`, so these
+ride out automatically with the next version bump (no ad-hoc republish needed).
+
+## 0.5.0 — 2026-06-09
+
+### Added
+- **Drift telemetry (M1, opt-in, OFF by default).** On a tool pin or a contract drift the
+  gate can emit one one-way signal — salted (HMAC) fingerprints of the server/tool id, the
+  contract hashes, the change type, a safety flag, an hour-rounded time, and a random install
+  id. Never a schema, argument, description, URL, or server/tool name. Enable with
+  `MCPINDEX_DRIFT_TELEMETRY=detection`; fail-open (never blocks or changes a tool call). The
+  consent string is exported as `DRIFT_TELEMETRY_NOTICE`.
+
+### Docs
+- README "What it does" now documents the default-on blast-radius grade (Tier-0a action
+  classification) shipped in 0.4.0, with the `MCPINDEX_ACTION_CLASSIFICATION_ENABLED=0`
+  opt-out. (0.4.0 published before the README caught up.)
+
+## 0.4.0 — 2026-06-08
+
+### Added
+- **Local Tier-0a action classification (blast radius).** The gate now COMPUTES the
+  advisory `actionClassification` block locally from the live tool definition — action
+  type, resource, side-effect, reversibility, egress, and a static autonomy ceiling —
+  instead of leaving it `null` until a hosted verdict supplied one. So the blast-radius
+  grade is on by default in the SDK, at parity with the Python `mcpindex-preflight`
+  client. Default-on; opt out with `MCPINDEX_ACTION_CLASSIFICATION_ENABLED=0`. Pure,
+  deterministic, total, and a byte-for-byte port of the Python `cse.action_class.classify`
+  (12-case cross-language golden parity test). **Advisory only** — it rides alongside the
+  decision and never moves `PROCEED`/`HOLD` (AD-1). New exports: `classifyAction`,
+  `classifyToolDef`, `actionClassificationEnabled`, and the `ActionType` /
+  `SideEffectClass` / `Reversibility` / `Egress` / `ScopeHint` / `PatternShape` /
+  `AutonomyCeiling` / `NoteClass` / `Severity` / `EvidenceRefType` enums.
+
 ## 0.3.2 — 2026-06-08
 
 ### Fixed

package/README.md

@@ -36,6 +36,11 @@ const guarded = wrap(session);   // pins each tool's contract on first use (TOFU
   on a benign change (no false alarm).
 - Postures: `Monitor` (notify + proceed) / `Guard` (default; hold dangerous) /
   `Strict` (hold any drift).
+- Grades each call's **blast radius** (Tier-0a action classification) on the verdict:
+  action type (read / write / delete / send / …), reversibility, egress, and a static
+  autonomy ceiling, computed locally from the live contract. **Advisory** — it rides
+  alongside the decision and never moves HOLD/PROCEED. On by default; opt out with
+  `MCPINDEX_ACTION_CLASSIFICATION_ENABLED=0`.
 
 ## What it is NOT
 
@@ -43,6 +48,32 @@ The verdict is a **contract-diff, not a safety oracle** — it tells you the con
 *changed* versus your pin, not that the new contract is safe. It does not "block attacks"
 or "guarantee safe." You decide what a HOLD means for your agent.
 
+## Drift telemetry (opt-in, OFF by default)
+
+The SDK can report **that** a tool's contract drifted — so mcpindex can track drift on servers
+it can't crawl itself (private / auth-gated). It is **off by default and sends nothing** unless
+you turn it on:
+
+```sh
+export MCPINDEX_DRIFT_TELEMETRY=detection   # off (default) | detection | contribute
+```
+
+When enabled, each tool you pin and each contract drift sends **one one-way signal**:
+
+- **What it sends:** salted (HMAC) fingerprints of the server/tool id, the contract hashes, the
+  change type (the fixed ChangeKind vocabulary), a safety flag, an **hour-rounded** timestamp,
+  and a random install id (a token that links one machine's signals so distinct installs can be
+  counted — not derived from you).
+- **What it NEVER sends:** tool schemas, arguments, descriptions, URLs, server/tool **names**, or
+  any of your data. The payload has no free-text field by construction, and the ingest rejects
+  anything that isn't the closed shape.
+- **Fail-open:** telemetry never blocks, slows, or changes a tool call. Losing a signal is always
+  preferred to perturbing the gate.
+
+`detection` enables the closed signal above; `contribute` is reserved for a future, separately
+opt-in richer tier (it behaves identically today). The full notice is exported as
+`DRIFT_TELEMETRY_NOTICE`. Unset the variable any time to stop.
+
 ## License
 
 PolyForm Noncommercial 1.0.0 — © Bhartis LLC. Free for noncommercial use; commercial use

package/dist/src/actionClass.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Tier 0a — the static action classifier (TS port of `cse.action_class`).
+ *
+ * Grades the *action* a tool would take (its blast radius), not just whether the
+ * tool is trustworthy. Pure, deterministic, model-free, total (never throws on
+ * hostile input). Reuses the structural risk leg (`risk.assess`) + the name-token
+ * lexicon (`lexicon.nameTokens`) and maps them into the spec's action-classification
+ * schema (action_type / resource / side-effect / reversibility / egress + a STATIC,
+ * fail-closed autonomy_ceiling).
+ *
+ * ADVISORY only: it rides ALONGSIDE the gate decision and NEVER moves PROCEED/HOLD.
+ * The `autonomy_ceiling` here is the STATIC cold-start default; the calibration-backed
+ * ceiling lives in the private moat and is structurally unreachable from the SDK.
+ *
+ * Cross-language parity: the value tables and derivation ladder mirror
+ * `corpus_eval/tooling/cse/action_class.py` byte-for-byte. Keep them in lockstep.
+ */
+import type { ActionClassification, ToolDef } from "./preflight.js";
+export declare enum ActionType {
+    READ = "read",
+    LIST = "list",
+    SEARCH = "search",
+    WRITE = "write",
+    UPDATE = "update",
+    DELETE = "delete",
+    SEND = "send",
+    EXECUTE = "execute",
+    AUTH = "auth",
+    ADMIN = "admin",
+    UNKNOWN = "unknown"
+}
+export declare enum SideEffectClass {
+    NONE = "none",
+    LOCAL_WRITE = "local-write",
+    OUTBOUND = "outbound",
+    DESTRUCTIVE = "destructive"
+}
+export declare enum Reversibility {
+    REVERSIBLE = "reversible",
+    HARD_TO_REVERSE = "hard-to-reverse",
+    IRREVERSIBLE = "irreversible"
+}
+export declare enum Egress {
+    NONE = "none",
+    INTERNAL = "internal",
+    EXTERNAL = "external"
+}
+export declare enum ScopeHint {
+    NARROW = "narrow",
+    BROAD = "broad",
+    UNBOUNDED = "unbounded"
+}
+export declare enum PatternShape {
+    LITERAL = "literal",
+    SINGLE_ARG = "single-arg",
+    GLOB = "glob",
+    WILDCARD = "wildcard",
+    TEMPLATED = "templated"
+}
+export declare enum AutonomyCeiling {
+    DISCOVERY = "discovery",
+    REVERSIBLE = "reversible",
+    NEEDS_APPROVAL = "needs-approval",
+    NEVER_UNATTENDED = "never-unattended"
+}
+export declare enum NoteClass {
+    DESTRUCTIVE_NO_UNDO_PATH = "destructive_no_undo_path",
+    ANNOTATION_CONTRADICTS_PROBE = "annotation_contradicts_probe",
+    KNOWN_CVE = "known_cve",
+    OBSERVED_EXFIL = "observed_exfil",
+    SCOPE_ESCAPE = "scope_escape"
+}
+export declare enum Severity {
+    LOW = "low",
+    MEDIUM = "medium",
+    HIGH = "high"
+}
+export declare enum EvidenceRefType {
+    PROBE = "probe",
+    SCHEMA_FLAG = "schema_flag",
+    CORPUS_CELL = "corpus_cell",
+    CVE = "cve"
+}
+/** Precedence ladder, deterministic legs only (annotations advisory-UP + verb-keyword
+ * over name). A self-declared readOnlyHint can NEVER lower a class the verb raises;
+ * destructiveHint:true floors the effective type at DELETE. No verb match -> UNKNOWN. */
+export declare function deriveActionTypes(name: string, annotations?: unknown): [ActionType[], ActionType];
+/** Static action classification (Tier 0a). Pure, deterministic, total. The
+ * autonomy_ceiling is the STATIC cold-start default (basis="static"). */
+export declare function classify(name: string, description: string, inputSchema: unknown, annotations?: unknown): ActionClassification;
+/** Tier 0a feature flag — default ON; opt out by setting the env var to a falsey
+ * string. Read at call time (not import) so a toggle takes effect without reimport. */
+export declare function actionClassificationEnabled(env?: Record<string, string | undefined>): boolean;
+/** Convenience wrapper for the gate: classify a live tool definition. Returns null
+ * when the flag is off or the definition is unusable (mirrors Python
+ * `build_action_classification`). Never throws. */
+export declare function classifyToolDef(name: string, defn: ToolDef | null, env?: Record<string, string | undefined>): ActionClassification | null;
+//# sourceMappingURL=actionClass.d.ts.map

package/dist/src/actionClass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actionClass.d.ts","sourceRoot":"","sources":["../../src/actionClass.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAIpE,oBAAY,UAAU;IACpB,IAAI,SAAS;IACb,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,KAAK,UAAU;IACf,MAAM,WAAW;IACjB,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,KAAK,UAAU;IACf,OAAO,YAAY;CACpB;AAED,oBAAY,eAAe;IACzB,IAAI,SAAS;IACb,WAAW,gBAAgB;IAC3B,QAAQ,aAAa;IACrB,WAAW,gBAAgB;CAC5B;AAED,oBAAY,aAAa;IACvB,UAAU,eAAe;IACzB,eAAe,oBAAoB;IACnC,YAAY,iBAAiB;CAC9B;AAED,oBAAY,MAAM;IAChB,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,QAAQ,aAAa;CACtB;AAED,oBAAY,SAAS;IACnB,MAAM,WAAW;IACjB,KAAK,UAAU;IACf,SAAS,cAAc;CACxB;AAED,oBAAY,YAAY;IACtB,OAAO,YAAY;IACnB,UAAU,eAAe;IACzB,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,SAAS,cAAc;CACxB;AAED,oBAAY,eAAe;IACzB,SAAS,cAAc;IACvB,UAAU,eAAe;IACzB,cAAc,mBAAmB;IACjC,gBAAgB,qBAAqB;CACtC;AAED,oBAAY,SAAS;IACnB,wBAAwB,6BAA6B;IACrD,4BAA4B,iCAAiC;IAC7D,SAAS,cAAc;IACvB,cAAc,mBAAmB;IACjC,YAAY,iBAAiB;CAC9B;AAED,oBAAY,QAAQ;IAClB,GAAG,QAAQ;IACX,MAAM,WAAW;IACjB,IAAI,SAAS;CACd;AAED,oBAAY,eAAe;IACzB,KAAK,UAAU;IACf,WAAW,gBAAgB;IAC3B,WAAW,gBAAgB;IAC3B,GAAG,QAAQ;CACZ;AAkED;;yFAEyF;AACzF,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,WAAW,GAAE,OAAc,GAC1B,CAAC,UAAU,EAAE,EAAE,UAAU,CAAC,CAc5B;AA8ID;yEACyE;AACzE,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,OAAO,EACpB,WAAW,GAAE,OAAc,GAC1B,oBAAoB,CAqBtB;AAKD;uFACuF;AACvF,wBAAgB,2BAA2B,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,OAAO,CAG1G;AAED;;mDAEmD;AACnD,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GAAG,IAAI,EACpB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACvC,oBAAoB,GAAG,IAAI,CAmB7B"}

package/dist/src/actionClass.js

@@ -0,0 +1,350 @@
+/**
+ * Tier 0a — the static action classifier (TS port of `cse.action_class`).
+ *
+ * Grades the *action* a tool would take (its blast radius), not just whether the
+ * tool is trustworthy. Pure, deterministic, model-free, total (never throws on
+ * hostile input). Reuses the structural risk leg (`risk.assess`) + the name-token
+ * lexicon (`lexicon.nameTokens`) and maps them into the spec's action-classification
+ * schema (action_type / resource / side-effect / reversibility / egress + a STATIC,
+ * fail-closed autonomy_ceiling).
+ *
+ * ADVISORY only: it rides ALONGSIDE the gate decision and NEVER moves PROCEED/HOLD.
+ * The `autonomy_ceiling` here is the STATIC cold-start default; the calibration-backed
+ * ceiling lives in the private moat and is structurally unreachable from the SDK.
+ *
+ * Cross-language parity: the value tables and derivation ladder mirror
+ * `corpus_eval/tooling/cse/action_class.py` byte-for-byte. Keep them in lockstep.
+ */
+import { assess, blastRank, BlastRadius, DomainClass } from "./risk.js";
+import { nameTokens } from "./lexicon.js";
+// ----------------------------------------------------------------------- enums
+export var ActionType;
+(function (ActionType) {
+    ActionType["READ"] = "read";
+    ActionType["LIST"] = "list";
+    ActionType["SEARCH"] = "search";
+    ActionType["WRITE"] = "write";
+    ActionType["UPDATE"] = "update";
+    ActionType["DELETE"] = "delete";
+    ActionType["SEND"] = "send";
+    ActionType["EXECUTE"] = "execute";
+    ActionType["AUTH"] = "auth";
+    ActionType["ADMIN"] = "admin";
+    ActionType["UNKNOWN"] = "unknown";
+})(ActionType || (ActionType = {}));
+export var SideEffectClass;
+(function (SideEffectClass) {
+    SideEffectClass["NONE"] = "none";
+    SideEffectClass["LOCAL_WRITE"] = "local-write";
+    SideEffectClass["OUTBOUND"] = "outbound";
+    SideEffectClass["DESTRUCTIVE"] = "destructive";
+})(SideEffectClass || (SideEffectClass = {}));
+export var Reversibility;
+(function (Reversibility) {
+    Reversibility["REVERSIBLE"] = "reversible";
+    Reversibility["HARD_TO_REVERSE"] = "hard-to-reverse";
+    Reversibility["IRREVERSIBLE"] = "irreversible";
+})(Reversibility || (Reversibility = {}));
+export var Egress;
+(function (Egress) {
+    Egress["NONE"] = "none";
+    Egress["INTERNAL"] = "internal";
+    Egress["EXTERNAL"] = "external";
+})(Egress || (Egress = {}));
+export var ScopeHint;
+(function (ScopeHint) {
+    ScopeHint["NARROW"] = "narrow";
+    ScopeHint["BROAD"] = "broad";
+    ScopeHint["UNBOUNDED"] = "unbounded";
+})(ScopeHint || (ScopeHint = {}));
+export var PatternShape;
+(function (PatternShape) {
+    PatternShape["LITERAL"] = "literal";
+    PatternShape["SINGLE_ARG"] = "single-arg";
+    PatternShape["GLOB"] = "glob";
+    PatternShape["WILDCARD"] = "wildcard";
+    PatternShape["TEMPLATED"] = "templated";
+})(PatternShape || (PatternShape = {}));
+export var AutonomyCeiling;
+(function (AutonomyCeiling) {
+    AutonomyCeiling["DISCOVERY"] = "discovery";
+    AutonomyCeiling["REVERSIBLE"] = "reversible";
+    AutonomyCeiling["NEEDS_APPROVAL"] = "needs-approval";
+    AutonomyCeiling["NEVER_UNATTENDED"] = "never-unattended";
+})(AutonomyCeiling || (AutonomyCeiling = {}));
+export var NoteClass;
+(function (NoteClass) {
+    NoteClass["DESTRUCTIVE_NO_UNDO_PATH"] = "destructive_no_undo_path";
+    NoteClass["ANNOTATION_CONTRADICTS_PROBE"] = "annotation_contradicts_probe";
+    NoteClass["KNOWN_CVE"] = "known_cve";
+    NoteClass["OBSERVED_EXFIL"] = "observed_exfil";
+    NoteClass["SCOPE_ESCAPE"] = "scope_escape";
+})(NoteClass || (NoteClass = {}));
+export var Severity;
+(function (Severity) {
+    Severity["LOW"] = "low";
+    Severity["MEDIUM"] = "medium";
+    Severity["HIGH"] = "high";
+})(Severity || (Severity = {}));
+export var EvidenceRefType;
+(function (EvidenceRefType) {
+    EvidenceRefType["PROBE"] = "probe";
+    EvidenceRefType["SCHEMA_FLAG"] = "schema_flag";
+    EvidenceRefType["CORPUS_CELL"] = "corpus_cell";
+    EvidenceRefType["CVE"] = "cve";
+})(EvidenceRefType || (EvidenceRefType = {}));
+// ------------------------------------------------------- derivation primitives
+// Verb token -> action_type. Most-destructive wins on multi-match (see DESTRUCT_RANK).
+const VERB_TO_TYPE = [
+    [ActionType.DELETE, new Set("delete remove drop destroy purge wipe truncate prune".split(" "))],
+    [ActionType.EXECUTE, new Set("exec execute run eval".split(" "))],
+    [ActionType.ADMIN, new Set("provision deploy terminate reboot scale kill".split(" "))],
+    [ActionType.AUTH, new Set("authorize grant revoke issue".split(" "))],
+    [ActionType.SEND, new Set("send post publish notify dispatch email broadcast tweet sms message".split(" "))],
+    [ActionType.WRITE, new Set("write create insert upload put".split(" "))],
+    [ActionType.UPDATE, new Set("update modify patch merge set".split(" "))],
+    [ActionType.SEARCH, new Set("search query lookup find".split(" "))],
+    [ActionType.LIST, new Set("list".split(" "))],
+    [ActionType.READ, new Set("get read fetch describe show view".split(" "))],
+];
+// Descending destructiveness — tiebreak for the "effective" action_type and the
+// fail-closed ordering. UNKNOWN is most severe (we could not classify it).
+const DESTRUCT_ORDER = [
+    ActionType.UNKNOWN,
+    ActionType.DELETE,
+    ActionType.EXECUTE,
+    ActionType.ADMIN,
+    ActionType.AUTH,
+    ActionType.SEND,
+    ActionType.WRITE,
+    ActionType.UPDATE,
+    ActionType.SEARCH,
+    ActionType.LIST,
+    ActionType.READ,
+];
+const DESTRUCT_RANK = new Map(DESTRUCT_ORDER.map((t, i) => [t, i]));
+const READ_TYPES = new Set([
+    ActionType.READ,
+    ActionType.LIST,
+    ActionType.SEARCH,
+]);
+// Defense-in-depth caps on the attacker-controlled tool name + schema.
+const MAX_NAME = 8192; // chars of name tokenized (mirrors risk MAX_TEXT)
+const MAX_PROPS = 512; // top-level schema property keys scanned before fail-closed
+function isPlainObject(x) {
+    return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+function intersects(a, b) {
+    for (const x of a)
+        if (b.has(x))
+            return true;
+    return false;
+}
+/** Read a boolean MCP annotation hint; total, fail-safe (non-object / missing /
+ * non-bool -> false). */
+function annotationBool(annotations, key) {
+    if (isPlainObject(annotations)) {
+        const v = annotations[key];
+        if (typeof v === "boolean")
+            return v;
+    }
+    return false;
+}
+/** Precedence ladder, deterministic legs only (annotations advisory-UP + verb-keyword
+ * over name). A self-declared readOnlyHint can NEVER lower a class the verb raises;
+ * destructiveHint:true floors the effective type at DELETE. No verb match -> UNKNOWN. */
+export function deriveActionTypes(name, annotations = null) {
+    const tokens = nameTokens(name.slice(0, MAX_NAME));
+    const matched = new Set();
+    for (const [t, verbs] of VERB_TO_TYPE) {
+        if (intersects(tokens, verbs))
+            matched.add(t);
+    }
+    if (annotationBool(annotations, "destructiveHint"))
+        matched.add(ActionType.DELETE);
+    if (matched.size === 0)
+        return [[ActionType.UNKNOWN], ActionType.UNKNOWN];
+    const ordered = [...matched].sort((a, b) => (DESTRUCT_RANK.get(a) ?? 0) - (DESTRUCT_RANK.get(b) ?? 0));
+    return [ordered, ordered[0]];
+}
+/** Coarse static scope/pattern shape from the schema's top-level params. Conservative:
+ * no arg values, no deep walk. Fail-closed for non-trivial / pathological schemas. */
+function scopePattern(inputSchema) {
+    if (!isPlainObject(inputSchema))
+        return [ScopeHint.BROAD, PatternShape.TEMPLATED];
+    const props = inputSchema["properties"];
+    if (!isPlainObject(props) || Object.keys(props).length === 0) {
+        return [ScopeHint.NARROW, PatternShape.LITERAL];
+    }
+    const keys = Object.keys(props);
+    if (keys.length > MAX_PROPS)
+        return [ScopeHint.UNBOUNDED, PatternShape.WILDCARD];
+    const names = new Set(keys.map((k) => k.toLowerCase()));
+    const globIsh = new Set(["glob", "pattern", "wildcard", "regex"]);
+    const multiIsh = new Set(["ids", "keys", "paths", "targets", "filters", "query"]);
+    if (intersects(names, globIsh))
+        return [ScopeHint.UNBOUNDED, PatternShape.GLOB];
+    for (const nm of names) {
+        const spec = props[nm];
+        if (isPlainObject(spec) && spec["type"] === "array") {
+            return [ScopeHint.UNBOUNDED, PatternShape.WILDCARD];
+        }
+    }
+    if (intersects(names, multiIsh))
+        return [ScopeHint.BROAD, PatternShape.WILDCARD];
+    return [ScopeHint.NARROW, PatternShape.SINGLE_ARG];
+}
+function sideEffectClass(eff, ra) {
+    if (READ_TYPES.has(eff) && ra.looksReadOnly)
+        return SideEffectClass.NONE;
+    if (eff === ActionType.DELETE || eff === ActionType.EXECUTE || eff === ActionType.ADMIN) {
+        return SideEffectClass.DESTRUCTIVE;
+    }
+    if (ra.domainClass === DomainClass.PAYMENTS)
+        return SideEffectClass.DESTRUCTIVE;
+    if (eff === ActionType.SEND || ra.domainClass === DomainClass.COMMS) {
+        return SideEffectClass.OUTBOUND;
+    }
+    if (eff === ActionType.WRITE || eff === ActionType.UPDATE || eff === ActionType.AUTH) {
+        return SideEffectClass.LOCAL_WRITE;
+    }
+    // Fallthrough: a read-NAMED tool the risk leg refused to confirm read-only, or an
+    // UNKNOWN type. Fail closed to local-write (UNKNOWN is floored to never-unattended
+    // downstream by the ceiling).
+    return SideEffectClass.LOCAL_WRITE;
+}
+function reversibility(eff, sec) {
+    if (eff === ActionType.DELETE ||
+        eff === ActionType.EXECUTE ||
+        eff === ActionType.ADMIN ||
+        eff === ActionType.AUTH) {
+        return Reversibility.IRREVERSIBLE;
+    }
+    if (sec === SideEffectClass.DESTRUCTIVE)
+        return Reversibility.IRREVERSIBLE;
+    if (sec === SideEffectClass.OUTBOUND || eff === ActionType.WRITE || eff === ActionType.UPDATE) {
+        return Reversibility.HARD_TO_REVERSE;
+    }
+    return Reversibility.REVERSIBLE;
+}
+function egressOf(eff, sec) {
+    if (sec === SideEffectClass.OUTBOUND)
+        return Egress.EXTERNAL;
+    if (READ_TYPES.has(eff) && sec === SideEffectClass.NONE)
+        return Egress.NONE;
+    return Egress.INTERNAL;
+}
+/** Cold-start fail-closed lattice. UNKNOWN / HIGH-blast-irreversible / execute ->
+ * never-unattended; then by side-effect/reversibility, fail-closed. */
+function staticCeiling(eff, sec, rev, blast) {
+    if (eff === ActionType.UNKNOWN)
+        return AutonomyCeiling.NEVER_UNATTENDED;
+    if (rev === Reversibility.IRREVERSIBLE && blastRank(blast) >= blastRank(BlastRadius.HIGH)) {
+        return AutonomyCeiling.NEVER_UNATTENDED;
+    }
+    if (eff === ActionType.EXECUTE)
+        return AutonomyCeiling.NEVER_UNATTENDED;
+    if (rev === Reversibility.IRREVERSIBLE || sec === SideEffectClass.OUTBOUND) {
+        return AutonomyCeiling.NEEDS_APPROVAL;
+    }
+    if (sec === SideEffectClass.LOCAL_WRITE || rev === Reversibility.HARD_TO_REVERSE) {
+        return AutonomyCeiling.REVERSIBLE;
+    }
+    return AutonomyCeiling.DISCOVERY;
+}
+function resourceKind(ra) {
+    return ra.domainClass !== DomainClass.UNKNOWN ? ra.domainClass : "unknown";
+}
+function evidence(ra, eff) {
+    const refs = [];
+    if (ra.nameWriteish)
+        refs.push({ ref_type: EvidenceRefType.SCHEMA_FLAG, ref_id: "name_writeish" });
+    if (ra.hasWritePayloadParam) {
+        refs.push({ ref_type: EvidenceRefType.SCHEMA_FLAG, ref_id: "write_payload_param" });
+    }
+    if (ra.requiresCredential) {
+        refs.push({ ref_type: EvidenceRefType.SCHEMA_FLAG, ref_id: "requires_credential" });
+    }
+    if (ra.domainClass !== DomainClass.UNKNOWN) {
+        refs.push({ ref_type: EvidenceRefType.SCHEMA_FLAG, ref_id: `domain.${ra.domainClass}` });
+    }
+    refs.push({ ref_type: EvidenceRefType.SCHEMA_FLAG, ref_id: `action.${eff}` });
+    return refs.slice(0, 16);
+}
+function riskNotes(eff, sec, annotations) {
+    const notes = [];
+    if (annotationBool(annotations, "readOnlyHint") && sec !== SideEffectClass.NONE) {
+        notes.push({
+            note_class: NoteClass.ANNOTATION_CONTRADICTS_PROBE,
+            severity: Severity.HIGH,
+            source: { ref_type: EvidenceRefType.SCHEMA_FLAG, ref_id: "readonly_hint_vs_writeish" },
+            provenance: "derived",
+        });
+    }
+    if (sec === SideEffectClass.DESTRUCTIVE) {
+        notes.push({
+            note_class: NoteClass.DESTRUCTIVE_NO_UNDO_PATH,
+            severity: Severity.MEDIUM,
+            source: { ref_type: EvidenceRefType.SCHEMA_FLAG, ref_id: `action.${eff}` },
+            provenance: "derived",
+        });
+    }
+    return notes;
+}
+/** Static action classification (Tier 0a). Pure, deterministic, total. The
+ * autonomy_ceiling is the STATIC cold-start default (basis="static"). */
+export function classify(name, description, inputSchema, annotations = null) {
+    const ra = assess(name, description, inputSchema);
+    const [types, eff] = deriveActionTypes(name, annotations);
+    const [scope, pattern] = scopePattern(inputSchema);
+    const sec = sideEffectClass(eff, ra);
+    const rev = reversibility(eff, sec);
+    const egress = egressOf(eff, sec);
+    const ceiling = staticCeiling(eff, sec, rev, ra.blastRadius);
+    return {
+        action_types: types,
+        effective_action_type: eff,
+        resource: { kind: resourceKind(ra), pattern, scope_hint: scope },
+        side_effect_class: sec,
+        reversibility: rev,
+        egress,
+        autonomy_ceiling: ceiling,
+        autonomy_ceiling_basis: "static",
+        known_risk_notes: riskNotes(eff, sec, annotations),
+        evidence: evidence(ra, eff),
+    };
+}
+const ACTION_CLASS_ENV = "MCPINDEX_ACTION_CLASSIFICATION_ENABLED";
+const FALSEY = new Set(["0", "false", "no", "off"]);
+/** Tier 0a feature flag — default ON; opt out by setting the env var to a falsey
+ * string. Read at call time (not import) so a toggle takes effect without reimport. */
+export function actionClassificationEnabled(env = process.env) {
+    const raw = (env[ACTION_CLASS_ENV] ?? "").trim().toLowerCase();
+    return !FALSEY.has(raw);
+}
+/** Convenience wrapper for the gate: classify a live tool definition. Returns null
+ * when the flag is off or the definition is unusable (mirrors Python
+ * `build_action_classification`). Never throws. */
+export function classifyToolDef(name, defn, env) {
+    if (!actionClassificationEnabled(env))
+        return null;
+    if (defn === null || !name)
+        return null;
+    try {
+        const d = defn;
+        const rawDesc = d["description"];
+        // Mirror Python `str(defn.get("description", ""))`: identical for the normal string
+        // case; a non-string description is malformed/hostile, so stringify its CONTENT (never
+        // "[object Object]") so embedded text is still scanned — the grade can't be suppressed by
+        // sending a non-string. Security-conservative; never fail-open to a lower blast radius.
+        const description = typeof rawDesc === "string" ? rawDesc : rawDesc == null ? "" : JSON.stringify(rawDesc);
+        // Mirror Python `schema if isinstance(schema, dict) else {}`: a tool with no (or a
+        // non-object) inputSchema grades identically here and on the server.
+        const inputSchema = isPlainObject(d["inputSchema"]) ? d["inputSchema"] : {};
+        return classify(name, description, inputSchema, d["annotations"]);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=actionClass.js.map

package/dist/src/actionClass.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actionClass.js","sourceRoot":"","sources":["../../src/actionClass.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAuB,MAAM,WAAW,CAAC;AAC7F,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,gFAAgF;AAEhF,MAAM,CAAN,IAAY,UAYX;AAZD,WAAY,UAAU;IACpB,2BAAa,CAAA;IACb,2BAAa,CAAA;IACb,+BAAiB,CAAA;IACjB,6BAAe,CAAA;IACf,+BAAiB,CAAA;IACjB,+BAAiB,CAAA;IACjB,2BAAa,CAAA;IACb,iCAAmB,CAAA;IACnB,2BAAa,CAAA;IACb,6BAAe,CAAA;IACf,iCAAmB,CAAA;AACrB,CAAC,EAZW,UAAU,KAAV,UAAU,QAYrB;AAED,MAAM,CAAN,IAAY,eAKX;AALD,WAAY,eAAe;IACzB,gCAAa,CAAA;IACb,8CAA2B,CAAA;IAC3B,wCAAqB,CAAA;IACrB,8CAA2B,CAAA;AAC7B,CAAC,EALW,eAAe,KAAf,eAAe,QAK1B;AAED,MAAM,CAAN,IAAY,aAIX;AAJD,WAAY,aAAa;IACvB,0CAAyB,CAAA;IACzB,oDAAmC,CAAA;IACnC,8CAA6B,CAAA;AAC/B,CAAC,EAJW,aAAa,KAAb,aAAa,QAIxB;AAED,MAAM,CAAN,IAAY,MAIX;AAJD,WAAY,MAAM;IAChB,uBAAa,CAAA;IACb,+BAAqB,CAAA;IACrB,+BAAqB,CAAA;AACvB,CAAC,EAJW,MAAM,KAAN,MAAM,QAIjB;AAED,MAAM,CAAN,IAAY,SAIX;AAJD,WAAY,SAAS;IACnB,8BAAiB,CAAA;IACjB,4BAAe,CAAA;IACf,oCAAuB,CAAA;AACzB,CAAC,EAJW,SAAS,KAAT,SAAS,QAIpB;AAED,MAAM,CAAN,IAAY,YAMX;AAND,WAAY,YAAY;IACtB,mCAAmB,CAAA;IACnB,yCAAyB,CAAA;IACzB,6BAAa,CAAA;IACb,qCAAqB,CAAA;IACrB,uCAAuB,CAAA;AACzB,CAAC,EANW,YAAY,KAAZ,YAAY,QAMvB;AAED,MAAM,CAAN,IAAY,eAKX;AALD,WAAY,eAAe;IACzB,0CAAuB,CAAA;IACvB,4CAAyB,CAAA;IACzB,oDAAiC,CAAA;IACjC,wDAAqC,CAAA;AACvC,CAAC,EALW,eAAe,KAAf,eAAe,QAK1B;AAED,MAAM,CAAN,IAAY,SAMX;AAND,WAAY,SAAS;IACnB,kEAAqD,CAAA;IACrD,0EAA6D,CAAA;IAC7D,oCAAuB,CAAA;IACvB,8CAAiC,CAAA;IACjC,0CAA6B,CAAA;AAC/B,CAAC,EANW,SAAS,KAAT,SAAS,QAMpB;AAED,MAAM,CAAN,IAAY,QAIX;AAJD,WAAY,QAAQ;IAClB,uBAAW,CAAA;IACX,6BAAiB,CAAA;IACjB,yBAAa,CAAA;AACf,CAAC,EAJW,QAAQ,KAAR,QAAQ,QAInB;AAED,MAAM,CAAN,IAAY,eAKX;AALD,WAAY,eAAe;IACzB,kCAAe,CAAA;IACf,8CAA2B,CAAA;IAC3B,8CAA2B,CAAA;IAC3B,8BAAW,CAAA;AACb,CAAC,EALW,eAAe,KAAf,eAAe,QAK1B;AAED,gFAAgF;AAEhF,uFAAuF;AACvF,MAAM,YAAY,GAA8D;IAC9E,CAAC,UAAU,CAAC,MAAM,EAAE,IAAI,GAAG,CAAC,sDAAsD,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/F,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,GAAG,CAAC,uBAAuB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACjE,CAAC,UAAU,CAAC,KAAK,EAAE,IAAI,GAAG,CAAC,8CAA8C,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACtF,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,8BAA8B,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACrE,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,qEAAqE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5G,CAAC,UAAU,CAAC,KAAK,EAAE,IAAI,GAAG,CAAC,gCAAgC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACxE,CAAC,UAAU,CAAC,MAAM,EAAE,IAAI,GAAG,CAAC,+BAA+B,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACxE,CAAC,UAAU,CAAC,MAAM,EAAE,IAAI,GAAG,CAAC,0BAA0B,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACnE,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7C,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,mCAAmC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;CAC3E,CAAC;AAEF,gFAAgF;AAChF,2EAA2E;AAC3E,MAAM,cAAc,GAA0B;IAC5C,UAAU,CAAC,OAAO;IAClB,UAAU,CAAC,MAAM;IACjB,UAAU,CAAC,OAAO;IAClB,UAAU,CAAC,KAAK;IAChB,UAAU,CAAC,IAAI;IACf,UAAU,CAAC,IAAI;IACf,UAAU,CAAC,KAAK;IAChB,UAAU,CAAC,MAAM;IACjB,UAAU,CAAC,MAAM;IACjB,UAAU,CAAC,IAAI;IACf,UAAU,CAAC,IAAI;CAChB,CAAC;AACF,MAAM,aAAa,GAAoC,IAAI,GAAG,CAC5D,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CACrC,CAAC;AAEF,MAAM,UAAU,GAA4B,IAAI,GAAG,CAAC;IAClD,UAAU,CAAC,IAAI;IACf,UAAU,CAAC,IAAI;IACf,UAAU,CAAC,MAAM;CAClB,CAAC,CAAC;AAEH,uEAAuE;AACvE,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,kDAAkD;AACzE,MAAM,SAAS,GAAG,GAAG,CAAC,CAAC,4DAA4D;AAEnF,SAAS,aAAa,CAAC,CAAU;IAC/B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,UAAU,CAAC,CAAsB,EAAE,CAAsB;IAChE,KAAK,MAAM,CAAC,IAAI,CAAC;QAAE,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;IAC7C,OAAO,KAAK,CAAC;AACf,CAAC;AAED;yBACyB;AACzB,SAAS,cAAc,CAAC,WAAoB,EAAE,GAAW;IACvD,IAAI,aAAa,CAAC,WAAW,CAAC,EAAE,CAAC;QAC/B,MAAM,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,OAAO,CAAC,KAAK,SAAS;YAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;yFAEyF;AACzF,MAAM,UAAU,iBAAiB,CAC/B,IAAY,EACZ,cAAuB,IAAI;IAE3B,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;IACnD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAc,CAAC;IACtC,KAAK,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,YAAY,EAAE,CAAC;QACtC,IAAI,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC;IACD,IAAI,cAAc,CAAC,WAAW,EAAE,iBAAiB,CAAC;QAAE,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IAEnF,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;IAE1E,MAAM,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAC/B,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CACpE,CAAC;IACF,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/B,CAAC;AAED;sFACsF;AACtF,SAAS,YAAY,CAAC,WAAoB;IACxC,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC;QAAE,OAAO,CAAC,SAAS,CAAC,KAAK,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IAClF,MAAM,KAAK,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC;IACxC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7D,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;IAClD,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChC,IAAI,IAAI,CAAC,MAAM,GAAG,SAAS;QAAE,OAAO,CAAC,SAAS,CAAC,SAAS,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IACjF,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;IAClE,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;IAClF,IAAI,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC;QAAE,OAAO,CAAC,SAAS,CAAC,SAAS,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC;IAChF,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC;QACvB,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,OAAO,EAAE,CAAC;YACpD,OAAO,CAAC,SAAS,CAAC,SAAS,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IACD,IAAI,UAAU,CAAC,KAAK,EAAE,QAAQ,CAAC;QAAE,OAAO,CAAC,SAAS,CAAC,KAAK,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IACjF,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE,YAAY,CAAC,UAAU,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,eAAe,CAAC,GAAe,EAAE,EAAkB;IAC1D,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,aAAa;QAAE,OAAO,eAAe,CAAC,IAAI,CAAC;IACzE,IAAI,GAAG,KAAK,UAAU,CAAC,MAAM,IAAI,GAAG,KAAK,UAAU,CAAC,OAAO,IAAI,GAAG,KAAK,UAAU,CAAC,KAAK,EAAE,CAAC;QACxF,OAAO,eAAe,CAAC,WAAW,CAAC;IACrC,CAAC;IACD,IAAI,EAAE,CAAC,WAAW,KAAK,WAAW,CAAC,QAAQ;QAAE,OAAO,eAAe,CAAC,WAAW,CAAC;IAChF,IAAI,GAAG,KAAK,UAAU,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,KAAK,WAAW,CAAC,KAAK,EAAE,CAAC;QACpE,OAAO,eAAe,CAAC,QAAQ,CAAC;IAClC,CAAC;IACD,IAAI,GAAG,KAAK,UAAU,CAAC,KAAK,IAAI,GAAG,KAAK,UAAU,CAAC,MAAM,IAAI,GAAG,KAAK,UAAU,CAAC,IAAI,EAAE,CAAC;QACrF,OAAO,eAAe,CAAC,WAAW,CAAC;IACrC,CAAC;IACD,kFAAkF;IAClF,mFAAmF;IACnF,8BAA8B;IAC9B,OAAO,eAAe,CAAC,WAAW,CAAC;AACrC,CAAC;AAED,SAAS,aAAa,CAAC,GAAe,EAAE,GAAoB;IAC1D,IACE,GAAG,KAAK,UAAU,CAAC,MAAM;QACzB,GAAG,KAAK,UAAU,CAAC,OAAO;QAC1B,GAAG,KAAK,UAAU,CAAC,KAAK;QACxB,GAAG,KAAK,UAAU,CAAC,IAAI,EACvB,CAAC;QACD,OAAO,aAAa,CAAC,YAAY,CAAC;IACpC,CAAC;IACD,IAAI,GAAG,KAAK,eAAe,CAAC,WAAW;QAAE,OAAO,aAAa,CAAC,YAAY,CAAC;IAC3E,IAAI,GAAG,KAAK,eAAe,CAAC,QAAQ,IAAI,GAAG,KAAK,UAAU,CAAC,KAAK,IAAI,GAAG,KAAK,UAAU,CAAC,MAAM,EAAE,CAAC;QAC9F,OAAO,aAAa,CAAC,eAAe,CAAC;IACvC,CAAC;IACD,OAAO,aAAa,CAAC,UAAU,CAAC;AAClC,CAAC;AAED,SAAS,QAAQ,CAAC,GAAe,EAAE,GAAoB;IACrD,IAAI,GAAG,KAAK,eAAe,CAAC,QAAQ;QAAE,OAAO,MAAM,CAAC,QAAQ,CAAC;IAC7D,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,KAAK,eAAe,CAAC,IAAI;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IAC5E,OAAO,MAAM,CAAC,QAAQ,CAAC;AACzB,CAAC;AAED;uEACuE;AACvE,SAAS,aAAa,CACpB,GAAe,EACf,GAAoB,EACpB,GAAkB,EAClB,KAAkB;IAElB,IAAI,GAAG,KAAK,UAAU,CAAC,OAAO;QAAE,OAAO,eAAe,CAAC,gBAAgB,CAAC;IACxE,IAAI,GAAG,KAAK,aAAa,CAAC,YAAY,IAAI,SAAS,CAAC,KAAK,CAAC,IAAI,SAAS,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1F,OAAO,eAAe,CAAC,gBAAgB,CAAC;IAC1C,CAAC;IACD,IAAI,GAAG,KAAK,UAAU,CAAC,OAAO;QAAE,OAAO,eAAe,CAAC,gBAAgB,CAAC;IACxE,IAAI,GAAG,KAAK,aAAa,CAAC,YAAY,IAAI,GAAG,KAAK,eAAe,CAAC,QAAQ,EAAE,CAAC;QAC3E,OAAO,eAAe,CAAC,cAAc,CAAC;IACxC,CAAC;IACD,IAAI,GAAG,KAAK,eAAe,CAAC,WAAW,IAAI,GAAG,KAAK,aAAa,CAAC,eAAe,EAAE,CAAC;QACjF,OAAO,eAAe,CAAC,UAAU,CAAC;IACpC,CAAC;IACD,OAAO,eAAe,CAAC,SAAS,CAAC;AACnC,CAAC;AAED,SAAS,YAAY,CAAC,EAAkB;IACtC,OAAO,EAAE,CAAC,WAAW,KAAK,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7E,CAAC;AAID,SAAS,QAAQ,CAAC,EAAkB,EAAE,GAAe;IACnD,MAAM,IAAI,GAAkB,EAAE,CAAC;IAC/B,IAAI,EAAE,CAAC,YAAY;QAAE,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,CAAC;IACnG,IAAI,EAAE,CAAC,oBAAoB,EAAE,CAAC;QAC5B,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC,CAAC;IACtF,CAAC;IACD,IAAI,EAAE,CAAC,kBAAkB,EAAE,CAAC;QAC1B,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC,CAAC;IACtF,CAAC;IACD,IAAI,EAAE,CAAC,WAAW,KAAK,WAAW,CAAC,OAAO,EAAE,CAAC;QAC3C,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC3F,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,GAAG,EAAE,EAAE,CAAC,CAAC;IAC9E,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC3B,CAAC;AASD,SAAS,SAAS,CAChB,GAAe,EACf,GAAoB,EACpB,WAAoB;IAEpB,MAAM,KAAK,GAAoB,EAAE,CAAC;IAClC,IAAI,cAAc,CAAC,WAAW,EAAE,cAAc,CAAC,IAAI,GAAG,KAAK,eAAe,CAAC,IAAI,EAAE,CAAC;QAChF,KAAK,CAAC,IAAI,CAAC;YACT,UAAU,EAAE,SAAS,CAAC,4BAA4B;YAClD,QAAQ,EAAE,QAAQ,CAAC,IAAI;YACvB,MAAM,EAAE,EAAE,QAAQ,EAAE,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,2BAA2B,EAAE;YACtF,UAAU,EAAE,SAAS;SACtB,CAAC,CAAC;IACL,CAAC;IACD,IAAI,GAAG,KAAK,eAAe,CAAC,WAAW,EAAE,CAAC;QACxC,KAAK,CAAC,IAAI,CAAC;YACT,UAAU,EAAE,SAAS,CAAC,wBAAwB;YAC9C,QAAQ,EAAE,QAAQ,CAAC,MAAM;YACzB,MAAM,EAAE,EAAE,QAAQ,EAAE,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,GAAG,EAAE,EAAE;YAC1E,UAAU,EAAE,SAAS;SACtB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;yEACyE;AACzE,MAAM,UAAU,QAAQ,CACtB,IAAY,EACZ,WAAmB,EACnB,WAAoB,EACpB,cAAuB,IAAI;IAE3B,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC;IAClD,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,GAAG,iBAAiB,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAC1D,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,YAAY,CAAC,WAAW,CAAC,CAAC;IACnD,MAAM,GAAG,GAAG,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACrC,MAAM,GAAG,GAAG,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACpC,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAClC,MAAM,OAAO,GAAG,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC;IAE7D,OAAO;QACL,YAAY,EAAE,KAAK;QACnB,qBAAqB,EAAE,GAAG;QAC1B,QAAQ,EAAE,EAAE,IAAI,EAAE,YAAY,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE;QAChE,iBAAiB,EAAE,GAAG;QACtB,aAAa,EAAE,GAAG;QAClB,MAAM;QACN,gBAAgB,EAAE,OAAO;QACzB,sBAAsB,EAAE,QAAQ;QAChC,gBAAgB,EAAE,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,WAAW,CAAC;QAClD,QAAQ,EAAE,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC;KAC5B,CAAC;AACJ,CAAC;AAED,MAAM,gBAAgB,GAAG,wCAAwC,CAAC;AAClE,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;AAEpD;uFACuF;AACvF,MAAM,UAAU,2BAA2B,CAAC,MAA0C,OAAO,CAAC,GAAG;IAC/F,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/D,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAC1B,CAAC;AAED;;mDAEmD;AACnD,MAAM,UAAU,eAAe,CAC7B,IAAY,EACZ,IAAoB,EACpB,GAAwC;IAExC,IAAI,CAAC,2BAA2B,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACnD,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAA+B,CAAC;QAC1C,MAAM,OAAO,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC;QACjC,oFAAoF;QACpF,uFAAuF;QACvF,0FAA0F;QAC1F,wFAAwF;QACxF,MAAM,WAAW,GACf,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACzF,mFAAmF;QACnF,qEAAqE;QACrE,MAAM,WAAW,GAAG,aAAa,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,OAAO,QAAQ,CAAC,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC;IACpE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/src/driftTelemetry.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Drift telemetry — the detection-tier emit (M1 of the usage-log drift flywheel).
+ *
+ * Opt-in (`MCPINDEX_DRIFT_TELEMETRY` ∈ {off,detection,contribute}, default off),
+ * fire-and-forget, fail-OPEN. On a TOFU pin (coverage) or a classified drift (outcome),
+ * emit a CLOSED, privacy-by-construction signal: salted fingerprints + change enums +
+ * content hashes ONLY — NEVER a schema, an argument, a URL, or a plaintext server/tool
+ * name. Mirrors the `outcomes.ts` discipline: the only thing that ever leaves the device
+ * is a safe projection built by construction, not a redaction of a richer record.
+ *
+ * PRIVACY INVARIANT (enforced by construction + the leak test): the DriftSignal has no
+ * field that can hold a raw string from the tool's schema/args/description.
+ *   - server_fp / tool_fp are HMAC-SHA256 fingerprints under a GLOBAL salt. Global salt =>
+ *     a public server_id is de-anonymizable by anyone who can guess it (ACCEPTED — public
+ *     servers are public); a private/internal server_id is unreversible (PROTECTED).
+ *   - prev_hash / new_hash are the gate's own `definition_hash` — already a SHA over the
+ *     canonical contract, public-by-design (it is what the verdict is keyed on).
+ *   - change_kinds is the closed `ChangeKind` enum vocabulary; safety_relevant is a bool.
+ *   - at_hour is coarsened to the hour (no sub-hour timing fingerprint).
+ *
+ * The emit path NEVER blocks on the network and NEVER throws: it appends to a bounded ring
+ * buffer and returns; a single unref'd timer flushes batches in the background. A flush
+ * failure DROPS the batch (no retry) — losing telemetry is always preferable to perturbing
+ * a tool call. Telemetry is a SINGLETON across every Gate (one buffer, one timer).
+ *
+ * Byte-identical fingerprints to the Python port `tooling/cse/drift_telemetry.py` — the
+ * cross-language parity test pins this.
+ */
+import type { Change } from "./schemaDiff.js";
+export type DriftMode = "off" | "detection" | "contribute";
+/** The canonical human-readable consent notice — the single source of truth for the README
+ * and the future first-run prompt (M5). Byte-identical to the Python `DRIFT_TELEMETRY_NOTICE`. */
+export declare const DRIFT_TELEMETRY_NOTICE: string;
+/** The CLOSED wire payload. Every field is a fingerprint, a content hash, a closed enum,
+ * a bool, an hour-stamp, or the opaque install id — never a raw tool string. */
+export interface DriftSignal {
+    readonly v: 1;
+    readonly event: "pin" | "drift";
+    readonly server_fp: string;
+    readonly tool_fp: string;
+    readonly prev_hash: string | null;
+    readonly new_hash: string;
+    readonly change_kinds: string[] | null;
+    readonly safety_relevant: boolean;
+    readonly at_hour: string;
+    readonly sdk: string;
+    readonly install_id: string;
+}
+export type DriftTransport = (batch: DriftSignal[]) => Promise<void>;
+/** HMAC-SHA256(GLOBAL_SALT, msg) hex, truncated to 16 bytes (32 hex chars). Byte-identical
+ * to the Python `_fingerprint`. */
+export declare function fingerprint(msg: string): string;
+export declare function serverFp(serverId: string): string;
+export declare function toolFp(serverId: string, toolName: string): string;
+/** Coarsen an ISO-8601 stamp to the hour: "2026-06-09T05:09:46.123Z" → "2026-06-09T05:00:00Z".
+ * Returns "" on any unexpected shape (never leaks sub-hour precision; never throws). Mirrors
+ * the Python `_at_hour`. */
+export declare function atHour(nowIso: string): string;
+/** Build the coverage (pin) signal. Pure — exported for the leak/parity tests. */
+export declare function buildPinSignal(serverId: string, toolName: string, definitionHash: string, nowIso: string, installId: string): DriftSignal;
+/** Build the outcome (drift) signal. Pure — exported for the leak/parity tests. The change
+ * details (path/detail strings, which CAN carry tool text) are DROPPED here by construction;
+ * only the closed `kind` enum and the `safetyRelevant` bool survive. */
+export declare function buildDriftSignal(serverId: string, toolName: string, prevHash: string, newHash: string, changes: readonly Change[], nowIso: string, installId: string): DriftSignal;
+/** The singleton emit engine. One per process; every Gate shares it. */
+declare class DriftTelemetry {
+    private buffer;
+    private timer;
+    private flushing;
+    private mode;
+    private cachedInstallId;
+    private transport;
+    private resolveMode;
+    enabled(): boolean;
+    private installId;
+    private enqueue;
+    /** Drain the buffer and POST it. Best-effort: a transport failure drops the batch with no
+     * retry (fail-open). Never throws. */
+    flush(): Promise<void>;
+    recordPin(serverId: string, toolName: string, definitionHash: string, nowIso: string): void;
+    recordDrift(serverId: string, toolName: string, prevHash: string, newHash: string, changes: readonly Change[], nowIso: string): void;
+    _setTransport(t: DriftTransport): void;
+    _reset(): void;
+    _drainForTest(): DriftSignal[];
+}
+/** Process-wide singleton. The Gate calls `driftTelemetry.recordPin/recordDrift`. */
+export declare const driftTelemetry: DriftTelemetry;
+export {};
+//# sourceMappingURL=driftTelemetry.d.ts.map

package/dist/src/driftTelemetry.d.ts.map

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