import type { InstanceGeneralSettings } from "./types/instance.js";
/**
 * Operator-configurable setting defaults.
 *
 * A hosting operator (a managed cloud, an internal shared server) can replace
 * the schema default of selected instance settings by setting the
 * `PAPERCLIP_SETTING_DEFAULTS` environment variable to a JSON object, e.g.
 * `{"feedbackDataSharingPreference":"allowed"}`. The operator value
 * substitutes for the schema default at read time: any field whose effective
 * value is still the schema default resolves to the operator value, while an
 * explicit non-default user choice always wins. The overlay is never
 * persisted, so unsetting the variable restores stock behavior everywhere a
 * user has not chosen otherwise.
 *
 * Parsing is fail-closed for policy content: malformed JSON or an invalid
 * value for a known field is an error (the server refuses to boot), because a
 * silently dropped policy default is worse than a loud failure. Unknown field
 * names are warned about and ignored, so one value can be rolled across a
 * fleet of mixed app versions where older images predate a field.
 *
 * Pairing note: an operator that also wants the control invisible hides it
 * with `PAPERCLIP_HIDDEN_SETTINGS` (see settings-visibility.ts); the two
 * mechanisms are orthogonal.
 */
export declare const SETTING_DEFAULTS_ENV_KEY = "PAPERCLIP_SETTING_DEFAULTS";
/** Instance → General fields whose schema default an operator may replace. */
export declare const DEFAULTABLE_GENERAL_SETTINGS: readonly ["feedbackDataSharingPreference"];
export type DefaultableGeneralSetting = (typeof DEFAULTABLE_GENERAL_SETTINGS)[number];
export type OperatorSettingDefaults = Partial<Pick<InstanceGeneralSettings, DefaultableGeneralSetting>>;
export interface ParsedSettingDefaults {
    /** Validated operator defaults for known fields; null when the var is unset. */
    defaults: OperatorSettingDefaults | null;
    /** Unrecognized field names, for the caller to warn about. */
    unknown: string[];
}
/**
 * Parse a `PAPERCLIP_SETTING_DEFAULTS`-style JSON object.
 *
 * @throws when the JSON is malformed, not an object, or a known field carries
 * an invalid value — policy configuration fails closed.
 */
export declare function parseSettingDefaults(raw: string | undefined): ParsedSettingDefaults;
/**
 * Overlay operator defaults onto normalized general settings at read time.
 *
 * The operator value substitutes for the schema default: a field still at its
 * schema default (absent from storage, or stored equal to it) resolves to the
 * operator value; an explicit non-default choice is untouched. Callers must
 * never persist the result.
 */
export declare function applyOperatorGeneralDefaults(general: InstanceGeneralSettings, defaults: OperatorSettingDefaults | null): InstanceGeneralSettings;
/**
 * Strip overlay echoes from a general-settings write at persist time.
 *
 * A client that writes back the full object it read (a full-GET echo) sends
 * the overlaid operator value for a field the user never chose. Persisting
 * that echo would promote the operator value into an explicit stored choice —
 * sticky across later changes to, or removal of, the environment variable.
 * This maps such a write back to the schema default: a field whose stored
 * value is still the schema default (unchosen) and whose incoming value
 * equals the operator default stays unchosen, keeping the overlay
 * strictly read-time.
 *
 * A user cannot be distinguished from an echo when they deliberately pick the
 * value that already shows as the default, so that pick also stays unchosen —
 * the mirror image of the documented "stored schema default is treated as
 * unchosen" rule, with identical effective behavior. Any other write persists
 * as given: an incoming value that differs from the operator default, or a
 * write over an explicit stored choice.
 */
export declare function stripOperatorGeneralEchoes(stored: InstanceGeneralSettings, next: InstanceGeneralSettings, defaults: OperatorSettingDefaults | null): InstanceGeneralSettings;
//# sourceMappingURL=setting-defaults.d.ts.map