@oscharko-dev/keiko-contracts 0.2.0

package/dist/prompt-enhancer-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-enhancer-safety.d.ts","sourceRoot":"","sources":["../src/prompt-enhancer-safety.ts"],"names":[],"mappings":"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"}

package/dist/prompt-enhancer-safety.js

@@ -0,0 +1,446 @@
+// Prompt Enhancer safety annotations and the deterministic validate-stage rule model
+// (Epic #1307, Issue #1313; ADR-0044 §4/§5/§7).
+//
+// This module owns the machine-readable safety-annotation shapes and the STRUCTURAL half of the
+// validate stage: a pure, deterministic assessment of whether an `EnhancedPrompt` upholds the safety
+// invariants the enhancer must never relax — trusted/untrusted channel separation (AC1), untrusted
+// content marked and unable to override instructions (AC2), no capability-grant / secret-disclosure
+// claims, an explicit human-review + least-privilege posture for risky agentic tasks (AC5), and an
+// output-validation expectation for structured outputs. The result is a wire-safe
+// `PromptSafetyAssessment` the evidence model (#1313, keiko-evidence) and the server (#1314) can
+// transmit, persist, and render.
+//
+// Split of responsibility (ADR-0044 §5 — redaction is distinct from validation): this leaf module
+// performs the STRUCTURAL validation derivable from the prompt + analysis alone (presence of required
+// safeguards, absence of authority-grant claims in the trusted sections). The AUTHORITATIVE text-level
+// detection of prompt injection, secret-exfiltration, and manipulative content in untrusted input
+// lives in `keiko-security` and is composed over this assessment by the gateway validate stage
+// (`keiko-model-gateway/src/promptEnhancer/validate.ts`); the leaf-package rule (ADR-0019 direction 1)
+// forbids importing it here. The findings vocabulary below is the shared closed set both layers emit.
+//
+// Determinism: pure. No IO, clock, crypto, or randomness. No raw user input is echoed — every finding
+// `detail` is a fixed, content-free template. A generated prompt is data, never a capability grant
+// (ADR-0044 §4): nothing here can encode or confer tool, secret, egress, or patch authority.
+import { stripUnsafeFormatChars } from "./text-safety.js";
+import { PROMPT_ENHANCER_SCHEMA_VERSION, validatePromptEnhancerIdString, } from "./prompt-enhancer.js";
+export const PROMPT_SAFETY_RULE_IDS = [
+    "trusted-untrusted-separation",
+    "untrusted-content-marked",
+    "no-authority-grant",
+    "no-secret-or-system-prompt-disclosure",
+    "human-review-for-risky-actions",
+    "least-privilege-tool-access",
+    "output-validation-required",
+    "no-manipulative-or-injected-instructions",
+];
+export const PROMPT_SAFETY_VIOLATION_CODES = [
+    "missing-channel-separation",
+    "missing-untrusted-marker",
+    "missing-authority-restriction",
+    "missing-secrecy-rule",
+    "missing-human-review",
+    "missing-least-privilege",
+    "missing-output-validation",
+    "capability-grant-claim",
+    "secret-request",
+    "system-prompt-disclosure",
+    "untrusted-instruction-override",
+    "manipulative-instruction",
+    "hidden-assumption",
+];
+export const isPromptSafetyViolationCode = (value) => typeof value === "string" && PROMPT_SAFETY_VIOLATION_CODES.includes(value);
+export const PROMPT_SAFETY_SEVERITIES = [
+    "info",
+    "warning",
+    "blocking",
+];
+export const LEAST_PRIVILEGE_CONSTRAINTS = [
+    "no-tool-execution",
+    "no-file-write",
+    "no-network-egress",
+    "no-secret-access",
+    "require-human-approval",
+];
+// The baseline deny-all posture every generated prompt carries (least privilege by default).
+const BASELINE_LEAST_PRIVILEGE = [
+    "no-tool-execution",
+    "no-file-write",
+    "no-network-egress",
+    "no-secret-access",
+];
+export const PROMPT_SAFETY_DECISIONS = [
+    "accepted",
+    "requires-human-review",
+    "rejected",
+];
+export const PROMPT_SAFETY_VERIFICATION_STATUSES = [
+    "passed",
+    "passed-with-review",
+    "failed",
+];
+// ─── Finding + assessment shapes ─────────────────────────────────────────────────────
+const SAFETY_DETAIL_MAX_CHARS = 400;
+// Fixed, content-free detail templates keyed by violation code. Stable strings so the audit trail and
+// UI render consistent, never-echoing explanations.
+export const PROMPT_SAFETY_VIOLATION_DETAILS = {
+    "missing-channel-separation": "The prompt does not instruct the model to treat the user Input section as data rather than instructions.",
+    "missing-untrusted-marker": "The grounding plan does not mark external and retrieved content as untrusted.",
+    "missing-authority-restriction": "The prompt does not state that it grants no tool, file, network, or secret authority.",
+    "missing-secrecy-rule": "The prompt does not forbid disclosing secrets, credentials, or system instructions.",
+    "missing-human-review": "A risky agentic prompt does not require explicit human approval before side-effecting actions.",
+    "missing-least-privilege": "A risky agentic prompt does not constrain the model to least-privilege, approval-gated actions.",
+    "missing-output-validation": "A structured-output prompt does not require the response to conform to the declared format.",
+    "capability-grant-claim": "A trusted section appears to grant the model tool, file, network, or secret authority.",
+    "secret-request": "Content requests secrets, credentials, environment values, or system instructions.",
+    "system-prompt-disclosure": "Content requests disclosure of the system or developer prompt.",
+    "untrusted-instruction-override": "Content attempts to override or ignore the trusted instructions.",
+    "manipulative-instruction": "Content uses manipulative framing or role reassignment to alter the model's behaviour.",
+    "hidden-assumption": "A trusted section introduces an unstated assumption not derived from the analysis.",
+};
+// ─── Pure predicates ─────────────────────────────────────────────────────────────────
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isMember = (value, allowed) => typeof value === "string" && allowed.includes(value);
+const isBoundedSafeText = (value, max) => typeof value === "string" && value.length <= max && stripUnsafeFormatChars(value) === value;
+const containsAll = (haystack, needles) => needles.every((needle) => haystack.includes(needle));
+const containsAny = (haystack, needles) => needles.some((needle) => haystack.includes(needle));
+// ─── Required-safeguard predicates over the trusted sections ──────────────────────────
+// These confirm a generated prompt actually carries the safeguard. They match on robust concept
+// keywords, not brittle exact strings, so wording can evolve while the safeguard stays detectable.
+const marksInputAsData = (context) => {
+    const text = context.join(" \n ").toLowerCase();
+    return containsAll(text, ["input", "data"]) && containsAny(text, ["instruction", "directions"]);
+};
+const assertsNoAuthority = (safetyRules) => {
+    const text = safetyRules.join(" \n ").toLowerCase();
+    return (text.includes("not an authorization") ||
+        (text.includes("grant") && containsAny(text, ["no tool", "no secret", "no access"])));
+};
+const forbidsSecretDisclosure = (safetyRules) => {
+    const text = safetyRules.join(" \n ").toLowerCase();
+    return (containsAny(text, ["do not reveal", "never reveal", "do not disclose"]) &&
+        containsAny(text, ["secret", "credential", "system instruction", "system prompt"]));
+};
+const requiresHumanApprovalRule = (safetyRules) => {
+    const text = safetyRules.join(" \n ").toLowerCase();
+    return containsAny(text, ["human approval", "explicit approval", "explicit human"]);
+};
+// Distinct from the human-approval rule: the least-privilege constraint instructs the model not to
+// *assume* tool/file/network authority in the first place. Matched on its own phrasing so the two
+// safeguards are checked independently (a tampered prompt could drop one but keep the other).
+const carriesLeastPrivilegeConstraint = (constraints, safetyRules) => {
+    const text = [...constraints, ...safetyRules].join(" \n ").toLowerCase();
+    return (text.includes("do not assume authority") ||
+        text.includes("least privilege") ||
+        text.includes("least-privilege"));
+};
+const requiresOutputConformance = (constraints, qualityCriteria) => {
+    const text = [...constraints, ...qualityCriteria].join(" \n ").toLowerCase();
+    return containsAny(text, ["required output format", "required format", "conform"]);
+};
+// ─── Prohibited-pattern predicates over the trusted sections (defense in depth, AC3) ──
+// A correctly generated prompt never contains these in its TRUSTED sections; a forged or tampered
+// candidate would. The authoritative detection over UNTRUSTED input lives in keiko-security.
+const TRUSTED_AUTHORITY_GRANT_CUES = [
+    "grant yourself",
+    "give yourself access",
+    "you may run any",
+    "you are authorized to run",
+    "you can execute any",
+];
+const TRUSTED_OVERRIDE_CUES = [
+    "ignore previous instructions",
+    "ignore all previous",
+    "disregard previous",
+    "disregard the above",
+    "ignore the above",
+    "ignore the safety rules",
+];
+const TRUSTED_DISCLOSURE_CUES = [
+    "reveal the system prompt",
+    "print the system prompt",
+    "reveal your system prompt",
+    "disclose the system prompt",
+];
+const TRUSTED_ASSUMPTION_PREFIX = "Assumption: ";
+// ─── Human-review derivation ──────────────────────────────────────────────────────────
+/**
+ * Derive whether a task is risky enough to require human review before any side-effecting action
+ * (AC5). Pure. A task is risky when it is agentic, requests tool/egress authority, or is critical.
+ */
+export function requiresHumanReviewForAnalysis(analysis) {
+    return (analysis.criticality === "critical" ||
+        analysis.taskClass === "agentic-tool-use" ||
+        analysis.riskFlags.includes("tool-authority-requested") ||
+        analysis.riskFlags.includes("egress-requested"));
+}
+/**
+ * Reduce a finding set and the human-review flag to the decision + verification status. Pure. Shared
+ * by the structural assessor and the gateway validate stage (which adds security findings first).
+ */
+export function summarizePromptSafety(findings, requiresHumanReview) {
+    if (findings.some((finding) => finding.severity === "blocking")) {
+        return { decision: "rejected", verificationStatus: "failed" };
+    }
+    if (requiresHumanReview) {
+        return { decision: "requires-human-review", verificationStatus: "passed-with-review" };
+    }
+    return { decision: "accepted", verificationStatus: "passed" };
+}
+/**
+ * Compute the least-privilege constraint set for a task. Pure. Always denies tool/file/egress/secret
+ * authority (least privilege by default); risky tasks additionally require human approval (AC5).
+ */
+export function leastPrivilegeForAnalysis(analysis) {
+    return requiresHumanReviewForAnalysis(analysis)
+        ? [...BASELINE_LEAST_PRIVILEGE, "require-human-approval"]
+        : [...BASELINE_LEAST_PRIVILEGE];
+}
+function finding(code, ruleId, severity) {
+    return { code, ruleId, severity, detail: PROMPT_SAFETY_VIOLATION_DETAILS[code] };
+}
+// Baseline safeguards required of EVERY generated prompt (AC1/AC2, no-authority, no-disclosure).
+function collectBaselineSafeguardFindings(prompt) {
+    const findings = [];
+    // AC2 — untrusted content must be marked. `untrustedContent` is pinned to `true` in the type, but a
+    // forged/cast object can violate it, so the runtime check is load-bearing.
+    if (prompt.groundingPlan.untrustedContent !== true) {
+        findings.push(finding("missing-untrusted-marker", "untrusted-content-marked", "blocking"));
+    }
+    // AC1 — the Input section must be labelled as data, not instructions.
+    if (!marksInputAsData(prompt.context)) {
+        findings.push(finding("missing-channel-separation", "trusted-untrusted-separation", "blocking"));
+    }
+    // ADR-0044 §4 — no authority grant.
+    if (!assertsNoAuthority(prompt.safetyRules)) {
+        findings.push(finding("missing-authority-restriction", "no-authority-grant", "blocking"));
+    }
+    // Scope — no secret / system-prompt disclosure.
+    if (!forbidsSecretDisclosure(prompt.safetyRules)) {
+        findings.push(finding("missing-secrecy-rule", "no-secret-or-system-prompt-disclosure", "blocking"));
+    }
+    return findings;
+}
+// Conditional safeguards: human review + least privilege for risky tasks (AC5), and an output-
+// validation expectation for structured outputs.
+function collectConditionalSafeguardFindings(prompt, requiresReview) {
+    const findings = [];
+    if (requiresReview && !requiresHumanApprovalRule(prompt.safetyRules)) {
+        findings.push(finding("missing-human-review", "human-review-for-risky-actions", "blocking"));
+    }
+    if (requiresReview && !carriesLeastPrivilegeConstraint(prompt.constraints, prompt.safetyRules)) {
+        findings.push(finding("missing-least-privilege", "least-privilege-tool-access", "blocking"));
+    }
+    if (prompt.outputSchema.structured &&
+        !requiresOutputConformance(prompt.constraints, prompt.qualityCriteria)) {
+        findings.push(finding("missing-output-validation", "output-validation-required", "warning"));
+    }
+    return findings;
+}
+function collectStructuralFindings(prompt, requiresReview) {
+    return [
+        ...collectBaselineSafeguardFindings(prompt),
+        ...collectConditionalSafeguardFindings(prompt, requiresReview),
+    ];
+}
+function trustedEntries(prompt) {
+    return [
+        prompt.role,
+        prompt.goal,
+        ...prompt.context,
+        ...prompt.taskDecomposition,
+        ...prompt.constraints,
+        ...prompt.groundingRules,
+        ...prompt.qualityCriteria,
+        ...prompt.uncertaintyHandling,
+        ...prompt.safetyRules,
+    ];
+}
+function collectHiddenAssumptionFindings(prompt, analysis) {
+    const allowed = new Set(analysis.missingContext
+        .filter((item) => item.kind === "assumption")
+        .map((item) => `${TRUSTED_ASSUMPTION_PREFIX}${item.statement}`));
+    const hasHiddenAssumption = trustedEntries(prompt)
+        .flatMap((entry) => entry.split(/\r?\n/u).map((line) => line.trim()))
+        .some((entry) => entry.startsWith(TRUSTED_ASSUMPTION_PREFIX) && !allowed.has(entry));
+    return hasHiddenAssumption
+        ? [finding("hidden-assumption", "no-manipulative-or-injected-instructions", "blocking")]
+        : [];
+}
+function collectProhibitedTrustedFindings(prompt, analysis) {
+    const trusted = [...trustedEntries(prompt)].join(" \n ").toLowerCase();
+    const findings = [];
+    if (containsAny(trusted, TRUSTED_AUTHORITY_GRANT_CUES)) {
+        findings.push(finding("capability-grant-claim", "no-authority-grant", "blocking"));
+    }
+    if (containsAny(trusted, TRUSTED_OVERRIDE_CUES)) {
+        findings.push(finding("untrusted-instruction-override", "no-manipulative-or-injected-instructions", "blocking"));
+    }
+    if (containsAny(trusted, TRUSTED_DISCLOSURE_CUES)) {
+        findings.push(finding("system-prompt-disclosure", "no-secret-or-system-prompt-disclosure", "blocking"));
+    }
+    findings.push(...collectHiddenAssumptionFindings(prompt, analysis));
+    return findings;
+}
+/**
+ * Deterministically assess the STRUCTURAL safety of an `EnhancedPrompt` against the validate-stage
+ * rule set. Pure. Confirms the required safeguards are present (AC1/AC2/AC5, no-authority,
+ * no-disclosure, output validation) and that the trusted sections carry no authority-grant, override,
+ * or disclosure claim (AC3 defense in depth). The authoritative text-level detection over untrusted
+ * input is layered on top by the gateway validate stage; this function never inspects raw input.
+ */
+export function assessEnhancedPromptStructuralSafety(prompt, analysis) {
+    const requiresReview = requiresHumanReviewForAnalysis(analysis);
+    const findings = [
+        ...collectStructuralFindings(prompt, requiresReview),
+        ...collectProhibitedTrustedFindings(prompt, analysis),
+    ];
+    const { decision, verificationStatus } = summarizePromptSafety(findings, requiresReview);
+    return {
+        schemaVersion: PROMPT_ENHANCER_SCHEMA_VERSION,
+        promptId: prompt.promptId,
+        decision,
+        requiresHumanReview: requiresReview,
+        verificationStatus,
+        findings,
+        leastPrivilege: leastPrivilegeForAnalysis(analysis),
+    };
+}
+// ─── Wire validator ────────────────────────────────────────────────────────────────
+const ASSESSMENT_KEYS = new Set([
+    "schemaVersion",
+    "promptId",
+    "decision",
+    "requiresHumanReview",
+    "verificationStatus",
+    "findings",
+    "leastPrivilege",
+]);
+const FINDING_KEYS = new Set(["code", "ruleId", "severity", "detail"]);
+const ASSESSMENT_FINDINGS_MAX = 256;
+const VERIFICATION_BY_DECISION = {
+    accepted: "passed",
+    "requires-human-review": "passed-with-review",
+    rejected: "failed",
+};
+function validateFinding(value, index, errors) {
+    const label = `assessment.findings[${String(index)}]`;
+    if (!isRecord(value)) {
+        errors.push(`${label} must be an object`);
+        return false;
+    }
+    let ok = true;
+    if (Object.keys(value).some((key) => !FINDING_KEYS.has(key))) {
+        errors.push(`${label} must not contain unknown fields`);
+        ok = false;
+    }
+    if (!isPromptSafetyViolationCode(value.code)) {
+        errors.push(`${label}.code must be a known violation code`);
+        ok = false;
+    }
+    if (!isMember(value.ruleId, PROMPT_SAFETY_RULE_IDS)) {
+        errors.push(`${label}.ruleId must be a known safety rule id`);
+        ok = false;
+    }
+    const isBlocking = value.severity === "blocking";
+    if (!isMember(value.severity, PROMPT_SAFETY_SEVERITIES)) {
+        errors.push(`${label}.severity must be a known severity`);
+        ok = false;
+    }
+    if (!isBoundedSafeText(value.detail, SAFETY_DETAIL_MAX_CHARS)) {
+        errors.push(`${label}.detail must be a bounded, control-free string`);
+        ok = false;
+    }
+    return ok && isBlocking;
+}
+function validateAssessmentScalars(input, errors) {
+    if (Object.keys(input).some((key) => !ASSESSMENT_KEYS.has(key))) {
+        errors.push("assessment must not contain unknown fields");
+    }
+    if (input.schemaVersion !== PROMPT_ENHANCER_SCHEMA_VERSION) {
+        errors.push(`assessment.schemaVersion must be "${PROMPT_ENHANCER_SCHEMA_VERSION}"`);
+    }
+    const promptIdResult = validatePromptEnhancerIdString(input.promptId, "EnhancedPromptId");
+    if (!promptIdResult.ok)
+        errors.push(`assessment.promptId: ${promptIdResult.reason}`);
+    if (!isMember(input.decision, PROMPT_SAFETY_DECISIONS)) {
+        errors.push(`assessment.decision must be one of ${PROMPT_SAFETY_DECISIONS.join("|")}`);
+    }
+    if (typeof input.requiresHumanReview !== "boolean") {
+        errors.push("assessment.requiresHumanReview must be a boolean");
+    }
+    if (!isMember(input.verificationStatus, PROMPT_SAFETY_VERIFICATION_STATUSES)) {
+        errors.push(`assessment.verificationStatus must be one of ${PROMPT_SAFETY_VERIFICATION_STATUSES.join("|")}`);
+    }
+}
+// Validate the findings array; returns the number of well-formed blocking findings (or -1 when the
+// array itself is malformed, so the caller can skip the blocking-count cross-checks).
+function validateAssessmentFindings(input, errors) {
+    if (!Array.isArray(input.findings) || input.findings.length > ASSESSMENT_FINDINGS_MAX) {
+        errors.push(`assessment.findings must be an array of at most ${String(ASSESSMENT_FINDINGS_MAX)} entries`);
+        return -1;
+    }
+    let blockingCount = 0;
+    input.findings.forEach((entry, index) => {
+        if (validateFinding(entry, index, errors))
+            blockingCount += 1;
+    });
+    return blockingCount;
+}
+function isValidLeastPrivilege(value) {
+    return (Array.isArray(value) &&
+        value.every((entry) => isMember(entry, LEAST_PRIVILEGE_CONSTRAINTS)) &&
+        new Set(value).size === value.length);
+}
+function validateDecisionConsistency(input, blockingCount, errors) {
+    if (!isMember(input.decision, PROMPT_SAFETY_DECISIONS) || blockingCount < 0)
+        return;
+    if (input.verificationStatus !== VERIFICATION_BY_DECISION[input.decision]) {
+        errors.push("assessment.verificationStatus must match the decision");
+    }
+    if (input.decision === "rejected" && blockingCount === 0) {
+        errors.push("assessment.decision rejected requires at least one blocking finding");
+    }
+    if (input.decision !== "rejected" && blockingCount > 0) {
+        errors.push("assessment.decision must be rejected when a blocking finding is present");
+    }
+}
+function validateHumanReviewConstraint(input, leastPrivilegeOk, errors) {
+    if (input.decision === "accepted" && input.requiresHumanReview !== false) {
+        errors.push("assessment.decision accepted requires requiresHumanReview to be false");
+    }
+    if (input.decision === "requires-human-review" && input.requiresHumanReview !== true) {
+        errors.push("assessment.decision requires-human-review requires requiresHumanReview to be true");
+    }
+    if (input.requiresHumanReview === true &&
+        leastPrivilegeOk &&
+        !input.leastPrivilege.includes("require-human-approval")) {
+        errors.push("assessment.leastPrivilege must include require-human-approval when human review is required");
+    }
+}
+function validateAssessmentCrossFields(input, blockingCount, leastPrivilegeOk, errors) {
+    validateDecisionConsistency(input, blockingCount, errors);
+    validateHumanReviewConstraint(input, leastPrivilegeOk, errors);
+}
+/**
+ * Validate a `PromptSafetyAssessment`. Pure; returns a discriminated result and never throws. Checks
+ * structural well-formedness and the cross-field invariants that make the assessment trustworthy: the
+ * verification status matches the decision, a `rejected` decision carries at least one blocking
+ * finding, and a human-review requirement implies the `require-human-approval` least-privilege
+ * constraint.
+ */
+export function validatePromptSafetyAssessment(input) {
+    if (!isRecord(input)) {
+        return { ok: false, errors: ["assessment must be an object"] };
+    }
+    const errors = [];
+    validateAssessmentScalars(input, errors);
+    const blockingCount = validateAssessmentFindings(input, errors);
+    const leastPrivilegeOk = isValidLeastPrivilege(input.leastPrivilege);
+    if (!leastPrivilegeOk) {
+        errors.push("assessment.leastPrivilege must be an array of unique least-privilege constraints");
+    }
+    validateAssessmentCrossFields(input, blockingCount, leastPrivilegeOk, errors);
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, value: input };
+}

