encoded, err := json.Marshal(value)

if err != nil {

return Observation{}, err

}

fingerprint, err := contentHash(json.RawMessage(encoded))

return Observation{Fingerprint: fingerprint, Value: encoded}, err

if len(o.Fingerprint) != 64 || len(o.Value) == 0 || !json.Valid(o.Value) {

return fmt.Errorf("domain observation requires canonical value and fingerprint")

}

fingerprint, err := contentHash(o.Value)

if err != nil || fingerprint != o.Fingerprint {

return fmt.Errorf("domain observation fingerprint mismatch")

}

return nil

State ControlState

Observation Observation

Objective *Objective

Transition Transition

Observe(context.Context, string) (Observation, error)

// Admissible must keep a declared recovery transition admissible while its

// matching RecoveryState is active, including after an earlier recovery

// attempt may already have changed the domain.

Admissible(context.Context, Evaluation) (bool, string, error)

Verify(context.Context, Evaluation, Effect, Observation) error

InstanceID string

Transition Transition

Observation Observation

Objective *Objective

Capabilities []Capability

Load(context.Context, string) (ControlState, error)

BeginEffect(context.Context, uint64, ControlState) error

CommitTransition(context.Context, uint64, ControlState, Receipt) error

Kind DecisionKind `json:"kind"`

Transition string `json:"transition,omitempty"`

Candidates []string `json:"candidates,omitempty"`

Reason string `json:"reason"`

SchemaVersion int `json:"schema_version"`

ID string `json:"id"`

TransitionID string `json:"transition_id"`

Freshness

ExpectedObjectiveBinding *ObjectiveBinding `json:"expected_objective_binding,omitempty"`

RequestedObjectiveBinding *ObjectiveBinding `json:"requested_objective_binding,omitempty"`

RequiredCapabilities []Capability `json:"required_capabilities"`

State ControlState `json:"state"`

Observation Observation `json:"observation"`

Decision Decision `json:"decision"`

Prescription *Prescription `json:"prescription,omitempty"`

Trace *DecisionTrace `json:"trace,omitempty"`

InstanceID string

Objective *Objective

Authority Authority

Requested string

Trace bool

SchemaVersion int `json:"schema_version"`

ID string `json:"id"`

InstanceID string `json:"instance_id"`

PrescriptionID string `json:"prescription_id"`

Program ProgramIdentity `json:"program"`

TransitionID string `json:"transition_id"`

PriorStateRevision uint64 `json:"prior_state_revision"`

AttemptStateRevision uint64 `json:"attempt_state_revision"`

ResultStateRevision uint64 `json:"result_state_revision"`

ObjectiveBinding *ObjectiveBinding `json:"objective_binding,omitempty"`

AuthorityFingerprint string `json:"authority_fingerprint"`

Capabilities []Capability `json:"capabilities"`

Effects []EffectFact `json:"effects"`

PriorObservation string `json:"prior_observation"`

ResultObservation string `json:"result_observation"`

Verification string `json:"verification"`

CommittedAt time.Time `json:"committed_at"`

program Program

domain Domain

operator Operator

classifier CapabilityClassifier

store Store

locker Locker

clock Clock

if err := program.Validate(); err != nil {

return Runtime{}, err

}

if domain == nil || operator == nil || classifier == nil || store == nil || locker == nil || clock == nil {

return Runtime{}, fmt.Errorf("kernel runtime requires domain, operator, capability classifier, transactional store, lock, and clock ports")

}

for _, transition := range program.Transitions {

if _, err := requiredCapabilities(classifier, transition); err != nil {

return Runtime{}, err

}

}

return Runtime{program: program, domain: domain, operator: operator, classifier: classifier, store: store, locker: locker, clock: clock}, nil

state, err := r.store.Load(ctx, request.InstanceID)

if err != nil {

return Resolution{}, err

}

observation, err := r.domain.Observe(ctx, request.InstanceID)

if err != nil {

return Resolution{}, err

}

return r.resolve(ctx, state, observation, request)

base := Resolution{State: state, Observation: observation}

trace := newDecisionTrace(state, observation, request, r.program.Identity())

trace.Marked = r.program.Marked(state.Mode)

finish := func(decision Decision) (Resolution, error) {

base.Decision = decision

trace.Decision = TraceDecision(decision)

if request.Trace {

base.Trace = &trace

}

return base, nil

}

