contract

type Action struct {
	Contributor string
	Intent      string
	Kind        Kind
	Capability  Capability
	Resource    map[string]any
}

type AuditEmitter interface {
	Emit(ctx context.Context, rec AuditRecord)
}

type AuditFilter struct {
	Limit       int
	Contributor string
	Intent      string
	User        string
	Result      string
}

type AuditRecord struct {
	Time          time.Time
	Contributor   string
	Intent        string
	IntentVersion int
	Subject       string // resource id when known
	User          string // user identity (subject from UserInfo)
	Result        string // ok | error
	LatencyMs     int64
	Payload       map[string]any // pre-redaction; subject to per-intent redaction list
	CorrelationID string
}

type AuditStore interface {
	Append(rec AuditRecord)
	List(filter AuditFilter) []AuditRecord
	// Subscribe returns a channel that receives every Append from now on, plus
	// a cancel func that closes the channel and unregisters the subscriber.
	// Slow subscribers drop events rather than block writers — audit is
	// telemetry, not the source of truth.
	Subscribe() (<-chan AuditRecord, func())
}

type CacheHint struct {
	StaleTime string `json:"staleTime,omitempty"`
}

type Capability string

type Cardinality string

type ContractManifest struct {
	SchemaVersion int              `yaml:"schemaVersion" json:"schemaVersion"`
	Contributor   Contributor      `yaml:"contributor"   json:"contributor"`
	Queries       map[string]Query `yaml:"queries,omitempty" json:"queries,omitempty"`
	Intents       []Intent         `yaml:"intents"       json:"intents"`
	Graph         []GraphNode      `yaml:"graph,omitempty" json:"graph,omitempty"`
	Extends       []Extension      `yaml:"extends,omitempty" json:"extends,omitempty"`
}

type Contributor struct {
	Name         string          `yaml:"name"         json:"name"`
	Envelope     EnvelopeSupport `yaml:"envelope"     json:"envelope"`
	Capabilities []string        `yaml:"capabilities,omitempty" json:"capabilities,omitempty"`
}

type DataBinding struct {
	QueryRef string                 `yaml:"-" json:"queryRef,omitempty"`
	Intent   string                 `yaml:"intent,omitempty"  json:"intent,omitempty"`
	Params   map[string]ParamSource `yaml:"params,omitempty"  json:"params,omitempty"`
}

type Decision struct {
	// Allow reports whether access is granted.
	Allow bool
	// Reason is a short, human-readable explanation. Surfaced in audit logs
	// and (optionally) in error responses.
	Reason string
	// Redactions lists JSONPath-like field paths that must be redacted from
	// the response payload even when Allow is true. Empty when no redactions
	// apply.
	Redactions []string
}

type Deprecation struct {
	IntentVersion int    `json:"intentVersion"`
	RemoveAfter   string `json:"removeAfter"`
}

type EnvelopeSupport struct {
	Supports  []string `yaml:"supports"  json:"supports"`
	Preferred string   `yaml:"preferred" json:"preferred"`
}

type Error struct {
	Code          ErrorCode      `json:"code"`
	Message       string         `json:"message,omitempty"`
	Details       map[string]any `json:"details,omitempty"`
	Retryable     bool           `json:"retryable,omitempty"`
	CorrelationID string         `json:"correlationID,omitempty"`
	Redactions    []string       `json:"redactions,omitempty"`
}

type ErrorCode string

type ErrorResponse struct {
	OK       bool   `json:"ok"`
	Envelope string `json:"envelope"`
	Error    *Error `json:"error"`
}

type Extension struct {
	Target ExtensionTarget `yaml:"target" json:"target"`
	Slot   string          `yaml:"slot"   json:"slot"` // dotted path: "detailDrawer.fields"
	Add    []GraphNode     `yaml:"add"    json:"add"`
}

type ExtensionTarget struct {
	Contributor string `yaml:"contributor" json:"contributor"`
	Intent      string `yaml:"intent"      json:"intent"`
	Route       string `yaml:"route,omitempty" json:"route,omitempty"`
}

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

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

type GraphCacheKey struct {
	Route           string
	PermissionsHash string
	ShellVersion    string
}

