discovery

type AcceptedSet struct {
	Path string `json:"path"`
	// Parent is the owning blockType for a parent-scoped pattern
	// (`group.blocks`), empty otherwise.
	Parent string         `json:"parent,omitempty"`
	Types  []AcceptedType `json:"types"`
	// Authoritative is true only when a declared source enumerates the whole
	// set: a profile pin, or a GraphQL union whose every member resolved to a
	// confirmed slug. Only then is "not in the set" an error rather than
	// "never observed here".
	Authoritative bool   `json:"authoritative"`
	Source        string `json:"source"`
	// InterfaceNames and Unconfirmed carry the GraphQL half when there is one.
	InterfaceNames []string `json:"interface_names,omitempty"`
	Unconfirmed    []string `json:"unconfirmed,omitempty"`
	Reason         string   `json:"reason,omitempty"`
	// Rows/Docs/EmptyRows/UntypedRows are the census counts at this path.
	Rows        int `json:"rows"`
	Docs        int `json:"docs"`
	EmptyRows   int `json:"empty_rows"`
	UntypedRows int `json:"untyped_rows"`
}

type AcceptedType struct {
	Slug string `json:"slug"`
	// Count is how many rows of this type the census saw at this path.
	Count         int      `json:"count"`
	Sources       []string `json:"sources"`
	InterfaceName string   `json:"interface_name,omitempty"`
	Label         *string  `json:"label,omitempty"`
	Description   *string  `json:"description,omitempty"`
}

type AuthBootstrap struct {
	// Collection is the resolved auth-collection slug.
	Collection string
	// Source is "bootstrap" when Stage -1 ran, "configured" when it was
	// skipped because the slug was set, "cached" when it came from
	// auth-resolution.json.
	Source string
	// Candidates are every slug that survived the /init filter, in the order
	// they were tried. They are recorded in diagnostics.auth_candidates[].
	Candidates []string
	// Truncated reports that the candidate set was the anonymous slug list
	// alone.
	Truncated bool
	// Requests is the number of HTTP requests Stage -1 spent.
	Requests int
}

type BlockDoc struct {
	Slug        string  `json:"slug"`
	Label       *string `json:"label"`
	LabelPlural *string `json:"label_plural"`
	// LabelsSource / DescriptionSource are "project-source" or "unknown".
	// Nothing here is ever derived from the slug: a block whose author wrote
	// no labels has none, and title-casing "mediaBlock" would invent one.
	LabelsSource      string  `json:"labels_source"`
	Description       *string `json:"description"`
	DescriptionSource string  `json:"description_source"`
	// DescriptionKey names the config key the text came from, because Payload
	// defines none for a block: see BlockTypeSchema.DescriptionKey.
	DescriptionKey string `json:"description_key"`
	// FieldsCount is the block's content fields, excluding the three plumbing
	// keys every block row carries.
	FieldsCount int `json:"fields_count"`
	// DocsReason is empty exactly when both label and description were found,
	// and otherwise says why they were not — a plugin block has no config on
	// disk, and that is expected rather than a failure.
	DocsReason string `json:"docs_reason"`
}

type BlockField struct {
	Path string `json:"path"`
	// Slugs are the blockType values the REST API accepts here, or null when
	// none could be resolved.
	Slugs []string `json:"slugs"`
	// Source is the weakest provenance among Slugs, or "mixed".
	Source string `json:"source"`
	// SlugSources gives every slug its own provenance so a confirmed slug is
	// distinguishable from one inferred from an interfaceName.
	SlugSources map[string]string `json:"slug_sources"`
	// SlugInterfaces pairs each slug with the GraphQL union member it came
	// from, which is how a slug is joined to the block's field schema in
	// Shard.BlockSchemas.
	SlugInterfaces map[string]string `json:"slug_interface_names"`
	// InterfaceNames is the field's GraphQL union possibleTypes, verbatim.
	// They are NOT blockType slugs and must never be sent to the API.
	InterfaceNames []string `json:"interface_names"`
	// Unresolved lists union members no source could name; the field accepts
	// them but PayCLI cannot say what to call them.
	Unresolved []string `json:"unresolved_interface_names"`
	// Reason is empty exactly when every slug came from a confirmed source.
	Reason string `json:"reason"`
}

type BlockFieldSchema struct {
	Name string `json:"name"`
	// Path is dotted WITHIN the block: "links.link.url". It is not a
	// collection field path and cannot be used in --where.
	Path   string  `json:"path"`
	Parent *string `json:"parent"`

	PayloadType           string `json:"payload_type"`
	PayloadTypeConfidence string `json:"payload_type_confidence"`
	// PayloadTypeSource is "graphql" unless the block's config.ts resolved an
	// ambiguity GraphQL cannot: lexical richText and json are the same JSON
	// scalar, and select and radio compile to the same ENUM.
	PayloadTypeSource string `json:"payload_type_source"`

	GraphQLType *string `json:"graphql_type"`
	JSONType    string  `json:"json_type"`
	HasMany     bool    `json:"has_many"`

	// Required is tri-state and is null far more often here than on a
	// collection field: see this file's header for why.
	Required       *bool  `json:"required"`
	RequiredSource string `json:"required_source"`

	Options       []string `json:"options"`
	OptionsSource string   `json:"options_source"`

	RelationTo       []string `json:"relation_to"`
	RelationToSource string   `json:"relation_to_source"`
	Polymorphic      bool     `json:"polymorphic"`

	WriteShape *string `json:"write_shape"`

	// Plumbing marks id/blockName/blockType — Payload's own keys, not this
	// block's content.
	Plumbing bool `json:"plumbing"`

	Label string `json:"label"`

	// Description is the field's own human instruction in the project's own
	// words, read from `admin: { description: '…' }` in the block's config.ts
	// (§7.10). It is a POINTER: null is "nobody wrote one", which is a
	// different fact from an empty string and must never be filled in with a
	// sentence PayCLI made up.
	Description *string `json:"description"`
	// DescriptionSource is "project-source" when Description is non-null and
	// "unknown" when it is null. A plugin's block lives in node_modules, which
	// §7.10 never scans, so every one of its fields reads "unknown" — expected,
	// and stated rather than hidden.
	DescriptionSource string `json:"description_source"`
	// DescriptionKey is the literal config key the text came from
	// ("admin.description"), "" when there is none. Payload has no standard
	// description for a BLOCK, so naming the key is what keeps this output
	// honest about where the words originated.
	DescriptionKey string `json:"description_key"`
}

