chainlesschain 0.166.20 → 0.166.21

package/src/lib/skill-retrieval-router.js

@@ -0,0 +1,235 @@
+import { BM25Search } from "./bm25-search.js";
+
+export const SKILL_RETRIEVAL_RESULT_SCHEMA =
+  "chainlesschain.skill-retrieval-result/v1";
+export const MAX_ROUTABLE_SKILLS = 10_000;
+
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+
+function finite(value, fallback = 0) {
+  return Number.isFinite(Number(value)) ? Number(value) : fallback;
+}
+
+function normalize(scores) {
+  const values = [...scores.values()];
+  const max = Math.max(0, ...values);
+  if (max === 0) return new Map([...scores].map(([key]) => [key, 0]));
+  return new Map([...scores].map(([key, value]) => [key, value / max]));
+}
+
+function digestFor(skill) {
+  const value = skill?.executionIdentity?.contentDigest;
+  return DIGEST.test(value || "") ? value : null;
+}
+
+function containsPath(skill, targetPath) {
+  if (!targetPath || !Array.isArray(skill.paths) || skill.paths.length === 0)
+    return true;
+  const normalized = String(targetPath).replaceAll("\\", "/");
+  return skill.paths.some((scope) => {
+    const prefix = String(scope).replaceAll("\\", "/").replace(/\/$/u, "");
+    return normalized === prefix || normalized.startsWith(`${prefix}/`);
+  });
+}
+
+function compatible(skill, target) {
+  if (!target) return { accepted: true, reasons: [] };
+  const reasons = [];
+  if (
+    Array.isArray(skill.os) &&
+    skill.os.length > 0 &&
+    target.os &&
+    !skill.os.includes(target.os)
+  ) {
+    reasons.push(`os:${target.os}`);
+  }
+  if (
+    Array.isArray(target.allowedCapabilities) &&
+    Array.isArray(skill.capabilities)
+  ) {
+    const allowed = new Set(target.allowedCapabilities);
+    const denied = skill.capabilities.filter((value) => !allowed.has(value));
+    if (denied.length > 0) reasons.push(`capability:${denied.join(",")}`);
+  }
+  return { accepted: reasons.length === 0, reasons };
+}
+
+function metricFor(metrics, digest) {
+  const value = metrics?.[digest] ?? metrics?.get?.(digest) ?? null;
+  if (value === null) return { samples: 0, successRate: 0, correctionRate: 0 };
+  const samples = finite(value.samples);
+  const successRate = finite(value.successRate);
+  const correctionRate = finite(value.correctionRate);
+  if (
+    !Number.isSafeInteger(samples) ||
+    samples < 0 ||
+    successRate < 0 ||
+    successRate > 1 ||
+    correctionRate < 0 ||
+    correctionRate > 1
+  ) {
+    throw new TypeError("Skill outcome metrics are invalid");
+  }
+  return { samples, successRate, correctionRate };
+}
+
+export function routeSkillDescriptors({
+  skills,
+  query,
+  namespace = null,
+  tags = [],
+  targetPath = null,
+  target = null,
+  vectorScores = null,
+  outcomeMetrics = null,
+  topK = 5,
+  ambiguityMargin = 0.02,
+} = {}) {
+  if (
+    !Array.isArray(skills) ||
+    skills.length > MAX_ROUTABLE_SKILLS ||
+    typeof query !== "string" ||
+    query.trim().length < 1 ||
+    query.length > 4096 ||
+    !Array.isArray(tags) ||
+    !Number.isSafeInteger(topK) ||
+    topK < 1 ||
+    topK > 64 ||
+    !Number.isFinite(ambiguityMargin) ||
+    ambiguityMargin < 0 ||
+    ambiguityMargin > 1
+  ) {
+    throw new TypeError("Skill retrieval request is invalid or unbounded");
+  }
+  const requiredTags = new Set(
+    tags.map((value) => String(value).toLowerCase()),
+  );
+  const rejected = [];
+  const admitted = [];
+  for (const skill of skills) {
+    const digest = digestFor(skill);
+    const skillTags = new Set(
+      (Array.isArray(skill.tags) ? skill.tags : []).map((value) =>
+        String(value).toLowerCase(),
+      ),
+    );
+    const mismatch = compatible(skill, target);
+    const reasons = [];
+    if (!digest) reasons.push("missing-content-digest");
+    if (namespace !== null && skill.source !== namespace)
+      reasons.push("namespace-mismatch");
+    if ([...requiredTags].some((value) => !skillTags.has(value)))
+      reasons.push("tag-mismatch");
+    if (!containsPath(skill, targetPath)) reasons.push("path-mismatch");
+    reasons.push(...mismatch.reasons);
+    if (reasons.length > 0) {
+      rejected.push({ id: skill.id, digest, reasons });
+      continue;
+    }
+    admitted.push({ skill, digest });
+  }
+
+  const bm25 = new BM25Search({ language: "auto" });
+  bm25.indexDocuments(
+    admitted.map(({ skill, digest }) => ({
+      id: digest,
+      title: `${skill.id} ${skill.displayName || ""} ${(skill.tags || []).join(" ")}`,
+      content: `${skill.description || ""} ${skill.category || ""}`,
+    })),
+  );
+  const bm25Scores = normalize(
+    new Map(
+      bm25
+        .search(query, { topK: admitted.length || 1, threshold: 0 })
+        .map(({ id, score }) => [id, score]),
+    ),
+  );
+  const vector = normalize(
+    new Map(
+      admitted.map(({ digest }) => [
+        digest,
+        Math.max(
+          0,
+          finite(vectorScores?.[digest] ?? vectorScores?.get?.(digest)),
+        ),
+      ]),
+    ),
+  );
+  const vectorAvailable = [...vector.values()].some((value) => value > 0);
+  const candidates = admitted
+    .map(({ skill, digest }) => {
+      const lexicalScore = bm25Scores.get(digest) || 0;
+      const vectorScore = vector.get(digest) || 0;
+      const outcome = metricFor(outcomeMetrics, digest);
+      const outcomeScore =
+        outcome.samples === 0
+          ? 0.5
+          : outcome.successRate * (1 - outcome.correctionRate);
+      const score =
+        lexicalScore * (vectorAvailable ? 0.45 : 0.75) +
+        vectorScore * (vectorAvailable ? 0.35 : 0) +
+        outcomeScore * (vectorAvailable ? 0.2 : 0.25);
+      return {
+        id: skill.id,
+        displayName: skill.displayName || skill.id,
+        namespace: skill.source,
+        version: String(skill.version || "1.0.0"),
+        digest,
+        category: skill.category || "uncategorized",
+        contextCostTokens: Math.ceil(
+          `${skill.id}\n${skill.description || ""}\n${skill.category || ""}`
+            .length / 4,
+        ),
+        score,
+        scores: {
+          lexical: lexicalScore,
+          vector: vectorScore,
+          outcome: outcomeScore,
+        },
+        outcome,
+        reason: `bm25=${lexicalScore.toFixed(3)}, vector=${vectorScore.toFixed(3)}, outcome=${outcomeScore.toFixed(3)}`,
+      };
+    })
+    .filter(({ scores }) => scores.lexical > 0 || scores.vector > 0)
+    .sort(
+      (left, right) =>
+        right.score - left.score || left.digest.localeCompare(right.digest),
+    );
+
+  const conflicts = [];
+  const byName = new Map();
+  for (const candidate of candidates) {
+    const key = candidate.id.toLowerCase();
+    const prior = byName.get(key);
+    if (prior && prior.digest !== candidate.digest) {
+      conflicts.push({
+        type: "same-name-different-version",
+        name: candidate.id,
+        digests: [prior.digest, candidate.digest].sort(),
+      });
+    } else byName.set(key, candidate);
+  }
+  const returned = candidates.slice(0, topK);
+  const ambiguous =
+    returned.length > 1 &&
+    returned[0].score - returned[1].score < ambiguityMargin;
+  if (ambiguous) {
+    conflicts.push({
+      type: "ambiguous-top-score",
+      digests: [returned[0].digest, returned[1].digest],
+      margin: returned[0].score - returned[1].score,
+    });
+  }
+  const topConflict = conflicts.some(({ digests }) =>
+    digests?.includes(returned[0]?.digest),
+  );
+  return Object.freeze({
+    schema: SKILL_RETRIEVAL_RESULT_SCHEMA,
+    query: query.trim(),
+    selected: returned.length > 0 && !topConflict ? returned[0] : null,
+    candidates: Object.freeze(returned.map(Object.freeze)),
+    conflicts: Object.freeze(conflicts.map(Object.freeze)),
+    rejected: Object.freeze(rejected.map(Object.freeze)),
+    vectorAvailable,
+  });
+}

