@principles/core 1.196.0 → 1.198.0

package/dist/runtime-v2/internalization/rule-context-v2.js

@@ -0,0 +1,301 @@
+/**
+ * PRI-480 — Phase 1 Core ABI (rule-context-v2.ts)
+ *
+ * Pure logic: types + canonicalize + validators + behavior-facts computation.
+ * Zero I/O — this module MUST NOT import node:fs / node:path / better-sqlite3 /
+ * any network module. The runtime-v2 architecture-regression test enforces the
+ * file boundary.
+ *
+ * Err-prevention:
+ *   - ERR-001 (validate-as-unknown): every public validator takes `unknown` and
+ *     validates structurally. No `as` bypass on parsed input.
+ *   - ERR-076 (prototype-pollution / host-realm independence): structural checks
+ *     use Object.keys + a PROTO_KEYS set. We never touch the host realm's
+ *     prototype chain (no `instanceof`, no `in`).
+ *   - rc-2: no `as` casts on parsed input.
+ *   - rc-5: Object.hasOwn / Object.keys over the `in` operator.
+ *
+ * Spec: docs/superpowers/specs/2026-06-27-rulecode-context-vision-design.md §4.
+ */
+// ── internal constants ─────────────────────────────────────────────────────
+const CANONICAL_KINDS = new Set([
+    'read',
+    'search',
+    'write',
+    'execute',
+    'agent',
+    'other',
+]);
+const EVIDENCE_STATES = new Set(['yes', 'no', 'unknown']);
+const TOOL_OUTCOMES = new Set(['success', 'failure', 'blocked']);
+const HISTORY_STATUSES = new Set(['available', 'unavailable']);
+const PROTO_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+const OK_RESULT = { valid: true, errors: [] };
+function fail(errors) {
+    return errors.length === 0 ? OK_RESULT : { valid: false, errors };
+}
+function isPlainObjectLike(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasNoProtoKeys(value) {
+    for (const key of Object.keys(value)) {
+        if (PROTO_KEYS.has(key))
+            return false;
+    }
+    return true;
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function isNullOrNonNegativeFinite(value) {
+    return value === null || (typeof value === 'number' && Number.isFinite(value) && value >= 0);
+}
+// ── canonicalizeToolKind (static alias table, spec §4.4) ────────────────────
+//
+// NOTE: the authoritative source for canonical kinds SHOULD be a host declaration
+// (spec §4.4 anti-drift note), so that `core` never owns a growing hardcoded
+// tool list. The first version uses a static alias table (ticket-bounded); a
+// later phase will let hosts declare `ruleCanonicalKind` overrides. core only
+// owns the CLOSED CanonicalKind enum + this pure lookup function.
+const TOOL_ALIAS = {
+    read: 'read',
+    read_file: 'read',
+    read_many_files: 'read',
+    grep: 'search',
+    grep_search: 'search',
+    search_file_content: 'search',
+    glob: 'search',
+    write: 'write',
+    write_file: 'write',
+    edit: 'write',
+    edit_file: 'write',
+    replace: 'write',
+    apply_patch: 'write',
+    bash: 'execute',
+    exec: 'execute',
+    execute: 'execute',
+    run_shell_command: 'execute',
+    sessions_spawn: 'agent',
+};
+export function canonicalizeToolKind(toolName) {
+    if (typeof toolName !== 'string')
+        return 'other';
+    // ERR-076: Object.hasOwn guards against inherited Object.prototype keys
+    // (__proto__, constructor, toString, hasOwnProperty, ...) that direct
+    // indexing would otherwise leak as non-CanonicalKind values (e.g. the
+    // Object.prototype object, the Object constructor function). Without this
+    // guard `TOOL_ALIAS['__proto__']` returns Object.prototype, not undefined.
+    if (!Object.hasOwn(TOOL_ALIAS, toolName))
+        return 'other';
+    const hit = TOOL_ALIAS[toolName];
+    return hit !== undefined ? hit : 'other';
+}
+// ── validators ─────────────────────────────────────────────────────────────
+export function validateRuleToolCallRecord(value) {
+    if (!isPlainObjectLike(value)) {
+        return { valid: false, errors: ['record must be a plain object'] };
+    }
+    if (!hasNoProtoKeys(value)) {
+        return { valid: false, errors: ['record must not carry prototype-pollution keys'] };
+    }
+    const errors = [];
+    if (!isFiniteNumber(value.sequenceId)) {
+        errors.push('sequenceId must be a finite number');
+    }
+    const { toolName } = value;
+    if (typeof toolName !== 'string' || toolName.length === 0) {
+        errors.push('toolName must be a non-empty string');
+    }
+    const { canonicalKind } = value;
+    if (typeof canonicalKind !== 'string' || !CANONICAL_KINDS.has(canonicalKind)) {
+        errors.push('canonicalKind must be a valid CanonicalKind');
+    }
+    const { normalizedPath } = value;
+    if (normalizedPath !== null && typeof normalizedPath !== 'string') {
+        errors.push('normalizedPath must be a string or null');
+    }
+    if (!isPlainObjectLike(value.paramsSummary)) {
+        errors.push('paramsSummary must be a plain object');
+    }
+    const { outcome } = value;
+    if (typeof outcome !== 'string' || !TOOL_OUTCOMES.has(outcome)) {
+        errors.push('outcome must be success | failure | blocked');
+    }
+    return fail(errors);
+}
+export function validateRuleHistoryWindow(value) {
+    if (!isPlainObjectLike(value)) {
+        return { valid: false, errors: ['history window must be a plain object'] };
+    }
+    if (!hasNoProtoKeys(value)) {
+        return { valid: false, errors: ['history window must not carry prototype-pollution keys'] };
+    }
+    const errors = [];
+    const { status } = value;
+    if (typeof status !== 'string' || !HISTORY_STATUSES.has(status)) {
+        errors.push('status must be available | unavailable');
+    }
+    const { unavailableReason } = value;
+    if (unavailableReason !== undefined && typeof unavailableReason !== 'string') {
+        errors.push('unavailableReason must be a string or undefined');
+    }
+    if (typeof value.truncated !== 'boolean') {
+        errors.push('truncated must be a boolean');
+    }
+    const { calls } = value;
+    if (!Array.isArray(calls)) {
+        errors.push('calls must be an array');
+    }
+    else {
+        for (let i = 0; i < calls.length; i++) {
+            const recordResult = validateRuleToolCallRecord(calls[i]);
+            if (!recordResult.valid) {
+                errors.push(`calls[${i}] invalid: ${recordResult.errors.join('; ')}`);
+            }
+        }
+    }
+    return fail(errors);
+}
+export function validateRuleBehaviorFacts(value) {
+    if (!isPlainObjectLike(value)) {
+        return { valid: false, errors: ['facts must be a plain object'] };
+    }
+    if (!hasNoProtoKeys(value)) {
+        return { valid: false, errors: ['facts must not carry prototype-pollution keys'] };
+    }
+    const errors = [];
+    const { priorReadOfTarget } = value;
+    if (typeof priorReadOfTarget !== 'string' || !EVIDENCE_STATES.has(priorReadOfTarget)) {
+        errors.push('priorReadOfTarget must be yes | no | unknown');
+    }
+    if (!isNullOrNonNegativeFinite(value.readCount)) {
+        errors.push('readCount must be a non-negative finite number or null');
+    }
+    if (!isNullOrNonNegativeFinite(value.writeCount)) {
+        errors.push('writeCount must be a non-negative finite number or null');
+    }
+    if (!isNullOrNonNegativeFinite(value.uniqueWritePathCount)) {
+        errors.push('uniqueWritePathCount must be a non-negative finite number or null');
+    }
+    if (!isNullOrNonNegativeFinite(value.sameActionBlockCount)) {
+        errors.push('sameActionBlockCount must be a non-negative finite number or null');
+    }
+    return fail(errors);
+}
+export function validateRuleContextV2(value) {
+    if (!isPlainObjectLike(value)) {
+        return { valid: false, errors: ['context must be a plain object'] };
+    }
+    if (!hasNoProtoKeys(value)) {
+        return { valid: false, errors: ['context must not carry prototype-pollution keys'] };
+    }
+    const errors = [];
+    if (value.version !== 2) {
+        errors.push('version must be 2');
+    }
+    const historyResult = validateRuleHistoryWindow(value.history);
+    if (!historyResult.valid) {
+        errors.push(`history invalid: ${historyResult.errors.join('; ')}`);
+    }
+    const factsResult = validateRuleBehaviorFacts(value.facts);
+    if (!factsResult.valid) {
+        errors.push(`facts invalid: ${factsResult.errors.join('; ')}`);
+    }
+    // Unavailable invariant (acceptance C): when history.status === 'unavailable',
+    // facts MUST be the canonical unavailable posture — priorReadOfTarget='unknown'
+    // and every count null. Any drift is rejected so downstream gates can't be
+    // fooled by a host that fabricates numbers while claiming history is missing.
+    const { history } = value;
+    const { facts } = value;
+    if (historyResult.valid &&
+        factsResult.valid &&
+        isPlainObjectLike(history) &&
+        isPlainObjectLike(facts) &&
+        history.status === 'unavailable') {
+        if (facts.priorReadOfTarget !== 'unknown') {
+            errors.push('unavailable invariant: priorReadOfTarget must be "unknown" when history is unavailable');
+        }
+        if (facts.readCount !== null) {
+            errors.push('unavailable invariant: readCount must be null when history is unavailable');
+        }
+        if (facts.writeCount !== null) {
+            errors.push('unavailable invariant: writeCount must be null when history is unavailable');
+        }
+        if (facts.uniqueWritePathCount !== null) {
+            errors.push('unavailable invariant: uniqueWritePathCount must be null when history is unavailable');
+        }
+        if (facts.sameActionBlockCount !== null) {
+            errors.push('unavailable invariant: sameActionBlockCount must be null when history is unavailable');
+        }
+    }
+    return fail(errors);
+}
+// ── computeBehaviorFacts (pure) ────────────────────────────────────────────
+export function computeBehaviorFacts(window, targetPath, sameActionBlockCount) {
+    if (window.status === 'unavailable') {
+        return {
+            priorReadOfTarget: 'unknown',
+            readCount: null,
+            writeCount: null,
+            uniqueWritePathCount: null,
+            sameActionBlockCount: null,
+        };
+    }
+    let readCount = 0;
+    let writeCount = 0;
+    const writePaths = new Set();
+    let priorReadOfTarget = targetPath === null ? 'unknown' : 'no';
+    const { calls } = window;
+    for (const call of calls) {
+        const kind = call.canonicalKind;
+        if (kind === 'read' || kind === 'search') {
+            readCount++;
+            if (targetPath !== null && call.normalizedPath === targetPath) {
+                priorReadOfTarget = 'yes';
+            }
+        }
+        else if (kind === 'write') {
+            writeCount++;
+            if (typeof call.normalizedPath === 'string') {
+                writePaths.add(call.normalizedPath);
+            }
+        }
+    }
+    return {
+        priorReadOfTarget,
+        readCount,
+        writeCount,
+        uniqueWritePathCount: writePaths.size,
+        sameActionBlockCount,
+    };
+}
+// ── UNAVAILABLE_RULE_CONTEXT sentinel (deep-frozen) ────────────────────────
+//
+// The canonical "host gave us no history" context. Downstream code compares
+// against this (or checks history.status) instead of null-checking, so the
+// unavailable posture is always well-typed. Deep-frozen so a buggy host cannot
+// mutate the shared sentinel and poison every subsequent rule evaluation.
+const _UNAVAILABLE_FACTS = {
+    priorReadOfTarget: 'unknown',
+    readCount: null,
+    writeCount: null,
+    uniqueWritePathCount: null,
+    sameActionBlockCount: null,
+};
+Object.freeze(_UNAVAILABLE_FACTS);
+const _UNAVAILABLE_HISTORY = {
+    status: 'unavailable',
+    unavailableReason: 'host did not provide a history window',
+    truncated: false,
+    calls: [],
+};
+Object.freeze(_UNAVAILABLE_HISTORY.calls);
+Object.freeze(_UNAVAILABLE_HISTORY);
+const _UNAVAILABLE_VALUE = {
+    version: 2,
+    history: _UNAVAILABLE_HISTORY,
+    facts: _UNAVAILABLE_FACTS,
+};
+Object.freeze(_UNAVAILABLE_VALUE);
+export const UNAVAILABLE_RULE_CONTEXT = _UNAVAILABLE_VALUE;
+//# sourceMappingURL=rule-context-v2.js.map

package/dist/runtime-v2/internalization/rule-context-v2.js.map

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

package/dist/runtime-v2/internalization/rule-host-contracts.d.ts

@@ -11,6 +11,7 @@
  *   - No filesystem, process, require, dynamic import, eval, or network access
  */
 import type { CorrectionProposal } from './correction-proposal.js';
+import type { RuleContextV2 } from './rule-context-v2.js';
 export interface RuleHostInput {
     action: {
         toolName: string;
@@ -34,6 +35,14 @@ export interface RuleHostInput {
         estimatedLineChanges: number;
         bashRisk: 'safe' | 'normal' | 'dangerous' | 'unknown';
     };
+    /**
+     * PRI-480 (RuleContext v2 — Phase 1): optional structured context describing
+     * the recent tool-call history and derived behavior facts. Optional on purpose
+     * — v1 rule implementations that never read this field see `undefined` and
+     * behave exactly as before. Hosts opt in by populating the field; downstream
+     * phases will gate new rule behavior on `context?.history.status === 'available'`.
+     */
+    context?: RuleContextV2;
 }
 export type RuleHostDecision = 'allow' | 'block' | 'requireApproval' | 'auto_correct';
 export interface RuleHostMeta {

package/dist/runtime-v2/internalization/rule-host-contracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rule-host-contracts.d.ts","sourceRoot":"","sources":["../../../src/runtime-v2/internalization/rule-host-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAMnE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE;QACN,QAAQ,EAAE,MAAM,CAAC;QACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;QAC9B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACxC,CAAC;IACF,SAAS,EAAE;QACT,UAAU,EAAE,OAAO,CAAC;QACpB,UAAU,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;QACnD,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;IACF,OAAO,EAAE;QACP,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,OAAO,CAAC;KACzB,CAAC;IACF,SAAS,EAAE;QACT,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,OAAO,EAAE;QACP,oBAAoB,EAAE,MAAM,CAAC;QAC7B,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;KACvD,CAAC;CACH;AAMD,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,OAAO,GAAG,iBAAiB,GAAG,cAAc,CAAC;AAMtF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;CACzB;AAMD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;CACzC;AAMD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,cAAc,CAAC;CACrD"}
+{"version":3,"file":"rule-host-contracts.d.ts","sourceRoot":"","sources":["../../../src/runtime-v2/internalization/rule-host-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAM1D,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE;QACN,QAAQ,EAAE,MAAM,CAAC;QACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;QAC9B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACxC,CAAC;IACF,SAAS,EAAE;QACT,UAAU,EAAE,OAAO,CAAC;QACpB,UAAU,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;QACnD,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;IACF,OAAO,EAAE;QACP,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,OAAO,CAAC;KACzB,CAAC;IACF,SAAS,EAAE;QACT,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,OAAO,EAAE;QACP,oBAAoB,EAAE,MAAM,CAAC;QAC7B,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;KACvD,CAAC;IACF;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAMD,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,OAAO,GAAG,iBAAiB,GAAG,cAAc,CAAC;AAMtF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;CACzB;AAMD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;CACzC;AAMD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,cAAc,CAAC;CACrD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/core",
-  "version": "1.196.0",
+  "version": "1.198.0",
   "description": "Universal Evolution SDK - framework-agnostic pain signal capture and principle injection",
   "type": "module",
   "main": "./dist/index.js",