@principles/core 1.277.0 → 1.277.2

package/dist/runtime-v2/internalization/tool-semantic-registry.js

@@ -0,0 +1,113 @@
+/**
+ * Tool Semantic Registry — PRI-634-F Phase 1 (Tool Semantic Closure)
+ *
+ * PURPOSE: One authoritative mapping from raw tool names to the closed
+ * CanonicalKind enum, so replay and production resolve identical tool
+ * semantics for the same raw name.
+ *
+ * OWNERSHIP (SPEC §5, mirroring the anti-drift note in rule-context-v2.ts):
+ *   - core owns the CLOSED CanonicalKind enum + the host-neutral baseline
+ *     table (generic LLM vocabulary names, no host-specific tools);
+ *   - each host owns its raw tool name list and declares mappings that are
+ *     layered on top of the baseline (host wins on conflict);
+ *   - core never grows the baseline with host tool names.
+ *
+ * Pure logic — zero I/O. Runtime Contract: mappings arrive as untrusted
+ * `unknown` at the public builder boundary and are validated structurally
+ * (rc-1, rc-2, rc-4, rc-5) before use.
+ */
+import { baselineToolAlias, CANONICAL_KIND_VALUES, isCanonicalKind } from './tool-semantic-baseline.js';
+const PROTO_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+function isPlainObjectLike(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Validate untrusted host mappings (rc-1: unknown until validated; rc-4: every
+ * element checked, not just "is array"; rc-5: Object.hasOwn over `in`).
+ */
+export function validateToolSemanticMappings(raw) {
+    if (!Array.isArray(raw)) {
+        return { valid: false, errors: ['toolSemanticMappings must be an array'] };
+    }
+    const errors = [];
+    const seen = new Map();
+    raw.forEach((entry, index) => {
+        if (!isPlainObjectLike(entry)) {
+            errors.push(`toolSemanticMappings[${index}] must be a plain object`);
+            return;
+        }
+        if (!Object.hasOwn(entry, 'rawToolName') || typeof entry.rawToolName !== 'string' || entry.rawToolName.trim() === '') {
+            errors.push(`toolSemanticMappings[${index}].rawToolName must be a non-empty string`);
+            return;
+        }
+        if (PROTO_KEYS.has(entry.rawToolName)) {
+            errors.push(`toolSemanticMappings[${index}].rawToolName must not be a prototype-pollution key`);
+            return;
+        }
+        const kind = entry.canonicalKind;
+        if (!isCanonicalKind(kind)) {
+            errors.push(`toolSemanticMappings[${index}].canonicalKind must be one of ${[...CANONICAL_KIND_VALUES].join('|')}, got ${String(kind)}`);
+            return;
+        }
+        // A host may repeat a raw name only with the SAME kind (idempotent
+        // declaration); a conflicting duplicate is a declaration defect.
+        const previous = seen.get(entry.rawToolName);
+        if (previous !== undefined && previous !== kind) {
+            errors.push(`toolSemanticMappings[${index}]: rawToolName '${entry.rawToolName}' declared twice with conflicting kinds (${previous} vs ${kind})`);
+            return;
+        }
+        seen.set(entry.rawToolName, kind);
+    });
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Build the effective registry: host mappings validated then layered over the
+ * host-neutral core baseline (host wins on conflict). Returns a discriminated
+ * result so an invalid host declaration fails loud at construction (rc-3)
+ * instead of silently degrading to baseline.
+ */
+export function buildToolSemanticRegistry(hostMappings) {
+    let merged;
+    const hostNames = new Set();
+    if (hostMappings === undefined) {
+        merged = baselineToolAlias;
+    }
+    else {
+        const validation = validateToolSemanticMappings(hostMappings);
+        if (!validation.valid) {
+            return { ok: false, errors: validation.errors };
+        }
+        const record = { ...baselineToolAlias };
+        for (const mapping of hostMappings) {
+            // validateToolSemanticMappings guarantees own-property safety
+            record[mapping.rawToolName] = mapping.canonicalKind;
+            hostNames.add(mapping.rawToolName);
+        }
+        merged = Object.freeze(record);
+    }
+    return {
+        ok: true,
+        registry: {
+            version: 1,
+            hasHostLayer: hostNames.size > 0,
+            hasHostTool(rawToolName) {
+                if (typeof rawToolName !== 'string')
+                    return false;
+                return hostNames.has(rawToolName);
+            },
+            lookup(rawToolName) {
+                if (typeof rawToolName !== 'string')
+                    return null;
+                // ERR-076: Object.hasOwn guards inherited Object.prototype keys
+                if (!Object.hasOwn(merged, rawToolName))
+                    return null;
+                const hit = merged[rawToolName];
+                return hit ?? null;
+            },
+            resolve(rawToolName) {
+                return this.lookup(rawToolName) ?? 'other';
+            },
+        },
+    };
+}
+//# sourceMappingURL=tool-semantic-registry.js.map

package/dist/runtime-v2/internalization/tool-semantic-registry.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/core",
-  "version": "1.277.0",
+  "version": "1.277.2",
   "description": "Pure-logic core of Principles Disciple, an AI Agent Governance System - pain signal capture and principle proposal (no I/O)",
   "type": "module",
   "main": "./dist/index.js",