type BlockFieldView struct {
	// Path is the field's path inside the row: `title`, `section.contentWidth`,
	// `buttons[].label`.
	Path       string   `json:"path"`
	Name       string   `json:"name"`
	Depth      int      `json:"depth"`
	Kind       string   `json:"kind"`
	KindSource string   `json:"kind_source"`
	JSONTypes  []string `json:"json_types"`
	// PayloadType is the declared type when GraphQL or project source has one.
	PayloadType *string `json:"payload_type"`
	// Observed is how many rows (or group/array entries) this field's
	// percentages are relative to.
	Observed      int           `json:"observed"`
	PresencePct   int           `json:"presence_pct"`
	NonNullPct    int           `json:"non_null_pct"`
	Values        []CensusValue `json:"values"`
	EnumLike      bool          `json:"enum_like"`
	Options       []string      `json:"options"`
	OptionsSource string        `json:"options_source"`
	// Required is "true", "false", "likely" or "unknown".
	Required       string   `json:"required"`
	RequiredSource string   `json:"required_source"`
	Accepts        []string `json:"accepts,omitempty"`
	RelationTo     []string `json:"relation_to,omitempty"`
	Plumbing       bool     `json:"plumbing"`
	Description    *string  `json:"description"`
	Sources        []string `json:"sources"`
}

type BlockIssue struct {
	Severity  string `json:"severity"`
	Code      string `json:"code"`
	Path      string `json:"path"`
	BlockType string `json:"block_type,omitempty"`
	Message   string `json:"message"`
	Hint      string `json:"hint,omitempty"`
	// Source names the fact that produced the issue: a declared source
	// (configured, project-source, graphql) or observed-census.
	Source string `json:"source"`
}

type BlockKnowledge struct {
	Kind string
	Slug string
	// Entity is this entity's census, nil when none was read.
	Entity *CensusEntity
	// Census is the whole census, used for cross-entity facts about a block
	// type (a block used on pages and posts is the same block).
	Census *Census
	// Shard is the entity's field schema, nil when discovery had none.
	Shard *Shard
	// contains filtered or unexported fields
}

type BlockResolution struct {
	// Slugs are the blockType values the REST API accepts for this field, or
	// nil when nothing could resolve them. nil and empty mean different
	// things: nil is "PayCLI does not know".
	Slugs []string
	// Source is how THIS field was resolved: the weakest provenance among its
	// slugs, so a single inferred member downgrades the whole field.
	Source string
	// SlugSources gives each returned slug its own provenance, so an agent can
	// tell a slug confirmed from project source apart from one inferred from
	// an interfaceName.
	SlugSources map[string]string
	// SlugInterfaces pairs each slug with the GraphQL union member it was
	// resolved from. It is what makes a block's own field schema reachable:
	// the fields are published under the interfaceName (CallToActionBlock)
	// while everything writable is keyed by the slug (cta), and without the
	// pair the two halves cannot be joined.
	SlugInterfaces map[string]string
	// Interfaces is the field's GraphQL union possibleTypes, verbatim. They
	// are reported, never returned as slugs: feeding an interfaceName back to
	// the API is exactly the silent-wrong-answer this type exists to prevent.
	Interfaces []string
	// Unresolved are union members no source could name, i.e. slugs that are
	// missing from Slugs even though the API accepts them.
	Unresolved []string
	// Reason is the plain-words explanation of why the answer is less than
	// confirmed. It is empty only when every slug came from a confirmed
	// source; when Slugs is nil it is §7.10's publishable_reason.
	Reason string
}

type BlockSchemaView struct {
	BlockType     string           `json:"block_type"`
	InterfaceName string           `json:"interface_name,omitempty"`
	Label         *string          `json:"label"`
	Description   *string          `json:"description"`
	Count         int              `json:"count"`
	Docs          int              `json:"docs"`
	UsedIn        []BlockUse       `json:"used_in"`
	Sources       []string         `json:"sources"`
	Fields        []BlockFieldView `json:"fields"`
	Required      []string         `json:"required_fields"`
	Likely        []string         `json:"likely_required"`
	BestInstance  *CensusRef       `json:"best_instance"`
}

type BlockSourceDecl struct {
	File     string
	Fields   []BlockSourceField
	Complete bool
	// LabelSingular and LabelPlural are the block's `labels:` literals. They
	// are the human name of the block — "Call to Action" for slug cta — and
	// are "" when the project declares none, never a title-cased guess.
	LabelSingular string
	LabelPlural   string
	// Description is what this block is FOR, in the project's own words, and
	// DescriptionKey is the config key it was read from. Payload defines NO
	// standard description for a block, so the key is always reported with the
	// text: see config.DescriptionKeys.
	Description    string
	DescriptionKey string
}

type BlockSourceField struct {
	Name     string
	Type     string
	Required *bool
	// Description is the field's own `admin: { description: '…' }` — the
	// per-field instruction an agent needs while filling that field in
	// ("Pass a media document id"). "" is "the project's authors wrote none".
	Description string
	// DescriptionKey is the literal config path the text came from,
	// "admin.description" in the normal case.
	DescriptionKey string
}

