spss

type Case []CaseValue

type CaseValue struct {
	// Num is the numeric reading of the field:
	//
	//   - u4 / u8 / u16 / u32 / u64 — the integer.
	//   - f32 / f64 — the float, widened exactly.
	//   - decimal128 — the value scaled by the field's Scale.
	//   - packed_bool — 0 or 1.
	//   - date — whole epoch DAYS, read unsigned, matching io/export.go.
	//   - datetime — whole epoch SECONDS, read SIGNED, so an instant before
	//     1970 stays before 1970 (the on-wire u64 is two's complement, which
	//     is exactly what encoding.FormatDateTime reinterprets).
	//   - categorical_* — the dictionary ID.
	//   - set_* — the mask, echoed as a float; see Mask.
	Num float64

	// Mask is a set_* column's bitmask at full width. Num echoes it, but a
	// set_u64 mask above 2^53 does not survive the float, and bit 63 of a
	// selection is data.
	Mask uint64

	// Null reports that the cohort's null bitmap marks this field missing for
	// this record. It is authoritative: Num and Mask are zero when it is set,
	// and carry no information.
	Null bool
}

type Category struct {
	// ID is the Pulse dictionary ID: the entry's position, and the
	// value stored on the wire. Two entries MAY share an ID, when two
	// distinct source values collapsed to one dictionary text; that is
	// represented rather than flattened so the ambiguity stays visible.
	ID uint32 `json:"id"`

	// Value is the dictionary entry text at position ID — the SPSS
	// value's canonical rendering, never the label.
	Value string `json:"value"`

	// Numeric reports whether the source variable is numeric, and hence
	// which of Code and Text carries the SPSS value.
	Numeric bool `json:"numeric"`

	// Code is the SPSS numeric value. Non-nil only when Numeric.
	Code *Float `json:"code,omitempty"`

	// Text is the SPSS string value with its declared-width padding
	// removed. Non-nil only when not Numeric. It can differ from Value,
	// which is additionally trimmed of leading space.
	Text *string `json:"text,omitempty"`

	// Label is the record type 3 (or 7/21) value label.
	Label string `json:"label,omitempty"`

	// Labelled reports whether the file DECLARED a label for this
	// value. False for an entry appended from the data section — an
	// unlabelled code is perfectly legal SPSS.
	Labelled bool `json:"labelled"`

	// Observed reports whether at least one case carried this value.
	// False for a declared label nothing used, which still occupies its
	// ID so the file's own code ordering survives.
	Observed bool `json:"observed"`

	// Missing reports that this entry's SPSS value is one of the
	// variable's USER-MISSING codes.
	//
	// It is the categorical arm of the missing-value mapping, and the
	// asymmetry with the numeric arm is deliberate. A numeric variable
	// gets a `<var>_missing` sibling because f64 has no dictionary and
	// the null bitmap is one bit — there is nowhere else for the reason
	// to live. A categorical one already stores the code as a dictionary
	// entry, so the information is present and losslessly addressable;
	// what it lacks is a way to say WHICH entry is a missing code, and
	// that is exactly this flag. Duplicating the code into a sibling
	// would be pure redundancy and would double the schema width of an
	// all-categorical survey file.
	//
	// It is `omitempty`, so a document over a file that declares no
	// categorical user-missing codes is byte-identical to the shape
	// before the flag existed. SidecarFormatVersion is unchanged.
	//
	// Two entries sharing an ID (a value collision) are flagged
	// independently: the flag describes the SOURCE value, and one of a
	// collided pair may be missing-coded while the other is not.
	Missing bool `json:"missing,omitempty"`
}

type CategoryCode struct {
	// Code is the SPSS numeric value, meaningful when the variable is
	// numeric.
	Code float64

	// Text is the SPSS string value, meaningful when the variable is a
	// string. It is UTF-8, as every string in a Pulse cohort is.
	Text string

	// Encoded is Text in the EMITTED FILE's charset — the bytes the data
	// encoder lays into a case, and the bytes the variable's declared width
	// is measured in.
	//
	// It is precomputed rather than encoded per case for two reasons, and
	// only one of them is speed. A dictionary holds every value the column
	// can carry, so encoding it once at plan time means an unencodable
	// character stops the export before a single byte of the file is
	// written, instead of part way through the data section. Nil for an
	// empty value and for a numeric variable.
	Encoded []byte

	// Known reports that the value came from a sidecar's recorded triple
	// rather than from the cohort dictionary text. A synthesised plan sets
	// it false for every entry, which is the writer saying in the plan
	// itself that it did not invent codes.
	Known bool

	// Ambiguous marks an ID two distinct SOURCE values collapsed onto — the
	// PULSE_SPSS_VALUE_COLLISION case. The first is what this entry
	// carries; the collision is flagged rather than hidden, because
	// re-emitting either one is a guess about which row meant which.
	Ambiguous bool
}

