chainlesschain 0.166.16 → 0.166.18

package/src/lib/evolution/skill-promotion-controller.js

@@ -12,6 +12,13 @@ import {
   verifySkillMutationConsumptionReceipt,
   verifySkillMutationRequest,
 } from "./skill-mutation-authority.js";
+import { captureSkillEvaluatedPromotionProvider } from "./skill-evaluated-promotion.js";
+import { captureStructuredMemoryPromotionReceiptWriter } from "./structured-memory-promotion-receipt-writer.js";
+import {
+  consumeRegistryTransitionCapability,
+  issueRegistryTransitionCapability,
+} from "./skill-registry-transition-capability.js";
+import { captureSkillPromotionReviewProvider } from "./skill-promotion-review.js";
 
 const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/u;
 const EMPTY_ACTIVE_DOMAIN = "chainlesschain.skill-active/empty/v1\0";
@@ -22,7 +29,24 @@ export const EMPTY_SKILL_ACTIVE_DIGEST = `sha256:${crypto
   .update(EMPTY_ACTIVE_DOMAIN, "utf8")
   .digest("hex")}`;
 
-const TRANSITION_CAPABILITIES = new WeakMap();
+const EVALUATED_CONTROL_PLANE_OPTION_KEYS = new Set([
+  "candidateRegistry",
+  "releaseRegistry",
+  "authority",
+  "evaluatedPromotionProvider",
+  "memoryPromotionReceiptWriter",
+  "promotionReviewProvider",
+]);
+const EVALUATED_CONTROL_PLANE_REQUIRED_KEYS = new Set([
+  "candidateRegistry",
+  "releaseRegistry",
+  "authority",
+  "evaluatedPromotionProvider",
+]);
+
+export const SKILL_EVALUATED_PROMOTION_CONTROL_PLANE_SCHEMA =
+  "chainlesschain.skill-evaluated-promotion-control-plane/v1";
+const EVALUATED_PROMOTION_CONTROL_PLANES = new WeakSet();
 
 export class SkillPromotionControllerError extends Error {
   constructor(code, message, details = {}) {
@@ -201,40 +225,7 @@ function assertTransitionSubject(request, expectedDigest) {
   }
 }
 
-function issueRegistryTransitionCapability(registry, payload) {
-  const capability = Object.freeze(Object.create(null));
-  TRANSITION_CAPABILITIES.set(capability, {
-    registry,
-    payload: deepFreeze(payload),
-    status: "issued",
-  });
-  return capability;
-}
-
-/**
- * Registry-only broker. It is exported solely to break the module boundary;
- * callers cannot manufacture a WeakMap-backed capability or replay one.
- */
-export function consumeRegistryTransitionCapability(capability, registry) {
-  const state =
-    capability && typeof capability === "object"
-      ? TRANSITION_CAPABILITIES.get(capability)
-      : null;
-  if (!state || state.registry !== registry) {
-    throw failure(
-      "SKILL_PROMOTION_TRANSITION_CAPABILITY_INVALID",
-      "registry transition capability is forged or bound to another registry",
-    );
-  }
-  if (state.status !== "issued") {
-    throw failure(
-      "SKILL_PROMOTION_TRANSITION_CAPABILITY_REPLAYED",
-      "registry transition capability has already been consumed",
-    );
-  }
-  state.status = "consumed";
-  return state.payload;
-}
+export { consumeRegistryTransitionCapability };
 
 export class SkillPromotionController {
   #tenantId;
@@ -251,7 +242,26 @@ export class SkillPromotionController {
 
   #consumeAuthority;
 
-  constructor({ candidateRegistry, releaseRegistry, authority } = {}) {
+  #evaluatedPromotionProvider;
+
+  #requireEvaluatedPromotion;
+
+  #memoryPromotionReceiptWriter;
+
+  #promotionReviewProvider;
+
+  #requireHumanReview;
+
+  constructor({
+    candidateRegistry,
+    releaseRegistry,
+    authority,
+    evaluatedPromotionProvider = null,
+    requireEvaluatedPromotion = false,
+    memoryPromotionReceiptWriter = null,
+    promotionReviewProvider = null,
+    requireHumanReview = false,
+  } = {}) {
     if (!candidateRegistry || typeof candidateRegistry.read !== "function") {
       throw failure(
         "SKILL_PROMOTION_CANDIDATE_REGISTRY_REQUIRED",
@@ -288,6 +298,30 @@ export class SkillPromotionController {
         "SkillMutationAuthority.consume is required",
       );
     }
+    if (typeof requireEvaluatedPromotion !== "boolean") {
+      throw failure(
+        "SKILL_PROMOTION_INVALID",
+        "requireEvaluatedPromotion must be boolean",
+      );
+    }
+    if (requireEvaluatedPromotion && evaluatedPromotionProvider === null) {
+      throw failure(
+        "SKILL_PROMOTION_EVALUATION_REQUIRED",
+        "evaluated-only promotion requires a captured evidence provider",
+      );
+    }
+    if (typeof requireHumanReview !== "boolean") {
+      throw failure(
+        "SKILL_PROMOTION_INVALID",
+        "requireHumanReview must be boolean",
+      );
+    }
+    if (requireHumanReview && promotionReviewProvider === null) {
+      throw failure(
+        "SKILL_PROMOTION_REVIEW_REQUIRED",
+        "human-reviewed promotion requires a captured review provider",
+      );
+    }
 
     this.#tenantId = candidateRegistry.tenantId;
     this.#registryIdentity = releaseRegistry;
@@ -297,6 +331,22 @@ export class SkillPromotionController {
     this.#applyTransition =
       releaseRegistry.applyTransition.bind(releaseRegistry);
     this.#consumeAuthority = authority.consume.bind(authority);
+    this.#evaluatedPromotionProvider =
+      evaluatedPromotionProvider === null
+        ? null
+        : captureSkillEvaluatedPromotionProvider(evaluatedPromotionProvider);
+    this.#requireEvaluatedPromotion = requireEvaluatedPromotion;
+    this.#memoryPromotionReceiptWriter =
+      memoryPromotionReceiptWriter === null
+        ? null
+        : captureStructuredMemoryPromotionReceiptWriter(
+            memoryPromotionReceiptWriter,
+          );
+    this.#promotionReviewProvider =
+      promotionReviewProvider === null
+        ? null
+        : captureSkillPromotionReviewProvider(promotionReviewProvider);
+    this.#requireHumanReview = requireHumanReview;
 
     Object.freeze(candidateRegistry);
     Object.freeze(releaseRegistry);
@@ -352,7 +402,7 @@ export class SkillPromotionController {
     return verifyDirectConsumptionReceipt(directReceipt, request);
   }
 
-  async promote(input = {}) {
+  async #promote(input = {}) {
     assertDataRecord(
       input,
       new Set(["authorization", "candidateId"]),
@@ -425,6 +475,77 @@ export class SkillPromotionController {
     return this.#applyTransition(transitionCapability);
   }
 
+  async promote(input = {}) {
+    if (this.#requireEvaluatedPromotion) {
+      throw failure(
+        "SKILL_PROMOTION_EVALUATION_REQUIRED",
+        "direct promotion is disabled by the evaluated-only controller policy",
+      );
+    }
+    const result = await this.#promote(input);
+    if (this.#memoryPromotionReceiptWriter === null) return result;
+    const memoryAuthorityReceipt =
+      await this.#memoryPromotionReceiptWriter.retainPromotion(result);
+    return deepFreeze({ ...result, memoryAuthorityReceipt });
+  }
+
+  async promoteEvaluated(input = {}) {
+    assertDataRecord(
+      input,
+      new Set(["authorization", "candidateId", "matrixContext"]),
+      "evaluated promotion input",
+    );
+    if (this.#evaluatedPromotionProvider === null) {
+      throw failure(
+        "SKILL_PROMOTION_EVALUATION_REQUIRED",
+        "evaluated promotion requires a captured evidence provider",
+      );
+    }
+    const candidate = this.#readCandidate(input.candidateId);
+    const state = this.#readState(candidate.skillName);
+    const activeContentDigest = this.#currentContentDigest(state);
+    const matrixBinding = await this.#evaluatedPromotionProvider.verify({
+      matrixContext: input.matrixContext,
+      authorization: input.authorization,
+      candidate,
+      state,
+      activeContentDigest,
+    });
+    let reviewBinding = null;
+    if (this.#requireHumanReview) {
+      const activeRelease =
+        state.activeReleaseDigest === null
+          ? null
+          : this.#readRelease(state.activeReleaseDigest);
+      reviewBinding = await this.#promotionReviewProvider.verify({
+        activeRelease,
+        authorization: input.authorization,
+        candidate,
+        matrixBinding,
+        state,
+      });
+    }
+    const result = await this.#promote({
+      authorization: input.authorization,
+      candidateId: input.candidateId,
+    });
+    if (this.#memoryPromotionReceiptWriter === null) {
+      return deepFreeze({ ...result, matrixBinding, reviewBinding });
+    }
+    const memoryAuthorityReceipt =
+      await this.#memoryPromotionReceiptWriter.retainPromotion(
+        result,
+        matrixBinding,
+        reviewBinding,
+      );
+    return deepFreeze({
+      ...result,
+      matrixBinding,
+      reviewBinding,
+      memoryAuthorityReceipt,
+    });
+  }
+
   async rollback(input = {}) {
     assertDataRecord(
       input,
@@ -503,4 +624,66 @@ export class SkillPromotionController {
   }
 }
 
+/**
+ * Builds the narrow promotion surface intended for production adapters.
+ *
+ * This is a composition primitive, not proof that any production entry point
+ * uses it. The returned facade deliberately withholds both the controller and
+ * direct promote(), while retaining authorized rollback as the recovery path.
+ */
+export function createSkillEvaluatedPromotionControlPlane(options = {}) {
+  assertDataRecord(
+    options,
+    EVALUATED_CONTROL_PLANE_OPTION_KEYS,
+    "evaluated promotion control plane options",
+    { required: EVALUATED_CONTROL_PLANE_REQUIRED_KEYS },
+  );
+  const provider = captureSkillEvaluatedPromotionProvider(
+    options.evaluatedPromotionProvider,
+  );
+  const reviewProvider = captureSkillPromotionReviewProvider(
+    options.promotionReviewProvider,
+  );
+  const controller = new SkillPromotionController({
+    candidateRegistry: options.candidateRegistry,
+    releaseRegistry: options.releaseRegistry,
+    authority: options.authority,
+    evaluatedPromotionProvider: options.evaluatedPromotionProvider,
+    memoryPromotionReceiptWriter: options.memoryPromotionReceiptWriter ?? null,
+    promotionReviewProvider: options.promotionReviewProvider,
+    requireEvaluatedPromotion: true,
+    requireHumanReview: true,
+  });
+  const controlPlane = {
+    schema: SKILL_EVALUATED_PROMOTION_CONTROL_PLANE_SCHEMA,
+    tenantId: options.candidateRegistry.tenantId,
+    providerAuthorityId: provider.authorityId,
+    providerRevision: provider.revision,
+    providerHandlerArtifactDigest: provider.handlerArtifactDigest,
+    reviewAuthorityId: reviewProvider.authorityId,
+    reviewRevision: reviewProvider.revision,
+    reviewHandlerArtifactDigest: reviewProvider.handlerArtifactDigest,
+    promoteEvaluated: Object.freeze((input) =>
+      controller.promoteEvaluated(input),
+    ),
+    rollback: Object.freeze((input) => controller.rollback(input)),
+  };
+  EVALUATED_PROMOTION_CONTROL_PLANES.add(controlPlane);
+  return Object.freeze(controlPlane);
+}
+
+export function captureSkillEvaluatedPromotionControlPlane(value) {
+  if (!value || !EVALUATED_PROMOTION_CONTROL_PLANES.has(value)) {
+    throw failure(
+      "SKILL_PROMOTION_CONTROL_PLANE_REQUIRED",
+      "a branded evaluated promotion control plane is required",
+    );
+  }
+  return Object.freeze({
+    schema: value.schema,
+    tenantId: value.tenantId,
+    promoteEvaluated: value.promoteEvaluated.bind(value),
+  });
+}
+
 Object.freeze(SkillPromotionController.prototype);