type BlockSources struct {
	// Configured is the profile's blocks map, keyed by field path. A pin is an
	// explicit statement by the operator and outranks everything.
	Configured map[string][]string
	// ProjectSource is §7.10's local filesystem scan result — every slug:
	// literal found in an object that also has fields:. It is a PROJECT-WIDE
	// bag with no field attribution, so it is never the answer for a field on
	// its own; it only supplies the vocabulary SlugByInterface indexes.
	ProjectSource []string
	// ProjectSourceFiles are the absolute paths each slug came from, recorded
	// in diagnostics.block_slug_files[].
	ProjectSourceFiles []string
	// SlugByInterface maps an interfaceName declared in project source to the
	// slug declared beside it in the same object literal. This is what turns a
	// per-field union member into a writable blockType.
	SlugByInterface map[string]string
	// Observed are blockType values seen in sampled documents, keyed by field
	// path. On a fresh project this yields nothing — verified that all 12 live
	// pages have layout: [].
	Observed map[string][]string
	// SourceDecls are the block declarations §7.10's scan read off disk,
	// keyed by slug. They carry the one fact GraphQL cannot supply for a block
	// — `required: true` — because Payload publishes no input type for a block
	// type. A slug absent from this map is a block PayCLI has no source for,
	// which is the normal case for every plugin-provided block.
	SourceDecls map[string]BlockSourceDecl
}

type BlockTypeSchema struct {
	Slug string `json:"slug"`
	// InterfaceName is the GraphQL union member this schema was read from. It
	// is NOT writable — sending it as a blockType is the §7.10 mistake.
	InterfaceName string `json:"interface_name"`
	// Fields are the block's own fields plus its three plumbing keys, in
	// GraphQL order, with nested group/array interiors flattened into dotted
	// paths.
	Fields []BlockFieldSchema `json:"fields"`
	// FieldsSource is "graphql" when the object type was readable and
	// "unknown" when it was not.
	FieldsSource string `json:"fields_source"`
	// RequiredSource is the summary across the block's content fields: the one
	// source when every field agreed, "mixed" when they did not (including
	// when SOME field is unknown), and "unknown" when nothing answered for any
	// of them. RequiredUnknown and Reason name the gaps precisely.
	RequiredSource string `json:"required_source"`
	// RequiredUnknown names every content field whose required is null, so an
	// agent can see the gap without walking the list.
	RequiredUnknown []string `json:"required_unknown"`
	// ConfigFile is the absolute path required-ness was read from, or "" when
	// no project source declared this slug.
	ConfigFile string `json:"config_file"`
	// PlumbingNote explains id/blockName/blockType in one line.
	PlumbingNote string `json:"plumbing_note"`
	// Reason is empty exactly when every content field's required-ness is
	// known; otherwise it says in plain words what is missing and why.
	Reason string `json:"reason"`

	// Label and LabelPlural are the block's human name, read from its
	// `labels: { singular, plural }` (§7.10). They are POINTERS because a
	// project that declares none has none: null is the honest answer, and
	// title-casing the slug would manufacture a label the admin UI never
	// shows.
	Label       *string `json:"label"`
	LabelPlural *string `json:"label_plural"`
	// LabelsSource is "project-source" when the labels were read off disk and
	// "unknown" when they were not.
	LabelsSource string `json:"labels_source"`

	// Description is the one-sentence statement of what this block is FOR —
	// the fact that lets an agent choose between cta, content and mediaBlock
	// without opening the project. null when the project's authors wrote none.
	Description *string `json:"description"`
	// DescriptionSource is "project-source" or "unknown".
	DescriptionSource string `json:"description_source"`
	// DescriptionKey is the config key the text was read from —
	// "custom.description", "custom.docs" or "custom.summary". It is reported
	// because Payload defines NO description for a block: a Block's `admin`
	// accepts only components/custom/disableBlockName/group/images/jsx and
	// `tsc --noEmit` rejects `admin: { description }` on one, so the text is
	// always project convention rather than a standard field, and saying which
	// key it came from is the difference between reporting and implying.
	DescriptionKey string `json:"description_key"`
	// DocsReason is empty exactly when both the label and the description were
	// found; otherwise it says in plain words which is missing and why.
	DocsReason string `json:"docs_reason"`
}

type BlockUse struct {
	Kind  string `json:"kind"`
	Slug  string `json:"slug"`
	Path  string `json:"path"`
	Count int    `json:"count"`
}

type BlockValidation struct {
	CheckedRows int          `json:"checked_rows"`
	Errors      int          `json:"errors"`
	Warnings    int          `json:"warnings"`
	Issues      []BlockIssue `json:"issues"`
}

type Capabilities struct {
	GraphQL         GraphQLCapability `json:"graphql"`
	Localization    Localization      `json:"localization"`
	Reorder         *bool             `json:"reorder"`
	OG              *bool             `json:"og"`
	MethodOverride  *bool             `json:"method_override"`
	Jobs            Jobs              `json:"jobs"`
	Preferences     Preferences       `json:"preferences"`
	CustomEndpoints []string          `json:"custom_endpoints"`
}

type Census struct {
	CensusVersion int       `json:"census_version"`
	Scope         string    `json:"scope"`
	CLIVersion    string    `json:"cli_version"`
	UpdatedAt     time.Time `json:"updated_at"`
	// Collections and Globals are keyed by slug. Entities are built and
	// refreshed independently, so each carries its own built_at.
	Collections map[string]*CensusEntity `json:"collections"`
	Globals     map[string]*CensusEntity `json:"globals"`
}

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

