event

type Actor ¶

type Actor struct {
	Kind string `json:"kind"`
	ID   string `json:"id"`
}

Actor identifies the originator of an event.

type Artifact ¶

type Artifact struct {
	Type     string `json:"type"`
	ID       string `json:"id"`
	Path     string `json:"path"`
	Revision string `json:"revision"`
}

Artifact identifies the SpecScore artifact an event refers to.

type DispatchResult ¶

type DispatchResult struct {
	// ValidationError is non-nil when envelope validation failed; in that
	// case no subscriber was invoked.
	ValidationError error
	// Delivered counts subscribers whose Deliver returned nil.
	Delivered int
	// Failed counts subscribers whose Deliver returned a non-nil error.
	Failed int
	// Failures lists each non-nil Deliver error in declared order.
	Failures []SubscriberFailure
}

DispatchResult is the structured outcome of a Dispatch call. The verb layer maps it to the standard exit-code contract (REQ:dispatch-exit-codes):

• ValidationError != nil -> exit 2
• Delivered > 0 OR len(subscribers) == 0 -> exit 0
• Failed > 0 AND Delivered == 0 AND len(subscribers) > 0 -> exit 10

Exit codes 3 (missing project root) and other 2-class failures (config validation) are produced by callers above Dispatch.

func Dispatch(ctx context.Context, e Event, subscribers []Subscriber) DispatchResult

event-dispatch failure: subscriber=<Name()> event=<e.Name> error="<err.Error()>"

type Event ¶

type Event struct {
	Name      string          `json:"name"`
	Version   int             `json:"version"`
	UUID      string          `json:"uuid"`
	Timestamp time.Time       `json:"timestamp"`
	Actor     Actor           `json:"actor"`
	Artifact  Artifact        `json:"artifact"`
	Payload   json.RawMessage `json:"payload"`
}

Event is the common envelope passed to every Subscriber. Field shapes mirror the cross-repo event contract; see REQ:envelope-validation in spec/features/cli/event/README.md.

type Exec ¶

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

Exec is a Subscriber that delivers events by spawning a child process and piping the JSON-serialized envelope to its stdin. It enforces a wall-clock timeout: on expiry the command tree is terminated using platform-specific process-group or tree controls. The configured env mapping is appended to the inherited process environment (additive, not replacement).

func NewExec(argv []string, env map[string]string, timeout time.Duration) *Exec

func (x *Exec) Deliver(ctx context.Context, e Event) error

func (x *Exec) Name() string

type ExecExitError ¶

type ExecExitError struct {
	ExitCode int
	Cause    error
}

ExecExitError is returned when the child exited non-zero without hitting the timeout. ExitCode is the OS-reported exit status.

func (e *ExecExitError) Error() string

func (e *ExecExitError) Unwrap() error

type ExecTimeoutError ¶

type ExecTimeoutError struct {
	Timeout time.Duration
	Cause   error
}

ExecTimeoutError is returned when the configured wall-clock timeout elapsed before the child completed. It is distinguishable from *ExecExitError so the dispatcher's stderr log can name the failure mode.

func (e *ExecTimeoutError) Error() string

func (e *ExecTimeoutError) Unwrap() error

type JsonlWriter ¶

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

JsonlWriter is a Subscriber that appends each delivered Event as a single JSON line to a file. It is the default subscriber synthesized by the config loader when the `events:` block is omitted; see spec/features/cli/event/README.md.

Relative configured paths resolve against the project root supplied at construction time, NEVER against the current working directory. The dispatcher wires the project root in once, at startup.

func NewJsonlWriter(path string, projectRoot string) *JsonlWriter

func (w *JsonlWriter) Deliver(_ context.Context, e Event) error

func (w *JsonlWriter) Name() string

func (w *JsonlWriter) Path() string

type MergeInputError ¶ added in v0.38.0

type MergeInputError struct{ Err error }

MergeInputError identifies a merge refusal caused by invalid or ambiguous input. CLI callers can map it to their invalid-arguments exit status while retaining a different status for publication failures.

func (e *MergeInputError) Error() string

func (e *MergeInputError) Unwrap() error

type MergeOptions ¶ added in v0.38.0

type MergeOptions struct {
	// DryRun validates and plans the union without changing the target.
	DryRun bool
}

MergeOptions controls MergeLedgersWithOptions.

type MergeResult ¶ added in v0.38.0

