@xdxer/dingtalk-agent 0.1.4-beta.0 → 0.1.4-beta.10

package/dist/src/promotion.js

@@ -0,0 +1,786 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, writeFileSync, } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { inspectAgentProject, showDevelopmentWorkspace, } from './development-workspace.js';
+import { digest, stableStringify } from './events.js';
+import { applyMulticaDeployment, planMulticaDeployment, statusMulticaDeployment, } from './multica-deploy.js';
+export const PROMOTION_POLICY_SCHEMA = 'dingtalk-agent/promotion-policy@1';
+export const PROMOTION_PLAN_SCHEMA = 'dingtalk-agent/promotion-plan@1';
+export const PROMOTION_RECEIPT_SCHEMA = 'dingtalk-agent/promotion-receipt@1';
+export const OBSERVATION_SCHEMA = 'dingtalk-agent/observation@1';
+export const EVAL_CANDIDATE_SCHEMA = 'dingtalk-agent/eval-candidate@1';
+const PROMOTION_ROOT = '.dingtalk-agent/development-workspace-evidence/promotions';
+const CANDIDATE_ROOT = '.dingtalk-agent/eval-candidates';
+const HASH = /^[a-f0-9]{64}$/;
+const SAFE_ID = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/;
+const STAGE_RANK = { dev: 0, test: 1, staging: 2, prod: 3 };
+const SURFACES = new Set(['response', 'filesystem', 'workspace', 'artifact']);
+export function planPromotion(start, policyRef, routeId, options = {}) {
+    const info = inspectAgentProject(start, options.cliVersion || '');
+    const { policy, policyPath, policyHash } = loadPolicy(info.root, policyRef);
+    const route = policy.routes.find((item) => item.id === routeId);
+    if (!route)
+        throw new Error(`Promotion route 不存在: ${routeId}`);
+    const source = showDevelopmentWorkspace(info.root, route.fromWorkspace, options.cliVersion || '');
+    const target = showDevelopmentWorkspace(info.root, route.toWorkspace, options.cliVersion || '');
+    const blocking = [];
+    if (source.legacy || source.provider.kind !== 'opencode')
+        blocking.push('source.provider-not-opencode');
+    if (target.legacy || target.provider.kind !== 'multica')
+        blocking.push('target.provider-not-multica');
+    if (target.stage === 'prod')
+        blocking.push('target.prod-requires-separate-live-gate');
+    if (STAGE_RANK[target.stage] < STAGE_RANK[source.stage])
+        blocking.push('target.stage-downgrade');
+    if (source.sourceHash !== target.sourceHash)
+        blocking.push('project.source-hash-mismatch');
+    let evalEvidence = null;
+    try {
+        evalEvidence = loadEvalGate(info.root, source, route);
+    }
+    catch (error) {
+        blocking.push(`eval.${errorCategory(error)}`);
+    }
+    let deployment;
+    try {
+        deployment = planMulticaDeployment(info.root, target.name, {
+            env: options.env, cliVersion: options.cliVersion,
+        });
+        blocking.push(...deployment.blocking.map((item) => `deployment.${item}`));
+    }
+    catch (error) {
+        blocking.push(`deployment.${errorCategory(error)}`);
+        deployment = emptyDeploymentPlan(target);
+    }
+    const sourceSkills = deployment.expected.skills.map((item) => ({ name: item.name, hash: item.hash }));
+    const sourceBinding = {
+        workspace: source.name,
+        stage: source.stage,
+        sourceHash: source.sourceHash,
+        desiredHash: source.desiredHash,
+        observedHash: source.observedHash,
+        definitionHash: deployment.expected.definitionHash || emptyHash(),
+        skills: sourceSkills,
+    };
+    const targetBinding = {
+        workspace: target.name,
+        stage: target.stage,
+        desiredHash: target.desiredHash,
+        deploymentHash: deployment.deploymentHash || emptyHash(),
+        deploymentPlanId: deployment.planId,
+    };
+    const resolvedEval = evalEvidence || emptyEvalEvidence(route);
+    const uniqueBlocking = [...new Set(blocking)].sort();
+    const planId = `promotion_plan_${digest(stableStringify({
+        routeId, policyHash, source: sourceBinding, eval: resolvedEval,
+        target: targetBinding, deploymentPlanId: deployment.planId, blocking: uniqueBlocking,
+    })).slice(0, 24)}`;
+    return {
+        $schema: PROMOTION_PLAN_SCHEMA,
+        planId,
+        routeId,
+        policyPath,
+        policyHash,
+        source: sourceBinding,
+        eval: resolvedEval,
+        target: targetBinding,
+        deployment,
+        blocking: uniqueBlocking,
+        requiresPlanId: true,
+        requiresExplicitYes: true,
+        remoteRead: false,
+        remoteWrite: false,
+        localWrite: false,
+        triggerWrite: false,
+        sideEffect: false,
+        dingtalkSideEffect: false,
+    };
+}
+export function applyPromotion(start, policyRef, routeId, options = {}) {
+    if (!options.yes || !options.planId) {
+        throw new Error('promote 会调用 Multica deploy；必须显式传当前 --plan-id 和 --yes');
+    }
+    const info = inspectAgentProject(start, options.cliVersion || '');
+    const plan = planPromotion(info.root, policyRef, routeId, {
+        env: options.env, cliVersion: options.cliVersion,
+    });
+    if (plan.planId !== options.planId) {
+        throw new Error(`promotion plan 已失效；期望当前 planId ${plan.planId}`);
+    }
+    if (plan.blocking.length)
+        throw new Error(`promotion 前置条件不完整: ${plan.blocking.join(', ')}`);
+    const deployment = applyMulticaDeployment(info.root, plan.target.workspace, {
+        ...options,
+        planId: plan.deployment.planId,
+        yes: true,
+    });
+    const deploymentReceiptPath = safeProjectPath(info.root, deployment.evidencePath, true);
+    const deploymentReceiptHash = sha256(readFileSync(deploymentReceiptPath));
+    const promoted = deployment.status === 'ready' && deployment.passed && deployment.providerReady &&
+        deployment.deploymentHash === plan.target.deploymentHash && Boolean(deployment.observedHash);
+    const status = promoted ? 'promoted'
+        : ['verifying', 'reconciling'].includes(deployment.status) ? 'verifying' : 'failed';
+    const target = {
+        ...plan.target,
+        deploymentReceiptId: deployment.receiptId,
+        deploymentOperationId: deployment.operationId,
+        deploymentReceiptPath: deployment.evidencePath,
+        deploymentReceiptHash,
+        observedHash: deployment.observedHash,
+    };
+    const linkHash = promotionLinkHash(plan.source, plan.eval, target);
+    const promotionId = `promotion_${digest(stableStringify({
+        routeId, planId: plan.planId, deploymentReceiptId: deployment.receiptId, linkHash,
+    })).slice(0, 24)}`;
+    const receiptId = `promotion_receipt_${digest(stableStringify({ promotionId, status, linkHash })).slice(0, 24)}`;
+    const receipt = {
+        $schema: PROMOTION_RECEIPT_SCHEMA,
+        promotionId,
+        receiptId,
+        planId: plan.planId,
+        routeId,
+        policyHash: plan.policyHash,
+        status,
+        passed: promoted,
+        idempotent: deployment.idempotent,
+        source: plan.source,
+        eval: plan.eval,
+        target,
+        linkHash,
+        failures: promoted ? [] : [...deployment.failures],
+        evidencePath: promotionReceiptPath(receiptId),
+        remoteRead: deployment.remoteRead,
+        remoteWrite: deployment.remoteWrite,
+        localWrite: true,
+        triggerWrite: false,
+        sideEffect: deployment.sideEffect,
+        dingtalkSideEffect: false,
+    };
+    persistPromotion(info.root, receipt);
+    return receipt;
+}
+export function statusPromotion(start, promotionId = '') {
+    const info = inspectAgentProject(start);
+    const loaded = loadPromotion(info.root, promotionId);
+    if (!loaded)
+        return {
+            $schema: 'dingtalk-agent/promotion-status@1', available: false,
+            promotionId: '', status: 'missing', passed: false, integrity: true, receipt: null,
+            remoteRead: false, remoteWrite: false, localWrite: false, triggerWrite: false,
+            sideEffect: false, dingtalkSideEffect: false,
+        };
+    verifyPromotionDependencies(info.root, loaded.receipt, loaded.receiptHash);
+    return {
+        $schema: 'dingtalk-agent/promotion-status@1', available: true,
+        promotionId: loaded.receipt.promotionId,
+        status: loaded.receipt.status,
+        passed: loaded.receipt.passed,
+        integrity: true,
+        receipt: loaded.receipt,
+        remoteRead: false, remoteWrite: false, localWrite: false, triggerWrite: false,
+        sideEffect: false, dingtalkSideEffect: false,
+    };
+}
+export function listPromotions(start) {
+    const info = inspectAgentProject(start);
+    const directory = safeProjectPath(info.root, join(PROMOTION_ROOT, 'bindings'), false);
+    const promotions = [];
+    if (existsSync(directory)) {
+        for (const entry of readdirSync(directory, { withFileTypes: true })
+            .filter((item) => item.isFile() && item.name.endsWith('.json'))
+            .sort((a, b) => a.name.localeCompare(b.name))) {
+            const promotionId = entry.name.slice(0, -5);
+            const status = statusPromotion(info.root, promotionId);
+            if (!status.receipt)
+                continue;
+            promotions.push({
+                promotionId, receiptId: status.receipt.receiptId, routeId: status.receipt.routeId,
+                status: status.receipt.status, passed: status.receipt.passed,
+                sourceHash: status.receipt.source.sourceHash,
+                evalEvidenceHash: status.receipt.eval.evidenceHash,
+                deploymentHash: status.receipt.target.deploymentHash,
+                observedHash: status.receipt.target.observedHash,
+            });
+        }
+    }
+    return {
+        $schema: 'dingtalk-agent/promotion-list@1', promotions,
+        remoteRead: false, remoteWrite: false, localWrite: false, triggerWrite: false,
+        sideEffect: false, dingtalkSideEffect: false,
+    };
+}
+export function planObservation(start, promotionId, inputRef) {
+    const info = inspectAgentProject(start);
+    const loaded = loadPromotion(info.root, promotionId);
+    if (!loaded)
+        throw new Error(`Promotion 不存在: ${promotionId}`);
+    verifyPromotionDependencies(info.root, loaded.receipt, loaded.receiptHash);
+    if (!loaded.receipt.passed || loaded.receipt.status !== 'promoted') {
+        throw new Error('只有已 promoted 且完整性通过的 Receipt 可以生成 Eval candidate');
+    }
+    const observation = loadObservation(info.root, inputRef);
+    if (observation.observedHash !== loaded.receipt.target.observedHash) {
+        throw new Error('Observation observedHash 与 Promotion 远端 observedHash 不一致');
+    }
+    const observationHash = digest(stableStringify(observation));
+    const candidateId = `eval_candidate_${digest(stableStringify({
+        promotionId, receiptHash: loaded.receiptHash, observationHash,
+    })).slice(0, 24)}`;
+    return {
+        $schema: 'dingtalk-agent/eval-candidate-plan@1',
+        candidateId,
+        promotionId,
+        observedHash: observation.observedHash,
+        observationHash,
+        candidatePath: candidatePath(candidateId),
+        writeBudget: { local: 1 },
+        reviewRequired: true,
+        eligibleForSuite: false,
+        remoteRead: false, remoteWrite: false, localWrite: false, triggerWrite: false,
+        sideEffect: false, dingtalkSideEffect: false,
+    };
+}
+export function applyObservation(start, promotionId, inputRef, options = {}) {
+    if (!options.yes)
+        throw new Error('observe 会写入本地 Eval candidate；必须显式传 --yes');
+    const info = inspectAgentProject(start);
+    const plan = planObservation(info.root, promotionId, inputRef);
+    const loaded = loadPromotion(info.root, promotionId);
+    if (!loaded)
+        throw new Error(`Promotion 不存在: ${promotionId}`);
+    const observation = loadObservation(info.root, inputRef);
+    const candidateBase = {
+        $schema: EVAL_CANDIDATE_SCHEMA,
+        candidateId: plan.candidateId,
+        status: 'proposed',
+        eligibleForSuite: false,
+        reviewRequired: true,
+        published: false,
+        promotion: {
+            promotionId,
+            receiptId: loaded.receipt.receiptId,
+            receiptHash: loaded.receiptHash,
+            linkHash: loaded.receipt.linkHash,
+        },
+        source: loaded.receipt.source,
+        eval: {
+            runId: loaded.receipt.eval.runId,
+            evidenceHash: loaded.receipt.eval.evidenceHash,
+            suiteId: loaded.receipt.eval.suiteId,
+        },
+        target: {
+            workspace: loaded.receipt.target.workspace,
+            deploymentReceiptId: loaded.receipt.target.deploymentReceiptId,
+            deploymentHash: loaded.receipt.target.deploymentHash,
+            observedHash: loaded.receipt.target.observedHash,
+        },
+        observation,
+        observationHash: plan.observationHash,
+        evidencePath: plan.candidatePath,
+        remoteRead: false,
+        remoteWrite: false,
+        localWrite: true,
+        triggerWrite: false,
+        sideEffect: 'local-eval-candidate',
+        dingtalkSideEffect: false,
+    };
+    const candidateHash = digest(stableStringify(candidateBase));
+    const candidate = { ...candidateBase, candidateHash };
+    const path = safeProjectPath(info.root, plan.candidatePath, false);
+    if (existsSync(path)) {
+        const previous = JSON.parse(readFileSync(path, 'utf8'));
+        if (stableStringify(previous) !== stableStringify(candidate)) {
+            throw new Error('Eval candidate ID 已存在但内容不一致');
+        }
+        return {
+            $schema: 'dingtalk-agent/eval-candidate-result@1', applied: false, idempotent: true,
+            candidate, remoteRead: false, remoteWrite: false, localWrite: false,
+            triggerWrite: false, sideEffect: false, dingtalkSideEffect: false,
+        };
+    }
+    atomicJson(path, candidate);
+    const readback = JSON.parse(readFileSync(path, 'utf8'));
+    if (stableStringify(readback) !== stableStringify(candidate)) {
+        throw new Error('Eval candidate 写后回读不一致');
+    }
+    return {
+        $schema: 'dingtalk-agent/eval-candidate-result@1', applied: true, idempotent: false,
+        candidate, remoteRead: false, remoteWrite: false, localWrite: true,
+        triggerWrite: false, sideEffect: 'local-eval-candidate', dingtalkSideEffect: false,
+    };
+}
+function loadEvalGate(root, source, route) {
+    if (!source.state || source.state.status !== 'ready')
+        throw new Error('source-not-ready');
+    const binding = source.state.binding;
+    for (const key of [
+        'managedPath', 'sourceHash', 'evalRunId', 'evalEvidencePath', 'evalPlanHash',
+        'evalSuiteHash', 'evalReportHash', 'evalSuiteId', 'evalModel', 'evalSourceHash',
+        'evalDesiredHash', 'evalObservedHash',
+    ])
+        if (!binding[key])
+            throw new Error(`binding-${key}-missing`);
+    if (binding.sourceHash !== source.sourceHash || binding.evalSourceHash !== source.sourceHash ||
+        binding.evalDesiredHash !== source.desiredHash || source.state.desiredHash !== source.desiredHash) {
+        throw new Error('source-hash-drift');
+    }
+    const managed = safeProjectPath(root, binding.managedPath, true);
+    const actualObservedHash = hashTree(managed);
+    if (actualObservedHash !== source.observedHash || actualObservedHash !== binding.evalObservedHash ||
+        source.state.observedHash !== actualObservedHash)
+        throw new Error('observed-hash-drift');
+    const policySuitePath = safeProjectPath(root, route.suite, true);
+    const policySuite = readJson(policySuitePath, 'Promotion policy suite');
+    const policySuiteHash = digest(stableStringify(policySuite));
+    if (policySuiteHash !== binding.evalSuiteHash)
+        throw new Error('designated-suite-drift');
+    const evidenceRoot = safeProjectPath(root, binding.evalEvidencePath, true);
+    if (!lstatSync(evidenceRoot).isDirectory() || lstatSync(evidenceRoot).isSymbolicLink()) {
+        throw new Error('evidence-root-invalid');
+    }
+    const planPath = safeProjectPath(root, join(binding.evalEvidencePath, 'plan.json'), true);
+    const suitePath = safeProjectPath(root, join(binding.evalEvidencePath, 'suite.json'), true);
+    const reportPath = safeProjectPath(root, join(binding.evalEvidencePath, 'report.json'), true);
+    if (sha256(readFileSync(planPath)) !== binding.evalPlanHash ||
+        sha256(readFileSync(reportPath)) !== binding.evalReportHash)
+        throw new Error('evidence-byte-drift');
+    const plan = readJson(planPath, 'OpenCode Eval plan');
+    const suite = readJson(suitePath, 'OpenCode Eval suite');
+    const report = readJson(reportPath, 'OpenCode Eval report');
+    if (digest(stableStringify(suite)) !== binding.evalSuiteHash ||
+        stableStringify(suite) !== stableStringify(policySuite))
+        throw new Error('suite-evidence-drift');
+    if (plan.$schema !== 'dingtalk-agent/opencode-eval-plan@1' ||
+        report.$schema !== 'dingtalk-agent/opencode-eval-report@1' ||
+        report.runId !== binding.evalRunId || report.evidencePath !== binding.evalEvidencePath ||
+        plan.suite !== suite.id || suite.id !== binding.evalSuiteId ||
+        report.engine?.model !== source.provider.model || report.engine?.model !== binding.evalModel) {
+        throw new Error('evidence-binding-mismatch');
+    }
+    const runs = Number(plan.runsPerConfiguration);
+    const configurations = stringList(plan.configurations, 'Eval plan configurations');
+    const planCases = Array.isArray(plan.cases) ? plan.cases : [];
+    const planCaseIds = planCases.map((item) => String(item?.id || ''));
+    if (!Number.isInteger(runs) || runs < route.minimumRuns || runs > 10 ||
+        configurations.length !== 2 || new Set(configurations).size !== configurations.length) {
+        throw new Error('runs-or-configurations');
+    }
+    if (!route.requiredCases.every((id) => planCaseIds.includes(id)))
+        throw new Error('required-case-missing');
+    if (report.passed !== true || report.summary?.loadGate !== true ||
+        report.summary?.hardGate !== true || report.summary?.falseCompletionGate !== true ||
+        report.summary?.behaviorScoresValid !== true ||
+        (route.requireBehaviorGate && report.summary?.behaviorGate !== true)) {
+        throw new Error('hard-gate-failed');
+    }
+    for (const configuration of configurations) {
+        const gate = report.summary?.configurationLoadGates?.[configuration];
+        if (!gate?.passed || gate.passedRuns !== runs || gate.totalRuns !== runs) {
+            throw new Error('configuration-load-gate-failed');
+        }
+    }
+    const results = Array.isArray(report.results) ? report.results : [];
+    const expectedResults = planCaseIds.length * configurations.length * runs;
+    if (results.length !== expectedResults || results.some((item) => !item.hardGatePassed || !item.safetyPassed || item.falseCompletion)) {
+        throw new Error('result-hard-gate-failed');
+    }
+    for (const caseId of route.requiredCases) {
+        for (const configuration of configurations) {
+            const selected = results.filter((item) => item.id === caseId && item.configuration === configuration);
+            if (selected.length !== runs)
+                throw new Error('required-case-result-count');
+            for (const surface of route.requiredSurfaces) {
+                if (!selected.every((item) => item.surfaceResults?.[surface]?.declared === true &&
+                    item.surfaceResults?.[surface]?.passed === true))
+                    throw new Error(`surface-${surface}-failed`);
+            }
+        }
+    }
+    const evidenceHash = digest(stableStringify({
+        runId: binding.evalRunId,
+        evidencePath: binding.evalEvidencePath,
+        planHash: binding.evalPlanHash,
+        suiteHash: binding.evalSuiteHash,
+        reportHash: binding.evalReportHash,
+        sourceHash: binding.evalSourceHash,
+        desiredHash: binding.evalDesiredHash,
+        observedHash: binding.evalObservedHash,
+    }));
+    return {
+        runId: binding.evalRunId,
+        evidencePath: binding.evalEvidencePath,
+        evidenceHash,
+        planHash: binding.evalPlanHash,
+        suiteHash: binding.evalSuiteHash,
+        reportHash: binding.evalReportHash,
+        suiteId: binding.evalSuiteId,
+        model: binding.evalModel,
+        runs,
+        configurations,
+        caseIds: [...route.requiredCases],
+        requiredSurfaces: [...route.requiredSurfaces],
+        loadGate: true,
+        hardGate: true,
+        falseCompletionGate: true,
+        behaviorGate: report.summary.behaviorGate === true,
+    };
+}
+function loadPolicy(root, ref) {
+    const path = safeProjectPath(root, ref, true);
+    if (lstatSync(path).isSymbolicLink() || !lstatSync(path).isFile()) {
+        throw new Error('Promotion policy 必须是 Project 内真实文件');
+    }
+    const input = readJson(path, 'Promotion policy');
+    exactKeys(input, ['$schema', 'routes'], 'Promotion policy');
+    if (input.$schema !== PROMOTION_POLICY_SCHEMA || !Array.isArray(input.routes) ||
+        input.routes.length < 1 || input.routes.length > 32)
+        throw new Error('Promotion policy schema/routes 非法');
+    const ids = new Set();
+    const routes = input.routes.map((value, index) => {
+        const item = objectValue(value, `Promotion route ${index}`);
+        exactKeys(item, [
+            'id', 'fromWorkspace', 'toWorkspace', 'suite', 'minimumRuns',
+            'requiredCases', 'requiredSurfaces', 'requireBehaviorGate',
+        ], `Promotion route ${index}`);
+        const id = safeId(item.id, 'Promotion route id');
+        if (ids.has(id))
+            throw new Error(`Promotion route 重复: ${id}`);
+        ids.add(id);
+        const requiredCases = uniqueSafeIds(item.requiredCases, 'Promotion requiredCases', 30);
+        const requiredSurfaces = stringList(item.requiredSurfaces, 'Promotion requiredSurfaces');
+        if (!requiredSurfaces.length || requiredSurfaces.some((surface) => !SURFACES.has(surface)) ||
+            new Set(requiredSurfaces).size !== requiredSurfaces.length)
+            throw new Error('Promotion requiredSurfaces 非法');
+        if (!Number.isInteger(item.minimumRuns) || item.minimumRuns < 1 || item.minimumRuns > 10 ||
+            typeof item.requireBehaviorGate !== 'boolean')
+            throw new Error('Promotion route gate 配置非法');
+        const suite = stringField(item.suite, 'Promotion suite');
+        safeProjectPath(root, suite, true);
+        return {
+            id,
+            fromWorkspace: safeId(item.fromWorkspace, 'Promotion fromWorkspace'),
+            toWorkspace: safeId(item.toWorkspace, 'Promotion toWorkspace'),
+            suite,
+            minimumRuns: item.minimumRuns,
+            requiredCases,
+            requiredSurfaces: requiredSurfaces,
+            requireBehaviorGate: item.requireBehaviorGate,
+        };
+    });
+    const policy = { $schema: PROMOTION_POLICY_SCHEMA, routes };
+    return {
+        policy,
+        policyPath: relative(realpathSync(root), path),
+        policyHash: digest(stableStringify(policy)),
+    };
+}
+function loadObservation(root, ref) {
+    const path = safeProjectPath(root, ref, true);
+    if (lstatSync(path).isSymbolicLink() || !lstatSync(path).isFile()) {
+        throw new Error('Observation input 必须是 Project 内真实文件');
+    }
+    const input = readJson(path, 'Observation input');
+    exactKeys(input, [
+        '$schema', 'observedAt', 'observedHash', 'category', 'risk', 'capability',
+        'outcome', 'summary', 'expected', 'actual', 'sourceRefs', 'redacted',
+    ], 'Observation input');
+    if (input.$schema !== OBSERVATION_SCHEMA || input.redacted !== true ||
+        !['behavior', 'safety', 'reliability', 'quality'].includes(String(input.category)) ||
+        !['low', 'medium', 'high', 'critical'].includes(String(input.risk)) ||
+        !['pass', 'fail', 'mixed', 'unknown'].includes(String(input.outcome))) {
+        throw new Error('Observation schema/category/risk/outcome/redacted 非法');
+    }
+    const observedAt = stringField(input.observedAt, 'Observation observedAt');
+    if (Number.isNaN(Date.parse(observedAt)) || new Date(observedAt).toISOString() !== observedAt) {
+        throw new Error('Observation observedAt 必须是规范 ISO 时间');
+    }
+    const observedHash = hashField(input.observedHash, 'Observation observedHash');
+    const capability = boundedString(input.capability, 'Observation capability', 100);
+    const summary = boundedString(input.summary, 'Observation summary', 500);
+    const expected = boundedString(input.expected, 'Observation expected', 1000);
+    const actual = boundedString(input.actual, 'Observation actual', 1000);
+    const sourceRefs = stringList(input.sourceRefs, 'Observation sourceRefs');
+    if (sourceRefs.length > 10 || sourceRefs.some((item) => item.length > 200)) {
+        throw new Error('Observation sourceRefs 超出预算');
+    }
+    assertRedactedObservation([capability, summary, expected, actual, ...sourceRefs]);
+    return {
+        $schema: OBSERVATION_SCHEMA,
+        observedAt,
+        observedHash,
+        category: input.category,
+        risk: input.risk,
+        capability,
+        outcome: input.outcome,
+        summary,
+        expected,
+        actual,
+        sourceRefs,
+        redacted: true,
+    };
+}
+function persistPromotion(root, receipt) {
+    const receiptPath = safeProjectPath(root, receipt.evidencePath, false);
+    atomicJson(receiptPath, receipt);
+    const receiptHash = sha256(readFileSync(receiptPath));
+    const pointer = {
+        $schema: 'dingtalk-agent/promotion-pointer@1',
+        promotionId: receipt.promotionId,
+        receiptId: receipt.receiptId,
+        receiptPath: receipt.evidencePath,
+        receiptHash,
+    };
+    atomicJson(safeProjectPath(root, promotionBindingPath(receipt.promotionId), false), pointer);
+    atomicJson(safeProjectPath(root, join(PROMOTION_ROOT, 'latest.json'), false), pointer);
+}
+function loadPromotion(root, promotionId = '') {
+    const pointerPath = safeProjectPath(root, promotionId
+        ? promotionBindingPath(safeResourceId(promotionId, 'promotionId'))
+        : join(PROMOTION_ROOT, 'latest.json'), false);
+    if (!existsSync(pointerPath))
+        return null;
+    const pointer = readJson(pointerPath, 'Promotion pointer');
+    exactKeys(pointer, ['$schema', 'promotionId', 'receiptId', 'receiptPath', 'receiptHash'], 'Promotion pointer');
+    if (pointer.$schema !== 'dingtalk-agent/promotion-pointer@1')
+        throw new Error('Promotion pointer schema 非法');
+    const expectedPromotionId = safeResourceId(pointer.promotionId, 'pointer promotionId');
+    if (promotionId && expectedPromotionId !== promotionId)
+        throw new Error('Promotion pointer ID 不一致');
+    const receiptPath = safeProjectPath(root, stringField(pointer.receiptPath, 'pointer receiptPath'), true);
+    const receiptHash = sha256(readFileSync(receiptPath));
+    if (receiptHash !== hashField(pointer.receiptHash, 'pointer receiptHash')) {
+        throw new Error('Promotion Receipt hash 不一致');
+    }
+    const receipt = readJson(receiptPath, 'Promotion Receipt');
+    if (receipt.$schema !== PROMOTION_RECEIPT_SCHEMA || receipt.promotionId !== expectedPromotionId ||
+        receipt.receiptId !== pointer.receiptId || receipt.evidencePath !== pointer.receiptPath) {
+        throw new Error('Promotion Receipt 绑定不一致');
+    }
+    return { receipt, receiptHash };
+}
+function verifyPromotionDependencies(root, receipt, receiptHash) {
+    if (receipt.linkHash !== promotionLinkHash(receipt.source, receipt.eval, receipt.target)) {
+        throw new Error('Promotion source/eval/target link hash 不一致');
+    }
+    const evalPlan = safeProjectPath(root, join(receipt.eval.evidencePath, 'plan.json'), true);
+    const evalSuite = safeProjectPath(root, join(receipt.eval.evidencePath, 'suite.json'), true);
+    const evalReport = safeProjectPath(root, join(receipt.eval.evidencePath, 'report.json'), true);
+    if (sha256(readFileSync(evalPlan)) !== receipt.eval.planHash ||
+        digest(stableStringify(readJson(evalSuite, 'Promotion Eval suite'))) !== receipt.eval.suiteHash ||
+        sha256(readFileSync(evalReport)) !== receipt.eval.reportHash) {
+        throw new Error('Promotion Eval plan/suite/report 发生漂移');
+    }
+    const deploymentStatus = statusMulticaDeployment(root, receipt.target.workspace, {
+        operationId: receipt.target.deploymentOperationId,
+    });
+    if (!deploymentStatus.receipt || deploymentStatus.receipt.receiptId !== receipt.target.deploymentReceiptId ||
+        deploymentStatus.receipt.evidencePath !== receipt.target.deploymentReceiptPath ||
+        sha256(readFileSync(safeProjectPath(root, receipt.target.deploymentReceiptPath, true))) !==
+            receipt.target.deploymentReceiptHash ||
+        deploymentStatus.receipt.deploymentHash !== receipt.target.deploymentHash ||
+        deploymentStatus.receipt.observedHash !== receipt.target.observedHash) {
+        throw new Error('Promotion 绑定的 Multica deployment Receipt 不一致');
+    }
+    if (!HASH.test(receiptHash))
+        throw new Error('Promotion Receipt hash 非法');
+}
+function promotionLinkHash(source, evalEvidence, target) {
+    return digest(stableStringify({
+        source: {
+            workspace: source.workspace, stage: source.stage, sourceHash: source.sourceHash,
+            desiredHash: source.desiredHash, observedHash: source.observedHash,
+            definitionHash: source.definitionHash, skills: source.skills,
+        },
+        eval: {
+            runId: evalEvidence.runId, evidenceHash: evalEvidence.evidenceHash,
+            suiteId: evalEvidence.suiteId, suiteHash: evalEvidence.suiteHash,
+            reportHash: evalEvidence.reportHash,
+        },
+        target: {
+            workspace: target.workspace, stage: target.stage,
+            deploymentHash: target.deploymentHash,
+            deploymentReceiptId: 'deploymentReceiptId' in target ? target.deploymentReceiptId : '',
+            deploymentReceiptHash: 'deploymentReceiptHash' in target ? target.deploymentReceiptHash : '',
+            observedHash: 'observedHash' in target ? target.observedHash : '',
+        },
+    }));
+}
+function emptyDeploymentPlan(target) {
+    return {
+        $schema: 'dingtalk-agent/multica-deployment-plan@1',
+        planId: 'multica_deploy_plan_unavailable', action: 'apply', workspace: target.name,
+        provider: 'multica', profile: '', inspectionId: '', desiredHash: target.desiredHash,
+        deploymentHash: emptyHash(), expected: {
+            workspaceId: '', runtimeId: '', agentId: '', agentName: '', skills: [],
+            definitionHash: emptyHash(), instructionsHash: emptyHash(),
+        }, operations: [], writeBudget: { forward: 0, rollback: 0 }, blocking: ['unavailable'],
+        requiresPlanId: true, requiresExplicitYes: true, remoteRead: false, remoteWrite: false,
+        triggerWrite: false, sideEffect: false, dingtalkSideEffect: false,
+    };
+}
+function emptyEvalEvidence(route) {
+    return {
+        runId: '', evidencePath: '', evidenceHash: emptyHash(), planHash: emptyHash(),
+        suiteHash: emptyHash(), reportHash: emptyHash(), suiteId: '', model: '', runs: 0,
+        configurations: [], caseIds: [...route.requiredCases],
+        requiredSurfaces: [...route.requiredSurfaces], loadGate: false, hardGate: false,
+        falseCompletionGate: false, behaviorGate: false,
+    };
+}
+function hashTree(root) {
+    if (!lstatSync(root).isDirectory() || lstatSync(root).isSymbolicLink()) {
+        throw new Error('Managed Workspace 必须是普通目录');
+    }
+    const base = realpathSync(root);
+    const entries = [];
+    const visit = (directory, prefix = '') => {
+        for (const entry of readdirSync(directory, { withFileTypes: true })
+            .sort((a, b) => a.name.localeCompare(b.name))) {
+            const path = join(directory, entry.name);
+            const ref = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isSymbolicLink())
+                throw new Error(`Managed Workspace 不允许符号链接: ${ref}`);
+            if (entry.isDirectory())
+                visit(path, ref);
+            else if (entry.isFile())
+                entries.push({ path: ref, hash: sha256(readFileSync(path)) });
+            else
+                throw new Error(`Managed Workspace 包含特殊文件: ${ref}`);
+        }
+    };
+    visit(base);
+    return digest(stableStringify(entries));
+}
+function assertRedactedObservation(values) {
+    const text = values.join('\n');
+    const forbidden = [
+        /(?:client[_-]?secret|access[_-]?token|refresh[_-]?token|password|credentials?|authorization|bearer)/iu,
+        /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/iu,
+        /(?:https?:\/\/|dingtalk:\/\/)/iu,
+        /(?:^|\D)(?:\+?86[- ]?)?1[3-9]\d{9}(?:\D|$)/u,
+        /\b[A-Za-z0-9_-]{40,}\b/u,
+    ];
+    if (forbidden.some((pattern) => pattern.test(text))) {
+        throw new Error('Observation 包含凭据、PII、URL 或未脱敏长标识');
+    }
+}
+function promotionReceiptPath(receiptId) {
+    return join(PROMOTION_ROOT, 'receipts', `${safeResourceId(receiptId, 'receiptId')}.json`);
+}
+function promotionBindingPath(promotionId) {
+    return join(PROMOTION_ROOT, 'bindings', `${safeResourceId(promotionId, 'promotionId')}.json`);
+}
+function candidatePath(candidateId) {
+    return join(CANDIDATE_ROOT, `${safeResourceId(candidateId, 'candidateId')}.json`);
+}
+function safeProjectPath(root, ref, mustExist) {
+    const rootReal = realpathSync(resolve(root));
+    const candidate = resolve(rootReal, ref);
+    const rel = relative(rootReal, candidate);
+    if (rel === '..' || rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`)) {
+        throw new Error(`Promotion 路径必须位于 Project 内: ${ref}`);
+    }
+    if (mustExist && !existsSync(candidate))
+        throw new Error(`Promotion 路径不存在: ${ref}`);
+    if (existsSync(candidate)) {
+        if (lstatSync(candidate).isSymbolicLink())
+            throw new Error(`Promotion 路径不能是符号链接: ${ref}`);
+        if (realpathSync(candidate) !== candidate && !isInside(rootReal, realpathSync(candidate))) {
+            throw new Error(`Promotion 真实路径越界: ${ref}`);
+        }
+    }
+    let ancestor = dirname(candidate);
+    while (!existsSync(ancestor)) {
+        const parent = dirname(ancestor);
+        if (parent === ancestor)
+            break;
+        ancestor = parent;
+    }
+    if (!existsSync(ancestor) || !isInside(rootReal, realpathSync(ancestor))) {
+        throw new Error(`Promotion 父目录越界: ${ref}`);
+    }
+    return candidate;
+}
+function atomicJson(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = `${path}.tmp-${process.pid}-${randomUUID().slice(0, 8)}`;
+    writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx' });
+    renameSync(temp, path);
+}
+function readJson(path, label) {
+    try {
+        const value = JSON.parse(readFileSync(path, 'utf8'));
+        return objectValue(value, label);
+    }
+    catch (error) {
+        throw new Error(`${label} 不是合法 JSON object: ${error.message}`);
+    }
+}
+function exactKeys(value, keys, label) {
+    const expected = [...keys].sort();
+    const actual = Object.keys(value).sort();
+    if (stableStringify(actual) !== stableStringify(expected)) {
+        throw new Error(`${label} 字段不精确: ${actual.join(',')}`);
+    }
+}
+function objectValue(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`${label} 必须是 object`);
+    return value;
+}
+function stringField(value, label) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new Error(`${label} 必须是非空字符串`);
+    return value.trim();
+}
+function boundedString(value, label, max) {
+    const item = stringField(value, label);
+    if (item.length > max)
+        throw new Error(`${label} 超过 ${max} 字符预算`);
+    return item;
+}
+function stringList(value, label) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || !item.trim())) {
+        throw new Error(`${label} 必须是非空字符串数组`);
+    }
+    return value.map((item) => item.trim());
+}
+function uniqueSafeIds(value, label, max) {
+    const items = stringList(value, label).map((item) => safeId(item, label));
+    if (!items.length || items.length > max || new Set(items).size !== items.length) {
+        throw new Error(`${label} 数量或唯一性非法`);
+    }
+    return items;
+}
+function safeId(value, label) {
+    const item = stringField(value, label);
+    if (!SAFE_ID.test(item))
+        throw new Error(`${label} 不是安全 ID: ${item}`);
+    return item;
+}
+function safeResourceId(value, label) {
+    const item = stringField(value, label);
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{1,127}$/.test(item))
+        throw new Error(`${label} 不是安全资源 ID`);
+    return item;
+}
+function hashField(value, label) {
+    const item = stringField(value, label);
+    if (!HASH.test(item))
+        throw new Error(`${label} 不是 SHA-256`);
+    return item;
+}
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function emptyHash() {
+    return '0'.repeat(64);
+}
+function errorCategory(error) {
+    return String(error?.message || error).replace(/[^a-zA-Z0-9._-]+/g, '-').slice(0, 120);
+}
+function isInside(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`));
+}
+//# sourceMappingURL=promotion.js.map