type CensusChange struct {
	Change    string `json:"change"` // added | removed | not_seen
	What      string `json:"what"`   // block_type | field | path | path_type
	Entity    string `json:"entity"`
	BlockType string `json:"block_type,omitempty"`
	Path      string `json:"path,omitempty"`
	Message   string `json:"message"`
}

type CensusEntity struct {
	Slug    string    `json:"slug"`
	Kind    string    `json:"kind"`
	BuiltAt time.Time `json:"built_at"`
	// Draft reports that documents were read with draft=true, i.e. the census
	// describes the newest draft of every document, which is what an editor
	// is about to overwrite.
	Draft bool `json:"draft"`
	// Select is the top-level field projection the read used; empty means the
	// whole document was read.
	Select      []string `json:"select"`
	DocsScanned int      `json:"docs_scanned"`
	TotalDocs   *int     `json:"total_docs"`
	// Truncated is true when the entity has more documents than were read.
	Truncated bool `json:"truncated"`
	// StoppedEarly is true when the read stopped after a full page with no
	// block row at all: the entity does not use blocks.
	StoppedEarly bool `json:"stopped_early,omitempty"`
	MaxDocs      int  `json:"max_docs"`
	Requests     int  `json:"requests"`
	// RelationProbe says whether the depth-1 relationship probe ran: "ok",
	// "none" (nothing to probe), "failed" or "skipped".
	RelationProbe string `json:"relation_probe"`
	// Error is set when the read failed; the entity then carries whatever was
	// learned before the failure.
	Error string `json:"error,omitempty"`
	// FoldedDocs counts the distinct documents PayCLI's own successful writes
	// folded into this entity after it was read (OverlayDocs): the census
	// then also knows the shapes those writes created, without another read.
	FoldedDocs int `json:"folded_docs,omitempty"`
	// DocKeys are the ids of the documents the read counted ("_global" for a
	// global) and FoldedKeys those of the documents folded in since. They are
	// references, like Instances, never content; OverlayDocs uses them to
	// count every document once however often it is written (§7.10c).
	DocKeys    []string               `json:"doc_keys,omitempty"`
	FoldedKeys []string               `json:"folded_keys,omitempty"`
	BlockRows  int                    `json:"block_rows"`
	Paths      map[string]*CensusPath `json:"paths"`
	Types      map[string]*CensusType `json:"types"`
}

type CensusField struct {
	Kind string `json:"kind"`
	// KindSource is observed-census, or observed-depth-1 when the kind was
	// settled by the relationship probe.
	KindSource string `json:"kind_source"`
	// Types counts JSON types: string, number, boolean, object, array, null.
	Types    map[string]int `json:"types"`
	Present  int            `json:"present"`
	NonNull  int            `json:"non_null"`
	NonEmpty int            `json:"non_empty"`
	// Values are the most common scalar values with their counts. For a field
	// that is not enum-like only REPEATED values are kept: a value seen once is
	// content, not vocabulary.
	Values         []CensusValue `json:"values,omitempty"`
	Distinct       int           `json:"distinct"`
	DistinctCapped bool          `json:"distinct_capped,omitempty"`
	EnumLike       bool          `json:"enum_like"`
	// Accepts counts blockTypes for a nested blocks field.
	Accepts map[string]int `json:"accepts,omitempty"`
	// Items is the total number of array / blocks rows observed.
	Items int `json:"items,omitempty"`
	// Fields are a group's keys or an array row's keys.
	Fields map[string]*CensusField `json:"fields,omitempty"`
	// Optional is set when a document the census already counted was folded
	// in (OverlayDocs) holding this field empty, or holding it at all for the
	// first time: the server keeps such a row, so the field is never reported
	// likely_required, whatever the counts say.
	Optional bool `json:"optional,omitempty"`
	// contains filtered or unexported fields
}

type CensusOptions struct {
	Client  *payload.Client
	Now     func() time.Time
	MaxDocs int
	// Concurrency bounds how many entities are read at once.
	Concurrency int
	// NoRelationProbe skips the depth-1 re-read of up to three documents per
	// entity that turns an id-looking number into a relationship or upload.
	NoRelationProbe bool
	Logger          *slog.Logger
}

type CensusPath struct {
	Path string `json:"path"`
	// Parent is the enclosing blocks pattern ("" at the top level).
	Parent string `json:"parent"`
	// ParentTypes counts the blockType of the row that owns this field, so a
	// nested pattern knows it is `group.blocks` in 30 rows and `grid.blocks`
	// in 12.
	ParentTypes map[string]int `json:"parent_types,omitempty"`
	// Field is the key inside the parent row (`blocks`), or the top-level
	// field path for a top-level pattern.
	Field string `json:"field"`
	// Types counts every blockType seen at this pattern.
	Types map[string]int `json:"types"`
	Rows  int            `json:"rows"`
	Docs  int            `json:"docs"`
	// EmptyRows are `{}` entries — the orphan rows Payload's Postgres adapter
	// leaves behind after a nested block restructure.
	EmptyRows int `json:"empty_rows"`
	// UntypedRows are non-empty rows with no blockType.
	UntypedRows int `json:"untyped_rows"`
}

type CensusRef struct {
	Kind string `json:"kind"`
	Slug string `json:"slug"`
	ID   any    `json:"id,omitempty"`
	// Path is the concrete row path, e.g. layout[1].blocks[0].
	Path string `json:"path"`
	// Score is the number of non-empty fields on the row.
	Score int `json:"score"`
}

type CensusTarget struct {
	Kind string
	Slug string
	// Draft asks for the newest draft of every document. It is set unless the
	// entity is known NOT to have drafts; Payload ignores draft=true on an
	// entity without versions, so an unknown answer costs nothing.
	Draft bool
	// Select narrows the read to the top-level fields that can hold blocks.
	// Empty means "read everything" — the answer when no field list is known.
	Select []string
}