type Charset struct {
	// DeclaredName is the record 7/20 name exactly as spelled, "" when
	// the file carries no 7/20.
	DeclaredName string `json:"declared_name,omitempty"`

	// DeclaredCode is the record 7/3 character_code, 0 when absent.
	DeclaredCode int32 `json:"declared_code,omitempty"`

	// Declared reports whether the file said anything at all. A file
	// that did not is being read by assumption, and the write path must
	// know the difference — which "" alone cannot tell it, since a
	// declaration could in principle be blank.
	Declared bool `json:"declared"`

	// Overridden reports that a caller's WithCharset replaced the
	// declaration for DECODING. The declaration above is untouched.
	Overridden bool `json:"overridden"`

	// ResolvedName is the canonical name actually decoded with.
	ResolvedName string `json:"resolved_name"`
}

type ColumnPlan struct {
	// Name is the variable's FINAL name: the record 7/13 long name where
	// one exists, else the record type 2 short name.
	//
	// It is UTF-8, unlike the wire form of the same name that goes into
	// the file. Every other string on this struct describes bytes; this
	// one is what a diagnostic quotes and what a later pass matches a
	// cohort column against, and neither of those wants codepage bytes.
	//
	// This is the name records 7/21 and 7/22 carry. ReadStat — the C reader
	// behind haven, pyreadstat and most of the ecosystem — REFUSES a file
	// whose 7/21 or 7/22 entry names a variable by its short name when a
	// long name exists, so emitting anything else here produces files most
	// tools reject.
	Name string

	// ShortName is the 8-byte record type 2 name, as it was WRITTEN —
	// encoded in the emitted file's charset. Records 7/5, 7/7, 7/14 and
	// 7/19 key by it, and they key by the bytes.
	//
	// In practice it is 7-bit either way: a synthesised short name is
	// folded to ASCII by the name minter and a source's own is ASCII by
	// the format's rules, so the encode is an identity. It is documented
	// as bytes because that is what it is, not because it usually differs.
	ShortName string

	// Index is the 1-based dictionary ELEMENT index of the variable's first
	// element — what the header weight_index, the record type 4 bindings
	// and every other index-bearing field count.
	Index int32

	// Elements is how many 8-byte elements the variable occupies across all
	// of its physical segments.
	Elements int

	// Width is 0 for a numeric variable, else the LOGICAL declared byte
	// width — the total across the physical segments of a very long string,
	// not the 255 a single segment declares.
	Width int

	// Segments are the physical record type 2 variables, head first. Always
	// at least one; more than one only for a string wider than 255 bytes.
	Segments []SegmentPlan

	// PrintFormat and WriteFormat are the emitted output formats.
	//
	// For a MOYR (28) / QYR (29) / WKYR (30) column these are the SOURCE's
	// codes, re-emitted unchanged over an unchanged raw-seconds value. That
	// is the routed export-side answer to E2-S6's deferral: those formats
	// are date-valued in SPSS but not day-resolution, so the import kept
	// them as f64 raw seconds rather than truncating to a `date`. Nothing
	// was converted on the way in, so nothing needs converting on the way
	// out — and the format code is the ONLY thing that makes those seconds
	// render as "JAN 2024" instead of 1.4e10. Downgrading them to F would
	// lose the meaning of a column whose values are otherwise perfect.
	PrintFormat Format
	WriteFormat Format

	// Encoding is how a cohort value becomes this variable's elements.
	Encoding ValueEncoding

	// Field is the index into DictionaryRequest.Schema.Fields of the cohort
	// column this variable is written from, or -1 when nothing backs it.
	Field int

	// FieldName is the cohort field's name, kept beside Field so a
	// diagnostic does not have to reach back into the schema.
	FieldName string

	// FieldType is the cohort field's `.pulse` type.
	FieldType encoding.FieldType

	// Categories maps cohort dictionary ID to SPSS value, for
	// EncodeCategoricalCode and EncodeText. Indexed by ID; an ID past the
	// end has no recorded value.
	Categories []CategoryCode

	// SetBit is the source `set_*` mask bit this indicator variable stands
	// for, or -1 when the variable is not a set member.
	SetBit int

	// CountedValue is the numeric value meaning "selected", for
	// EncodeSetMember.
	CountedValue float64

	// MissingField is the cohort field index of the `<var>_missing` reason
	// sibling this variable folds back from, or -1 when it has none.
	//
	// It is the E5-S5 fold: the sibling emits no SPSS variable of its own,
	// and what it does instead is decide what THIS variable writes wherever
	// the cohort holds a null — the recorded user-missing code rather than
	// the system-missing sentinel. Only a plain numeric variable can carry
	// one; a categorical's missing codes never left its dictionary.
	MissingField int

	// MissingCodes maps that sibling's dictionary ID to the SPSS value to
	// write, indexed by ID. Nil when MissingField is -1.
	//
	// It comes from the sidecar's recorded [Derived.Reasons] and is never
	// re-derived from the missing specification plus the value labels: a
	// second derivation that disagreed with the import's would produce a
	// file that looks authoritative and names the wrong missing state.
	MissingCodes []MissingCode
}

type DataEncoder struct {
	// contains filtered or unexported fields
}

