metadata

type ActorMeta struct {
	ID                  string `yaml:"id"`
	MaxConsistencyLevel string `yaml:"maxConsistencyLevel"`
}

type AssemblyCellRef struct {
	// yaml tags drive only marshaling (decode is the custom UnmarshalYAML below);
	// module is omitempty so a round-trip of a same-module ref emits `id: x`
	// rather than `module: ""` (which the decoder rejects as explicit-empty).
	ID     string `yaml:"id"`
	Module string `yaml:"module,omitempty"`
}

type AssemblyMeta struct {
	ID    string            `yaml:"id"`
	Cells []AssemblyCellRef `yaml:"cells"`
	Owner OwnerMeta         `yaml:"owner"`
	// The assembly's provisioned capability set is NOT declared here — it is the
	// derived union of its cells' CellMeta.Requires (Design Y, #855). There is no
	// hand-authored assembly-level `capabilities` field; the single source is
	// per-cell. kernel/assembly.GenerateModulesGen computes the union when
	// rendering generatedCapabilities() in modules_gen.go.
	Build               BuildMeta `yaml:"build,omitempty"`
	MaxConsistencyLevel string    `yaml:"-"` // derived; yaml occurrence rejected by KnownFields
	Dir                 string    `yaml:"-"` // assembly directory name (parts[1]); set by parser from path, not YAML
	File                string    `yaml:"-"` // parsed assembly.yaml path relative to project root
}

type BuildMeta struct {
	Entrypoint     string `yaml:"entrypoint,omitempty"`
	Binary         string `yaml:"binary,omitempty"`
	DeployTemplate string `yaml:"deployTemplate,omitempty"`
	// CompositionAPI when true instructs GenerateModulesGen to emit the
	// runtime/composition.CellModule form (cellmodules/ module functions) instead
	// of the legacy local-CellModule-type form used by examples/.
	// Set to true in assemblies that use cellmodules/{cell}.Module() constructors
	// (currently only assemblies/corebundle/assembly.yaml).
	CompositionAPI bool `yaml:"compositionAPI,omitempty"`
}

type CellMeta struct {
	ID               string `yaml:"id"`
	Type             string `yaml:"type"`             // "core"|"edge"|"support"
	ConsistencyLevel string `yaml:"consistencyLevel"` // "L0"-"L4"
	DurabilityMode   string `yaml:"durabilityMode"`   // "demo"|"durable" (advisory for L2+)
	// Lifecycle is the governance maturity phase
	// (experimental|candidate|asset|maintenance|retired). Optional; empty
	// defaults to experimental at BaseCell construction. Distinct from the
	// runtime cellState and from a Contract's draft/active/deprecated lifecycle
	// — see kernel/cellvocab.CellLifecycle. The parser stays lenient (membership
	// is enforced by cell.schema.json enum + governance CELL-LIFECYCLE-01 +
	// NewBaseCell's ParseCellLifecycle), matching the durabilityMode/requires
	// posture.
	Lifecycle      string         `yaml:"lifecycle,omitempty"`
	Owner          OwnerMeta      `yaml:"owner"`
	Schema         SchemaMeta     `yaml:"schema"`
	Verify         CellVerifyMeta `yaml:"verify"`
	L0Dependencies []L0DepMeta    `yaml:"l0Dependencies"`
	// GoStructName is a schema extension consumed by tools/codegen — kernel
	// itself does not interpret its value. Cells that opt into K#04 codegen
	// MUST set this; non-codegen cells leave it empty. There is no reliable
	// automatic mapping from a lowercased cell id to its conventional CamelCase
	// Go type (e.g. "ordercell" → "OrderCell"), which is why explicit
	// declaration is required.
	GoStructName GoIdentifier `yaml:"goStructName,omitempty"`
	// Requires lists the assembly-level shared infrastructure capabilities this
	// cell consumes (postgres / redis / rabbitmq). It is the authoritative single
	// source: the owning assembly's provisioned capability set is the derived
	// union of its cells' Requires (see kernel/assembly.GenerateModulesGen). The
	// closed value set is mirrored by CapabilityEnum + runtime/capability.Kind +
	// cell.schema.json `requires` enum; unknown/duplicate values are rejected by
	// `gocell validate` governance rule FMT-36 (validation-time, not by ParseFS —
	// the parser stays lenient, matching Kubernetes admission-layer validation).
	// "Requires" names what the cell consumes; it declares intent, not a uniform
	// hardness contract. Whether a listed capability is hard-required or
	// best-effort is decided per kind by the provisioner (cmd/corebundle
	// provisionCapabilities): postgres is hard-required in non-memory storage
	// modes (absence fails fast at the cell's nil-guard); redis is
	// provision-if-available (absence degrades gracefully — e.g. accesscore's
	// AUTH-CACHE-01 session cache is skipped when no redis client is configured).
	Requires []string `yaml:"requires,omitempty"`
	Dir      string   `yaml:"-"` // directory segment under cells/, set by parser
	File     string   `yaml:"-"` // parsed cell.yaml path relative to project root
}