type CensusType struct {
	Slug  string `json:"slug"`
	Count int    `json:"count"`
	Docs  int    `json:"docs"`
	// UsedIn counts rows per path pattern.
	UsedIn map[string]int `json:"used_in"`
	// Fields are the row's keys, excluding id and blockType.
	Fields map[string]*CensusField `json:"fields"`
	// Instances reference the most complete real rows, most complete first.
	Instances []CensusRef `json:"instances"`
}

type CensusValue struct {
	Value any `json:"value"`
	Count int `json:"count"`
}

type Collection struct {
	Slug         string        `json:"slug"`
	Labels       Labels        `json:"labels"`
	GraphQL      *GraphQLNames `json:"graphql"`
	IDType       string        `json:"id_type"`
	IDTypeSource string        `json:"id_type_source"`
	Reachability string        `json:"reachability"`
	Internal     bool          `json:"internal"`

	Publishable       bool    `json:"publishable"`
	PublishableReason *string `json:"publishable_reason"`

	Flags       Flags       `json:"flags"`
	FlagsSource FlagsSource `json:"flags_source"`
	Permissions Permissions `json:"permissions"`

	Stats Stats `json:"stats"`

	FieldsCount  int    `json:"fields_count"`
	FieldsSHA256 string `json:"fields_sha256"`
	FieldsShard  string `json:"fields_shard"`
	FieldsSource string `json:"fields_source"`

	TitleField *string  `json:"title_field"`
	DateFields []string `json:"date_fields"`
	Warnings   []string `json:"warnings"`
}

type Diagnostics struct {
	Requests          int      `json:"requests"`
	ElapsedMS         int64    `json:"elapsed_ms"`
	Bytes             int64    `json:"bytes"`
	GraphQLBatches    int      `json:"graphql_batches"`
	Degraded          []string `json:"degraded"`
	Warnings          []string `json:"warnings"`
	CreatedAndDeleted []string `json:"created_and_deleted"`
	AuthCandidates    []string `json:"auth_candidates"`
	BlockSlugFiles    []string `json:"block_slug_files"`
}

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

type Field struct {
	Name        string  `json:"name"`
	Path        string  `json:"path"`
	GraphQLPath string  `json:"graphql_path"`
	Parent      *string `json:"parent"`

	PayloadType           string `json:"payload_type"`
	PayloadTypeConfidence string `json:"payload_type_confidence"`

	GraphQLType *string `json:"graphql_type"`
	JSONType    string  `json:"json_type"`

	Required       *bool  `json:"required"`
	RequiredSource string `json:"required_source"`

	HasMany         bool   `json:"has_many"`
	Localized       *bool  `json:"localized"`
	LocalizedSource string `json:"localized_source"`

	ReadOnly bool `json:"read_only"`

	Options       []string `json:"options"`
	OptionsSource string   `json:"options_source"`

	RelationTo       []string `json:"relation_to"`
	RelationToSource string   `json:"relation_to_source"`
	Polymorphic      bool     `json:"polymorphic"`

	// WriteShape is mandatory and non-null on every relationship, upload and
	// polymorphic field and null on every other kind. §9.10's --set coercion
	// reads exactly this key.
	WriteShape *string `json:"write_shape"`

	Queryable bool     `json:"queryable"`
	Operators []string `json:"operators"`

	Sortable           bool   `json:"sortable"`
	SortableConfidence string `json:"sortable_confidence"`

	HookMutated string `json:"hook_mutated"`

	Label string `json:"label"`
}

type FieldDoc struct {
	Description string `json:"description"`
	Key         string `json:"key"`
	// Source is "project-source"; it exists so that a single entry is
	// self-describing when it is lifted out of the map.
	Source string `json:"source"`
}

type Fingerprint struct {
	TopologySHA256 string    `json:"topology_sha256"`
	SchemaSHA256   string    `json:"schema_sha256"`
	CheckedAt      time.Time `json:"checked_at"`
	ServerIdentity string    `json:"server_identity"`
}

type Flags struct {
	Upload            *bool `json:"upload"`
	Auth              *bool `json:"auth"`
	UseAPIKey         *bool `json:"use_api_key"`
	Versions          *bool `json:"versions"`
	Drafts            *bool `json:"drafts"`
	Trash             *bool `json:"trash"`
	Folders           *bool `json:"folders"`
	Duplicate         *bool `json:"duplicate"`
	Orderable         *bool `json:"orderable"`
	EndpointsDisabled *bool `json:"endpoints_disabled"`
}

type FlagsSource struct {
	Upload            string `json:"upload"`
	Auth              string `json:"auth"`
	UseAPIKey         string `json:"use_api_key"`
	Versions          string `json:"versions"`
	Drafts            string `json:"drafts"`
	Trash             string `json:"trash"`
	Folders           string `json:"folders"`
	Duplicate         string `json:"duplicate"`
	Orderable         string `json:"orderable"`
	EndpointsDisabled string `json:"endpoints_disabled"`
}

type Global struct {
	Slug         string        `json:"slug"`
	Labels       Labels        `json:"labels"`
	GraphQL      *GraphQLNames `json:"graphql"`
	Reachability string        `json:"reachability"`
	Internal     bool          `json:"internal"`

	Flags       GlobalFlags       `json:"flags"`
	FlagsSource GlobalFlagsSource `json:"flags_source"`
	Permissions GlobalPermissions `json:"permissions"`

	FieldsCount  int    `json:"fields_count"`
	FieldsSHA256 string `json:"fields_sha256"`
	FieldsShard  string `json:"fields_shard"`
	FieldsSource string `json:"fields_source"`

	Warnings []string `json:"warnings"`
}

