contexel 0.1.16

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mahesh Vaikri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/maheshvaikri-code/contexel/main/logo/contexel_logo.png" width="340" alt="contexel logo">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/contexel"><img src="https://img.shields.io/npm/v/contexel?label=npm" alt="npm"></a>
+  <a href="https://pypi.org/project/contexel/"><img src="https://img.shields.io/pypi/v/contexel?label=pypi" alt="PyPI"></a>
+  <a href="https://github.com/maheshvaikri-code/contexel/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT"></a>
+</p>
+
+# contexel
+
+Deterministic, dependency-free **context shaping** for code-writing agents —
+the TypeScript build of [contexel](https://github.com/maheshvaikri-code/contexel).
+
+Tool calls return verbose, duplicated, sometimes hostile data. contexel sits at
+the tool → context boundary and shapes it: select the fields that matter, drop
+duplicates, gate by provenance, quarantine injection patterns, rescore by
+relevance, truncate, rank, and trim to a token budget — every stage a pure
+function over `Record<string, unknown>[]`, every run reproducible, every drop
+attributable in an audit record.
+
+**This package is a parity port, not a re-imagining.** The Python
+implementation is canon; both languages run their test suites against the same
+golden vectors (`parity/vectors.json`, generated by Python) so that the same
+records, policy, and budget produce the same shaped output in either language.
+Versions track the Python release. Design and boundaries:
+[ADR-001](https://github.com/maheshvaikri-code/contexel/blob/main/docs/adr/001-typescript-parity.md).
+
+## Install
+
+```bash
+npm install contexel     # zero runtime dependencies, Node >= 18, ESM
+```
+
+## Sixty seconds
+
+```ts
+import { select, dedupe, rescore, truncateField, rank, trimToBudget, trace } from "contexel";
+
+const raw = await searchTool(userQuery);       // a batch of verbose results
+
+const [context, t] = trace({ idField: "url" }, () => {
+  let r = select(raw, { fields: ["title", "url", "snippet", "published"] });
+  r = dedupe(r, { key: "url" });
+  r = rescore(r, { query: userQuery, fields: ["title", "snippet"] });
+  r = truncateField(r, { field: "snippet", maxTokens: 120 });
+  r = rank(r, { by: "score", desc: true });
+  return trimToBudget(r, { maxTokens: 1500 });
+});
+
+console.log(t.report());   // per-stage: records in -> out, tokens before -> after
+console.log(t.audit());    // policy fingerprints + which stage dropped which IDs
+```
+
+Or pin the policy at the tool boundary, so the model never sees raw output:
+
+```ts
+import { shaped, stage, select, dedupe, trimToBudget } from "contexel";
+
+const searchCode = shaped([
+  stage(select, { fields: ["path", "line", "snippet"] }),
+  stage(dedupe, { key: ["path", "line"] }),
+  stage(trimToBudget, { maxTokens: 2000 }),
+])(async (query: string) => repo.search(query));  // async tools are awaited, then shaped
+```
+
+## The eight stages
+
+| Stage | What it does |
+|---|---|
+| `select` | keep only the listed fields |
+| `dedupe` | drop duplicates by key or whole-record fingerprint (type-aware: `1`, `"1"`, `true` stay distinct) |
+| `allowlist` | fail-closed provenance gate — keep records whose field is in the allowed set (a missing field reads as `null`, kept only if `null` is explicitly allowed) |
+| `quarantine` | drop or flag records matching injection patterns ("ignore previous instructions", …) |
+| `rescore` | batch BM25 relevance with word-boundary matching and in-order proximity bonus |
+| `rank` | stable sort by a field; records missing the field sort last |
+| `truncateField` | cut one field to a token budget, `…` suffix |
+| `trimToBudget` | keep records until the total token budget is spent; `minRecords` guarantees the best records survive a too-small budget instead of returning `[]` |
+
+Plus `merge` for combining multiple sources under one schema, `pipeline`/`stage`
+for composition with a stable policy fingerprint, `trace`/`audit` for the
+governance record, and `tokens.scoped` for concurrency-safe (AsyncLocalStorage)
+tokenizer and serializer overrides per tenant.
+
+## Parity, precisely
+
+- Shaped output is structurally identical to Python's for JSON-safe records —
+  enforced by golden vectors covering every stage, the composed contract, the
+  audit record, canonical serialization, and token counts.
+- Token counting is per Unicode **code point** (matches Python `len`), not
+  UTF-16 units — `"café"` costs the same in both languages.
+- Documented boundaries (see ADR-001): JS collapses `1.0` to `"1"` in
+  serialization; Unicode word classes differ at the margins; pipeline
+  fingerprints are language-local in v1.
+
+## Links
+
+- Docs: <https://maheshvaikri-code.github.io/contexel/>
+- Benchmarks (methodology and limits stated): <https://github.com/maheshvaikri-code/contexel/blob/main/benchmarks/COMPARISON.md>
+- Python package: <https://pypi.org/project/contexel/>
+- License: MIT

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * contexel — deterministic, dependency-free context shaping for
+ * code-writing agents. TypeScript parity of the Python package, enforced
+ * by shared golden vectors (see the repo's parity/ directory and ADR-001).
+ */
+export { select, dedupe, allowlist, quarantine, rescore, rank, truncateField, trimToBudget, merge, type Rec, type Records, } from "./stages.js";
+export { pipeline, stage, type StageFn } from "./pipeline.js";
+export { shaped } from "./shaped.js";
+export { trace, currentTrace, Trace, type Entry } from "./trace.js";
+export * as tokens from "./tokens.js";
+export declare const VERSION = "0.1.16";

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * contexel — deterministic, dependency-free context shaping for
+ * code-writing agents. TypeScript parity of the Python package, enforced
+ * by shared golden vectors (see the repo's parity/ directory and ADR-001).
+ */
+export { select, dedupe, allowlist, quarantine, rescore, rank, truncateField, trimToBudget, merge, } from "./stages.js";
+export { pipeline, stage } from "./pipeline.js";
+export { shaped } from "./shaped.js";
+export { trace, currentTrace, Trace } from "./trace.js";
+export * as tokens from "./tokens.js";
+export const VERSION = "0.1.16";

package/dist/pipeline.d.ts

@@ -0,0 +1,11 @@
+import type { Records } from "./stages.js";
+export type StageFn = (records: Records) => Records;
+interface Described extends StageFn {
+    __contexelDesc?: string;
+    fingerprint?: string;
+}
+/** Bind params to a stage so it slots into a pipeline as `records => records`. */
+export declare function stage<P>(fn: (records: Records, params: P) => Records, params: P): StageFn;
+/** Compose stages left-to-right; the callable exposes `.fingerprint`. */
+export declare function pipeline(stages: StageFn[]): Described;
+export {};

package/dist/pipeline.js

@@ -0,0 +1,50 @@
+/**
+ * In-language composition — parity port. Any `records => records` callable
+ * is a valid stage. Pipelines carry a stable, address-free fingerprint
+ * (language-local in v1 per ADR-001) recorded into any active trace.
+ */
+import { createHash } from "node:crypto";
+import { currentTrace } from "./trace.js";
+function stableRepr(value) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return "[" + value.map(stableRepr).join(",") + "]";
+    if (typeof value === "function")
+        return value.name || "function";
+    if (typeof value === "object") {
+        const entries = Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+        return "{" + entries.map(([k, v]) => `${JSON.stringify(k)}:${stableRepr(v)}`).join(",") + "}";
+    }
+    return typeof value;
+}
+/** Bind params to a stage so it slots into a pipeline as `records => records`. */
+export function stage(fn, params) {
+    const run = (records) => fn(records, params);
+    Object.defineProperty(run, "name", { value: fn.name || "stage" });
+    run.__contexelDesc = `${fn.name || "stage"}(${stableRepr(params)})`;
+    return run;
+}
+/** Compose stages left-to-right; the callable exposes `.fingerprint`. */
+export function pipeline(stages) {
+    const descs = stages.map((s) => s.__contexelDesc ?? (s.name || "callable"));
+    const fingerprint = createHash("sha256")
+        .update(JSON.stringify(descs))
+        .digest("hex")
+        .slice(0, 16);
+    const run = (records) => {
+        const tr = currentTrace();
+        if (tr && !tr.policies.includes(fingerprint))
+            tr.policies.push(fingerprint);
+        let out = records;
+        for (const s of stages)
+            out = s(out);
+        return out;
+    };
+    run.fingerprint = fingerprint;
+    return run;
+}

package/dist/py.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Python-semantics helpers — the parity layer under stages/tokens/trace.
+ * Each function replicates the exact CPython behavior the canon relies on;
+ * remaining margins (exotic repr escapes, huge integers, list-vs-list
+ * comparison in sorts) are documented in ADR-001.
+ */
+/** repr(float): fixed notation for 1e-4 <= |x| < 1e16, else scientific
+ * with a sign and a two-digit exponent. JS switches at 1e-7/1e21, so
+ * String(1e-5) === "0.00001" where Python says "1e-05". */
+export declare function pyFloat(value: number): string;
+/** str() for numbers: int digits, nan/inf like Python, pyFloat otherwise.
+ * Integer-valued floats collapse to int form (ADR-001 boundary 4a). */
+export declare function pyNumber(value: number): string;
+/** repr(): containers render Python-style ({'k': 'v'}, ['a', 1]). */
+export declare function pyRepr(value: unknown): string;
+/** str(): what Python's `str(r.get(f, ""))` produces for JSON-safe values —
+ * None -> "None", True -> "True", nested containers via repr. */
+export declare function pyStr(value: unknown): string;
+/** round(x, nd) with CPython semantics: correctly rounded on the double's
+ * EXACT value, ties to even. A tie exists iff x is exactly k/2^(nd+1) with
+ * k odd (the only doubles whose decimal expansion ends in ...5 at digit
+ * nd+1); everything else is unambiguous and toFixed rounds it correctly.
+ * So 2.675 (really 2.67499...82) rounds DOWN to 2.67 like Python, while a
+ * true tie like 0.90625 -> 0.9062 goes to even. */
+export declare function pyRound(x: number, nd: number): number;
+/** Python string `<`: code-point order. JS `<` is UTF-16 order, which sorts
+ * astral characters below U+E000..U+FFFF. */
+export declare function compareCodePoints(a: string, b: string): number;
+/** Python comparison for sort keys: numbers/bools inter-compare, strings by
+ * code point, anything else raises TypeError like CPython (lists, which
+ * Python would compare element-wise, are an ADR-001 margin). */
+export declare function pyCompare(a: unknown, b: unknown): number;
+/** Membership key with Python hash/eq semantics: True == 1 == 1.0, None is
+ * its own class; dict/list/set raise TypeError (unhashable) like set(). */
+export declare function pyEqKey(value: unknown): string;
+/** Map a UTF-16 index to a code-point index (Python str positions). The
+ * common no-surrogate case is the identity, at no cost. */
+export declare function codePointIndexer(text: string): (utf16Index: number) => number;
+export declare function pyRstrip(text: string): string;

package/dist/py.js

@@ -0,0 +1,206 @@
+/**
+ * Python-semantics helpers — the parity layer under stages/tokens/trace.
+ * Each function replicates the exact CPython behavior the canon relies on;
+ * remaining margins (exotic repr escapes, huge integers, list-vs-list
+ * comparison in sorts) are documented in ADR-001.
+ */
+/** repr(float): fixed notation for 1e-4 <= |x| < 1e16, else scientific
+ * with a sign and a two-digit exponent. JS switches at 1e-7/1e21, so
+ * String(1e-5) === "0.00001" where Python says "1e-05". */
+export function pyFloat(value) {
+    const [mant, expStr] = value.toExponential().split("e");
+    const exp = parseInt(expStr, 10);
+    const neg = mant.startsWith("-");
+    const digits = mant.replace("-", "").replace(".", "");
+    let body;
+    if (exp < -4 || exp >= 16) {
+        const m = digits.length > 1 ? digits[0] + "." + digits.slice(1) : digits;
+        body = m + "e" + (exp < 0 ? "-" : "+") + String(Math.abs(exp)).padStart(2, "0");
+    }
+    else if (exp >= 0) {
+        body = digits.slice(0, exp + 1).padEnd(exp + 1, "0") + "." + (digits.slice(exp + 1) || "0");
+    }
+    else {
+        body = "0." + "0".repeat(-exp - 1) + digits;
+    }
+    return neg ? "-" + body : body;
+}
+/** str() for numbers: int digits, nan/inf like Python, pyFloat otherwise.
+ * Integer-valued floats collapse to int form (ADR-001 boundary 4a). */
+export function pyNumber(value) {
+    if (Number.isNaN(value))
+        return "nan";
+    if (!Number.isFinite(value))
+        return value > 0 ? "inf" : "-inf";
+    if (Number.isInteger(value))
+        return String(value);
+    return pyFloat(value);
+}
+function pyTypeName(value) {
+    if (value === null || value === undefined)
+        return "NoneType";
+    if (Array.isArray(value))
+        return "list";
+    if (value instanceof Set)
+        return "set";
+    switch (typeof value) {
+        case "boolean": return "bool";
+        case "number": return Number.isInteger(value) ? "int" : "float";
+        case "string": return "str";
+        case "object": return "dict";
+        default: return typeof value;
+    }
+}
+/** repr(str): quote choice + escapes for control characters. Exotic
+ * non-printables (Unicode Cf/Zs beyond Latin-1) stay literal — an ADR-001
+ * margin; ASCII and common text are exact. */
+function pyReprStr(s) {
+    const q = s.includes("'") && !s.includes('"') ? '"' : "'";
+    let out = q;
+    for (const ch of s) {
+        const c = ch.codePointAt(0);
+        if (ch === "\\" || ch === q)
+            out += "\\" + ch;
+        else if (ch === "\n")
+            out += "\\n";
+        else if (ch === "\r")
+            out += "\\r";
+        else if (ch === "\t")
+            out += "\\t";
+        else if (c < 0x20 || (c >= 0x7f && c <= 0xa0) || c === 0xad) {
+            out += "\\x" + c.toString(16).padStart(2, "0");
+        }
+        else
+            out += ch;
+    }
+    return out + q;
+}
+/** repr(): containers render Python-style ({'k': 'v'}, ['a', 1]). */
+export function pyRepr(value) {
+    if (value === undefined || value === null)
+        return "None";
+    if (typeof value === "boolean")
+        return value ? "True" : "False";
+    if (typeof value === "number")
+        return pyNumber(value);
+    if (typeof value === "string")
+        return pyReprStr(value);
+    if (Array.isArray(value))
+        return "[" + value.map(pyRepr).join(", ") + "]";
+    if (typeof value === "object" && !(value instanceof Set)) {
+        const entries = Object.entries(value).map(([k, v]) => `${pyReprStr(k)}: ${pyRepr(v)}`);
+        return "{" + entries.join(", ") + "}";
+    }
+    return String(value);
+}
+/** str(): what Python's `str(r.get(f, ""))` produces for JSON-safe values —
+ * None -> "None", True -> "True", nested containers via repr. */
+export function pyStr(value) {
+    if (typeof value === "string")
+        return value;
+    return pyRepr(value);
+}
+/** round(x, nd) with CPython semantics: correctly rounded on the double's
+ * EXACT value, ties to even. A tie exists iff x is exactly k/2^(nd+1) with
+ * k odd (the only doubles whose decimal expansion ends in ...5 at digit
+ * nd+1); everything else is unambiguous and toFixed rounds it correctly.
+ * So 2.675 (really 2.67499...82) rounds DOWN to 2.67 like Python, while a
+ * true tie like 0.90625 -> 0.9062 goes to even. */
+export function pyRound(x, nd) {
+    const scaled2 = x * 2 ** (nd + 1); // power-of-two scaling is exact
+    if (Number.isInteger(scaled2) && Math.abs(scaled2) % 2 === 1) {
+        const trunc = x.toFixed(nd + 1).slice(0, -1); // exact digits, drop the "5"
+        const digits = trunc.replace(/[-.]/g, "");
+        const last = digits ? digits.charCodeAt(digits.length - 1) - 48 : 0;
+        const v = Number(last % 2 === 0 ? trunc : bumpLastDigit(trunc));
+        return v === 0 ? 0 : v;
+    }
+    const v = Number(x.toFixed(nd));
+    return v === 0 ? 0 : v;
+}
+function bumpLastDigit(s) {
+    const neg = s.startsWith("-");
+    const chars = (neg ? s.slice(1) : s).split("");
+    let carry = 1;
+    for (let i = chars.length - 1; i >= 0 && carry; i--) {
+        if (chars[i] === ".")
+            continue;
+        const d = chars[i].charCodeAt(0) - 48 + carry;
+        chars[i] = String(d % 10);
+        carry = d >= 10 ? 1 : 0;
+    }
+    if (carry)
+        chars.unshift("1");
+    return (neg ? "-" : "") + chars.join("");
+}
+/** Python string `<`: code-point order. JS `<` is UTF-16 order, which sorts
+ * astral characters below U+E000..U+FFFF. */
+export function compareCodePoints(a, b) {
+    const ia = a[Symbol.iterator]();
+    const ib = b[Symbol.iterator]();
+    for (;;) {
+        const ra = ia.next();
+        const rb = ib.next();
+        if (ra.done && rb.done)
+            return 0;
+        if (ra.done)
+            return -1;
+        if (rb.done)
+            return 1;
+        const ca = ra.value.codePointAt(0);
+        const cb = rb.value.codePointAt(0);
+        if (ca !== cb)
+            return ca < cb ? -1 : 1;
+    }
+}
+/** Python comparison for sort keys: numbers/bools inter-compare, strings by
+ * code point, anything else raises TypeError like CPython (lists, which
+ * Python would compare element-wise, are an ADR-001 margin). */
+export function pyCompare(a, b) {
+    const an = typeof a === "number" || typeof a === "boolean";
+    const bn = typeof b === "number" || typeof b === "boolean";
+    if (an && bn) {
+        const x = Number(a);
+        const y = Number(b);
+        return x < y ? -1 : x > y ? 1 : 0;
+    }
+    if (typeof a === "string" && typeof b === "string")
+        return compareCodePoints(a, b);
+    throw new TypeError(`'<' not supported between instances of '${pyTypeName(b)}' and '${pyTypeName(a)}'`);
+}
+/** Membership key with Python hash/eq semantics: True == 1 == 1.0, None is
+ * its own class; dict/list/set raise TypeError (unhashable) like set(). */
+export function pyEqKey(value) {
+    if (value === undefined || value === null)
+        return "None";
+    if (typeof value === "boolean")
+        return "num:" + (value ? 1 : 0);
+    if (typeof value === "number")
+        return "num:" + value;
+    if (typeof value === "string")
+        return "str:" + value;
+    throw new TypeError(`unhashable type: '${pyTypeName(value)}'`);
+}
+/** Map a UTF-16 index to a code-point index (Python str positions). The
+ * common no-surrogate case is the identity, at no cost. */
+export function codePointIndexer(text) {
+    if (!/[\uD800-\uDFFF]/.test(text))
+        return (i) => i;
+    const map = new Map();
+    let cp = 0;
+    let i = 0;
+    while (i < text.length) {
+        map.set(i, cp);
+        i += text.codePointAt(i) > 0xffff ? 2 : 1;
+        cp++;
+    }
+    map.set(text.length, cp);
+    return (idx) => map.get(idx);
+}
+/** Trailing-whitespace strip matching Python str.rstrip(): includes the
+ * file/group/record/unit separators (0x1C-0x1F) and NEL (0x85), and does
+ * NOT strip U+FEFF (which JS \s wrongly includes). */
+const PY_TRAILING_WS = /[\t-\r\x1c-\x1f \x85\xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]+$/u;
+export function pyRstrip(text) {
+    return text.replace(PY_TRAILING_WS, "");
+}

package/dist/shaped.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Apply a contexel pipeline at the tool boundary — parity port. The model
+ * calls the tool normally and never writes the reshaping. Async-first: a
+ * tool returning a promise is awaited, then shaped (an improvement over
+ * static detection — JS shapes any thenable result).
+ */
+import type { Records } from "./stages.js";
+import { type StageFn } from "./pipeline.js";
+type Tool<A extends unknown[]> = (...args: A) => Records | Promise<Records>;
+export declare function shaped(pipe: StageFn | StageFn[]): <A extends unknown[]>(fn: Tool<A>) => (...args: A) => Records | Promise<Records>;
+export {};

package/dist/shaped.js

@@ -0,0 +1,13 @@
+import { pipeline } from "./pipeline.js";
+export function shaped(pipe) {
+    const runner = typeof pipe === "function" ? pipe : pipeline(pipe);
+    return function (fn) {
+        return (...args) => {
+            const result = fn(...args);
+            if (result && typeof result.then === "function") {
+                return result.then((records) => runner(records));
+            }
+            return runner(result);
+        };
+    };
+}

package/dist/stages.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Deterministic context-economy stages — parity port of contexel's Python
+ * `stages` module. Every stage is `(records, params) => records`, never
+ * mutates its input, and is auto-traced when a trace is active. Behavior
+ * matches the Python implementation on the shared golden vectors
+ * (parity/vectors.json); boundaries are documented in ADR-001.
+ */
+import * as tokens from "./tokens.js";
+export type Rec = Record<string, unknown>;
+export type Records = Rec[];
+export declare const select: (records: {
+    [x: string]: unknown;
+}[], params: {
+    fields: string | string[];
+}) => {
+    [x: string]: unknown;
+}[];
+export declare const dedupe: (records: {
+    [x: string]: unknown;
+}[], params?: {
+    key?: string | string[] | null;
+} | undefined) => {
+    [x: string]: unknown;
+}[];
+export declare const allowlist: (records: {
+    [x: string]: unknown;
+}[], params: {
+    field: string;
+    allowed: unknown[] | Set<unknown>;
+}) => {
+    [x: string]: unknown;
+}[];
+export declare const quarantine: (records: {
+    [x: string]: unknown;
+}[], params?: {
+    fields?: string | string[];
+    patterns?: string[];
+    action?: "drop" | "flag";
+    into?: string;
+} | undefined) => {
+    [x: string]: unknown;
+}[];
+export declare const rescore: (records: {
+    [x: string]: unknown;
+}[], params: {
+    query: string | string[];
+    fields?: string | string[];
+    into?: string;
+    proximity?: boolean;
+    match?: "word" | "substring";
+}) => {
+    [x: string]: unknown;
+}[];
+export declare const rank: (records: {
+    [x: string]: unknown;
+}[], params: {
+    by: string | ((r: Rec) => unknown);
+    desc?: boolean;
+}) => {
+    [x: string]: unknown;
+}[];
+export declare const truncateField: (records: {
+    [x: string]: unknown;
+}[], params: {
+    field: string;
+    maxTokens: number;
+    tokenizer?: tokens.Tokenizer | null;
+    suffix?: string;
+}) => {
+    [x: string]: unknown;
+}[];
+export declare const trimToBudget: (records: {
+    [x: string]: unknown;
+}[], params: {
+    maxTokens: number;
+    tokenizer?: tokens.Tokenizer | null;
+    minRecords?: number;
+}) => {
+    [x: string]: unknown;
+}[];
+/** Combiner (not auto-traced, matching Python): normalize and concatenate
+ * record lists from different tools; `schema` maps unified name -> source
+ * name or candidate list (first match wins). */
+export declare function merge(sources: Records[], options?: {
+    schema?: Record<string, string | string[]>;
+    dedupeKey?: string | null;
+}): Records;

package/dist/stages.js

@@ -0,0 +1,311 @@
+/**
+ * Deterministic context-economy stages — parity port of contexel's Python
+ * `stages` module. Every stage is `(records, params) => records`, never
+ * mutates its input, and is auto-traced when a trace is active. Behavior
+ * matches the Python implementation on the shared golden vectors
+ * (parity/vectors.json); boundaries are documented in ADR-001.
+ */
+import * as tokens from "./tokens.js";
+import { traced } from "./trace.js";
+import { codePointIndexer, pyCompare, pyEqKey, pyRound, pyRstrip, pyStr, } from "./py.js";
+/** A bare string means ONE field, not its characters (parity with Python). */
+function fieldList(fields) {
+    return typeof fields === "string" ? [fields] : fields;
+}
+/** Own-property write that cannot hit setters or the "__proto__" trap —
+ * a key named "__proto__" becomes an ordinary data property, as in Python. */
+function defineField(out, key, value) {
+    Object.defineProperty(out, key, {
+        value,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+    });
+}
+/* ------------------------------ fingerprints ----------------------------- */
+/** Python-mapped type tag: int/float distinction for JSON-sourced numbers. */
+function typedKey(value) {
+    if (value === null || value === undefined)
+        return "NoneType:None";
+    if (typeof value === "boolean")
+        return `bool:${value}`;
+    if (typeof value === "number") {
+        return Number.isInteger(value) ? `int:${value}` : `float:${value}`;
+    }
+    if (typeof value === "string")
+        return `str:${JSON.stringify(value)}`;
+    if (Array.isArray(value))
+        return "list:[" + value.map(typedKey).join(",") + "]";
+    if (value instanceof Set) {
+        return "set:(" + [...value].map(typedKey).sort().join(",") + ")";
+    }
+    if (typeof value === "object") {
+        const entries = Object.entries(value)
+            .map(([k, v]) => `${JSON.stringify(k)}:${typedKey(v)}`)
+            .sort();
+        return "dict:{" + entries.join(",") + "}";
+    }
+    return `${typeof value}:${String(value)}`;
+}
+/* -------------------------------- stages --------------------------------- */
+export const select = traced("select", (records, params) => {
+    const keep = fieldList(params.fields);
+    return records.map((r) => {
+        const out = {};
+        for (const k of keep)
+            if (Object.hasOwn(r, k))
+                defineField(out, k, r[k]);
+        return out;
+    });
+});
+export const dedupe = traced("dedupe", (records, params = {}) => {
+    const key = params.key ?? null;
+    const keys = key === null ? null : Array.isArray(key) ? key : [key];
+    const seen = new Set();
+    const out = [];
+    for (const r of records) {
+        const basis = keys === null ? r : keys.map((k) => (Object.hasOwn(r, k) ? r[k] : null));
+        const fp = typedKey(basis);
+        if (seen.has(fp))
+            continue;
+        seen.add(fp);
+        out.push(r);
+    }
+    return out;
+});
+export const allowlist = traced("allowlist", (records, params) => {
+    // Python builds set(allowed) up front: an unhashable entry raises.
+    const allowed = new Set();
+    for (const a of params.allowed)
+        allowed.add(pyEqKey(a));
+    return records.filter((r) => {
+        // Python r.get(field): a missing field reads as None, and None can
+        // legitimately be allowed; unhashable values fail closed.
+        const v = Object.hasOwn(r, params.field) ? r[params.field] : null;
+        try {
+            return allowed.has(pyEqKey(v));
+        }
+        catch {
+            return false;
+        }
+    });
+});
+const INJECTION_PATTERNS = [
+    "ignore\\s+(?:all\\s+|any\\s+)?(?:previous|prior|above|earlier)\\s+(?:instructions|messages|prompts|context)",
+    "disregard\\s+(?:all\\s+|the\\s+)?(?:previous|prior|above|earlier)",
+    "you\\s+are\\s+now\\s+",
+    "new\\s+instructions\\s*:",
+    "system\\s+prompt",
+    "</?\\s*(?:system|assistant|instructions?)\\s*>",
+];
+export const quarantine = traced("quarantine", (records, params = {}) => {
+    const fields = fieldList(params.fields ?? ["snippet"]);
+    const action = params.action ?? "drop";
+    const into = params.into ?? "quarantined";
+    if (action !== "drop" && action !== "flag") {
+        throw new Error(`action must be 'drop' or 'flag', got ${String(action)}`);
+    }
+    const matcher = new RegExp((params.patterns ?? INJECTION_PATTERNS).join("|"), "i");
+    const out = [];
+    for (const r of records) {
+        // Python str(r.get(f, "")): None -> "None", nested containers via
+        // repr — a payload inside a dict or list still hits the matcher.
+        const text = fields
+            .map((f) => (Object.hasOwn(r, f) ? pyStr(r[f]) : ""))
+            .join(" ");
+        const hit = matcher.test(text);
+        if (action === "flag")
+            out.push({ ...r, [into]: hit });
+        else if (!hit)
+            out.push(r);
+    }
+    return out;
+});
+/* Word matching: identical to Python's [^\W_] on ASCII (all parity
+   vectors); exotic Unicode word classes may differ at the margin. */
+const WORD = /[\p{L}\p{N}]+/gu;
+export const rescore = traced("rescore", (records, params) => {
+    const fields = fieldList(params.fields ?? ["snippet"]);
+    const into = params.into ?? "score";
+    const proximity = params.proximity ?? true;
+    const match = params.match ?? "word";
+    const rawTerms = typeof params.query === "string"
+        ? params.query.toLowerCase().match(WORD) ?? []
+        : params.query.flatMap((p) => String(p).toLowerCase().match(WORD) ?? []);
+    const terms = [...new Set(rawTerms)];
+    if (!terms.length || !records.length) {
+        return records.map((r) => ({ ...r, [into]: 0.0 }));
+    }
+    const texts = records.map((r) => fields
+        .map((f) => (Object.hasOwn(r, f) ? pyStr(r[f]) : ""))
+        .join(" ")
+        .toLowerCase());
+    let finder = null;
+    if (match === "word") {
+        const alt = [...terms]
+            .sort((a, b) => b.length - a.length)
+            .map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+            .join("|");
+        // boundary guards: underscore counts as a boundary (snake_case splits)
+        finder = new RegExp(`(?<![\\p{L}\\p{N}])(?:${alt})(?![\\p{L}\\p{N}])`, "gu");
+    }
+    const n = records.length;
+    const tfs = [];
+    const firsts = [];
+    const df = new Map(terms.map((t) => [t, 0]));
+    for (const text of texts) {
+        // Python positions are code-point indices; JS regex/indexOf yield
+        // UTF-16 units — convert so the proximity window means the same thing.
+        const toCp = codePointIndexer(text);
+        const row = new Map();
+        const first = new Map();
+        if (finder) {
+            finder.lastIndex = 0;
+            for (const m of text.matchAll(finder)) {
+                const t = m[0];
+                row.set(t, (row.get(t) ?? 0) + 1);
+                if (!first.has(t))
+                    first.set(t, toCp(m.index ?? 0));
+            }
+        }
+        else {
+            for (const t of terms) {
+                let idx = text.indexOf(t);
+                let cnt = 0;
+                const firstIdx = idx;
+                while (idx !== -1) {
+                    cnt++;
+                    idx = text.indexOf(t, idx + 1);
+                }
+                if (cnt) {
+                    row.set(t, cnt);
+                    first.set(t, toCp(firstIdx));
+                }
+            }
+        }
+        for (const t of row.keys())
+            df.set(t, (df.get(t) ?? 0) + 1);
+        tfs.push(row);
+        firsts.push(first);
+    }
+    const idf = new Map(terms.map((t) => [t, Math.log((n - (df.get(t) ?? 0) + 0.5) / ((df.get(t) ?? 0) + 0.5) + 1.0)]));
+    const k1 = 1.5;
+    const window = 80;
+    return records.map((r, i) => {
+        const row = tfs[i];
+        const first = firsts[i];
+        let score = 0;
+        for (const [t, tf] of row)
+            score += (idf.get(t) ?? 0) * (tf / (tf + k1));
+        if (proximity && row.size > 1) {
+            for (let j = 0; j + 1 < terms.length; j++) {
+                const t1 = terms[j];
+                const t2 = terms[j + 1];
+                if (first.has(t1) && first.has(t2)) {
+                    const gap = first.get(t2) - first.get(t1);
+                    if (gap > 0 && gap <= window) {
+                        score += ((idf.get(t1) ?? 0) + (idf.get(t2) ?? 0)) / 4;
+                    }
+                }
+            }
+        }
+        return { ...r, [into]: pyRound(score, 6) };
+    });
+});
+export const rank = traced("rank", (records, params) => {
+    const desc = params.desc ?? true;
+    const by = params.by;
+    const dir = desc ? -1 : 1;
+    // decorate-sort-undecorate like Python sorted(key=...): the key is
+    // computed once per record, the sort is stable, and reverse=desc keeps
+    // ties in original order (never reverse a stable ascending sort).
+    const sortKeyed = (rs, keyOf) => {
+        const keyed = rs.map((r) => [keyOf(r), r]);
+        keyed.sort((p, q) => dir * pyCompare(p[0], q[0]));
+        return keyed.map((p) => p[1]);
+    };
+    if (typeof by === "function")
+        return sortKeyed([...records], by);
+    const present = records.filter((r) => Object.hasOwn(r, by));
+    const missing = records.filter((r) => !Object.hasOwn(r, by));
+    return [...sortKeyed(present, (r) => r[by]), ...missing];
+});
+function truncateText(text, maxTokens, tokenizer, suffix) {
+    if (tokens.count(text, tokenizer) <= maxTokens)
+        return text;
+    const budget = Math.max(1, maxTokens - tokens.count(suffix, tokenizer));
+    if (tokens.isHeuristic(tokenizer)) {
+        // ceil(len/4) is invertible: longest prefix within budget = 4*budget
+        // code points (Python slices by code points, so must we).
+        const cps = [...text];
+        return pyRstrip(cps.slice(0, 4 * budget).join("")) + suffix;
+    }
+    const cps = [...text];
+    let lo = 0;
+    let hi = cps.length;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (tokens.count(cps.slice(0, mid).join(""), tokenizer) <= budget)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return pyRstrip(cps.slice(0, lo).join("")) + suffix;
+}
+export const truncateField = traced("truncate_field", (records, params) => {
+    const suffix = params.suffix ?? "…";
+    return records.map((r) => {
+        const value = r[params.field];
+        if (typeof value !== "string")
+            return r;
+        return {
+            ...r,
+            [params.field]: truncateText(value, params.maxTokens, params.tokenizer ?? null, suffix),
+        };
+    });
+});
+export const trimToBudget = traced("trim_to_budget", (records, params) => {
+    // minRecords guards the silent-failure edge: a too-small budget would
+    // return [], indistinguishable from "nothing matched" — keep the first
+    // (best-ranked) records anyway; the overrun shows in the audit.
+    const minRecords = params.minRecords ?? 0;
+    const out = [];
+    let used = 0;
+    for (const r of records) {
+        const cost = tokens.count(r, params.tokenizer ?? null) + 2; // list framing
+        if (used + cost > params.maxTokens && out.length >= minRecords)
+            break;
+        out.push(r);
+        used += cost;
+    }
+    return out;
+});
+/** Combiner (not auto-traced, matching Python): normalize and concatenate
+ * record lists from different tools; `schema` maps unified name -> source
+ * name or candidate list (first match wins). */
+export function merge(sources, options = {}) {
+    const combined = [];
+    for (const src of sources) {
+        for (const r of src) {
+            if (!options.schema) {
+                combined.push(r);
+                continue;
+            }
+            const mapped = {};
+            for (const [unified, candidates] of Object.entries(options.schema)) {
+                const names = typeof candidates === "string" ? [candidates] : candidates;
+                for (const name of names) {
+                    if (Object.hasOwn(r, name)) {
+                        defineField(mapped, unified, r[name]);
+                        break;
+                    }
+                }
+            }
+            combined.push(mapped);
+        }
+    }
+    if (options.dedupeKey != null) {
+        return dedupe(combined, { key: options.dedupeKey });
+    }
+    return combined;
+}

package/dist/tokens.d.ts

@@ -0,0 +1,27 @@
+export type Tokenizer = (text: string) => number;
+export type Serializer = (value: unknown) => string;
+export declare function codePointLength(text: string): number;
+/** Python-compatible canonical JSON (sort_keys, ensure_ascii=False, default=str). */
+export declare function pythonJson(value: unknown): string;
+interface Scope {
+    tokenizer?: Tokenizer;
+    serializer?: Serializer;
+}
+/** Process-wide default tokenizer; null resets to the built-in estimator. */
+export declare function setTokenizer(tokenizer: Tokenizer | null): void;
+/** Process-wide default serializer; null resets to canonical JSON. */
+export declare function setSerializer(serializer: Serializer | null): void;
+/**
+ * Context-local token accounting — safe for concurrent tenants. The JS
+ * analog of Python's `tokens.scoped()`: overrides apply within `fn` and
+ * every async continuation it spawns; other tasks are untouched.
+ */
+export declare function scoped<T>(overrides: Scope, fn: () => T): T;
+/** True when the tokenizer in effect is the built-in estimator (enables
+ * the closed-form truncate fast path, which relies on ceil(len/4)). */
+export declare function isHeuristic(tokenizer?: Tokenizer | null): boolean;
+/** Render a value exactly the way token counting will price it. */
+export declare function serialize(value: unknown): string;
+/** Token cost of any serializable value (strings bypass the serializer). */
+export declare function count(value: unknown, tokenizer?: Tokenizer | null): number;
+export {};

package/dist/tokens.js

@@ -0,0 +1,106 @@
+/**
+ * Token measurement — parity port of contexel's Python `tokens` module.
+ *
+ * Counting is encoding-relative: a record's cost is the token count of its
+ * serialized text. The canonical serialization replicates Python's
+ * `json.dumps(value, ensure_ascii=False, default=str, sort_keys=True)` —
+ * including the ", " / ": " separators — so both languages price identical
+ * records identically. Token length counts Unicode code points (Python
+ * `len`), not UTF-16 units.
+ *
+ * Parity boundary (ADR-001): JS has one number type — a JSON `1.0` parses
+ * to `1` and serializes as `"1"`, where Python emits `"1.0"`.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { compareCodePoints, pyFloat } from "./py.js";
+export function codePointLength(text) {
+    let n = 0;
+    for (const _ of text)
+        n++;
+    return n;
+}
+function heuristic(text) {
+    if (!text)
+        return 0;
+    return Math.max(1, Math.ceil(codePointLength(text) / 4));
+}
+/** Python-compatible canonical JSON (sort_keys, ensure_ascii=False, default=str). */
+export function pythonJson(value) {
+    if (value === null || value === undefined)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            return value > 0 ? "Infinity" : value < 0 ? "-Infinity" : "NaN";
+        // Python repr thresholds for floats ("1e-05", not JS's "0.00001");
+        // integer-valued numbers collapse to int form (ADR-001 boundary 4a).
+        return Number.isInteger(value) ? String(value) : pyFloat(value);
+    }
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return "[" + value.map(pythonJson).join(", ") + "]";
+    }
+    if (value instanceof Set) {
+        // Python json.dumps falls to default=str for sets; not JSON data — best effort.
+        return JSON.stringify(String(value));
+    }
+    if (typeof value === "object") {
+        // Python sorted() compares by code point; JS default string order is
+        // UTF-16, which sorts astral-plane keys differently.
+        const entries = Object.entries(value)
+            .sort(([a], [b]) => compareCodePoints(a, b));
+        return "{" + entries.map(([k, v]) => JSON.stringify(k) + ": " + pythonJson(v)).join(", ") + "}";
+    }
+    return JSON.stringify(String(value)); // default=str
+}
+let processTokenizer = null;
+let processSerializer = null;
+const scopeStore = new AsyncLocalStorage();
+/** Process-wide default tokenizer; null resets to the built-in estimator. */
+export function setTokenizer(tokenizer) {
+    processTokenizer = tokenizer;
+}
+/** Process-wide default serializer; null resets to canonical JSON. */
+export function setSerializer(serializer) {
+    processSerializer = serializer;
+}
+/**
+ * Context-local token accounting — safe for concurrent tenants. The JS
+ * analog of Python's `tokens.scoped()`: overrides apply within `fn` and
+ * every async continuation it spawns; other tasks are untouched.
+ */
+export function scoped(overrides, fn) {
+    // merge with any enclosing scope so nested overrides compose, like
+    // Python's two independent ContextVars; an explicit `undefined` means
+    // "not provided", never "clobber the outer override"
+    const merged = { ...scopeStore.getStore() };
+    if (overrides.tokenizer !== undefined)
+        merged.tokenizer = overrides.tokenizer;
+    if (overrides.serializer !== undefined)
+        merged.serializer = overrides.serializer;
+    return scopeStore.run(merged, fn);
+}
+function activeTokenizer() {
+    return scopeStore.getStore()?.tokenizer ?? processTokenizer ?? heuristic;
+}
+function activeSerializer() {
+    return scopeStore.getStore()?.serializer ?? processSerializer ?? pythonJson;
+}
+/** True when the tokenizer in effect is the built-in estimator (enables
+ * the closed-form truncate fast path, which relies on ceil(len/4)). */
+export function isHeuristic(tokenizer) {
+    return (tokenizer ?? activeTokenizer()) === heuristic;
+}
+/** Render a value exactly the way token counting will price it. */
+export function serialize(value) {
+    if (typeof value === "string")
+        return value;
+    return activeSerializer()(value);
+}
+/** Token cost of any serializable value (strings bypass the serializer). */
+export function count(value, tokenizer) {
+    const tok = tokenizer ?? activeTokenizer();
+    return tok(typeof value === "string" ? value : serialize(value));
+}

package/dist/trace.d.ts

@@ -0,0 +1,31 @@
+export interface Entry {
+    stage: string;
+    inCount: number;
+    outCount: number;
+    tokensBefore: number;
+    tokensAfter: number;
+    droppedIds: unknown[];
+}
+export declare class Trace {
+    entries: Entry[];
+    policies: string[];
+    idField: string | null;
+    constructor(idField?: string | null);
+    get tokensBefore(): number;
+    get tokensAfter(): number;
+    get reduction(): number;
+    report(): string;
+    /** JSON-able governance record: policy fingerprints, per-stage dropped
+     * record ids (stage = removal reason; records lacking the field are
+     * untracked), token movement. */
+    audit(): Record<string, unknown>;
+}
+export declare function currentTrace(): Trace | null;
+/** Run `fn` with an active trace; returns [result, trace]. */
+export declare function trace<T>(options: {
+    idField?: string;
+} | null, fn: () => T): [T, Trace];
+type Rec = Record<string, unknown>;
+/** Wrap a stage so an active trace records its effect (incl. dropped ids). */
+export declare function traced<A extends unknown[]>(name: string, fn: (records: Rec[], ...args: A) => Rec[]): (records: Rec[], ...args: A) => Rec[];
+export {};

package/dist/trace.js

@@ -0,0 +1,124 @@
+/**
+ * Per-stage observability — parity port of contexel's Python `trace`.
+ * `trace({idField}, fn)` runs `fn` with an active trace (AsyncLocalStorage,
+ * the JS analog of contextvars) and records what every stage did; with
+ * `idField` it also records which records each stage dropped (records
+ * lacking the field are untracked). `audit()` is the governance record.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import * as tokens from "./tokens.js";
+import { pyRound } from "./py.js";
+export class Trace {
+    entries = [];
+    policies = [];
+    idField;
+    constructor(idField = null) {
+        this.idField = idField;
+    }
+    get tokensBefore() {
+        return this.entries.length ? this.entries[0].tokensBefore : 0;
+    }
+    get tokensAfter() {
+        return this.entries.length ? this.entries[this.entries.length - 1].tokensAfter : 0;
+    }
+    get reduction() {
+        const before = this.tokensBefore;
+        return before === 0 ? 0 : 1 - this.tokensAfter / before;
+    }
+    report() {
+        if (!this.entries.length)
+            return "(no stages traced)";
+        const lines = this.entries.map((e) => `${e.stage.padEnd(16)} ${String(e.inCount).padStart(5)} -> ` +
+            `${String(e.outCount).padEnd(5)} ${e.tokensBefore.toLocaleString("en-US").padStart(7)} -> ` +
+            `${e.tokensAfter.toLocaleString("en-US").padEnd(7)} tokens`);
+        lines.push("-".repeat(56));
+        lines.push(`${"total".padEnd(16)} ${"".padStart(5)}    ${"".padEnd(5)} ` +
+            `${this.tokensBefore.toLocaleString("en-US").padStart(7)} -> ` +
+            `${this.tokensAfter.toLocaleString("en-US").padEnd(7)} tokens  ` +
+            `(${pyRound(this.reduction * 100, 0)}% reduction)`);
+        return lines.join("\n");
+    }
+    /** JSON-able governance record: policy fingerprints, per-stage dropped
+     * record ids (stage = removal reason; records lacking the field are
+     * untracked), token movement. */
+    audit() {
+        return {
+            policies: [...this.policies],
+            id_field: this.idField,
+            tokens_before: this.tokensBefore,
+            tokens_after: this.tokensAfter,
+            reduction: pyRound(this.reduction, 4), // Python round(): half to even
+            stages: this.entries.map((e) => ({
+                stage: e.stage,
+                records_in: e.inCount,
+                records_out: e.outCount,
+                tokens_before: e.tokensBefore,
+                tokens_after: e.tokensAfter,
+                dropped_ids: [...e.droppedIds],
+            })),
+        };
+    }
+}
+const store = new AsyncLocalStorage();
+export function currentTrace() {
+    return store.getStore() ?? null;
+}
+/** Run `fn` with an active trace; returns [result, trace]. */
+export function trace(options, fn) {
+    const tr = new Trace(options?.idField ?? null);
+    const result = store.run(tr, fn);
+    return [result, tr];
+}
+function idKey(value) {
+    if (value !== null && typeof value === "object")
+        return tokens.pythonJson(value);
+    return value;
+}
+/** Wrap a stage so an active trace records its effect (incl. dropped ids). */
+export function traced(name, fn) {
+    return (records, ...args) => {
+        const tr = currentTrace();
+        if (!tr)
+            return fn(records, ...args);
+        const beforeN = records.length;
+        const beforeTok = tokens.count(records);
+        const out = fn(records, ...args);
+        const dropped = [];
+        const fid = tr.idField;
+        if (fid) {
+            const remaining = new Map();
+            let unidentified = 0; // survivors without the id field absorb drops
+            for (const r of out) {
+                if (r !== null && typeof r === "object" && Object.hasOwn(r, fid)) {
+                    const k = idKey(r[fid]);
+                    remaining.set(k, (remaining.get(k) ?? 0) + 1);
+                }
+                else {
+                    unidentified++;
+                }
+            }
+            for (const r of records) {
+                if (r !== null && typeof r === "object" && Object.hasOwn(r, fid)) {
+                    const original = r[fid];
+                    const k = idKey(original);
+                    const left = remaining.get(k) ?? 0;
+                    if (left > 0)
+                        remaining.set(k, left - 1);
+                    else if (unidentified > 0)
+                        unidentified--;
+                    else
+                        dropped.push(original);
+                }
+            }
+        }
+        tr.entries.push({
+            stage: name,
+            inCount: beforeN,
+            outCount: out.length,
+            tokensBefore: beforeTok,
+            tokensAfter: tokens.count(out),
+            droppedIds: dropped,
+        });
+        return out;
+    };
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "contexel",
+  "version": "0.1.16",
+  "description": "Deterministic, dependency-free context shaping for code-writing agents — TypeScript parity of the Python package, enforced by shared golden vectors.",
+  "keywords": ["llm", "agents", "context-engineering", "tokens", "tool-use", "rag"],
+  "license": "MIT",
+  "author": "Mahesh Vaikri",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.test.json && node --test dist-test/test/parity.test.js dist-test/test/behavior.test.js",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maheshvaikri-code/contexel.git",
+    "directory": "ts"
+  },
+  "homepage": "https://maheshvaikri-code.github.io/contexel/",
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.5.0"
+  }
+}