@qlm/learnlog-mcp 0.0.0-stage → 0.2.0

package/dist/tools/formats.js

@@ -0,0 +1,35 @@
+/** learnlog_formats: which exports the transformer converts, and what each one records, stage by stage. */
+import { VENDORED_FROM } from "../package.js";
+import { LEARNLOG_DRAFT, STAGES } from "../stages.js";
+import { engine, formatStages } from "../transformer.js";
+import { PREPRINT_DATASETS } from "./preprint.js";
+const UNIT = { dialogue: "transcript turns", summary: "participant summaries", assistance_events: "explicit lifecycle assertions", annotated_dialogue: "Sandpiper utterances" };
+export function learnlogFormats() {
+    return {
+        learnlog: LEARNLOG_DRAFT,
+        stages: STAGES,
+        formats: engine.ADAPTER_PROFILES.map((p) => {
+            const contract = engine.getSemanticContract(p.id);
+            return {
+                id: p.id,
+                name: p.name,
+                description: p.description,
+                observation_unit: UNIT[p.mode],
+                status: p.status,
+                what_one_record_is: contract.definition,
+                coverage: contract.coverage,
+                help_stages: formatStages(p),
+                ...(p.mode === "assistance_events" ? { also_recorded: "learner_response_observed: a later learner action the source asserts. It is kept apart from the draft's accepted stage." } : {}),
+                limitations: p.source.limitations,
+                sample: { bundled: true, file: `data/samples/${p.sampleName}`, summary: p.source.summary, license: p.source.license, citation: p.source.citation, source: p.source.url },
+                input: "CSV, a JSON array or JSON Lines; 1 to 5,000 rows; up to 2 MB (the transformer's limits)",
+            };
+        }),
+        preprint_datasets: PREPRINT_DATASETS,
+        transformer: { engine_version: engine.ENGINE_VERSION, vendored_from: `${VENDORED_FROM} demo/transformer/dist/engine.mjs`, license: "MIT" },
+        does_not_show: [
+            "Whether a product's own exports match these formats. The adapters cover published research releases, an explicit lifecycle contract and Sandpiper's documented utterance export, not vendor integrations.",
+            "Anything about your data. This lists formats only; run learnlog_transform or assistance_inventory on a file to see what it records.",
+        ],
+    };
+}

package/dist/tools/inventory.js