if err := state.Validate(); err != nil {

return finish(Decision{Kind: Unresolved, Reason: "control state is invalid: " + err.Error()})

}

if err := observation.Validate(); err != nil {

return finish(Decision{Kind: Unresolved, Reason: "domain observation is invalid: " + err.Error()})

}

if state.InstanceID != request.InstanceID {

return finish(Decision{Kind: Unresolved, Reason: "control state instance identity does not match the request"})

}

if state.Program != r.program.Identity() {

return finish(Decision{Kind: Unresolved, Reason: "control state program identity is stale for the active program"})

}

if r.program.Marked(state.Mode) && state.Recovery == nil && request.Requested == "" {

return finish(Decision{Kind: Marked, Reason: "program-defined marked state is established"})

}

authority, err := request.Authority.projection(r.clock.Now())

if err != nil {

return finish(Decision{Kind: Refused, Reason: err.Error()})

}

trace.AuthorityFingerprint = authority.Fingerprint

transitions := map[string]Transition{}

var candidates []RelationCandidate

for _, transition := range r.program.Transitions {

candidateTrace := CandidateTrace{TransitionID: transition.ID, Priority: transition.Priority}

if request.Requested != "" && transition.ID != request.Requested {

candidateTrace.Disposition = DispositionIrrelevantToRequest

trace.Candidates = append(trace.Candidates, candidateTrace)

continue

}

if !contains(transition.SourceModes, state.Mode) {

candidateTrace.SourceMode = EvaluationTrace{Evaluated: true, Reason: fmt.Sprintf("current mode %q is not a declared source mode", state.Mode)}

candidateTrace.Disposition = DispositionSourceModeRejected

trace.Candidates = append(trace.Candidates, candidateTrace)

continue

}

candidateTrace.SourceMode = EvaluationTrace{Evaluated: true, Satisfied: true, Reason: "current mode is a declared source mode"}

if state.Recovery != nil && !contains(transition.Recovers, state.Recovery.TransitionID) {

candidateTrace.RecoveryCompatible = EvaluationTrace{Evaluated: true, Reason: fmt.Sprintf("transition does not recover %q", state.Recovery.TransitionID)}

candidateTrace.Disposition = DispositionRecoveryRejected

trace.Candidates = append(trace.Candidates, candidateTrace)

continue

}

if state.Recovery == nil && len(transition.Recovers) != 0 {

candidateTrace.RecoveryCompatible = EvaluationTrace{Evaluated: true, Reason: "recovery transition requires an active recovery state"}

candidateTrace.Disposition = DispositionRecoveryRejected

trace.Candidates = append(trace.Candidates, candidateTrace)

continue

}

candidateTrace.RecoveryCompatible = EvaluationTrace{Evaluated: true, Satisfied: true, Reason: "recovery state is compatible"}

objective, reason := objectiveFor(state, request.Objective, transition)

if reason != "" {

candidateTrace.ObjectiveScope = EvaluationTrace{Evaluated: true, Reason: reason}

candidateTrace.ObjectiveMutation = EvaluationTrace{Evaluated: true, Reason: reason}

candidateTrace.Disposition = DispositionObjectiveRejected

trace.Candidates = append(trace.Candidates, candidateTrace)

continue

}

candidateTrace.ObjectiveScope = EvaluationTrace{Evaluated: true, Satisfied: true, Reason: "objective scope is satisfied"}

candidateTrace.ObjectiveMutation = EvaluationTrace{Evaluated: true, Satisfied: true, Reason: "objective mutation is admissible"}

allowed, domainReason, evaluationErr := r.domain.Admissible(ctx, Evaluation{State: state, Observation: observation, Objective: objective, Transition: transition})

if evaluationErr != nil {

return Resolution{}, evaluationErr

}

candidateTrace.DomainAdmissible = EvaluationTrace{Evaluated: true, Satisfied: allowed, Reason: boundedTraceReason(domainReason)}

if !allowed {

candidateTrace.Disposition = DispositionDomainRejected

trace.Candidates = append(trace.Candidates, candidateTrace)

continue

}

required, capabilityErr := requiredCapabilities(r.classifier, transition)

if capabilityErr != nil {

return Resolution{}, capabilityErr

}

candidateTrace.Selectable, candidateTrace.Survived = true, true

transitions[transition.ID] = transition

candidates = append(candidates, RelationCandidate{ID: transition.ID, Priority: transition.Priority, Selectable: true, RequiredAll: required})

trace.Candidates = append(trace.Candidates, candidateTrace)

}