type CellVerifyMeta struct {
	Smoke []string `yaml:"smoke"`
}

type CellWireBundle struct {
	Listeners  []WireBundleListener
	Routes     []WireBundleRoute
	Subscribes []WireBundleSubscribe
}

type CellWireSummary struct {
	CellID     string              `json:"cellId"     yaml:"cellId"`
	Listeners  []WireListenerView  `json:"listeners"  yaml:"listeners"`
	Routes     []WireRouteView     `json:"routes"     yaml:"routes"`
	Subscribes []WireSubscribeView `json:"subscribes" yaml:"subscribes"`
}

type ContractMeta struct {
	ID   string `yaml:"id"`
	Kind string `yaml:"kind"` // http|event|command|projection|webhook|grpc|saga
	// Transports is the non-empty SET of wire transports this contract is
	// sanctioned to bind to (e.g. [amqp, mqtt] for an event published over both
	// brokers). When the contract.yaml omits `transports:`, parser.parseContract
	// defaults it per kind (event/command→[amqp], http/webhook→[http],
	// grpc→[grpc], projection/saga→[internal]) so every existing contract stays
	// byte-identical. Each member MUST be one of cellvocab.AllTransports();
	// kind↔transport compatibility is enforced by governance FMT-39. contractgen
	// derives the generated ContractSpec.Transport as the primary (Transports[0])
	// and emits the full exported set for multi-transport contracts.
	// ref: asyncapi/spec channel.servers (transport set); k8s SetDefaults (per-kind default).
	Transports       []string `yaml:"transports,omitempty"`
	OwnerCell        string   `yaml:"ownerCell"`
	ConsistencyLevel string   `yaml:"consistencyLevel"`
	Lifecycle        string   `yaml:"lifecycle"` // draft|active|deprecated
	// Triggers lists the outbox event topics emitted by this contract's owner
	// cell when the HTTP handler succeeds. Required for L2+ HTTP contracts.
	// Each value MUST be a string literal or named constant (dto.TopicX /
	// domain.TopicX); dynamic expressions (fmt.Sprintf, variables) are rejected
	// by CONTRACT-CONSISTENCY-EMIT-01. Validated bidirectionally against
	// outbox.Emit call sites in cells/<ownerCell>/slices/**/service.go.
	Triggers   []string       `yaml:"triggers,omitempty"`
	Endpoints  EndpointsMeta  `yaml:"endpoints"`
	SchemaRefs SchemaRefsMeta `yaml:"schemaRefs,omitempty"`
	// Saga carries the orchestration definition for kind=saga contracts (steps,
	// timeout, compensationOrder). Nil for all other kinds. Parsed under strict
	// KnownFields decode; the declarative mirror lives in
	// schemas/contract.schema.json. contractgen derives typed step I/O structs +
	// an Impl interface + BuildDefinition/Register from it (PR-07).
	Saga              *SagaMeta `yaml:"saga,omitempty"`
	Replayable        *bool     `yaml:"replayable,omitempty"`
	IdempotencyKey    string    `yaml:"idempotencyKey,omitempty"`
	DeliverySemantics string    `yaml:"deliverySemantics,omitempty"`
	// Codegen opts the contract into `gocell generate contract` output.
	// When true, contractgen produces types_gen.go / iface_gen.go (and
	// handler_gen.go for kind=http) under generated/contracts/<kind>/<...>/v<N>/.
	//
	// K#09 funnel: parser.parseContract defaults this to true when the
	// contract.yaml omits the `codegen:` key (detected via yaml AST in
	// contractYAMLHasKey). Explicit `codegen: false` is the only way to
	// opt out. Scaffold output omits the field entirely so the funnel is
	// the single source of truth (INVARIANT SCAFFOLD-BUNDLE-NO-CODEGEN-LITERAL-01).
	Codegen bool `yaml:"codegen,omitempty"`
	// Direction is the webhook flow direction: "inbound" (external → cell) or
	// "outbound" (cell → external). Only populated for kind=webhook.
	Direction string `yaml:"direction,omitempty"`
	// Signature holds the webhook signature verification metadata. Only
	// populated for kind=webhook contracts.
	Signature *WebhookSignatureMeta `yaml:"signature,omitempty"`
	// Payload holds webhook payload constraints. Only populated for
	// kind=webhook contracts.
	Payload *WebhookPayloadMeta `yaml:"payload,omitempty"`
	// Description / DeprecatedAt are documentation only — excluded from
	// structural fingerprint via fingerprint:"-".
	Description  string `yaml:"description,omitempty" fingerprint:"-"`
	DeprecatedAt string `yaml:"deprecatedAt,omitempty" fingerprint:"-"`
	// Dir / File are parsed-time fields tracking contract.yaml location relative
	// to the project root; never persisted, hence yaml:"-".
	Dir  string `yaml:"-" fingerprint:"-"`
	File string `yaml:"-" fingerprint:"-"`
}