type Derived struct {
	// Name is the derived Pulse field name.
	Name string `json:"name"`

	// Kind says what derived it. E4-S2/S3/S4 own the vocabulary; the
	// values this package emits are named constants —
	// [DerivedKindNumericMissing] and [DerivedKindMultipleDichotomy].
	Kind string `json:"kind"`

	// SetName is the SPSS multiple-response set this column was derived
	// from, INCLUDING its leading '$'. Non-empty only for
	// [DerivedKindMultipleDichotomy].
	//
	// It is recorded rather than reconstructed from Name because the
	// derivation drops the '$' — a leading sigil is not a legal
	// expr-lang identifier, so a field named "$media" would be
	// unreachable from ATTR_FORMULA — and because this is the key into
	// the payload's MultipleResponseSets block, where the counted value
	// and the set label live.
	//
	// Additive and `omitempty`: a document over a file with no derivable
	// response set is byte-identical to the shape before the slot
	// existed, and SidecarFormatVersion is unchanged.
	SetName string `json:"set_name,omitempty"`

	// Sources names the source variables it was derived FROM, by Pulse
	// field name.
	//
	// For [DerivedKindMultipleDichotomy] the ORDER is load-bearing: it is
	// bit order, so bit i of the mask and dictionary entry i are
	// Sources[i]. For [DerivedKindNumericMissing] it is the single source
	// variable.
	Sources []string `json:"sources,omitempty"`

	// Position is the 0-based column position in the cohort. Derived
	// columns are INTERLEAVED with the real ones — a `<var>_missing`
	// sibling sits immediately after the variable it belongs to — so
	// neither this slice nor Variables can be read as a contiguous run,
	// and a consumer reconstructing the source's own column order needs
	// both sorted together.
	Position int `json:"position"`

	// Reasons is the derived column's dictionary, one entry per ID, for
	// a `<var>_missing` sibling. It is what makes the column FOLDABLE:
	// an export re-emitting the source variable reads the sibling's ID,
	// finds the entry, and writes back the system-missing sentinel or
	// the original SPSS code. Without it the fold would have to
	// re-derive the mapping from the source variable's missing
	// specification and value labels, which is exactly the guess this
	// document exists to remove.
	//
	// Empty for a derived kind that is not a reason column.
	Reasons []DerivedReason `json:"reasons,omitempty"`
}

type DerivedFold int

type DerivedReason struct {
	// ID is the Pulse dictionary ID, which is the entry's position and
	// the value stored on the wire.
	ID uint32 `json:"id"`

	// Reason is the dictionary entry text.
	Reason string `json:"reason"`

	// Sysmis marks the one entry standing for the system-missing
	// sentinel rather than for a user-missing code. It always occupies
	// ID 0. Code is meaningless when it is set.
	Sysmis bool `json:"sysmis,omitempty"`

	// Code is the SPSS numeric value this reason stands for, nil for
	// the Sysmis entry.
	Code *Float `json:"code,omitempty"`

	// Label is the value label the file declared for Code, "" when it
	// declared none. It is recorded even where Reason fell back to the
	// numeric code because the label collided with another reason, so a
	// consumer can still see what the file said.
	Label string `json:"label,omitempty"`

	// Declared reports that Code appears in the variable's
	// missing-value SPECIFICATION as a discrete value. False for a
	// value only a RANGE plus the data section put here: a range is not
	// a finite vocabulary, so its members are collected as observed
	// rather than enumerated.
	Declared bool `json:"declared"`

	// Observed reports that at least one case carried this state. False
	// for a declared code nothing used, which still occupies its ID so
	// the specification's own order survives.
	Observed bool `json:"observed"`
}

type DictionaryPlan struct {
	// Bytes are the dictionary section: the file header through the record
	// type 999 terminator, inclusive. The data section starts at
	// len(Bytes).
	Bytes []byte

	// ByteOrder is the order every multi-byte field in Bytes was written
	// in, and the order the data section must be written in.
	//
	// Always little-endian. Byte order carries no information about the
	// DATA — the values are identical either way — so re-emitting a
	// big-endian source's order would buy nothing and cost compatibility
	// with the many tools that only ever meet little-endian files.
	ByteOrder binary.ByteOrder

	// Compression is the header compression flag that was written.
	Compression int32

	// Bias is the header compression bias that was written.
	Bias float64

	// Sysmis is the system-missing sentinel the data section must use.
	//
	// It is resolved by READING Bytes back, not by reporting what the
	// front-end intended, and that is the contract: a `.sav` may declare its
	// own sentinel in record 7/4, a conforming reader ADOPTS a coherent
	// declaration (see applyMachineFloat), and a sidecar-driven dictionary
	// re-emits the source's 7/4 verbatim. A plan that reported the spec
	// default over a file declaring something else would hand a data encoder
	// a value that reads back as ORDINARY DATA in every null it was written
	// into. Deriving it from the emitted bytes makes the plan and any reader
	// of the file agree by construction rather than by two implementations
	// of one rule staying in step.
	Sysmis float64

	// ElementCount is the 8-byte elements per case: the header's
	// nominal_case_size, and the stride the data section must produce.
	ElementCount int32

	// CaseCount is the case count that was written, -1 for unknown.
	CaseCount int64

	// CaseCountOffset is the byte offset within Bytes of the header's
	// int32 ncases field, so a streaming encoder can patch it.
	CaseCountOffset int

	// CaseCount64Offset is the byte offset of the record 7/16 int64 case
	// count, or -1 when no 7/16 was emitted (which is the case exactly when
	// CaseCount is -1). Patching one and not the other leaves a file whose
	// two case counts disagree.
	CaseCount64Offset int

	// Columns are the emitted variables in element order.
	Columns []ColumnPlan

	// UnboundFields lists the cohort schema field indices no emitted
	// variable is written from, in schema order.
	//
	// For a sidecar-driven plan these are the DERIVED columns — the
	// `<var>_missing` reason siblings and the multiple-dichotomy `set_*`
	// convenience columns — which the document keeps in its own Derived
	// registry rather than in Variables. E5-S5 cross-checks this list
	// against that registry: a field that is unbound and NOT derived is a
	// column about to be silently dropped, which is the one outcome the
	// fold must refuse.
	UnboundFields []int

	// Status is the sidecar resolution the plan was built under.
	Status SidecarStatus

	// Synthesised reports that the dictionary was built from the `.pulse`
	// schema alone.
	Synthesised bool

	// Renames are the variable names [WriterOptions.SanitizeNames]
	// rewrote, in emission order. Nil when the flag is unset, when the
	// plan came from a sidecar, and when every cohort name was already a
	// legal SPSS name — so an export that renamed nothing is
	// indistinguishable from one that could not have.
	//
	// The same set rides Warnings as a single
	// PULSE_SPSS_NAME_SANITIZED. It is repeated here in typed form
	// because a caller that wants to map emitted variables back to
	// cohort fields should not have to parse it out of a details map.
	Renames []NameRename

	// Warnings are the diagnostics to surface, the sidecar resolution's own
	// warning first when it raised one.
	Warnings []*errors.CodedError
}