var relationTraces []CandidateTrace

base.Decision, relationTraces = RelateWithTrace(RelationInput{Requested: request.Requested, Candidates: candidates, Available: authority.Capabilities})

mergeRelationTraces(trace.Candidates, relationTraces)

trace.Decision = TraceDecision(base.Decision)

if base.Decision.Kind != Prescribed {

if request.Trace {

base.Trace = &trace

}

return base, nil

}

top := transitions[base.Decision.Transition]

required, err := requiredCapabilities(r.classifier, top)

if err != nil {

return Resolution{}, err

}

objective, _ := objectiveFor(state, request.Objective, top)

prescription, err := newPrescription(state, observation, top, objective, authority, required)

if err != nil {

return Resolution{}, err

}

base.Prescription = &prescription

if request.Trace {

base.Trace = &trace

}

return base, nil

stateProgram := state.Program

trace := DecisionTrace{

SchemaVersion: DecisionTraceSchemaVersion, InstanceID: state.InstanceID,

StateRevision: state.Revision, CurrentMode: state.Mode, Program: program, StateProgram: &stateProgram,

ObservationFingerprint: observation.Fingerprint, RequestedTransition: request.Requested,

Marked: false,

}

if state.ObjectiveBinding != nil {

trace.Objective.Binding = &ObjectiveIdentity{ID: state.ObjectiveBinding.ObjectiveID, Revision: state.ObjectiveBinding.ObjectiveRevision, Fingerprint: state.ObjectiveBinding.ObjectiveFingerprint}

}

if request.Objective != nil {

trace.Objective.Requested = &ObjectiveIdentity{ID: request.Objective.ID, Revision: request.Objective.Revision, Fingerprint: request.Objective.Fingerprint}

}

if state.Recovery != nil {

trace.Recovery = &RecoveryTrace{Active: true, PrescriptionID: state.Recovery.PrescriptionID, TransitionID: state.Recovery.TransitionID, Reason: state.Recovery.Reason}

}

return trace

const limit = 1024

if len(reason) <= limit {

return reason

}

return reason[:limit]

byID := make(map[string]CandidateTrace, len(relation))

for _, candidate := range relation {

byID[candidate.TransitionID] = candidate

}

for index := range candidates {

resolved, ok := byID[candidates[index].TransitionID]

if !ok {

continue

}

candidates[index].Selectable = resolved.Selectable

candidates[index].Rank = resolved.Rank

candidates[index].Priority = resolved.Priority

candidates[index].Authority = resolved.Authority

candidates[index].Survived = resolved.Survived

candidates[index].Disposition = resolved.Disposition

}

lock, err := r.locker.Acquire(ctx, request.InstanceID)

if err != nil {

return Receipt{}, err

}

defer lock.Unlock()

state, err := r.store.Load(ctx, request.InstanceID)

if err != nil {

return Receipt{}, err

}

observation, err := r.domain.Observe(ctx, request.InstanceID)

if err != nil {

return Receipt{}, err

}

authority, err := request.Authority.projection(r.clock.Now())

if err != nil {

return Receipt{}, err

}

if err := request.Prescription.validateCurrent(state, observation, authority); err != nil {

return Receipt{}, err

}

resolution, err := r.resolve(ctx, state, observation, request.ResolveRequest)

if err != nil {

return Receipt{}, err

}

if resolution.Decision.Kind != Prescribed || resolution.Prescription == nil {

return Receipt{}, fmt.Errorf("apply refused: %s", resolution.Decision.Reason)

}

if request.Prescription.ID != resolution.Prescription.ID {

return Receipt{}, StalePrescriptionError{Reason: "state, program, objective binding, observation, authority, or transition changed"}

}

transition, ok := r.program.Transition(request.Prescription.TransitionID)

if !ok {

return Receipt{}, StalePrescriptionError{Reason: "transition no longer belongs to the program"}

}

objective, _ := objectiveFor(state, request.Objective, transition)

required, err := requiredCapabilities(r.classifier, transition)

if err != nil {

return Receipt{}, err

}

attempt := state

attempt.Revision++

if state.Recovery == nil {

attempt.Recovery = &RecoveryState{

PrescriptionID: request.Prescription.ID,

TransitionID: request.Prescription.TransitionID,

Reason: "effect attempt began; outcome is unresolved",

}

} else {

recovery := *state.Recovery

attempt.Recovery = &recovery

}

