@meetless/mla 0.1.4

package/dist/lib/rules/ce0-evidence.js

@@ -0,0 +1,281 @@
+"use strict";
+// Commit 9: the `mla evidence` CE0 labeling workflow, export half
+// (notes/20260617-evidence-consultation-forcing-function-proposal.md §2.3). CE0 finalization is
+// a human-driven LOCAL JSONL workflow: no model call, no external egress, no second deterministic
+// finalizer. `ce0-export` writes a JSONL of the three-record facts a labeler needs for answer
+// disposition and per-subject coverage audit; `ce0-import-labels` (slice 9b) reads the labeled
+// file back, verifies each obligation's id and expected stateVersion, writes the terminal outcome,
+// and moves status to FINALIZED.
+//
+// The CE0 nuance this module resolves: the live store never writes subjectSatisfaction. The
+// runtime adapters only record facts (the assessment, the consultation attempts) and the first
+// Stop freezes the eligibility boundary; the live subjectSatisfaction stays []. So the export is
+// the one place the deterministic satisfaction reducer runs: it selects the eligible consultations
+// (those that contributed a proof AND landed on or before the frozen deadline boundary) and
+// recomputes the per-subject proof set. That recomputed set, NOT the live [], is the machine
+// baseline the human audits against the terminal outcome they assign.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assembleCe0ExportRows = assembleCe0ExportRows;
+exports.serializeCe0ExportRows = serializeCe0ExportRows;
+exports.parseCe0ExportRows = parseCe0ExportRows;
+exports.assembleCe0ExportLines = assembleCe0ExportLines;
+exports.serializeCe0ExportLines = serializeCe0ExportLines;
+exports.parseCe0ExportLines = parseCe0ExportLines;
+exports.runCe0Export = runCe0Export;
+exports.reconcileCe0Labels = reconcileCe0Labels;
+exports.parseCe0LabelRows = parseCe0LabelRows;
+exports.runCe0ImportLabels = runCe0ImportLabels;
+const ce0_store_1 = require("./ce0-store");
+const requirement_subject_1 = require("./requirement-subject");
+const ce0_recall_sample_1 = require("./ce0-recall-sample");
+/**
+ * Build the export rows for a workspace: one per deadline-claimed, non-finalized obligation. For
+ * each, read the turn's consultations, run the deterministic reducer over the eligible set bounded
+ * by the frozen deadline, and carry the recomputed proof set plus the raw consultation facts with
+ * their eligibility flag. Deterministic and side-effect-free; the store reads are already ordered.
+ */
+function assembleCe0ExportRows(store, workspaceId) {
+    const rows = [];
+    for (const obl of (0, ce0_store_1.listDeadlineClaimedObligations)(store, workspaceId)) {
+        // FINALIZED obligations are already labeled; the export is for the set awaiting a label.
+        if (obl.status === "FINALIZED")
+            continue;
+        const consultations = (0, ce0_store_1.listConsultationsForTurn)(store, {
+            workspaceId: obl.workspaceId,
+            sessionId: obl.sessionId,
+            localTurnSequence: obl.localTurnSequence,
+        });
+        const reducerInputs = consultations.map(ce0_store_1.consultationRecordToReducerInput);
+        const eligible = (0, requirement_subject_1.selectEligibleConsultations)(reducerInputs, obl.deadlineClaimedAt);
+        const eligibleIds = new Set(eligible.map((c) => c.consultationId));
+        const subjectSatisfaction = (0, requirement_subject_1.recomputeSubjectSatisfaction)(obl.requiredSubjects, eligible);
+        rows.push({
+            obligationId: obl.obligationId,
+            workspaceId: obl.workspaceId,
+            sessionId: obl.sessionId,
+            localTurnSequence: obl.localTurnSequence,
+            ruleId: obl.ruleId,
+            ruleVersionId: obl.ruleVersionId,
+            requiredSubjects: obl.requiredSubjects,
+            status: obl.status,
+            stateVersion: obl.stateVersion,
+            deadlineClaimedAt: obl.deadlineClaimedAt,
+            deadlineClaimedVersion: obl.deadlineClaimedVersion,
+            responseHash: obl.responseHash,
+            subjectSatisfaction,
+            machineSatisfied: (0, requirement_subject_1.isObligationSatisfied)(obl.requiredSubjects, subjectSatisfaction),
+            consultations: consultations.map((c) => ({
+                consultationId: c.consultationId,
+                source: c.source,
+                consultationSubjects: c.consultationSubjects,
+                execution: c.execution,
+                result: c.result,
+                deliveredToAnsweringContext: c.deliveredToAnsweringContext,
+                orderingToken: c.orderingToken,
+                eligible: eligibleIds.has(c.consultationId),
+            })),
+        });
+    }
+    return rows;
+}
+/** Serialize export rows as JSONL: one JSON object per line, newline-terminated. An empty set
+ * serializes to the empty string (no spurious blank line). */
+function serializeCe0ExportRows(rows) {
+    return rows.map((r) => JSON.stringify(r)).join("\n") + (rows.length > 0 ? "\n" : "");
+}
+/** Parse a JSONL export back into rows, ignoring blank lines so a trailing newline round-trips. */
+function parseCe0ExportRows(jsonl) {
+    return jsonl
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => JSON.parse(line));
+}
+/**
+ * Assemble the full export stream for a workspace: every precision (obligation) line first, then every
+ * recall (sampled unflagged assessment) line. `recallSampleRate` thresholds the recall population only;
+ * the precision population is always complete. Deterministic and side-effect-free.
+ */
+function assembleCe0ExportLines(store, workspaceId, recallSampleRate) {
+    const lines = [];
+    for (const obligation of assembleCe0ExportRows(store, workspaceId)) {
+        lines.push({ population: "PRECISION", obligation });
+    }
+    for (const recall of (0, ce0_recall_sample_1.assembleCe0RecallSampleRows)(store, workspaceId, recallSampleRate)) {
+        lines.push({ population: "RECALL", recall });
+    }
+    return lines;
+}
+/** Serialize export lines as JSONL: one JSON object per line, newline-terminated. An empty stream
+ * serializes to the empty string (no spurious blank line). */
+function serializeCe0ExportLines(lines) {
+    return lines.map((l) => JSON.stringify(l)).join("\n") + (lines.length > 0 ? "\n" : "");
+}
+/** Parse a JSONL export back into lines, ignoring blank lines so a trailing newline round-trips. */
+function parseCe0ExportLines(jsonl) {
+    return jsonl
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => JSON.parse(line));
+}
+/** The `mla evidence ce0-export` core: assemble the workspace's two-population stream and serialize it.
+ * `recallSampleRate` defaults to the pinned DEFAULT_RECALL_SAMPLE_RATE (sample every unflagged turn). */
+function runCe0Export(store, workspaceId, recallSampleRate = ce0_recall_sample_1.DEFAULT_RECALL_SAMPLE_RATE) {
+    return serializeCe0ExportLines(assembleCe0ExportLines(store, workspaceId, recallSampleRate));
+}
+const OBLIGATION_OUTCOMES = new Set([
+    "NOT_DUE",
+    "COMPLIANT_ON_TIME",
+    "CONSULTED_LATE_WITH_EVIDENCE",
+    "CONSULTED_LATE_NO_EVIDENCE",
+    "MISSED",
+    "UNKNOWN",
+    "CANCELLED",
+]);
+const COVERAGE_GRADES = new Set([
+    "FULL",
+    "PARTIAL",
+    "NONE",
+    "UNKNOWN",
+]);
+/** Whether an outcome asserts the obligation was satisfied on time (true), missed (false), or is
+ * not a satisfaction claim at all (null). The agreement check compares this to the machine baseline. */
+function satisfactionExpectation(outcome) {
+    switch (outcome) {
+        case "COMPLIANT_ON_TIME":
+            return true;
+        case "CONSULTED_LATE_WITH_EVIDENCE":
+        case "CONSULTED_LATE_NO_EVIDENCE":
+        case "MISSED":
+            return false;
+        case "NOT_DUE":
+        case "UNKNOWN":
+        case "CANCELLED":
+            return null;
+    }
+}
+/**
+ * Validate a labeled file against the export snapshot, producing the finalization commands, the
+ * rejections, and the machine-vs-human agreement summary. Pure: no store access, no side effects.
+ * Each label is checked in order (unknown obligation, stale stateVersion, bad outcome, bad grade,
+ * subject-coverage mismatch); the first failure rejects the label and no finalization is emitted.
+ */
+function reconcileCe0Labels(exportRows, labelRows) {
+    const byId = new Map(exportRows.map((r) => [r.obligationId, r]));
+    const out = { finalizations: [], rejections: [], agreement: [] };
+    for (const label of labelRows) {
+        const row = byId.get(label.obligationId);
+        if (!row) {
+            out.rejections.push({
+                obligationId: label.obligationId,
+                reason: "unknown obligation: not in the export set (already finalized or never claimed)",
+            });
+            continue;
+        }
+        if (label.expectedStateVersion !== row.stateVersion) {
+            out.rejections.push({
+                obligationId: label.obligationId,
+                reason: `stale label: expected stateVersion ${label.expectedStateVersion}, export is ${row.stateVersion}`,
+            });
+            continue;
+        }
+        if (!OBLIGATION_OUTCOMES.has(label.outcome)) {
+            out.rejections.push({
+                obligationId: label.obligationId,
+                reason: `invalid outcome: ${String(label.outcome)} is not one of the seven terminal outcomes`,
+            });
+            continue;
+        }
+        const badGrade = label.perSubject.find((p) => !COVERAGE_GRADES.has(p.grade));
+        if (badGrade) {
+            out.rejections.push({
+                obligationId: label.obligationId,
+                reason: `invalid grade: ${String(badGrade.grade)} for subject ${badGrade.subjectId}`,
+            });
+            continue;
+        }
+        const requiredIds = new Set(row.requiredSubjects.map((s) => s.subjectId));
+        const gradedIds = new Set(label.perSubject.map((p) => p.subjectId));
+        const extra = [...gradedIds].find((id) => !requiredIds.has(id));
+        if (extra) {
+            out.rejections.push({
+                obligationId: label.obligationId,
+                reason: `grades a subject the obligation does not require: ${extra}`,
+            });
+            continue;
+        }
+        const ungraded = [...requiredIds].find((id) => !gradedIds.has(id));
+        if (ungraded) {
+            out.rejections.push({
+                obligationId: label.obligationId,
+                reason: `leaves a required subject ungraded: ${ungraded}`,
+            });
+            continue;
+        }
+        out.finalizations.push({
+            obligationId: label.obligationId,
+            expectedStateVersion: label.expectedStateVersion,
+            outcome: label.outcome,
+        });
+        const expectation = satisfactionExpectation(label.outcome);
+        out.agreement.push({
+            obligationId: label.obligationId,
+            machineSatisfied: row.machineSatisfied,
+            humanOutcome: label.outcome,
+            agrees: expectation === null ? null : expectation === row.machineSatisfied,
+        });
+    }
+    return out;
+}
+/** Parse a labeled JSONL back into rows, ignoring blank lines (mirrors parseCe0ExportRows). */
+function parseCe0LabelRows(jsonl) {
+    return jsonl
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => JSON.parse(line));
+}
+/**
+ * The `mla evidence ce0-import-labels` core: assemble the workspace's current export snapshot,
+ * reconcile the labeled JSONL against it, then CAS-finalize each accepted label. The reconcile
+ * pre-flight gives clean human-facing rejections; the store's compare-and-swap is the authoritative
+ * write guard, so an already-finalized or concurrently-changed obligation can never be double-written.
+ */
+function runCe0ImportLabels(store, workspaceId, labelJsonl) {
+    const exportRows = assembleCe0ExportRows(store, workspaceId);
+    const labels = parseCe0LabelRows(labelJsonl);
+    const reconciliation = reconcileCe0Labels(exportRows, labels);
+    const report = {
+        finalized: [],
+        conflicts: [],
+        rejected: [...reconciliation.rejections],
+        agreement: reconciliation.agreement,
+    };
+    for (const cmd of reconciliation.finalizations) {
+        const result = (0, ce0_store_1.finalizeObligation)(store, cmd);
+        switch (result.status) {
+            case "FINALIZED":
+                report.finalized.push({
+                    obligationId: result.obligationId,
+                    outcome: result.outcome,
+                    stateVersion: result.stateVersion,
+                });
+                break;
+            case "CAS_CONFLICT":
+                report.conflicts.push({
+                    obligationId: result.obligationId,
+                    expectedStateVersion: result.expectedStateVersion,
+                    actualStateVersion: result.actualStateVersion,
+                });
+                break;
+            case "NO_OBLIGATION":
+                report.rejected.push({
+                    obligationId: result.obligationId,
+                    reason: "obligation vanished between reconcile and finalize",
+                });
+                break;
+        }
+    }
+    return report;
+}

