@meetless/mla 0.1.4

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

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NOTES_FORBIDDEN_ROOT_RELATIVE = void 0;
+exports.selectNotesLocationDirective = selectNotesLocationDirective;
+exports.buildObservedNotesRuleSpec = buildObservedNotesRuleSpec;
+const applicability_1 = require("./applicability");
+// The R0 notes-location pilot (proposal §2.4): the single, named rule R0 observes.
+// This is NOT a generic rule-language framework and deliberately stays one rule:
+// its applicability, forbidden root, and effect are fixed pilot constants, and the
+// scan cache's only job is to tell us whether THIS workspace actually declares the
+// rule (so we observe it only where it is in force) and to hand us the exact prose
+// the agent was shown. Generalizing past one rule is explicitly a later ring.
+// The explicit applicability descriptor for the pilot. It is run through the same
+// parseApplicability validator every other applicability passes (never inferred):
+// action-scoped, file-writing tools only, gated to Markdown by the file_path field.
+const NOTES_LOCATION_APPLICABILITY_DESCRIPTOR = {
+    mode: "action",
+    tools: ["Write", "Edit"],
+    matcher: { field: "file_path", glob: "*.md" },
+};
+// The forbidden root the pilot protects, relative to the runtime project root. A
+// Write/Edit of a Markdown file UNDER this root is the violation; anything outside
+// is compliant. Kept as relative CONTENT so the rule is machine-independent.
+exports.NOTES_FORBIDDEN_ROOT_RELATIVE = "notes";
+// The effect the rule asserts when violated. PROHIBIT: rules constrain, never grant.
+const NOTES_EFFECT = "PROHIBIT";
+/**
+ * Select the single notes-location directive out of a scanned directive set, or
+ * null if this workspace declares no such rule. The predicate is deliberately
+ * TIGHT (one pilot, not a classifier): a directive qualifies only when its prose
+ * is about the notes/design-doc SUBJECT *and* carries a PLACEMENT sense (where it
+ * must or must not live). That keeps a bare "add release notes" mention from being
+ * mistaken for the rule. In observe-only R0 a false miss is a harmless
+ * NOT_APPLICABLE and a false match is a harmless OBSERVED; neither can enforce.
+ */
+function selectNotesLocationDirective(directives) {
+    return directives.find(isNotesLocationDirective) ?? null;
+}
+function isNotesLocationDirective(d) {
+    const t = d.text.toLowerCase();
+    const mentionsSubject = /\bnotes?\b/.test(t) || t.includes("design doc") || t.includes("design-doc");
+    const mentionsPlacement = t.includes("vault") ||
+        t.includes("standalone") ||
+        t.includes("not the") ||
+        t.includes("never the") ||
+        /\bgo(?:es)? in\b/.test(t) ||
+        /\bbelongs?\b/.test(t);
+    return mentionsSubject && mentionsPlacement;
+}
+/**
+ * Convert a selected notes-location directive into the in-memory ObservedRuleSpec
+ * the evaluator reads. The text comes from the scanned directive (the exact prose
+ * the agent saw); the applicability is parsed-and-validated from the pilot
+ * descriptor; the effect and forbidden root are pilot constants. Returns an error
+ * only if the pilot's own descriptor fails to parse, which is an infrastructure
+ * fault in MLA itself, never a rule violation.
+ */
+function buildObservedNotesRuleSpec(directive) {
+    const parsed = (0, applicability_1.parseApplicability)(NOTES_LOCATION_APPLICABILITY_DESCRIPTOR);
+    if (parsed.status !== "OK" || !parsed.applicability) {
+        return {
+            ok: false,
+            diagnostic: `notes-location applicability ${parsed.status}: ${parsed.diagnostic ?? "unparseable"}`,
+        };
+    }
+    return {
+        ok: true,
+        spec: {
+            text: directive.text,
+            applicability: parsed.applicability,
+            effect: NOTES_EFFECT,
+            forbiddenRootRelativePath: exports.NOTES_FORBIDDEN_ROOT_RELATIVE,
+        },
+    };
+}