package/dist/prompt-enhancer-validation.d.ts

@@ -0,0 +1,28 @@
+import { type EnhancedPrompt, type GroundingPlan, type PromptEnhancementRequest, type PromptTaskAnalysis } from "./prompt-enhancer.js";
+import { type PromptCandidateScorecard, type PromptCandidateSelection } from "./prompt-enhancer-critic.js";
+export interface ValidationOk<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+export interface ValidationFail {
+    readonly ok: false;
+    readonly errors: readonly string[];
+}
+export type PromptEnhancerValidation<T> = ValidationOk<T> | ValidationFail;
+export declare const PROMPT_REQUEST_TEXT_MAX_CHARS: 100000;
+export declare function validatePromptEnhancementRequest(input: unknown): PromptEnhancerValidation<PromptEnhancementRequest>;
+export declare function validatePromptTaskAnalysis(input: unknown): PromptEnhancerValidation<PromptTaskAnalysis>;
+export declare function validateGroundingPlan(input: unknown): PromptEnhancerValidation<GroundingPlan>;
+export declare function validateEnhancedPrompt(input: unknown): PromptEnhancerValidation<EnhancedPrompt>;
+/**
+ * Validate a `PromptCandidateScorecard`. Pure; returns a discriminated result and never throws.
+ */
+export declare function validatePromptCandidateScorecard(input: unknown): PromptEnhancerValidation<PromptCandidateScorecard>;
+/**
+ * Validate a `PromptCandidateSelection`. Pure; returns a discriminated result and never throws. Checks
+ * structural well-formedness and the cross-field invariants that make the result auditable: the winner
+ * is the first ranked entry, every ranked scorecard is well-formed, and the considered/consumed totals
+ * are non-negative integers within the declared bounds.
+ */
+export declare function validatePromptCandidateSelection(input: unknown): PromptEnhancerValidation<PromptCandidateSelection>;
+//# sourceMappingURL=prompt-enhancer-validation.d.ts.map

package/dist/prompt-enhancer-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-enhancer-validation.d.ts","sourceRoot":"","sources":["../src/prompt-enhancer-validation.ts"],"names":[],"mappings":"AAUA,OAAO,EAEL,KAAK,cAAc,EAEnB,KAAK,aAAa,EAIlB,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,EA4BxB,MAAM,sBAAsB,CAAC;AAS9B,OAAO,EAGL,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAG9B,MAAM,6BAA6B,CAAC;AAOrC,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAAI,YAAY,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC;AAI3E,eAAO,MAAM,6BAA6B,QAAiC,CAAC;AAqK5E,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,OAAO,GACb,wBAAwB,CAAC,wBAAwB,CAAC,CA6BpD;AA0HD,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,GACb,wBAAwB,CAAC,kBAAkB,CAAC,CAoB9C;AAwUD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,wBAAwB,CAAC,aAAa,CAAC,CAK7F;AAsBD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,wBAAwB,CAAC,cAAc,CAAC,CAwB/F;AAuGD;;GAEG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,OAAO,GACb,wBAAwB,CAAC,wBAAwB,CAAC,CAKpD;AA+UD;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,OAAO,GACb,wBAAwB,CAAC,wBAAwB,CAAC,CAoBpD"}