jevkit-core 0.2.0

package/README.md

@@ -0,0 +1,27 @@
+# jevkit-core
+
+Shared substrate for [jevkit](https://github.com/pjdurden/jevkit-js), a set of
+tools for building on TypeSafe's Jev. Nothing in this package calls the API.
+
+- **`.jevl` record format** — one JSON Lines format that serves as test
+  cassette, drift golden set, benchmark instance, and calibration observation.
+  See [the spec](../../docs/specs/record-format-v1.md).
+- **Canonical digests** — RFC 8785 canonicalization, so the same request always
+  hashes the same way. `record_id()` includes the model; `request_id()` does
+  not, which is what lets you pair a golden record with its replay on a new
+  model version.
+- **Question normalization** — one view over SDK objects and plain dicts alike.
+- **Token budgets** — estimates against Jev's two documented limits: 64k for
+  state plus all questions, 32k for state plus the longest single question.
+
+> Unofficial and unaffiliated with TypeSafe.
+
+## Install
+
+```bash
+npm install jevkit-core
+```
+
+## License
+
+MIT

package/dist/answers.d.ts

@@ -0,0 +1,66 @@
+/**
+ * A uniform view of a jev answer, and how it compares to a ground-truth label.
+ *
+ * `drift`, `calibrate` and `bench` all need the same three things from an
+ * answer: what it predicted, how much probability sat on a given outcome, and
+ * whether it matched a label. Those live here so the three packages agree on
+ * the definitions rather than each inventing its own.
+ *
+ * The vocabulary is deliberately narrow:
+ *
+ * - **predicted** is the outcome the answer selects. For a Choice it is the
+ *   option key. For a Noul it is `true` when `noul` clears the threshold. For a
+ *   Score it is the index of the most probable level, which is *not* the same
+ *   as rounding `score`.
+ * - **confidence** is what the API returned, and Nouls do not have one. A
+ *   Noul's distance from 0.5 is a different quantity, exposed as `decisiveness`
+ *   rather than pretending it is the same number.
+ */
+export declare const NOUL_THRESHOLD = 0.5;
+export type AnswerType = "choice" | "score" | "noul";
+type Raw = {
+    [key: string]: unknown;
+};
+export declare class Answer {
+    readonly id: string;
+    readonly type: AnswerType;
+    readonly raw: Raw;
+    constructor(id: string, type: AnswerType, raw: Raw);
+    /**
+     * Outcome -> probability.
+     *
+     * Choice returns its options, Score its level indices as strings. Noul has no
+     * distribution from the API, so the two-outcome distribution it implies is
+     * synthesized here.
+     */
+    get probabilities(): Record<string, number>;
+    /** As returned by the API. `null` for a Noul, which carries none. */
+    get confidence(): number | null;
+    /**
+     * How far from maximally uncertain this answer is, on 0..1.
+     *
+     * For a Noul this is `|noul - 0.5| * 2`. This is *not* confidence and is not
+     * comparable to the API's confidence across question types; it exists so
+     * Nouls can be thresholded on something with a defined meaning.
+     */
+    get decisiveness(): number;
+    /** The outcome this answer selects. */
+    predicted(noulThreshold?: number): unknown;
+    /** The probability-weighted score, for a Score answer. */
+    get score(): number | null;
+    private labelKey;
+    /**
+     * Probability this answer assigned to `label`.
+     *
+     * Returns 0 for an outcome the question never offered, which is the honest
+     * reading: the model could not have selected it.
+     */
+    probabilityOf(label: unknown): number;
+    isCorrect(label: unknown, noulThreshold?: number): boolean;
+    /** Probability mass on the predicted outcome. */
+    get topProbability(): number;
+}
+export declare function parseAnswer(qid: string, raw: unknown): Answer;
+export declare function parseAnswers(answers: Record<string, unknown>): Record<string, Answer>;
+export {};
+//# sourceMappingURL=answers.d.ts.map

package/dist/answers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"answers.d.ts","sourceRoot":"","sources":["../src/answers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AAErD,KAAK,GAAG,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AAEtC,qBAAa,MAAM;IAEf,QAAQ,CAAC,EAAE,EAAE,MAAM;IACnB,QAAQ,CAAC,IAAI,EAAE,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,GAAG;gBAFR,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,GAAG;IAGnB;;;;;;OAMG;IACH,IAAI,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAS1C;IAED,qEAAqE;IACrE,IAAI,UAAU,IAAI,MAAM,GAAG,IAAI,CAG9B;IAED;;;;;;OAMG;IACH,IAAI,YAAY,IAAI,MAAM,CAKzB;IAED,uCAAuC;IACvC,SAAS,CAAC,aAAa,GAAE,MAAuB,GAAG,OAAO;IAe1D,0DAA0D;IAC1D,IAAI,KAAK,IAAI,MAAM,GAAG,IAAI,CAIzB;IAED,OAAO,CAAC,QAAQ;IAKhB;;;;;OAKG;IACH,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM;IAIrC,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,aAAa,GAAE,MAAuB,GAAG,OAAO;IAY1E,iDAAiD;IACjD,IAAI,cAAc,IAAI,MAAM,CAG3B;CACF;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,MAAM,CAmB7D;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIrF"}

package/dist/answers.js

@@ -0,0 +1,152 @@
+/**
+ * A uniform view of a jev answer, and how it compares to a ground-truth label.
+ *
+ * `drift`, `calibrate` and `bench` all need the same three things from an
+ * answer: what it predicted, how much probability sat on a given outcome, and
+ * whether it matched a label. Those live here so the three packages agree on
+ * the definitions rather than each inventing its own.
+ *
+ * The vocabulary is deliberately narrow:
+ *
+ * - **predicted** is the outcome the answer selects. For a Choice it is the
+ *   option key. For a Noul it is `true` when `noul` clears the threshold. For a
+ *   Score it is the index of the most probable level, which is *not* the same
+ *   as rounding `score`.
+ * - **confidence** is what the API returned, and Nouls do not have one. A
+ *   Noul's distance from 0.5 is a different quantity, exposed as `decisiveness`
+ *   rather than pretending it is the same number.
+ */
+export const NOUL_THRESHOLD = 0.5;
+export class Answer {
+    id;
+    type;
+    raw;
+    constructor(id, type, raw) {
+        this.id = id;
+        this.type = type;
+        this.raw = raw;
+    }
+    /**
+     * Outcome -> probability.
+     *
+     * Choice returns its options, Score its level indices as strings. Noul has no
+     * distribution from the API, so the two-outcome distribution it implies is
+     * synthesized here.
+     */
+    get probabilities() {
+        if (this.type === "noul") {
+            const p = Number(this.raw["noul"] ?? 0);
+            return { true: p, false: 1 - p };
+        }
+        const probs = (this.raw["probabilities"] ?? {});
+        const out = {};
+        for (const [k, v] of Object.entries(probs))
+            out[String(k)] = Number(v);
+        return out;
+    }
+    /** As returned by the API. `null` for a Noul, which carries none. */
+    get confidence() {
+        const value = this.raw["confidence"];
+        return value === undefined || value === null ? null : Number(value);
+    }
+    /**
+     * How far from maximally uncertain this answer is, on 0..1.
+     *
+     * For a Noul this is `|noul - 0.5| * 2`. This is *not* confidence and is not
+     * comparable to the API's confidence across question types; it exists so
+     * Nouls can be thresholded on something with a defined meaning.
+     */
+    get decisiveness() {
+        if (this.type === "noul") {
+            return Math.abs(Number(this.raw["noul"] ?? 0) - NOUL_THRESHOLD) * 2;
+        }
+        return this.confidence ?? 0;
+    }
+    /** The outcome this answer selects. */
+    predicted(noulThreshold = NOUL_THRESHOLD) {
+        if (this.type === "noul")
+            return Number(this.raw["noul"] ?? 0) >= noulThreshold;
+        if (this.type === "choice")
+            return this.raw["choice"];
+        if (this.type === "score") {
+            const probs = this.probabilities;
+            const keys = Object.keys(probs);
+            if (!keys.length)
+                return null;
+            let best = keys[0];
+            for (const k of keys)
+                if (probs[k] > probs[best])
+                    best = k;
+            const asInt = Number.parseInt(best, 10);
+            return Number.isNaN(asInt) ? best : asInt;
+        }
+        return null;
+    }
+    /** The probability-weighted score, for a Score answer. */
+    get score() {
+        if (this.type !== "score")
+            return null;
+        const value = this.raw["score"];
+        return value === undefined || value === null ? null : Number(value);
+    }
+    labelKey(label) {
+        if (this.type === "noul")
+            return label ? "true" : "false";
+        return String(label);
+    }
+    /**
+     * Probability this answer assigned to `label`.
+     *
+     * Returns 0 for an outcome the question never offered, which is the honest
+     * reading: the model could not have selected it.
+     */
+    probabilityOf(label) {
+        return this.probabilities[this.labelKey(label)] ?? 0;
+    }
+    isCorrect(label, noulThreshold = NOUL_THRESHOLD) {
+        const predicted = this.predicted(noulThreshold);
+        if (this.type === "noul")
+            return Boolean(predicted) === Boolean(label);
+        if (this.type === "score") {
+            const a = Number(predicted);
+            const b = Number(label);
+            if (!Number.isNaN(a) && !Number.isNaN(b))
+                return a === b;
+            return predicted === label;
+        }
+        return predicted === label;
+    }
+    /** Probability mass on the predicted outcome. */
+    get topProbability() {
+        const values = Object.values(this.probabilities);
+        return values.length ? Math.max(...values) : 0;
+    }
+}
+export function parseAnswer(qid, raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new TypeError(`answer "${qid}": expected an object, got ${typeof raw}`);
+    }
+    const obj = raw;
+    let type = obj["type"];
+    if (type !== "choice" && type !== "score" && type !== "noul") {
+        // Infer from shape when the API response omits the discriminator.
+        if ("choice" in obj)
+            type = "choice";
+        else if ("noul" in obj)
+            type = "noul";
+        else if ("score" in obj)
+            type = "score";
+        else {
+            throw new TypeError(`answer "${qid}": cannot determine type; expected a 'type' field or one of ` +
+                `'choice'/'score'/'noul'`);
+        }
+    }
+    return new Answer(qid, type, obj);
+}
+export function parseAnswers(answers) {
+    const out = {};
+    for (const [qid, raw] of Object.entries(answers))
+        out[qid] = parseAnswer(qid, raw);
+    return out;
+}
+//# sourceMappingURL=answers.js.map

