chainlesschain 0.166.21 → 0.166.22

package/src/lib/evolution/governed-knowledge-sync.js

@@ -2,11 +2,16 @@ import { createHash } from "node:crypto";
 import { types as utilTypes } from "node:util";
 
 import { isGovernedKnowledgeDependencyExecutor } from "./governed-knowledge-dependency-ledger-executor.js";
+import { isGovernedKnowledgeArtifactLifecycle } from "./governed-knowledge-artifact-lifecycle.js";
 
 export const GOVERNED_KNOWLEDGE_SYNC_SCHEMA =
   "chainlesschain.governed-evolution-knowledge-sync/v1";
 export const GOVERNED_KNOWLEDGE_ENVELOPE_SCHEMA =
   "chainlesschain.governed-evolution-knowledge-envelope/v1";
+export const GOVERNED_KNOWLEDGE_ARTIFACT_BINDING_SCHEMA =
+  "chainlesschain.governed-knowledge-artifact-binding/v2";
+export const GOVERNED_KNOWLEDGE_ARTIFACT_BINDING_LEGACY_SCHEMA =
+  "chainlesschain.governed-knowledge-artifact-binding/v1";
 export const GOVERNED_KNOWLEDGE_SCOPE = Object.freeze({
   PERSONAL: "personal",
   PROJECT: "project",
@@ -37,6 +42,20 @@ const ENVELOPE_KEYS = new Set([
   "tenantId",
   "vectorClock",
 ]);
+const ARTIFACT_BINDING_KEYS = new Set([
+  "activate",
+  "authorizationReceiptDigest",
+  "baseline",
+  "evidenceDigest",
+  "humanReviewed",
+  "issuedAt",
+  "operationId",
+  "operation",
+  "schema",
+]);
+const LEGACY_ARTIFACT_BINDING_KEYS = new Set(
+  [...ARTIFACT_BINDING_KEYS].filter((key) => key !== "activate"),
+);
 
 function canonical(value) {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
@@ -206,6 +225,53 @@ export function verifyGovernedKnowledgeRecord(input, { tenantId } = {}) {
   return normalizeRecord(input, { tenantId: id(tenantId, "tenantId") });
 }
 
+export function verifyGovernedKnowledgeArtifactBinding(
+  input,
+  { tenantId, knowledge, authorizationReceiptDigest } = {},
+) {
+  record(input, "knowledge artifact binding");
+  const expectedTenantId = id(tenantId, "tenantId");
+  const normalizedKnowledge = verifyGovernedKnowledgeRecord(knowledge, {
+    tenantId: expectedTenantId,
+  });
+  const keys = Reflect.ownKeys(input);
+  const current = input.schema === GOVERNED_KNOWLEDGE_ARTIFACT_BINDING_SCHEMA;
+  const legacy =
+    input.schema === GOVERNED_KNOWLEDGE_ARTIFACT_BINDING_LEGACY_SCHEMA;
+  const expectedKeys = current
+    ? ARTIFACT_BINDING_KEYS
+    : LEGACY_ARTIFACT_BINDING_KEYS;
+  const baseline =
+    input.baseline === null
+      ? null
+      : verifyGovernedKnowledgeRecord(input.baseline, {
+          tenantId: expectedTenantId,
+        });
+  if (
+    (!current && !legacy) ||
+    keys.length !== expectedKeys.size ||
+    keys.some((key) => typeof key !== "string" || !expectedKeys.has(key)) ||
+    !ID.test(input.operationId ?? "") ||
+    !(
+      current ? ["publish", "merge", "receive"] : ["publish", "merge"]
+    ).includes(input.operation) ||
+    (current && typeof input.activate !== "boolean") ||
+    !Number.isFinite(Date.parse(input.issuedAt)) ||
+    input.authorizationReceiptDigest !== authorizationReceiptDigest ||
+    !DIGEST.test(input.authorizationReceiptDigest ?? "") ||
+    !DIGEST.test(input.evidenceDigest ?? "") ||
+    typeof input.humanReviewed !== "boolean" ||
+    (baseline !== null &&
+      (baseline.knowledgeId !== normalizedKnowledge.knowledgeId ||
+        baseline.scope !== normalizedKnowledge.scope ||
+        baseline.scopeId !== normalizedKnowledge.scopeId)) ||
+    canonical(baseline) !== canonical(input.baseline)
+  ) {
+    throw new Error("knowledge artifact binding is invalid");
+  }
+  return freeze(clone(input));
+}
+
 export function isGovernedKnowledgeExecutionRecord(value) {
   return EXECUTION_RECORDS.has(value);
 }
@@ -250,7 +316,14 @@ export function verifyGovernedKnowledgeEnvelopeIntegrity(
 }
 
 export class GovernedKnowledgeSync {
-  constructor({ tenantId, deviceId, ports, dependencyExecutor = null } = {}) {
+  constructor({
+    tenantId,
+    deviceId,
+    ports,
+    dependencyExecutor = null,
+    artifactLifecycle,
+    clock = () => Date.now(),
+  } = {}) {
     this.tenantId = id(tenantId, "tenantId");
     this.deviceId = id(deviceId, "deviceId");
     this._authorize = capture(ports, "authorize");
@@ -265,6 +338,16 @@ export class GovernedKnowledgeSync {
       ports?.loadPublication === undefined
         ? null
         : capture(ports, "loadPublication");
+    this._loadReception = capture(ports, "loadReception");
+    if (!isGovernedKnowledgeArtifactLifecycle(artifactLifecycle)) {
+      throw new TypeError(
+        "a branded governed Knowledge artifact lifecycle is required",
+      );
+    }
+    this._prepareArtifact = capture(artifactLifecycle, "prepare");
+    this._commitArtifact = capture(artifactLifecycle, "commit");
+    if (typeof clock !== "function") throw new TypeError("clock is required");
+    this._clock = clock;
     if (
       dependencyExecutor !== null &&
       !isGovernedKnowledgeDependencyExecutor(dependencyExecutor)
@@ -279,7 +362,20 @@ export class GovernedKnowledgeSync {
     SYNCHRONIZERS.add(this);
   }
 
-  async publish(input, { operationId = null } = {}) {
+  async publish(input, options = {}) {
+    const result = await this.publishWithArtifactEvidence(input, options);
+    return result.envelope;
+  }
+
+  async publishWithArtifactEvidence(
+    input,
+    {
+      operationId = null,
+      artifactOperation = "publish",
+      artifactEvidenceDigest = null,
+      artifactHumanReviewed = false,
+    } = {},
+  ) {
     const knowledge = normalizeRecord(input, this, { executionRecord: true });
     if (knowledge.scope === "personal")
       throw new Error("personal knowledge cannot enter a shared sync channel");
@@ -301,6 +397,32 @@ export class GovernedKnowledgeSync {
           throw new Error("publish operationId resolved different knowledge");
         }
         verifyGovernedKnowledgeEnvelopeIntegrity(existing.envelope, this);
+        const binding = verifyGovernedKnowledgeArtifactBinding(
+          existing.artifactBinding,
+          {
+            tenantId: this.tenantId,
+            knowledge,
+            authorizationReceiptDigest: existing.authorizationReceiptDigest,
+          },
+        );
+        if (
+          artifactOperation !== binding.operation ||
+          (artifactEvidenceDigest !== null &&
+            artifactEvidenceDigest !== binding.evidenceDigest) ||
+          artifactHumanReviewed !== binding.humanReviewed
+        ) {
+          throw new Error("publish artifact recovery binding differs");
+        }
+        const prepared = await this._prepareArtifact({
+          knowledge,
+          currentKnowledge: binding.baseline,
+          operation: binding.operation,
+          operationId: binding.operationId,
+          authorizationReceiptDigest: binding.authorizationReceiptDigest,
+          evidenceDigest: binding.evidenceDigest,
+          issuedAt: binding.issuedAt,
+          humanReviewed: binding.humanReviewed,
+        });
         const sent = await this._send({ envelope: existing.envelope });
         if (
           sent?.durable !== true ||
@@ -308,10 +430,51 @@ export class GovernedKnowledgeSync {
         ) {
           throw new Error("sync transport did not durably accept the envelope");
         }
-        return freeze(clone(existing.envelope));
+        const artifact = await this._commitArtifact(prepared);
+        return freeze({
+          envelope: clone(existing.envelope),
+          artifact: clone(artifact),
+          recovered: true,
+        });
       }
     }
     const admission = await this._admit("publish", knowledge);
+    const current = await this._load({ knowledgeId: knowledge.knowledgeId });
+    const effectiveOperationId =
+      operationId ??
+      `knowledge-publish:${hash(
+        "chainlesschain.governed-knowledge-publish-operation/v1",
+        { tenantId: this.tenantId, deviceId: this.deviceId, knowledge },
+      ).slice(7)}`;
+    const milliseconds = Number(this._clock());
+    if (!Number.isFinite(milliseconds))
+      throw new TypeError("knowledge sync clock is invalid");
+    const binding = freeze({
+      schema: GOVERNED_KNOWLEDGE_ARTIFACT_BINDING_SCHEMA,
+      activate: true,
+      operationId: effectiveOperationId,
+      operation: artifactOperation,
+      issuedAt: new Date(milliseconds).toISOString(),
+      authorizationReceiptDigest: admission.receiptDigest,
+      evidenceDigest: artifactEvidenceDigest ?? admission.receiptDigest,
+      humanReviewed: artifactHumanReviewed,
+      baseline: current === null ? null : clone(current),
+    });
+    verifyGovernedKnowledgeArtifactBinding(binding, {
+      tenantId: this.tenantId,
+      knowledge,
+      authorizationReceiptDigest: admission.receiptDigest,
+    });
+    const prepared = await this._prepareArtifact({
+      knowledge,
+      currentKnowledge: binding.baseline,
+      operation: binding.operation,
+      operationId: binding.operationId,
+      authorizationReceiptDigest: binding.authorizationReceiptDigest,
+      evidenceDigest: binding.evidenceDigest,
+      issuedAt: binding.issuedAt,
+      humanReviewed: binding.humanReviewed,
+    });
     await this._applyRevocationDependencies(knowledge);
     const plaintext = Buffer.from(canonical(knowledge), "utf8");
     const encrypted = await this._encrypt({ knowledge, plaintext });
@@ -344,11 +507,19 @@ export class GovernedKnowledgeSync {
       envelopeDigest,
       signature: clone(signature),
     });
-    await this._persist(knowledge, envelope, "local", admission, operationId);
+    await this._persist(
+      knowledge,
+      envelope,
+      "local",
+      admission,
+      operationId,
+      binding,
+    );
     const sent = await this._send({ envelope });
     if (sent?.durable !== true || sent.envelopeDigest !== envelopeDigest)
       throw new Error("sync transport did not durably accept the envelope");
-    return envelope;
+    const artifact = await this._commitArtifact(prepared);
+    return freeze({ envelope, artifact: clone(artifact), recovered: false });
   }
 
   async receive(envelope) {
@@ -390,6 +561,60 @@ export class GovernedKnowledgeSync {
     )
       throw new Error("knowledge envelope substituted its governed record");
     const admission = await this._admit("receive", knowledge);
+    const existing = await this._loadReception({
+      envelopeDigest: envelope.envelopeDigest,
+    });
+    if (existing) {
+      const comparable = { ...existing.knowledge };
+      delete comparable.conflictWithDigest;
+      if (
+        !["remote", "conflict"].includes(existing.disposition) ||
+        existing.envelopeDigest !== envelope.envelopeDigest ||
+        canonical(comparable) !== canonical(knowledge)
+      ) {
+        throw new Error("receive envelope resolved different knowledge");
+      }
+      const binding = verifyGovernedKnowledgeArtifactBinding(
+        existing.artifactBinding,
+        {
+          tenantId: this.tenantId,
+          knowledge,
+          authorizationReceiptDigest: existing.authorizationReceiptDigest,
+        },
+      );
+      if (
+        binding.operation !== "receive" ||
+        binding.activate !== (existing.disposition === "remote")
+      ) {
+        throw new Error("receive artifact recovery binding differs");
+      }
+      const prepared = await this._prepareArtifact({
+        knowledge,
+        currentKnowledge: binding.baseline,
+        operation: binding.operation,
+        operationId: binding.operationId,
+        authorizationReceiptDigest: binding.authorizationReceiptDigest,
+        evidenceDigest: binding.evidenceDigest,
+        issuedAt: binding.issuedAt,
+        activate: binding.activate,
+        humanReviewed: binding.humanReviewed,
+      });
+      const artifact = await this._commitArtifact(prepared);
+      return existing.disposition === "conflict"
+        ? freeze({
+            applied: false,
+            reason: "conflict",
+            requiresHumanMerge: true,
+            recovered: true,
+            artifact: clone(artifact),
+          })
+        : freeze({
+            applied: true,
+            action: knowledge.action,
+            recovered: true,
+            artifact: clone(artifact),
+          });
+    }
     const current = await this._load({ knowledgeId: knowledge.knowledgeId });
     if (current) {
       const order = relation(current.vectorClock, knowledge.vectorClock);
@@ -400,22 +625,105 @@ export class GovernedKnowledgeSync {
         return freeze({ applied: false, reason: "replay" });
       }
       if (order === "concurrent") {
+        const binding = this._receiveArtifactBinding({
+          knowledge,
+          current,
+          admission,
+          envelope,
+          activate: false,
+        });
+        const prepared = await this._prepareArtifact({
+          knowledge,
+          currentKnowledge: binding.baseline,
+          operation: binding.operation,
+          operationId: binding.operationId,
+          authorizationReceiptDigest: binding.authorizationReceiptDigest,
+          evidenceDigest: binding.evidenceDigest,
+          issuedAt: binding.issuedAt,
+          activate: binding.activate,
+          humanReviewed: binding.humanReviewed,
+        });
         await this._persist(
           { ...knowledge, conflictWithDigest: current.contentDigest },
           envelope,
           "conflict",
           admission,
+          null,
+          binding,
         );
+        const artifact = await this._commitArtifact(prepared);
         return freeze({
           applied: false,
           reason: "conflict",
           requiresHumanMerge: true,
+          recovered: false,
+          artifact: clone(artifact),
         });
       }
     }
+    const binding = this._receiveArtifactBinding({
+      knowledge,
+      current,
+      admission,
+      envelope,
+      activate: true,
+    });
+    const prepared = await this._prepareArtifact({
+      knowledge,
+      currentKnowledge: binding.baseline,
+      operation: binding.operation,
+      operationId: binding.operationId,
+      authorizationReceiptDigest: binding.authorizationReceiptDigest,
+      evidenceDigest: binding.evidenceDigest,
+      issuedAt: binding.issuedAt,
+      activate: binding.activate,
+      humanReviewed: binding.humanReviewed,
+    });
     await this._applyRevocationDependencies(knowledge);
-    await this._persist(knowledge, envelope, "remote", admission);
-    return freeze({ applied: true, action: knowledge.action });
+    await this._persist(
+      knowledge,
+      envelope,
+      "remote",
+      admission,
+      null,
+      binding,
+    );
+    const artifact = await this._commitArtifact(prepared);
+    return freeze({
+      applied: true,
+      action: knowledge.action,
+      recovered: false,
+      artifact: clone(artifact),
+    });
+  }
+
+  _receiveArtifactBinding({
+    knowledge,
+    current,
+    admission,
+    envelope,
+    activate,
+  }) {
+    const milliseconds = Number(this._clock());
+    if (!Number.isFinite(milliseconds))
+      throw new TypeError("knowledge sync clock is invalid");
+    const binding = freeze({
+      schema: GOVERNED_KNOWLEDGE_ARTIFACT_BINDING_SCHEMA,
+      activate,
+      operationId: `knowledge-receive:${envelope.envelopeDigest.slice(7)}`,
+      operation: "receive",
+      issuedAt: new Date(milliseconds).toISOString(),
+      authorizationReceiptDigest: admission.receiptDigest,
+      evidenceDigest: envelope.envelopeDigest,
+      humanReviewed: false,
+      baseline: current === null ? null : clone(current),
+    });
+    verifyGovernedKnowledgeArtifactBinding(binding, {
+      tenantId: this.tenantId,
+      knowledge,
+      authorizationReceiptDigest: admission.receiptDigest,
+    });
+    return binding;
   }
 
   async _admit(operation, knowledge) {
@@ -439,6 +747,7 @@ export class GovernedKnowledgeSync {
     disposition,
     admission,
     operationId = null,
+    artifactBinding = null,
   ) {
     const result = await this._commit({
       knowledge,
@@ -447,6 +756,7 @@ export class GovernedKnowledgeSync {
       disposition,
       authorizationReceiptDigest: admission.receiptDigest,
       operationId,
+      artifactBinding,
     });
     if (
       result?.authenticated !== true ||

package/src/lib/evolution/skill-writer-inventory-manifest.js

@@ -705,8 +705,8 @@ export const SKILL_WRITER_INVENTORY = Object.freeze({
         file: "desktop-app-vue/src/main/ai-engine/cowork/skills/skill-sync-manager.js",
         symbol: "SkillSyncManager.importSkill",
         evidence: [
-          "await this.candidateStore.create(createRequest)",
-          "validateCandidateReadback(readback, receipt, createRequest)",
+          "const staged = await this.artifactCandidateGate.stageCandidate(",
+          "persistenceReceipt: staged.receipt",
           'action: "candidate-staged"',
           "activeMutation: false",
         ],
@@ -716,9 +716,9 @@ export const SKILL_WRITER_INVENTORY = Object.freeze({
       id: "desktop-plugin-install",
       surface: "desktop",
       triggerClass: "manual",
-      targetAuthority: "legacy-active",
-      mutationType: "indirect-plugin-tree",
-      discoverySymbol: "installPlugin",
+      targetAuthority: "candidate-only",
+      mutationType: "inactive-plugin-tree",
+      discoverySymbol: null,
       entrypoint: {
         file: "desktop-app-vue/src/main/marketplace/plugin-installer.js",
         symbol: "PluginInstaller.installPlugin",
@@ -730,7 +730,8 @@ export const SKILL_WRITER_INVENTORY = Object.freeze({
         evidence: [
           "await this.extractPlugin(downloadPath, pluginDir)",
           'path.join(pluginDir, "SKILL.md")',
-          "registry.hotLoadSkill(definition.name, definition)",
+          "Marketplace SKILL.md files are not active at install time",
+          "governed promotion is required",
         ],
       },
     }),