type DictionaryRequest struct {
	// Schema is the `.pulse` cohort schema, as delivered through
	// pio.SchemaAwareWriter.SetPulseSchema. Required.
	Schema *encoding.Schema

	// Sidecar is [LoadSidecar]'s resolution. A nil resolution, or one whose
	// [SidecarResolution.Synthesise] reports true, selects the synthesised
	// default dictionary.
	//
	// Staleness is NOT re-checked here. LoadSidecar returns a resolution
	// only when the export may proceed, so a resolution in hand is already
	// the permission to use it.
	Sidecar *SidecarResolution

	// Cases is the number of cases the data section will carry, or -1 when
	// the writer does not yet know.
	//
	// -1 is a legal header value meaning "unknown" and every reader handles
	// it, so a streaming encoder may emit the dictionary first and either
	// leave it at -1 or patch [DictionaryPlan.CaseCountOffset] (and
	// [DictionaryPlan.CaseCount64Offset]) once the last case is written.
	Cases int64

	// Compression is the header compression flag the data section will be
	// written under: 0 for uncompressed, 1 for SPSS bytecode. ZSAV (2) is
	// rejected — emission of it is out of scope for this effort.
	Compression int32

	// Options are the caller's knobs.
	Options WriterOptions
}

type Document struct {
	// FormatVersion is SidecarFormatVersion at write time.
	FormatVersion int `json:"format_version"`

	// Kind is SidecarKind.
	Kind string `json:"kind"`

	// Fingerprint binds the document to the cohort it describes.
	Fingerprint Fingerprint `json:"fingerprint"`

	// Payload is the self-contained metadata.
	Payload Payload `json:"payload"`
}

type Fingerprint struct {
	// SHA256 is the 32-byte SHA-256 digest of the cohort's full bytes,
	// hex-encoded to 64 characters. Decode with [Fingerprint.Digest].
	SHA256 string `json:"sha256"`

	// SourceSize is the cohort's byte length at write time.
	SourceSize uint64 `json:"source_size"`

	// SourceModTime is the cohort's modification time at write time, as
	// Unix nanoseconds.
	SourceModTime int64 `json:"source_mod_time"`
}

type Float float64

type Format struct {
	// Code is the SPSS format type code: 1 = A, 5 = F, 20 = DATE, ...
	Code uint8 `json:"code"`

	// Width is the field width in characters.
	Width int `json:"width"`

	// Decimals is the number of decimal places.
	Decimals int `json:"decimals"`
}

