% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sequence-data.R
\name{audit_sequence_data}
\alias{audit_sequence_data}
\title{Audit Long-Format Sequence Data}
\usage{
audit_sequence_data(
  data,
  sequence_id_col,
  order_col,
  state_col,
  duration_col = NULL,
  metadata_cols = NULL,
  expected_states = NULL
)
}
\arguments{
\item{data}{A data frame containing ordered state observations.}

\item{sequence_id_col}{Name of the sequence identifier column.}

\item{order_col}{Name of the numeric sequence-order column.}

\item{state_col}{Name of the categorical state column.}

\item{duration_col}{Optional name of a numeric duration column.}

\item{metadata_cols}{Optional character vector naming columns that should
remain constant within each sequence.}

\item{expected_states}{Optional vector of known or permitted state values.}
}
\value{
A data frame with one row per detected issue and the stable columns
\code{sequence_id}, \code{row}, \code{column}, \code{issue_code}, \code{severity}, \code{value},
\code{message}, and \code{action}. Severity values are \code{error}, \code{review}, and
\code{info}.
}
\description{
Examines a long-format data frame against the neutral \code{gp3sequences}
sequence-data contract without modifying the input.
}
\details{
The audit checks column mappings, empty inputs, missing identifiers,
missing or non-numeric order values, duplicated positions, integer order
gaps, unordered rows, missing states, consecutive repeated states,
single-row sequences, invalid durations, inconsistent metadata, unexpected
states, and unused factor levels.

The function reports structural properties only. It does not infer
psychological, cognitive, emotional, or diagnostic states.
}
\examples{
sequences <- data.frame(
  id = rep(c("s1", "s2"), each = 3L),
  position = rep(1:3, times = 2L),
  state = c("home", "search", "product", "home", "category", "product")
)

audit_sequence_data(
  sequences,
  sequence_id_col = "id",
  order_col = "position",
  state_col = "state"
)

}
