errors

Documentation

Overview

Package errors provides structured error codes and error handling for pulse.

Index

• func AllDomains() []string
• func Domain(c Code) string
• func HasCode(err error, code Code) bool
• func SortedCodeNames() []string
• type Code
  • func AllCodes() []Code
  • func ParseCode(s string) (Code, bool)
  • func (c Code) Fixup(req any) []Fixup
• type CodedError
  • func NewCodedError(code Code, message string) *CodedError
  • func NewCodedErrorWithDetails(code Code, message string, details map[string]any) *CodedError
  • func WrapCodedError(err error, code Code, message string) *CodedError
  • func (e *CodedError) Error() string
  • func (e *CodedError) MarshalJSON() ([]byte, error)
  • func (e *CodedError) Unwrap() error
• type Fixup
• type FixupAction
• type LookupResult
  • func ByDomain(domain string) []LookupResult
  • func Lookup(code string) (LookupResult, bool)
  • func Search(query string) []LookupResult
• type Metadata
  • func MetadataFor(c Code) (Metadata, bool)

Functions

func AllDomains

func AllDomains() []string

AllDomains returns every distinct domain prefix observed in AllCodes(), sorted alphabetically.

func Domain

func Domain(c Code) string

Domain returns the prefix segment of a Code (the substring before the first underscore). Returns the whole string when no underscore is present.

func HasCode

func HasCode(err error, code Code) bool

HasCode traverses the error chain to determine if any CodedError in the chain carries the specified code. Returns false if err is nil or no CodedError in the chain matches.

func SortedCodeNames

func SortedCodeNames() []string

SortedCodeNames returns every registered code as a string slice, alphabetized. Used by the slim manifest's error_codes field.

Types

type Code

type Code string

Code is a typed string representing categorical error codes. Each code identifies a specific error category within a domain.

const (
	// ENCODING_INVALID indicates invalid data format or structure.
	ENCODING_INVALID Code = "ENCODING_INVALID"

	// ENCODING_IO indicates I/O failures during read/write operations.
	ENCODING_IO Code = "ENCODING_IO"

	// ENCODING_TYPE_MISMATCH indicates type conversion or casting errors.
	ENCODING_TYPE_MISMATCH Code = "ENCODING_TYPE_MISMATCH"

	// ENCODING_INTERNAL indicates unexpected errors in encoding layer.
	ENCODING_INTERNAL Code = "ENCODING_INTERNAL"
)

ENCODING domain - Binary format and data encoding operations

const (
	// PROCESSING_CONFIG indicates component configuration errors.
	PROCESSING_CONFIG Code = "PROCESSING_CONFIG"

	// PROCESSING_STATE indicates context state management errors.
	PROCESSING_STATE Code = "PROCESSING_STATE"

	// PROCESSING_RUNTIME indicates runtime execution errors.
	PROCESSING_RUNTIME Code = "PROCESSING_RUNTIME"

	// PROCESSING_GROUP indicates group-related processing errors.
	PROCESSING_GROUP Code = "PROCESSING_GROUP"

	// PROCESSING_INTERNAL indicates unexpected errors in processing layer.
	PROCESSING_INTERNAL Code = "PROCESSING_INTERNAL"

	// PROCESSING_REGRESSION_NOT_IMPLEMENTED indicates the request named a
	// regression operator whose engine has not yet shipped. Phase 0
	// stubs return this for every REG_* spec; later phases retire the
	// code as each engine lands.
	PROCESSING_REGRESSION_NOT_IMPLEMENTED Code = "PROCESSING_REGRESSION_NOT_IMPLEMENTED"

	// PROCESSING_REGRESSION_RANK_DEFICIENT indicates the predictor
	// design matrix has collinear columns; XᵀX is singular and the
	// closed-form OLS solve cannot proceed. Add a regularization
	// penalty or drop the redundant predictor.
	PROCESSING_REGRESSION_RANK_DEFICIENT Code = "PROCESSING_REGRESSION_RANK_DEFICIENT"

	// PROCESSING_REGRESSION_NO_CONVERGE indicates an iterative fit
	// (IRLS for REG_GLM, coordinate descent for regularized REG_OLS)
	// failed to converge within MaxIters.
	PROCESSING_REGRESSION_NO_CONVERGE Code = "PROCESSING_REGRESSION_NO_CONVERGE"

	// PROCESSING_REGRESSION_SINGULAR_GRAM indicates XᵀX remained
	// non-invertible even after regularization. Typically caused by a
	// degenerate predictor (all-zero column) or a vanishingly small
	// Alpha.
	PROCESSING_REGRESSION_SINGULAR_GRAM Code = "PROCESSING_REGRESSION_SINGULAR_GRAM"

	// PROCESSING_REGRESSION_INVALID_FAMILY indicates REG_GLM was
	// requested with a Family outside the supported set
	// ({"binomial", "poisson", "gamma"}).
	PROCESSING_REGRESSION_INVALID_FAMILY Code = "PROCESSING_REGRESSION_INVALID_FAMILY"

	// PROCESSING_REGRESSION_INVALID_LINK indicates the requested Link
	// function is incompatible with the chosen Family.
	PROCESSING_REGRESSION_INVALID_LINK Code = "PROCESSING_REGRESSION_INVALID_LINK"

	// PROCESSING_REGRESSION_INSUFFICIENT_DATA indicates the filtered
	// record set has fewer observations than predictors + 1 (the
	// minimum for an identifiable fit).
	PROCESSING_REGRESSION_INSUFFICIENT_DATA Code = "PROCESSING_REGRESSION_INSUFFICIENT_DATA"
)

