normentity

package
v0.56.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 14, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package normentity defines the in-memory Go model of the normalized entity (normalized-entity v1) that harness CEL predicates evaluate over (ADR 0098, ADR 0147). Contract: docs/normative/normalized-entity/v1/.

The model is shaped for a CEL binding to wrap without copying:

  • Entity mirrors the specification's `entity` object member for member, and covers every field of the entity model, including the kind-specific sections, reviewers and approvals, checks with log lines, annotations, threads, reactions, and extensions.
  • Field holds an attribute that can be unresolved: absent (does not apply), known, null (source-confirmed no value), or unknown with a reason. A binding maps unknown to CEL unknown at the attribute's path.
  • List holds a collection's known members together with the coverage of its remainder, which is what a coverage-aware CEL list needs. There is deliberately no separate in-memory coverage structure: a parallel structure would have to be rejoined to its collections on every evaluation and could drift from them. The specification's host-only `coverage` member exists only on the wire; Document splits it out when marshaling and rejoins it when unmarshaling.
  • Document pairs the entity with the host-only View and is the unit that is serialized, validated against the JSON Schema, and cached.

Timestamps stay strings so lexical comparison is chronological in CEL, as the specification requires. ID is the canonical entity ID.

Index

Constants

View Source
const SchemaVersion = "normalized-entity/v1"

SchemaVersion is the `schema_version` of a serialized document.

Variables

View Source
var ErrInvalid = errors.New("normentity: invalid document")

ErrInvalid reports a document that violates an identity invariant of the normalized-entity v1 specification. See Document.Validate.

Functions

This section is empty.

Types

type Action

type Action struct {
	ID             string           `json:"id"`
	CreatedAt      Timestamp        `json:"created_at"`
	RevisedAt      Field[Timestamp] `json:"revised_at,omitzero"`
	Actor          Actor            `json:"actor"`
	IsEntityAuthor Field[bool]      `json:"is_entity_author,omitzero"`
	Extensions     *Extensions      `json:"extensions,omitempty"`
}

Action holds the members shared by body, comment, review, and label-application records. Actor must be an admitted actor.

type Actor

type Actor struct {
	ID           Field[string]    `json:"id,omitzero"`
	Login        Field[string]    `json:"login,omitzero"`
	Kind         Field[ActorKind] `json:"kind,omitzero"`
	Role         Field[Role]      `json:"role,omitzero"`
	BotRole      Field[string]    `json:"bot_role,omitzero"`
	RoleVerified Field[bool]      `json:"role_verified,omitzero"`
}

Actor is the shared ADR 0107 person shape used for authors, assignees, action actors, lifecycle actors, resolvers, reaction actors, approvers, and actor-valued extensions. Every attribute can be unresolved. An admitted actor is the same shape with a concrete ID, kind, and role and RoleVerified true. A human omits BotRole.

type ActorKind

type ActorKind string

ActorKind classifies an actor; Team is used only by reviewer subjects.

const (
	ActorHuman ActorKind = "human"
	ActorBot   ActorKind = "bot"
	ActorTeam  ActorKind = "team"
)

Actor kinds.

type AnnotationLevel

type AnnotationLevel string

AnnotationLevel is a check annotation's severity.

const (
	LevelNotice  AnnotationLevel = "notice"
	LevelWarning AnnotationLevel = "warning"
	LevelFailure AnnotationLevel = "failure"
)

Annotation levels.

type Approval

type Approval struct {
	Gate Field[ApprovalGate] `json:"gate,omitzero"`
}

Approval is the current approval-requirement result.

type ApprovalGate

type ApprovalGate string

ApprovalGate is the current approval requirement result.

const (
	GateNotRequired ApprovalGate = "not_required"
	GateSatisfied   ApprovalGate = "satisfied"
	GateUnsatisfied ApprovalGate = "unsatisfied"
)

Approval gate results.

type ChangeProposal