package/dist/answers.js.map

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

package/dist/canonical.d.ts

@@ -0,0 +1,18 @@
+/** RFC 8785 JSON Canonicalization, and the digests jevkit builds on it. */
+export type Json = null | boolean | number | string | Json[] | {
+    [k: string]: Json;
+};
+/** Serialize to RFC 8785 canonical form. */
+export declare function canonicalJson(value: unknown): string;
+/** `sha256:<hex>` over the canonical form of `value`. */
+export declare function digest(value: unknown): string;
+/**
+ * Digest of state + questions, with no model.
+ *
+ * This is what pairs a golden-set record with its replay on a different model
+ * version, since the full record id includes the model and would differ.
+ */
+export declare function requestId(state: unknown, questions: Record<string, unknown>): string;
+/** Digest of model + state + questions. The record's `id` field. */
+export declare function recordId(model: string, state: unknown, questions: Record<string, unknown>): string;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAI3E,MAAM,MAAM,IAAI,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,EAAE,GAAG;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAwDrF,4CAA4C;AAC5C,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD;AAED,yDAAyD;AACzD,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE7C;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAEpF;AAED,oEAAoE;AACpE,wBAAgB,QAAQ,CACtB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,MAAM,CAER"}

package/dist/canonical.js

@@ -0,0 +1,73 @@
+/** RFC 8785 JSON Canonicalization, and the digests jevkit builds on it. */
+import { createHash } from "node:crypto";
+/**
+ * Sort keys by Unicode code point.
+ *
+ * `Array.prototype.sort` on strings compares UTF-16 code units, which orders
+ * astral-plane characters wrongly relative to the code-point order RFC 8785
+ * requires. Comparing the code-point arrays directly fixes that.
+ */
+function compareCodePoints(a, b) {
+    const ca = Array.from(a).map((c) => c.codePointAt(0));
+    const cb = Array.from(b).map((c) => c.codePointAt(0));
+    const n = Math.min(ca.length, cb.length);
+    for (let i = 0; i < n; i++) {
+        const x = ca[i];
+        const y = cb[i];
+        if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    return ca.length - cb.length;
+}
+function serialize(value) {
+    if (value === null)
+        return "null";
+    const type = typeof value;
+    if (type === "boolean")
+        return value ? "true" : "false";
+    if (type === "number") {
+        const n = value;
+        if (!Number.isFinite(n)) {
+            throw new TypeError(`cannot canonicalize non-finite number: ${n}`);
+        }
+        // JSON.stringify emits ECMAScript shortest-round-trip form, which is what
+        // RFC 8785 specifies for numbers.
+        return JSON.stringify(n);
+    }
+    if (type === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return "[" + value.map((v) => serialize(v === undefined ? null : v)).join(",") + "]";
+    }
+    if (type === "object") {
+        const obj = value;
+        const keys = Object.keys(obj)
+            .filter((k) => obj[k] !== undefined)
+            .sort(compareCodePoints);
+        const body = keys.map((k) => `${JSON.stringify(k)}:${serialize(obj[k])}`).join(",");
+        return "{" + body + "}";
+    }
+    throw new TypeError(`cannot canonicalize value of type ${type}`);
+}
+/** Serialize to RFC 8785 canonical form. */
+export function canonicalJson(value) {
+    return serialize(value);
+}
+/** `sha256:<hex>` over the canonical form of `value`. */
+export function digest(value) {
+    return "sha256:" + createHash("sha256").update(canonicalJson(value), "utf8").digest("hex");
+}
+/**
+ * Digest of state + questions, with no model.
+ *
+ * This is what pairs a golden-set record with its replay on a different model
+ * version, since the full record id includes the model and would differ.
+ */
+export function requestId(state, questions) {
+    return digest({ questions, state });
+}
+/** Digest of model + state + questions. The record's `id` field. */
+export function recordId(model, state, questions) {
+    return digest({ model, questions, state });
+}
+//# sourceMappingURL=canonical.js.map

package/dist/canonical.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared substrate for the jevkit packages.
+ *
+ * Nothing here calls the jev API. This package holds the pieces every other
+ * jevkit tool needs: canonical digests, the `.jevl` record format, a uniform
+ * view of a question, and token budget estimation.
+ */
+export { Answer, NOUL_THRESHOLD, parseAnswer, parseAnswers, type AnswerType, } from "./answers.js";
+export { canonicalJson, digest, recordId, requestId, type Json } from "./canonical.js";
+export { Question, flattenText, normalizeQuestion, normalizeQuestions, type QuestionType, } from "./question.js";
+export { FORMAT_VERSION, Record, RecordFormatError, appendRecord, loadCassette, parseRecords, readRecords, writeRecords, type RecordInit, } from "./record.js";
+export { STATE_BUDGET, TOTAL_BUDGET, checkBudget, estimateTokens, type BudgetReport, } from "./tokens.js";
+export declare const VERSION = "0.2.0";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,MAAM,EACN,cAAc,EACd,WAAW,EACX,YAAY,EACZ,KAAK,UAAU,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACvF,OAAO,EACL,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,MAAM,EACN,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,KAAK,UAAU,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,cAAc,EACd,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC;AAErB,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * Shared substrate for the jevkit packages.
+ *
+ * Nothing here calls the jev API. This package holds the pieces every other
+ * jevkit tool needs: canonical digests, the `.jevl` record format, a uniform
+ * view of a question, and token budget estimation.
+ */
+export { Answer, NOUL_THRESHOLD, parseAnswer, parseAnswers, } from "./answers.js";
+export { canonicalJson, digest, recordId, requestId } from "./canonical.js";
+export { Question, flattenText, normalizeQuestion, normalizeQuestions, } from "./question.js";
+export { FORMAT_VERSION, Record, RecordFormatError, appendRecord, loadCassette, parseRecords, readRecords, writeRecords, } from "./record.js";
+export { STATE_BUDGET, TOTAL_BUDGET, checkBudget, estimateTokens, } from "./tokens.js";
+export const VERSION = "0.2.0";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,MAAM,EACN,cAAc,EACd,WAAW,EACX,YAAY,GAEb,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAa,MAAM,gBAAgB,CAAC;AACvF,OAAO,EACL,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,kBAAkB,GAEnB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,MAAM,EACN,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,YAAY,GAEb,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,cAAc,GAEf,MAAM,aAAa,CAAC;AAErB,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/dist/question.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A uniform view of a jev question.
+ *
+ * Questions arrive as plain objects sent to the HTTP API, as SDK objects, or
+ * from a user's own helper. Every jevkit tool wants the same few facts, so they
+ * are normalized once here.
+ *
+ * `instructions` and `criteria` both accept JSON structure, not just strings,
+ * so the normalized form keeps the raw value and exposes flattened text
+ * separately for textual analysis.
+ */
+export type QuestionType = "choice" | "score" | "noul";
+/** Collapse a string / object / array into one string for textual analysis. */
+export declare function flattenText(value: unknown): string;
+export declare class Question {
+    readonly id: string;
+    readonly type: QuestionType;
+    readonly instructions: unknown;
+    readonly criteria: unknown;
+    readonly raw: unknown;
+    constructor(id: string, type: QuestionType, instructions: unknown, criteria: unknown, raw?: unknown);
+    get instructionsText(): string;
+    get criteriaText(): string;
+    /** Everything the model reads, as one string. */
+    get text(): string;
+    /** Choice option keys, or Score level descriptions. Empty otherwise. */
+    get options(): string[];
+    /** [option key, description] pairs for a Choice. */
+    optionDescriptions(): Array<[string, string]>;
+}
+export declare function normalizeQuestion(qid: string, obj: unknown): Question;
+export declare function normalizeQuestions(questions: Record<string, unknown>): Question[];
+//# sourceMappingURL=question.d.ts.map

package/dist/question.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["../src/question.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AAIvD,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAgBlD;AAED,qBAAa,QAAQ;IAEjB,QAAQ,CAAC,EAAE,EAAE,MAAM;IACnB,QAAQ,CAAC,IAAI,EAAE,YAAY;IAC3B,QAAQ,CAAC,YAAY,EAAE,OAAO;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO;IAC1B,QAAQ,CAAC,GAAG,EAAE,OAAO;gBAJZ,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,YAAY,EAClB,YAAY,EAAE,OAAO,EACrB,QAAQ,EAAE,OAAO,EACjB,GAAG,GAAE,OAAmB;IAGnC,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,iDAAiD;IACjD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,wEAAwE;IACxE,IAAI,OAAO,IAAI,MAAM,EAAE,CAYtB;IAED,oDAAoD;IACpD,kBAAkB,IAAI,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAS9C;AAkBD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,QAAQ,CASrE;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,QAAQ,EAAE,CAEjF"}

package/dist/question.js

@@ -0,0 +1,107 @@
+/**
+ * A uniform view of a jev question.
+ *
+ * Questions arrive as plain objects sent to the HTTP API, as SDK objects, or
+ * from a user's own helper. Every jevkit tool wants the same few facts, so they
+ * are normalized once here.
+ *
+ * `instructions` and `criteria` both accept JSON structure, not just strings,
+ * so the normalized form keeps the raw value and exposes flattened text
+ * separately for textual analysis.
+ */
+const VALID_TYPES = ["choice", "score", "noul"];
+/** Collapse a string / object / array into one string for textual analysis. */
+export function flattenText(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (Array.isArray(value)) {
+        return value.map(flattenText).filter(Boolean).join(" ");
+    }
+    if (typeof value === "object") {
+        const parts = [];
+        for (const [k, v] of Object.entries(value)) {
+            // Keys carry meaning: in a Choice they are the option names.
+            parts.push(k, flattenText(v));
+        }
+        return parts.filter(Boolean).join(" ");
+    }
+    return String(value);
+}
+export class Question {
+    id;
+    type;
+    instructions;
+    criteria;
+    raw;
+    constructor(id, type, instructions, criteria, raw = undefined) {
+        this.id = id;
+        this.type = type;
+        this.instructions = instructions;
+        this.criteria = criteria;
+        this.raw = raw;
+    }
+    get instructionsText() {
+        return flattenText(this.instructions);
+    }
+    get criteriaText() {
+        return flattenText(this.criteria);
+    }
+    /** Everything the model reads, as one string. */
+    get text() {
+        return `${this.instructionsText} ${this.criteriaText}`.trim();
+    }
+    /** Choice option keys, or Score level descriptions. Empty otherwise. */
+    get options() {
+        const c = this.criteria;
+        if (this.type === "choice" && c && typeof c === "object" && !Array.isArray(c)) {
+            return Object.keys(c);
+        }
+        if (this.type === "score" && Array.isArray(c)) {
+            return c.map(flattenText);
+        }
+        if (this.type === "score" && c && typeof c === "object") {
+            return Object.values(c).map(flattenText);
+        }
+        return [];
+    }
+    /** [option key, description] pairs for a Choice. */
+    optionDescriptions() {
+        const c = this.criteria;
+        if (this.type === "choice" && c && typeof c === "object" && !Array.isArray(c)) {
+            return Object.entries(c).map(([k, v]) => [k, flattenText(v)]);
+        }
+        return [];
+    }
+}
+function get(obj, name) {
+    if (obj && typeof obj === "object")
+        return obj[name];
+    return undefined;
+}
+function inferType(obj) {
+    const declared = get(obj, "type");
+    if (typeof declared === "string" && VALID_TYPES.includes(declared.toLowerCase())) {
+        return declared.toLowerCase();
+    }
+    // SDK objects carry no `type` field; fall back to the constructor name.
+    const ctor = obj?.constructor?.name?.toLowerCase();
+    if (ctor && VALID_TYPES.includes(ctor))
+        return ctor;
+    return null;
+}
+export function normalizeQuestion(qid, obj) {
+    const type = inferType(obj);
+    if (type === null) {
+        throw new TypeError(`question "${qid}": cannot determine type. Expected a "type" key of ` +
+            `${VALID_TYPES.join(" | ")}, or a Choice/Score/Noul object.`);
+    }
+    return new Question(qid, type, get(obj, "instructions"), get(obj, "criteria"), obj);
+}
+export function normalizeQuestions(questions) {
+    return Object.entries(questions).map(([qid, obj]) => normalizeQuestion(qid, obj));
+}
+//# sourceMappingURL=question.js.map

package/dist/question.js.map

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

package/dist/record.d.ts

@@ -0,0 +1,66 @@
+/** Reading and writing `.jevl` records. See docs/specs/record-format-v1.md. */
+/**
+ * Local alias for the built-in utility type.
+ *
+ * This module exports a class named `Record`, which shadows TypeScript's
+ * `Record<K, V>` inside the file. Aliasing keeps the public class name while
+ * leaving the utility type usable.
+ */
+type Dict<V = unknown> = {
+    [key: string]: V;
+};
+export declare const FORMAT_VERSION = 1;
+/** A `.jevl` line is malformed, or its version is unreadable. */
+export declare class RecordFormatError extends Error {
+    constructor(message: string);
+}
+export interface RecordInit {
+    model: string;
+    state: unknown;
+    questions: Dict;
+    answers: Dict;
+    id?: string;
+    ts?: string;
+    usage?: Dict | null;
+    label?: Dict | null;
+    tags?: string[];
+    meta?: Dict;
+    extra?: Dict;
+}
+export declare class Record {
+    readonly model: string;
+    readonly state: unknown;
+    readonly questions: Dict;
+    readonly answers: Dict;
+    readonly id: string;
+    readonly ts: string;
+    readonly usage: Dict | null;
+    readonly label: Dict | null;
+    readonly tags: string[];
+    readonly meta: Dict;
+    readonly extra: Dict;
+    constructor(init: RecordInit);
+    /** Model-independent digest, used to pair across model versions. */
+    get requestId(): string;
+    toJSON(): Dict;
+    static fromJSON(raw: unknown, source?: string, lineNo?: number): Record;
+}
+/**
+ * Parse `.jevl` text into records.
+ *
+ * A line that fails to parse throws. Skipping silently would let a truncated
+ * golden set look like a passing one.
+ */
+export declare function parseRecords(text: string, source?: string): Record[];
+export declare function readRecords(path: string): Record[];
+export declare function writeRecords(path: string, records: Iterable<Record>): number;
+export declare function appendRecord(path: string, record: Record): void;
+/**
+ * Map record id -> Record, last occurrence winning.
+ *
+ * Re-recording a request appends rather than rewrites, so the last line for an
+ * id is the current answer.
+ */
+export declare function loadCassette(path: string): Map<string, Record>;
+export {};
+//# sourceMappingURL=record.d.ts.map

package/dist/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../src/record.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAM/E;;;;;;GAMG;AACH,KAAK,IAAI,CAAC,CAAC,GAAG,OAAO,IAAI;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,CAAA;CAAE,CAAC;AAE9C,eAAO,MAAM,cAAc,IAAI,CAAC;AAIhC,iEAAiE;AACjE,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACpB,KAAK,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,KAAK,CAAC,EAAE,IAAI,CAAC;CACd;AAMD,qBAAa,MAAM;IACjB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;gBAET,IAAI,EAAE,UAAU;IAc5B,oEAAoE;IACpE,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,MAAM,IAAI,IAAI;IAoBd,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,SAAa,EAAE,MAAM,SAAI,GAAG,MAAM;CAsDvE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAa,GAAG,MAAM,EAAE,CAiBxE;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAElD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,CAS5E;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAI9D"}

package/dist/record.js

@@ -0,0 +1,168 @@
+/** Reading and writing `.jevl` records. See docs/specs/record-format-v1.md. */
+import { appendFileSync, readFileSync, writeFileSync } from "node:fs";
+import { recordId, requestId } from "./canonical.js";
+export const FORMAT_VERSION = 1;
+const REQUIRED = ["v", "id", "ts", "model", "request", "answers"];
+/** A `.jevl` line is malformed, or its version is unreadable. */
+export class RecordFormatError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RecordFormatError";
+    }
+}
+function utcNow() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+export class Record {
+    model;
+    state;
+    questions;
+    answers;
+    id;
+    ts;
+    usage;
+    label;
+    tags;
+    meta;
+    extra;
+    constructor(init) {
+        this.model = init.model;
+        this.state = init.state;
+        this.questions = init.questions;
+        this.answers = init.answers;
+        this.ts = init.ts ?? utcNow();
+        this.usage = init.usage ?? null;
+        this.label = init.label ?? null;
+        this.tags = init.tags ?? [];
+        this.meta = init.meta ?? {};
+        this.extra = init.extra ?? {};
+        this.id = init.id || recordId(this.model, this.state, this.questions);
+    }
+    /** Model-independent digest, used to pair across model versions. */
+    get requestId() {
+        return requestId(this.state, this.questions);
+    }
+    toJSON() {
+        const out = {
+            v: FORMAT_VERSION,
+            id: this.id,
+            ts: this.ts,
+            model: this.model,
+            request: { state: this.state, questions: this.questions },
+            answers: this.answers,
+        };
+        if (this.usage !== null)
+            out["usage"] = this.usage;
+        if (this.label !== null)
+            out["label"] = this.label;
+        if (this.tags.length)
+            out["tags"] = [...this.tags];
+        if (Object.keys(this.meta).length)
+            out["meta"] = { ...this.meta };
+        // Unknown keys survive a read/write round trip.
+        for (const [k, v] of Object.entries(this.extra)) {
+            if (!(k in out))
+                out[k] = v;
+        }
+        return out;
+    }
+    static fromJSON(raw, source = "<memory>", lineNo = 0) {
+        const where = lineNo ? `${source}:${lineNo}` : source;
+        if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+            throw new RecordFormatError(`${where}: record must be a JSON object`);
+        }
+        const obj = raw;
+        const version = obj["v"];
+        if (version === undefined) {
+            throw new RecordFormatError(`${where}: missing required key 'v'`);
+        }
+        if (typeof version !== "number" || !Number.isInteger(version)) {
+            throw new RecordFormatError(`${where}: 'v' must be an integer, got ${JSON.stringify(version)}`);
+        }
+        if (version > FORMAT_VERSION) {
+            throw new RecordFormatError(`${where}: record format v${version} is newer than this reader ` +
+                `(v${FORMAT_VERSION}). Upgrade jevkit-core rather than guessing.`);
+        }
+        const missing = REQUIRED.filter((k) => !(k in obj));
+        if (missing.length) {
+            throw new RecordFormatError(`${where}: missing required key(s): ${missing.join(", ")}`);
+        }
+        const request = obj["request"];
+        if (!request || typeof request !== "object" || !("questions" in request)) {
+            throw new RecordFormatError(`${where}: 'request' must be an object with 'questions'`);
+        }
+        const req = request;
+        const known = new Set([...REQUIRED, "usage", "label", "tags", "meta"]);
+        const extra = {};
+        for (const [k, v] of Object.entries(obj)) {
+            if (!known.has(k))
+                extra[k] = v;
+        }
+        return new Record({
+            model: obj["model"],
+            state: req.state,
+            questions: req.questions,
+            answers: obj["answers"],
+            id: obj["id"],
+            ts: obj["ts"],
+            usage: obj["usage"] ?? null,
+            label: obj["label"] ?? null,
+            tags: obj["tags"] ?? [],
+            meta: obj["meta"] ?? {},
+            extra,
+        });
+    }
+}
+/**
+ * Parse `.jevl` text into records.
+ *
+ * A line that fails to parse throws. Skipping silently would let a truncated
+ * golden set look like a passing one.
+ */
+export function parseRecords(text, source = "<memory>") {
+    const out = [];
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        let raw;
+        try {
+            raw = JSON.parse(line);
+        }
+        catch (err) {
+            throw new RecordFormatError(`${source}:${i + 1}: invalid JSON: ${err.message}`);
+        }
+        out.push(Record.fromJSON(raw, source, i + 1));
+    }
+    return out;
+}
+export function readRecords(path) {
+    return parseRecords(readFileSync(path, "utf8"), path);
+}
+export function writeRecords(path, records) {
+    let count = 0;
+    const lines = [];
+    for (const record of records) {
+        lines.push(JSON.stringify(record.toJSON()));
+        count++;
+    }
+    writeFileSync(path, lines.length ? lines.join("\n") + "\n" : "", "utf8");
+    return count;
+}
+export function appendRecord(path, record) {
+    appendFileSync(path, JSON.stringify(record.toJSON()) + "\n", "utf8");
+}
+/**
+ * Map record id -> Record, last occurrence winning.
+ *
+ * Re-recording a request appends rather than rewrites, so the last line for an
+ * id is the current answer.
+ */
+export function loadCassette(path) {
+    const table = new Map();
+    for (const record of readRecords(path))
+        table.set(record.id, record);
+    return table;
+}
+//# sourceMappingURL=record.js.map