type ContractSchemaRef struct {
	Field string
	Ref   string
	Scope SchemaRefScope
}

type ContractUsage struct {
	Contract string `yaml:"contract"`
	Role     string `yaml:"role"` // serve|call|publish|subscribe|handle|invoke|provide|read|webhook-receive|webhook-dispatch
	// Handler is the consumer handler method name on the slice's service/consumer
	// struct field; REQUIRED for role=subscribe and role=webhook-receive, forbidden
	// otherwise (including role=webhook-dispatch). Single source for the
	// reg.Subscribe / reg.RegisterWebhookReceiver handler expression that cellgen emits.
	Handler string `yaml:"handler,omitempty"`
	// Group is the broker consumer group for role=subscribe; optional, defaults to
	// the owning cell ID when empty. Forbidden for non-subscribe roles (including
	// webhook-receive and webhook-dispatch).
	Group string `yaml:"group,omitempty"`
	// Field optionally names the cell-struct field holding the consumer slice's
	// service, disambiguating slices that own more than one *sliceID.T field
	// (e.g. a route Handler plus a subscribe Consumer or a webhook receiver).
	// Optional for role=subscribe, role=webhook-receive, and role=webhook-dispatch
	// (cellgen resolves by package convention when empty); forbidden for all other
	// roles.
	Field string `yaml:"field,omitempty"`
	// SourceID is the secret-isolation key identifying the webhook source (e.g.
	// "stripe", "shopify"). REQUIRED for role=webhook-receive and
	// role=webhook-dispatch; forbidden for all other roles. For webhook-receive,
	// this value must equal contract.endpoints.inbound.sourceID.
	SourceID string `yaml:"sourceID,omitempty"`
	// TargetSelector is the target-URL selector method name used by the
	// dispatcher to resolve the outbound webhook URL at runtime. REQUIRED for
	// role=webhook-dispatch; forbidden for all other roles.
	TargetSelector string `yaml:"targetSelector,omitempty"`
	// Projection, when set on a role=subscribe CU, makes cellgen emit
	// reg.RegisterProjection (an L3 CQRS projection) instead of reg.Subscribe.
	// The value is the ProjectionID — half of the checkpoint key
	// (cellID, projectionID). MUST be a snake_case probe-name identifier:
	// ^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$. Optional; forbidden on every
	// non-subscribe role.
	Projection string `yaml:"projection,omitempty"`
	// OnReset names the optional rebuild Reset-phase hook method on the same
	// slice service field as Handler (cell.ProjectionResetHook). Only meaningful
	// when Projection is set; exported Go identifier (^[A-Z][A-Za-z0-9_]*$).
	// Optional; subscribe-only. Forbidden when Projection is empty.
	OnReset string `yaml:"onReset,omitempty"`
}