package/dist/lib/rules/observe-adapter.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OBSERVE_TIMEOUT_MS = void 0;
+exports.parsePreToolUseInput = parsePreToolUseInput;
+exports.observePreToolUse = observePreToolUse;
+const evaluator_1 = require("./evaluator");
+const notes_path_1 = require("./notes-path");
+/** Production default for the hard evaluation timeout. */
+exports.OBSERVE_TIMEOUT_MS = 500;
+class TimeoutError extends Error {
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Parse and minimally validate the raw hook payload. Accepts either an already
+ * parsed object or the raw JSON string delivered on stdin. Returns null for any
+ * shape that is not a usable PreToolUse call; the adapter maps that null to an
+ * INFRA observation, never a violation.
+ */
+function parsePreToolUseInput(raw) {
+    let obj = raw;
+    if (typeof raw === "string") {
+        try {
+            obj = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!isPlainObject(obj)) {
+        return null;
+    }
+    const toolName = obj.tool_name;
+    if (typeof toolName !== "string" || toolName.length === 0) {
+        return null;
+    }
+    const toolInput = obj.tool_input;
+    if (!isPlainObject(toolInput)) {
+        return null;
+    }
+    const str = (v) => (typeof v === "string" ? v : undefined);
+    return {
+        session_id: str(obj.session_id),
+        transcript_path: str(obj.transcript_path),
+        cwd: str(obj.cwd),
+        hook_event_name: str(obj.hook_event_name),
+        tool_name: toolName,
+        tool_input: toolInput,
+        tool_use_id: str(obj.tool_use_id),
+        permission_mode: str(obj.permission_mode),
+    };
+}
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new TimeoutError("evaluation timed out")), ms);
+        if (typeof timer.unref === "function") {
+            timer.unref();
+        }
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+/**
+ * Observe a single PreToolUse call. Pure of enforcement: it computes what it
+ * observed and always returns an empty (decision-free) hook response.
+ */
+async function observePreToolUse(rawInput, config) {
+    const NO_DECISION = {};
+    const parsed = parsePreToolUseInput(rawInput);
+    if (!parsed) {
+        return { response: NO_DECISION, observation: { kind: "INFRA", diagnostic: "malformed hook input" } };
+    }
+    const call = { toolName: parsed.tool_name, toolInput: parsed.tool_input };
+    let selection;
+    try {
+        selection = (0, evaluator_1.selectRule)(call, config.applicability);
+    }
+    catch (err) {
+        return {
+            response: NO_DECISION,
+            observation: { kind: "INFRA", diagnostic: `selector failure: ${describeError(err)}` },
+        };
+    }
+    // Only an action rule that selected this call can be evaluated. Ambient rules
+    // (and any non-match) are never action gates, so there is nothing to observe.
+    if (selection === "NOT_APPLICABLE" || config.applicability.mode !== "action") {
+        return { response: NO_DECISION, observation: { kind: "NOT_APPLICABLE" } };
+    }
+    const rawFilePath = parsed.tool_input[config.applicability.matcher.field];
+    const classify = config.classify ?? notes_path_1.classifyTargetPath;
+    const timeoutMs = config.timeoutMs ?? exports.OBSERVE_TIMEOUT_MS;
+    let classification;
+    try {
+        classification = await withTimeout(classify(rawFilePath, config.notesScope), timeoutMs);
+    }
+    catch (err) {
+        const diagnostic = err instanceof TimeoutError ? "evaluation timed out" : `evaluator failure: ${describeError(err)}`;
+        return { response: NO_DECISION, observation: { kind: "INFRA", diagnostic } };
+    }
+    const verdict = (0, evaluator_1.verdictForForbiddenRoot)(classification);
+    return {
+        response: NO_DECISION,
+        observation: { kind: "OBSERVED", result: verdict.result, reasonCode: verdict.reasonCode },
+    };
+}

