commitrollup

Documentation

Overview

Package commitrollup plans compatible commit-intent batches without touching git.

The live drain path is expected to supply already-validated commit intents. This package only answers the pure compatibility question: which intents can share one witnessed commit, which ones must bounce, and whether the final committed path set still equals the planned union.

Index

• Constants
• type Config
• type Intent
• type PathsetAssertion
  • func AssertPathset(expected, actual []string) PathsetAssertion
• type Plan
  • func PlanBatch(intents []Intent, cfg Config) Plan
  • func (p Plan) AssertPathset(actual []string) PathsetAssertion
• type Reason
• type Refusal

Constants

const Schema = "fak.commit-rollup/v1"

Schema identifies the machine-readable planner envelope.

Types

type Config

type Config struct {
	// DisableRollup keeps one-intent-at-a-time behavior while still returning
	// typed bounces for every intent that was not allowed into the next commit.
	DisableRollup bool
}

Config controls planner behavior. The zero value enables rollup.

type Intent

type Intent struct {
	ID        string   `json:"id"`
	Submitter string   `json:"submitter,omitempty"`
	Paths     []string `json:"paths"`
	Stamp     string   `json:"stamp"`

	Stale         bool     `json:"stale,omitempty"`
	Refused       bool     `json:"refused,omitempty"`
	RefusedReason Reason   `json:"refused_reason,omitempty"`
	Witnesses     []string `json:"witnesses,omitempty"`
}

Intent is the minimal local shape the #1788 commit-intent drain can later map into. Stamp accepts either a leaf ("gateway") or a trailer ("(fak gateway)").

type PathsetAssertion

type PathsetAssertion struct {
	OK       bool     `json:"ok"`
	Reason   Reason   `json:"reason,omitempty"`
	Expected []string `json:"expected"`
	Actual   []string `json:"actual"`
	Missing  []string `json:"missing,omitempty"`
	Extra    []string `json:"extra,omitempty"`
}

PathsetAssertion is a pure equality witness for the later impure commit step: the committed pathset must equal the planner's union, with no hidden expansion.

func AssertPathset

func AssertPathset(expected, actual []string) PathsetAssertion

AssertPathset compares the planned union with the paths the commit layer says it actually committed.

type Plan

type Plan struct {
	Schema        string    `json:"schema"`
	OK            bool      `json:"ok"`
	RollupEnabled bool      `json:"rollup_enabled"`
	Stamp         string    `json:"stamp,omitempty"`
	Trailer       string    `json:"trailer,omitempty"`
	Subject       string    `json:"subject,omitempty"`
	IntentIDs     []string  `json:"intent_ids"`
	Submitters    []string  `json:"submitters,omitempty"`
	UnionPaths    []string  `json:"union_paths"`
	Witnesses     []string  `json:"witnesses,omitempty"`
	Refusals      []Refusal `json:"refusals,omitempty"`
}

Plan is the pure rollup decision for the next commit.

func PlanBatch

func PlanBatch(intents []Intent, cfg Config) Plan

PlanBatch greedily builds the next compatible rollup batch from queued intents. It is deterministic, side-effect free, and never reads git.

func (Plan) AssertPathset

func (p Plan) AssertPathset(actual []string) PathsetAssertion

AssertPathset compares this plan's union with the actual committed pathset.

type Reason

type Reason string

Reason is a closed refusal token emitted by the pure planner.

const (
	ReasonMissingID         Reason = "MISSING_ID"
	ReasonMissingPathset    Reason = "MISSING_PATHSET"
	ReasonInvalidPath       Reason = "INVALID_PATH"
	ReasonMissingStamp      Reason = "MISSING_STAMP"
	ReasonInvalidStamp      Reason = "INVALID_STAMP"
	ReasonStaleInput        Reason = "STALE_INPUT"
	ReasonRefusedInput      Reason = "REFUSED_INPUT"
	ReasonOverlappingPath   Reason = "OVERLAPPING_PATH"
	ReasonIncompatibleStamp Reason = "INCOMPATIBLE_STAMP"
	ReasonRollupDisabled    Reason = "ROLLUP_DISABLED"
	ReasonPathsetMismatch   Reason = "PATHSET_MISMATCH"
)

type Refusal

type Refusal struct {
	IntentID string   `json:"intent_id,omitempty"`
	Reason   Reason   `json:"reason"`
	Detail   string   `json:"detail,omitempty"`
	Paths    []string `json:"paths,omitempty"`
	Stamp    string   `json:"stamp,omitempty"`
}

Refusal records why a single input intent could not join the planned batch.