type EndpointsMeta struct {
	// HTTP (also reused by gRPC: provider=server, consumers=clients)
	Server  string             `yaml:"server,omitempty"`
	Clients []string           `yaml:"clients,omitempty"`
	HTTP    *HTTPTransportMeta `yaml:"http,omitempty"`
	// gRPC transport subtree (parallel to HTTP); server/clients above carry
	// the provider/consumer cells.
	GRPC *GRPCTransportMeta `yaml:"grpc,omitempty"`
	// Event
	Publisher        string   `yaml:"publisher,omitempty"`
	ActorSubscribers []string `yaml:"actorSubscribers,omitempty"`
	// Subscribers is derived by deriveEventSubscribers (parser post-process):
	// union of ActorSubscribers + cell IDs from slice.yaml contractUsages[role=subscribe].
	// yaml:"-" means hand-written "subscribers:" in YAML is rejected by KnownFields strict decode.
	Subscribers []string `yaml:"-"`
	// Command
	Handler  string   `yaml:"handler,omitempty"`
	Invokers []string `yaml:"invokers,omitempty"`
	// Projection
	Provider string   `yaml:"provider,omitempty"`
	Readers  []string `yaml:"readers,omitempty"`
	// Webhook (kind=webhook only)
	Inbound *WebhookInboundMeta `yaml:"inbound,omitempty"`
	// Receivers is derived by deriveWebhookEndpoints (parser post-process): cell
	// IDs from slice.yaml contractUsages[role=webhook-receive].belongsToCell,
	// deduped and sorted alphabetically. yaml:"-" means hand-written "receivers:"
	// in YAML is rejected by KnownFields strict decode — mirrors the Subscribers
	// field pattern.
	Receivers []string `yaml:"-"`
	// Dispatchers is derived by deriveWebhookEndpoints (parser post-process): cell
	// IDs from slice.yaml contractUsages[role=webhook-dispatch].belongsToCell,
	// deduped and sorted alphabetically. yaml:"-" means hand-written "dispatchers:"
	// in YAML is rejected by KnownFields strict decode — mirrors the Subscribers
	// field pattern.
	Dispatchers []string `yaml:"-"`
}

type GRPCTransportMeta struct {
	// Service is the proto fully-qualified service name,
	// e.g. "device.command.v1.DeviceCommandService".
	Service string `yaml:"service" json:"service"`
	// Proto is the contracts-relative path to the .proto file, e.g.
	// "contracts/grpc/device/command/v1/device_command.proto".
	Proto string `yaml:"proto" json:"proto"`
}

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

type HTTPAuthMeta struct {
	// Public marks the route as JWT-exempt. The generated NewHandler takes no
	// policy argument; auth.Route{Public: true} is emitted by RegisterRoutes.
	// Mutually exclusive with PasswordResetExempt, Bootstrap, ServiceOwned,
	// and ClientsOnly.
	Public bool `yaml:"public,omitempty" json:"public,omitempty"`
	// PasswordResetExempt allows callers whose JWT carries password_reset_required=true
	// to reach this route. The generated handler emits auth.Route{PasswordResetExempt: true}.
	// Mutually exclusive with Public, Bootstrap, and ClientsOnly. May combine
	// with ServiceOwned.
	PasswordResetExempt bool `yaml:"passwordResetExempt,omitempty" json:"passwordResetExempt,omitempty"`
	// ServiceOwned indicates that the listener must still authenticate the caller,
	// but route-level authorization is intentionally absent because the service
	// validates ownership against domain state. When true, contractgen generates a
	// single-arg NewHandler(svc Service) constructor and emits auth.Route without
	// a Policy field. May be combined with PasswordResetExempt. Mutually exclusive
	// with Public, Bootstrap, and ClientsOnly.
	ServiceOwned bool `yaml:"serviceOwned,omitempty" json:"serviceOwned,omitempty"`
	// Bootstrap marks the route as protected by HTTP Basic Auth using
	// GOCELL_BOOTSTRAP_ADMIN_USERNAME/PASSWORD env credentials. Listener-level
	// JWT middleware skips routes flagged as Bootstrap (matcher in FinalizeAuth).
	// Mutually exclusive with Public, PasswordResetExempt, ServiceOwned, and
	// ClientsOnly. FMT-28 limits this flag to contracts whose path matches
	// IsBootstrapPath.
	Bootstrap bool `yaml:"bootstrap,omitempty" json:"bootstrap,omitempty"`
	// ClientsOnly indicates that this endpoint relies solely on Contract.Clients
	// caller-cell allowlist for authorization. When true, contractgen generates a
	// single-arg NewHandler(svc Service) constructor and emits auth.Route without
	// a Policy field. auth.Mount auto-injects RequireCallerCell guard when
	// Clients is non-empty. Mutually exclusive with Public, Bootstrap,
	// PasswordResetExempt, and ServiceOwned. Requires endpoints.clients to be
	// non-empty and the path to match IsInternalHTTPPath (/internal/v1 or
	// /internal/v1/...) where caller-cell identity is verifiable via the
	// service token.
	ClientsOnly bool `yaml:"clientsOnly,omitempty" json:"clientsOnly,omitempty"`
	// Responses lists HTTP status codes injected by listener-mounted middleware,
	// NOT emitted by the handler/adapter — so they are declared here (no typed
	// response struct) rather than in the responses map. Despite the "auth" name,
	// this list already spans non-auth middleware: bootstrap auth 401, rate limiter
	// 429, and HTTP-idempotency 409 (ClaimBusy) / 422 (key-reused) — both required
	// on non-exempt mutating routes by governance rule CH-07. CH-04 treats these as
	// declared without requiring handler AST emission.
	Responses []int `yaml:"responses,omitempty" json:"responses,omitempty"`
}

