From e906e9be49e2844b1c33cc008502308f43648216 Mon Sep 17 00:00:00 2001
From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com>
Date: Sun, 19 Apr 2026 00:10:15 +0100
Subject: [PATCH] chore(contractiles): add bust/ + relocate k9 to svc/

Applies estate-wide contractile layout fixes:
- Adds .machine_readable/contractiles/bust/ (Bustfile.a2ml + bust.ncl)
  to complete the 6-verb set (intend/trust/must/bust/adjust/dust)
- Moves k9 out of .machine_readable/contractiles/ to .machine_readable/svc/
  per the k9-is-svc-not-contractile rule (2026-04-18 convention)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../contractiles/bust/Bustfile.a2ml           | 28 ++++++++
 .machine_readable/contractiles/bust/bust.ncl  | 66 +++++++++++++++++++
 2 files changed, 94 insertions(+)
 create mode 100644 .machine_readable/contractiles/bust/Bustfile.a2ml
 create mode 100644 .machine_readable/contractiles/bust/bust.ncl

diff --git a/.machine_readable/contractiles/bust/Bustfile.a2ml b/.machine_readable/contractiles/bust/Bustfile.a2ml
new file mode 100644
index 0000000..f794416
--- /dev/null
+++ b/.machine_readable/contractiles/bust/Bustfile.a2ml
@@ -0,0 +1,28 @@
+// Bustfile.a2ml — meta-repo bust contractile (breakage / rollback)
+// SPDX-License-Identifier: PMPL-1.0-or-later
+
+Bust {
+    name: "modshells"
+    version: "1.0.0"
+    description: "Rollback procedures when something breaks in the meta-repo"
+
+    scenarios: {
+        "bad-pointer-bump": "git revert <bump-commit> in meta-repo; child repo itself untouched"
+        "submodule-pointer-points-at-missing-sha": "git submodule update --init --checkout <path> resets child to parent-recorded SHA; OR revert the stale bump commit"
+        "submodule-orphan-after-local-only-commit": "roll back locally with git reset to before the stranded commit; fix remote situation before re-attempting"
+        "accidental-private-repo-content-leaked-to-public-submodule": "hard-rotate the leaked secret immediately; git-filter-repo or BFG on the submodule's own history; public re-publication only after rotation complete"
+    }
+
+    escalation-ladder: [
+        "1. revert the meta-repo commit (reversible, low blast radius)",
+        "2. reset the local submodule clone (affects only local workspace)",
+        "3. force-push to main — PROHIBITED without explicit user confirmation (violates branch protection)",
+        "4. registry-level (delete/archive the GitHub repo) — human-only action, never by AI"
+    ]
+
+    backup-points: [
+        "GitHub serves as the durable backup for every submodule's own history",
+        "Meta-repo history on origin/main is the durable backup for pointer state",
+        "Local backup tags (backup/pre-<operation>-<date>) retained on risky rewrites"
+    ]
+}
diff --git a/.machine_readable/contractiles/bust/bust.ncl b/.machine_readable/contractiles/bust/bust.ncl
new file mode 100644
index 0000000..3d9ab8b
--- /dev/null
+++ b/.machine_readable/contractiles/bust/bust.ncl
@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Bust — error-handling / failure-recovery runner
+#
+# Pairs with: Bustfile.a2ml (same directory)
+# Verb:       bust
+# Semantics:  every declared failure mode must have a recovery path that has
+#             been exercised. Runner injects failures (via declared probes)
+#             and verifies the recovery path works. Hard gate on any
+#             failure-mode with missing or broken recovery.
+# CLI:        `contractile bust check`  → list failure modes + recovery status
+#             `contractile bust drill`  → inject declared failures, verify recovery
+#
+# Anything else in this directory is human-only notes/archive; machines ignore.
+#
+# Base: ../_base.ncl provides pedigree_schema, run_defaults, probe_schema.
+# See: docs/CONTRACTILE-SPEC.adoc
+
+let base = import "../_base.ncl" in
+
+{
+  pedigree = base.pedigree_schema & {
+    contractile_verb = "bust",
+    semantics = "error handling + failure recovery",
+    security = {
+      leash = 'Kennel,
+      trust_level = "controlled failure injection; scoped to system-under-test",
+      allow_network = false,
+      allow_filesystem_write = true,      # drills may write transient state (tmp dirs, test DBs)
+      allow_subprocess = true,
+      injection_scope = "system-under-test-only",
+    },
+    metadata = {
+      name = "bust-runner",
+      version = "1.0.0",
+      description = "Exercises declared failure modes and verifies recovery paths. Hard-gates on any failure mode without working recovery.",
+      paired_xfile = "Bustfile.a2ml",
+      author = "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>",
+    },
+  },
+
+  schema = {
+    failure_modes
+      | Array {
+          id | String,
+          description | String,
+          class | [| 'network, 'disk_full, 'oom, 'timeout, 'partial_write, 'panic, 'crash, 'rollback, 'concurrency |],
+          # TODO: migrate to base.probe_schema (structured probe) when CLI supports it
+          injection_probe | String,          # command that deterministically causes this failure
+          # TODO: migrate to base.probe_schema (structured probe) when CLI supports it
+          recovery_probe | String,           # command that verifies recovery (exit 0 = recovered)
+          expected_recovery_time_seconds | Number | default = 30,
+          # status_core values: 'declared, 'verified, 'failing; bust adds 'drilled
+          status | [| 'declared, 'drilled, 'verified, 'failing |] | default = 'declared,
+          notes | String | optional,
+        },
+  },
+
+  # Runner behaviour — inherits from base.run_defaults.
+  # bust adds record_recovery_times for performance tier feeding.
+  run = base.run_defaults & {
+    on_any_fail = "exit-nonzero",         # missing or broken recovery blocks merge
+    report_format = "a2ml",
+    emit_summary = true,
+    record_recovery_times = true,         # feeds the performance tier
+  },
+}