package/dist/lib/rules/ce0-recall-sample.js

@@ -0,0 +1,82 @@
+"use strict";
+// The offline recall-sampling threshold for `ce0-export`
+// (notes/20260617-evidence-consultation-forcing-function-proposal.md lines 1010-1019, 2129).
+//
+// The durable store stamps EVERY classified turn with a uniform `samplingBucket` (a sha256 hex digest
+// over the turn's natural key; see ce0-sampling-bucket.ts) and bakes in NO sampling rate. Recall (the
+// false-negative rate) is constructible only from the NOT_REQUIRED / UNKNOWN turns we did not flag, so
+// the OFFLINE export must choose WHICH of those unflagged turns to put in front of a grader. It does so
+// by THRESHOLDING the bucket: read the leading 32 bits of the digest as a uniform fraction in [0, 1) and
+// sample the turn iff that fraction is below the rate. Because the bucket is reconstructible from the
+// turn's logical coordinate alone, sample membership is reproducible offline with no runtime random draw.
+//
+// The threshold is monotonic in the rate: a turn in the sample at rate r is in the sample at every rate
+// above r. Widening the rate only ever ADDS turns, so a later, more generous export is a superset of an
+// earlier one over the same store.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RECALL_SAMPLE_RATE = void 0;
+exports.isInRecallSample = isInRecallSample;
+exports.assembleCe0RecallSampleRows = assembleCe0RecallSampleRows;
+const ce0_store_1 = require("./ce0-store");
+/**
+ * The pinned default recall sampling rate: 1.0, i.e. sample EVERY unflagged (NOT_REQUIRED / UNKNOWN)
+ * turn. At dogfood / measurement-harness scale the recall gate needs at least 100 sampled unflagged
+ * turns before recall is observable at all (proposal line 2129; line 2145: recall unmeasurable -> do
+ * not authorize CE1). Sampling DOWN from that starves the gate, so the default measures everything.
+ * The threshold machinery below exists so the rate can be dialed under 1.0 once a real pilot's volume
+ * forces a grader-load bound; it is not exercised by the default path.
+ */
+exports.DEFAULT_RECALL_SAMPLE_RATE = 1;
+/** The number of leading hex chars (32 bits) of the digest read as the sampling fraction. */
+const PREFIX_HEX_CHARS = 8;
+/** 2^32: the denominator that turns the 32-bit prefix into a fraction in [0, 1). */
+const PREFIX_SPACE = 0x1_0000_0000;
+/**
+ * Whether a turn whose assessment carries `samplingBucket` falls in the offline recall sample at `rate`.
+ * Reads the leading 32 bits of the digest as a uniform fraction and samples iff it is strictly below the
+ * rate. `rate >= 1` samples every turn; `rate <= 0` samples none. A malformed bucket (not a hex digest
+ * of at least 8 chars) is never sampled: the real producer always emits a 64-char sha256 digest, and a
+ * conservative exclude keeps a parse fault from silently corrupting the recall denominator.
+ */
+function isInRecallSample(samplingBucket, rate) {
+    if (samplingBucket.length < PREFIX_HEX_CHARS)
+        return false;
+    const prefix = samplingBucket.slice(0, PREFIX_HEX_CHARS);
+    if (!/^[0-9a-f]{8}$/.test(prefix))
+        return false;
+    // The fraction is always in [0, 1) (the largest 32-bit prefix is 0xffffffff / 2^32 < 1), so this
+    // single comparison subsumes the rate bounds: rate >= 1 samples every valid bucket, rate <= 0 none.
+    const fraction = parseInt(prefix, 16) / PREFIX_SPACE;
+    return fraction < rate;
+}
+/**
+ * Build the recall-sample rows for a workspace: one per NOT_REQUIRED / UNKNOWN assessment whose
+ * samplingBucket falls in the sample at `rate`. Reads the store's ordered assessment list, so the rows
+ * inherit its (session, sequence, assessmentId) order. Deterministic and side-effect-free.
+ */
+function assembleCe0RecallSampleRows(store, workspaceId, rate) {
+    const rows = [];
+    for (const a of (0, ce0_store_1.listTurnMemoryAssessments)(store, workspaceId)) {
+        // REQUIRED turns are the precision population (assembleCe0ExportRows); the recall sample is the
+        // unflagged turns only.
+        if (a.requirement === "REQUIRED")
+            continue;
+        if (!isInRecallSample(a.samplingBucket, rate))
+            continue;
+        const ref = a.responseSourceRef ?? null;
+        rows.push({
+            assessmentId: a.assessmentId,
+            workspaceId: a.workspaceId,
+            sessionId: a.sessionId,
+            localTurnSequence: a.localTurnSequence,
+            requirement: a.requirement,
+            samplingBucket: a.samplingBucket,
+            promptHash: a.promptHash,
+            responseHash: a.responseHash ?? null,
+            responseSourceRef: ref,
+            labelability: ref ? "LABELABLE" : "UNLABELABLE",
+            labelabilityReason: ref ? null : "NO_RESPONSE_SNAPSHOT",
+        });
+    }
+    return rows;
+}

