@nexusclawhq/cli 0.2.1

package/dist/nexus-cli/node_modules/@nexusclaw/shared/dist/ai-workforce-learning/index.d.ts

@@ -0,0 +1,743 @@
+export declare const AI_WORKFORCE_BEHAVIOR_EVENT_TYPES: readonly ["execution_started", "user_input_received", "context_retrieved", "knowledge_retrieved", "agent_output_generated", "tool_call_started", "tool_call_completed", "tool_call_failed", "policy_checked", "guardrail_triggered", "approval_requested", "approval_approved", "approval_rejected", "human_edit_applied", "human_handoff_triggered", "execution_completed", "execution_failed", "outcome_verified", "feedback_received", "learning_signal_generated", "improvement_recommendation_generated"];
+export type AiWorkforceBehaviorEventType = typeof AI_WORKFORCE_BEHAVIOR_EVENT_TYPES[number];
+export declare const AI_WORKFORCE_LEARNING_SIGNAL_TYPES: readonly ["successful_behavior_pattern", "failed_behavior_pattern", "human_correction_pattern", "approval_pattern", "rejection_pattern", "knowledge_gap", "knowledge_conflict", "missing_tool", "tool_failure_pattern", "prompt_policy_gap", "guardrail_gap", "workflow_bottleneck", "sop_drift", "model_routing_issue", "cost_optimization_opportunity", "autonomy_upgrade_candidate", "autonomy_downgrade_candidate", "test_case_candidate", "regression_case_candidate", "template_candidate", "auto_approval_candidate"];
+export type AiWorkforceLearningSignalType = typeof AI_WORKFORCE_LEARNING_SIGNAL_TYPES[number];
+export declare const AI_WORKFORCE_IMPROVEMENT_RECOMMENDATION_TYPES: readonly ["hire_new_employee", "improve_existing_employee", "create_workflow", "update_workflow", "add_guardrail", "relax_guardrail", "add_tool", "change_tool_permission", "update_sop", "update_knowledge", "generate_test_suite", "upgrade_autonomy", "downgrade_autonomy", "change_model_routing", "auto_approval_policy", "prompt_policy_update"];
+export type AiWorkforceImprovementRecommendationType = typeof AI_WORKFORCE_IMPROVEMENT_RECOMMENDATION_TYPES[number];
+export declare const AI_WORKFORCE_IMPROVEMENT_RECOMMENDATION_SOURCE_TYPES: readonly ["learning_signal", "learned_pattern", "behavior_event", "goal_blueprint", "advisor_recommendation"];
+export type AiWorkforceImprovementRecommendationSourceType = typeof AI_WORKFORCE_IMPROVEMENT_RECOMMENDATION_SOURCE_TYPES[number];
+export declare const AI_WORKFORCE_ARTIFACT_CANDIDATE_TYPES: readonly ["prompt_policy_update", "prompt_template_update", "guardrail_update", "workflow_update", "sop_update", "knowledge_update", "tool_permission_update", "approval_policy_update", "model_routing_update", "employee_template", "test_case", "eval_suite", "skill_recommendation"];
+export type AiWorkforceArtifactCandidateType = typeof AI_WORKFORCE_ARTIFACT_CANDIDATE_TYPES[number];
+export declare const AI_WORKFORCE_TARGET_ARTIFACT_TYPES: readonly ["agent", "agent_version", "prompt_policy", "prompt_template", "guardrail", "workflow", "sop", "knowledge", "tool_permission", "approval_policy", "model_routing", "employee_template", "test_case", "eval_suite"];
+export type AiWorkforceTargetArtifactType = typeof AI_WORKFORCE_TARGET_ARTIFACT_TYPES[number];
+export declare const AI_WORKFORCE_LEARNING_PIPELINE_STATUSES: readonly ["captured", "redaction_pending", "redacted", "ineligible", "eligible", "signal_extracted", "pattern_generated", "recommendation_generated", "draft_created", "tests_required", "simulation_running", "simulation_failed", "approval_required", "approved", "rejected", "ready_to_publish", "published", "rolled_back"];
+export type AiWorkforceLearningPipelineStatus = typeof AI_WORKFORCE_LEARNING_PIPELINE_STATUSES[number];
+export declare const AI_WORKFORCE_REDACTION_STATUSES: readonly ["not_required", "pending", "redacted", "failed", "blocked"];
+export type AiWorkforceRedactionStatus = typeof AI_WORKFORCE_REDACTION_STATUSES[number];
+export declare const AI_WORKFORCE_RELEASE_GATE_STATUSES: readonly ["not_started", "tests_required", "tests_running", "tests_failed", "simulation_required", "simulation_running", "simulation_failed", "approval_required", "ready_to_publish", "published", "blocked", "rolled_back"];
+export type AiWorkforceReleaseGateStatus = typeof AI_WORKFORCE_RELEASE_GATE_STATUSES[number];
+export declare const AI_WORKFORCE_APPROVAL_STATUSES: readonly ["not_required", "required", "pending", "approved", "rejected", "expired"];
+export type AiWorkforceApprovalStatus = typeof AI_WORKFORCE_APPROVAL_STATUSES[number];
+export declare const AI_WORKFORCE_RISK_LEVELS: readonly ["L0", "L1", "L2", "L3", "L4"];
+export type AiWorkforceRiskLevel = typeof AI_WORKFORCE_RISK_LEVELS[number];
+/**
+ * code-quality-audit-remediation-v1 R6 (P1-9) — single source of truth for
+ * "which risk levels are learning-eligible". Before this, three call sites
+ * each independently hand-wrote this same rule with drifted literal
+ * expressions: `behavior-learning-capture.service.ts` used
+ * `['L0','L1','L2'].includes(riskLevel)`, `behavior-learning-pipeline
+ * .service.ts` independently rewrote the identical whitelist for its
+ * `risk_not_allowed` gate, and `behavior-learning-governance-route
+ * .service.ts` used the logically-equivalent-but-differently-written
+ * complement `riskLevel !== 'L0' && riskLevel !== 'L1'` for its
+ * `approvalRequired` gate (see `requiresApprovalRiskLevel` below — a
+ * DIFFERENT rule, not a duplicate of this one; the two happen to be
+ * complements of each other today but govern different decisions and must
+ * stay as two named functions, not be collapsed into one).
+ */
+export declare const LEARNING_ELIGIBLE_RISK_LEVELS: readonly AiWorkforceRiskLevel[];
+export declare function isLearningEligibleRiskLevel(riskLevel: AiWorkforceRiskLevel): boolean;
+/**
+ * code-quality-audit-remediation-v1 R6 (P1-9) — single source of truth for
+ * "which risk levels require approval before publication". Governs
+ * `behavior-learning-governance-route.service.ts`'s `approvalRequired`
+ * decision. See `isLearningEligibleRiskLevel` above for why this is a
+ * separate function rather than reusing/negating that one.
+ */
+export declare function requiresApprovalRiskLevel(riskLevel: AiWorkforceRiskLevel): boolean;
+/**
+ * learning-content-generation-v1 R2.2 (rollback mutation) — closed set of
+ * stable reasonCode values a caller may pass to `rollbackLearningPublication`.
+ *
+ * Prior to this (Phase 0 finding), `rollback_reason_code`
+ * (`behavior-learning-rollback-execution.entity.ts`) and every owner
+ * rollback service only enforced the generic stable-code SHAPE regex
+ * (`^[a-z][a-z0-9_]*$`, see `normalizeRequiredStableCode()` in
+ * `behavior-learning-rollback-execution.service.ts`) — there was no closed
+ * vocabulary. This is a genuinely new contract, not a pre-existing word
+ * list being "discovered". The DB column stays free-form varchar to remain
+ * compatible with any pre-existing rows; this enum is enforced at the
+ * GraphQL/class-validator layer only (see
+ * `RollbackLearningPublicationInput.reasonCode` in
+ * `ai-workforce-learning-rollback.input.ts`).
+ *
+ * `cost_regression` / `safety_regression` added by
+ * model-routing-learning-publication-v1 Phase 5 (requirements.md R6,
+ * design.md §6): the three model_routing monitoring regression triggers
+ * (cost/quality/safety) each produce a rollback RECOMMENDATION carrying one
+ * of these stable codes. `quality_regression` already existed and is reused
+ * verbatim for the quality trigger — it is not a new concept, just a new
+ * (real) producer of an existing code. Per Q4 (signed): every trigger only
+ * ever produces a recommendation; a human must still separately call
+ * `rollbackLearningPublication` with this same reasonCode for the EXISTING
+ * Phase 4 rollback path to actually run — no trigger, including safety,
+ * calls that mutation itself (see
+ * `model-routing-monitoring-regression.service.ts`).
+ */
+export declare const AI_WORKFORCE_ROLLBACK_REASON_CODES: readonly ["quality_regression", "cost_regression", "safety_regression", "incident_rollback", "manual_operator_decision", "policy_violation"];
+export type AiWorkforceRollbackReasonCode = typeof AI_WORKFORCE_ROLLBACK_REASON_CODES[number];
+/**
+ * model-routing-learning-publication-v1 R2/R3/R5 — new stable reason codes
+ * the (Phase 4) `ModelRoutingPublicationAdapter` and its R2 safety guard /
+ * R3 budget guard / R5 simulation-evidence gate return via
+ * `BehaviorLearningPublicationAdapterRefusal.reasonCode`
+ * (`behavior-learning-publication-adapter.registry.ts`'s
+ * `reasonCode: string` field). The 4 existing adapters (guardrail/
+ * tool_permission/approval_policy/sop) reuse a shared *generic* rejection
+ * vocabulary (`target_missing` / `content_missing` / `content_invalid` /
+ * `rollback_owner_rejected`) as inline literals scattered per-adapter-file
+ * — there is no dedicated shared-package constant for that generic set
+ * today, and this spec does not introduce one (out of scope). What IS new
+ * here is a set of reason codes specific to a single artifact type's own
+ * guard logic (safety/budget/simulation-evidence gates unique to
+ * `model_routing`, requirements.md R2/R3/R5) — those get a named closed-set
+ * export so Phase 2's guards and Phase 4's adapter both reference the same
+ * stable codes instead of re-typing string literals in multiple files.
+ * Chinese/English copy for these lives only in
+ * `packages/shared/src/locales/{zh-CN,en-US}.ts`
+ * (`aiWorkforceLearningCopy.contentPanel.modelRoutingGuardReasonCode`,
+ * requirements.md R8) — never re-derive display text from the code string
+ * itself.
+ */
+export declare const AI_WORKFORCE_MODEL_ROUTING_GUARD_REASON_CODES: readonly ["safety_guard_rejected", "budget_guard_rejected", "simulation_evidence_missing"];
+export type AiWorkforceModelRoutingGuardReasonCode = typeof AI_WORKFORCE_MODEL_ROUTING_GUARD_REASON_CODES[number];
+/**
+ * learning-content-generation-v1 R3.6/R4 — content-generation posture per
+ * `AiWorkforceTargetArtifactType`. Drives both the `generateLearningDraftContent`
+ * mutation's structured-rejection branch and the front-end's per-type
+ * rendering (design.md §7):
+ *
+ * - `llm_patch`: the 7 patch-type owners (guardrail/knowledge/tool_permission/
+ *   approval_policy/employee_template/sop/model_routing) — LLM drafts a patch
+ *   payload against the type's content contract, subject to the full
+ *   evidence/validator/generation pipeline. NOTE (Phase 0 finding for the
+ *   first 6, do not re-litigate; model-routing-learning-publication-v1
+ *   Phase 4 for the 7th): 5 of these 7 (guardrail/tool_permission/
+ *   approval_policy/sop/model_routing) have zero real `targetArtifactId` in
+ *   the current pipeline (`BehaviorLearningTargetIdentityService` does not
+ *   resolve `model_routing` — see `model-routing-publication.adapter.ts`'s
+ *   class doc) and will therefore always terminate at a "target missing"
+ *   outcome before an LLM call is ever made — this posture only says "the
+ *   content SHAPE is patch-like", not "a real candidate of this type can
+ *   reach `generated`" via the fully-automated pipeline. Honesty note
+ *   specific to `model_routing` (do not conflate with the publish/rollback
+ *   chain below, which IS fully real): `learning-draft-content-generator
+ *   .service.ts`'s internal `describeSchemaForType()`/`validateForType()`
+ *   switches also have no `model_routing` case yet (both fall to their
+ *   generic default), so even a hand-supplied `targetArtifactId` reaching
+ *   the real `generateLearningDraftContent` mutation would terminate at
+ *   `validation_failed`, not `generated` — wiring that LLM-drafting path is
+ *   a real, separate, still-open gap, not required by
+ *   model-routing-learning-publication-v1 (R1-R7 only cover PUBLISHING an
+ *   already-generated candidate, not drafting one). What IS fully real and
+ *   proven end-to-end: a candidate whose `generatedContent` is set directly
+ *   (bypassing the LLM generator, the same "hand-built content" idiom the
+ *   other four adapters' own e2e coverage already uses) flows through the
+ *   real R1 re-validator, R2/R3/R5 guards, R4 canary overlay, and real
+ *   `setOrgPolicy` publish/rollback — see the real-Postgres full-lifecycle
+ *   integration test in `model-routing-publication-adapter.e2e.integration
+ *   .spec.ts`.
+ * - `reference_no_content`: `test_case`/`eval_suite` — the artifact already
+ *   has real, publishable content (a materialized `AgentTestCase` /
+ *   `AgentTestSuite`); there is nothing for an LLM to draft.
+ * - `reference_draft_pending`: `workflow`/`prompt_policy`/`prompt_template`/
+ *   `agent` — drafting requires materializing a non-active draft entity
+ *   through the owning module's own creation path, not just writing
+ *   `generated_content` on the candidate row. `prompt_template` moved INTO
+ *   this bucket in prompt-template-learning-publication-v1 Phase 2
+ *   (requirements.md R1/R7): `PromptTemplateVersionService`'s snapshot/
+ *   archive path is still not treated as the draft boundary (that judgment
+ *   from learning-content-generation-v2 phase-5 stands unchanged) — the NEW
+ *   `PromptTemplateLearningDraft` table is the real pending→activated→
+ *   rolled_back draft boundary instead. `agent` moved INTO this bucket in
+ *   agent-learning-publication-v1 Phase 2 (requirements.md R1/R3/R7, Q9
+ *   signed): ONLY `improve_existing_employee`-sourced candidates can reach
+ *   `generated` — `upgrade_autonomy`/`downgrade_autonomy` candidates share
+ *   this same `targetArtifactType`/posture but are still honestly deferred
+ *   by the generator's own R3 sub-gate (posture cannot distinguish
+ *   recommendationType; see `learning-draft-content-generator.service.ts`'s
+ *   `checkAgentAutonomySubGate()`) — autonomy-level semantics have no data
+ *   model in this codebase (Phase 0 finding) and remain out of scope for a
+ *   future, independent spec.
+ * - `deferred`: `agent_version` only — v2 product-decision defer, now
+ *   permanent (agent-version-learning-publication-v1 closed by decision,
+ *   2026-07-09: standalone publication is not needed — the existing
+ *   rollback owner already IS "publish a historical AgentVersion" in
+ *   substance). `model_routing` moved OUT of this bucket in model-routing-
+ *   learning-publication-v1 Phase 4 (requirements.md R7) — it is now
+ *   `llm_patch`, real adapter, real owner, real publish/rollback (see
+ *   `ModelRoutingPublicationAdapter`).
+ */
+export declare const AI_WORKFORCE_LEARNING_CONTENT_POSTURES: readonly ["llm_patch", "reference_no_content", "reference_draft_pending", "deferred"];
+export type AiWorkforceLearningContentPosture = typeof AI_WORKFORCE_LEARNING_CONTENT_POSTURES[number];
+/**
+ * Per-type posture lookup — single source of truth consumed by both the
+ * backend (`generateLearningDraftContent` mutation's non-`llm_patch`
+ * structured rejection) and the front-end (design.md §7 per-posture
+ * rendering). Every one of the 14 `AiWorkforceTargetArtifactType`s must
+ * appear exactly once here.
+ */
+export declare const AI_WORKFORCE_TARGET_ARTIFACT_CONTENT_POSTURE: Readonly<Record<AiWorkforceTargetArtifactType, AiWorkforceLearningContentPosture>>;
+export declare function getAiWorkforceLearningContentPosture(targetArtifactType: AiWorkforceTargetArtifactType): AiWorkforceLearningContentPosture;
+/**
+ * learning-content-generation-v1 R3/R4 — closed set of terminal
+ * `content_status` values a candidate's generated-content lifecycle can
+ * reach, plus the one non-terminal starting value. Exactly 4 terminal
+ * states per design.md §5.5 — do not add a 5th without updating the
+ * migration/entity/GraphQL object type together.
+ */
+export declare const AI_WORKFORCE_LEARNING_CONTENT_STATUSES: readonly ["not_generated", "generated", "insufficient_evidence", "validation_failed", "generation_failed"];
+export type AiWorkforceLearningContentStatus = typeof AI_WORKFORCE_LEARNING_CONTENT_STATUSES[number];
+/**
+ * learning-content-generation-v2 Phase 2 — persisted Goal-to-Agent blueprint
+ * lifecycle. These rows are draft planning artifacts only; none of these
+ * statuses may be interpreted as "active employee created" or "published".
+ */
+export declare const AI_WORKFORCE_GOAL_TO_AGENT_BLUEPRINT_STATUSES: readonly ["draft", "insufficient_evidence", "validation_failed"];
+export type AiWorkforceGoalToAgentBlueprintStatus = typeof AI_WORKFORCE_GOAL_TO_AGENT_BLUEPRINT_STATUSES[number];
+export interface AiWorkforceGoalToAgentLearningPlan {
+    captureSources: string[];
+    redactionPolicy: string;
+    learningOutputs: string[];
+    releaseControl: string;
+    approvalCheckpoints: string[];
+}
+export interface AiWorkforceGoalToAgentReleasePlan {
+    generatedTests: string[];
+    replayRequired: boolean;
+    riskReview: string;
+    approvalCheckpoints: string[];
+    versioningRequirement: string;
+    monitoringMetrics: string[];
+    rollbackRequirement: string;
+    releaseGateStatus: AiWorkforceReleaseGateStatus;
+    blockedReason?: string | null;
+}
+export interface AiWorkforceGoalToAgentBlueprint {
+    id: string;
+    status: AiWorkforceGoalToAgentBlueprintStatus;
+    businessGoal: string;
+    mission: string;
+    role: string;
+    scope: string[];
+    outOfScope: string[];
+    successMetrics: string[];
+    autonomyLevel: string;
+    tools: string[];
+    knowledge: string[];
+    guardrails: string[];
+    behaviorPolicy: string[];
+    tests: string[];
+    releasePlan: AiWorkforceGoalToAgentReleasePlan;
+    learningPlan: AiWorkforceGoalToAgentLearningPlan;
+    evidenceSourceIds: string[];
+    missingEvidence: string[];
+    riskLevel: AiWorkforceRiskLevel;
+    confidence: number;
+    /**
+     * Advisory-only success-contract seed. It is deliberately not an
+     * AgentCognitivePolicyV1 and cannot enter AgentVersion until a human manager
+     * confirms and converts it through the candidate owner API.
+     */
+    draftSuccessContract?: {
+        status: 'draft_success_contract';
+        mission: string;
+        metricCandidates: string[];
+        requiresHumanConfirmation: true;
+    };
+}
+/**
+ * learning-content-generation-v2 Phase 3 — Hiring Marketplace candidate
+ * read-model contract. This is a query/view contract only: a marketplace
+ * candidate is not an active employee and does not by itself publish any
+ * owner configuration.
+ */
+export declare const AI_WORKFORCE_HIRING_MARKETPLACE_SOURCE_TYPES: readonly ["behavior_candidate", "goal_blueprint", "advisor_recommendation"];
+export type AiWorkforceHiringMarketplaceSourceType = typeof AI_WORKFORCE_HIRING_MARKETPLACE_SOURCE_TYPES[number];
+export declare const AI_WORKFORCE_HIRING_MARKETPLACE_CANDIDATE_TYPES: readonly ["employee_template", "goal_to_agent_blueprint"];
+export type AiWorkforceHiringMarketplaceCandidateType = typeof AI_WORKFORCE_HIRING_MARKETPLACE_CANDIDATE_TYPES[number];
+export declare const AI_WORKFORCE_HIRING_MARKETPLACE_RELEASE_READINESS: readonly ["needs_tests", "needs_approval", "ready_for_draft", "blocked"];
+export type AiWorkforceHiringMarketplaceReleaseReadiness = typeof AI_WORKFORCE_HIRING_MARKETPLACE_RELEASE_READINESS[number];
+export interface AiWorkforceHiringMarketplaceCandidate {
+    id: string;
+    sourceType: AiWorkforceHiringMarketplaceSourceType;
+    sourceId: string;
+    candidateType: AiWorkforceHiringMarketplaceCandidateType;
+    releaseReadiness: AiWorkforceHiringMarketplaceReleaseReadiness;
+    title: string;
+    roleName: string;
+    mission: string;
+    sourceWorkPattern: string;
+    learnedFromWork: string;
+    whyNow: string;
+    autonomyLevel: string;
+    requiredTools: string[];
+    requiredKnowledge: string[];
+    guardrails: string[];
+    successMetrics: string[];
+    learningPlan: AiWorkforceGoalToAgentLearningPlan;
+    generatedTests: number;
+    riskLevel: AiWorkforceRiskLevel;
+    impactScore: number;
+    confidence: number;
+    releaseGateStatus: AiWorkforceReleaseGateStatus;
+    approvalStatus: AiWorkforceApprovalStatus;
+    evidenceSourceIds: string[];
+    targetArtifactId: string;
+    draftArtifactIds: string[];
+    recommendationId?: string | null;
+    blueprintId?: string | null;
+}
+export declare const AI_WORKFORCE_REDACTED_VALUE: "[REDACTED]";
+export type AiWorkforceJsonObject = Record<string, unknown>;
+export interface AiWorkforceToolCallSnapshot {
+    toolName: string;
+    input?: AiWorkforceJsonObject | null;
+    output?: AiWorkforceJsonObject | null;
+    success?: boolean | null;
+    errorCode?: string | null;
+    durationMs?: number | null;
+    retryCount?: number | null;
+    rollbackTriggered?: boolean | null;
+    approvalRequired?: boolean | null;
+    policyBlocked?: boolean | null;
+    guardrailCheck?: 'passed' | 'escalated' | 'blocked' | null;
+    permissionCheck?: 'passed' | 'denied' | null;
+}
+export interface AiWorkforceKnowledgeReferenceSnapshot {
+    sourceId: string;
+    chunkId?: string | null;
+    sourceRef?: string | null;
+    score?: number | null;
+    cited?: boolean | null;
+    verified?: boolean | null;
+    gapDetected?: boolean | null;
+    conflictDetected?: boolean | null;
+}
+export interface AiWorkforceApprovalSnapshot {
+    approvalId: string;
+    suggestedAction?: string | null;
+    approverId?: string | null;
+    decision?: 'approved' | 'rejected' | 'pending' | null;
+    rationale?: string | null;
+    agreementWithAi?: boolean | null;
+    durationMs?: number | null;
+    negativeOutcomeDetected?: boolean | null;
+}
+export interface AiWorkforceHumanEditSnapshot {
+    before?: string | AiWorkforceJsonObject | null;
+    after?: string | AiWorkforceJsonObject | null;
+    changedFields?: string[] | null;
+    deletedContent?: string[] | null;
+    addedContent?: string[] | null;
+    reason?: string | null;
+    improvedOutcome?: boolean | null;
+}
+export interface AiWorkforceOutcomeSnapshot {
+    status: 'completed' | 'failed' | 'reworked' | 'escalated' | 'unknown';
+    outcomeVerified?: boolean | null;
+    outcomeType?: string | null;
+    outcomeRecordId?: string | null;
+    savedMinutes?: number | null;
+    costReduction?: number | null;
+    revenueImpact?: number | null;
+    customerSatisfactionScore?: number | null;
+    riskIncident?: boolean | null;
+}
+export interface AiWorkforceFeedbackSnapshot {
+    rating?: 'up' | 'down' | 'neutral' | null;
+    reviewerFeedback?: string | null;
+    customerFeedback?: string | null;
+    qualityScore?: number | null;
+}
+export interface AiWorkforceBehaviorEvent {
+    id: string;
+    tenantId: string;
+    employeeId?: string | null;
+    agentId?: string | null;
+    workflowId?: string | null;
+    executionId: string;
+    spanId?: string | null;
+    correlationId: string;
+    eventType: AiWorkforceBehaviorEventType;
+    eventSource: string;
+    userId?: string | null;
+    department?: string | null;
+    channel?: string | null;
+    businessObjectType?: string | null;
+    businessObjectId?: string | null;
+    riskLevel: AiWorkforceRiskLevel;
+    inputSnapshot?: string | AiWorkforceJsonObject | null;
+    outputSnapshot?: string | AiWorkforceJsonObject | null;
+    contextSnapshot?: AiWorkforceJsonObject | null;
+    toolCalls?: AiWorkforceToolCallSnapshot[];
+    knowledgeRefs?: AiWorkforceKnowledgeReferenceSnapshot[];
+    approvals?: AiWorkforceApprovalSnapshot[];
+    humanEdits?: AiWorkforceHumanEditSnapshot[];
+    finalOutcome?: AiWorkforceOutcomeSnapshot | null;
+    feedback?: AiWorkforceFeedbackSnapshot | null;
+    labels?: string[];
+    redactionStatus: AiWorkforceRedactionStatus;
+    piiDetected: boolean;
+    learningEligible: boolean;
+    createdAt: string;
+}
+export interface AiWorkforceLearningSignal {
+    id: string;
+    tenantId: string;
+    signalType: AiWorkforceLearningSignalType;
+    sourceEventIds: string[];
+    employeeId?: string | null;
+    workflowId?: string | null;
+    affectedArtifactType?: AiWorkforceTargetArtifactType | null;
+    affectedArtifactId?: string | null;
+    title: string;
+    summary: string;
+    evidence: AiWorkforceJsonObject[];
+    confidence: number;
+    impactScore: number;
+    riskScore: number;
+    suggestedAction: string;
+    status: AiWorkforceLearningPipelineStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface AiWorkforceLearnedBehaviorPattern {
+    id: string;
+    tenantId: string;
+    patternType: AiWorkforceLearningSignalType;
+    title: string;
+    description: string;
+    derivedFromEventCount: number;
+    positiveExamples: string[];
+    negativeExamples: string[];
+    humanCorrectionExamples: string[];
+    applicableAgents: string[];
+    applicableWorkflows: string[];
+    suggestedPolicySnippet?: string | null;
+    suggestedTestCases: string[];
+    successMetrics: AiWorkforceJsonObject;
+    confidence: number;
+    status: AiWorkforceLearningPipelineStatus;
+    createdAt: string;
+}
+export interface AiWorkforceImprovementRecommendation {
+    id: string;
+    tenantId: string;
+    sourceType: AiWorkforceImprovementRecommendationSourceType;
+    sourceId: string;
+    targetArtifactType: AiWorkforceTargetArtifactType;
+    targetArtifactId?: string | null;
+    recommendationType: AiWorkforceImprovementRecommendationType;
+    title: string;
+    rationale: string;
+    /** Structured rationale metadata for i18n rendering — see the entity's
+     * `source_signal_type`/`source_event_count` column docs. `undefined` in
+     * shapes built before this field existed (e.g. some test fixtures). */
+    sourceSignalType?: AiWorkforceLearningSignalType | null;
+    sourceEventCount?: number | null;
+    evidence: AiWorkforceJsonObject[];
+    expectedImpact: AiWorkforceJsonObject;
+    riskAssessment: {
+        riskLevel: AiWorkforceRiskLevel;
+        reason: string;
+        riskScore: number;
+    };
+    proposedChange: AiWorkforceJsonObject;
+    generatedTests: string[];
+    simulationResult?: AiWorkforceJsonObject | null;
+    status: AiWorkforceLearningPipelineStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface AiWorkforceLearningArtifactCandidate {
+    id: string;
+    tenantId: string;
+    candidateType: AiWorkforceArtifactCandidateType;
+    generatedFrom: {
+        sourceType: 'learning_signal' | 'learned_pattern' | 'improvement_recommendation';
+        sourceId: string;
+    };
+    targetArtifactType: AiWorkforceTargetArtifactType;
+    targetArtifactId?: string | null;
+    draftPayload: AiWorkforceJsonObject;
+    testSuiteId?: string | null;
+    releaseGateStatus: AiWorkforceReleaseGateStatus;
+    approvalStatus: AiWorkforceApprovalStatus;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    /** learning-content-generation-v1 (R3/R4) — LLM-generated draft content
+     * lifecycle. `contentStatus` defaults to `not_generated` for every
+     * candidate created before this phase (migration default). */
+    contentStatus?: AiWorkforceLearningContentStatus;
+    generatedContent?: AiWorkforceJsonObject | null;
+    contentEvidence?: AiWorkforceLearningContentEvidence | null;
+}
+/**
+ * learning-content-generation-v1 §5.5 — the `content_evidence` jsonb
+ * envelope stored alongside `generated_content`. `usedEvidenceSourceIds` is
+ * the audit trail proving every generated fact traces back to a real
+ * behavior-event/target-snapshot id; `missingEvidence` is populated only on
+ * the `insufficient_evidence` terminal (including the LLM's own honest
+ * `cannotGenerate` protocol response); `truncation` records whether the
+ * event-snapshot volume cap (design.md §5.1 step 6) was hit.
+ */
+export interface AiWorkforceLearningContentEvidence {
+    usedEvidenceSourceIds: string[];
+    missingEvidence?: string[];
+    modelRef?: string | null;
+    generatedAt: string;
+    truncation?: {
+        truncatedEventCount: number;
+        totalEventCount: number;
+        maxEvents: number;
+        maxBytesPerEvent: number;
+    } | null;
+}
+/** Mirrors `LearningGuardrailRuleCandidatePatch`
+ * (`guardrail/services/guardrail-learning-publication-owner.service.ts`).
+ * Guardrail is a v1 patch-only, update-only target — Phase 0 confirmed the
+ * pipeline never produces a real `targetArtifactId` for this type (see
+ * `AI_WORKFORCE_TARGET_ARTIFACT_CONTENT_POSTURE` doc comment); this contract
+ * still exists so the adapter/validator can honestly report "target
+ * missing" rather than silently skip the type. */
+export interface LearningGuardrailRuleCandidatePatchContract {
+    name?: string | null;
+    description?: string | null;
+    isActive?: boolean | null;
+    priority?: number | null;
+    conditions?: Record<string, unknown> | null;
+    riskLevel?: AiWorkforceRiskLevel | null;
+    action?: Record<string, unknown> | null;
+}
+/** Mirrors `LearningKnowledgeSourceCandidatePatch`
+ * (`knowledge/services/knowledge-learning-publication-owner.service.ts`).
+ * `content` is required + non-empty (the owner service's
+ * `normalizeCandidateSourcePatch()` throws on empty/whitespace-only
+ * content) — this is the one patch-type contract where v1's real pipeline
+ * usually DOES have a real `targetArtifactId` (Phase 0 finding). */
+export interface LearningKnowledgeSourceCandidatePatchContract {
+    title?: string | null;
+    content: string;
+    sourceType?: string | null;
+    sourceObject?: string | null;
+    accessLevel?: 'public' | 'private' | 'org_subtree' | null;
+    orgNodeId?: string | null;
+    metadata?: Record<string, unknown> | null;
+}
+/** Mirrors `LearningToolPermissionCandidateConfig`
+ * (`agent-permission/services/tool-permission-learning-publication-owner.service.ts`).
+ * `allowedTools`/`blockedTools` are both required arrays; every tool name
+ * must match `STABLE_TOOL_NAME` (`/^[A-Za-z0-9:._/-]+$/`, exported below as
+ * {@link AI_WORKFORCE_STABLE_TOOL_NAME_PATTERN}) and a name may not appear
+ * in both arrays. Phase 0: 100% target-missing in the real v1 pipeline. */
+export interface LearningToolPermissionCandidateConfigContract {
+    allowedTools: string[];
+    blockedTools: string[];
+    maxQueriesPerMinute?: number | null;
+    maxWritesPerMinute?: number | null;
+    maxBatchSize?: number | null;
+}
+/** Regex the tool-permission owner service enforces on every entry of
+ * `allowedTools`/`blockedTools` (`STABLE_TOOL_NAME` in
+ * `tool-permission-learning-publication-owner.service.ts`). Exported so the
+ * shared validator and any front-end input validation use the exact same
+ * pattern rather than a hand-copied approximation. */
+export declare const AI_WORKFORCE_STABLE_TOOL_NAME_PATTERN: RegExp;
+/** Mirrors `LearningApprovalPolicyCandidatePatch`
+ * (`approval/services/approval-policy-learning-publication-owner.service.ts`).
+ * `steps`, when provided, must be a non-empty array of objects each carrying
+ * a stable `id`/`name`/`approverType`/`approverName` (owner service's
+ * `normalizeSteps()`). Phase 0: 100% target-missing in the real v1
+ * pipeline. */
+export interface LearningApprovalPolicyCandidatePatchContract {
+    name?: string | null;
+    description?: string | null;
+    entryCondition?: string | null;
+    steps?: Array<{
+        id: string;
+        name: string;
+        approverType: string;
+        approverName: string;
+        [key: string]: unknown;
+    }> | null;
+    riskAssessmentConfig?: Record<string, unknown> | null;
+    finalApprovalAction?: string | null;
+    finalRejectionAction?: string | null;
+}
+/** Mirrors `LearningEmployeeTemplateCandidatePatch`
+ * (`agent-builder/employee-template-learning-publication-owner.service.ts`).
+ * All 5 fields are required by the owner service's
+ * `normalizeCandidateTemplate()`. `templateKey` and `blueprint` are
+ * "constructed fields" (design.md §5.2) — the LLM never outputs
+ * `templateKey` directly (the generator service slugifies it from
+ * `roleName`), and only fills the semantic portion of `blueprint`; the rest
+ * of this contract (`title`/`roleName`/`mission`) IS real LLM output,
+ * subject to the evidence-closure prompt rules like every other patch
+ * type. */
+export interface LearningEmployeeTemplateCandidatePatchContract {
+    templateKey: string;
+    title: string;
+    roleName: string;
+    mission: string;
+    blueprint: Record<string, unknown>;
+}
+/** Regex the employee-template owner service enforces on `templateKey`
+ * (`TEMPLATE_KEY` in `employee-template-learning-publication-owner.service.ts`).
+ * Exported so the generator's slugify step and the shared validator use the
+ * exact same pattern. */
+export declare const AI_WORKFORCE_TEMPLATE_KEY_PATTERN: RegExp;
+/** Mirrors `LearningSopDocumentCandidatePatch`
+ * (`knowledge-distillation/sop-generator/sop-learning-publication-owner.service.ts`).
+ * All fields optional (owner service's `normalizeCandidateDocumentPatch()`
+ * only requires at least one field to be set). Phase 0: 100% target-missing
+ * in the real v1 pipeline (`sop_drift` signals carry no id field at all). */
+export interface LearningSopDocumentCandidatePatchContract {
+    title?: string | null;
+    category?: string | null;
+    applicableObjects?: string[] | null;
+    steps?: Record<string, unknown>[] | null;
+}
+/** A single flow node in a drafted `workflow` definition. Deliberately a
+ * looser structural shape than the backend's full `FlowNode`/`FlowNodeType`
+ * union (`packages/backend/.../workflow-version/types/flow-definition.types.ts`)
+ * — `FlowService.saveVersion()` is the real, authoritative validator
+ * (`validateGraph()`) and already runs on whatever this contract's `data`
+ * decodes to; this shared contract only needs to be strict enough to catch
+ * an LLM output that isn't even shaped like a node before it's ever handed
+ * to `saveVersion()`. `type` intentionally accepts any non-empty string
+ * (not a closed enum) so this contract never has to be kept in lockstep
+ * with the backend's node-type list — `saveVersion()` rejects unknown types
+ * on its own. */
+export interface LearningWorkflowDraftNodeContract {
+    id: string;
+    type: string;
+    name: string;
+    position?: {
+        x: number;
+        y: number;
+    } | null;
+    settings: Record<string, unknown>;
+}
+export interface LearningWorkflowDraftEdgeContract {
+    id: string;
+    source: string;
+    target: string;
+    sourceHandle?: string | null;
+    targetHandle?: string | null;
+    label?: string | null;
+}
+/** Mirrors `FlowVersionDefinition`
+ * (`workflow-version/types/flow-definition.types.ts`) — the exact shape
+ * `FlowService.saveVersion(versionId, definition, ...)` accepts as its
+ * `definition` argument. Only the `update_workflow` scenario is in v1 scope
+ * (requirements.md R5.3 — `create_workflow`'s trigger hint is confirmed
+ * dead code); this contract still models `trigger` since `saveVersion()`
+ * accepts and persists it regardless of which recommendation type produced
+ * the candidate. */
+export interface LearningWorkflowDraftDefinitionContract {
+    version: string;
+    nodes: LearningWorkflowDraftNodeContract[];
+    edges: LearningWorkflowDraftEdgeContract[];
+    trigger?: Record<string, unknown> | null;
+}
+/** Mirrors `CreatePromptStrategyInput`
+ * (`ai-service/prompt-strategy.service.ts`) — the exact shape
+ * `PromptStrategyService.create(data)` accepts, minus `workspaceId` (always
+ * supplied by the generator from the caller's context, never from LLM
+ * output, same rule as every other type in this file). `create()` hardcodes
+ * `isActive: false`, so this contract's fields never influence activation
+ * state — activation only ever happens later via
+ * `PromptStrategyService.activate()`, called exclusively by
+ * `PromptPolicyLearningPublicationOwnerService` during real publication. */
+export interface LearningPromptPolicyDraftContentContract {
+    name: string;
+    description?: string | null;
+    industry?: string | null;
+    templateOverrides?: Record<string, unknown> | null;
+}
+export declare const AI_WORKFORCE_LEARNING_STATUS_TRANSITIONS: Readonly<Record<AiWorkforceLearningPipelineStatus, readonly AiWorkforceLearningPipelineStatus[]>>;
+export declare function canTransitionAiWorkforceLearningStatus(from: AiWorkforceLearningPipelineStatus, to: AiWorkforceLearningPipelineStatus): boolean;
+export declare function getAiWorkforceLearningReadinessIssues(event: Pick<AiWorkforceBehaviorEvent, 'learningEligible' | 'redactionStatus'>): string[];
+export declare function isAiWorkforceBehaviorEventLearningReady(event: Pick<AiWorkforceBehaviorEvent, 'learningEligible' | 'redactionStatus'>): boolean;
+export declare function createRedactedAiWorkforceBehaviorEventSample(overrides?: Partial<AiWorkforceBehaviorEvent>): AiWorkforceBehaviorEvent;
+export type LearningContentValidationResult<T> = {
+    valid: true;
+    data: T;
+} | {
+    valid: false;
+    errors: string[];
+};
+export declare function validateLearningGuardrailRuleCandidatePatch(raw: unknown): LearningContentValidationResult<LearningGuardrailRuleCandidatePatchContract>;
+export declare function validateLearningKnowledgeSourceCandidatePatch(raw: unknown): LearningContentValidationResult<LearningKnowledgeSourceCandidatePatchContract>;
+export declare function validateLearningToolPermissionCandidateConfig(raw: unknown): LearningContentValidationResult<LearningToolPermissionCandidateConfigContract>;
+export declare function validateLearningApprovalPolicyCandidatePatch(raw: unknown): LearningContentValidationResult<LearningApprovalPolicyCandidatePatchContract>;
+export declare function validateLearningEmployeeTemplateCandidatePatch(raw: unknown): LearningContentValidationResult<LearningEmployeeTemplateCandidatePatchContract>;
+export declare function validateLearningSopDocumentCandidatePatch(raw: unknown): LearningContentValidationResult<LearningSopDocumentCandidatePatchContract>;
+export declare function validateLearningWorkflowDraftDefinition(raw: unknown): LearningContentValidationResult<LearningWorkflowDraftDefinitionContract>;
+export declare function validateLearningPromptPolicyDraftContent(raw: unknown): LearningContentValidationResult<LearningPromptPolicyDraftContentContract>;
+/** v1 whitelist subset of `OrgAIProviderModelPolicy`
+ * (`org-ai-provider-policy.entity.ts:43-50`) — only the two mapping fields
+ * a learning-generated candidate patch may set (requirements.md R1, Q2
+ * signed: "不扩展，仅 modelPolicy 两个映射字段"). */
+export interface LearningModelRoutingCandidatePatchContract {
+    modelPolicy: {
+        defaultModelByCapability?: Record<string, string>;
+        defaultModelByScenario?: Record<string, string>;
+    };
+}
+/** Convenience alias matching the exact name requirements.md R1 / tasks.md
+ * Phase 1 use ("新增 `LearningModelRoutingCandidatePatch` +
+ * `validateLearningModelRoutingCandidatePatch()`") — same type as
+ * {@link LearningModelRoutingCandidatePatchContract}, which follows this
+ * file's established `*Contract` naming convention for every other
+ * patch-type contract above. */
+export type LearningModelRoutingCandidatePatch = LearningModelRoutingCandidatePatchContract;
+/**
+ * mirrors the v1 whitelist described in the block comment above — takes the
+ * LLM's raw (already `JSON.parse`d) candidate patch and either narrows it
+ * to exactly `{ modelPolicy: { defaultModelByCapability?, defaultModelByScenario? } }`
+ * or reports every whitelist violation / shape error found. Never throws
+ * (same discriminated-union contract as every other validator in this
+ * file).
+ */
+export declare function validateLearningModelRoutingCandidatePatch(raw: unknown): LearningContentValidationResult<LearningModelRoutingCandidatePatchContract>;
+export interface LearningPromptTemplateCandidatePatchContract {
+    template: string;
+}
+/** Convenience alias matching requirements.md R2 / tasks.md Phase 1 naming
+ * (`LearningPromptTemplateCandidatePatch`), same convention as
+ * {@link LearningModelRoutingCandidatePatch} above. */
+export type LearningPromptTemplateCandidatePatch = LearningPromptTemplateCandidatePatchContract;
+/**
+ * Body-only whitelist validator — narrows the LLM's raw (already
+ * `JSON.parse`d) output to exactly `{ template: string }` or reports every
+ * whitelist violation / shape error found. Never throws (same
+ * discriminated-union contract as every other validator in this file).
+ * The body is intentionally NOT trimmed — leading/trailing whitespace can
+ * be meaningful in a prompt template; only the "effectively empty" check
+ * uses a trimmed view.
+ */
+export declare function validateLearningPromptTemplateCandidatePatch(raw: unknown): LearningContentValidationResult<LearningPromptTemplateCandidatePatchContract>;
+export interface LearningAgentCandidatePatchContract {
+    persona?: string;
+    systemInstructions?: string;
+    identityPolicy?: string;
+}
+/** Convenience alias matching requirements.md R2 / tasks.md Phase 1 naming
+ * (`LearningAgentCandidatePatch`), same convention as
+ * {@link LearningPromptTemplateCandidatePatch} above. */
+export type LearningAgentCandidatePatch = LearningAgentCandidatePatchContract;
+/**
+ * Three-field whitelist validator — narrows the LLM's raw (already
+ * `JSON.parse`d) output to a subset of `{ persona?, systemInstructions?,
+ * identityPolicy? }` (each, when present, a non-empty string) or reports
+ * every whitelist violation / shape error found. Never throws (same
+ * discriminated-union contract as every other validator in this file).
+ * Bodies are intentionally NOT trimmed for the same reason
+ * `validateLearningPromptTemplateCandidatePatch` does not trim `template` —
+ * leading/trailing whitespace can be meaningful in prompt-adjacent text;
+ * only the "effectively empty" check uses a trimmed view.
+ */
+export declare function validateLearningAgentCandidatePatch(raw: unknown): LearningContentValidationResult<LearningAgentCandidatePatchContract>;