type HTTPIdempotencyMeta struct {
	// Exempt, when true, instructs the HTTP idempotency middleware to never
	// claim/record/replay this route's responses (credential-rotation /
	// change-password whose body returns tokens). The generated handler emits
	// auth.Route{IdempotencyExempt: true} (see runtime/auth/route.go).
	// Mandatory for any route whose response schema carries a
	// pkg/redaction.IsSensitiveKey field — codegen rejects generation without it
	// (CREDENTIAL-RESPONSE-IDEMPOTENCY-EXEMPT-FUNNEL-01).
	Exempt bool `yaml:"exempt,omitempty" json:"exempt,omitempty"`
}

type HTTPOwnershipMeta struct {
	SubjectPath  string `yaml:"subjectPath"  json:"subjectPath"`
	ResourcePath string `yaml:"resourcePath" json:"resourcePath"`
}

type HTTPResponseMeta struct {
	Description string `yaml:"description" json:"description" fingerprint:"-"`
	SchemaRef   string `yaml:"schemaRef"   json:"schemaRef"`
}

type HTTPTransportMeta struct {
	Method      string                 `yaml:"method"        json:"method"`
	Path        string                 `yaml:"path"          json:"path"`
	PathParams  map[string]ParamSchema `yaml:"pathParams,omitempty"  json:"pathParams,omitempty"`
	QueryParams map[string]ParamSchema `yaml:"queryParams,omitempty" json:"queryParams,omitempty"`
	// Headers declares inbound HTTP request headers this endpoint consumes
	// (keyed by canonical header name, e.g. "X-Tenant-ID"). It is the single
	// source for request-header consumption: contractgen merges each declared
	// header into the generated Request DTO as a typed field populated from
	// r.Header.Get — see archtest HTTP-REQUEST-HEADER-READ-FUNNEL-01 (cells /
	// examples may not read inbound headers raw; the generated handler is the
	// sole reader).
	//
	// Headers are POPULATE-ONLY at codegen: the generated handler emits no
	// required / length / format gate. Per-endpoint fail behavior (e.g. the
	// X-Tenant-ID anti-enumeration matrix in ADR 1160 — login→401, setup/admin→400,
	// setup/status→200 fail-soft) is owned by the cell adapter/service via
	// tenant.ParseTenantID, not derivable from a uniform codegen gate. `required`
	// is documentation / governance / client-gen metadata only. Governance FMT-40
	// rejects unenforced minLength/maxLength/minimum/maximum on header schemas so a
	// declared constraint can never silently no-op. ref: goadesign/goa v3
	// expr/http_endpoint.go Headers; go-kratos/kratos transport/http header binding.
	Headers       map[string]ParamSchema   `yaml:"headers,omitempty"     json:"headers,omitempty"`
	SuccessStatus int                      `yaml:"successStatus" json:"successStatus"`
	NoContent     bool                     `yaml:"noContent"     json:"noContent"`
	Responses     map[int]HTTPResponseMeta `yaml:"responses,omitempty" json:"responses,omitempty"`
	// Auth declares route-level authentication overrides for contractgen.
	// When set, the generated handler emits the corresponding auth.Route flags
	// instead of the default Policy-only wiring. Omit for standard authenticated routes.
	Auth HTTPAuthMeta `yaml:"auth,omitempty" json:"auth,omitempty"`
	// Ownership declares object-level authorization subject/resource paths.
	// Required when auth.serviceOwned=true (governance FMT-32 enforces presence).
	Ownership *HTTPOwnershipMeta `yaml:"ownership,omitempty" json:"ownership,omitempty"`
	// Idempotency declares route-level HTTP-idempotency behavior. It is a
	// first-class sibling of Auth (not folded into the auth-mode mutex matrix):
	// idempotency is a middleware concern, not an authentication mode (#1469
	// review F7). Omit for default idempotent-eligible routes.
	Idempotency HTTPIdempotencyMeta `yaml:"idempotency,omitempty" json:"idempotency,omitempty"`
}