type MRSet struct {
	// Name is the set name, including its leading '$'.
	Name string `json:"name"`

	// Kind is [MRSetKindDichotomy] or [MRSetKindCategory].
	Kind string `json:"kind"`

	// Label is the set label, possibly empty.
	Label string `json:"label,omitempty"`

	// Subtype is the extension subtype the definition came from: 5, 7
	// or 19.
	Subtype int32 `json:"subtype"`

	// Variables names the member variables by SHORT name, in file
	// order — the name the record itself carries, and what a write path
	// re-emits verbatim.
	//
	// ORDER IS LOAD-BEARING and duplicates are NOT collapsed. For a
	// multiple-category set the member order is the answer order — "first
	// choice, second choice, third choice" — and two slots may
	// legitimately hold the same code, which is exactly why an MC set is
	// not a Pulse `set_*`: a bitmask is unordered and idempotent, so
	// collapsing one would lose both facts.
	Variables []string `json:"variables"`

	// Fields resolves each entry of Variables to its PULSE FIELD NAME,
	// index for index, so a consumer never has to re-derive the mapping
	// the import already performed. An entry is "" for a member no
	// record type 2 declares, which is the one case where the set names
	// a variable this cohort has no column for.
	//
	// It exists because Variables holds SHORT names and the cohort holds
	// long ones: matching them back up means a case-insensitive walk of
	// Variables[].ShortName, and a set whose members were renamed,
	// truncated or long-name-mapped is precisely where that walk goes
	// wrong. Same slot-pair precedent as Variable.ShortName / .Name.
	//
	// Present whenever Variables is; len(Fields) == len(Variables)
	// always, including the duplicate entries an MC set may carry.
	// Additive and `omitempty` — a SidecarFormatVersion 1 document
	// written before this slot existed simply has no `fields` key.
	Fields []string `json:"fields,omitempty"`

	// CountedValue is the value meaning "selected", held verbatim as
	// the text the record carried; the wire form does not say whether
	// it is a number or a string. Non-nil only for a dichotomy set.
	CountedValue *string `json:"counted_value,omitempty"`

	// LabelFromVariableLabel is the subtype 19 'E' form's "11" label
	// source: the label comes from the first member's variable label.
	LabelFromVariableLabel bool `json:"label_from_variable_label,omitempty"`

	// Extended records the 'E' type code, which only subtype 19 writes.
	Extended bool `json:"extended,omitempty"`
}

type MachineFloat struct {
	Sysmis  Float `json:"sysmis"`
	Highest Float `json:"highest"`
	Lowest  Float `json:"lowest"`
}

type Missing struct {
	// Code is the raw record type 2 n_missing_values field.
	Code int32 `json:"code"`

	// Kind is the shape discriminant, per the table above.
	Kind string `json:"kind"`

	// Range is the lo..hi bound, non-nil for "range" and
	// "range_plus_discrete".
	Range *MissingRange `json:"range,omitempty"`

	// Discrete are the discrete numeric missing codes, in file order.
	// For "range_plus_discrete" there is exactly one.
	Discrete []Float `json:"discrete,omitempty"`

	// DiscreteText are the discrete STRING missing values, trimmed to
	// the declared width exactly as a datum of the same variable is.
	DiscreteText []string `json:"discrete_text,omitempty"`

	// Raw are the abs(Code) eight-byte slots verbatim, base64-encoded
	// by encoding/json. Authoritative: the decoded fields above are a
	// projection of these bytes, never a replacement.
	Raw [][]byte `json:"raw"`
}

type MissingCode struct {
	// Known reports that the ID has a recorded reason at all. A false entry
	// is an ID the registry never described, which the encoder refuses
	// rather than writing a value for.
	Known bool

	// Sysmis marks the reason standing for the system-missing sentinel
	// rather than for a user-missing code. Code is meaningless when it is
	// set.
	Sysmis bool

	// Code is the SPSS numeric value to write. It is the SOURCE's own
	// double, in the source's own units: for a `date` or `datetime`
	// variable that is raw SPSS seconds, not epoch days, because the import
	// never converted a missing code and so the export must not either.
	Code float64

	// Reason is the dictionary entry text the cohort stores, carried for
	// diagnostics only.
	Reason string
}

type MissingMode int

type MissingRange struct {
	Low  Float `json:"low"`
	High Float `json:"high"`
}

type NameRename struct {
	// Field is the cohort field the variable is written from. Empty for a
	// name no single column owns, which today is only a multiple-response
	// set name.
	Field string `json:"field"`

	// From is the name the cohort asked for and a `.sav` cannot carry.
	From string `json:"from"`

	// Name is the legal SPSS name that was emitted instead.
	Name string `json:"name"`
}

type Option func(*Reader)

type Payload struct {
	// Source is the file-header and geometry metadata.
	Source Source `json:"source"`

	// Charset is the file's own encoding declaration.
	Charset Charset `json:"charset"`

	// Weight is the weighting variable, nil for an unweighted file.
	Weight *Weight `json:"weight,omitempty"`

	// Documents are the record type 6 lines in file order, each still
	// the full fixed-width 80-byte field. Untrimmed on purpose: which
	// trailing spaces are padding and which are the author's is not
	// knowable, and guessing would not round-trip.
	Documents []string `json:"documents,omitempty"`

	// ProductInfo is record 7/10, extra product identification.
	ProductInfo *RawText `json:"product_info,omitempty"`

	// FileAttributes is record 7/17: attributes of the FILE.
	// Deliberately distinct from VariableAttributes.
	FileAttributes *RawText `json:"file_attributes,omitempty"`

	// VariableAttributes is record 7/18: attributes of VARIABLES.
	// Deliberately distinct from FileAttributes.
	VariableAttributes *RawText `json:"variable_attributes,omitempty"`

	// MultipleResponseSets are the records 7/5, 7/7 and 7/19 set
	// definitions. E4-S5 owns what is DONE with them; they are recorded
	// here regardless, because an export has to write them back.
	MultipleResponseSets []MRSet `json:"multiple_response_sets,omitempty"`

	// VariableSets are the record 7/5 display groupings. They ride the
	// same record as multiple-response sets and are NOT response sets;
	// they have no Pulse home at all and are sidecar-only.
	VariableSets []VarSet `json:"variable_sets,omitempty"`

	// VeryLongStrings are the record 7/14 declarations: one
	// (head short name, logical byte width) pair per very long string.
	// The per-variable physical segmentation is on Variable.VeryLongString.
	VeryLongStrings []VLSDeclaration `json:"very_long_strings,omitempty"`

	// Variables are the columns in cohort order, one per Pulse field.
	Variables []Variable `json:"variables"`

	// Derived is the registry of columns this import SYNTHESISED rather
	// than read: the `<var>_missing` reason siblings (kind
	// [DerivedKindNumericMissing]) and the multiple-dichotomy `set_*`
	// convenience columns (kind [DerivedKindMultipleDichotomy]). An
	// export drops or consumes them and reconstructs the source from the
	// real columns, so it needs to tell "column absent from Variables"
	// from "column absent from the source" without pattern-matching on
	// names. See derived.go for the closed kind vocabulary and the fold
	// action each one prescribes.
	//
	// Derived columns are INTERLEAVED with the real ones, not appended:
	// a reason sibling sits immediately after its source variable, and a
	// set column immediately after the LAST of its constituents (a
	// summary must not precede its parts). Position on each entry is what
	// says where; constituents need not be contiguous.
	//
	// NOT `omitempty`, deliberately. An import that derived nothing
	// writes an EMPTY ARRAY, because "this cohort has no derived columns"
	// and "this document cannot tell me" are different answers and an
	// absent key collapses them — the second is what an export must
	// refuse on, and the first is the overwhelmingly common case it must
	// proceed on.
	//
	// Additive: entries may gain fields without a SidecarFormatVersion
	// bump, which is how Reasons arrived after the slot was reserved.
	Derived []Derived `json:"derived"`
}