PROCESSING domain - Processing engine and pipeline operations

const (
	// SERVICE_VALIDATION indicates request validation failures.
	SERVICE_VALIDATION Code = "SERVICE_VALIDATION"

	// SERVICE_RESOURCE indicates resource loading or access failures.
	SERVICE_RESOURCE Code = "SERVICE_RESOURCE"

	// SERVICE_REGISTRY indicates registry lookup failures.
	SERVICE_REGISTRY Code = "SERVICE_REGISTRY"

	// SERVICE_INTERNAL indicates unexpected errors in service layer.
	SERVICE_INTERNAL Code = "SERVICE_INTERNAL"
)

SERVICE domain - HTTP/API layer and service operations

const (
	// DATA_FILE indicates file access or format errors.
	DATA_FILE Code = "DATA_FILE"

	// DATA_PARSE indicates data parsing or deserialization errors.
	DATA_PARSE Code = "DATA_PARSE"

	// DATA_CONFIG indicates data configuration errors.
	DATA_CONFIG Code = "DATA_CONFIG"

	// DATA_CALCULATION indicates errors during data field access or calculation.
	DATA_CALCULATION Code = "DATA_CALCULATION"

	// DATA_INTERNAL indicates unexpected errors in data layer.
	DATA_INTERNAL Code = "DATA_INTERNAL"
)

DATA domain - Data file and dataset management operations

const (
	// CLI_INPUT indicates command input or argument errors.
	CLI_INPUT Code = "CLI_INPUT"

	// CLI_OUTPUT indicates output generation or file write errors.
	CLI_OUTPUT Code = "CLI_OUTPUT"

	// CLI_COMMAND indicates command execution errors.
	CLI_COMMAND Code = "CLI_COMMAND"

	// CLI_INTERNAL indicates unexpected errors in CLI layer.
	CLI_INTERNAL Code = "CLI_INTERNAL"
)

CLI domain - Command-line interface operations