@@ -0,0 +1,179 @@
+/**
+ * assistance_inventory: what does this dataset actually record about help? Stage by stage, in the
+ * draft's six terms, with counts by source and what the counts can't show. It reads Learnlog
+ * records (made now from an export, or from a Learnlog file), or the preprint's three released
+ * datasets (see preprint.ts).
+ */
+import { Refusal, readLocalText } from "../files.js";
+import { LEARNLOG_DRAFT, NOT_RECORDED, STAGE_VERB, TRANSFORMER_EVENT_STAGE, byStage } from "../stages.js";
+import { engine } from "../transformer.js";
+import { preprintInventory } from "./preprint.js";
+import { runTransform } from "./transform.js";
+const inc = (c, k) => {
+    c[k] = (c[k] ?? 0) + 1;
+};
+async function recordsFrom(input) {
+    if (input.learnlog_path === undefined)
+        return (await runTransform(input)).records;
+    let doc;
+    try {
+        doc = engine.parseStrictJSON(readLocalText(input.learnlog_path, "learnlog_path", 50_000_000).replace(/^\ufeff/, ""));
+    }
+    catch (e) {
+        if (e instanceof Refusal)
+            throw e;
+        throw new Refusal(`${input.learnlog_path} isn't valid JSON: ${e.message}`);
+    }
+    try {
+        await engine.verify(doc);
+    }
+    catch (e) {
+        throw new Refusal(`${input.learnlog_path} does not verify, so it isn't inventoried: ${e.message} Run learnlog_validate for details.`);
+    }
+    return doc.records;
+}
+function sourceInventory(records) {
+    const h = records[0].header;
+    const entries = records.flatMap((r) => r.entries);
+    const data = entries.map((e) => e.event.data);
+    const mode = h.import_mode;
+    const base = { source: h.source_platform, ...(h.source_namespace ? { source_namespace: h.source_namespace } : {}), import_mode: mode, source_kind: h.source_kind, records: records.length, entries: entries.length };
+    const coverage = { help_coverage: h.assistance_coverage, mapping_coverage: h.semantic_mapping.coverage };
+    if (mode === "dialogue") {
+        const bySpeaker = {};
+        for (const d of data)
+            inc(bySpeaker, d.dialogue.role);
+        return {
+            ...base,
+            what_is_recorded: { unit: "dialogue turns", sessions: records.length, turns: entries.length, turns_by_speaker: bySpeaker },
+            stages: byStage(() => ({ status: NOT_RECORDED, note: "This source keeps who spoke and what they said. The adapter doesn't classify any turn as help, and a Tutor turn isn't a help event." })),
+            coverage,
+        };
+    }
+    if (mode === "annotated_dialogue") {
+        // Roles, annotator names and fields are any text the export uses, so the tallies have no prototype.
+        const tally = () => Object.create(null);
+        const byRole = tally();
+        const byAnnotator = tally();
+        const byField = tally();
+        const byAnnotatorAndField = tally();
+        const identifiedBy = tally();
+        let codes = 0;
+        let coded = 0;
+        for (const d of data) {
+            inc(byRole, d.utterance.role);
+            const annotations = d.inferred_annotations;
+            if (annotations.length)
+                coded++;
+            for (const a of annotations) {
+                if (a.identifiedBy !== undefined)
+                    inc(identifiedBy, a.identifiedBy);
+                for (const field of Object.keys(a.fields)) {
+                    codes++;
+                    inc(byAnnotator, a.annotator);
+                    inc(byField, field);
+                    inc((byAnnotatorAndField[a.annotator] ??= tally()), field);
+                }
+            }
+        }
+        return {
+            ...base,
+            what_is_recorded: {
+                unit: "utterances",
+                sessions: records.length,
+                utterances: entries.length,
+                turns_by_role: byRole,
+                inferred_codes: {
+                    basis: "inferred",
+                    note: "Annotation codes are an annotator's inferred assertions about utterances, not help events. They aren't counted at any stage, and identifiedBy is counted only where the export carries it.",
+                    codes,
+                    utterances_with_codes: coded,
+                    by_annotator: byAnnotator,
+                    by_field: byField,
+                    by_annotator_and_field: byAnnotatorAndField,
+                    identified_by: identifiedBy,
+                },
+            },
+            stages: byStage(() => ({ status: NOT_RECORDED, note: "This export keeps who spoke and what they said. Its annotation codes are inferred assertions by an annotator, so none of them records help being asked for, offered, generated, sent, shown or accepted." })),
+            coverage,
+        };
+    }
+    if (mode === "summary") {
+        const conditions = {};
+        const use = {};
+        for (const d of data) {
+            const ev = d.help_evidence;
+            inc(conditions, ev.condition);
+            inc(use, ev.actual_help_use);
+        }
+        return {
+            ...base,
+            what_is_recorded: { unit: "participant summaries", participants: entries.length, assigned_condition: conditions, actual_help_use: use },
+            stages: byStage(() => ({ status: NOT_RECORDED, note: "This table gives each participant's assigned help condition. Being assigned to a condition doesn't show that help was asked for, offered or shown." })),
+            coverage,
+        };
+    }
+    const types = {};
+    const capture = {};
+    for (const d of data) {
+        inc(types, d.lifecycle.event_type);
+        inc(capture, d.assistance_context.capture);
+    }
+    const stages = byStage((stage) => {
+        const type = Object.keys(TRANSFORMER_EVENT_STAGE).find((t) => TRANSFORMER_EVENT_STAGE[t] === stage);
+        if (!type)
+            return { status: NOT_RECORDED, note: "The transformer's lifecycle input has no event type for this stage, so nothing here can record it." };
+        const n = types[type] ?? 0;
+        if (n === 0)
+            return { status: NOT_RECORDED, note: `No ${type} assertions in this file. Not recorded is not proof that no help was ${STAGE_VERB[stage]}: capture of this stage isn't established.` };
+        return { status: "recorded", count: n, note: `${n} ${type} assertions in this file. Each is the source's assertion, and a count isn't a total unless capture of this stage was complete.` };
+    });
+    return {
+        ...base,
+        what_is_recorded: { unit: "lifecycle assertions", assertions: entries.length, event_types: types },
+        stages,
+        learner_response_observed: types.learner_response_observed ?? 0,
+        capture_declared: capture,
+        coverage,
+    };
+}
+export const RECORD_LIMITS = [
+    "An inventory isn't a help rate: there is no denominator of opportunities, time or learners.",
+    "A missing record isn't proof that no help was given. Not recorded is never the same as none.",
+    "Each stage is its own observation. A request doesn't show that help was generated, and a display doesn't show that it was read.",
+    "Counts from different sources measure different things and can't be pooled into one number.",
+];
+export async function assistanceInventoryOfRecords(input) {
+    const records = await recordsFrom(input);
+    const groups = new Map();
+    for (const r of records) {
+        const key = JSON.stringify([r.header.source_platform, r.header.source_namespace ?? null]);
+        groups.set(key, [...(groups.get(key) ?? []), r]);
+    }
+    return {
+        kind: "learnlog_records",
+        learnlog: LEARNLOG_DRAFT,
+        sources: [...groups.values()].map(sourceInventory),
+        cannot_conclude: RECORD_LIMITS,
+        does_not_show: [
+            "Help outside the recorded source: other apps, devices, people or AI tools.",
+            "Whether any help worked. These are records of help, not of learning.",
+            "Learner identities. Learner IDs are pseudonyms and no rows are listed.",
+        ],
+    };
+}
+/** Chooses what to inventory: Learnlog records, the preprint's files, or (with nothing given) the published figures. */
+export async function assistanceInventory(input) {
+    const records = ["format", "path", "use_sample", "learnlog_path"].some((k) => input[k] !== undefined);
+    const preprint = ["zenodo_zip", "idetrace_json", "assistments_csv"].some((k) => input[k] !== undefined);
+    if (records && preprint)
+        throw new Refusal("Ask about one thing at a time: either Learnlog records (format with path or use_sample, or learnlog_path) or the preprint's files (zenodo_zip, idetrace_json, assistments_csv).");
+    if (records) {
+        if (input.learnlog_path === undefined && input.format === undefined)
+            throw new Refusal("Name the export's format (see learnlog_formats), or give learnlog_path for a Learnlog file.");
+        if (input.learnlog_path !== undefined && input.format !== undefined)
+            throw new Refusal("Give either learnlog_path or format with path or use_sample, not both.");
+        return assistanceInventoryOfRecords(input);
+    }
+    return preprintInventory(input);
+}