type RawText struct {
	// Subtype is the record type 7 subtype: 10, 17 or 18.
	Subtype int32 `json:"subtype"`

	// Raw is the payload bytes, base64-encoded by encoding/json.
	Raw []byte `json:"raw"`

	// Text is the decoded payload, omitted when undecodable.
	Text string `json:"text,omitempty"`
}

type Reader struct {
	// contains filtered or unexported fields
}

type SegmentPlan struct {
	// Name is the segment's own 8-byte short name.
	Name string

	// Width is the segment's DECLARED byte width.
	Width int

	// Content is how many bytes of the LOGICAL value the segment carries.
	// It is not Width: a non-final very-long-string segment declares 255
	// and carries 252.
	Content int

	// Elements is how many 8-byte elements the segment occupies.
	Elements int

	// Index is the 1-based dictionary element index of the segment's first
	// element.
	Index int32
}

type SidecarResolution struct {
	// Cohort is the `.pulse` path the resolution is about.
	Cohort string

	// Path is the sidecar path that was consulted, derived by
	// [SidecarPath]. Reported for every status, including
	// SidecarStatusAbsent, where it is the path that was looked for.
	Path string

	// Status is the terminal state.
	Status SidecarStatus

	// Document is the validated, normalised sidecar. Non-nil if and
	// only if Status is SidecarStatusPresent — see [SidecarResolution.Synthesise].
	Document *Document

	// Warning is the coded diagnostic this resolution raised, nil for
	// SidecarStatusPresent. It is a *errors.CodedError so it can be
	// appended straight onto the warning slice the io/ reports carry
	// (ImportReport.SourceWarnings and its siblings), which is the
	// established channel for a non-fatal PULSE_SPSS_* diagnostic.
	Warning *errors.CodedError
}

type SidecarStatus int

type Source struct {
	// Magic is "$FL2" (a plain system file) or "$FL3" (ZSAV).
	Magic string `json:"magic"`

	// ProductName is the 60-byte header prod_name field.
	ProductName string `json:"product_name"`

	// FileLabel is the 64-byte header file label.
	FileLabel string `json:"file_label,omitempty"`

	// CreationDate is the header "dd mmm yy" field.
	CreationDate string `json:"creation_date,omitempty"`

	// CreationTime is the header "hh:mm:ss" field.
	CreationTime string `json:"creation_time,omitempty"`

	// ByteOrder is [SourceByteOrderLittle] or [SourceByteOrderBig].
	//
	// It describes the SOURCE file's bytes, which matters on the write
	// side for one thing beyond provenance: [Missing.Raw] holds flt64
	// slots verbatim, so a big-endian source's slots have to be reversed
	// before they are re-emitted into the always-little-endian file this
	// package writes.
	ByteOrder string `json:"byte_order"`

	// LayoutCode is the header layout probe (2 or 3) the byte order was
	// derived from.
	LayoutCode int32 `json:"layout_code"`

	// Compression is "none", "bytecode" or "zsav".
	Compression string `json:"compression"`

	// CompressionBias is the header bias field, normally 100. It is
	// written even for an uncompressed file, so it is recorded
	// unconditionally.
	CompressionBias Float `json:"compression_bias"`

	// NominalCaseSize is the header's CLAIM about 8-byte elements per
	// case. It is a claim, not a fact.
	NominalCaseSize int32 `json:"nominal_case_size"`

	// ElementCount is the AUTHORITATIVE elements-per-case, counted from
	// the record type 2 stream. Both are kept so a consumer can see a
	// disagreement rather than inherit a resolution.
	ElementCount int32 `json:"element_count"`

	// CaseCount is the number of cases the reader actually walked.
	CaseCount int64 `json:"case_count"`

	// DeclaredCaseCount is what the file claimed: the record 7/16
	// 64-bit count where present, else the header's int32, which is -1
	// when the writer did not know.
	DeclaredCaseCount int64 `json:"declared_case_count"`

	// Sysmis is the system-missing sentinel in force, which is the spec
	// default (-DBL_MAX) unless record 7/4 declared a coherent one.
	Sysmis Float `json:"sysmis"`

	// MachineFloat is the record 7/4 sentinel triple, nil when the file
	// carries no 7/4 — the common case.
	MachineFloat *MachineFloat `json:"machine_float,omitempty"`
}