type ChangeProposal struct {
	BaseRepository Field[string]     `json:"base_repository,omitzero"`
	HeadRepository Field[string]     `json:"head_repository,omitzero"`
	BaseRef        Field[string]     `json:"base_ref,omitzero"`
	HeadRef        Field[string]     `json:"head_ref,omitzero"`
	HeadSHA        Field[string]     `json:"head_sha,omitzero"`
	IsFork         Field[bool]       `json:"is_fork,omitzero"`
	Draft          Field[bool]       `json:"draft,omitzero"`
	Approval       Field[Approval]   `json:"approval,omitzero"`
	ChangedFiles   List[ChangedFile] `json:"changed_files,omitzero"`
	Commits        List[string]      `json:"commits,omitzero"`
}

ChangeProposal holds change-proposal-only details.

type ChangeProposalCoverage

type ChangeProposalCoverage struct {
	ChangedFiles Coverage
	Commits      Coverage
}

ChangeProposalCoverage is the coverage of a change proposal's changed_files and commits collections, kept at entity level while the change proposal itself is unresolved. See Entity.UnresolvedChangeProposal.

type ChangedFile

type ChangedFile struct {
	Path  string        `json:"path"`
	Patch Field[string] `json:"patch,omitzero"`
}

ChangedFile is one changed path. Patch is the complete filtered diff, null when the source confirms no patch, or unknown.

type Check

type Check struct {
	ID           string                 `json:"id"`
	Name         Field[string]          `json:"name,omitzero"`
	Status       Field[CheckStatus]     `json:"status,omitzero"`
	Conclusion   Field[CheckConclusion] `json:"conclusion,omitzero"`
	CreatedAt    Timestamp              `json:"created_at"`
	HeadSHA      string                 `json:"head_sha"`
	StartedAt    Field[Timestamp]       `json:"started_at,omitzero"`
	CompletedAt  Field[Timestamp]       `json:"completed_at,omitzero"`
	NeverStarted Field[bool]            `json:"never_started,omitzero"`
	Log          CheckLog               `json:"log"`
	Report       CheckReport            `json:"report"`
	Extensions   *Extensions            `json:"extensions,omitempty"`
	URL          Field[string]          `json:"url,omitzero"`
	RunAttempt   Field[int]             `json:"run_attempt,omitzero"`
	TriggerEvent Field[string]          `json:"trigger_event,omitzero"`
}

Check is a current-head check result.

type CheckAnnotation

type CheckAnnotation struct {
	Path        string          `json:"path"`
	StartLine   int             `json:"start_line"`
	EndLine     int             `json:"end_line"`
	StartColumn Field[int]      `json:"start_column,omitzero"`
	EndColumn   Field[int]      `json:"end_column,omitzero"`
	Level       AnnotationLevel `json:"level"`
	Title       Field[string]   `json:"title,omitzero"`
	Message     Field[string]   `json:"message,omitzero"`
	Details     Field[string]   `json:"details,omitzero"`
}

CheckAnnotation is a forge-published file finding attached to a check.

type CheckConclusion

type CheckConclusion string

CheckConclusion is a completed check's outcome.

const (
	ConclusionSuccess        CheckConclusion = "success"
	ConclusionFailure        CheckConclusion = "failure"
	ConclusionNeutral        CheckConclusion = "neutral"
	ConclusionCancelled      CheckConclusion = "cancelled"
	ConclusionSkipped        CheckConclusion = "skipped"
	ConclusionTimedOut       CheckConclusion = "timed_out"
	ConclusionActionRequired CheckConclusion = "action_required"
	ConclusionStale          CheckConclusion = "stale"
)

Check conclusions.

type CheckLog

type CheckLog struct {
	Ascending  List[LogEntry] `json:"ascending,omitzero"`
	Descending List[LogEntry] `json:"descending,omitzero"`
}

CheckLog holds a check's log lines read from either end. Each side is a contiguous known prefix from its end with independent coverage.

type CheckReport

type CheckReport struct {
	Title       Field[string]         `json:"title,omitzero"`
	Summary     Field[string]         `json:"summary,omitzero"`
	Details     Field[string]         `json:"details,omitzero"`
	Annotations List[CheckAnnotation] `json:"annotations,omitzero"`
}

CheckReport is the forge-published check report.

type CheckStatus

type CheckStatus string

CheckStatus is a check's execution status.

const (
	CheckQueued     CheckStatus = "queued"
	CheckInProgress CheckStatus = "in_progress"
	CheckCompleted  CheckStatus = "completed"
)

Check statuses.

type Comment