type GraphNode struct {
	Route       string                 `yaml:"route,omitempty"       json:"route,omitempty"` // top-level only
	Intent      string                 `yaml:"intent"                json:"intent"`
	Title       string                 `yaml:"title,omitempty"       json:"title,omitempty"`
	Nav         *NavConfig             `yaml:"nav,omitempty"         json:"nav,omitempty"`
	Root        bool                   `yaml:"root,omitempty"        json:"root,omitempty"`
	Data        *DataBinding           `yaml:"data,omitempty"        json:"data,omitempty"`
	Props       map[string]any         `yaml:"props,omitempty"       json:"props,omitempty"`
	Slots       map[string][]GraphNode `yaml:"slots,omitempty"       json:"slots,omitempty"`
	VisibleWhen *Predicate             `yaml:"visibleWhen,omitempty" json:"visibleWhen,omitempty"`
	EnabledWhen *Predicate             `yaml:"enabledWhen,omitempty" json:"enabledWhen,omitempty"`
	Op          string                 `yaml:"op,omitempty"          json:"op,omitempty"` // for action nodes
	Payload     map[string]ParamSource `yaml:"payload,omitempty"     json:"payload,omitempty"`
	Component   string                 `yaml:"component,omitempty"   json:"component,omitempty"` // intent: custom escape hatch
	Src         string                 `yaml:"src,omitempty"         json:"src,omitempty"`       // intent: iframe escape hatch
	Sandbox     []string               `yaml:"sandbox,omitempty"     json:"sandbox,omitempty"`
	Protocol    string                 `yaml:"protocol,omitempty"    json:"protocol,omitempty"`
}

type Intent struct {
	Name        string           `yaml:"name"        json:"name"`
	Kind        IntentKind       `yaml:"kind"        json:"kind"`
	Version     int              `yaml:"version"     json:"version"`
	Capability  Capability       `yaml:"capability"  json:"capability"`
	Requires    Predicate        `yaml:"requires,omitempty" json:"requires,omitempty"`
	Schema      IntentSchema     `yaml:"schema,omitempty" json:"schema,omitempty"`
	Mode        SubscriptionMode `yaml:"mode,omitempty" json:"mode,omitempty"`               // subscription only
	Invalidates []string         `yaml:"invalidates,omitempty" json:"invalidates,omitempty"` // command only
	Audit       *bool            `yaml:"audit,omitempty"       json:"audit,omitempty"`       // default true for commands
	Deprecated  *Deprecation     `yaml:"deprecated,omitempty" json:"deprecated,omitempty"`
}

type IntentKind string

type IntentKindDef struct {
	Slots map[string]SlotDef
}

type IntentSchema struct {
	Input  map[string]any `yaml:"input,omitempty"  json:"input,omitempty"`
	Output any            `yaml:"output,omitempty" json:"output,omitempty"`
}

type Kind string

type NavConfig struct {
	Group    string `yaml:"group,omitempty"    json:"group,omitempty"`
	Icon     string `yaml:"icon,omitempty"     json:"icon,omitempty"`
	Priority int    `yaml:"priority,omitempty" json:"priority,omitempty"`
	Badge    string `yaml:"badge,omitempty"    json:"badge,omitempty"`
}

type NoopAuditEmitter struct{}

type ParamSource struct {
	Value any    `yaml:"value,omitempty" json:"value,omitempty"`
	From  string `yaml:"from,omitempty"  json:"from,omitempty"` // route.X | parent.X | state.X | session.X
}

type Predicate struct {
	All    []string `yaml:"all,omitempty"    json:"all,omitempty"`
	Any    []string `yaml:"any,omitempty"    json:"any,omitempty"`
	Not    []string `yaml:"not,omitempty"    json:"not,omitempty"`
	Warden string   `yaml:"warden,omitempty" json:"warden,omitempty"`
}

type Principal struct {
	User   *dashauth.UserInfo
	Claims map[string]any
}

type Query struct {
	Intent string                 `yaml:"intent" json:"intent"`
	Params map[string]ParamSource `yaml:"params,omitempty" json:"params,omitempty"`
	Cache  *QueryCache            `yaml:"cache,omitempty"  json:"cache,omitempty"`
}

type QueryCache struct {
	StaleTime string `yaml:"staleTime,omitempty" json:"staleTime,omitempty"`
}