type VLSDeclaration struct {
	// Name is the HEAD physical variable's short name; 7/14 keys by
	// short name.
	Name string `json:"name"`

	// Width is the LOGICAL byte width, 256..32767.
	Width int `json:"width"`
}

type VLSLayout struct {
	// Width is the LOGICAL byte width and the sum of every segment's
	// Content.
	Width int `json:"width"`

	// Segments are the physical variables in file order, head first.
	// Always at least two.
	Segments []VLSSegment `json:"segments"`
}

type VLSSegment struct {
	// Name is the physical variable's record type 2 short name.
	Name string `json:"name"`

	// Width is the physical variable's DECLARED byte width.
	Width int `json:"width"`

	// Content is how many bytes of the LOGICAL value this segment
	// carries. NOT Width: a non-final segment's last three declared
	// bytes are unused padding.
	Content int `json:"content"`

	// Elements is how many 8-byte data elements the physical variable
	// occupies.
	Elements int `json:"elements"`
}

type ValueEncoding int

type VarSet struct {
	Name      string   `json:"name"`
	Variables []string `json:"variables"`
}

type Variable struct {
	// Name is the Pulse field name: the record 7/13 long name where the
	// file declares one, else the short name.
	Name string `json:"name"`

	// ShortName is the ORIGINAL 8-byte record type 2 name. Retained
	// because the record 7/13 mapping is short -> long and an export
	// has to write the short name back; and because records 7/5, 7/7,
	// 7/14 and 7/19 all key by it.
	ShortName string `json:"short_name"`

	// LongName is the record 7/13 declaration, "" when the file
	// declares none. Held apart from Name so "the file declared a long
	// name equal to the short one" stays distinguishable from "the file
	// declared none".
	LongName string `json:"long_name,omitempty"`

	// Index is the 1-based dictionary ELEMENT index of the variable's
	// first element — what every index-bearing field in the file counts.
	Index int32 `json:"index"`

	// Position is the 0-based column position in the cohort.
	Position int `json:"position"`

	// Label is the SPSS variable label, which also became the Pulse
	// field description.
	Label string `json:"label,omitempty"`

	// HasLabel distinguishes "carried an empty label" from "carried
	// none", which the record type 2 flag really does distinguish.
	HasLabel bool `json:"has_label"`

	// TypeCode is the raw record type 2 `type` field: 0 for numeric,
	// else the declared byte width.
	TypeCode int32 `json:"type_code"`

	// DeclaredWidth is the declared width in BYTES — never runes — 0
	// for a numeric. SPSS space-pads to it and this reader trims, so
	// this is what an export re-pads to. For a very long string it is
	// the LOGICAL total, not the 255 a single segment declares.
	DeclaredWidth int `json:"declared_width"`

	// Segments is how many 8-byte elements the variable occupies.
	Segments int `json:"segments"`

	// PrintFormat and WriteFormat are the SPSS output formats.
	PrintFormat Format `json:"print_format"`
	WriteFormat Format `json:"write_format"`

	// Measure is the record 7/11 level: "unset", "nominal", "ordinal"
	// or "scale". It informs Pulse smart defaults on import but is not
	// derivable back from a Pulse schema, so it is stored regardless.
	Measure string `json:"measure"`

	// Alignment is the record 7/11 alignment: "left", "right" or
	// "center". 7/11 has no unset alignment.
	Alignment string `json:"alignment"`

	// DisplayWidth is the record 7/11 display column width. Nil for the
	// older two-int32-per-variable form of the record, which omits it.
	DisplayWidth *int32 `json:"display_width,omitempty"`

	// HasDisplayParams reports whether a record 7/11 was applied at
	// all, so an absent record stays distinguishable from one declaring
	// every field unset.
	HasDisplayParams bool `json:"has_display_params"`

	// PulseType is the resolved .pulse field type, as
	// encoding.FieldType.String().
	PulseType string `json:"pulse_type"`

	// Kind is the mapping family: "numeric", "duration", "date",
	// "datetime" or "categorical". A duration is f64 exactly as a
	// numeric is; the distinction is recorded so a TIME / DTIME column
	// is never mistaken for an instant.
	Kind string `json:"kind"`

	// Nullable is a fact, not a sample: the whole data section was
	// scanned.
	Nullable bool `json:"nullable"`

	// DefaultAggregation and DefaultGrouper are the smart-default hints
	// the measure level implied. Empty means no default applies.
	DefaultAggregation string `json:"default_aggregation,omitempty"`
	DefaultGrouper     string `json:"default_grouper,omitempty"`

	// Missing is the missing-value specification, nil when the variable
	// declares none.
	Missing *Missing `json:"missing,omitempty"`

	// Categories is the code <-> label <-> ID triple, one per
	// dictionary entry, in ID order. Empty for a non-categorical column.
	Categories []Category `json:"categories,omitempty"`

	// VeryLongString is the record 7/14 physical segmentation, non-nil
	// only for a logical string wider than 255 bytes.
	VeryLongString *VLSLayout `json:"very_long_string,omitempty"`
}