type HeaderViolation struct {
	// Header is the offending declared header name (the contract.yaml map key).
	Header string
	// Kind classifies the violation.
	Kind HeaderViolationKind
	// Message is a human-readable description of the problem.
	Message string
}

type HeaderViolationKind int

type JourneyMeta struct {
	ID           string          `yaml:"id"`
	Goal         string          `yaml:"goal"`
	Lifecycle    string          `yaml:"lifecycle"` // "active"|"experimental"
	Owner        OwnerMeta       `yaml:"owner"`
	Cells        []string        `yaml:"cells"`
	Contracts    []string        `yaml:"contracts"`
	PassCriteria []PassCriterion `yaml:"passCriteria"`
	File         string          `yaml:"-"` // parsed journey YAML path relative to project root
}

type L0DepMeta struct {
	Cell   string `yaml:"cell"`
	Reason string `yaml:"reason"`
}

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

type LocatorMode int

type LocatorOption func(*Locator)

type ManifestIncludes struct {
	// Cells corresponds to the "cells:" YAML key.
	Cells []string `yaml:"cells"`
	// Slices corresponds to the "slices:" YAML key.
	Slices []string `yaml:"slices"`
	// Contracts corresponds to the "contracts:" YAML key.
	Contracts []string `yaml:"contracts"`
	// Journeys corresponds to the "journeys:" YAML key.
	Journeys []string `yaml:"journeys"`
	// Assemblies corresponds to the "assemblies:" YAML key.
	Assemblies []string `yaml:"assemblies"`
	// Actors corresponds to the "actors:" YAML key (singular string, not a list).
	Actors string `yaml:"actors"`
	// StatusBoard corresponds to the "statusBoard:" YAML key (camelCase, not kebab-case).
	StatusBoard string `yaml:"statusBoard"`
}

type ManifestModule struct {
	Path     string           `yaml:"path"`
	Includes ManifestIncludes `yaml:"includes"`
	Excludes []string         `yaml:"excludes"`
}

type ManifestSpec struct {
	Version string           `yaml:"version"`
	Modules []ManifestModule `yaml:"modules"`
}

type MetadataSource struct {
	Path   string
	Kind   SourceKind
	CellID string
}

type OwnerMeta struct {
	Team string `yaml:"team"`
	Role string `yaml:"role"`
}

type ParamSchema struct {
	// Ref is a relative path to a shared JSON Schema mixin that single-sources
	// the value shape (type/minimum/maximum/minLength/maxLength) for this param.
	// It is mutually exclusive with inline type, minimum, maximum, minLength,
	// maxLength, and format declarations; resolved at parse time so governance
	// (FMT-25) and contractgen see a fully-resolved ParamSchema transparently.
	// The Ref field is preserved after resolution for traceability.
	Ref       string `yaml:"$ref,omitempty"      json:"$ref,omitempty"`
	Type      string `yaml:"type"                json:"type"`
	Required  *bool  `yaml:"required,omitempty"  json:"required,omitempty"`
	Format    string `yaml:"format,omitempty"    json:"format,omitempty"`
	MinLength *int   `yaml:"minLength,omitempty" json:"minLength,omitempty"`
	MaxLength *int   `yaml:"maxLength,omitempty" json:"maxLength,omitempty"`
	Minimum   *int   `yaml:"minimum,omitempty"   json:"minimum,omitempty"`
	Maximum   *int   `yaml:"maximum,omitempty"   json:"maximum,omitempty"`
}

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

type PassCriterion struct {
	Text     string `yaml:"text"`
	Mode     string `yaml:"mode"` // "auto"|"manual"
	CheckRef string `yaml:"checkRef,omitempty"`
}

type Position struct {
	Line   int
	Column int
}

type ProjectMeta struct {
	Cells       map[string]*CellMeta     // keyed by cell ID
	Slices      map[string]*SliceMeta    // keyed by "cellID/sliceID"
	Contracts   map[string]*ContractMeta // keyed by contract ID
	Journeys    map[string]*JourneyMeta  // keyed by journey ID
	Assemblies  map[string]*AssemblyMeta // keyed by assembly ID
	StatusBoard []StatusBoardEntry
	Actors      []ActorMeta
	// contains filtered or unexported fields
}