const (
	// PULSE_IMPORT_SCHEMA_AMBIGUOUS indicates type ambiguity during schema inference.
	PULSE_IMPORT_SCHEMA_AMBIGUOUS Code = "PULSE_IMPORT_SCHEMA_AMBIGUOUS"

	// PULSE_IMPORT_ROW_ERROR indicates a per-row import error.
	PULSE_IMPORT_ROW_ERROR Code = "PULSE_IMPORT_ROW_ERROR"

	// PULSE_EXPORT_ROW_ERROR indicates a per-row export error.
	PULSE_EXPORT_ROW_ERROR Code = "PULSE_EXPORT_ROW_ERROR"

	// PULSE_IMPORT_CATEGORICAL_OVERFLOW indicates dictionary exceeds width capacity.
	PULSE_IMPORT_CATEGORICAL_OVERFLOW Code = "PULSE_IMPORT_CATEGORICAL_OVERFLOW"

	// PULSE_IMPORT_CATEGORICAL_UNBOUNDED indicates sample suggests unbounded cardinality.
	PULSE_IMPORT_CATEGORICAL_UNBOUNDED Code = "PULSE_IMPORT_CATEGORICAL_UNBOUNDED"

	// PULSE_IMPORT_DESCRIPTION_TOO_LONG indicates description exceeds 1000 bytes.
	PULSE_IMPORT_DESCRIPTION_TOO_LONG Code = "PULSE_IMPORT_DESCRIPTION_TOO_LONG"

	// PULSE_IMPORT_FORMAT_UNKNOWN indicates the source extension was not
	// recognised and no explicit format hint was supplied. Surfaced by
	// the imports.Manager on Open.
	PULSE_IMPORT_FORMAT_UNKNOWN Code = "PULSE_IMPORT_FORMAT_UNKNOWN"

	// PULSE_IMPORT_SOURCE_MISSING indicates the source file referenced
	// by an import or by a managed-import sidecar could not be read.
	PULSE_IMPORT_SOURCE_MISSING Code = "PULSE_IMPORT_SOURCE_MISSING"

	// PULSE_IMPORT_HANDLE_EXISTS indicates a managed-import handle of
	// the requested name already exists and Overwrite was not set.
	PULSE_IMPORT_HANDLE_EXISTS Code = "PULSE_IMPORT_HANDLE_EXISTS"

	// PULSE_IMPORT_SOURCE_FORBIDDEN indicates an absolute source path
	// resolved outside the import jail. The Manager confines absolute
	// reads to a configured root (default: process cwd) so an MCP /
	// CLI invocation cannot reach arbitrary files on the host.
	PULSE_IMPORT_SOURCE_FORBIDDEN Code = "PULSE_IMPORT_SOURCE_FORBIDDEN"

	// PULSE_AGG_NOT_MEANINGFUL_FOR_CATEGORICAL indicates a numeric aggregation
	// was requested on a categorical field.
	PULSE_AGG_NOT_MEANINGFUL_FOR_CATEGORICAL Code = "PULSE_AGG_NOT_MEANINGFUL_FOR_CATEGORICAL"

	// PULSE_FIELD_DESCRIPTION_LOW_QUALITY indicates a field description quality warning.
	PULSE_FIELD_DESCRIPTION_LOW_QUALITY Code = "PULSE_FIELD_DESCRIPTION_LOW_QUALITY"

	// PULSE_WINDOW_INVALID indicates a structural validation failure for a
	// window operation: invalid frame matrix, alpha out of bounds,
	// non-orderable order key, label collision, or unsupported window type.
	PULSE_WINDOW_INVALID Code = "PULSE_WINDOW_INVALID"

	// PULSE_FEAT_TARGET_LEAKAGE_RISK indicates that FEAT_TARGET_ENCODE was
	// requested without a prior FEAT_TRAIN_TEST_SPLIT in the same Features
	// list. The encoded values include rows that should belong to the
	// validation/test partitions, leaking target information into the
	// training feature. Mitigation: place a FEAT_TRAIN_TEST_SPLIT operator
	// before any FEAT_TARGET_ENCODE.
	PULSE_FEAT_TARGET_LEAKAGE_RISK Code = "PULSE_FEAT_TARGET_LEAKAGE_RISK"

	// PULSE_DECIMAL_OVERFLOW indicates a decimal arithmetic or aggregation
	// result exceeds the decimal128(38) representable range.
	PULSE_DECIMAL_OVERFLOW Code = "PULSE_DECIMAL_OVERFLOW"

	// PULSE_DECIMAL_PRECISION_LOSS warns that a decimal aggregation fell
	// back to f64 because intermediate state would have overflowed
	// decimal128(38).
	PULSE_DECIMAL_PRECISION_LOSS Code = "PULSE_DECIMAL_PRECISION_LOSS"

	// PULSE_DECIMAL_DIVIDE_BY_ZERO indicates a decimal divide operation
	// with a zero divisor.
	PULSE_DECIMAL_DIVIDE_BY_ZERO Code = "PULSE_DECIMAL_DIVIDE_BY_ZERO"

	// PULSE_AGG_NOT_MEANINGFUL_FOR_DECIMAL is a predict warning emitted
	// when an aggregation has no defined semantics on a decimal128 field
	// (e.g., AGG_MEDIAN, AGG_PERCENTILE in v1).
	PULSE_AGG_NOT_MEANINGFUL_FOR_DECIMAL Code = "PULSE_AGG_NOT_MEANINGFUL_FOR_DECIMAL"

	// PULSE_SYNTH_DISTRIBUTION_UNKNOWN indicates a synth spec referenced
	// a distribution kind not registered in the synth package.
	PULSE_SYNTH_DISTRIBUTION_UNKNOWN Code = "PULSE_SYNTH_DISTRIBUTION_UNKNOWN"

	// PULSE_SYNTH_CONSTRAINT_INFEASIBLE indicates that rejection sampling
	// for declared constraints exceeded the allowed rejection rate (50%
	// by default), so the generator gives up rather than produce biased
	// or truncated output.
	PULSE_SYNTH_CONSTRAINT_INFEASIBLE Code = "PULSE_SYNTH_CONSTRAINT_INFEASIBLE"

	// PULSE_PROFILE_FIELD_UNSUPPORTED indicates a field type the profile
	// layer cannot summarize. The field is skipped with a warning rather
	// than failing the whole profile.
	PULSE_PROFILE_FIELD_UNSUPPORTED Code = "PULSE_PROFILE_FIELD_UNSUPPORTED"

	// PULSE_TEST_UNKNOWN_TYPE indicates the request referenced a TestType
	// that is not registered in either the row-test or post-test registry.
	PULSE_TEST_UNKNOWN_TYPE Code = "PULSE_TEST_UNKNOWN_TYPE"

	// PULSE_TEST_FIELD_NOT_NUMERIC indicates a test requires a numeric
	// field but the named field resolves to a categorical or otherwise
	// non-numeric schema type.
	PULSE_TEST_FIELD_NOT_NUMERIC Code = "PULSE_TEST_FIELD_NOT_NUMERIC"

	// PULSE_TEST_INVALID_ALPHA indicates the request's Alpha value lies
	// outside the open interval (0, 1).
	PULSE_TEST_INVALID_ALPHA Code = "PULSE_TEST_INVALID_ALPHA"

	// PULSE_TEST_INSUFFICIENT_N indicates a test received fewer
	// non-null observations than the minimum needed to compute its
	// statistic (typically n < 2 per group, n < df + 1 for parametric
	// tests).
	PULSE_TEST_INSUFFICIENT_N Code = "PULSE_TEST_INSUFFICIENT_N"

	// PULSE_TEST_VARIANCE_ZERO indicates one or more groups have zero
	// sample variance, making the t- or F-statistic undefined.
	PULSE_TEST_VARIANCE_ZERO Code = "PULSE_TEST_VARIANCE_ZERO"

	// PULSE_TEST_SPLIT_GROUPS_LT_2 indicates a two-sample or ANOVA test
	// observed fewer than the required number of distinct groups in the
	// SplitBy field after filtering.
	PULSE_TEST_SPLIT_GROUPS_LT_2 Code = "PULSE_TEST_SPLIT_GROUPS_LT_2"

	// PULSE_TEST_CONTINGENCY_DEGENERATE indicates a chi-square contingency
	// table is empty or has a single row/column, making the test
	// statistic undefined.
	PULSE_TEST_CONTINGENCY_DEGENERATE Code = "PULSE_TEST_CONTINGENCY_DEGENERATE"

	// PULSE_TEST_EXPECTED_COUNT_TOO_LOW warns that a chi-square cell's
	// expected count is below the conventional threshold of 5, making
	// the asymptotic χ² approximation unreliable.
	PULSE_TEST_EXPECTED_COUNT_TOO_LOW Code = "PULSE_TEST_EXPECTED_COUNT_TOO_LOW"

	// PULSE_TEST_FIELD2_NOT_NUMERIC indicates the secondary Field2
	// reference required by a paired or bivariate test (TEST_PAIRED_T,
	// TEST_PEARSON_R) resolves to a non-numeric schema type.
	PULSE_TEST_FIELD2_NOT_NUMERIC Code = "PULSE_TEST_FIELD2_NOT_NUMERIC"

	// PULSE_TEST_SUCCESS_VALUE_MISSING indicates a two-proportion z-test
	// did not supply Params.success — the dictionary value treated as a
	// success on the primary field. Without it, the test cannot decide
	// which category counts as a positive outcome.
	PULSE_TEST_SUCCESS_VALUE_MISSING Code = "PULSE_TEST_SUCCESS_VALUE_MISSING"

	// PULSE_TEST_CORRELATION_UNDEFINED indicates Pearson r encountered
	// a column with zero variance; r and its t-statistic are
	// mathematically undefined in that case.
	PULSE_TEST_CORRELATION_UNDEFINED Code = "PULSE_TEST_CORRELATION_UNDEFINED"

	// PULSE_TEST_PAIRED_LENGTH_MISMATCH indicates a Wilcoxon signed-rank
	// (or future paired test) encountered rows where one of the paired
	// columns is null while the other is present. Drop-pair semantics
	// apply by default (rows with either value missing are skipped);
	// this code surfaces as a warning so the caller knows the effective
	// pair count differs from the input row count.
	PULSE_TEST_PAIRED_LENGTH_MISMATCH Code = "PULSE_TEST_PAIRED_LENGTH_MISMATCH"

	// PULSE_TEST_TIES_DOMINATE warns that a rank-based test observed
	// ties on ≥ 50 % of the input values. The asymptotic normal / chi-
	// square approximation used for the p-value loses accuracy under
	// heavy ties; consider an exact-permutation variant when the count
	// is small.
	PULSE_TEST_TIES_DOMINATE Code = "PULSE_TEST_TIES_DOMINATE"

	// PULSE_TEST_SUBJECT_MISSING indicates a repeated-measures test
	// found at least one subject missing one or more conditions.
	// Default behavior is to drop the incomplete subject(s) and surface
	// the count as a warning; configurable to error under strict mode.
	PULSE_TEST_SUBJECT_MISSING Code = "PULSE_TEST_SUBJECT_MISSING"

	// PULSE_TEST_BALANCED_DESIGN_REQUIRED indicates a repeated-measures
	// test observed unequal cell counts across the condition × subject
	// grid. Type II / III sums-of-squares decompositions for the
	// unbalanced case are not implemented yet; the test fails rather
	// than reporting a biased balanced-design F.
	PULSE_TEST_BALANCED_DESIGN_REQUIRED Code = "PULSE_TEST_BALANCED_DESIGN_REQUIRED"

	// PULSE_TEST_TUKEY_REQUIRES_K_GE_3 indicates a Tukey HSD request on
	// fewer than 3 groups. A standard t-test or two-proportion z is
	// the appropriate alternative for k = 2.
	PULSE_TEST_TUKEY_REQUIRES_K_GE_3 Code = "PULSE_TEST_TUKEY_REQUIRES_K_GE_3"

	// PULSE_TEST_SHAPIRO_N_BOUND warns that a Shapiro-Wilk request
	// observed n above the supported limit (5000). The asymptotic
	// alternative (D'Agostino's K² or Anderson-Darling) is recommended.
	PULSE_TEST_SHAPIRO_N_BOUND Code = "PULSE_TEST_SHAPIRO_N_BOUND"

	// PULSE_TEST_FISHER_R_OR_C_GT_2 indicates a Fisher exact request on
	// a contingency table larger than 2×2. The v1 implementation
	// supports only 2×2; the network algorithm needed for r×c lands
	// later.
	PULSE_TEST_FISHER_R_OR_C_GT_2 Code = "PULSE_TEST_FISHER_R_OR_C_GT_2"

	// PULSE_QUERY_UNRESOLVED indicates the natural-language query
	// parser (internal/query) could not map one or more tokens to an
	// operator, schema field, or bucket within the configured edit-
	// distance budget. Severity depends on context: a query that
	// produced no parseable structure surfaces this as an error; a
	// query that produced a partial request surfaces it as a warning
	// so the caller can still inspect and repair the partial parse.
	PULSE_QUERY_UNRESOLVED Code = "PULSE_QUERY_UNRESOLVED"

	// PULSE_QUERY_AMBIGUOUS indicates a query token matched multiple
	// schema fields at the same Levenshtein distance, or otherwise
	// produced two candidate requests with similar confidence. The
	// parser picks the lexically first match and proceeds; the
	// warning names every candidate so the caller can disambiguate
	// by editing the resolved request.
	PULSE_QUERY_AMBIGUOUS Code = "PULSE_QUERY_AMBIGUOUS"

	// PULSE_EXTENSION_NAME_INVALID indicates an embedder registration
	// name does not match the required pattern
	// <CATEGORY>_<NAMESPACE>_<NAME> with uppercase ASCII segments.
	PULSE_EXTENSION_NAME_INVALID Code = "PULSE_EXTENSION_NAME_INVALID"

	// PULSE_EXTENSION_NAME_RESERVED indicates an embedder registration
	// uses a namespace segment reserved for Pulse internals
	// (BUILTIN / STANDARD / CORE / PULSE).
	PULSE_EXTENSION_NAME_RESERVED Code = "PULSE_EXTENSION_NAME_RESERVED"

	// PULSE_EXTENSION_NAME_COLLISION indicates an embedder registration
	// name matches a built-in operator name within the same category.
	PULSE_EXTENSION_NAME_COLLISION Code = "PULSE_EXTENSION_NAME_COLLISION"

	// PULSE_EXTENSION_DUPLICATE indicates the same operator name was
	// registered more than once within a single pulse.New call (same
	// category).
	PULSE_EXTENSION_DUPLICATE Code = "PULSE_EXTENSION_DUPLICATE"

	// PULSE_EXTENSION_STREAMABLE_MISMATCH indicates a registration
	// declared Streamable=true but its factory returned an instance
	// that does not implement the required streaming interface, or
	// declared Mode=row_local / Mode=two_pass without the corresponding
	// attribute interface.
	PULSE_EXTENSION_STREAMABLE_MISMATCH Code = "PULSE_EXTENSION_STREAMABLE_MISMATCH"

	// PULSE_EXTENSION_FACTORY_PANIC indicates an embedder factory
	// panicked during probe-validation at registration time.
	PULSE_EXTENSION_FACTORY_PANIC Code = "PULSE_EXTENSION_FACTORY_PANIC"

	// PULSE_EXTENSION_PARAM_INVALID indicates a ParamMeta entry on a
	// registration has missing or contradictory fields (empty name,
	// unknown JSONType, Required=true with a non-nil Default).
	PULSE_EXTENSION_PARAM_INVALID Code = "PULSE_EXTENSION_PARAM_INVALID"

	// PULSE_LOOKUP_TABLE_UNKNOWN indicates a runtime expression
	// referenced a lookup table that is not registered on the
	// Service.
	PULSE_LOOKUP_TABLE_UNKNOWN Code = "PULSE_LOOKUP_TABLE_UNKNOWN"

	// PULSE_LOOKUP_MISS indicates a lookup table call provided a key
	// tuple that is not present in the table.
	PULSE_LOOKUP_MISS Code = "PULSE_LOOKUP_MISS"

	// PULSE_ARCHIVE_MAGIC_INVALID indicates a cohort path whose leading
	// bytes match neither the single-file Pulse magic ("PULSE\x00\x00\x00")
	// nor the zip-archive magic (PK\x03\x04). Surfaced by pulse.Open
	// when the file is not a recognised Pulse artifact.
	PULSE_ARCHIVE_MAGIC_INVALID Code = "PULSE_ARCHIVE_MAGIC_INVALID"

	// PULSE_ARCHIVE_CORRUPT indicates a Pulse shard archive whose zip
	// end-of-central-directory record is missing or invalid, or whose
	// central directory cannot be parsed. The archive is unreadable
	// until repaired (typically via re-creation from constituent shards).
	PULSE_ARCHIVE_CORRUPT Code = "PULSE_ARCHIVE_CORRUPT"

	// PULSE_SHARD_MISSING indicates the central directory references an
	// entry that is not addressable inside the archive, or a caller
	// requested a shard by name that does not exist. Distinct from
	// PULSE_ARCHIVE_CORRUPT in that the archive itself is structurally
	// valid; only the named entry is absent.
	PULSE_SHARD_MISSING Code = "PULSE_SHARD_MISSING"

	// PULSE_SHARD_HEADER_INVALID indicates a shard payload inside an
	// archive failed its first-read magic + format-version check. The
	// archive's central directory may be valid while a constituent
	// shard's bytes are not a single-file Pulse cohort.
	PULSE_SHARD_HEADER_INVALID Code = "PULSE_SHARD_HEADER_INVALID"

	// PULSE_SHARD_SCHEMA_MISMATCH indicates an incoming shard's
	// structural schema (field count, per-field name/type/byte_offset/
	// bit_position, categorical width) is not byte-equal to the
	// archive's canonical schema. The insert is rejected; descriptions
	// alone diverging do NOT raise this code (see
	// PULSE_SHARD_DESCRIPTION_DIVERGENCE).
	PULSE_SHARD_SCHEMA_MISMATCH Code = "PULSE_SHARD_SCHEMA_MISMATCH"

	// PULSE_SHARD_DICT_DIVERGENCE indicates an incoming shard's
	// categorical dictionary is not prefix-related to the canonical
	// dictionary on the same field. Pulse permits append-only growth
	// (incoming prefix of canonical, or canonical prefix of incoming
	// — see PULSE_SHARD_DICT_WIDTH_OVERFLOW for the capacity guard),
	// but rejects reorders or new values inserted before existing
	// ones.
	PULSE_SHARD_DICT_DIVERGENCE Code = "PULSE_SHARD_DICT_DIVERGENCE"

	// PULSE_SHARD_DICT_WIDTH_OVERFLOW indicates a categorical
	// dictionary extension that would exceed the declared field
	// width's capacity (256 for u8, 65 536 for u16, 2^32 for u32).
	// The field's width is fixed at folder creation; widening
	// requires rebuilding the archive with a wider categorical type.
	PULSE_SHARD_DICT_WIDTH_OVERFLOW Code = "PULSE_SHARD_DICT_WIDTH_OVERFLOW"

	// PULSE_SHARD_DESCRIPTION_DIVERGENCE is emitted as a WARNING (not
	// an error) when an incoming shard's per-field description differs
	// from the canonical schema's. Descriptions are advisory metadata;
	// the canonical description in `_schema.pulse` wins for any
	// downstream consumer.
	PULSE_SHARD_DESCRIPTION_DIVERGENCE Code = "PULSE_SHARD_DESCRIPTION_DIVERGENCE"

	// PULSE_SHARD_RESERVED_NAME indicates a caller attempted to insert
	// a shard whose basename collides with the reserved canonical
	// schema entry name (`_schema.pulse`). The reserved name is
	// addressable only through the archive's own canonical-schema
	// channel; user shards must pick a different basename.
	PULSE_SHARD_RESERVED_NAME Code = "PULSE_SHARD_RESERVED_NAME"

	// PULSE_SHARD_NAME_COLLISION indicates two shards in the same
	// archive (or two paths handed to `pulse shard create`) share a
	// basename. Zip entry names are flat — basenames must be unique
	// within an archive.
	PULSE_SHARD_NAME_COLLISION Code = "PULSE_SHARD_NAME_COLLISION"
)