type Weight struct {
	// Index is the 1-based dictionary ELEMENT index the header stores.
	Index int32 `json:"index"`

	// Variable is the Pulse field name it resolves to, "" when the
	// index names no variable's first element.
	Variable string `json:"variable,omitempty"`
}

type Writer struct {
	// contains filtered or unexported fields
}

type WriterOptions struct {
	// IgnoreSidecar suppresses the metadata sidecar entirely: the file
	// is not read even if it is present and healthy, and the export
	// proceeds on a dictionary synthesised from the `.pulse` schema
	// alone, exactly as it would for a cohort that never had one.
	//
	// It suppresses the READ rather than only the staleness verdict, and
	// that is the deliberate reading of the flag's name. Two
	// consequences follow, both wanted. Output no longer depends on the
	// state of a file the caller has explicitly opted out of — a flag
	// whose effect flipped with an mtime would be a trap. And an
	// UNREADABLE sidecar cannot block the export either, so the flag is
	// a genuine escape hatch rather than one that works only for the
	// failure mode it was named after.
	//
	// It never causes a stale dictionary to be applied. There is no
	// option that does; the choice is between the recorded metadata and
	// the synthesised default, never between fresh and stale.
	IgnoreSidecar bool

	// Uncompressed writes the data section as flat 8-byte elements
	// instead of SPSS's bytecode compression.
	//
	// The DEFAULT is compressed, because that is what SPSS's own SAVE
	// writes: almost every `.sav` in the world is bytecode-compressed,
	// so it is the path every tool that opens one exercises daily. The
	// two encodings are losslessly equivalent — identical case data,
	// re-importing to identical cohorts — so this knob trades size for
	// a data section a human can read in a hex dump, and nothing else.
	//
	// It does NOT select ZSAV. ZSAV emission is not implemented; asking
	// for it is PULSE_SPSS_COMPRESSION_UNSUPPORTED.
	Uncompressed bool

	// Charset overrides the character encoding the emitted file's strings
	// are written in, and the record 7/20 declaration that names it.
	//
	// The DEFAULT — an empty string — writes the file in the charset its
	// SOURCE declared, in the source's own spelling, which is the whole
	// point of the write-side transcode: emitting UTF-8 into a file whose
	// header says windows-1252 corrupts every non-ASCII label. A cohort
	// with no SPSS provenance, or one whose source declared no encoding,
	// gets UTF-8.
	//
	// Setting it is the answer to two situations the default cannot serve.
	// A cohort has been edited since it was imported and now holds text the
	// source's legacy codepage cannot express, which is otherwise a hard
	// PULSE_SPSS_CHARSET_UNENCODABLE — writing UTF-8 keeps the text, and
	// modern SPSS, PSPP, haven and pyreadstat all read a UTF-8 `.sav`. Or
	// the source MISLABELLED itself and was read through
	// spss.WithCharset: that override changes decoding only and is
	// deliberately not consulted here, because it says nothing about what
	// the new file should declare, so a caller who wants it honoured on
	// the way out states it again here.
	//
	// The spelling is quoted verbatim into record 7/20, so "cp1252" is
	// declared as "cp1252". A name this package cannot write in is
	// PULSE_SPSS_CHARSET_UNSUPPORTED, never a silent fall back to UTF-8.
	Charset string

	// SanitizeNames rewrites cohort field names that cannot be SPSS
	// variable names, instead of refusing the export.
	//
	// The DEFAULT is the refusal, and that is not timidity. A `.pulse`
	// field name is any UTF-8 string; an SPSS variable name is a
	// constrained identifier, and the three ways an illegal one fails
	// (see dict_names.go) all produce a well-formed file that says
	// something other than what the cohort said. Renaming a caller's
	// columns behind their back to avoid that is the same class of quiet
	// substitution, one step further downstream.
	//
	// But the refusal is a usability cliff on the SYNTHESISED path, where
	// the names came from a CSV header rather than from SPSS: a space, a
	// bracket, a hyphen or a leading digit is ordinary there, and
	// `pulse convert data.csv out.sav` on a column called
	// "household income (gross)" would otherwise have no way through at
	// all. This flag is that way through, and it pays for itself by being
	// LOUD: every rename is reported as a PULSE_SPSS_NAME_SANITIZED
	// warning carrying the full field -> name list, so nothing about the
	// emitted file is a surprise. Renames are deterministic — the same
	// cohort always yields the same names — and collision-safe against
	// both other renames and the names that were already legal.
	//
	// It has no effect on the SIDECAR-driven path. Those names came from
	// a `.sav` and are legal by construction, so there is nothing to
	// rewrite, and rewriting a source's own names would be the fidelity
	// loss the whole write side exists to avoid.
	SanitizeNames bool
}