type GlobalFlags struct {
	Versions *bool `json:"versions"`
	Drafts   *bool `json:"drafts"`
}

type GlobalFlagsSource struct {
	Versions string `json:"versions"`
	Drafts   string `json:"drafts"`
}

type GlobalPermissions struct {
	Read         bool  `json:"read"`
	Update       bool  `json:"update"`
	ReadVersions bool  `json:"read_versions"`
	FieldLevel   *bool `json:"field_level"`
}

type GraphQLCapability struct {
	Mode          string `json:"mode"`
	Introspection *bool  `json:"introspection"`
	Path          string `json:"path"`
	Detail        string `json:"detail,omitempty"`
	Hint          string `json:"hint,omitempty"`
}

type GraphQLNames struct {
	Singular string `json:"singular"`
	Plural   string `json:"plural,omitempty"`
	Count    string `json:"count,omitempty"`
	Source   string `json:"source"`
}

type IDLadderInput struct {
	// GraphQL is the Stage-1 answer, "" when GraphQL was unavailable.
	GraphQL string
	// SampleID is docs[0].id from GET /{slug}?limit=1&depth=0&select[id]=true.
	SampleID any
	// SampleIDPresent distinguishes "the collection is empty" from "id was
	// null".
	SampleIDPresent bool
	// VersionParentID is docs[0].parent from /{slug}/versions, which is the
	// *document* id while the version's own id is a different row.
	VersionParentID      any
	VersionParentPresent bool
	// Configured is the profile's id_type pin.
	Configured string
}

type Identity struct {
	AuthMode             string  `json:"auth_mode"`
	AuthCollection       *string `json:"auth_collection"`
	AuthCollectionSource string  `json:"auth_collection_source"`
	UserID               any     `json:"user_id"`
	Verified             bool    `json:"verified"`
	CanAccessAdmin       bool    `json:"can_access_admin"`
	Strategy             string  `json:"strategy"`
	KeyFingerprint       string  `json:"key_fingerprint"`
}

type IntroArg struct {
	Name string   `json:"name"`
	Type *TypeRef `json:"type"`
}

type IntroEnumValue struct {
	Name string `json:"name"`
}

type IntroField struct {
	Name string     `json:"name"`
	Args []IntroArg `json:"args"`
	Type *TypeRef   `json:"type"`
}

type IntroInputField struct {
	Name string   `json:"name"`
	Type *TypeRef `json:"type"`
}

type IntroType struct {
	Kind          string            `json:"kind"`
	Name          string            `json:"name"`
	Fields        []IntroField      `json:"fields"`
	InputFields   []IntroInputField `json:"inputFields"`
	EnumValues    []IntroEnumValue  `json:"enumValues"`
	PossibleTypes []IntroTypeName   `json:"possibleTypes"`
}

type IntroTypeName struct {
	Name string `json:"name"`
	Kind string `json:"kind"`
}

type Jobs struct {
	Collection  *string `json:"collection"`
	StatsGlobal *string `json:"stats_global"`
}

type Kind struct {
	PayloadType string
	Confidence  string
	JSONType    string
	HasMany     bool
	ReadOnly    bool
	Polymorphic bool

	Options       []string
	OptionsSource string

	RelationTo       []string
	RelationToSource string

	// Blocks is the UNION member list for a blocks field. These are
	// interfaceNames, NOT blockType slugs — §7.10 resolves the real slugs from
	// project source.
	BlockInterfaces []string

	// Children is the named type whose fields should be walked as nested
	// group/array entries, or "" when there are none.
	Children string
	// Leaves are type names this inference needs resolved to be complete.
	Leaves []string
}

type Labels struct {
	Singular string `json:"singular"`
	Plural   string `json:"plural"`
	Source   string `json:"source"`
}

type LearnedFailure struct {
	Operator   string    `json:"operator"`
	Collection string    `json:"collection"`
	Evidence   string    `json:"evidence"`
	LearnedAt  time.Time `json:"learned_at"`
}

type Limitation struct {
	Code       string `json:"code"`
	Entity     string `json:"entity,omitempty"`
	Field      string `json:"field,omitempty"`
	Detail     string `json:"detail,omitempty"`
	Mitigation string `json:"mitigation"`
}

type LocaleAnalysis struct {
	// Candidates are the true locale codes, or nil when the sample proved
	// nothing. These are real codes, unlike the formatName()-mangled names the
	// GraphQL LocaleInputType enum exposes.
	Candidates []string
	// Localized are the field names that came back as a locale map.
	Localized []string
	// NotLocalized are the field names that did not, on a document where at
	// least one sibling did — which is the only evidence REST offers for a
	// per-field false.
	NotLocalized []string
}

type LocaleInput struct {
	// Configured is the profile's locales pin.
	Configured []string
	// Analysis is the locale=all sample result.
	Analysis LocaleAnalysis
	// EnumNames are LocaleInputType's enumValues, which are
	// formatName()-mangled and are therefore NEVER usable as codes.
	EnumNames []string
	// GraphQLReachable reports whether the cross-validation could run at all.
	GraphQLReachable bool
}

type Localization struct {
	Enabled *bool `json:"enabled"`
	// EnabledSource is the story behind `enabled`, which §7.8.3 requires of
	// every derived fact: "graphql-arg" / "graphql-arg-absent" when the plural
	// Query field settled it, "locale-all" when a ?locale=all sample proved it
	// positively, "configured" when the profile pinned locale codes, and
	// "unknown" while it is still nil.
	EnabledSource string   `json:"enabled_source"`
	Locales       []string `json:"locales"`
	// Default is Payload's localization.defaultLocale. No API exposes it, so
	// it is null unless something actually established it — it is NEVER the
	// first entry of a sorted locale list (§21.3 rule 1: a defaulted value is
	// not a discovered fact).
	Default         *string `json:"default"`
	DefaultSource   string  `json:"default_source"`
	LocalesSource   string  `json:"locales_source"`
	FallbackDefault *string `json:"fallback_default"`
	LocaleCount     *int    `json:"locale_count"`
}