package/dist/lib/rules/ce0-rule.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONSULT_EVIDENCE_CANONICAL_PAYLOAD_HASH = exports.CONSULT_EVIDENCE_RULE_PAYLOAD = exports.CONSULT_EVIDENCE_RESPONSE_CEILING = exports.CONSULT_EVIDENCE_RULE_VERSION_ID = exports.CONSULT_EVIDENCE_RULE_ID = void 0;
+const canonical_json_1 = require("./canonical-json");
+const memory_requirement_1 = require("./memory-requirement");
+const requirement_subject_1 = require("./requirement-subject");
+/**
+ * The ONE CE0 rule the forcing function records against:
+ * CONSULT_GOVERNED_EVIDENCE_ON_MEMORY_REQUIRED_TURN_V1
+ * (notes/20260617-evidence-consultation-forcing-function-proposal.md §1.3).
+ *
+ * This is NOT a second obligation framework. The canonical Rules primitive
+ * (types.ts / applicability.ts, commit 7cdbee1a) models PreToolUse ACTION gates;
+ * its "turn" mode is explicitly inert there. The turn-scoped obligation lives as the
+ * TurnRuleObligation record, created by the prompt-submit adapter and STAMPED with
+ * this module's frozen identity. This file only pins that identity; it owns no
+ * lifecycle and selects nothing.
+ *
+ * THE RESPONSE CEILING is RECORD_ONLY for CE0 and CE1: the hook observes and records,
+ * it NEVER injects, steers, asks, or denies. Raising the ceiling to AUTO_CORRECT is a
+ * CE2 concern that requires a NEW immutable rule version (a new ruleVersionId) minted
+ * after a separate policy ratification, never an in-place edit of this one.
+ *
+ * THE canonicalPayloadHash binds the obligation to the EXACT compiled rule that
+ * produced it: the rule identity plus the live trigger-classifier and subject-extractor
+ * seed versions. Because the payload reads those seed constants (it never hand-copies
+ * the literals), bumping any seed set rotates this hash, so an obligation is always
+ * attributable to a reproducible (classifier, extractor, seed-set) tuple. The digest is
+ * sha256 over RFC 8785 canonical JSON, the same discipline as the subject fingerprint.
+ */
+exports.CONSULT_EVIDENCE_RULE_ID = "consult-evidence";
+exports.CONSULT_EVIDENCE_RULE_VERSION_ID = "consult-evidence@ce0-v1";
+exports.CONSULT_EVIDENCE_RESPONSE_CEILING = "RECORD_ONLY";
+/** The closed, hashable identity of the compiled rule. All fields are strings; the seed
+ * versions are read from their owning modules so the payload cannot drift from the
+ * classifier / extractor actually wired into the adapter. */
+exports.CONSULT_EVIDENCE_RULE_PAYLOAD = {
+    schemaVersion: "ce0-rule-v1",
+    ruleId: exports.CONSULT_EVIDENCE_RULE_ID,
+    ruleVersionId: exports.CONSULT_EVIDENCE_RULE_VERSION_ID,
+    responseCeiling: exports.CONSULT_EVIDENCE_RESPONSE_CEILING,
+    trigger: {
+        classifierVersion: memory_requirement_1.MEMORY_REQUIREMENT_CLASSIFIER_VERSION,
+        markerSetVersion: memory_requirement_1.MEMORY_REQUIREMENT_MARKER_SET_VERSION,
+        exclusionSetVersion: memory_requirement_1.MEMORY_REQUIREMENT_EXCLUSION_SET_VERSION,
+    },
+    subject: {
+        extractorVersion: requirement_subject_1.REQUIREMENT_SUBJECT_EXTRACTOR_VERSION,
+        fingerprintSchemaVersion: requirement_subject_1.SUBJECT_FINGERPRINT_SCHEMA_VERSION,
+        stopwordSetVersion: requirement_subject_1.SUBJECT_STOPWORD_SET_VERSION,
+    },
+};
+/** sha256(RFC 8785 canonical JSON of the rule payload). Stamped on every obligation as
+ * its canonicalPayloadHash so the obligation attests which compiled rule produced it. */
+exports.CONSULT_EVIDENCE_CANONICAL_PAYLOAD_HASH = (0, canonical_json_1.sha256Hex)((0, canonical_json_1.canonicalize)(exports.CONSULT_EVIDENCE_RULE_PAYLOAD));

package/dist/lib/rules/ce0-sampling-bucket.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.samplingBucketFor = samplingBucketFor;
+const canonical_json_1 = require("./canonical-json");
+/** Deterministic, uniform sampling bucket for one assessment: sha256 over the canonical natural key,
+ * the same hashing discipline as the rule and subject fingerprints (canonical-json). The full digest
+ * carries maximum entropy and bakes in no sampling cardinality; the offline export thresholds it to
+ * pick the rate. */
+function samplingBucketFor(key) {
+    return (0, canonical_json_1.sha256Hex)((0, canonical_json_1.canonicalize)({
+        workspaceId: key.workspaceId,
+        sessionId: key.sessionId,
+        localTurnSequence: key.localTurnSequence,
+    }));
+}