Building 70 Projects ranging from beginner to advanced so anyone can β learn from, build upon, use as a reference, or even copy directly. Owned by my cybersecurity company π
Go aicertificationcloud-engineeringcybercybersecuritycybersecurity-analystcybersecurity-certificationcybersecurity-certificationscybersecurity-educationcybersecurity-jobscybersecurity-portfoliocybersecurity-projectscybersecurity-toolsgrchackinglearningpentestingproject-repositoryprojetcspython
chore(khaos): comments that state the constraint, not how it was found
CarterPerez-devac2310f83987
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos/main.go b/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos/main.goindex fe04e0ce..9f2f4ace 100644--- a/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos/main.go+++ b/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos/main.go@@ -52,16 +52,12 @@ func main() {os.Exit(guarded(execute))}-// guarded is the boundary that makes CodeInternal reachable. The taxonomy-// published code 70 as "a recovered panic" and nothing in khaos recovered-// one, so a bug crashed with a Go stack trace and whatever exit status the-// runtime chose -- indistinguishable to CI from a tool that could not parse-// its flags.+// guarded is the boundary that makes CodeInternal reachable, so a bug exits+// 70 rather than with whatever status the runtime chose.//// Recovering HERE and nowhere deeper is deliberate: the panic still unwinds// every frame below, so every deferred revert, lease release and lock-// handoff runs exactly as it does on any other error path. khaos only-// decides what to say about it.+// handoff runs as it does on any other error path.func guarded(run func() int) (code int) {defer func() {recovered := recover()@@ -143,10 +139,9 @@ func noColorRequested(args []string) bool {// verdict outcomes is decided once where the run ends rather than re-derived// by a chain here that grows with every epistemic value. The checks below it// are for errors that never reached a verdict at all.-// fail decides what the operator READS. What the process RETURNS is decided by-// cli.ExitCode, which is the same classification the run record carries, so-// the status and the artifact cannot disagree. This function used to carry its-// own table, and a rollback failure exited 6 while run.json said 1.+// fail decides what the operator READS. What the process RETURNS is decided+// by cli.ExitCode, the same classification the run record carries, so the+// status and the artifact cannot disagree.func fail(err error) int {code := cli.ExitCode(err)diff --git a/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos/main_test.go b/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos/main_test.goindex d19c13fc..42f519c5 100644--- a/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos/main_test.go+++ b/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos/main_test.go@@ -206,16 +206,9 @@ func TestRollbackFailureOutranksEveryOtherExitCode(t *testing.T) {}}-// Exit code 70 was published in the taxonomy as "a recovered panic" and-// nothing in khaos recovered one: `CodeInternal` appeared in its own-// declaration and in a numeric assertion, and in no production path at all.-// A bug therefore crashed with a Go stack trace and whatever status the-// runtime chose, which CI cannot tell from a tool that could not parse its-// flags.-//-// The deferred cleanup below is the half that matters more than the code: the-// panic still unwinds every frame, so a fault khaos had applied is still-// reverted on the way out.+// A bug has to exit 70 rather than with whatever status the runtime chose.+// The deferred cleanup matters more than the code: the panic still unwinds+// every frame, so an applied fault is still reverted on the way out.func TestAPanicBecomesTheInternalCodeWithCleanupIntact(t *testing.T) {reverted := falsediff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/emit.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/emit.goindex 7517540d..da9510b4 100644--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/emit.go+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/emit.go@@ -126,10 +126,9 @@ func emitRecord(return outcome}- // A verdict khaos reached outranks a file it could not write. The warning- // goes to the DIAGNOSTIC stream: writing it to out appended prose to the- // JSON document under --output json, which breaks that contract on the one- // path where CI needs machine-readable evidence.+ // A verdict khaos reached outranks a file it could not write, and the+ // warning goes to the DIAGNOSTIC stream so --output json stays one+ // decodable document.if outcome != nil {fmt.Fprintf(emit.diagnostic(), warnRecordWrite, writeErr)@@ -170,18 +169,15 @@ func writeProjections(rec record.Record, into Projections) error {// exitDetail reads the code and the outcome name back off a finished run, so// the record can carry what khaos is about to return to the shell.//-// It is the SAME classification the process boundary uses, because these were-// two lists: this one mapped anything without a typed Exit to usage code 1-// while the boundary recognised the rollback and cancellation sentinels on its-// own, so a real rollback failure wrote exit.code 1 into run.json and exited 6.+// It is the SAME classification the process boundary uses, so the status and+// the artifact cannot disagree.func exitDetail(outcome error) (int, string) {if outcome == nil {return CodeOK, ""}- // Matched on the sentinels BEFORE any carried code, because these are the- // outcomes nothing may suppress and they must not depend on some other- // layer having wrapped them correctly.+ // Matched on the sentinels BEFORE any carried code: nothing may suppress+ // these, so they cannot depend on another layer having wrapped them.if errors.Is(outcome, run.ErrRevertFailed) ||errors.Is(outcome, ErrNotRecovered) {return CodeRollback, string(outcomeRollback)diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/emit_test.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/emit_test.goindex 85dfdf8e..b4bee752 100644--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/emit_test.go+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/emit_test.go@@ -414,12 +414,9 @@ func TestAProjectionThatCannotBeWrittenIsNotSilent(t *testing.T) {}// pflag advertises a flag's value by the FIRST backquoted word in its usage-// string, so that placeholder is prose maintained like a signature. Three of-// these were wrong on arrival: `--record` takes a DIRECTORY and advertised-// `run.json`, so an operator reads the help and passes a filename; `--junit`-// advertised `skipped`, which is a JUnit element and not a value at all; and-// `--metrics-out` advertised nothing and fell back to `string` beside two-// neighbours that did not.+// string, so the placeholder is prose maintained like a signature. --record+// takes a DIRECTORY, and advertising a filename sends an operator to the+// wrong shape.func TestTheReportingFlagsAdvertiseWhatTheyTake(t *testing.T) {definition := outage(t)sub := experimentCmdFor(t, newRunCmd(), definition)@@ -448,12 +445,8 @@ func TestTheReportingFlagsAdvertiseWhatTheyTake(t *testing.T) {}// --output json promises stdout carries the record and nothing else, so-// `khaos run x --output json | jq .verdict` works. A write failure broke that-// promise on exactly the path CI needs most: the JSON went to `out`, and so-// did the prose warning about the artifact khaos could not write, so a defect-// plus an invalid --record destination produced a JSON document followed by a-// sentence. Diagnostics belong on stderr; the machine format gets the stream-// it was asked for.+// `khaos run x --output json | jq .verdict` works. A defect plus an+// unwritable --record must not append prose to that document.func TestAnArtifactFailureNeverContaminatesTheJSONStream(t *testing.T) {result, definition := emitted(t)diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/exit_test.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/exit_test.goindex 309c42b0..dc012263 100644--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/exit_test.go+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/exit_test.go@@ -447,15 +447,9 @@ func TestTheExitCodesAreTheirPublishedNumbers(t *testing.T) {}// The code in the record and the code the process returns are the SAME-// contract, and they were computed by two different lists.-//-// exitFor returned an execution error unclassified, exitDetail mapped anything-// without a typed Exit to usage code 1, and the process boundary separately-// recognised the rollback and cancellation sentinels. So a real rollback-// failure wrote `exit.code: 1` into run.json while the process exited 6 -- the-// artifact disagreeing with the status about the one outcome no --fail-on value-// may suppress. The unit census never caught it because it called exitFor with-// a nil execution error.+// contract. Computed by two lists, they disagreed: a rollback failure wrote+// exit.code 1 into run.json while the process exited 6, about the one+// outcome no --fail-on value may suppress.func TestTheRecordedCodeIsTheCodeTheProcessReturns(t *testing.T) {for name, tc := range map[string]struct {err error@@ -522,10 +516,9 @@ func TestTheRecordedCodeIsTheCodeTheProcessReturns(t *testing.T) {}}-// `reap --interval 0` reached time.NewTicker(0), which panics, and it got-// there AFTER the workspace was opened and its lock taken -- so the operator-// paid for a refusal that arrived as a Go stack trace. Validated before-// anything is opened.+// A non-positive reap interval reaches time.NewTicker, which panics, and it+// got there after the workspace lock was taken. Refused before anything+// opens.func TestANonPositiveReapIntervalIsRefusedBeforeAnythingOpens(t *testing.T) {for _, interval := range []time.Duration{0,diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/experiment.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/experiment.goindex fe133e63..7bb65e42 100644--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/experiment.go+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/experiment.go@@ -652,11 +652,10 @@ type Output struct {Record stringProjections Projections- // Diagnostic is where a failure that is NOT the verdict goes. It is- // separate from the report stream because a warning on stdout turns the- // --output json contract into a JSON document followed by a sentence, and- // it is separate from the report because under json the report is- // discarded while this must still be seen.+ // Diagnostic is where a failure that is NOT the verdict goes: separate+ // from stdout so --output json stays one decodable document, and+ // separate from the report because json discards the report while this+ // still has to be seen.Diagnostic io.Writer}diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/reclaim.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/reclaim.goindex 5a91887e..dadfde4f 100644--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/reclaim.go+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/reclaim.go@@ -58,9 +58,8 @@ every other fault on the machine.`errIntervalUsage = "%w: %s")-// A non-positive interval reached time.NewTicker, which panics, AFTER the-// workspace had been opened and its lock taken. Refused by name instead, and-// before anything is opened.+// A non-positive interval reaches time.NewTicker, which panics. Refused by+// name instead, before the workspace is opened and its lock taken.var ErrIntervalNotPositive = errors.New("the reap interval has to be longer than zero, or there is no tick to check the journal on",)@@ -135,8 +134,8 @@ func runReclaim(ctx context.Context, out io.Writer, expiredOnly bool) error {}func runReap(ctx context.Context, out io.Writer, interval time.Duration) error {- // Before the workspace, because a refusal that has already taken the lock- // is a refusal that cost the operator something.+ // Before the workspace: a refusal that already took the lock cost the+ // operator something.if interval <= 0 {return fmt.Errorf(errIntervalUsage, ErrIntervalNotPositive, interval)}diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/dockerx/recreate.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/dockerx/recreate.goindex 495ea0e9..09028ac2 100644--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/dockerx/recreate.go+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/dockerx/recreate.go@@ -140,12 +140,9 @@ func (c *Client) Capture(}// Identify resolves a name to the IMMUTABLE container id behind it, or-// ErrContainerGone when nothing answers to that name.-//-// A name is a label the daemon lets any container hold, and this tier hands-// one container's name to another on purpose. Anything destructive therefore-// has to ask which container a name currently means before acting on it, and-// then act on the id rather than on the name it came from.+// ErrContainerGone when nothing answers to it. A name is a label the daemon+// lets any container hold, and the environment tier hands one container's+// name to another on purpose, so anything destructive resolves first.func (c *Client) Identify(ctx context.Context, ref string) (string, error) {result, err := c.api.ContainerInspect(ctx,diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/forgery_verdict_test.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/forgery_verdict_test.goindex 782dd8bb..e33325c0 100644--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/forgery_verdict_test.go+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/forgery_verdict_test.go@@ -617,17 +617,10 @@ func TestARequiredForgedStreamWithNoDecisionsCannotReportHeld(t *testing.T) {}}-// The guard that requires this experiment's own stream to have been MEASURED-// counted transport observations as decisions.-//-// `Countable()` excludes only khaos's own failures, so a timeout, an-// unreachable target and a throttle all satisfied a check whose own name and-// comment say "the target actually decided about it". Thirty forged probes that-// timed out therefore cleared the floor, and a healthy valid/invalid pair then-// produced a CONCLUSIVE hold about a credential the target was never observed-// to judge. `Answered()` is the discriminator -- the same one that split-// `Unavailable` from `Unreachable` -- and this was the fourth site reading the-// wrong one.+// The guard requiring this experiment's own stream to have been MEASURED+// must count DECISIONS, not transport: Countable() excludes only khaos's own+// failures, so a stream of timeouts would clear the floor and produce a hold+// about a credential the target was never observed to judge.func TestATimedOutForgedStreamIsNotEvidenceTheTargetDecided(t *testing.T) {for _, disposition := range []probe.Disposition{probe.Unreachable,diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/verdict.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/verdict.goindex 258a2cfc..ddac4b58 100644--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/verdict.go+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/verdict.go@@ -776,10 +776,8 @@ func requiredStreamThin(observation Observation) (string, bool) {return "", false}- // Answered(), not Countable(): a timeout or an unreachable target is a- // transport observation and not a decision about the credential, and- // Countable() excludes only khaos's own failures. This is the same- // discriminator that splits Unavailable from Unreachable.+ // Answered(), not Countable(): a timeout is a transport observation and+ // not a decision about the credential.if decided := observation.Fault.Forged.Answered(); decided < MinimumPaired {return sprintf(reasonThinForged, decided, MinimumPaired), true}@@ -1169,17 +1167,12 @@ func unanswered(// transition declared on one lucky sample is how a flaky recovery reads as a// clean one. An empty window is UNOBSERVED, never recovered.//-// The whole window is read, because this used to return the moment it found a-// qualifying run: two healthy pairs followed by twenty broken ones was-// RECOVERED, and a run whose last observed state was broken could exit 0.-//-// Recovery therefore needs two things -- it has to have been ESTABLISHED, and-// it must not have collapsed for a sustained stretch afterwards. The same run-// length governs both, because the reason a single healthy pair cannot declare-// recovery is the reason a single failed one cannot withdraw it. A window of-// fifteen pairs whose last sample happens to be a blip is still a recovery;-// this verdict maps to the one exit code no --fail-on value can suppress, so-// the cost of declaring it on noise lands on every later job.+// Recovery needs two things: it has to have been ESTABLISHED, and it must+// not have collapsed for a sustained stretch afterwards. The same run length+// governs both, because the reason a single healthy pair cannot declare+// recovery is the reason a single failed one cannot withdraw it -- and this+// verdict maps to the one exit code no --fail-on value can suppress, so+// declaring it on one noisy sample costs every later job on the runner.func recoveryOf(recovery probe.Window, closed []probe.Disposition) Recovery {if recovery.Paired() == 0 {return Unobserveddiff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/verdict_test.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/verdict_test.goindex a6f88c3c..ade4d37b 100644--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/verdict_test.go+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/verdict_test.go@@ -547,15 +547,8 @@ func TestADeclaredClosureNeverHidesARefusal(t *testing.T) {}}-// recoveryOf returned the moment it found its run of consecutive healthy pairs-// and never looked at the rest of the window, so a recovery that collapsed-// after two good samples was reported RECOVERED. A run whose last observed-// state was broken could then exit 0.-//-// The criterion is now the END of the window rather than the first qualifying-// run: recovery has to still be established when khaos stops looking. A late-// recovery still counts, because a window that ends with a full healthy run-// ends healthy however it started.+// Recovery is judged over the WHOLE window: a run that collapses after two+// good pairs is not recovered, and a late recovery still counts.func TestRecoveryIsJudgedAtTheEndOfTheWindowNotTheFirstGoodRun(t *testing.T) {healthy := func(n int) []probe.Disposition {out := make([]probe.Disposition, n)@@ -613,10 +606,8 @@ func TestRecoveryIsJudgedAtTheEndOfTheWindowNotTheFirstGoodRun(t *testing.T) {},want: Degraded,},- // The brittleness guard. A single trailing blip in a long healthy- // window must NOT withdraw a recovery: this verdict maps to the one- // exit code no --fail-on value can suppress, and declaring it on one- // unlucky last sample makes every later job on that runner suspect.+ // A single trailing blip must NOT withdraw a recovery: this verdict+ // maps to the one exit code no --fail-on value can suppress."one trailing blip after a long healthy run": {valid: append(healthy(12), probe.Unreachable),want: Recovered,diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/inject/envfault.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/inject/envfault.goindex 3c74a1c9..98557856 100644--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/inject/envfault.go+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/inject/envfault.go@@ -340,10 +340,7 @@ func (m envMutator) Revert(original := strings.TrimSuffix(plan.Held, dockerx.HeldSuffix)- // A cold start finds the replacement by NAME, because the original's name- // is what it took and the id was never journaled until it existed. That- // name is the ORIGINAL's, so it has to be resolved before anything- // destructive happens to it -- see removeReplacement.+ // A cold start has only the NAME, and that name is the original's.replaced := plan.ReplacedIDif replaced == "" {replaced = original@@ -353,10 +350,8 @@ func (m envMutator) Revert(failures = append(failures, err)}- // Already restored: the held name is gone and the original's name is the- // original. A revert that completed and failed only to append REVERTED is- // replayed from the journal, and replay must be a no-op rather than a- // second attempt at a state that already holds.+ // A revert that completed and failed only to append REVERTED is replayed,+ // and replay has to be a no-op rather than a second attempt.if restored, err := m.alreadyRestored(ctx,env,@@ -418,18 +413,10 @@ func ValidEnvKind(kind EnvKind) error {func (envMutator) Prefix() string { return KindEnvPrefix }// removeReplacement deletes the container khaos created, and NOTHING else.-//-// The name it is given is the original's own name whenever ReplacedID was-// never journaled, which is every cold start: ReplacedID is written to the-// in-memory plan after Recreate and the journal payload is never updated. So-// a Remove on that name took the operator's container -- with its anonymous-// volume and every log line -- in two reachable states: khaos dying between-// the PENDING record and the rename, and a replay after a revert that already-// succeeded. OriginalID was in the payload the whole time.-//-// The id is resolved first and the removal is addressed to the ID, not the-// name, because the name can move between the two calls and this tier moves-// names on purpose.+// On a cold start the only handle is a NAME, and that name is the original's+// own, so the id behind it decides: it is resolved first, compared against+// OriginalID, and the removal is addressed to the id rather than the name,+// which can move between the two calls.func (m envMutator) removeReplacement(ctx context.Context,env Env,@@ -444,8 +431,6 @@ func (m envMutator) removeReplacement(case err != nil:return errcase id == plan.OriginalID:- // That name is the ORIGINAL. Nothing to remove, and removing it is- // the one thing this tier must never do.return nil}@@ -458,8 +443,7 @@ func (m envMutator) removeReplacement(}// alreadyRestored reports that the original is back under its own name, by-// IDENTITY rather than by the name being taken: a replacement still holding-// that name would otherwise read as a completed revert.+// IDENTITY: a replacement still holding that name reads the same otherwise.func (m envMutator) alreadyRestored(ctx context.Context,env Env,@@ -471,8 +455,6 @@ func (m envMutator) alreadyRestored(}if _, err := env.Docker.Identify(ctx, plan.Held); err == nil {- // The original is still aside under its held name, so the revert has- // work to do.return false, nil} else if !errors.Is(err, dockerx.ErrContainerGone) {return false, errdiff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/inject/envfault_recovery_test.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/inject/envfault_recovery_test.goindex b26af887..83a1667c 100644--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/inject/envfault_recovery_test.go+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/inject/envfault_recovery_test.go@@ -67,20 +67,10 @@ func alive(name string) bool {// THE one outcome this tier must never produce: khaos destroying the// operator's own container.//-// The revert removed the replacement by NAME, derived as Held minus the held-// suffix -- which is the ORIGINAL's name. On a cold start ReplacedID is empty-// because it is only ever written to the in-memory plan, never to the-// journal, so that name is all the revert had. It is the original's name-// whenever khaos died in either of two windows:-//-// - after the journal recorded PENDING and before the rename, so the-// original is still sitting under its own name, or-// - after a revert already succeeded and only the final journal append-// failed, so the restored original is under its own name again.-//-// In both, a Remove(Force) took the operator's container, its anonymous-// volume and every log line with it. OriginalID was in the payload the whole-// time and the revert never read it.+// On a cold start the revert has only a NAME to find the replacement by, and+// that name is the original's. It resolves to the original in two windows:+// khaos dying after the PENDING record and before the rename, and a replay+// after a revert that already succeeded.func TestARevertNeverRemovesTheOriginalContainer(t *testing.T) {client := dockerOrSkip(t)defer func() { _ = client.Close() }()@@ -141,11 +131,9 @@ func TestARevertNeverRemovesTheOriginalContainer(t *testing.T) {}}-// The NEGATIVE CONTROL on the guard above. A removeReplacement that simply-// never removed anything would satisfy every assertion in that test, so this-// one drives the state the fault actually produces -- the original renamed-// aside, a replacement holding its name -- and requires the revert to remove-// the replacement and put the original back.+// The NEGATIVE CONTROL: a removeReplacement that never removed anything+// would satisfy the test above, so this drives the state the fault really+// produces and requires the replacement to go and the original to come back.func TestARevertStillRemovesAGenuineReplacement(t *testing.T) {client := dockerOrSkip(t)defer func() { _ = client.Close() }()@@ -154,8 +142,8 @@ func TestARevertStillRemovesAGenuineReplacement(t *testing.T) {originalID := seedOriginal(t, fixtureName)- // The fault's own sequence: the original goes aside under the held name,- // and a DIFFERENT container takes the name it vacated.+ // The fault's own sequence: original aside, a different container on the+ // name it vacated.if err := exec.Command("docker", "rename", fixtureName, held).Run(); err != nil {t.Skipf("could not rename the fixture aside: %v", err)@@ -174,9 +162,8 @@ func TestARevertStillRemovesAGenuineReplacement(t *testing.T) {Variable: "A_SECRET",Held: held,OriginalID: originalID,- // Deliberately empty: this is the cold-start shape, where the revert- // has only the name to go on. That is the dangerous path, so it is- // the one the control exercises.+ // ReplacedID deliberately empty: the cold-start shape, which is the+ // dangerous path.})if err != nil {t.Fatalf("marshal: %v", err)diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/record/record.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/record/record.goindex fceb86d1..93794a00 100644--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/record/record.go+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/record/record.go@@ -197,15 +197,9 @@ type Phase struct {}// Phases is the ONE enumeration of the measured windows, in the order the-// engine measures them. The aggregate serializer and the raw-event serializer-// each used to carry their own list and each listed four of the five: `shift`,-// the second fault window the authorization tier needs and the verdict reads-// at three sites, was in neither. A defect established from it was written to-// a record that did not contain the observations establishing it, with an-// events hash and count that were internally consistent about the wrong set.-//-// Both serializers read this, so a phase added to the engine cannot go missing-// from one of them.+// engine measures them. Both serializers read it, so a phase added to the+// engine cannot go missing from one of them and leave a verdict resting on+// observations the record does not carry.func Phases(observation experiment.Observation) []Phase {return []Phase{{"baseline", observation.Baseline},diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/record/record_test.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/record/record_test.goindex 97c4c2c1..d0b91ea4 100644--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/record/record_test.go+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/record/record_test.go@@ -64,11 +64,9 @@ func finished() experiment.Result {Baseline: window(0, probe.Rejected),Fault: window(10*time.Second, probe.Accepted),- // Shift and Resumed are the two windows this fixture used to- // claim it carried and did not. Both are real measured phases --- // shift is the second fault window the authorization tier needs,- // and resumed is what the idleness discriminator reads -- and- // leaving them empty is why a serializer that dropped one passed.+ // Shift is the authorization tier's second fault window and+ // Resumed is what the idleness discriminator reads. A fixture+ // missing either lets a serializer drop it unnoticed.Shift: window(15*time.Second, probe.Accepted),Shifted: true,Resumed: window(18*time.Second, probe.Rejected),@@ -225,9 +223,8 @@ func TestEveryObservationReachesTheEventsFile(t *testing.T) {// two requests. Counting pairs here would have asserted half the// observations reached the file and called that complete.//- // Summed over Phases rather than over a list written here, because a- // hardcoded list of three windows is what let the shift window go- // unnoticed in both serializers.+ // Summed over Phases rather than a list written here, so a new phase+ // cannot go uncounted.want := 0for _, phase := range Phases(result.Observation) {want += phase.Window.Requests()@@ -531,13 +528,9 @@ var errNoInode = errors.New("this platform does not expose an inode, so the rename cannot be distinguished from a truncation here",)-// The record is canonical and every other output is a projection of it, so a-// window the VERDICT reads must survive serialization. The shift window did-// not: both the aggregate and the raw-event serializers enumerated their-// phases separately and both listed four of the five, so a defect established-// from the second fault window was saved without the observations that-// established it -- with an events hash and count that were internally-// consistent about the wrong set.+// Every window the VERDICT reads has to survive serialization, or a defect+// is saved without the observations that established it -- with an events+// hash and count internally consistent about the wrong set.func TestEveryMeasuredPhaseSurvivesTheRecord(t *testing.T) {result := finished()diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/secretfile/secretfile.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/secretfile/secretfile.goindex 026ddf72..8d2f53c9 100644--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/secretfile/secretfile.go+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/secretfile/secretfile.go@@ -205,8 +205,7 @@ func (m Mutation) Apply() error {//// The backup is PUBLISHED atomically, so its existence means it is complete.// Restore cannot tell a truncated backup from a genuinely short secret by-// looking at it, and a 5-byte secret is a legitimate secret, so the guarantee-// has to be structural rather than validated.+// looking at it, so the guarantee is structural rather than validated.func (m Mutation) hold(info os.FileInfo) error {if err := publishCopy(m.Path, m.Aside, info.Mode()); err != nil {return err@@ -269,10 +268,9 @@ func (m Mutation) Restore() error {return os.Remove(m.Aside)}-// publishCopy writes the copy to a temporary file in the destination's own-// directory, flushes it, and renames it into place. A failed copy leaves-// NOTHING at the destination, which is what lets a later Restore treat the-// backup's existence as proof that the whole original is in it.+// publishCopy writes to a temporary file in the destination's own directory,+// flushes it, and renames it into place, so a failed copy leaves NOTHING a+// later Restore could mistake for a complete original.//// Same directory because rename is only atomic within a filesystem, and the// flush before it because a rename that beats the data to disk publishes a@@ -332,11 +330,9 @@ func publishCopy(from, to string, mode os.FileMode) error {return nil}-// copyInto overwrites the destination IN PLACE, keeping its inode. The secret-// is restored this way rather than by rename because the whole reason this-// tier runs in a helper container is that unlink-and-recreate is invisible to-// a target holding the file open, and a restore that swapped the inode would-// leave that target reading the fault forever.+// copyInto overwrites the destination IN PLACE, keeping its inode. A rename+// here would swap the inode, and a target holding the file open would read+// the fault forever.func copyInto(from, to string, mode os.FileMode) error {//nolint:gosec // the path is the fault's subject, guarded by the noncesource, err := os.Open(from)diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/secretfile/secretfile_test.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/secretfile/secretfile_test.goindex d3618268..20496549 100644--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/secretfile/secretfile_test.go+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/secretfile/secretfile_test.go@@ -347,18 +347,9 @@ func TestVerifyRefusesAMalformedCredential(t *testing.T) {// The one outcome this package must never produce: khaos destroying the secret// it was asked to preserve.//-// The backup used to be written at its FINAL path, so a copy that failed-// partway left a short file where a complete original was expected, and a read-// error left a zero-byte one. Restore read existence as proof of a complete-// original, opened the untouched secret with O_TRUNC, and copied the stub over-// it. A short write or a full filesystem was enough, and truncating the-// original could itself free the space that let the destructive restore finish-// and report success.-//// Restore cannot tell a truncated backup from a genuinely short secret by-// looking at it -- a 5-byte secret is a legitimate secret -- so the fix is-// structural: the backup is published atomically, and a failed hold leaves-// nothing behind for Restore to trust.+// looking at it, so the guarantee is structural: the backup is published+// atomically, and a failed hold leaves nothing behind to trust.func TestAFailedHoldLeavesTheOriginalIntactAndUnrestorable(t *testing.T) {path, aside := seeded(t)diff --git a/PROJECTS/intermediate/chaos-engineering-tool/scripts/report.sh b/PROJECTS/intermediate/chaos-engineering-tool/scripts/report.shindex 87362b58..7d4c9067 100755--- a/PROJECTS/intermediate/chaos-engineering-tool/scripts/report.sh+++ b/PROJECTS/intermediate/chaos-engineering-tool/scripts/report.sh@@ -303,22 +303,12 @@ echo "== the codes this gate cannot reach, named rather than implied =="# 9 UNSUPPORTED driven by scripts/dns.sh and scripts/tls.sh, against the# targets whose question genuinely does not apply.# 70 INTERNAL a recovered panic, recovered at the process boundary in-# cmd/khaos. This comment used to say there was "nothing-# honest to assert" about it, which was itself the dishonest-# part: no production path returned the code at all, and no-# recover() existed anywhere, so the gate described a-# mechanism khaos did not have. It is driven by a unit test-# that panics through the real boundary and asserts both the-# code and that deferred reverts still ran.+# cmd/khaos and driven by a unit test that panics through+# it, asserting the code AND that deferred reverts ran.#-# A CENSUS rather than a comment. The paragraph above was an unconditional-# `pass`, which is documentation wearing an assertion's clothes: it could not-# fail, so it could not notice a thirteenth code arriving with nothing-# covering it. This counts the taxonomy in the source and holds it to the-# number this gate and the unit census between them account for.-# [[:space:]] rather than \t: grep -E treats a backslash-t as a literal-# `t`, so the tab form matched nothing and this census reported 0 under-# bash while appearing to work when the same line was pasted into zsh.+# A CENSUS rather than a comment, so a thirteenth code cannot arrive with+# nothing covering it. [[:space:]] rather than \t, which grep -E reads as a+# literal `t`.declared="$(grep -cE '^[[:space:]]+Code[A-Za-z]+ += ' internal/cli/exit.go || true)"if [[ "$declared" == 12 ]]; then@@ -335,10 +325,8 @@ elsefail "the unit census is gone, so the codes this gate cannot drive are unverified"fi-# A code with no producer is a published contract khaos does not honour, which-# is what 70 was: declared, counted by the census above, asserted by number,-# and returned from nowhere. The census cannot see that, because counting-# constants proves declaration and never reachability.+# Counting constants proves DECLARATION and never REACHABILITY, so the code+# needs a producer too.if grep -q 'code = cli.CodeInternal' cmd/khaos/main.go &&grep -q 'func TestAPanicBecomesTheInternalCodeWithCleanupIntact' cmd/khaos/main_test.go; thenpass "the internal code has a producer and a test that panics through it"@@ -346,8 +334,7 @@ elsefail "exit 70 is declared with no production path, so the taxonomy publishes a code khaos never returns"fi-# The refusal that used to be a panic: a non-positive interval reached-# time.NewTicker AFTER the workspace lock was taken.+# A non-positive interval reaches time.NewTicker, after the workspace lock.if ! out="$("$BIN" reap --interval 0 --no-color 2>&1)"; thenif grep -q "longer than zero" <<<"$out"; thenpass "a non-positive reap interval is refused by name instead of panicking"