PULSE domain - Pulse-specific error codes for I/O pipelines, categorical handling, description validation, and aggregation warnings.

func AllCodes

func AllCodes() []Code

AllCodes returns a copy of all defined error codes.

func ParseCode

func ParseCode(s string) (Code, bool)

ParseCode attempts to parse a string into a known Code. Returns the Code and true if found, or the zero value and false otherwise.

func (Code) Fixup

func (c Code) Fixup(req any) []Fixup

Fixup returns the materialised fixup templates for this code. The req argument is reserved for future path-resolution work; today the templates are returned as-is so callers see the abstract paths from the metadata table. Returns nil when the code is tagged FixupNotApplicable.

The signature accepts any so the errors package can avoid a circular dependency on types/. Predict-suggestions, which lives above both packages, will introduce a typed wrapper that walks the request to resolve concrete indices.

type CodedError

type CodedError struct {
	// Code identifies the error category.
	Code Code

	// Message provides a human-readable description.
	Message string

	// Details holds arbitrary key-value context (row number, field name, etc.).
	Details map[string]any

	// Cause is the underlying error, if any.
	Cause error
}

CodedError wraps an error code with context. It is the primary structured error type for Pulse, supporting JSON serialization for --json CLI output and error chain traversal via Unwrap.

func NewCodedError

func NewCodedError(code Code, message string) *CodedError

NewCodedError creates a new CodedError with no details or cause.

func NewCodedErrorWithDetails

func NewCodedErrorWithDetails(code Code, message string, details map[string]any) *CodedError

NewCodedErrorWithDetails creates a new CodedError with pre-populated details. The details map is defensively copied.

func WrapCodedError

func WrapCodedError(err error, code Code, message string) *CodedError

WrapCodedError wraps an existing error with a CodedError layer.

func (*CodedError) Error

func (e *CodedError) Error() string

Error implements the error interface. Format: "CODE: message"

func (*CodedError) MarshalJSON

func (e *CodedError) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler, producing the --json envelope shape. When Details is nil, the "details" key is omitted entirely. When Details is non-nil (even if empty), the "details" key is included.

func (*CodedError) Unwrap

func (e *CodedError) Unwrap() error

Unwrap returns the underlying cause for errors.Is / errors.As traversal.

type Fixup

type Fixup struct {
	// Action is the repair category.
	Action FixupAction `json:"action"`

	// Path is the request path the fix applies to. First-cut templates
	// use either an empty path (the caller resolves it) or a static
	// wildcard path like ["Aggregations", "*", "Type"] that describes
	// where the fix conceptually lives. Concrete index resolution is
	// predict-suggestions' job.
	Path []string `json:"path,omitempty"`

	// Hint is the prose remediation. Single sentence, imperative,
	// actionable — describes a concrete next move.
	Hint string `json:"hint"`

	// Examples lists ranked example fixes (e.g. specific operator
	// names, replacement values). Populated sparingly; most codes
	// carry only a Hint.
	Examples []any `json:"examples,omitempty"`
}

