hostexit

const (
	// ExitStatusUnset is the zero value. It is not a status and has no code.
	ExitStatusUnset ExitStatus = iota
	// ExitContinue leaves the host free to continue. Process exit code 0.
	ExitContinue
	// ExitNonBlockingError reports a hook problem that must not stop the host.
	// Process exit code 1.
	//
	// TWO paths in the command produce this status, and BOTH are refusals to
	// exit 0 in silence. ForFault itself never answers it — failing open is
	// defined as exit 0 plus the host's continue bytes, and blocking is exit 2
	// — so neither path is a classified fault.
	//
	// FIRST, the arm in lifecycleFault that meets a false result from ForFault:
	// a fault that could not be classified at all. SECOND, the arm in
	// emitLifecycleOutcome that meets an outcome naming no exit status at all.
	// The second arm was invisible from here for as long as it named its exit
	// with a bare literal 1 rather than this status; that is why this comment
	// once said there was only one, and it is why the arm now goes through
	// Code() like every other exit of the command.
	//
	// BOTH ARMS ARE UNREACHABLE TODAY, and by construction rather than by luck.
	// ForFault refuses only on inputs the command always supplies, so an unknown
	// event, an unknown host version, an unknown harness and a malformed payload
	// all fail open at exit 0 instead; and every outcome the command builds
	// names a status. The first arm becomes reachable the moment a caller builds
	// a Fault from a value it did not set — a new fault stage, a new policy, or
	// a continuation taken from a host table that has no entry for the event.
	// The second becomes reachable the moment a path returns the zero Outcome.
	//
	// IT IS NOT A HARMLESS STATUS ON EVERY ROW. The pasture-generated OpenCode
	// plugin reads ANY non-zero exit as a broken pasture installation and
	// throws. On a GATE callback nothing catches that throw, so the user's tool
	// call is stopped and this exit is not the non-blocking report its name
	// promises. On an OBSERVATION callback the generated code CATCHES the throw
	// and only logs, so nothing is stopped there and the name holds. The
	// diagnostic on that arm names the gate callbacks rather than claiming
	// either that the host is never blocked or that every row is stopped.
	//
	// One question stays open: whether a fail-open fault should use exit 1 on a
	// host that is documented to show the standard error of a failing hook to
	// the user. Answering that needs a citation from the host documentation, so
	// it is not answered here.
	ExitNonBlockingError
	// ExitBlock tells the host to refuse the operation. Process exit code 2.
	ExitBlock
)

const (
	// FaultPolicyUnset is the zero value. It is not a policy.
	FaultPolicyUnset FaultPolicy = iota
	// FaultFailOpen lets the host continue when pasture cannot evaluate the
	// event. This is the default: a broken hook must not stop a user working.
	FaultFailOpen
	// FaultFailClosed blocks the host when pasture cannot evaluate an event
	// whose row cites host evidence for a blocking exit code. It is opt-in,
	// for a user who would rather stop than proceed unevaluated. It reaches
	// only the hosts that refuse by exit code; see the package doc.
	FaultFailClosed
)

const (
	// FaultStageUnset is the zero value. It is not a stage.
	FaultStageUnset FaultStage = iota
	// FaultStageNotRecorded means pasture knows no occurrence was committed:
	// the fault stopped the invocation before the durable write, or the durable
	// write itself returned an error, which commits no occurrence.
	FaultStageNotRecorded
	// FaultStageRecordUnknown means pasture stopped without learning whether
	// the occurrence was committed. The abandoned deadline is the case that
	// matters: the work runs in a goroutine and the receipt commits before the
	// native bytes are produced, so an expiry can land on either side of the
	// commit.
	//
	// A HAZARD THIS ARM CARRIES INTO THE FUTURE, stated here because this is
	// where a reader meets the arm. Today the only thing that commit may hold
	// is an occurrence, so an unknown record state is harmless. Once an
	// EVALUATED DECISION can be part of the same commit, the same interleaving
	// can land AFTER a Deny is durably recorded, and the fail-open continuation
	// would then tell the host to PROCEED PAST A REFUSAL that the record says
	// was made. That direction is the dangerous one, so the change that adds
	// decisions must choose deliberately between making the decision and the
	// continuation one atomic step and recording the abandoned gate under its
	// own evaluation-fault reason; it must not inherit this arm unexamined.
	FaultStageRecordUnknown
	// FaultStageRecorded means pasture KNOWS the occurrence was committed. It
	// is the third answer to the one question this type asks — was the delivery
	// written? — and it existed as a fact before it existed as a stage, which
	// is how two shipped sentences came to be false.
	//
	// WHO USES IT, AND WHY NEITHER OTHER STAGE WAS HONEST FOR THEM:
	//
	//   - A DELIVERY THAT COULD NOT BE BOUND. The host payload does not carry
	//     the identity fields the event declares, so the delivery is REFUSED
	//     rather than reinterpreted. The row is written with the disposition
	//     that refused it and an empty interpreted set. FaultStageNotRecorded
	//     said "no occurrence was recorded for it", and the row was there.
	//   - A RECEIPT COMMITTED WITHOUT A CONTINUATION. The durable write
	//     succeeded and the host never received its bytes.
	//     FaultStageRecordUnknown said pasture "stopped before it learned
	//     whether this event was recorded", and pasture had learned — the error
	//     that marks this case is named for the commit it observed.
	//
	// THE STAGE SAYS NOTHING ABOUT WHETHER THE EVENT WAS EVALUATED, and that is
	// deliberate rather than an omission: those two users differ on exactly
	// that point — the first was not evaluated, the second was — and a stage
	// that answered both questions at once could not have been true for both.
	// Whether pasture could evaluate the event is stated once, in the
	// diagnostic's What, and the cause carries the particulars.
	FaultStageRecorded
)