type Registry interface {
	Register(m *ContractManifest) error
	Contributor(name string) (*ContractManifest, bool)
	Intent(contributor, intent string, version int) (Intent, bool)
	HighestVersion(contributor, intent string) (int, bool)
	All() []*ContractManifest
	MergedGraph(contributor, route string) (*GraphNode, bool)
	// MatchRoute is MergedGraph plus :name-style placeholder matching. On a
	// match the returned map carries the extracted segment values keyed by
	// placeholder name. Exact route matches return an empty (non-nil) map.
	// Slice (j) added this for deep-link detail routes; MergedGraph remains
	// for callers that don't care about params.
	MatchRoute(contributor, route string) (*GraphNode, map[string]string, bool)

	// RegisterRemote records a contributor whose handlers live in another
	// service. The manifest is registered identically to a local one so the
	// graph endpoint and capabilities listing work uniformly; the endpoint
	// is what the dispatcher's forwarding layer reads to know where to send
	// envelopes. Slice (m) added this.
	RegisterRemote(m *ContractManifest, endpoint RemoteEndpoint) error

	// IsRemote reports whether the named contributor was registered via
	// RegisterRemote.
	IsRemote(contributor string) bool

	// Remote returns the upstream endpoint for a contributor previously
	// registered via RegisterRemote. ok is false for local contributors.
	Remote(contributor string) (RemoteEndpoint, bool)

	// Unregister removes a contributor and all its intents + merged graph.
	// Used by discovery loops to clean up offline remotes; safe to call
	// for unknown names.
	Unregister(contributor string)
}

type RemoteEndpoint struct {
	// BaseURL is the upstream service's root, including any path prefix
	// (e.g. https://svc.internal:8443 or /proxied/svc). The forwarding
	// client appends "/_forge/contract/dispatch" for envelope POSTs and
	// "/_forge/contract/manifest" for manifest fetches.
	BaseURL string

	// APIKey, when non-empty, is sent as Authorization: Bearer <key> on
	// every forwarded envelope so the upstream can authenticate the
	// dashboard. Inbound user headers (Authorization, Cookie) are still
	// forwarded so the upstream sees the end-user identity too — the
	// API key authenticates the dashboard itself; user identity flows in
	// parallel.
	APIKey string

	// Client overrides the http.Client used to talk to this remote.
	// nil = a default client with a 10s timeout.
	Client *http.Client
}

type Request struct {
	Envelope       string          `json:"envelope"`
	Kind           Kind            `json:"kind"`
	Contributor    string          `json:"contributor"`
	Intent         string          `json:"intent"`
	IntentVersion  int             `json:"intentVersion,omitempty"`
	Payload        json.RawMessage `json:"payload,omitempty"`
	Params         map[string]any  `json:"params,omitempty"`
	Context        RequestContext  `json:"context"`
	CSRF           string          `json:"csrf,omitempty"`
	IdempotencyKey string          `json:"idempotencyKey,omitempty"`
}

type RequestContext struct {
	Route         string `json:"route,omitempty"`
	CorrelationID string `json:"correlationID,omitempty"`
}

type Response struct {
	OK       bool            `json:"ok"`
	Envelope string          `json:"envelope"`
	Kind     Kind            `json:"kind"`
	Data     json.RawMessage `json:"data,omitempty"`
	Meta     ResponseMeta    `json:"meta"`
}

type ResponseMeta struct {
	IntentVersion int               `json:"intentVersion,omitempty"`
	Deprecation   *Deprecation      `json:"deprecation,omitempty"`
	CacheControl  *CacheHint        `json:"cacheControl,omitempty"`
	Invalidates   []string          `json:"invalidates,omitempty"`
	RouteParams   map[string]string `json:"routeParams,omitempty"`
}

type SlotDef struct {
	Accepts     []string // intent names accepted in this slot
	Cardinality Cardinality
	Extensible  bool // if true, other contributors may extend via Extends
}

type StreamEvent struct {
	Intent  string           `json:"intent"`
	Mode    SubscriptionMode `json:"mode"`
	Payload json.RawMessage  `json:"payload"`
	Seq     uint64           `json:"seq"`
}

type SubscriptionMode string

type Warden interface {
	Authorize(ctx context.Context, p Principal, a Action) (Decision, error)
}

type WardenRegistry interface {
	Register(name string, w Warden) error
	Get(name string) (Warden, bool)
}