type ResolvedSchemaRef struct {
	ContractSchemaRef
	AbsPath    string
	ProjectRel string
}

type SagaMeta struct {
	// Timeout is the saga-wide deadline as a Go duration string (e.g. "30s").
	// Empty means no saga-level ceiling (per-step timeouts still apply).
	Timeout string `yaml:"timeout,omitempty"`
	// CompensationOrder selects the rollback walk. v1 limitation: only "reverse"
	// is supported (empty is treated as "reverse"); any other value is rejected
	// by governance SAGA-CONTRACT-COMPENSATION-ORDER-01. Forward/custom orders
	// are not yet modeled.
	CompensationOrder string `yaml:"compensationOrder,omitempty"`
	// Retries is the saga-wide default retry policy; each step inherits it
	// unless the step sets its own.
	Retries *SagaRetryMeta `yaml:"retries,omitempty"`
	// Steps lists the forward steps in execution order; must be non-empty.
	Steps []SagaStepMeta `yaml:"steps"`
}

type SagaRetryMeta struct {
	MaxAttempts  int    `yaml:"maxAttempts,omitempty"`
	BaseInterval string `yaml:"baseInterval,omitempty"`
	MaxInterval  string `yaml:"maxInterval,omitempty"`
}

type SagaStepMeta struct {
	Name       string         `yaml:"name"`
	Output     string         `yaml:"output"`
	Timeout    string         `yaml:"timeout,omitempty"`
	Retries    *SagaRetryMeta `yaml:"retries,omitempty"`
	Compensate *bool          `yaml:"compensate,omitempty"`
}

type SchemaMeta struct {
	Primary string `yaml:"primary"`
}

type SchemaRefError struct {
	Field string
	Ref   string
	Kind  string
}

type SchemaRefScope string

type SchemaRefsMeta struct {
	Request  string `yaml:"request,omitempty"  json:"request,omitempty"`
	Response string `yaml:"response,omitempty" json:"response,omitempty"`
	Payload  string `yaml:"payload,omitempty"  json:"payload,omitempty"`
	Headers  string `yaml:"headers,omitempty"  json:"headers,omitempty"`
	// Extra captures additional string-valued schema ref keys beyond the four
	// well-known ones, via yaml:",inline". It is excluded from JSON serialization
	// (json:"-") because Go's encoding/json does not support inline maps; callers
	// that need JSON output should implement custom MarshalJSON if needed.
	Extra map[string]string `yaml:",inline"            json:"-"`
}

type SliceMeta struct {
	ID            string `yaml:"id"`
	BelongsToCell string `yaml:"belongsToCell"`
	// ConsistencyLevel: "L0"-"L4"; required (parser rejects empty);
	// MUST be ≤ cell.ConsistencyLevel. slice.yaml is the SoR for slice
	// level (codegen funnel projects to slice_gen.go.sliceMeta);
	// inheritance from cell.consistencyLevel is no longer supported.
	ConsistencyLevel string `yaml:"consistencyLevel"`
	// Lifecycle is the slice's governance maturity phase
	// (experimental|candidate|asset|maintenance|retired). Optional; MUST be ≤ the
	// parent cell's lifecycle (governance CELL-LIFECYCLE-01). See
	// kernel/cellvocab.CellLifecycle.
	Lifecycle      string          `yaml:"lifecycle,omitempty"`
	ContractUsages []ContractUsage `yaml:"contractUsages"`
	Verify         SliceVerifyMeta `yaml:"verify"`
	AllowedFiles   []string        `yaml:"allowedFiles,omitempty"`
	Dir            string          `yaml:"-"` // slice directory segment, set by parser
	CellDir        string          `yaml:"-"` // parent cell directory segment, set by parser
	File           string          `yaml:"-"` // parsed slice.yaml path relative to project root
}

type SliceVerifyMeta struct {
	Unit     []string     `yaml:"unit"`
	Contract []string     `yaml:"contract"`
	Waivers  []WaiverMeta `yaml:"waivers"`
}

type SourceKind int

type StatusBoardEntry struct {
	JourneyID string `json:"journeyId" yaml:"journeyId"`
	State     string `json:"state"     yaml:"state"`
	Risk      string `json:"risk"      yaml:"risk"`
	Blocker   string `json:"blocker"   yaml:"blocker"`
	UpdatedAt string `json:"updatedAt" yaml:"updatedAt"`
}

type WaiverMeta struct {
	Contract  string `yaml:"contract"`
	Owner     string `yaml:"owner"`
	Reason    string `yaml:"reason"`
	ExpiresAt string `yaml:"expiresAt"`
}

type WebhookInboundMeta struct {
	// PathPattern is the HTTP path the platform exposes for receiving webhook
	// callbacks from the external source (e.g. "/webhooks/stripe/events").
	PathPattern string `yaml:"pathPattern"`
	// SourceID is the secret-isolation key identifying the webhook source
	// (e.g. "stripe"). Must match the SourceID declared in every
	// webhook-receive ContractUsage for this contract. Must satisfy
	// ^[a-z][a-z0-9_-]{0,63}$ (aligns with runtime kernel/webhook
	// sourceIDPattern, maxLen 64).
	SourceID string `yaml:"sourceID"`
}

type WebhookPayloadMeta struct {
	// SchemaRef is an optional path to a JSON Schema file (relative to the
	// contract.yaml directory) that validates the webhook payload body.
	SchemaRef string `yaml:"schemaRef,omitempty"`
	// ContentType is the expected MIME type of the webhook payload
	// (e.g. "application/json"). Runtime rejects requests with a mismatched
	// Content-Type header.
	ContentType string `yaml:"contentType,omitempty"`
	// MaxBodyBytes is the maximum allowed size (in bytes) of the webhook
	// request body. Runtime rejects requests exceeding this limit with 413.
	// A value of 0 means no limit (not recommended for production).
	MaxBodyBytes int64 `yaml:"maxBodyBytes,omitempty"`
}

type WebhookSignatureMeta struct {
	// Algorithm is the HMAC algorithm used to verify the webhook signature
	// (e.g. "hmac-sha256").
	Algorithm string `yaml:"algorithm"`
	// ToleranceSeconds is the bidirectional time window (in seconds) for
	// replay-attack prevention. Requests whose timestamp differs from server
	// time by more than this value in either direction are rejected. A value
	// of 0 disables time-window checking (not recommended for production).
	ToleranceSeconds int `yaml:"toleranceSeconds,omitempty"`
	// DeliveryIDHeader is the HTTP header carrying the unique delivery ID
	// (e.g. "svix-id"). Used as part of the signed string to prevent
	// cross-delivery replay attacks.
	DeliveryIDHeader string `yaml:"deliveryIDHeader"`
	// TimestampHeader is the HTTP header carrying the Unix timestamp of the
	// delivery (e.g. "svix-timestamp"). Must be within ToleranceSeconds of
	// server time.
	TimestampHeader string `yaml:"timestampHeader"`
	// SignatureHeader is the HTTP header carrying the HMAC signature value
	// (e.g. "svix-signature").
	SignatureHeader string `yaml:"signatureHeader"`
	// SignedStringForm is a template for constructing the signed string from
	// delivery fields. Template variables: {deliveryID} (value of
	// DeliveryIDHeader), {timestamp} (value of TimestampHeader), {body}
	// (raw request body). Example: "{deliveryID}.{timestamp}.{body}".
	SignedStringForm string `yaml:"signedStringForm"`
}

type WireBundleListener struct {
	Ref    string
	Prefix string
}

type WireBundleRoute struct {
	Slice    string
	Listener string
	SubPath  string
	Method   string // empty when marker omitted (defaults to "RegisterRoutes")
}

type WireBundleSubscribe struct {
	Slice   string
	Topic   string
	Handler string
	Group   string
}

type WireListenerView struct {
	Ref    string `json:"ref"              yaml:"ref"`
	Prefix string `json:"prefix,omitempty" yaml:"prefix,omitempty"`
}

type WireRouteView struct {
	Slice    string `json:"slice"            yaml:"slice"`
	Listener string `json:"listener"         yaml:"listener"`
	SubPath  string `json:"subPath,omitempty" yaml:"subPath,omitempty"`
	Method   string `json:"method,omitempty"  yaml:"method,omitempty"`
}

type WireSubscribeView struct {
	Slice   string `json:"slice"   yaml:"slice"`
	Topic   string `json:"topic"   yaml:"topic"`
	Handler string `json:"handler" yaml:"handler"`
	Group   string `json:"group"   yaml:"group"`
}