package/dist/tools/learning-graph.js

@@ -0,0 +1,111 @@
+/** qlm_learning_graph: what comes before or after a LabPath activity (mode), with its standards. */
+import { Refusal } from "../files.js";
+import { ANSWER_BUDGET, answerSize } from "../respond.js";
+import { datasetInfo } from "./qlm-datasets.js";
+import { worldLink } from "./worlds.js";
+export const EDGE_KINDS = ["prerequisite", "labpath-sequence", "reinforcement", "transfer", "extension"];
+/** Closest links first; within a kind, the export's own order. */
+const KIND_ORDER = ["prerequisite", "labpath-sequence", "reinforcement", "extension", "transfer"];
+const rank = (e) => KIND_ORDER.indexOf(e.kind);
+/** An edge keeps its first CONCEPTS_SHOWN concepts; concepts_total says how many it has when that's more. */
+export const CONCEPTS_SHOWN = 8;
+export const DEFAULT_LIMIT = 10;
+const edge = (e) => {
+    const concepts = Array.isArray(e.concepts) ? e.concepts : [];
+    return {
+        from: e.fromModeId,
+        to: e.toModeId,
+        kind: e.kind,
+        priority: e.priority,
+        concepts: concepts.slice(0, CONCEPTS_SHOWN),
+        ...(concepts.length > CONCEPTS_SHOWN ? { concepts_total: concepts.length } : {}),
+        misconceptions: e.misconceptions,
+        teacher_facing_reason: e.teacherFacingReason,
+        student_facing_reason: e.studentFacingReason,
+    };
+};
+export async function qlmLearningGraph(input, client) {
+    if ((input.mode_id === undefined) === (input.standard === undefined))
+        throw new Refusal("Give either mode_id or standard, not both and not neither.");
+    const [graph, standards] = await Promise.all([client.get("learning-graph"), client.get("standards")]);
+    const edges = graph.learningGraph;
+    const rows = standards.standardsAlignment;
+    const known = new Set([...edges.flatMap((e) => [e.fromModeId, e.toModeId]), ...rows.map((s) => s.modeId)]);
+    let modes;
+    if (input.mode_id !== undefined) {
+        const id = input.mode_id;
+        if (!known.has(id)) {
+            const close = [...known].filter((m) => m.includes(id.toLowerCase())).slice(0, 10);
+            throw new Refusal(`No LabPath mode "${id}".${close.length ? ` Close matches: ${close.join(", ")}` : ""}`);
+        }
+        modes = [id];
+    }
+    else {
+        const code = input.standard.toLowerCase();
+        modes = [...new Set(rows.filter((s) => String(s.code).toLowerCase() === code).map((s) => s.modeId))];
+        if (!modes.length)
+            throw new Refusal(`No LabPath mode is aligned to the standard ${input.standard}.`);
+    }
+    const kinds = new Set(input.kinds ?? EDGE_KINDS);
+    const direction = input.direction ?? "both";
+    const asked = input.limit ?? DEFAULT_LIMIT;
+    const lists = {};
+    for (const side of ["before", "after"]) {
+        if (direction !== "both" && direction !== side)
+            continue;
+        lists[side] = edges.filter((e) => kinds.has(e.kind) && modes.includes((side === "before" ? e.toModeId : e.fromModeId))).sort((a, b) => rank(a) - rank(b));
+    }
+    const build = (limit) => {
+        const out = { modes };
+        const truncated = {};
+        const linked = new Set();
+        for (const side of ["before", "after"]) {
+            const list = lists[side];
+            if (!list)
+                continue;
+            if (list.length > limit)
+                truncated[side] = list.length;
+            out[side] = list.slice(0, limit).map((e) => {
+                for (const m of [e.fromModeId, e.toModeId])
+                    if (!modes.includes(m))
+                        linked.add(m);
+                return edge(e);
+            });
+        }
+        if (Object.keys(truncated).length)
+            out.truncated = truncated;
+        if (![out.before, out.after].some((l) => Array.isArray(l) && l.length))
+            out.note = `${modes.join(", ")} has no edges of the kinds asked for in this direction.`;
+        out.standards = Object.fromEntries(modes.map((m) => [m, rows.filter((s) => s.modeId === m).map((s) => ({ code: s.code, description: s.description, gradeBand: s.gradeBand, disciplinaryCore: s.disciplinaryCore, discipline: s.discipline }))]));
+        out.linked_mode_standards = Object.fromEntries([...linked].map((m) => [m, rows.filter((s) => s.modeId === m).map((s) => s.code)]));
+        const links = [...modes, ...linked].map(worldLink);
+        out.worlds = Object.fromEntries(links.filter((w) => w.url !== null).map((w) => [w.id, w]));
+        const unknown = links.filter((w) => w.url === null).map((w) => w.id);
+        if (unknown.length)
+            out.worlds_without_a_known_page = unknown;
+        return out;
+    };
+    // Fit the answer: lower the per-direction limit until it does, and say so.
+    let used = asked;
+    let out = build(used);
+    while (used > 1 && answerSize({ ...out, does_not_show: ["x"] }) > ANSWER_BUDGET - 2_000) {
+        used = Math.floor(used * 0.75);
+        out = build(used);
+    }
+    if (used < asked)
+        out.limit_lowered = { asked, used, why: `${asked} links per direction would not fit in one answer, so ${used} are shown. Ask for one direction or fewer kinds to see others.` };
+    const priorities = new Set(edges.map((e) => e.priority));
+    if (priorities.size === 1)
+        out.priority_note = `Every edge in the export has priority "${String([...priorities][0])}", so priority doesn't rank these links.`;
+    const byKind = {};
+    for (const e of edges)
+        byKind[e.kind] = (byKind[e.kind] ?? 0) + 1;
+    out.dataset = { ...datasetInfo(graph, "learning-graph"), standards_source: datasetInfo(standards, "standards").source, edges_in_export: edges.length, edges_by_kind: byKind, standards_rows_in_export: rows.length };
+    out.does_not_show = [
+        "Whether a particular student needs a step. This is LabPath's designed sequence, not evidence about a learner.",
+        "How strong a link is. Priority is the export's coarse band of a tuned ranking, not a measured effect.",
+        "An official alignment. Standards are LabPath's own mapping of its modes to NGSS-style codes, not a standards body's.",
+        "The misconceptions themselves. Edges carry misconception ids; look them up with qlm_misconceptions.",
+    ];
+    return out;
+}

package/dist/tools/misconceptions.js

@@ -0,0 +1,54 @@
+/** qlm_misconceptions: search QLM's public misconception dataset (CC BY 4.0). */
+import { datasetInfo } from "./qlm-datasets.js";
+import { worldLinks } from "./worlds.js";
+const TEXT = ["id", "name", "subdomain", "studentBelief", "scientificReality", "counterexample", "teacherIntervention"];
+const KEEP = ["id", "tier", "domain", "subdomain", "gradeBands", "name", "studentBelief", "scientificReality", "counterexample", "teacherIntervention", "researchSource", "severity", "frequency", "persistence", "modes"];
+const placeholder = (v) => typeof v === "string" && v.startsWith("[");
+const lc = (v) => (typeof v === "string" ? v.toLowerCase() : "");
+const bands = (r) => (Array.isArray(r.gradeBands) ? r.gradeBands : []);
+/** A record as returned: never an evaluation-tier record's trigger patterns or diagnostic question. */
+function shown(r) {
+    const out = Object.fromEntries(KEEP.map((k) => [k, r[k]]));
+    out.worlds = worldLinks(r.modes);
+    if (r.tier === "evaluation") {
+        out.withheld = "triggerPatterns and diagnosticQuestion are withheld for evaluation-tier records, for benchmark integrity.";
+        return out;
+    }
+    if (placeholder(r.diagnosticQuestion))
+        out.withheld = "The diagnostic question is embedded in its residency scenario, not in the export.";
+    else
+        out.diagnosticQuestion = r.diagnosticQuestion;
+    out.triggerPatterns = Array.isArray(r.triggerPatterns) ? r.triggerPatterns.filter((p) => !placeholder(p)) : [];
+    return out;
+}
+const tally = (values) => {
+    const c = {};
+    for (const v of values)
+        c[v] = (c[v] ?? 0) + 1;
+    return c;
+};
+export async function qlmMisconceptions(input, client) {
+    const body = await client.get("misconceptions");
+    const all = body.misconceptions.filter((r) => typeof r === "object" && r !== null);
+    const words = lc(input.search).split(/\s+/).filter(Boolean);
+    const matches = all.filter((r) => (!input.id || lc(r.id) === lc(input.id)) &&
+        (!input.domain || lc(r.domain) === lc(input.domain)) &&
+        (!input.grade_band || bands(r).some((b) => lc(b) === lc(input.grade_band))) &&
+        words.every((w) => TEXT.some((k) => lc(r[k]).includes(w))));
+    const limit = input.limit ?? 10;
+    return {
+        dataset: { ...datasetInfo(body, "misconceptions"), records_in_export: all.length, records_by_tier: tally(all.map((r) => String(r.tier))) },
+        total_matching: matches.length,
+        returned: Math.min(limit, matches.length),
+        misconceptions: matches.slice(0, limit).map(shown),
+        worlds_note: "Each misconception's worlds are the LabPath worlds that work on it, with their public pages. Suggest them by name and link.",
+        ...(matches.length === 0 ? { note: "No misconception in the export matches. Try fewer words, or see the domains and grade bands listed under available." } : {}),
+        available: { domains: tally(all.map((r) => String(r.domain))), grade_bands: tally(all.flatMap(bands)) },
+        does_not_show: [
+            "Whether any student holds one of these. They are curated, research-based descriptions of common misconceptions, not observations of a learner.",
+            "Held-out records, kept back for benchmark integrity; they aren't in the export at all.",
+            "Evaluation-tier trigger patterns and diagnostic questions, withheld for benchmark integrity.",
+            "How often a misconception occurs in your setting. Frequency, persistence and severity are the dataset's research-based bands.",
+        ],
+    };
+}

package/dist/tools/preprint.js

@@ -0,0 +1,241 @@
+/**
+ * The three released datasets of the Learnlog preprint (v0.6), "Preserving assistance meaning in
+ * cross-source learning analytics". Their learner records are not bundled: the tool reads the
+ * user's own copies, recomputes the preprint's counts with the published rules (episodes.ts), and,
+ * when a file is the exact release the preprint pinned, compares every number with the published
+ * aggregate outputs bundled in data/preprint and vendor/transformer.
+ */
+import tableTwo from "../../vendor/transformer/cross-source-analysis-data.mjs";
+import { analyzeAssistments, assistmentsBySkill, analyzeIdetrace, analyzeZenodo, crossSourceEpisodes } from "../episodes.js";
+import { Refusal, localFile, readLocalBytes } from "../files.js";
+import { VENDORED_FROM, readJsonFile } from "../package.js";
+import { LEARNLOG_DRAFT, NOT_RECORDED } from "../stages.js";
+export const PINNED = {
+    zenodo: "5527127f0a3c939601b17ef207ef8b34df7cad9159c9617f879efbf4e989d499",
+    idetrace: "09972201c16a9f6def7d1e25a9b9e6827994601d720a37696afb0927168befc8",
+    assistments: "1d06aee9e649c5ba9db49052fe9a86e68d0c3ccb4709a7487289d7721f5464db",
+};
+export const PREPRINT_DATASETS = [
+    {
+        id: "zenodo.17551130",
+        argument: "zenodo_zip",
+        name: "JetBrains Academy next-step hint study (Zenodo 17551130 v1)",
+        records: "Hint requests, errors and displays inside 1,050 HTML scenario reports, plus a raw IDE activity file that isn't linked to them",
+        license: "CC BY 4.0",
+        bundled: false,
+        why_not_bundled: "QLM's releases carry only aggregate counts from this dataset, never its learner records (THIRD_PARTY_DATA.md).",
+        get_it: "https://zenodo.org/records/17551130 (ai_hints_interaction.zip)",
+        pinned_sha256: PINNED.zenodo,
+    },
+    {
+        id: "tutortrace.deployment8",
+        argument: "idetrace_json",
+        name: "TutorTrace / IDETrace, deployment 8",
+        records: "Chat queries and responses, code edits and test results in an instrumented programming environment",
+        license: "CC BY 4.0, as declared in its pinned Croissant metadata (GitHub reports no repository license)",
+        bundled: false,
+        why_not_bundled: "No permission to redistribute the raw payload is inferred. Reading it here needs allow_idetrace_research: true, the same opt-in the preprint's pipeline asks for.",
+        get_it: "https://github.com/divadbaroon/TutorTrace_dataset_and_benchmark/tree/bc7990370da18a611a122255ebc3e475bd8a3fc6 (dataset/raw_telemetry/deployment_8.json)",
+        pinned_sha256: PINNED.idetrace,
+    },
+    {
+        id: "assistments.2012-13",
+        argument: "assistments_csv",
+        name: "ASSISTments 2012-13 School Data with Affect",
+        records: "One row per problem: hints asked, whether the last hint was reached, the first action, scaffolding, and four affect detector confidences",
+        license: "ASSISTments terms of use",
+        bundled: false,
+        why_not_bundled: "The data were provided by the ASSISTments TestBed (WPI) and are not redistributed. Get them from ASSISTments under its terms of use.",
+        get_it: "https://sites.google.com/site/assistmentsdata/datasets/2012-13-school-data-with-affect",
+        pinned_sha256: PINNED.assistments,
+    },
+];
+export const PUBLISHED = {
+    tableTwo,
+    crossSource: readJsonFile("data/preprint/cross_source_episodes.json"),
+    assistments: readJsonFile("data/preprint/assistments_episodes.json"),
+};
+/** Every leaf of the published value against the recomputed value at the same path, both ways. */
+export function compare(published, recomputed) {
+    const mismatches = [];
+    let n = 0;
+    const walk = (p, r, path) => {
+        if (typeof p === "object" && p !== null && typeof r === "object" && r !== null && Array.isArray(p) === Array.isArray(r)) {
+            const keys = new Set([...Object.keys(p), ...Object.keys(r)]);
+            for (const k of keys)
+                walk(p[k], r[k], Array.isArray(p) ? `${path}[${k}]` : `${path}.${k}`);
+            return;
+        }
+        n++;
+        if (p !== r)
+            mismatches.push({ path, published: p ?? null, recomputed: r ?? null });
+    };
+    walk(published, recomputed, "$");
+    return { numbers_compared: n, matches: mismatches.length === 0, mismatches };
+}
+const pick = (o, keys) => Object.fromEntries(keys.map((k) => [k, o[k]]));
+const sourceRow = (p, id) => p.tableTwo.sources.find((s) => s.source_id === id);
+const n = (x) => x;
+export function zenodoStages(inv, ep) {
+    const labels = inv.native_log_label_counts;
+    const outcomes = ep.outcomes;
+    return {
+        requested: { status: "recorded", count: n(ep.requests), note: "Get Hint and Retry clicks (Table 2 inventory rule). Each report holds one." },
+        offered: NOT_RECORDED,
+        generated: { status: "not mapped", native_rows: pick(labels, ["Code hint generated", "Text hint generated"]), note: "The release logs generation rows, but the preprint's rules don't link them to requests, so no count is given for this stage." },
+        transmitted: NOT_RECORDED,
+        displayed: { status: "recorded by the episode rule", count: n(ep.shown), of_requests: n(ep.requests), not_displayed: n(ep.not_shown), not_displayed_with_error: outcomes.not_shown_error ?? 0, note: "A banner shown, or the code hint revealed or accepted, after the request. Links between stages come from the rule; the source declares none." },
+        accepted: { status: "recorded by the episode rule", count: outcomes.shown_acted_accepted ?? 0, revealed_only: outcomes.shown_acted_revealed_not_accepted ?? 0, note: "The product's 'Code hint is accepted' action. Accepting doesn't show use or learning." },
+        never_asked: "not in the release: it contains only request episodes, so going without help can't be counted here",
+    };
+}
+export function idetraceStages(ep) {
+    return {
+        requested: { status: "recorded", count: n(ep.requests), note: "CHAT_QUERY events (Table 2 inventory rule)." },
+        offered: NOT_RECORDED,
+        generated: { status: "not mapped", note: "The release logs CHAT_RESPONSE events; the episode rule reads a response as a display, not as its own generated stage." },
+        transmitted: NOT_RECORDED,
+        displayed: { status: "recorded by the episode rule", count: n(ep.shown), of_requests: n(ep.requests), note: "No separate display event exists: a response before the next query is counted as a display. A reply that was itself an error would still count." },
+        accepted: NOT_RECORDED,
+        never_asked: { records: n(ep.records), records_never_asked: n(ep.records_never_asked), note: "Learner records, which may not be people: the source's population descriptions conflict." },
+    };
+}
+export function assistmentsStages(a) {
+    const ep = a.episodes;
+    const hints = (ep["requested; hints short of the answer"] ?? 0) + (ep["requested; hints to the answer (bottom-out)"] ?? 0);
+    const steps = ep["requested; asked for steps (scaffolding)"] ?? 0;
+    const checks = a.checks;
+    return {
+        requested: { status: "recorded", count: hints + steps, with_hints: hints, asked_for_steps: steps, hints_to_the_answer: ep["requested; hints to the answer (bottom-out)"] ?? 0, note: "Counted by main problem. The last hint 'will generally contain the problem's answer' (ASSISTments' own description)." },
+        offered: { status: "candidates only", count: ep["not requested; system gave steps after a wrong first answer"] ?? 0, note: "Steps the system likely gave after a wrong first answer, by rule. The release logs no initiation event and keeps only the first action, so these aren't established offers." },
+        generated: NOT_RECORDED,
+        transmitted: NOT_RECORDED,
+        displayed: "not recorded as its own event (asking for a hint shows it, but display isn't logged)",
+        accepted: NOT_RECORDED,
+        never_asked: { students: n(a.students), never_asked_on_main_problems: n(a.students) - n(a.students_who_ever_requested), never_asked_anywhere_including_hints_inside_steps: n(a.students) - checks.students_who_ever_requested_including_hints_inside_scaffolding },
+        inferred: "The four affect values are detector inferences on every row, not observations. Whether hint use was among the detectors' inputs isn't known.",
+    };
+}
+const LIMIT = {
+    inventory: "1,109 is an inventory of selected released request records. It isn't a request rate, a dose of help or a learning effect.",
+    denominator: "There is no shared denominator of opportunities, time or learners, so rates can't be compared across the releases.",
+    rules: "Links between stages come from the scripts' rules (Supplement S1); the sources declare none. Display shares are provisional.",
+    missing: "A missing record isn't proof that no help was given. Not recorded is never the same as none.",
+    pooling: "Pooling the two programming releases hides that IDETrace has no separate display record.",
+    assistmentsBeside: "ASSISTments is counted by problem and is set beside the other two, never pooled with them.",
+    assistmentsAlone: "ASSISTments is counted by problem: a main problem is one opportunity, not one request event.",
+    review: "The mappings were written and audited by software agents; independent human review of them is still pending.",
+};
+export const PREPRINT_LIMITS = [LIMIT.inventory, LIMIT.denominator, LIMIT.rules, LIMIT.missing, LIMIT.pooling, LIMIT.assistmentsBeside, LIMIT.review];
+/** The cautions that apply to the files actually given. */
+function limitsFor(programming, assistments) {
+    return [
+        ...(programming ? [LIMIT.inventory, LIMIT.denominator] : []),
+        LIMIT.rules,
+        LIMIT.missing,
+        ...(programming ? [LIMIT.pooling] : []),
+        ...(assistments ? [programming ? LIMIT.assistmentsBeside : LIMIT.assistmentsAlone] : []),
+        LIMIT.review,
+    ];
+}
+const NOT_ESTABLISHED = {
+    actual_request_total: "not established: release selection and capture completeness are unknown",
+    request_rate: "not established: no comparable denominator of exposure or opportunity",
+    request_to_display_rate: "provisional only: links come from episode rules, not the sources",
+    learning_effect: "not estimated: a count of help records isn't an outcome",
+};
+const DOES_NOT_SHOW = [
+    "Any learner row, identity, dialogue or code. Only counts leave the files.",
+    "Help outside the instrumented tools: other apps, people or AI.",
+    "Whether any help worked.",
+];
+const GB = 1_000_000_000;
+export async function preprintInventory(input, pins = PINNED, published = PUBLISHED) {
+    if (input.idetrace_json !== undefined && input.allow_idetrace_research !== true) {
+        throw new Refusal("Reading the IDETrace file needs allow_idetrace_research: true. It holds learner telemetry whose redistribution terms are unclear, so the preprint's pipeline asks for the same explicit opt-in. Only counts are returned.");
+    }
+    const z = input.zenodo_zip === undefined ? undefined : analyzeZenodo(readLocalBytes(input.zenodo_zip, "zenodo_zip", 2 * GB));
+    const i = input.idetrace_json === undefined ? undefined : analyzeIdetrace(readLocalBytes(input.idetrace_json, "idetrace_json", GB).toString("utf8"));
+    const aPath = input.assistments_csv === undefined ? undefined : localFile(input.assistments_csv, "assistments_csv", 100 * GB).path;
+    const a = aPath === undefined ? undefined : await analyzeAssistments(aPath);
+    const inputs = {};
+    const inventory = {};
+    const stages = {};
+    const comparison = {};
+    const episodes = z || i ? crossSourceEpisodes(z, i) : undefined;
+    if (z) {
+        const pinned = z.input_sha256 === pins.zenodo;
+        inputs.zenodo = { sha256: z.input_sha256, is_the_preprint_release: pinned };
+        inventory.zenodo = z.inventory;
+        stages.zenodo = zenodoStages(z.inventory, z.episodes);
+        const cs = published.crossSource;
+        comparison.zenodo = pinned
+            ? compare({ table_2: pick(sourceRow(published, "zenodo.17551130"), Object.keys(z.inventory)), table_4: cs.zenodo, checks: pick(cs.checks, Object.keys(z.checks)) }, { table_2: z.inventory, table_4: z.episodes, checks: z.checks })
+            : "not compared: this file isn't the release the preprint pinned, so its numbers aren't the preprint's";
+    }
+    if (i) {
+        const pinned = i.input_sha256 === pins.idetrace;
+        inputs.idetrace = { sha256: i.input_sha256, is_the_preprint_release: pinned };
+        inventory.idetrace = i.inventory;
+        stages.idetrace = idetraceStages(i.episodes);
+        const cs = published.crossSource;
+        comparison.idetrace = pinned
+            ? compare({ table_2: pick(sourceRow(published, "tutortrace.deployment8"), Object.keys(i.inventory)), table_4: cs.idetrace, checks: pick(cs.checks, Object.keys(i.checks)) }, { table_2: i.inventory, table_4: i.episodes, checks: i.checks })
+            : "not compared: this file isn't the release the preprint pinned, so its numbers aren't the preprint's";
+    }
+    if (z && i) {
+        inventory.total_request_observations = z.inventory.assistance_request_observations + i.inventory.assistance_request_observations;
+        if (z.input_sha256 === pins.zenodo && i.input_sha256 === pins.idetrace) {
+            comparison.pooled = compare({ table_2_total: published.tableTwo.aggregate.assistance_request_observations, table_4_pooled: published.crossSource.pooled }, { table_2_total: inventory.total_request_observations, table_4_pooled: episodes.pooled });
+        }
+    }
+    if (a) {
+        const pinned = a.input_sha256 === pins.assistments;
+        inputs.assistments = { sha256: a.input_sha256, is_the_preprint_release: pinned };
+        stages.assistments = assistmentsStages(a);
+        comparison.assistments = pinned ? compare(published.assistments, a) : "not compared: this file isn't the release the preprint pinned, so its numbers aren't the preprint's";
+    }
+    if (!z && !i && !a)
+        return publishedFigures(published);
+    return {
+        kind: "recomputed from your files",
+        learnlog: LEARNLOG_DRAFT,
+        inputs,
+        ...(z || i ? { inventory_table_2: { ...inventory, ...NOT_ESTABLISHED }, episodes_table_4: episodes } : {}),
+        ...(a ? { assistments_table_4: a, assistments_requests_by_skill: await assistmentsBySkill(aPath) } : {}),
+        stages,
+        comparison_with_preprint: comparison,
+        rules: RULES,
+        cannot_conclude: limitsFor(Boolean(z || i), Boolean(a)),
+        does_not_show: DOES_NOT_SHOW,
+    };
+}
+const RULES = {
+    inventory: "aggregate.py native filters: Zenodo Log rows 'Hint button is clicked' or 'Hint retry is clicked'; IDETrace CHAT_QUERY events. This tool recomputes the counts; it doesn't rerun the capture-schema validation and xAPI/Caliper round trips the Python pipeline also performs.",
+    episodes: "research/learnlog-episodes/cross_source.py and assistments_episodes.py at preprint v0.6 (paste rule by timestamp), ported to TypeScript and tested against the Python on the same files.",
+    source: VENDORED_FROM,
+};
+/** The published figures, bundled with this package, when no files are given. */
+export function publishedFigures(published = PUBLISHED) {
+    const cs = published.crossSource;
+    const zRow = sourceRow(published, "zenodo.17551130");
+    const iRow = sourceRow(published, "tutortrace.deployment8");
+    return {
+        kind: "published figures, not recomputed",
+        note: "These are the preprint's published aggregate outputs, bundled with this package. Nothing was recomputed in this call. To recompute them, give your own copies of the files (zenodo_zip, idetrace_json with allow_idetrace_research: true, assistments_csv).",
+        learnlog: LEARNLOG_DRAFT,
+        inventory_table_2: {
+            zenodo: pick(zRow, ["input_sha256", "source_file_count", "native_input_count", "native_assistance_log_count", "native_log_label_counts", "assistance_request_observations", "help_request_subtypes"]),
+            idetrace: pick(iRow, ["input_sha256", "source_file_count", "native_input_count", "native_event_label_counts", "assistance_request_observations"]),
+            total_request_observations: published.tableTwo.aggregate.assistance_request_observations,
+            ...NOT_ESTABLISHED,
+        },
+        episodes_table_4: cs,
+        assistments_table_4: published.assistments,
+        stages: { zenodo: zenodoStages(zRow, cs.zenodo), idetrace: idetraceStages(cs.idetrace), assistments: assistmentsStages(published.assistments) },
+        datasets: PREPRINT_DATASETS,
+        rules: RULES,
+        cannot_conclude: PREPRINT_LIMITS,
+        does_not_show: DOES_NOT_SHOW,
+    };
+}