type Comment struct {
	TextAction
	// ThreadID is the source thread ID, null when the source confirms the
	// comment is unthreaded, or unknown.
	ThreadID Field[string] `json:"thread_id,omitzero"`
	// ParentID is the Discussion thread-root ID (equal to ID on a root).
	ParentID string        `json:"parent_id,omitempty"`
	URL      Field[string] `json:"url,omitzero"`
}

Comment is a source comment, note, review-thread comment, or Discussion reply.

type Conversation

type Conversation struct {
	Category Field[ConversationCategory] `json:"category,omitzero"`
}

Conversation holds conversation-only details.

type ConversationCategory

type ConversationCategory struct {
	Name   Field[string] `json:"name,omitzero"`
	ID     Field[string] `json:"id,omitzero"`
	Slug   Field[string] `json:"slug,omitzero"`
	Format Field[string] `json:"format,omitzero"`
}

ConversationCategory is a Discussion's exclusive category.

type Coverage

type Coverage struct {
	Status         CoverageStatus `json:"status"`
	Reason         string         `json:"reason,omitempty"`
	SourceRevision string         `json:"source_revision,omitempty"`
}

Coverage describes the unknown remainder of one collection. Reason and SourceRevision are optional host diagnostics.

func (Coverage) IsZero

func (c Coverage) IsZero() bool

IsZero reports whether no coverage has been recorded.

type CoverageStatus

type CoverageStatus string

CoverageStatus says how much of a collection the known members represent.

const (
	// CoverageComplete: exhaustively known at the stated source revision; an
	// empty known list is truly empty.
	CoverageComplete CoverageStatus = "complete"
	// CoveragePartial: some members are known, more may exist.
	CoveragePartial CoverageStatus = "partial"
	// CoverageNotLoaded: no members were requested.
	CoverageNotLoaded CoverageStatus = "not_loaded"
	// CoverageUnknown: completeness cannot be established.
	CoverageUnknown CoverageStatus = "unknown"
	// CoverageUnsupported: the source or kind cannot provide the collection.
	CoverageUnsupported CoverageStatus = "unsupported"
	// CoverageFailed: fetch, provenance, or permission resolution failed.
	CoverageFailed CoverageStatus = "failed"
)

Collection coverage states defined by the normalized-entity v1 specification.

type CurrentApproval

type CurrentApproval struct {
	Actor          Actor            `json:"actor"`
	ApprovedAt     Field[Timestamp] `json:"approved_at,omitzero"`
	IsEntityAuthor Field[bool]      `json:"is_entity_author,omitzero"`
}

CurrentApproval is a currently recorded approval.

type Document

type Document struct {
	Entity Entity
	View   View
}

Document is a normalized-entity v1 document: the Entity a CEL binding exposes and the host-only View.

The specification's host-only `coverage` member has no counterpart here. Each collection's coverage lives in its List, next to the known members it qualifies, because a CEL binding needs both together and keeping them in separate structures would require re-joining them for every evaluation. MarshalJSON gathers the coverage back into the serialized `coverage` member, and UnmarshalJSON rejoins it, so the serialized form is exactly the specified document.

Decoding is not a JSON Schema validator: member names match case-insensitively and members outside the closed schema are dropped. Check untrusted documents against the schema first. Document.Validate checks the identity invariants the schema cannot express.

func (Document) MarshalJSON

func (d Document) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*Document) UnmarshalJSON

func (d *Document) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

func (*Document) Validate

func (d *Document) Validate() error

Validate checks the identity invariants JSON Schema cannot express: the entity's kind and source system are specified values, the source host is lowercase, and `entity.id` is exactly the canonical ID derived from the source system, host, kind, and source ID. It returns ErrInvalid wrapped with the first violation.

type Entity