package/src/lib/skill-vector-authority.js

@@ -0,0 +1,325 @@
+import { createHash } from "node:crypto";
+import { types as utilTypes } from "node:util";
+
+export const SKILL_VECTOR_REQUEST_SCHEMA =
+  "chainlesschain.skill-vector-request/v1";
+export const SKILL_VECTOR_RESULT_SCHEMA =
+  "chainlesschain.skill-vector-result/v1";
+export const SKILL_VECTOR_AUTHORITY_SCHEMA =
+  "chainlesschain.skill-vector-authority/v1";
+export const SKILL_VECTOR_ATTESTATION_SCHEMA =
+  "chainlesschain.skill-vector-attestation/v1";
+
+const AUTHORITIES = new WeakSet();
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,255}$/u;
+const MAX_SKILLS = 10_000;
+const MAX_TEXT_BYTES = 8 * 1024 * 1024;
+const RESULT_KEYS = new Set([
+  "attestation",
+  "corpusDigest",
+  "indexDigest",
+  "modelId",
+  "modelRevision",
+  "requestDigest",
+  "resultDigest",
+  "schema",
+  "scores",
+  "tenantId",
+]);
+const SCORE_KEYS = new Set(["digest", "score"]);
+const ATTESTATION_KEYS = new Set(["algorithm", "keyId", "schema", "value"]);
+const VERIFICATION_KEYS = new Set([
+  "authenticated",
+  "durable",
+  "receiptDigest",
+  "requestDigest",
+  "resultDigest",
+  "tenantId",
+]);
+
+function canonical(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  return `{${Object.keys(value)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
+    .join(",")}}`;
+}
+
+function hash(domain, value) {
+  return `sha256:${createHash("sha256")
+    .update(domain)
+    .update("\0")
+    .update(canonical(value))
+    .digest("hex")}`;
+}
+
+function exact(value, keys, label) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    utilTypes.isProxy(value) ||
+    Reflect.ownKeys(value).length !== keys.size ||
+    Reflect.ownKeys(value).some(
+      (key) => typeof key !== "string" || !keys.has(key),
+    )
+  ) {
+    throw new TypeError(`${label} is invalid`);
+  }
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) {
+      throw new TypeError(`${label}.${String(key)} is invalid`);
+    }
+  }
+  return value;
+}
+
+function identifier(value, label) {
+  if (typeof value !== "string" || !SAFE_ID.test(value)) {
+    throw new TypeError(`${label} is invalid`);
+  }
+  return value;
+}
+
+function boundedText(value, label, maximum = 4096) {
+  if (
+    typeof value !== "string" ||
+    value.trim() === "" ||
+    value.length > maximum
+  ) {
+    throw new TypeError(`${label} is invalid or unbounded`);
+  }
+  return value.trim();
+}
+
+function capture(owner, method, label) {
+  if (!owner || typeof owner !== "object" || utilTypes.isProxy(owner)) {
+    throw new TypeError(`${label}.${method}() is required`);
+  }
+  const operation = owner[method];
+  if (typeof operation !== "function" || utilTypes.isProxy(operation)) {
+    throw new TypeError(`${label}.${method}() is required`);
+  }
+  return Object.freeze((...args) => Reflect.apply(operation, owner, args));
+}
+
+function corpusFor(skills) {
+  if (
+    !Array.isArray(skills) ||
+    utilTypes.isProxy(skills) ||
+    skills.length < 1 ||
+    skills.length > MAX_SKILLS
+  ) {
+    throw new TypeError("Skill vector corpus is invalid or unbounded");
+  }
+  let bytes = 0;
+  const digests = new Set();
+  const corpus = skills.map((skill, index) => {
+    if (!skill || typeof skill !== "object" || utilTypes.isProxy(skill)) {
+      throw new TypeError(`Skill vector corpus[${index}] is invalid`);
+    }
+    const digest = skill.executionIdentity?.contentDigest;
+    if (!DIGEST.test(digest ?? "") || digests.has(digest)) {
+      throw new TypeError(
+        "Skill vector corpus has a missing or duplicate digest",
+      );
+    }
+    digests.add(digest);
+    const entry = {
+      digest,
+      id: boundedText(skill.id, `skills[${index}].id`, 256),
+      displayName: boundedText(
+        skill.displayName || skill.id,
+        `skills[${index}].displayName`,
+        512,
+      ),
+      description: boundedText(
+        skill.description || "(no description)",
+        `skills[${index}].description`,
+        16_384,
+      ),
+      category: boundedText(
+        skill.category || "uncategorized",
+        `skills[${index}].category`,
+        128,
+      ),
+      tags: Array.isArray(skill.tags)
+        ? skill.tags.map((tag, tagIndex) =>
+            boundedText(tag, `skills[${index}].tags[${tagIndex}]`, 128),
+          )
+        : [],
+    };
+    if (
+      entry.tags.length > 64 ||
+      new Set(entry.tags).size !== entry.tags.length
+    ) {
+      throw new TypeError("Skill vector corpus tags are invalid or unbounded");
+    }
+    bytes += Buffer.byteLength(canonical(entry), "utf8");
+    if (bytes > MAX_TEXT_BYTES) {
+      throw new TypeError("Skill vector corpus is invalid or unbounded");
+    }
+    return Object.freeze({ ...entry, tags: Object.freeze(entry.tags) });
+  });
+  corpus.sort((left, right) => left.digest.localeCompare(right.digest));
+  return Object.freeze(corpus);
+}
+
+export function digestSkillVectorResult(value) {
+  return hash(SKILL_VECTOR_RESULT_SCHEMA, {
+    schema: value.schema,
+    tenantId: value.tenantId,
+    requestDigest: value.requestDigest,
+    corpusDigest: value.corpusDigest,
+    modelId: value.modelId,
+    modelRevision: value.modelRevision,
+    indexDigest: value.indexDigest,
+    scores: value.scores,
+  });
+}
+
+export function createSkillVectorAuthority({
+  tenantId: tenantIdInput,
+  provider,
+  verifier,
+} = {}) {
+  const tenantId = identifier(tenantIdInput, "tenantId");
+  const scoreProvider = capture(provider, "score", "Skill vector provider");
+  const verifyResult = capture(verifier, "verify", "Skill vector verifier");
+  const authority = Object.freeze({
+    tenantId,
+    async score({ query: queryInput, skills } = {}) {
+      const query = boundedText(queryInput, "Skill vector query");
+      const corpus = corpusFor(skills);
+      const corpusDigest = hash(
+        "chainlesschain.skill-vector-corpus/v1",
+        corpus,
+      );
+      const requestCore = {
+        schema: SKILL_VECTOR_REQUEST_SCHEMA,
+        tenantId,
+        query,
+        corpusDigest,
+        corpus,
+      };
+      const request = Object.freeze({
+        ...requestCore,
+        requestDigest: hash(SKILL_VECTOR_REQUEST_SCHEMA, requestCore),
+      });
+      const result = exact(
+        await scoreProvider(request),
+        RESULT_KEYS,
+        "Skill vector result",
+      );
+      if (
+        result.schema !== SKILL_VECTOR_RESULT_SCHEMA ||
+        result.tenantId !== tenantId ||
+        result.requestDigest !== request.requestDigest ||
+        result.corpusDigest !== corpusDigest ||
+        !SAFE_ID.test(result.modelId ?? "") ||
+        !SAFE_ID.test(result.modelRevision ?? "") ||
+        !DIGEST.test(result.indexDigest ?? "") ||
+        !DIGEST.test(result.resultDigest ?? "") ||
+        !Array.isArray(result.scores) ||
+        utilTypes.isProxy(result.scores) ||
+        result.scores.length !== corpus.length
+      ) {
+        throw new Error("Skill vector result is not authoritative");
+      }
+      const expected = new Set(corpus.map(({ digest }) => digest));
+      const scores = new Map();
+      for (const [index, input] of result.scores.entries()) {
+        const entry = exact(input, SCORE_KEYS, `Skill vector scores[${index}]`);
+        if (
+          !expected.has(entry.digest) ||
+          scores.has(entry.digest) ||
+          typeof entry.score !== "number" ||
+          !Number.isFinite(entry.score) ||
+          entry.score < 0 ||
+          entry.score > 1
+        ) {
+          throw new Error("Skill vector scores are invalid or incomplete");
+        }
+        scores.set(entry.digest, entry.score);
+      }
+      if (scores.size !== expected.size) {
+        throw new Error("Skill vector scores are invalid or incomplete");
+      }
+      exact(result.attestation, ATTESTATION_KEYS, "Skill vector attestation");
+      if (
+        result.attestation.schema !== SKILL_VECTOR_ATTESTATION_SCHEMA ||
+        !SAFE_ID.test(result.attestation.algorithm ?? "") ||
+        !SAFE_ID.test(result.attestation.keyId ?? "") ||
+        typeof result.attestation.value !== "string" ||
+        result.attestation.value.length < 16 ||
+        result.attestation.value.length > 4096
+      ) {
+        throw new Error("Skill vector attestation is invalid");
+      }
+      if (result.resultDigest !== digestSkillVectorResult(result)) {
+        throw new Error("Skill vector result integrity is invalid");
+      }
+      const verification = exact(
+        await verifyResult({
+          tenantId,
+          requestDigest: request.requestDigest,
+          resultDigest: result.resultDigest,
+          attestation: result.attestation,
+        }),
+        VERIFICATION_KEYS,
+        "Skill vector verification",
+      );
+      if (
+        verification.authenticated !== true ||
+        verification.durable !== true ||
+        verification.tenantId !== tenantId ||
+        verification.requestDigest !== request.requestDigest ||
+        verification.resultDigest !== result.resultDigest ||
+        !DIGEST.test(verification.receiptDigest ?? "")
+      ) {
+        throw new Error("Skill vector result is not independently verified");
+      }
+      return Object.freeze({
+        scores: Object.freeze(Object.fromEntries(scores)),
+        evidence: Object.freeze({
+          schema: SKILL_VECTOR_AUTHORITY_SCHEMA,
+          status: "verified",
+          tenantId,
+          requestDigest: request.requestDigest,
+          corpusDigest,
+          skillCount: corpus.length,
+          modelId: result.modelId,
+          modelRevision: result.modelRevision,
+          indexDigest: result.indexDigest,
+          resultDigest: result.resultDigest,
+          receiptDigest: verification.receiptDigest,
+        }),
+      });
+    },
+  });
+  AUTHORITIES.add(authority);
+  return authority;
+}
+
+export function captureSkillVectorAuthority(value) {
+  if (!AUTHORITIES.has(value)) {
+    throw new TypeError("a branded Skill vector authority is required");
+  }
+  return value;
+}
+
+export function unavailableSkillVectorEvidence(
+  code = "CC_SKILL_VECTOR_AUTHORITY_UNCONFIGURED",
+) {
+  if (!/^CC_SKILL_VECTOR_[A-Z0-9_]{1,96}$/u.test(code)) {
+    throw new TypeError("Skill vector unavailable code is invalid");
+  }
+  return Object.freeze({
+    schema: SKILL_VECTOR_AUTHORITY_SCHEMA,
+    status: "unavailable",
+    code,
+  });
+}