Fixup is a machine-actionable hint for repairing a request that triggered an error. Templates live in the per-code metadata table and are materialised via Code.Fixup(req) before being shipped to a caller.

type FixupAction

type FixupAction string

FixupAction enumerates the mechanical repair categories a caller can apply to an offending request. Action values are stable wire constants: downstream consumers (predict-suggestions, unified-ask-tool, manifest) dispatch on them.

const (
	// FixupReplaceField swaps the offending field reference for a
	// different field of the right type. The replacement candidate is
	// typically named in the Hint or surfaced by the caller's schema
	// walk; this package only declares the action class.
	FixupReplaceField FixupAction = "REPLACE_FIELD"

	// FixupReplaceOperator swaps the offending operator (aggregator,
	// attribute, filterer, grouper, window, feature, test) for a
	// compatible one. The Hint identifies one or more valid swaps.
	FixupReplaceOperator FixupAction = "REPLACE_OPERATOR"

	// FixupRemoveParam removes an incompatible request parameter (a
	// frame on a non-frame window, a success value on the wrong test,
	// etc.) so the request validates.
	FixupRemoveParam FixupAction = "REMOVE_PARAM"

	// FixupSetDefault supplies a missing required parameter with the
	// canonical default (alpha=0.05, etc.).
	FixupSetDefault FixupAction = "SET_DEFAULT"

	// FixupRequiresReschema signals that the offending request cannot
	// be repaired by editing the request alone — the .pulse cohort
	// itself needs different schema, filtering, or row counts.
	FixupRequiresReschema FixupAction = "REQUIRES_RESCHEMA"
)