type Manifest struct {
	ManifestVersion int       `json:"manifest_version"`
	Generation      string    `json:"generation"`
	CLIVersion      string    `json:"cli_version"`
	GeneratedAt     time.Time `json:"generated_at"`
	ExpiresAt       time.Time `json:"expires_at"`

	Meta        ManifestMeta `json:"meta"`
	Fingerprint Fingerprint  `json:"fingerprint"`
	Source      Source       `json:"source"`
	Identity    Identity     `json:"identity"`

	Capabilities Capabilities `json:"capabilities"`

	Collections []*Collection `json:"collections"`
	Globals     []*Global     `json:"globals"`

	Unreachable             []Unreachable         `json:"unreachable"`
	Limitations             []Limitation          `json:"limitations"`
	UnsupportedOperators    []UnsupportedOperator `json:"unsupported_operators"`
	LearnedOperatorFailures []LearnedFailure      `json:"learned_operator_failures"`

	Diagnostics Diagnostics `json:"diagnostics"`
}

type ManifestMeta struct {
	Scope          string    `json:"scope"`
	Profiles       []string  `json:"profiles"`
	BaseURL        string    `json:"base_url"`
	APIPath        string    `json:"api_path"`
	GraphQLPath    string    `json:"graphql_path"`
	HeaderNames    []string  `json:"header_names"`
	KeyFingerprint string    `json:"key_fingerprint"`
	CreatedAt      time.Time `json:"created_at"`
	ConfirmedAt    time.Time `json:"confirmed_at"`
}

type Options struct {
	Client *payload.Client

	BaseURL string

	APIPath       string
	APIPathSource string
	// GraphQLRoute is routes.graphQL, defaulting to /graphql. graphql_path is
	// DERIVED from api_path + this (§1 conflict 34), never an independent
	// literal.
	GraphQLRoute      string
	GraphQLPath       string
	GraphQLPathSource string

	AuthMode       string
	AuthCollection string
	// AuthCollectionSource is "configured" when the slug was pinned.
	AuthCollectionSource string
	// CachedAuthCollection is a slug already resolved for this
	// (normURL, keyFP) pair by a previous run (§7.0e). When set, Stage -1 is
	// skipped entirely.
	CachedAuthCollection string
	// CredentialAbsent reports anonymous operation. Stage 0's /me request is
	// then not made at all and discovery continues.
	CredentialAbsent bool
	KeyFingerprint   string

	Concurrency int

	Profile     string
	Profiles    []string
	ScopeKey    string
	HeaderNames []string

	CLIVersion string
	Generation string
	Now        func() time.Time
	TTL        time.Duration

	// Deep widens Stage 3 to every collection and adds the document census.
	Deep bool
	// AllowWriteProbes enables §7.7's empty-POST harvest. It creates a real
	// document in any collection with no required fields, so it is off by
	// default and the flag name is deliberately unpleasant.
	AllowWriteProbes bool
	// NoLabels skips §7.5 probe 8, which is the only DELETE verb discovery
	// ever issues.
	NoLabels bool
	// NoProbes disables Stage 3 entirely.
	NoProbes bool

	ConfiguredIDType  string
	ConfiguredLocales []string
	ConfiguredBlocks  map[string][]string
	CustomEndpoints   []string

	PayloadVersion       string
	PayloadVersionSource string
	DBAdapter            string
	DBAdapterSource      string

	// ProjectBlockSlugs are §7.10's `slug:` literals found on the local
	// filesystem, and ProjectBlockSlugFiles the absolute files they came from.
	ProjectBlockSlugs     []string
	ProjectBlockSlugFiles []string
	// ProjectBlockInterfaces maps an `interfaceName:` literal found on the
	// local filesystem to the `slug:` declared beside it in the same object
	// (CallToActionBlock -> cta). It is the other half of §7.10: a blocks
	// field's GraphQL union publishes interfaceNames, and only this map turns
	// one into a blockType the REST API will accept. Empty is survivable —
	// every union member then resolves through the interfaceName heuristic and
	// is labelled as inferred — but it is never guessed at silently.
	ProjectBlockInterfaces map[string]string
	// ProjectBlockDecls are the block declarations read off disk, keyed by
	// slug: each block's own `fields:` entries and whether the whole array was
	// parseable. This is the ONLY source of a block field's required-ness —
	// Payload generates no input type for a block type, so §7.4's NON_NULL
	// trick cannot reach inside one. Absent for every plugin-provided block,
	// which is why the answer stays tri-state.
	ProjectBlockDecls map[string]BlockSourceDecl
	// ProjectFieldDocs are the per-field `admin: { description: '…' }`
	// instructions read from the project's own collection and global configs,
	// keyed by entity slug and then by field name, with ProjectFieldDocFiles
	// naming the file each entity's came from.
	//
	// Payload publishes admin.description nowhere in the API — it is admin-UI
	// metadata, absent from both REST responses and GraphQL introspection — so
	// the file on disk is the only source there is, and an entity whose config
	// PayCLI cannot see (a plugin's collection lives in node_modules) has none.
	ProjectFieldDocs     map[string]map[string]FieldDoc
	ProjectFieldDocFiles map[string]string
	// ProjectAuthSlugs are auth-collection slug literals from the project's
	// own payload.config.ts, used only to widen Stage -1's candidate set.
	ProjectAuthSlugs []string
	// ProjectRoutes are `routes:` literals, named in the endpoint_not_payload
	// hint when nothing accepted.
	ProjectRoutes []string

	Logger *slog.Logger
}