type Entity struct {
	Kind     Kind   `json:"kind"`
	Source   Source `json:"source"`
	ID       ID     `json:"id"`
	SourceID string `json:"source_id"`
	Key      string `json:"key"`
	Number   int    `json:"number"`
	URL      string `json:"url"`

	State     Field[State]     `json:"state,omitzero"`
	Title     Field[string]    `json:"title,omitzero"`
	Author    Field[Actor]     `json:"author,omitzero"`
	CreatedAt Field[Timestamp] `json:"created_at,omitzero"`
	UpdatedAt Field[Timestamp] `json:"updated_at,omitzero"`

	Labels     List[string] `json:"labels,omitzero"`
	Assignees  List[Actor]  `json:"assignees,omitzero"`
	Lifecycle  Lifecycle    `json:"lifecycle"`
	Extensions *Extensions  `json:"extensions,omitempty"`

	// Kind-specific sections: WorkItem applies only to a work item,
	// ChangeProposal (with Reviews, Reviewers, CurrentApprovals, and Checks)
	// only to a change proposal, Conversation only to a conversation.
	WorkItem       Field[WorkItem]       `json:"work_item,omitzero"`
	ChangeProposal Field[ChangeProposal] `json:"change_proposal,omitzero"`
	Conversation   Field[Conversation]   `json:"conversation,omitzero"`

	// UnresolvedChangeProposal holds the coverage of the change proposal's
	// changed_files and commits collections while ChangeProposal is not
	// known (an unknown marker). The specification still requires both
	// coverage entries then, but there are no [List] values to carry them.
	// It is ignored once ChangeProposal is known, where each [List] carries
	// its own coverage. It is host-only and never serialized in the entity.
	UnresolvedChangeProposal ChangeProposalCoverage `json:"-"`

	// Body is the body action, null when the source confirms no body, or
	// unknown. It is singular and has no coverage.
	Body Field[TextAction] `json:"body,omitzero"`

	Comments          List[Comment]          `json:"comments,omitzero"`
	Reviews           List[Review]           `json:"reviews,omitzero"`
	Reviewers         List[Reviewer]         `json:"reviewers,omitzero"`
	CurrentApprovals  List[CurrentApproval]  `json:"current_approvals,omitzero"`
	LabelApplications List[LabelApplication] `json:"label_applications,omitzero"`
	Threads           List[Thread]           `json:"threads,omitzero"`
	Reactions         List[Reaction]         `json:"reactions,omitzero"`
	Checks            List[Check]            `json:"checks,omitzero"`
}

Entity is the source-neutral normalized entity (normalized-entity v1): the value a CEL binding exposes as `entity`.

Its shape follows the specification's `entity` object member for member, so a CEL adapter can wrap an Entity directly instead of copying it into a bridge structure:

  • Field carries the absent, known, null, and unknown states of attributes that can be unresolved (to become CEL unknown);
  • List carries a collection's known members together with the coverage of its remainder (to become a coverage-aware CEL list);
  • members that do not apply to the entity's kind are zero and omitted (absent, following ordinary CEL missing-key behavior).

Required members are always serialized; the JSON Schema remains the authority on which members are required for which kind and provider.

type ExtensionAtom

type ExtensionAtom struct {
	String *string
	Number *float64
	Bool   *bool
	Option *ExtensionOption
	Actor  *Actor
}

ExtensionAtom is one typed extension atom: exactly one of a string, number, boolean, option, or actor.

func (ExtensionAtom) MarshalJSON

func (a ExtensionAtom) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*ExtensionAtom) UnmarshalJSON

func (a *ExtensionAtom) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type ExtensionEntry

type ExtensionEntry struct {
	SourceKey  string                `json:"source_key"`
	SourcePath string                `json:"source_path,omitempty"`
	Value      Field[ExtensionValue] `json:"value,omitzero"`
	ChangedBy  Field[Actor]          `json:"changed_by,omitzero"`
	ChangedAt  Field[Timestamp]      `json:"changed_at,omitzero"`
}

ExtensionEntry is one configured extension value with the actor and time of its current revision.

type ExtensionOption

type ExtensionOption struct {
	ID    string        `json:"id"`
	Label Field[string] `json:"label,omitzero"`
}

ExtensionOption is a typed option value.

type ExtensionValue

type ExtensionValue struct {
	Atom *ExtensionAtom
	List *List[ExtensionAtom]
}

ExtensionValue is a known extension value: exactly one of Atom or List. A source-confirmed unset value is a null Field and an unresolved one an unknown Field. A list value carries its own coverage.

func (ExtensionValue) MarshalJSON

func (v ExtensionValue) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*ExtensionValue) UnmarshalJSON

func (v *ExtensionValue) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type Extensions