type LookupResult

type LookupResult struct {
	// Code is the canonical error code string (e.g.
	// "PULSE_AGG_NOT_MEANINGFUL_FOR_CATEGORICAL").
	Code string `json:"code"`

	// Domain is the prefix segment (PULSE, SERVICE, PROCESSING,
	// ENCODING, DATA, CLI).
	Domain string `json:"domain"`

	// Message is the canonical human-readable description for the
	// code. Mirrors codeMetadata[c].Message.
	Message string `json:"message"`

	// Fixups is the materialised fixup template list. Nil when the
	// code is FixupNotApplicable.
	Fixups []Fixup `json:"fixups,omitempty"`

	// FixupNotApplicable is true for codes that have no mechanical
	// repair (typically *_INTERNAL invariants).
	FixupNotApplicable bool `json:"fixup_not_applicable,omitempty"`
}

LookupResult is the depth-on-demand projection returned by Lookup, ByDomain, and Search. It carries the code identifier, its domain prefix, the canonical Message, and the materialised Fixup templates. FixupNotApplicable is mirrored so callers can distinguish "no fixup because internal bug" from "no fixup because none authored yet".

LookupResult is a stable wire shape. The MCP `pulse_errors_lookup` tool and the `pulse errors lookup` / `pulse errors list` CLI leaves emit a LookupResult per code, with json field names that mirror the manifest's slim error_codes list.