package/dist/lib/rules/observed-rule-hash.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObservedRuleHashError = exports.OBSERVED_RULE_HASH_DOMAIN = void 0;
+exports.buildObservedRulePayload = buildObservedRulePayload;
+exports.serializeObservedRule = serializeObservedRule;
+exports.observedRuleHash = observedRuleHash;
+const crypto_1 = require("crypto");
+const canonical_json_1 = require("./canonical-json");
+/**
+ * The `observed-rule-v1` canonical hash domain (proposal P0.36, sharpened by P0.53).
+ *
+ * It computes the content identity of an OBSERVED rule: the ephemeral, un-attested
+ * ObservedRuleSpec the scanner produced and the R0 evaluator reads. The digest is
+ *
+ *     SHA-256( domainTag || 0x00 || JCS(payload) )   (lowercase hex)
+ *
+ * where JCS is the repo's existing RFC 8785 canonicalizer (canonical-json.ts) and the
+ * domain tag + single 0x00 separator (P0.53) guarantee this digest can NEVER collide
+ * with an attested version (`rule-version-v1`), an action-input snapshot
+ * (`evaluation-input-v1`), or any other hashed artifact, even when two normalized bodies
+ * are byte-identical. JCS escapes control characters (a literal NUL in prose is emitted
+ * as its JSON unicode escape, not as a raw byte), so the only raw 0x00 byte in the hash
+ * input is the separator; the boundary between tag and payload is unambiguous.
+ *
+ * PROVISIONAL FIELD SET. The payload hashed here is EXACTLY today's evaluator-consumed
+ * ObservedRuleSpec (text, applicability, effect, forbiddenRootRelativePath). The fuller
+ * observed-rule-v1 field family from the proposal (rationale, the compliance-evaluator
+ * version triple, deliveryChannels, the observed enforcementCeiling, runtimeScopeId, the
+ * schema / canonical-serialization version tags) is owned by the schema/identity contract
+ * the document agent has not yet committed. When that contract lands, this payload schema
+ * and its golden-vector corpus rotate together. The domain-separation MACHINERY below is
+ * final; the field set is what is pending. (See ObservedRuleSpec in types.ts.)
+ *
+ * Per-field NFC caveat (honest, P0.53). The contract says NFC is applied ONLY to prose
+ * fields, while filesystem-derived and opaque values are byte-for-byte. The vendored JCS
+ * primitive applies NFC to EVERY string. For the R0 notes-location pilot every non-prose
+ * field (the tool names, the effect token, the matcher field and glob, the relative
+ * forbidden root) is ASCII and therefore NFC-stable, so universal NFC is byte-identical to
+ * the per-field rule and the golden vectors are contract-correct. When a future
+ * ObservedRuleSpec carries a non-prose field that can hold non-NFC Unicode (for instance a
+ * forbidden path with combining marks), this domain must switch to a per-field-NFC encoder
+ * so those bytes are preserved verbatim. That boundary is recorded in the ledger.
+ */
+exports.OBSERVED_RULE_HASH_DOMAIN = "observed-rule-v1";
+/** Thrown when a spec carries a field outside the observed-rule-v1 schema (fail-closed). */
+class ObservedRuleHashError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ObservedRuleHashError";
+    }
+}
+exports.ObservedRuleHashError = ObservedRuleHashError;
+// The closed key sets for each object in the payload schema. Unknown fields are an error
+// (P0.53), so a forward-incompatible producer cannot silently mint a hash a consumer would
+// compute differently. `glob` is the only optional key; it is omitted, never null, when absent.
+const OBSERVED_RULE_KEYS = new Set(["text", "applicability", "effect", "forbiddenRootRelativePath"]);
+const APPLICABILITY_AMBIENT_KEYS = new Set(["mode"]);
+const APPLICABILITY_ACTION_KEYS = new Set(["mode", "tools", "matcher"]);
+const MATCHER_KEYS = new Set(["field", "glob"]);
+function rejectUnknownKeys(obj, allowed, context) {
+    for (const key of Object.keys(obj)) {
+        if (!allowed.has(key)) {
+            throw new ObservedRuleHashError(`unknown field '${key}' in ${context} is outside the ${exports.OBSERVED_RULE_HASH_DOMAIN} schema`);
+        }
+    }
+}
+/** Sort + dedupe a SET-valued field by code unit (P0.53). Tool names are ASCII, so code
+ * unit and code point coincide; the comparison matches the JCS object-key ordering. */
+function sortedDedupedSet(values) {
+    return Array.from(new Set(values)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+function buildApplicabilityPayload(a) {
+    if (a.mode === "ambient") {
+        rejectUnknownKeys(a, APPLICABILITY_AMBIENT_KEYS, "applicability(ambient)");
+        return { mode: "ambient" };
+    }
+    rejectUnknownKeys(a, APPLICABILITY_ACTION_KEYS, "applicability(action)");
+    rejectUnknownKeys(a.matcher, MATCHER_KEYS, "applicability.matcher");
+    // Absent optional: OMIT the key (never null). Present: include verbatim.
+    const matcher = { field: a.matcher.field };
+    if (a.matcher.glob !== undefined) {
+        matcher.glob = a.matcher.glob;
+    }
+    return {
+        mode: "action",
+        // SET discipline: sorted + deduped so two logically-equal tool sets hash identically.
+        tools: sortedDedupedSet(a.tools),
+        matcher,
+    };
+}
+/**
+ * Build the closed canonical payload for an ObservedRuleSpec: the exact object that gets
+ * canonicalized and hashed. Rejects unknown fields, applies set discipline to `tools`, and
+ * omits an absent matcher glob. Field NFC (prose) is applied by the JCS encoder on the way
+ * out; see the per-field caveat in the file header.
+ */
+function buildObservedRulePayload(spec) {
+    rejectUnknownKeys(spec, OBSERVED_RULE_KEYS, "observed rule");
+    return {
+        text: spec.text,
+        applicability: buildApplicabilityPayload(spec.applicability),
+        effect: spec.effect,
+        forbiddenRootRelativePath: spec.forbiddenRootRelativePath,
+    };
+}
+/** The exact RFC 8785 canonical JSON string that is hashed (UTF-8). Exposed for golden
+ * vectors and debugging; the digest is over these bytes prefixed by the domain. */
+function serializeObservedRule(spec) {
+    return (0, canonical_json_1.canonicalize)(buildObservedRulePayload(spec));
+}
+/** The observed-rule-v1 content hash: SHA-256(domainTag || 0x00 || JCS(payload)), lowercase hex. */
+function observedRuleHash(spec) {
+    const jcs = serializeObservedRule(spec);
+    const h = (0, crypto_1.createHash)("sha256");
+    h.update(exports.OBSERVED_RULE_HASH_DOMAIN, "utf8");
+    h.update(Buffer.from([0x00]));
+    h.update(jcs, "utf8");
+    return h.digest("hex");
+}

package/dist/lib/rules/prompt-submit-adapter.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseUserPromptSubmitInput = parseUserPromptSubmitInput;
+exports.observeUserPromptSubmit = observeUserPromptSubmit;
+const crypto_1 = require("crypto");
+const ce0_store_1 = require("./ce0-store");
+const canonical_json_1 = require("./canonical-json");
+const memory_requirement_1 = require("./memory-requirement");
+const requirement_subject_1 = require("./requirement-subject");
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function defaultNewId(kind) {
+    return `${kind === "assessment" ? "asm" : "obl"}:${(0, crypto_1.randomUUID)()}`;
+}
+/**
+ * Parse and minimally validate the raw hook payload. Accepts either an already parsed
+ * object or the raw JSON string delivered on stdin. Returns null for any shape that is
+ * not a usable UserPromptSubmit turn (the adapter maps that null to INFRA). A turn is
+ * usable iff it carries a non-empty string `prompt`; the session coordinate is checked
+ * separately so its absence gets a distinct diagnostic.
+ */
+function parseUserPromptSubmitInput(raw) {
+    let obj = raw;
+    if (typeof raw === "string") {
+        try {
+            obj = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!isPlainObject(obj)) {
+        return null;
+    }
+    const prompt = obj.prompt;
+    if (typeof prompt !== "string" || prompt.length === 0) {
+        return null;
+    }
+    const str = (v) => (typeof v === "string" ? v : undefined);
+    return {
+        session_id: str(obj.session_id),
+        transcript_path: str(obj.transcript_path),
+        cwd: str(obj.cwd),
+        hook_event_name: str(obj.hook_event_name),
+        prompt,
+    };
+}
+/**
+ * Observe a single user turn: classify its memory requirement, mint its LocalTurnIdentity
+ * and persist the assessment, and create a TurnRuleObligation iff the turn is REQUIRED.
+ * Always returns an empty (injection-free) hook response.
+ */
+function observeUserPromptSubmit(rawInput, config) {
+    const NO_INJECTION = {};
+    const parsed = parseUserPromptSubmitInput(rawInput);
+    if (!parsed) {
+        return { response: NO_INJECTION, outcome: { kind: "INFRA", diagnostic: "malformed hook input" } };
+    }
+    if (!parsed.session_id) {
+        return {
+            response: NO_INJECTION,
+            outcome: { kind: "INFRA", diagnostic: "missing session_id coordinate" },
+        };
+    }
+    const now = config.now ?? Date.now;
+    const newId = config.newId ?? defaultNewId;
+    const classification = (0, memory_requirement_1.classifyMemoryRequirement)(parsed.prompt);
+    // Narrow the session coordinate once, past the guard above, so it stays `string` inside the
+    // obligation builder closure (a property read on the mutable `parsed` would widen back to optional).
+    const sessionId = parsed.session_id;
+    try {
+        const draft = {
+            assessmentId: newId("assessment"),
+            workspaceId: config.workspaceId,
+            sessionId,
+            requirement: classification.requirement,
+            markersMatched: classification.markersMatched,
+            exclusionsMatched: classification.exclusionsMatched,
+            classifierVersion: classification.classifierVersion,
+            markerSetVersion: classification.markerSetVersion,
+            exclusionSetVersion: classification.exclusionSetVersion,
+            createdAt: now(),
+            // R4 P0.1 recall snapshot (proposal lines 287-295): the prompt's identity-only hash, born
+            // here at classification. Content-free: the raw prompt is never duplicated into the record.
+            promptHash: (0, canonical_json_1.sha256Hex)(parsed.prompt),
+        };
+        // Open the turn ATOMICALLY: the assessment and (for a REQUIRED turn) its obligation are written in
+        // one BEGIN IMMEDIATE transaction, so a persistence failure can never leave a REQUIRED assessment
+        // without the obligation that grades it (proposal §1.3 req 1, R4 P0.4). The obligation is built
+        // INSIDE the transaction from the freshly minted assessment so it carries the same localTurnSequence;
+        // a non-REQUIRED turn returns null and records only its assessment.
+        const { assessment, obligation } = (0, ce0_store_1.openTurnAtomically)(config.store, draft, (a) => classification.requirement !== "REQUIRED"
+            ? null
+            : {
+                obligationId: newId("obligation"),
+                workspaceId: config.workspaceId,
+                sessionId,
+                localTurnSequence: a.localTurnSequence,
+                ruleId: config.ruleBinding.ruleId,
+                ruleVersionId: config.ruleBinding.ruleVersionId,
+                requiredSubjects: [(0, requirement_subject_1.buildRequiredSubjectFromPrompt)(parsed.prompt)],
+                subjectSatisfaction: [],
+                status: "OPEN",
+                stateVersion: 0,
+                deadlineClaimedAt: null,
+                deadlineClaimedVersion: null,
+                responseHash: null,
+                outcome: null,
+                canonicalPayloadHash: config.ruleBinding.canonicalPayloadHash,
+            });
+        return {
+            response: NO_INJECTION,
+            outcome: {
+                kind: "ASSESSED",
+                requirement: classification.requirement,
+                assessmentId: assessment.assessmentId,
+                localTurnSequence: assessment.localTurnSequence,
+                obligationId: obligation ? obligation.obligationId : null,
+            },
+        };
+    }
+    catch (err) {
+        return {
+            response: NO_INJECTION,
+            outcome: { kind: "INFRA", diagnostic: `persistence failure: ${describeError(err)}` },
+        };
+    }
+}