package/dist/record.js.map

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

package/dist/tokens.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Token budget estimation for jev requests.
+ *
+ * Jev ingests the state once and evaluates every question against it, so two
+ * budgets apply, both documented on the model card:
+ *
+ *     64k  state + every question combined
+ *     32k  state + the single longest question
+ *
+ * These are estimates. jevkit deliberately ships no tokenizer: TypeSafe does
+ * not publish which one Jev uses, and a confidently wrong count is worse than
+ * an honest approximation. The estimator errs conservative.
+ */
+export declare const TOTAL_BUDGET = 64000;
+export declare const STATE_BUDGET = 32000;
+/** Conservative token estimate for any JSON-serializable value. */
+export declare function estimateTokens(value: unknown): number;
+export interface BudgetReport {
+    stateTokens: number;
+    questionTokens: Record<string, number>;
+    longestQuestionId: string | null;
+    /** state + all questions. */
+    total: number;
+    /** state + the single longest question. */
+    longestPair: number;
+    overTotal: boolean;
+    overState: boolean;
+}
+export declare function checkBudget(state: unknown, questions: Record<string, unknown>): BudgetReport;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,eAAO,MAAM,YAAY,QAAS,CAAC;AACnC,eAAO,MAAM,YAAY,QAAS,CAAC;AAUnC,mEAAmE;AACnE,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGrD;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,YAAY,CA4Bd"}