type Extensions struct {
	// CustomFields holds selected schema-defined provider fields (for
	// example Jira customfield_* values).
	CustomFields map[string]ExtensionEntry `json:"custom_fields"`
	// Properties holds selected API key/value properties.
	Properties map[string]ExtensionEntry `json:"properties"`
}

Extensions is the reusable source-defined data shape permitted on the entity, actions, threads, and checks. Both maps are keyed by configured CEL alias. The zero pointer means no extensions are declared for the record.

func (Extensions) MarshalJSON

func (e Extensions) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler, always emitting both maps.

type Field

type Field[T any] struct {
	// contains filtered or unexported fields
}

Field is one entity attribute that may be unresolved. It distinguishes the four states the specification gives a field:

  • absent (the zero value): the field does not apply to this kind or category and is omitted from the document;
  • known: a concrete value of type T;
  • null: the source confirmed there is no value (only valid on nullable fields; the JSON Schema decides which those are);
  • unknown: unresolved, with a UnknownReason. A CEL binding maps this to CEL unknown at the field's attribute path.

Tag Field-typed struct members with `omitzero` so an absent field is omitted when marshaling.

func Known

func Known[T any](v T) Field[T]

Known returns a field holding the concrete value v.

func Null

func Null[T any]() Field[T]

Null returns a field recording that the source confirmed no value.

func Unknown

func Unknown[T any](reason UnknownReason) Field[T]

Unknown returns an unresolved field with the given reason.

func (Field[T]) IsNull

func (f Field[T]) IsNull() bool

IsNull reports whether the source confirmed there is no value.

func (Field[T]) IsZero

func (f Field[T]) IsZero() bool

IsZero reports whether the field is absent. It lets encoding/json's `omitzero` drop inapplicable fields.

func (Field[T]) MarshalJSON

