@qlm/learnlog-mcp 0.0.0-stage → 0.2.0

package/dist/tools/qlm-datasets.js

@@ -0,0 +1,56 @@
+/**
+ * QLM's public LabPath datasets, read from play.quantumlearningmachines.com: GET only, one host, a
+ * timeout, no redirects, and each dataset fetched at most once per process (kept in memory).
+ * Source: qlm-games src/app/api/labpath/dataset-export/route.ts.
+ */
+import { Refusal } from "../files.js";
+export const DATASET_URL = "https://play.quantumlearningmachines.com/api/labpath/dataset-export";
+export const ARCHIVE = "QLM LabPath Dataset v1.0, Zenodo, https://doi.org/10.5281/zenodo.21800324 (CC BY 4.0; the archived v1.0 holds the 423 released misconceptions)";
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const LIST = { misconceptions: "misconceptions", "learning-graph": "learningGraph", standards: "standardsAlignment" };
+export class DatasetClient {
+    fetchImpl;
+    cache = new Map();
+    constructor(fetchImpl = fetch) {
+        this.fetchImpl = fetchImpl;
+    }
+    get(dataset) {
+        let p = this.cache.get(dataset);
+        if (!p) {
+            p = this.load(dataset);
+            this.cache.set(dataset, p);
+            p.catch(() => this.cache.delete(dataset));
+        }
+        return p;
+    }
+    async load(dataset) {
+        const url = `${DATASET_URL}?dataset=${dataset}`;
+        let res;
+        try {
+            res = await this.fetchImpl(url, { method: "GET", redirect: "error", headers: { accept: "application/json" }, signal: AbortSignal.timeout(30_000) });
+        }
+        catch (e) {
+            throw new Refusal(`Couldn't reach play.quantumlearningmachines.com: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        if (res.status !== 200)
+            throw new Refusal(`The LabPath dataset service answered HTTP ${res.status}.`);
+        const text = await res.text();
+        if (text.length > 50_000_000)
+            throw new Refusal("The LabPath dataset service's answer was too large.");
+        let body = null;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            // checked below
+        }
+        if (!isObj(body) || !isObj(body._meta) || !Array.isArray(body[LIST[dataset]]))
+            throw new Refusal(`The service's answer wasn't the ${dataset} export this tool expects.`);
+        return body;
+    }
+}
+/** The dataset's own description, for citing it. */
+export function datasetInfo(body, dataset) {
+    const meta = body._meta;
+    return { source: `${DATASET_URL}?dataset=${dataset}`, version: meta.version, license: meta.license, citation: meta.citation, exported_at: meta.exportedAt, archived: ARCHIVE };
+}

package/dist/tools/transform.js

@@ -0,0 +1,61 @@
+/** learnlog_transform: a local export into Learnlog records, with source and capture details kept. */
+import { basename } from "node:path";
+import { Refusal, readLocalText } from "../files.js";
+import { ANSWER_BUDGET, answerSize } from "../respond.js";
+import { engine, formatStages, profileOf, sourceWarnings, unknownsOf } from "../transformer.js";
+/** Runs the transformer on a local file or the format's bundled sample. Nothing is written. */
+export async function runTransform(input) {
+    const p = profileOf(input.format);
+    if ((input.path === undefined) === (input.use_sample !== true))
+        throw new Refusal("Give either path or use_sample: true, not both and not neither.");
+    const text = input.path === undefined ? engine.getSample(p.id) : readLocalText(input.path, "path", 2_000_000);
+    try {
+        return await engine.transform({ profileId: p.id, text, tenant: input.tenant ?? "local", sourceName: input.path === undefined ? p.sampleName : basename(input.path) });
+    }
+    catch (e) {
+        throw new Refusal(`The transformer refused this input: ${e.message}`);
+    }
+}
+export async function learnlogTransform(input) {
+    const run = await runTransform(input);
+    const s = run.profile.source;
+    const first = run.records[0];
+    const body = {
+        format: run.profile.id,
+        source: {
+            file: run.sourceName,
+            sha256: run.sourceHash,
+            kind: run.sourceKind,
+            verified_public_sample: run.sourceVerified,
+            ...(run.sourceVerified ? { provenance: { citation: s.citation, license: s.license, url: s.url, revision: s.revision } } : {}),
+        },
+        summary: { input_rows: run.summary.inputRowCount, records: run.summary.recordCount, entries: run.summary.eventCount, unit: run.summary.unit, event_types: run.summary.eventTypes },
+        help_stages: formatStages(run.profile),
+        unknowns: unknownsOf(run.records),
+        warnings: sourceWarnings(run.records),
+        heads: run.checkpoint,
+        pseudonyms: "Learner IDs are replaced with HMAC pseudonyms keyed by a random secret made when this server started. They don't match across restarts or other tools.",
+        preview: { header: first.header, entries: first.entries.slice(0, 1) },
+        does_not_show: [
+            "Help that happened outside what the source recorded. A Learnlog record keeps what the export asserts, and nothing else.",
+            "Whether the source's assertions are true. The transformer checks structure and keeps provenance; it can't check a recording against the world.",
+            "Learning or the effect of help. These are records, not estimates.",
+        ],
+    };
+    const limits = body.does_not_show;
+    delete body.does_not_show;
+    if (!input.include_document)
+        return { ...body, document_note: "Set include_document: true to get the whole Learnlog document. This tool never writes it to disk.", does_not_show: limits };
+    const whole = { ...body, document: run.document, does_not_show: limits };
+    if (answerSize(whole) <= ANSWER_BUDGET)
+        return whole;
+    const characters = JSON.stringify(run.document, null, 2).length;
+    return {
+        ...body,
+        document_omitted: {
+            characters,
+            note: `The whole Learnlog document is ${characters.toLocaleString("en-US")} characters, too large to send in one answer (the limit is ${ANSWER_BUDGET.toLocaleString("en-US")}). The summary, heads, unknowns and preview here describe it. Nothing was written to disk.`,
+        },
+        does_not_show: limits,
+    };
+}

package/dist/tools/validate.js

@@ -0,0 +1,47 @@
+/** learnlog_validate: is this a valid Learnlog file, and what does each record leave unknown? */
+import { readLocalText } from "../files.js";
+import { VENDORED_FROM } from "../package.js";
+import { engine, sourceWarnings, unknownsOf } from "../transformer.js";
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+export const NOT_CHECKED = [
+    "Signed heads and signatures: the transformer's verifier refuses files that carry them, so they are not verified here.",
+    "Truncated or redacted records: refused, not checked.",
+    "Learnlog files from other producers: their header bindings won't match this transformer's profile, so they fail here even when their own chains are sound.",
+    "Whether any asserted event happened. Passing shows structural consistency under the stated rules, not that an event occurred (draft Section 2).",
+];
+export async function learnlogValidate(input) {
+    let text = readLocalText(input.path, "path", 50_000_000);
+    const warnings = [];
+    if (text.startsWith("")) {
+        text = text.slice(1);
+        warnings.push("The file starts with a byte-order mark, which was ignored.");
+    }
+    const base = {
+        checked_with: `QLM transformer verifier ${engine.ENGINE_VERSION} (vendored from ${VENDORED_FROM})`,
+        not_checked: NOT_CHECKED,
+        does_not_show: ["What a valid record means for learning. Validation checks the chain, the profile bindings and the import rules, not the learner."],
+    };
+    let doc;
+    try {
+        doc = engine.parseStrictJSON(text);
+    }
+    catch (e) {
+        return { valid: false, errors: [`Not valid JSON: ${e.message}`], warnings, records: [], ...base };
+    }
+    const list = isObj(doc) && Array.isArray(doc.records) ? doc.records : [];
+    const records = list.map((r, i) => {
+        const h = isObj(r) && isObj(r.header) ? r.header : null;
+        const entries = isObj(r) && Array.isArray(r.entries) ? r.entries.length : 0;
+        return h
+            ? { record: i + 1, record_id: h.record_id, source: h.source_platform, import_mode: h.import_mode, source_kind: h.source_kind, entries, unknowns: unknownsOf([r]) }
+            : { record: i + 1, unknowns: [] };
+    });
+    warnings.push(...sourceWarnings(list));
+    try {
+        const heads = await engine.verify(doc);
+        return { valid: true, errors: [], warnings, records, heads, ...base };
+    }
+    catch (e) {
+        return { valid: false, errors: [e.message], warnings, records, ...base };
+    }
+}

package/dist/tools/verify-credential.js

@@ -0,0 +1,155 @@
+/**
+ * verify_credential: is this QLM credential real and current? The one tool that uses the network.
+ * It sends one GET to https://app.qlmdev.com/v1/verify?id=<credential id> and nothing else, and it
+ * shows only the fields of the report it knows. The service's report carries no personal data
+ * (verification.ts: no credential subject, no evidence events), and this tool keeps it that way by
+ * copying known fields one by one and listing the names of any others it dropped.
+ */
+import { Refusal } from "../files.js";
+import { NOT_RECORDED, byStage } from "../stages.js";
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const str = (v) => typeof v === "string";
+export const VERIFY_URL = "https://app.qlmdev.com/v1/verify";
+const UUID = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+const URN = new RegExp(`urn:uuid:(${UUID})`, "gi");
+const ONLY_URN = new RegExp(`^urn:uuid:(${UUID})$`, "i");
+const ONLY_UUID = new RegExp(`^(${UUID})$`, "i");
+/** The credential ID in what the person gave: the ID itself, a bare UUID, or a link containing one. */
+export function credentialIdFrom(input) {
+    const text = input.trim();
+    if (text.length > 2048)
+        throw new Refusal("That's too long to be a credential ID or a link to one.");
+    // eslint-disable-next-line no-control-regex
+    const isId = !/[\u0000-\u001f\u007f]/.test(text);
+    const urn = isId ? ONLY_URN.exec(text) : null;
+    if (urn)
+        return { id: `urn:uuid:${urn[1].toLowerCase()}` };
+    const bare = isId ? ONLY_UUID.exec(text) : null;
+    if (bare) {
+        const id = `urn:uuid:${bare[1].toLowerCase()}`;
+        return { id, read_as: `A bare UUID was read as ${id}.` };
+    }
+    if (isId && /^https?:\/\//i.test(text)) {
+        const url = new URL(text);
+        if (url.pathname.startsWith("/v1/evidence"))
+            throw new Refusal("That's an evidence record link, not a credential. Give the credential's ID (urn:uuid:...) or a link containing it.");
+        let decoded = text;
+        try {
+            decoded = decodeURIComponent(text);
+        }
+        catch {
+            // keep the link as written
+        }
+        const found = new Set([...decoded.matchAll(URN)].map((m) => m[1].toLowerCase()));
+        if (found.size > 1)
+            throw new Refusal("That link holds more than one credential ID. Give the one you mean.");
+        const idParam = url.searchParams.get("id") ?? "";
+        const one = found.size === 1 ? [...found][0] : ONLY_UUID.test(idParam) ? idParam.toLowerCase() : null;
+        if (!one)
+            throw new Refusal("I couldn't find a credential ID in that link. Give the ID itself (urn:uuid:...).");
+        const id = `urn:uuid:${one}`;
+        return { id, read_as: `Read the ID ${id} from the link.` };
+    }
+    throw new Refusal("That isn't a credential ID (urn:uuid:...) or a link that contains one.");
+}
+const POLICY = {
+    not_permitted: "AI help: not permitted",
+    permitted: "AI help: permitted",
+    not_reviewed: "AI help: not reviewed (the issuer hasn't said whether AI help is permitted)",
+};
+/** The platform's three summary stages, in the draft's terms (summary.ts SUMMARY_STAGES). */
+const SUMMARY_KEY = { requested: "asked", generated: "generated", displayed: "shown" };
+function aiHelp(a, dropped) {
+    for (const k of Object.keys(a))
+        if (!["type", "learnlog", "coverage", "instrument", "boundary", "exclusions", "asked", "generated", "shown", "policy", "policyVersion"].includes(k))
+            dropped.push(`credential.aiHelp.${k}`);
+    const stages = byStage((stage) => {
+        const key = SUMMARY_KEY[stage];
+        if (!key)
+            return { status: NOT_RECORDED, note: "The badge's summary doesn't report this stage." };
+        const s = isObj(a[key]) ? a[key] : {};
+        if (s.capture === "complete")
+            return { status: "recorded", count: s.count, capture: "complete within the stated boundary" };
+        if (s.capture === "partial")
+            return { status: "recorded", count: s.count, capture: "partial: at least this many" };
+        return { status: NOT_RECORDED };
+    });
+    const recordedBy = a.coverage === "not_recorded"
+        ? "No AI-help record was kept with this evidence, so nothing is known about AI help. Not recorded is not the same as none."
+        : { learnlog: a.learnlog, instrument: a.instrument, coverage: str(a.coverage) ? a.coverage.replaceAll("_", " ") : a.coverage, boundary: a.boundary, not_covered: a.exclusions };
+    return { policy: str(a.policy) && POLICY[a.policy] ? POLICY[a.policy] : "not stated on this badge", stages, recorded_by: recordedBy };
+}
+const DOES_NOT_SHOW = [
+    "Who holds the badge. The service's report carries no personal data, and this tool shows none.",
+    "The evidence events themselves. Only their count and the seal check are reported.",
+    "Whether the person can do the work today. A credential is a record of a past assessment.",
+    "Anything about AI help beyond the badge's own summary. A stage the summary doesn't cover is not recorded, never none.",
+];
+async function readCapped(res) {
+    const text = await res.text();
+    if (text.length > 1_000_000)
+        throw new Refusal("The verify service's answer was too large to be a verification report.");
+    return text;
+}
+export async function verifyCredential(input, fetchImpl = fetch) {
+    const { id, read_as } = credentialIdFrom(input.credential);
+    const url = `${VERIFY_URL}?id=${encodeURIComponent(id)}`;
+    let res;
+    try {
+        res = await fetchImpl(url, { method: "GET", redirect: "error", headers: { accept: "application/json" }, signal: AbortSignal.timeout(15_000) });
+    }
+    catch (e) {
+        throw new Refusal(`Couldn't reach app.qlmdev.com: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const text = await readCapped(res);
+    let body = null;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        // handled by status below
+    }
+    const service = { url, http_status: res.status };
+    const base = { credential_id: id, ...(read_as ? { read_as } : {}), service };
+    if (res.status === 404 && isObj(body) && body.error === "not_found") {
+        return { ...base, verified: false, result: "not_found", meaning: "app.qlmdev.com has no credential with exactly this ID. It may be mistyped, or not issued by this platform.", does_not_show: DOES_NOT_SHOW };
+    }
+    if (res.status === 429)
+        throw new Refusal(`The verify service's rate limit was reached. Try again in ${res.headers.get("retry-after") ? `${res.headers.get("retry-after")} seconds` : "a little while"}.`);
+    if (res.status === 400 && isObj(body) && str(body.error))
+        throw new Refusal(`The verify service refused the request (${body.error})${str(body.message) ? `: ${body.message}` : "."}`);
+    if (res.status !== 200)
+        throw new Refusal(`The verify service answered HTTP ${res.status}.`);
+    const checksOk = isObj(body) && Array.isArray(body.checks) && body.checks.every((c) => isObj(c) && str(c.check) && (c.result === "pass" || c.result === "fail"));
+    if (!isObj(body) || typeof body.verified !== "boolean" || !checksOk)
+        throw new Refusal("The verify service's answer wasn't the JSON report this tool expects.");
+    const dropped = Object.keys(body).filter((k) => !["verified", "credentialId", "checks", "credential", "notices"].includes(k));
+    const checks = body.checks.map((c) => ({ check: c.check, result: c.result, ...(str(c.detail) ? { detail: c.detail } : {}) }));
+    const out = {
+        ...base,
+        verified: body.verified,
+        checks,
+        failed_checks: checks.filter((c) => c.result === "fail").map((c) => ({ check: c.check, detail: c.detail })),
+    };
+    const c = body.credential;
+    if (isObj(c)) {
+        for (const k of Object.keys(c))
+            if (!["issuer", "achievement", "validFrom", "evidenceEventCount", "evidenceLevel", "reissuedFromIssuerRecords", "awardedDate", "aiHelp"].includes(k))
+                dropped.push(`credential.${k}`);
+        const issuer = c.issuer;
+        const achievement = c.achievement;
+        out.issuer = { id: issuer.id, name: issuer.name };
+        out.achievement = { id: achievement.id, name: achievement.name, version: achievement.version };
+        out.date = { valid_from: c.validFrom, ...(c.awardedDate !== undefined ? { awarded_date: c.awardedDate, reissued_from_issuer_records: c.reissuedFromIssuerRecords === true } : {}) };
+        out.evidence = { event_count: c.evidenceEventCount, ...(c.evidenceLevel !== undefined ? { level: c.evidenceLevel } : {}) };
+        out.ai_help = isObj(c.aiHelp) ? aiHelp(c.aiHelp, dropped) : "not recorded: this badge carries no AI-help summary (it was issued before the summary existed, or under an older context)";
+    }
+    else {
+        out.issuer = "not given: the service names the issuer, achievement and date only when every check passes";
+    }
+    out.notices = Array.isArray(body.notices) ? body.notices.filter(str) : [];
+    if (dropped.length)
+        out.fields_not_shown = dropped;
+    out.does_not_show = DOES_NOT_SHOW;
+    return out;
+}

package/dist/tools/verify-evidence.js

@@ -0,0 +1,51 @@
+/**
+ * verify_evidence: can I trust this result? Runs qlm-measure's own verifier (vendored 0.9.0 build,
+ * unchanged) on a local evidence record or a product hash chain, the way its CLI does, and reports
+ * pass, or each named check that failed. The CLI's --report option, which writes a file, is never used.
+ */
+import { CATALOG, CATALOG_V03 } from "../../vendor/qlm-measure/checks.js";
+import { main } from "../../vendor/qlm-measure/cli.js";
+import { Refusal, localFile } from "../files.js";
+import { VENDORED_FROM } from "../package.js";
+const CHECK = new Map([...CATALOG_V03, ...CATALOG].map((c) => [c.id, c]));
+/** The verifier's stdin reader. This tool only ever passes file paths, so it is never asked to read stdin. */
+export function noStdin() {
+    throw new Refusal("verify_evidence reads files, not standard input.");
+}
+function run(argv) {
+    let out = "";
+    let err = "";
+    const code = main(argv, { out: (t) => (out += t), err: (t) => (err += t), readStdin: noStdin });
+    if (code === 2)
+        throw new Refusal(`The verifier stopped: ${err.trim()}`);
+    return { code, out, err };
+}
+const DOES_NOT_SHOW = [
+    "Whether the estimates in a record are right. The verifier checks bookkeeping integrity (hashes, order, schema, how posteriors chain), not how anything was estimated.",
+    "Whether the recorded events happened as described. A clean chain shows the records weren't changed after they were sealed.",
+    "Who the learner is.",
+];
+export function verifyEvidence(input) {
+    const kind = input.kind ?? "record";
+    const verifier = `qlm-measure 0.9.0 (vendored from ${VENDORED_FROM})`;
+    if (kind === "list_schemes") {
+        const schemes = run(["verify-chain", "--list"]).out.trim().split("\n").map((line) => {
+            const [id, family, since, fields] = line.split("\t");
+            return { id, family, since: since.replace(/^since /, ""), fields };
+        });
+        return { verifier, schemes, does_not_show: ["Anything about a file. This lists the chain schemes the verifier knows."] };
+    }
+    const { path } = localFile(input.path, "path", 100_000_000);
+    if (kind === "chain") {
+        if (input.family === undefined && input.scheme === undefined)
+            throw new Refusal("Name the chain's family (for example tpc/clinical) or its exact scheme (for example tpc/clinical-v2). verify_evidence with kind list_schemes lists them.");
+        const argv = ["verify-chain", path, ...(input.scheme !== undefined ? ["--scheme", input.scheme] : ["--family", input.family]), "--format", "json", ...(input.allow_mixed ? ["--allow-mixed"] : [])];
+        const { code, out } = run(argv);
+        const report = JSON.parse(out);
+        return { verdict: code === 0 ? "pass" : "fail", verifier, failed_checks: report.errors, report, does_not_show: DOES_NOT_SHOW };
+    }
+    const { code, out } = run(["verify", path, "--format", "json"]);
+    const report = JSON.parse(out);
+    const failed = report.records.flatMap((r, i) => r.checks.filter((c) => c.status === "fail").map((c) => ({ record: i + 1, check: c.id, failures: c.failures, first_failure: c.first_failure, what_it_checks: CHECK.get(c.id)?.description, how_to_pass: CHECK.get(c.id)?.howToPass })));
+    return { verdict: code === 0 ? "pass" : "fail", verifier, records_checked: report.records.length, failed_checks: failed, report, does_not_show: DOES_NOT_SHOW };
+}

package/dist/tools/worlds.js

@@ -0,0 +1,24 @@
+/**
+ * LabPath worlds and their public pages. The names come from each world's page on
+ * play.quantumlearningmachines.com (data/labpath-worlds.json, rebuilt by scripts/refresh-worlds.mjs).
+ * A world not in that list gets no link: a page is never made up.
+ */
+import { readJsonFile } from "../package.js";
+const TABLE = readJsonFile("data/labpath-worlds.json");
+export const WORLD_URL = TABLE.url_pattern.replace("{id}", "");
+export function worldLink(id) {
+    const name = Object.hasOwn(TABLE.worlds, id) ? TABLE.worlds[id] : null;
+    return name === null ? { id, name: null, url: null, note: "No public page is known for this world." } : { id, name, url: WORLD_URL + id };
+}
+/** Links for a list of world ids, in order, without repeats; anything that isn't text is skipped. */
+export function worldLinks(ids) {
+    const seen = new Set();
+    const out = [];
+    for (const id of Array.isArray(ids) ? ids : []) {
+        if (typeof id !== "string" || seen.has(id))
+            continue;
+        seen.add(id);
+        out.push(worldLink(id));
+    }
+    return out;
+}

package/dist/transformer.js

@@ -0,0 +1,92 @@
+/** The vendored QLM transformer (qlm-measure demo/transformer/dist/engine.mjs), used unchanged. */
+import * as engine from "../vendor/transformer/engine.mjs";
+import { Refusal } from "./files.js";
+import { NOT_RECORDED, byStage } from "./stages.js";
+export { engine };
+/** Every adapter the engine accepts, including sandpiper, which the transformer's demo page doesn't list. */
+export const FORMAT_IDS = engine.ADAPTER_PROFILES.map((p) => p.id);
+export function profileOf(id) {
+    const p = engine.ADAPTER_PROFILES.find((x) => x.id === id);
+    if (!p)
+        throw new Refusal(`Unknown format "${id}". Use one of: ${FORMAT_IDS.join(", ")}.`);
+    return p;
+}
+const LIFECYCLE_TYPE = { requested: "help_requested", generated: "help_generated", transmitted: "help_transmitted", displayed: "help_displayed" };
+/** What a format can record at each stage, before looking at any data. */
+export function formatStages(p) {
+    return byStage((stage) => {
+        if (p.mode === "dialogue")
+            return `${NOT_RECORDED}: the adapter keeps who spoke and what they said; it doesn't classify any turn as help`;
+        if (p.mode === "summary")
+            return `${NOT_RECORDED}: the table gives each participant's assigned help condition, not help events`;
+        if (p.mode === "annotated_dialogue")
+            return `${NOT_RECORDED}: the export keeps who spoke and what they said; annotation codes are kept as an annotator's inferred assertions and never set a help stage`;
+        const type = LIFECYCLE_TYPE[stage];
+        return type ? `recorded when the export asserts it (${type})` : `${NOT_RECORDED}: the transformer's lifecycle input has no event type for this stage`;
+    });
+}
+const words = (s) => s.replaceAll("_", " ");
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const CONTEXT_LABEL = { phase: "Phase", permission: "Help policy (permission)", observed_use: "Observed help use", capture: "Capture coverage", capture_boundary: "Capture boundary", product_version: "Product version", model_version: "Model version" };
+/** The unknowns a set of transformer-made records keep, in plain words, counted across their entries. */
+export function unknownsOf(records) {
+    const out = new Set();
+    const counts = new Map();
+    let entries = 0;
+    const count = (k) => counts.set(k, (counts.get(k) ?? 0) + 1);
+    for (const r of records) {
+        if (!isObj(r) || !isObj(r.header))
+            continue;
+        const h = r.header;
+        if (typeof h.assistance_coverage === "string")
+            out.add(`Help coverage: ${words(h.assistance_coverage)}`);
+        const m = isObj(h.semantic_mapping) ? h.semantic_mapping : {};
+        const cov = isObj(m.coverage) ? m.coverage : {};
+        if (typeof cov.status === "string")
+            out.add(`Coverage of the mapping: ${words(cov.status)}${typeof cov.boundary === "string" ? ` (${cov.boundary})` : ""}`);
+        if (m.measurement_profile === null)
+            out.add("No measurement profile: these records don't define a measure");
+        if (m.denominator === null)
+            out.add("No denominator: counts from these records are not rates");
+        for (const e of Array.isArray(r.entries) ? r.entries : []) {
+            const data = isObj(e) && isObj(e.event) && isObj(e.event.data) ? e.event.data : null;
+            if (!data)
+                continue;
+            entries++;
+            if (data.original_source_timestamp === null)
+                count("Source event time not recorded");
+            const utterance = isObj(data.utterance) ? data.utterance : {};
+            if (utterance.start_time === null)
+                count("Utterance start time not recorded");
+            if (utterance.end_time === null)
+                count("Utterance end time not recorded");
+            const ctx = isObj(data.assistance_context) ? data.assistance_context : {};
+            for (const [k, label] of Object.entries(CONTEXT_LABEL)) {
+                if (ctx[k] === "unknown")
+                    count(`${label} not recorded (unknown)`);
+                if (ctx[k] === null)
+                    count(`${label} not recorded`);
+            }
+            for (const name of Array.isArray(data.missing_metrics) ? data.missing_metrics : [])
+                count(`Metric ${String(name)} missing`);
+            const help = isObj(data.help_evidence) ? data.help_evidence.actual_help_use : undefined;
+            if (typeof help === "string")
+                count(`Actual help use ${words(help)}`);
+        }
+    }
+    for (const [k, n] of counts)
+        out.add(`${k} on ${n} of ${entries} entries`);
+    return [...out];
+}
+/** Warnings about where a set of records came from. */
+export function sourceWarnings(records) {
+    const out = new Set();
+    for (const r of records) {
+        const kind = isObj(r) && isObj(r.header) ? r.header.source_kind : undefined;
+        if (kind === "unverified_user_input")
+            out.add("The source bytes don't match a pinned public sample, so where they came from is the producer's claim.");
+        if (kind === "synthetic_fixture")
+            out.add("This is a SYNTHETIC contract fixture, not learner data.");
+    }
+    return [...out];
+}

package/dist/zip.js

@@ -0,0 +1,71 @@
+/**
+ * A small zip reader: the central directory, then one member at a time, so a 1 GB archive of HTML
+ * reports is never held decompressed all at once. It reads what Python's zipfile reads for the
+ * pinned Zenodo archive: stored and deflated members, cp437 or UTF-8 names, CRC-32 checked. ZIP64 and
+ * encrypted members are refused rather than guessed at.
+ */
+import { crc32, inflateRawSync } from "node:zlib";
+const CP437_HIGH = "ÇüéâäàåçêëèïîìÄÅÉæÆôöòûùÿÖÜ¢£¥₧ƒáíóúñѪº¿⌐¬½¼¡«»░▒▓│┤╡╢╖╕╣║╗╝╜╛┐└┴┬├─┼╞╟╚╔╩╦╠═╬╧╨╤╥╙╘╒╓╫╪┘┌█▄▌▐▀αßΓπΣσµτΦΘΩδ∞φε∩≡±≥≤⌠⌡÷≈°∙·√ⁿ²■\u00a0";
+function cp437(bytes) {
+    let s = "";
+    for (const b of bytes)
+        s += b < 0x80 ? String.fromCharCode(b) : CP437_HIGH[b - 0x80];
+    return s;
+}
+/** The members listed in the central directory, in its order (Python's ZipFile.namelist()). */
+export function zipEntries(buf) {
+    let end = -1;
+    for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 65535); i--) {
+        if (buf.readUInt32LE(i) === 0x06054b50) {
+            end = i;
+            break;
+        }
+    }
+    if (end < 0)
+        throw new Error("File is not a zip file");
+    const count = buf.readUInt16LE(end + 10);
+    const cdSize = buf.readUInt32LE(end + 12);
+    const cdOffset = buf.readUInt32LE(end + 16);
+    if (count === 0xffff || cdSize === 0xffffffff || cdOffset === 0xffffffff)
+        throw new Error("ZIP64 archives are not supported by this reader");
+    const entries = [];
+    let p = cdOffset;
+    for (let k = 0; k < count; k++) {
+        if (buf.readUInt32LE(p) !== 0x02014b50)
+            throw new Error("Bad magic number for central directory");
+        const flags = buf.readUInt16LE(p + 8);
+        const nameLength = buf.readUInt16LE(p + 28);
+        const raw = buf.subarray(p + 46, p + 46 + nameLength);
+        entries.push({
+            name: flags & 0x800 ? raw.toString("utf8") : cp437(raw),
+            flags,
+            method: buf.readUInt16LE(p + 10),
+            crc: buf.readUInt32LE(p + 16),
+            compressedSize: buf.readUInt32LE(p + 20),
+            size: buf.readUInt32LE(p + 24),
+            localOffset: buf.readUInt32LE(p + 42),
+        });
+        p += 46 + nameLength + buf.readUInt16LE(p + 30) + buf.readUInt16LE(p + 32);
+    }
+    return entries;
+}
+/** One member's bytes (Python's ZipFile.read(name)), with its CRC-32 checked. */
+export function zipRead(buf, e) {
+    if (e.flags & 1)
+        throw new Error(`File '${e.name}' is encrypted; encrypted members are not supported`);
+    const p = e.localOffset;
+    if (buf.readUInt32LE(p) !== 0x04034b50)
+        throw new Error("Bad magic number for file header");
+    const start = p + 30 + buf.readUInt16LE(p + 26) + buf.readUInt16LE(p + 28);
+    const body = buf.subarray(start, start + e.compressedSize);
+    let data;
+    if (e.method === 0)
+        data = Buffer.from(body);
+    else if (e.method === 8)
+        data = inflateRawSync(body);
+    else
+        throw new Error(`compression method ${e.method} is not supported`);
+    if (crc32(data) !== e.crc)
+        throw new Error(`Bad CRC-32 for file '${e.name}'`);
+    return data;
+}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@qlm/learnlog-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Learnlog MCP: ask your AI assistant what learning records actually show about help. Read-only tools for Learnlog records, QLM credential verification, and QLM's public misconception and learning-graph datasets.",
+  "license": "Apache-2.0",
+  "author": "Kumar Srivastava <kumar@quantumlearningmachines.com> (https://quantumlearningmachines.com)",
+  "type": "module",
+  "bin": {
+    "learnlog-mcp": "dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "vendor",
+    "data",
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node -e \"require('fs').chmodSync('dist/bin.js', 0o755)\"",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint .",
+    "test": "npm run build && vitest run --coverage",
+    "vendor:check": "node scripts/vendor.mjs --check ..",
+    "smoke:live": "node scripts/live-smoke.mjs",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm test && npm run vendor:check",
+    "prepack": "npm run build",
+    "parity:real": "node scripts/parity-real.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@types/node": "22.20.5",
+    "@vitest/coverage-v8": "5.0.3",
+    "eslint": "10.12.0",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.71.1",
+    "vitest": "5.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/quantumlearningmachines/qlm-measure.git",
+    "directory": "mcp"
+  },
+  "homepage": "https://github.com/quantumlearningmachines/qlm-measure/tree/main/mcp#readme",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "learnlog",
+    "learning-analytics",
+    "education",
+    "assistance",
+    "evidence",
+    "misconceptions",
+    "learning-graph"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}