type Permissions struct {
	Create       bool  `json:"create"`
	Read         bool  `json:"read"`
	Update       bool  `json:"update"`
	Delete       bool  `json:"delete"`
	ReadVersions bool  `json:"read_versions"`
	Unlock       bool  `json:"unlock"`
	FieldLevel   *bool `json:"field_level"`
}

type Preferences struct {
	Collection *string `json:"collection"`
}

type Result struct {
	Manifest *Manifest
	// Shards are keyed by the cache-relative shard path, e.g.
	// "fields/pages.json", so a caller can hand them straight to cache.Set.
	Shards map[string]*Shard

	AuthCollection       string
	AuthCollectionSource string
	// AuthResolved reports that Stage -1 ran and produced a slug worth
	// persisting to auth-resolution.json.
	AuthResolved bool

	APIPath           string
	APIPathSource     string
	GraphQLPath       string
	GraphQLPathSource string

	Warnings []output.Warning
}

type Schema struct {
	// Types are the resolved __type results, keyed by type name.
	Types map[string]*IntroType
	// SlugBySingular maps a GraphQL singular type name back to its slug, so a
	// monomorphic relationship target is reported as a slug, never as a type
	// name an agent cannot pass on the command line.
	SlugBySingular map[string]string
}

type Shard struct {
	Generation string  `json:"generation"`
	Slug       string  `json:"slug"`
	SHA256     string  `json:"sha256"`
	Fields     []Field `json:"fields"`
	// JoinFields lists read-only join fields, which must be requested with
	// joins[field][limit] rather than selected like a normal field.
	JoinFields []string `json:"join_fields"`
	// Blocks maps a blocks field's path to its resolved blockType slugs. It is
	// null — not an empty map — when no source could resolve them, which is
	// the difference between "this project has no blocks" and "PayCLI does not
	// know" (§7.10). Every entry is resolved from THAT FIELD's own GraphQL
	// union, so two blocks fields on the same entity can and do carry
	// different lists.
	Blocks map[string][]string `json:"blocks"`
	// BlocksSource is the entity-wide summary: the one source when every
	// blocks field resolved the same way, "mixed" when they did not, "unknown"
	// when the entity has no resolved blocks field at all. It is a SUMMARY —
	// BlockFields[path].Source is the per-field answer and the one an agent
	// should read.
	BlocksSource string `json:"blocks_source"`
	// BlockFields carries the full per-field answer for every blocks field,
	// including each slug's own provenance and the GraphQL union the slugs
	// were derived from. It is null when the entity has no blocks field.
	BlockFields map[string]BlockField `json:"block_fields"`
	// BlockSchemas is every reachable block type's OWN field schema, keyed by
	// blockType slug — what is inside a cta, not merely that cta exists. It is
	// null on a shard written before the key existed and on a REST-only shard
	// (there is no union to read), which is why every consumer treats null as
	// "not discovered" and says so rather than as "this block has no fields".
	BlockSchemas map[string]BlockTypeSchema `json:"block_schemas"`
	// RequiredPaths is the flattened list of paths whose required is true.
	RequiredPaths []string `json:"required_paths"`

	// FieldDocs are the per-field human instructions this entity's own config
	// declares — `admin: { description: '…' }` — keyed by field path.
	//
	// It is a SEPARATE map rather than three more keys on every field entry,
	// and that is a size decision with a measured reason: `pay describe pages`
	// carries ~90 field entries, so three keys each would add ~16 KB to the
	// most frequently run command in order to publish null 90 times. Here the
	// cost is proportional to what the project actually documented, and is
	// nothing at all on a project that documented nothing.
	//
	// FieldDocsSource is what distinguishes "scanned, found none" from "never
	// scanned": a producer records no map rather than an empty one.
	FieldDocs map[string]FieldDoc `json:"field_docs,omitempty"`
	// FieldDocsSource is "project-source" when this entity's config was read
	// off disk and "unknown" when it was not — the normal case for a
	// plugin-provided collection, whose config lives in node_modules.
	FieldDocsSource string `json:"field_docs_source,omitempty"`
	// FieldDocsFile is the absolute path the docs were read from, "" when
	// there is none.
	FieldDocsFile string `json:"field_docs_file,omitempty"`
}

type ShardLookup func(kind, slug string) *Shard

type Source struct {
	BaseURL              string  `json:"base_url"`
	APIPath              string  `json:"api_path"`
	APIPathSource        string  `json:"api_path_source"`
	GraphQLPath          string  `json:"graphql_path"`
	GraphQLPathSource    string  `json:"graphql_path_source"`
	PoweredBy            string  `json:"powered_by"`
	PayloadVersion       *string `json:"payload_version"`
	PayloadVersionSource string  `json:"payload_version_source"`
	DBAdapter            string  `json:"db_adapter"`
	DBAdapterSource      string  `json:"db_adapter_source"`
}

type Stats struct {
	TotalDocs *int `json:"total_docs"`
	Sampled   bool `json:"sampled"`
}

type TopologyProjection struct {
	Collections map[string][]string `json:"c"`
	Globals     map[string][]string `json:"g"`
	Admin       bool                `json:"admin"`
}

type TypeRef struct {
	Kind   string   `json:"kind"`
	Name   string   `json:"name"`
	OfType *TypeRef `json:"ofType"`
}

type Unreachable struct {
	Slug   string `json:"slug"`
	Kind   string `json:"kind"`
	Reason string `json:"reason"`
	Detail string `json:"detail"`
}

type UnsupportedOperator struct {
	Operator   string `json:"operator"`
	Collection string `json:"collection,omitempty"`
	Reason     string `json:"reason"`
}