if err := attempt.Validate(); err != nil {

return Receipt{}, fmt.Errorf("effect attempt state is invalid: %w", err)

}

if err := r.store.BeginEffect(ctx, state.Revision, attempt); err != nil {

return Receipt{}, fmt.Errorf("effect attempt did not begin: %w", err)

}

effect, err := r.operator.Execute(ctx, Operation{InstanceID: request.InstanceID, Transition: transition, Observation: observation, Objective: objective, Capabilities: required})

if err != nil {

return Receipt{}, RecoveryRequiredError{Reason: fmt.Sprintf("operator outcome is unknown: %v", err)}

}

if err := validateEffects(transition, effect); err != nil {

return Receipt{}, RecoveryRequiredError{Reason: err.Error()}

}

sort.Slice(effect.Facts, func(i, j int) bool {

if effect.Facts[i].Facet != effect.Facts[j].Facet {

return effect.Facts[i].Facet < effect.Facts[j].Facet

}

if effect.Facts[i].Operation != effect.Facts[j].Operation {

return effect.Facts[i].Operation < effect.Facts[j].Operation

}

return effect.Facts[i].Fingerprint < effect.Facts[j].Fingerprint

})

targetObservation, err := r.domain.Observe(ctx, request.InstanceID)

if err != nil {

return Receipt{}, RecoveryRequiredError{Reason: fmt.Sprintf("target observation failed: %v", err)}

}

if err := r.domain.Verify(ctx, Evaluation{State: state, Observation: observation, Objective: objective, Transition: transition}, effect, targetObservation); err != nil {

return Receipt{}, RecoveryRequiredError{Reason: fmt.Sprintf("verification failed: %v", err)}

}

target := attempt

target.Mode = transition.TargetMode

target.Revision++

switch transition.ObjectiveMutation {

case BindObjectiveMutation:

binding, bindErr := BindObjective(*objective)

if bindErr != nil {

return Receipt{}, bindErr

}

target.ObjectiveBinding = &binding

case ClearObjectiveMutation:

target.ObjectiveBinding = nil

}

target.Recovery = nil

receipt := Receipt{SchemaVersion: ReceiptSchemaVersion, InstanceID: state.InstanceID, PrescriptionID: request.Prescription.ID, Program: state.Program, TransitionID: transition.ID, PriorStateRevision: state.Revision, AttemptStateRevision: attempt.Revision, ResultStateRevision: target.Revision, ObjectiveBinding: cloneBinding(target.ObjectiveBinding), AuthorityFingerprint: authority.Fingerprint, Capabilities: required, Effects: append([]EffectFact(nil), effect.Facts...), PriorObservation: observation.Fingerprint, ResultObservation: targetObservation.Fingerprint, Verification: "satisfied", CommittedAt: r.clock.Now().UTC()}

identity := receipt

identity.ID = ""

receipt.ID, err = contentHash(identity)

if err != nil {

return Receipt{}, err

}

receipt.ID = "rcp-" + receipt.ID

if err := receipt.Validate(); err != nil {

return Receipt{}, RecoveryRequiredError{Reason: "transition receipt is invalid: " + err.Error()}

}

if err := r.store.CommitTransition(ctx, attempt.Revision, target, receipt); err != nil {

return Receipt{}, RecoveryRequiredError{Reason: "state and receipt transaction did not commit: " + err.Error()}

}

return receipt, nil

identity := r

want := identity.ID

identity.ID = ""

got, err := contentHash(identity)

if err != nil || want != "rcp-"+got {

return fmt.Errorf("receipt content identity is invalid")

}

if r.SchemaVersion != ReceiptSchemaVersion || !semanticID.MatchString(r.InstanceID) || r.PrescriptionID == "" || !qualifiedSemanticID.MatchString(r.TransitionID) || r.PriorStateRevision == 0 || r.AttemptStateRevision != r.PriorStateRevision+1 || r.ResultStateRevision != r.AttemptStateRevision+1 || r.AuthorityFingerprint == "" || len(r.PriorObservation) != 64 || len(r.ResultObservation) != 64 || r.Verification != "satisfied" || r.CommittedAt.IsZero() {

return fmt.Errorf("receipt is missing exact instance, transition, revision, observation, authority, or verification facts")

}

if err := r.Program.Validate(); err != nil {

return err

}

if r.ObjectiveBinding != nil {

if err := r.ObjectiveBinding.Validate(); err != nil {

return err

}

}

