import { LearningOutcome, SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
/**
 * The kind of reinforcement signal a {@link Feedback} row carries.
 *
 * `accept` / `reject` / `correction` / `rating` are human judgements;
 * `outcome` / `metric` are machine-observed autonomous signals.
 */
export type FeedbackSignalType = 'accept' | 'reject' | 'correction' | 'rating' | 'outcome' | 'metric';
/** Whether a signal originated from a person or an autonomous observation. */
export type FeedbackSource = 'human' | 'autonomous';
/** The human-authored signal types. */
export declare const HUMAN_SIGNAL_TYPES: readonly FeedbackSignalType[];
/**
 * Return the natural source for a signal type: the human judgement types are
 * `'human'`; `outcome` / `metric` are `'autonomous'`.
 */
export declare function feedbackSourceFor(signal: FeedbackSignalType): FeedbackSource;
/** Options for {@link Feedback.toLearningOutcome}. */
export interface FeedbackOutcomeOptions {
    /**
     * The neutral point of a `rating` scale. A rating strictly above the neutral
     * reinforces as a success; at or below it decays as a failure. Default `0`
     * (any positive rating is a success), matching {@link LearningOutcome}'s
     * metric convention. Pass e.g. `3` for a 1–5 star scale.
     */
    ratingNeutral?: number;
}
/**
 * A single reinforcement signal against a persona and a learning episode.
 */
export declare class Feedback extends SmrtObject {
    /** Owning tenant (optional — autonomous signals may be tenant-less). */
    tenantId: string | null;
    /** The persona this signal judges. */
    personaId: string;
    /** Canonical agent class the persona configures (denormalised for queries). */
    agentClass: string;
    /**
     * Memory scope the signal reinforces — the partition key routing it to the
     * right {@link LearningMemory} so different personas reinforce independently.
     */
    memoryScope: string;
    /** Learning episode scope this signal pertains to (`LearningEpisode.scope`). */
    scope: string;
    /** Learning episode key this signal pertains to (`LearningEpisode.key`). */
    key: string;
    /** The kind of signal (see {@link FeedbackSignalType}). */
    signalType: FeedbackSignalType;
    /** Whether the signal is human or autonomous. */
    source: FeedbackSource;
    /**
     * Correlation-id back to the thing this signal judges — the AI call,
     * dispatch, or job id. Required so a signal is always traceable to its cause.
     */
    correlationId: string;
    /**
     * What kind of thing {@link correlationId} names (e.g. `'ai_call'`,
     * `'dispatch'`, `'job'`). `null` when the namespace is implicit.
     */
    correlationType: string | null;
    /** Numeric rating for a `rating` signal (scale is caller-defined). */
    rating: number | null;
    /** Observed measurement for a `metric` signal. */
    metric: number | null;
    /** Observed boolean result for an `outcome` signal. */
    success: boolean | null;
    /**
     * Corrected instructions/value for a `correction` signal — the human-supplied
     * replacement that should supersede the strategy that was judged wrong.
     */
    correction: string | null;
    /** Freeform note attached to the signal. */
    comment: string | null;
    /** The user id that authored a human signal (`null` for autonomous). */
    actorId: string | null;
    /** Arbitrary structured metadata, stored as a JSON string. */
    metadata: string;
    /**
     * When this signal was applied to memory as reinforcement. `null` until a
     * reflection pass consumes it. Gates exactly-once reinforcement so a scheduled
     * runner never re-applies the same signal (which would amplify a single
     * accept/reject into many outcomes).
     */
    reinforcedAt: Date | null;
    /** Whether this is a human-authored signal. */
    isHuman(): boolean;
    /** Parse {@link metadata}, tolerating malformed JSON. */
    getMetadata(): Record<string, unknown>;
    /** Replace {@link metadata}. */
    setMetadata(value: Record<string, unknown>): void;
    /** Shallow-merge into {@link metadata}. */
    updateMetadata(patch: Record<string, unknown>): void;
    /**
     * The strategy value a `correction` signal should persist into memory, so a
     * regenerated (corrected) strategy supersedes the one that was judged wrong.
     * `undefined` for non-correction signals (reinforce confidence only).
     */
    getCorrectionValue(): string | undefined;
    /**
     * Map this signal onto a {@link LearningOutcome} for reinforcement, or `null`
     * when the signal carries no reinforcement value:
     *
     * - `accept` → success; `reject` / `correction` → failure.
     * - `outcome` → the recorded boolean `success`.
     * - `metric` → the recorded `metric` (positive → success).
     * - `rating` → `{ metric: rating - ratingNeutral }`.
     */
    toLearningOutcome(options?: FeedbackOutcomeOptions): LearningOutcome | null;
}
/**
 * Collection for {@link Feedback} rows.
 */
export declare class FeedbackCollection extends SmrtCollection<Feedback> {
    static readonly _itemClass: typeof Feedback;
    /** All signals for a persona, newest first. */
    forPersona(personaId: string, options?: {
        limit?: number;
    }): Promise<Feedback[]>;
    /** All signals filed under a memory scope, newest first. */
    forScope(memoryScope: string, options?: {
        limit?: number;
    }): Promise<Feedback[]>;
    /** Every signal correlated to a given AI call / dispatch / job id. */
    byCorrelation(correlationId: string): Promise<Feedback[]>;
}
export default Feedback;
//# sourceMappingURL=feedback.d.ts.map