import type { SurveyObservationInput } from "./builder.js";
/**
 * Observation authoring core — CONTEXT.md "Observation" / "Field Observation
 * and Repeated Observation" ("helper shapes for authoring Observations, not
 * separate domain concepts").
 *
 * `buildObservation`/`BuildObservationInput` are the shared authoring
 * primitive: they own the `extraction.target`/`value`/`excerpt` and
 * `claim.fieldOrBehavior`/`value`/`metadata` assembly (including the
 * three-way `claim.metadata` / caller `metadata` / representation-supplied
 * `surveyMetadata` merge below). Consumed by relative import from
 * `field-observation.ts`, `repeated-observation.ts` (via the
 * representation-keyed `buildFieldObservation`/`buildRepeatedObservation`
 * wrappers below), and `source-of-authority-observation.ts`, which calls
 * `buildObservation` directly with its own `surveyMetadata`/`defaultExcerpt`.
 * None of this is re-exported from `src/index.ts`.
 *
 * `ObservationAuthoringInput` is the shared base shape (id/field/value/
 * rawSource/extraction/reviewOutcome/claim/candidate/candidateSet/metadata)
 * common to `BuildObservationInput` and the two public skins' input types
 * (`FieldObservationInput`, `RepeatedObservationInput`); the skins extend it
 * with only their own `representation` literal.
 *
 * `buildFieldObservation`/`buildRepeatedObservation` are the representation-
 * keyed layer above `buildObservation`: each owns the default-excerpt
 * formula and the `surveyMetadata` sub-key (`field` vs `repeated`) for its
 * representation. They do not change `buildObservation`'s own signature or
 * body — `source-of-authority-observation.ts` depends on that staying
 * exactly as-is.
 *
 * `mergeObservationMetadata`/`mergeNestedRecords` are exported as a
 * module-internal seam (like `src/producer-discipline.ts`) purely for direct
 * test import (`tests/observation-helper.test.ts`) — consumed by relative
 * import only, NOT re-exported from `src/index.ts`. Their bodies, including
 * the `mergeNestedRecords` nested-record-vs-scalar asymmetry and the `??`
 * null/undefined coalescing, are unchanged characterization, not a defect.
 */
export interface ObservationAuthoringInput<TValue> {
    id: string;
    field: string;
    value: TValue;
    rawSource: SurveyObservationInput["rawSource"];
    extraction: Omit<SurveyObservationInput["extraction"], "target" | "value" | "excerpt"> & {
        target?: string;
        excerpt?: string | null;
    };
    reviewOutcome?: SurveyObservationInput["reviewOutcome"];
    claim: Omit<SurveyObservationInput["claim"], "fieldOrBehavior" | "value"> & {
        fieldOrBehavior?: string;
    };
    candidate?: SurveyObservationInput["candidate"];
    candidateSet?: SurveyObservationInput["candidateSet"];
    metadata?: Record<string, unknown>;
}
export interface BuildObservationInput<TValue> extends ObservationAuthoringInput<TValue> {
    surveyMetadata: Record<string, unknown>;
    defaultExcerpt: string;
}
export declare function buildObservation<TValue>(input: BuildObservationInput<TValue>): SurveyObservationInput;
export declare function buildFieldObservation<TValue>(input: ObservationAuthoringInput<TValue> & {
    representation?: "scalar";
}): SurveyObservationInput;
export declare function buildRepeatedObservation<TItem>(input: ObservationAuthoringInput<readonly TItem[]> & {
    representation?: "aggregate-array";
}): SurveyObservationInput;
export declare function mergeObservationMetadata(claimMetadata: Record<string, unknown> | undefined, metadata: Record<string, unknown> | undefined, surveyMetadata: Record<string, unknown>): Record<string, unknown>;
export declare function mergeNestedRecords(claimSurvey: Record<string, unknown>, survey: Record<string, unknown>, surveyMetadata: Record<string, unknown>): Record<string, unknown>;