type MergeResult struct {
	Target   string
	Existing int
	Added    int
	Skipped  int
}

MergeResult describes an event-ledger union. Existing target bytes are never rewritten; Added is the number of source-only events appended.

func MergeJSONL(target string, sources []string) (MergeResult, error)

func MergeLedgers(target string, sources []string) (MergeResult, error)

func MergeLedgersWithOptions(target string, sources []string, options MergeOptions) (MergeResult, error)

type NoOp ¶

type NoOp struct{}

NoOp is the explicit-opt-out Subscriber: it accepts every event, performs no work, and returns nil. It exists so an operator can configure events: with a "noop" entry and signal "I have considered subscribers and chosen none" rather than relying on the absence of configuration. See AC:noop-discards in spec/features/cli/event/README.md.

func (NoOp) Deliver(ctx context.Context, e Event) error

func (NoOp) Name() string

type Outbox ¶ added in v0.34.0

type Outbox struct{ Root string }

func NewOutbox(projectRoot string) Outbox

func (o Outbox) Abort(id string) error

func (o Outbox) Commit(id string) error

func (o Outbox) Enqueue(e Event, subscribers []Subscriber) error

func (o Outbox) FindPreparedIntent(intent Event, facts json.RawMessage) (*Event, error)

func (o Outbox) Prepare(e Event, subscribers []Subscriber) error

func (o Outbox) PrepareIntent(e Event, subscribers []Subscriber, facts json.RawMessage) error

func (o Outbox) Prepared() ([]PreparedRecord, error)

func (o Outbox) Recover() error

func (o Outbox) Replay(ctx context.Context, subscribers []Subscriber, name string, limit int) (ReplayResult, error)

func (o Outbox) ReplayFrom(ctx context.Context, subscribers []Subscriber, name, from string, limit int) (ReplayResult, error)

type PreparedRecord ¶ added in v0.34.0

type PreparedRecord struct {
	EventUUID      string    `json:"event_uuid"`
	EventName      string    `json:"event_name"`
	ArtifactPath   string    `json:"artifact_path"`
	ArtifactExists bool      `json:"artifact_exists"`
	Timestamp      time.Time `json:"timestamp"`
}

PreparedRecord is an interrupted two-phase event awaiting an explicit commit/abort decision. ArtifactExists is evidence for that decision, not an automatic conclusion: some mutations target an artifact that existed before the event was prepared.

type ReplayResult ¶ added in v0.34.0

type ReplayResult struct {
	Delivered int
	Failed    []SubscriberFailure
	Pending   int
	Prepared  []PreparedRecord
}

type Subscriber ¶

type Subscriber interface {
	// Deliver is invoked by the dispatcher with a validated envelope. It
	// returns nil on successful delivery and a non-nil error on any failure
	// (timeout, exec exit non-zero, filesystem error, etc.).
	Deliver(ctx context.Context, e Event) error

	// Name returns a stable identifier used in stderr failure logs. The
	// dispatcher does not interpret the string.
	Name() string
}

Subscriber is the extension point for receiving dispatched events. Any type implementing Subscriber may be registered via the events: config block in specscore.yaml. Delivery is at-least-once: a process can crash after the subscriber succeeds but before its durable acknowledgement is written. Implementations MUST therefore be idempotent by Event.UUID across processes and invocations, not merely safe to call repeatedly within one invocation.

func LoadSubscribers(projectRoot string) ([]Subscriber, error)

type SubscriberFailure ¶

type SubscriberFailure struct {
	Name string
	Err  error
}

SubscriberFailure pairs a failing subscriber's Name() with the error its Deliver returned. The dispatcher emits one stderr line per entry; the verb layer additionally inspects the slice when mapping to exit codes.

type ValidationError ¶

type ValidationError struct {
	// Field is the dotted JSON path of the offending field (e.g. "name",
	// "actor.kind", "artifact.type").
	Field string
	// Rule is a human-readable description of the rule that was violated;
	// regex rules embed the pattern verbatim so callers can grep for it.
	Rule string
	// Value is the offending value rendered for stderr. Empty when the
	// rule is "must not be empty" and the field is a string.
	Value string
}

ValidationError is the deterministic error returned by Validate. The dispatcher prints its Error() string verbatim to stderr; the envelope-validation ACs assert that the message names both the offending Field and the Rule violated, so both elements MUST appear in the formatted string.

func (e *ValidationError) Error() string