if _, err := normalizeCapabilities(r.Capabilities); err != nil {

return err

}

if len(r.Effects) == 0 {

return fmt.Errorf("receipt contains no committed effect facts")

}

return nil

bindingFingerprint, err := Fingerprint(state.ObjectiveBinding)

if err != nil {

return Prescription{}, err

}

freshness, err := NewFreshness(state.InstanceID, state.Revision, state.Program.Fingerprint, observation.Fingerprint, bindingFingerprint, authority.Fingerprint)

if err != nil {

return Prescription{}, err

}

p := Prescription{SchemaVersion: PrescriptionSchemaVersion, TransitionID: transition.ID, Freshness: freshness, RequiredCapabilities: append([]Capability(nil), required...)}

p.ExpectedObjectiveBinding = cloneBinding(state.ObjectiveBinding)

if transition.ObjectiveMutation == BindObjectiveMutation {

binding, err := BindObjective(*objective)

if err != nil {

return Prescription{}, err

}

p.RequestedObjectiveBinding = &binding

}

identity := p

identity.ID = ""

id, err := contentHash(identity)

if err != nil {

return Prescription{}, err

}

p.ID = "prx-" + id

return p, nil

identity := p

want := identity.ID

identity.ID = ""

got, err := contentHash(identity)

if err != nil || want != "prx-"+got {

return StalePrescriptionError{Reason: "prescription content identity is invalid"}

}

bindingFingerprint, bindingErr := Fingerprint(state.ObjectiveBinding)

current, freshnessErr := NewFreshness(state.InstanceID, state.Revision, state.Program.Fingerprint, observation.Fingerprint, bindingFingerprint, authority.Fingerprint)

if p.SchemaVersion != PrescriptionSchemaVersion || bindingErr != nil || freshnessErr != nil || p.Freshness.Check(current) != nil || !equalBinding(p.ExpectedObjectiveBinding, state.ObjectiveBinding) {

return StalePrescriptionError{Reason: "instance, state, program, objective binding, observation, or authority changed"}

}

return nil

if transition.ObjectiveMutation == BindObjectiveMutation {

if supplied == nil || supplied.Validate() != nil {

return nil, "objective binding requires one exact objective revision"

}

if state.ObjectiveBinding != nil && state.ObjectiveBinding.Matches(*supplied) {

return nil, "objective revision is already bound"

}

copy := *supplied

return &copy, ""

}

if transition.ObjectiveMutation == ClearObjectiveMutation && state.ObjectiveBinding == nil {

return nil, "objective binding is already absent"

}

switch transition.ObjectiveScope {

case ObjectiveNone:

return nil, ""

case ObjectiveOptionalPreserve:

if state.ObjectiveBinding != nil && supplied != nil && state.ObjectiveBinding.Matches(*supplied) {

copy := *supplied

return &copy, ""

}

// A command-scoped objective is not allowed to reinterpret durable

// supervisory state. Maintenance runs without an objective projection

// while its prescription remains bound to the exact existing binding.

return nil, ""

case ObjectiveBoundExact:

if state.ObjectiveBinding == nil || supplied == nil || !state.ObjectiveBinding.Matches(*supplied) {

return nil, "transition requires the exact bound objective revision"

}

copy := *supplied

return &copy, ""

default:

return nil, "invalid objective scope"

}

if len(effect.Facts) == 0 {

return fmt.Errorf("operator returned no committed effect facts")

}

owned := map[string]bool{}

for _, facet := range transition.OwnedFacets {

owned[facet] = true

}

for _, fact := range effect.Facts {

if !owned[fact.Facet] || !qualifiedSemanticID.MatchString(fact.Operation) || fact.Fingerprint == "" {

return fmt.Errorf("effect fact escapes transition-owned facets or is incomplete")

}

}

return nil

set := map[Capability]bool{}

for _, value := range available {

set[value] = true

}

var result []Capability

for _, value := range required {

if !set[value] {

result = append(result, value)

}

}

return result

minimum, err := classifier.RequiredCapabilities(transition)

if err != nil {

return nil, err

}

return normalizeCapabilities(append(append([]Capability(nil), transition.RequiredCapabilities...), minimum...))

for _, value := range values {

if value == wanted {

return true

}

}

return false

for _, value := range values {

if value == wanted {

return true

}

}

return false

if value == nil {

return nil

}

copy := *value

return &copy

if left == nil || right == nil {

return left == nil && right == nil

}

return *left == *right