func (f Field[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler. An absent field cannot be marshaled directly; omit it with `omitzero`.

func (*Field[T]) Ptr

func (f *Field[T]) Ptr() *T

Ptr returns a pointer to the concrete value for in-place updates, or nil when the field is not known.

func (Field[T]) UnknownReason

func (f Field[T]) UnknownReason() (UnknownReason, bool)

UnknownReason returns the marker reason and true when the field is unknown.

func (*Field[T]) UnmarshalJSON

func (f *Field[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler. JSON null becomes a null field, an object with a `$unknown` member becomes an unknown field, and anything else is decoded as a concrete T.

func (Field[T]) Value

func (f Field[T]) Value() (T, bool)

Value returns the concrete value and true when the field is known.

type ID

type ID string

ID is the canonical fullsend entity ID defined by the normalized-entity v1 specification: `fullsend:entity:v1:<system>:<host>:<kind>:<source_id>`, where each component is independently percent-encoded from its UTF-8 bytes (RFC 3986 unreserved bytes stay literal; every other byte becomes `%XX` with uppercase hex).

It is not the entity-context snapshot's hashed record key, a repository or project path, or a contextual reference such as `#123`.

func NewID

func NewID(system, host, kind, sourceID string) (ID, error)

NewID builds the canonical entity ID from the normalized source system (for example "github"), the source host (lowercased, including a non-default port when present), the entity kind (for example "work_item"), and the provider's immutable entity ID.

func (ID) Valid

func (id ID) Valid() bool

Valid reports whether id has the canonical shape produced by NewID.

type IssueType

type IssueType struct {
	ID        Field[string] `json:"id,omitzero"`
	Name      Field[string] `json:"name,omitzero"`
	IsSubtask Field[bool]   `json:"is_subtask,omitzero"`
}

IssueType is the source-native issue type.

type Kind

type Kind string

Kind is the entity's domain kind.

const (
	KindWorkItem       Kind = "work_item"
	KindChangeProposal Kind = "change_proposal"
	KindConversation   Kind = "conversation"
)

Entity kinds.

type LabelApplication

type LabelApplication struct {
	Action
	Label Field[string] `json:"label,omitzero"`
}

LabelApplication is the attributable application of a current label.

type Lifecycle

type Lifecycle struct {
	ClosedAt Field[Timestamp] `json:"closed_at,omitzero"`
	ClosedBy Field[Actor]     `json:"closed_by,omitzero"`
	MergedAt Field[Timestamp] `json:"merged_at,omitzero"`
	MergedBy Field[Actor]     `json:"merged_by,omitzero"`
}

Lifecycle records source-backed close and merge times and actors. The merge members apply only to a change proposal.

type List

type List[T any] struct {
	// Known holds the known members in the collection's specified order.
	Known []T
	// Coverage describes any members beyond Known.
	Coverage Coverage
}

List is a logical CEL list that may be only partly known: the known members plus the coverage of the remainder.

The specification serializes coverage in a separate host-only `coverage` document, but a CEL binding needs both at once — it MUST NOT bind the known members as an ordinary complete list when coverage is non-complete. Keeping them together here means the binding can wrap Known and Coverage directly, and the two can never drift apart or be keyed to the wrong collection. Document splits and rejoins them at the JSON boundary.

The zero List is absent: the collection does not apply to the entity's kind and is omitted. A present collection with no known members and no recorded coverage has a non-nil empty Known. Tag List-typed struct members with `omitzero`.

func (List[T]) IsZero

func (l List[T]) IsZero() bool

IsZero reports whether the collection is absent.

func (List[T]) MarshalJSON

func (l List[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler. The serialized form is the bare array of known members; coverage is serialized by Document.

func (*List[T]) UnmarshalJSON

func (l *List[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler. Coverage is rejoined by Document; until then it is zero.

type LogEntry

type LogEntry struct {
	Text      Field[string]    `json:"text,omitzero"`
	Timestamp Field[Timestamp] `json:"timestamp,omitzero"`
}

LogEntry is one source log line.

type Reaction

type Reaction struct {
	ID        string           `json:"id"`
	Content   Field[string]    `json:"content,omitzero"`
	Actor     Actor            `json:"actor"`
	CreatedAt Field[Timestamp] `json:"created_at,omitzero"`
}

Reaction is a source-backed reaction on the entity.

type Review

type Review struct {
	TextAction
	ReviewState Field[ReviewState] `json:"review_state,omitzero"`
}

Review is a submitted formal review on a change proposal.

type ReviewState

type ReviewState string

ReviewState is a formal review's disposition.

const (
	ReviewApproved         ReviewState = "approved"
	ReviewChangesRequested ReviewState = "changes_requested"
	ReviewCommented        ReviewState = "commented"
	ReviewDismissed        ReviewState = "dismissed"
)

Review states.

type Reviewer

type Reviewer struct {
	Subject ReviewerSubject      `json:"subject"`
	State   Field[ReviewerState] `json:"state,omitzero"`
}

Reviewer is one current reviewer assignment or standing.

type ReviewerState

type ReviewerState string

ReviewerState is a reviewer's current standing.

const (
	ReviewerUnreviewed       ReviewerState = "unreviewed"
	ReviewerReviewStarted    ReviewerState = "review_started"
	ReviewerReviewed         ReviewerState = "reviewed"
	ReviewerApproved         ReviewerState = "approved"
	ReviewerChangesRequested ReviewerState = "changes_requested"
	ReviewerUnapproved       ReviewerState = "unapproved"
	ReviewerDismissed        ReviewerState = "dismissed"
)

Reviewer states.

type ReviewerSubject

type ReviewerSubject struct {
	Actor
	Name Field[string] `json:"name,omitzero"`
}

ReviewerSubject is a reviewer's identity: an actor, or a team (Kind ActorTeam with ID and Name, and no other actor members).

type Role

type Role string

Role is the Authorization Contract role vocabulary.

const (
	RoleAdmin    Role = "admin"
	RoleMaintain Role = "maintain"
	RoleWrite    Role = "write"
	RoleTriage   Role = "triage"
	RoleRead     Role = "read"
	RoleNone     Role = "none"
	RoleExternal Role = "external"
)

Roles.

type Side

type Side string

Side is a diff side.

const (
	SideLeft  Side = "left"
	SideRight Side = "right"
)

Diff sides.

type Source

type Source struct {
	System       System `json:"system"`
	Host         string `json:"host"`
	Repository   string `json:"repository,omitempty"`
	RepositoryID string `json:"repository_id,omitempty"`
	Project      string `json:"project,omitempty"`
	ProjectID    string `json:"project_id,omitempty"`
}

Source identifies the authoritative system and container of an entity. Forge entities set Repository and RepositoryID; Jira entities set Project and ProjectID.

type SourceStatus

type SourceStatus struct {
	Name     Field[string] `json:"name,omitzero"`
	Category Field[string] `json:"category,omitzero"`
}

SourceStatus is the source-native status name and category.

type State

type State string

State is the portable current entity state.

const (
	StateOpen   State = "open"
	StateClosed State = "closed"
	StateMerged State = "merged"
)

Entity states. Merged applies only to a change proposal.

type System

type System string

System is the authoritative source system.

const (
	SystemGitHub System = "github"
	SystemGitLab System = "gitlab"
	SystemJira   System = "jira"
)

Source systems.

type TextAction

type TextAction struct {
	Action
	Text    Field[string] `json:"text,omitzero"`
	Command Field[string] `json:"command,omitzero"`
}

TextAction is an action carrying filtered text: the entity body, and the base of comments and reviews. Text is the complete filtered current text (an empty string is valid) or unknown; Command is the first-line command token, null when there is none, or unknown.

type Thread

type Thread struct {
	ID         string                `json:"id"`
	CreatedAt  Timestamp             `json:"created_at"`
	CommentIDs List[string]          `json:"comment_ids,omitzero"`
	Resolved   Field[bool]           `json:"resolved,omitzero"`
	Outdated   Field[bool]           `json:"outdated,omitzero"`
	ReviewID   Field[string]         `json:"review_id,omitzero"`
	ResolvedBy Field[Actor]          `json:"resolved_by,omitzero"`
	Location   Field[ThreadLocation] `json:"location,omitzero"`
	Extensions *Extensions           `json:"extensions,omitempty"`
}

Thread is a source comment thread. CommentIDs lists known admitted comment IDs in source thread order, with its own coverage.

type ThreadLocation

type ThreadLocation struct {
	Path              string      `json:"path"`
	Line              Field[int]  `json:"line,omitzero"`
	Side              Field[Side] `json:"side,omitzero"`
	StartLine         Field[int]  `json:"start_line,omitzero"`
	StartSide         Field[Side] `json:"start_side,omitzero"`
	OriginalLine      Field[int]  `json:"original_line,omitzero"`
	OriginalStartLine Field[int]  `json:"original_start_line,omitzero"`
	OldLine           Field[int]  `json:"old_line,omitzero"`
	NewLine           Field[int]  `json:"new_line,omitzero"`
}

ThreadLocation is a source-backed diff position.

type Timestamp

type Timestamp string

Timestamp is a UTC string in `YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ` form (exactly nine fractional digits), so lexical comparison equals chronological comparison, including in CEL. It is deliberately a string, not time.Time.

type UnknownReason

type UnknownReason string

UnknownReason is the diagnostic carried by a serialized `{"$unknown": ...}` marker. Every reason maps to CEL unknown; the distinction is for the host.

const (
	ReasonNotLoaded          UnknownReason = "not_loaded"
	ReasonPartial            UnknownReason = "partial"
	ReasonUnsupported        UnknownReason = "unsupported"
	ReasonFailed             UnknownReason = "failed"
	ReasonConsistencyUnknown UnknownReason = "consistency_unknown"
)

Unknown-marker reasons defined by the normalized-entity v1 specification.

func (UnknownReason) Valid

func (r UnknownReason) Valid() bool

Valid reports whether r is one of the specified reasons.

type View

type View struct {
	// HumanMinRole is the harness threshold applied to known actions.
	HumanMinRole Role `json:"human_min_role"`
	// ResolvedAt is the check time every known value is authoritative for.
	ResolvedAt Timestamp `json:"resolved_at"`
	// FilterVersion is the active content-safety pipeline version.
	FilterVersion string `json:"filter_version"`
}

View is the host-only metadata describing how an entity was resolved. It is not visible to CEL.

type WorkItem

type WorkItem struct {
	SourceStatus Field[SourceStatus] `json:"source_status,omitzero"`
	IssueType    Field[IssueType]    `json:"issue_type,omitzero"`
	StateReason  Field[string]       `json:"state_reason,omitzero"`
}

WorkItem holds work-item-only source details.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL