output

type ErrorRecord struct {
	// Code is a machine-readable error code.
	Code string `json:"code"`

	// Message is a human-readable error description.
	Message string `json:"message"`

	// Key is the object key related to this error, if applicable.
	Key string `json:"key,omitempty"`

	// Prefix is the prefix being listed when the error occurred.
	Prefix string `json:"prefix,omitempty"`

	// Details contains additional error context.
	Details any `json:"details,omitempty"`

	// Collision contains reflow collision context when an error is caused by a
	// destination collision.
	Collision any `json:"collision,omitempty"`
}

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

type ObjectRecord struct {
	// Key is the full object key (path) in the bucket.
	Key string `json:"key"`

	// Size is the object size in bytes.
	Size int64 `json:"size"`

	// ETag is the entity tag, typically an MD5 hash of the object.
	ETag string `json:"etag"`

	// LastModified is when the object was last modified.
	LastModified time.Time `json:"last_modified"`

	// StorageClass is the provider-native storage class when supplied.
	StorageClass string `json:"storage_class,omitempty"`

	// ContentType is the MIME type of the object.
	// Only populated if metadata enrichment is enabled.
	ContentType string `json:"content_type,omitempty"`

	// Metadata contains user-defined metadata key-value pairs.
	// Only populated if metadata enrichment is enabled.
	Metadata map[string]string `json:"metadata,omitempty"`
}

type PrefixRecord struct {
	Prefix    string `json:"prefix"`
	Delimiter string `json:"delimiter"`

	// Depth indicates the traversal depth of this prefix relative to the root.
	// Wave 1 emits a single record at depth=0.
	Depth int `json:"depth,omitempty"`

	ObjectsDirect  int64 `json:"objects_direct"`
	BytesDirect    int64 `json:"bytes_direct"`
	CommonPrefixes int64 `json:"common_prefixes"`
	Pages          int64 `json:"pages"`
	Truncated      bool  `json:"truncated"`

	TruncatedReason string `json:"truncated_reason,omitempty"`
}

type PreflightCheckResult struct {
	Capability string `json:"capability"`
	Allowed    bool   `json:"allowed"`
	Method     string `json:"method,omitempty"`
	ErrorCode  string `json:"error_code,omitempty"`
	Detail     string `json:"detail,omitempty"`
}

type PreflightRecord struct {
	Mode          string                 `json:"mode"`
	ProbeStrategy string                 `json:"probe_strategy,omitempty"`
	ProbePrefix   string                 `json:"probe_prefix,omitempty"`
	Results       []PreflightCheckResult `json:"results"`
}

type ProgressRecord struct {
	// Phase indicates the current crawl phase.
	Phase string `json:"phase"`

	// ObjectsFound is the total number of objects seen so far.
	ObjectsFound int64 `json:"objects_found"`

	// ObjectsMatched is the number of objects matching patterns.
	ObjectsMatched int64 `json:"objects_matched"`

	// BytesTotal is the cumulative size of matched objects in bytes.
	BytesTotal int64 `json:"bytes_total"`

	// Prefix is the current prefix being listed, if applicable.
	Prefix string `json:"prefix,omitempty"`
}

type Record struct {
	// Type identifies the record type (e.g., "gonimbus.object.v1").
	Type string `json:"type"`

	// TS is the timestamp when the record was created (RFC3339Nano).
	TS time.Time `json:"ts"`

	// JobID is the correlation ID for this crawl job.
	JobID string `json:"job_id"`

	// Provider identifies the storage provider (e.g., "s3", "gcs").
	Provider string `json:"provider"`

	// Advisory marks a non-work, non-integrity control/summary envelope that
	// a consumer without a registered handler for Type may skip with a bounded
	// warning. Known record types and recognized work/integrity/error families
	// are always validated or refused regardless of this marker.
	Advisory bool `json:"advisory,omitempty"`

	// Data contains the type-specific payload as raw JSON.
	Data json.RawMessage `json:"data"`
}

type SkipRecord struct {
	SourceKey string `json:"source_key"`
	TargetKey string `json:"target_key"`
	Reason    string `json:"reason"`
}

type SummaryRecord struct {
	// ObjectsFound is the total number of objects seen.
	ObjectsFound int64 `json:"objects_found"`

	// ObjectsMatched is the number of objects matching patterns.
	ObjectsMatched int64 `json:"objects_matched"`

	// BytesTotal is the cumulative size of matched objects in bytes.
	BytesTotal int64 `json:"bytes_total"`

	// Duration is the total crawl duration.
	Duration time.Duration `json:"duration_ns"`

	// DurationHuman is a human-readable duration string.
	DurationHuman string `json:"duration"`

	// Errors is the count of errors encountered.
	Errors int64 `json:"errors"`

	// Prefixes lists the prefixes that were crawled.
	Prefixes []string `json:"prefixes,omitempty"`
}

type TransferRecord struct {
	SourceKey string `json:"source_key"`
	TargetKey string `json:"target_key"`
	Bytes     int64  `json:"bytes"`
}

type WriteError struct {
	Op  string // Operation that failed (e.g., "marshal_data", "write")
	Err error  // Underlying error
}

type Writer interface {
	// WriteObject emits an object record.
	WriteObject(ctx context.Context, obj *ObjectRecord) error

	// WriteError emits an error record.
	WriteError(ctx context.Context, err *ErrorRecord) error

	// WriteProgress emits a progress record.
	WriteProgress(ctx context.Context, prog *ProgressRecord) error

	// WriteSummary emits a summary record.
	WriteSummary(ctx context.Context, sum *SummaryRecord) error

	// WritePrefix emits a prefix summary record.
	WritePrefix(ctx context.Context, prefix *PrefixRecord) error

	// WritePreflight emits a preflight record.
	WritePreflight(ctx context.Context, preflight *PreflightRecord) error

	// WriteTransfer emits a transfer record.
	WriteTransfer(ctx context.Context, transfer *TransferRecord) error

	// WriteSkip emits a skip record.
	WriteSkip(ctx context.Context, skip *SkipRecord) error

	// Close flushes any buffered output and releases resources.
	Close() error
}