// Package customschema: Milestone 3 (reset-metadata) models and sentinel
// errors. This file declares only the types and errors specific to the
// reset workstream so it stays disjoint from Milestone 2's
// models.go / service_metadata.go (see tracking §2.9).
package customschema

import (
	"errors"
	"time"

	"github.com/google/uuid"
)

// ErrMutualExclusivityViolation is returned by ResetDocumentMetadata when
// the locked document row carries at least one legacy field-extraction
// entry. The reset endpoint is deliberately scoped to documents using the
// custom schema system; the handler maps this sentinel to 409.
//
// This sentinel is intentionally separate from
// ErrDocumentHasLegacyExtractions (which is returned by
// AssignSchema / SetDocumentMetadata) so callers that want to distinguish
// "cannot bind / cannot write metadata" from "cannot reset" get the more
// specific wording. Both errors map to the same HTTP status (409).
var ErrMutualExclusivityViolation = errors.New("document uses the legacy field extraction system; reset-metadata only applies to documents using the custom schema system")

// ResetMetadataResult is the service-layer return value for
// ResetDocumentMetadata. Handlers translate this into the generated
// ResetDocumentMetadataResponse type; keeping the service return free of
// OpenAPI types lets the service stay decoupled from the generated
// package.
//
// All three PreviousSchema* pointers are nil when the document had no
// schema bound at reset time. This is the idempotent no-op case and is
// returned alongside MetadataVersionsDeleted == 0.
type ResetMetadataResult struct {
	// DocumentID is the document whose metadata was reset.
	DocumentID uuid.UUID

	// PreviousSchemaID is the document's custom_schema_id before the
	// reset ran. nil when no schema was bound.
	PreviousSchemaID *uuid.UUID

	// PreviousSchemaName mirrors the joined client_metadata_schemas.name
	// of the previously-bound schema. nil when no schema was bound.
	PreviousSchemaName *string

	// PreviousSchemaVersion mirrors the joined client_metadata_schemas.version
	// of the previously-bound schema. nil when no schema was bound.
	PreviousSchemaVersion *int

	// MetadataVersionsDeleted is the number of document_custom_metadata
	// rows that existed (and were subsequently deleted) at reset time.
	// Zero is a valid success value — the reset endpoint is idempotent
	// on already-clean documents.
	MetadataVersionsDeleted int

	// ResetAt is the wall-clock time the reset completed. Populated by
	// the service layer at the moment the audit record is emitted so the
	// response timestamp matches the audit entry.
	ResetAt time.Time

	// ResetBy is the Cognito subject of the caller, passed through from
	// the handler's JWT sub claim.
	ResetBy string
}