package/dist/tokens.js

@@ -0,0 +1,53 @@
+/**
+ * Token budget estimation for jev requests.
+ *
+ * Jev ingests the state once and evaluates every question against it, so two
+ * budgets apply, both documented on the model card:
+ *
+ *     64k  state + every question combined
+ *     32k  state + the single longest question
+ *
+ * These are estimates. jevkit deliberately ships no tokenizer: TypeSafe does
+ * not publish which one Jev uses, and a confidently wrong count is worse than
+ * an honest approximation. The estimator errs conservative.
+ */
+import { canonicalJson } from "./canonical.js";
+export const TOTAL_BUDGET = 64_000;
+export const STATE_BUDGET = 32_000;
+// Bytes per token. English on BPE-family tokenizers runs ~4.0; 3.5 buys
+// headroom for punctuation-dense JSON without being absurd.
+const BYTES_PER_TOKEN = 3.5;
+function byteLength(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+/** Conservative token estimate for any JSON-serializable value. */
+export function estimateTokens(value) {
+    const text = typeof value === "string" ? value : canonicalJson(value);
+    return Math.max(1, Math.floor(byteLength(text) / BYTES_PER_TOKEN) + 1);
+}
+export function checkBudget(state, questions) {
+    const stateTokens = estimateTokens(state);
+    const questionTokens = {};
+    for (const [qid, q] of Object.entries(questions)) {
+        questionTokens[qid] = estimateTokens(q);
+    }
+    let longestQuestionId = null;
+    for (const [qid, n] of Object.entries(questionTokens)) {
+        if (longestQuestionId === null || n > questionTokens[longestQuestionId]) {
+            longestQuestionId = qid;
+        }
+    }
+    const questionSum = Object.values(questionTokens).reduce((a, b) => a + b, 0);
+    const total = stateTokens + questionSum;
+    const longestPair = longestQuestionId === null ? stateTokens : stateTokens + questionTokens[longestQuestionId];
+    return {
+        stateTokens,
+        questionTokens,
+        longestQuestionId,
+        total,
+        longestPair,
+        overTotal: total > TOTAL_BUDGET,
+        overState: longestPair > STATE_BUDGET,
+    };
+}
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC;AACnC,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC;AAEnC,wEAAwE;AACxE,4DAA4D;AAC5D,MAAM,eAAe,GAAG,GAAG,CAAC;AAE5B,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACzC,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,MAAM,IAAI,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IACtE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC;AACzE,CAAC;AAcD,MAAM,UAAU,WAAW,CACzB,KAAc,EACd,SAAkC;IAElC,MAAM,WAAW,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IAC1C,MAAM,cAAc,GAA2B,EAAE,CAAC;IAClD,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACjD,cAAc,CAAC,GAAG,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IAC1C,CAAC;IAED,IAAI,iBAAiB,GAAkB,IAAI,CAAC;IAC5C,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;QACtD,IAAI,iBAAiB,KAAK,IAAI,IAAI,CAAC,GAAG,cAAc,CAAC,iBAAiB,CAAE,EAAE,CAAC;YACzE,iBAAiB,GAAG,GAAG,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7E,MAAM,KAAK,GAAG,WAAW,GAAG,WAAW,CAAC;IACxC,MAAM,WAAW,GACf,iBAAiB,KAAK,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,WAAW,GAAG,cAAc,CAAC,iBAAiB,CAAE,CAAC;IAE9F,OAAO;QACL,WAAW;QACX,cAAc;QACd,iBAAiB;QACjB,KAAK;QACL,WAAW;QACX,SAAS,EAAE,KAAK,GAAG,YAAY;QAC/B,SAAS,EAAE,WAAW,GAAG,YAAY;KACtC,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "jevkit-core",
+  "version": "0.2.0",
+  "description": "Shared substrate for jevkit: the .jevl record format, canonical request digests, question normalization, and token budgets for TypeSafe's Jev.",
+  "keywords": [
+    "jev",
+    "typesafe",
+    "system-one",
+    "llm",
+    "calibration"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pjdurden/jevkit-js.git"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  }
+}