func ByDomain

func ByDomain(domain string) []LookupResult

ByDomain returns every code's metadata in the given domain. Match is case-insensitive against the prefix segment. Returns a non-nil empty slice when no code matches (so JSON callers always see an array). Results are sorted by Code.

func Lookup

func Lookup(code string) (LookupResult, bool)

Lookup returns the metadata projection for a single code string. Case-sensitive exact match. Returns (LookupResult{}, false) when the code is unknown.

func Search

func Search(query string) []LookupResult

Search returns codes whose Message or Fixup hints contain q (case-insensitive substring). Results are ranked by where the match hit — description matches outrank fixup matches, fixup matches outrank code-name matches; ties resolve alphabetically by code. Returns a non-nil empty slice when nothing matches.

type Metadata

type Metadata struct {
	// Message is the canonical human-readable description used when no
	// caller-supplied message is provided. Mirrors the curated text in
	// descriptor.errorMetaTable but is owned by the errors package.
	Message string

	// Fixups is the template list. Empty when FixupNotApplicable is
	// true; otherwise carries at least one Fixup.
	Fixups []Fixup

	// FixupNotApplicable is true for codes that have no mechanical
	// fix: internal-invariant violations, corrupted files, and similar
	// "bug, not user error" signals. The flag is the honest signal —
	// callers should not invent suggestions for these codes.
	FixupNotApplicable bool
}

Metadata bundles per-code documentation that lives alongside the flat Code constant. Today it carries the canonical human Message and a Fixups template list. Future fields (severity, retryable, etc.) attach here.

func MetadataFor

func MetadataFor(c Code) (Metadata, bool)

Metadata returns the per-code metadata entry. The second return value is false if the code has no entry — TestCodesHaveFixups enforces that every entry in allCodes has metadata, so production code can ignore the bool except in introspection paths.