feat(wake): W5 — synthetic-canary FN-oracle + source-parity reconciler (#909)
Co-authored-by: jason.woltje <jason@diversecanvas.com> Co-committed-by: jason.woltje <jason@diversecanvas.com>
This commit was merged in pull request #909.
This commit is contained in:
568
packages/mosaic/framework/tools/wake/reconcile.sh
Executable file
568
packages/mosaic/framework/tools/wake/reconcile.sh
Executable file
@@ -0,0 +1,568 @@
|
||||
#!/usr/bin/env bash
|
||||
# reconcile.sh — A7 of the wake canon (EPIC #892, W5): the source-parity
|
||||
# reconciler.
|
||||
#
|
||||
# CONTRACT ANCHORS (docs/scratchpads/heartbeat-planning/CONVERGED-DESIGN.md):
|
||||
# §4/G3 Source parity / reconciliation — the GO condition has TWO ordered
|
||||
# parts:
|
||||
# (i) a source-coverage PARITY INVENTORY FIRST: a lane-by-lane
|
||||
# DECLARED inventory of every operational source the lane
|
||||
# depends on, so an OMITTED source cannot make the §4 vector pass
|
||||
# VACUOUSLY. An incomplete / undeclared inventory FLAGS (it must
|
||||
# NOT silently pass).
|
||||
# (ii) then a periodic full RECONCILE: enumerate declared+configured
|
||||
# source state vs observed_seq/inbox => 0 UNACCOUNTED. Any source
|
||||
# state not reflected in observed_seq/inbox is a gap => FLAG.
|
||||
# §4 vector { source-parity inventory complete AND reconcile = 0 unaccounted }
|
||||
# §7-res5 FN-oracle + reconciliation are a real, NON-OPTIONAL operating cost.
|
||||
# W4 review division: the detector's first-seen-baseline does NOT wake; the
|
||||
# RECONCILER is what enumerates PRE-EXISTING / startup source state into
|
||||
# the durable store (at startup and periodically). Without it, state
|
||||
# that already existed when the detector first saw it (baselined
|
||||
# silently) would never enter the inbox and would be lost.
|
||||
#
|
||||
# SCOPE: calls the PUBLIC APIs of store.sh (cursors/drain/enqueue) only. It does
|
||||
# NOT reimplement or modify the store, ack, digest, signer, or detector. It
|
||||
# OBSERVES current source state through the SAME operator adapter contract the
|
||||
# detector uses (WAKE_DETECTOR_SOURCE_CMD <kind> <id>, def on stdin), with the
|
||||
# SAME fail-loud (G2a) discipline: a source error / ambiguous-empty is never
|
||||
# silently "no state".
|
||||
#
|
||||
# CONTRACT NOTES (flagged, not silently guessed — see PR body):
|
||||
# * observed_seq DUAL-ALLOCATOR HAZARD (fail-closed; #908 tracks the fix).
|
||||
# observed_seq has TWO INDEPENDENT allocators today: the detector's PRIVATE
|
||||
# counter ($STATE_DIR/detector/observed_seq_counter, W4) and — if this
|
||||
# reconciler enumerated — the STORE cursor (observed_seq+offset). Because the
|
||||
# detector's next seq is (private_counter+1), NOT (store_observed_seq+1), the
|
||||
# two are decoupled and SERIALIZING THEM DOES NOT PREVENT COLLISION: after
|
||||
# the reconciler enumerates alpha->seq1, beta->seq2 (store observed_seq=2,
|
||||
# detector private still 0), the detector's next delta allocates private
|
||||
# 0->1 and enqueues seq1 — ALIASING alpha. A consumer acking CONSUMED 1
|
||||
# (trusting §2.4's unique observed_seq) then silently DROPS a distinct
|
||||
# obligation — the exact G3 swallow this reconciler exists to prevent.
|
||||
# THEREFORE, until #908 unifies on a single store-side allocator, the
|
||||
# reconciler FAILS CLOSED: it REFUSES to enumerate (loud, non-zero; the
|
||||
# obligation is FLAGGED, never silently swallowed) whenever a detector is
|
||||
# co-feeding this store, and otherwise requires the operator to assert
|
||||
# reconciler-SOLE-FEEDER mode. OPERATIONAL GUARD: a detector and this
|
||||
# reconciler MUST NOT co-feed one store until #908 lands.
|
||||
# * "accounted" is judged against observed_seq/inbox (§4/G3 wording) PLUS the
|
||||
# reconciler's OWN durable reconciled-state ledger — NOT the detector's
|
||||
# hash-file. Judging by the detector baseline would let a silent first-seen
|
||||
# baseline swallow a pre-existing obligation (the exact hole G3 closes).
|
||||
# * enumeration uses the non-coalescible fail-safe class `actionable` (§2.3)
|
||||
# so two distinct pre-existing obligations can never coalesce into one.
|
||||
#
|
||||
# Operator-agnostic: all state via XDG/env; no operator paths/names/secrets.
|
||||
set -uo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
# shellcheck source=./_wake-common.sh disable=SC1091
|
||||
. "$SCRIPT_DIR/_wake-common.sh"
|
||||
|
||||
STORE_SH="$SCRIPT_DIR/store.sh"
|
||||
MANIFEST="$SCRIPT_DIR/manifest.txt"
|
||||
|
||||
STATE_DIR="$(wake_state_dir)"
|
||||
# Reconciler-local state (its durable reconciled-state ledger) lives in its own
|
||||
# subdir under the store's STATE_DIR so it never collides with store/detector.
|
||||
RECON_DIR="$STATE_DIR/reconciler"
|
||||
# The detector's PRIVATE state dir (W4). Its presence signals a detector is (or
|
||||
# has been) allocating observed_seq into THIS store from an INDEPENDENT private
|
||||
# counter — the co-feeding condition under which reconciler enumeration is
|
||||
# unsafe (see the dual-allocator hazard note above; #908). Read-only coupling:
|
||||
# reconcile.sh never writes or imports W4, it only OBSERVES this path to fail
|
||||
# closed rather than silently alias a seq.
|
||||
DET_STATE="$STATE_DIR/detector"
|
||||
|
||||
_need_jq() {
|
||||
command -v jq >/dev/null 2>&1 || {
|
||||
echo "reconcile.sh: jq is required" >&2
|
||||
exit 3
|
||||
}
|
||||
}
|
||||
|
||||
_hash() {
|
||||
if command -v sha256sum >/dev/null 2>&1; then
|
||||
sha256sum | awk '{print $1}'
|
||||
elif command -v shasum >/dev/null 2>&1; then
|
||||
shasum -a 256 | awk '{print $1}'
|
||||
elif command -v openssl >/dev/null 2>&1; then
|
||||
openssl dgst -sha256 | awk '{print $NF}'
|
||||
else
|
||||
echo "reconcile.sh: no sha256 tool (sha256sum/shasum/openssl) available" >&2
|
||||
exit 3
|
||||
fi
|
||||
}
|
||||
|
||||
usage() {
|
||||
cat >&2 <<'EOF'
|
||||
Usage: reconcile.sh <command> [options]
|
||||
|
||||
Commands:
|
||||
inventory
|
||||
Part (i) — source-coverage PARITY INVENTORY. Prints a lane-by-lane
|
||||
declared inventory and FLAGS any incompleteness that could let the §4
|
||||
vector pass VACUOUSLY:
|
||||
* a declared operational source (repos/board_files/lane_anchors) that
|
||||
NO watch covers (an OMITTED source);
|
||||
* a watch that references a source with no declared definition (dangling);
|
||||
* a lane with zero sources; an empty watch-list;
|
||||
* if a lane declares `required_sources`, any id missing from its sources.
|
||||
Exit 0 IFF the inventory is complete; non-zero (loud) on any flag.
|
||||
|
||||
reconcile [--no-enumerate] [--allow-enumerate]
|
||||
Part (ii) — periodic full reconcile. Enumerates each covered source's
|
||||
CURRENT state and compares it against observed_seq/inbox (+ the
|
||||
reconciler's reconciled-state ledger). Any source state NOT reflected =>
|
||||
UNACCOUNTED => FLAG. Unless --no-enumerate, each unaccounted source is
|
||||
ENUMERATED into the durable store (the startup/pre-existing obligation
|
||||
path). Exit 0 IFF 0 unaccounted were FOUND this pass.
|
||||
|
||||
DUAL-ALLOCATOR SAFETY (fail-closed; #908): enumeration WRITES observed_seq
|
||||
from an allocator INDEPENDENT of the detector's private counter, so it
|
||||
FAILS LOUD (refuses; the obligation is FLAGGED, never swallowed) when it
|
||||
would risk aliasing a seq:
|
||||
* if a detector is co-feeding this store (its private state dir exists)
|
||||
=> refuse, ALWAYS (even with the ack below);
|
||||
* else the operator MUST assert reconciler-SOLE-FEEDER mode via
|
||||
--allow-enumerate (or WAKE_RECONCILE_ALLOW_ENUMERATE=1), promising no
|
||||
detector co-feeds this store until #908 lands.
|
||||
--no-enumerate (and `check`) never write, so they are always safe.
|
||||
|
||||
check
|
||||
The full §4/G3 gate, side-effect-free: `inventory` AND
|
||||
`reconcile --no-enumerate`. Exit 0 IFF the inventory is complete AND 0
|
||||
unaccounted. Use this to evaluate the vector's G3 clause without writing.
|
||||
|
||||
Environment:
|
||||
WAKE_WATCH_LIST Operator watch-list JSON (required).
|
||||
WAKE_DETECTOR_SOURCE_CMD Source adapter (required for reconcile/check; same
|
||||
contract as the detector: <cmd> <kind> <id>, def on
|
||||
stdin; exit!=0 or empty => FAIL LOUD).
|
||||
WAKE_STATE_HOME/WAKE_AGENT store namespace (see store.sh).
|
||||
WAKE_RECONCILE_ALLOW_ENUMERATE set to 1 to assert reconciler-SOLE-FEEDER mode
|
||||
(see reconcile's dual-allocator safety note; #908).
|
||||
EOF
|
||||
}
|
||||
|
||||
_manifest_val() {
|
||||
local key="$1"
|
||||
[ -f "$MANIFEST" ] || return 0
|
||||
sed -n "s/^${key}=//p" "$MANIFEST" | head -n1 | tr -d '[:space:]'
|
||||
}
|
||||
|
||||
# _load_watchlist — validate path + JSON + shape + Gate B schema range (mirrors
|
||||
# the detector's fail-loud validation so the reconciler certifies the SAME
|
||||
# watch-list the detector runs). Echoes validated JSON on stdout.
|
||||
_load_watchlist() {
|
||||
_need_jq
|
||||
local wl="${WAKE_WATCH_LIST:-}"
|
||||
if [ -z "$wl" ]; then
|
||||
echo "reconcile.sh: WAKE_WATCH_LIST is not set (no watch-list to reconcile)" >&2
|
||||
return 2
|
||||
fi
|
||||
if [ ! -f "$wl" ]; then
|
||||
echo "reconcile.sh: watch-list not found: $wl" >&2
|
||||
return 2
|
||||
fi
|
||||
local json
|
||||
if ! json="$(jq -e . "$wl" 2>/dev/null)"; then
|
||||
echo "reconcile.sh: watch-list is not valid JSON: $wl" >&2
|
||||
return 2
|
||||
fi
|
||||
if ! printf '%s' "$json" | jq -e 'has("schema_version") and has("watches")' >/dev/null 2>&1; then
|
||||
echo "reconcile.sh: watch-list missing required 'schema_version' or 'watches'" >&2
|
||||
return 2
|
||||
fi
|
||||
local ver smin smax
|
||||
ver="$(printf '%s' "$json" | jq -r '.schema_version')"
|
||||
smin="$(_manifest_val schema_min)"
|
||||
smax="$(_manifest_val schema_max)"
|
||||
case "$ver" in
|
||||
'' | *[!0-9]*)
|
||||
echo "reconcile.sh: watch-list schema_version must be an integer (got '$ver')" >&2
|
||||
return 2
|
||||
;;
|
||||
esac
|
||||
if [ -z "$smin" ] || [ -z "$smax" ]; then
|
||||
echo "reconcile.sh: manifest is missing schema_min/schema_max (cannot validate Gate B)" >&2
|
||||
return 2
|
||||
fi
|
||||
if [ "$ver" -lt "$smin" ] || [ "$ver" -gt "$smax" ]; then
|
||||
echo "reconcile.sh: FAIL LOUD (Gate B) — watch-list schema_version $ver is OUTSIDE the supported range [$smin, $smax]" >&2
|
||||
return 2
|
||||
fi
|
||||
printf '%s' "$json"
|
||||
}
|
||||
|
||||
# _coll_for_kind KIND — the top-level collection a source kind is defined in.
|
||||
_coll_for_kind() {
|
||||
case "$1" in
|
||||
repo) printf 'repos' ;;
|
||||
board_file) printf 'board_files' ;;
|
||||
lane_anchor) printf 'lane_anchors' ;;
|
||||
*) return 1 ;;
|
||||
esac
|
||||
}
|
||||
|
||||
# --- part (i): source-coverage parity inventory ----------------------------
|
||||
|
||||
cmd_inventory() {
|
||||
local json
|
||||
json="$(_load_watchlist)" || exit $?
|
||||
|
||||
local flags=0
|
||||
|
||||
# An empty watch-list can never certify coverage of anything.
|
||||
local nwatch
|
||||
nwatch="$(printf '%s' "$json" | jq -r '.watches | length')"
|
||||
if [ "${nwatch:-0}" -eq 0 ]; then
|
||||
echo "reconcile.sh: FLAG (G3 parity) — watch-list declares NO watches; coverage is vacuous." >&2
|
||||
flags=$((flags + 1))
|
||||
fi
|
||||
|
||||
echo "# source-coverage parity inventory (lane-by-lane)"
|
||||
|
||||
# Per-lane declared inventory + empty-lane + required_sources checks.
|
||||
local nlanes li
|
||||
nlanes="$(printf '%s' "$json" | jq -r '.watches | length')"
|
||||
li=0
|
||||
while [ "$li" -lt "${nlanes:-0}" ]; do
|
||||
local lane nsrc
|
||||
lane="$(printf '%s' "$json" | jq -r --argjson i "$li" '.watches[$i].lane // "(unnamed)"')"
|
||||
nsrc="$(printf '%s' "$json" | jq -r --argjson i "$li" '.watches[$i].sources | length')"
|
||||
printf ' lane %s: %s declared source(s)\n' "$lane" "${nsrc:-0}"
|
||||
|
||||
if [ "${nsrc:-0}" -eq 0 ]; then
|
||||
echo "reconcile.sh: FLAG (G3 parity) — lane '$lane' declares ZERO sources (empty coverage)." >&2
|
||||
flags=$((flags + 1))
|
||||
fi
|
||||
|
||||
# required_sources (optional, additive; ignored by the detector). If the
|
||||
# operator declares the lane's true dependency set here, every id MUST be
|
||||
# covered by the lane's sources — an OMITTED dependency FLAGS.
|
||||
local missing
|
||||
missing="$(printf '%s' "$json" | jq -r --argjson i "$li" '
|
||||
(.watches[$i].required_sources // []) as $req
|
||||
| ($req - [ .watches[$i].sources[].id ]) | .[]')"
|
||||
if [ -n "$missing" ]; then
|
||||
local m
|
||||
while IFS= read -r m; do
|
||||
[ -n "$m" ] || continue
|
||||
echo "reconcile.sh: FLAG (G3 parity) — lane '$lane' requires source '$m' but it is OMITTED from the lane's watched sources (vacuous-pass prevented)." >&2
|
||||
flags=$((flags + 1))
|
||||
done <<EOF
|
||||
$missing
|
||||
EOF
|
||||
fi
|
||||
li=$((li + 1))
|
||||
done
|
||||
|
||||
# Dangling: every watched (kind,id) MUST have a declared definition.
|
||||
local pairs kind id
|
||||
pairs="$(printf '%s' "$json" | jq -r '[ .watches[].sources[] | "\(.kind)\t\(.id)" ] | unique | .[]')"
|
||||
while IFS=$'\t' read -r kind id; do
|
||||
[ -n "$kind" ] || continue
|
||||
local coll def
|
||||
if ! coll="$(_coll_for_kind "$kind")"; then
|
||||
echo "reconcile.sh: FLAG (G3 parity) — unknown source kind '$kind' in a watch." >&2
|
||||
flags=$((flags + 1))
|
||||
continue
|
||||
fi
|
||||
def="$(printf '%s' "$json" | jq -c --arg c "$coll" --arg id "$id" '(.[$c] // []) | map(select(.id == $id)) | .[0] // empty')"
|
||||
if [ -z "$def" ]; then
|
||||
echo "reconcile.sh: FLAG (G3 parity) — watch references '$kind/$id' but no such entry is declared in '$coll' (dangling)." >&2
|
||||
flags=$((flags + 1))
|
||||
fi
|
||||
done <<EOF
|
||||
$pairs
|
||||
EOF
|
||||
|
||||
# Omitted-from-coverage: every DECLARED operational source must be covered by
|
||||
# at least one watch. A declared-but-unwatched source is exactly the OMITTED
|
||||
# source that would let the vector pass VACUOUSLY (the detector never checks it).
|
||||
local coll kinds
|
||||
kinds="repos:repo board_files:board_file lane_anchors:lane_anchor"
|
||||
for coll in $kinds; do
|
||||
local cname ckind ids
|
||||
cname="${coll%%:*}"
|
||||
ckind="${coll##*:}"
|
||||
ids="$(printf '%s' "$json" | jq -r --arg c "$cname" '(.[$c] // [])[].id')"
|
||||
local sid covered
|
||||
while IFS= read -r sid; do
|
||||
[ -n "$sid" ] || continue
|
||||
covered="$(printf '%s' "$json" | jq -r --arg k "$ckind" --arg id "$sid" \
|
||||
'[ .watches[].sources[] | select(.kind==$k and .id==$id) ] | length')"
|
||||
if [ "${covered:-0}" -eq 0 ]; then
|
||||
echo "reconcile.sh: FLAG (G3 parity) — declared source '$ckind/$sid' is NOT covered by any watch (OMITTED from coverage; vacuous-pass prevented)." >&2
|
||||
flags=$((flags + 1))
|
||||
fi
|
||||
done <<EOF
|
||||
$ids
|
||||
EOF
|
||||
done
|
||||
|
||||
if [ "$flags" -ne 0 ]; then
|
||||
echo "reconcile.sh: source-parity inventory INCOMPLETE — $flags flag(s). The §4 vector's G3 clause does NOT pass." >&2
|
||||
return 1
|
||||
fi
|
||||
echo "reconcile.sh: source-parity inventory COMPLETE (every declared source is covered; no dangling/empty/omitted)."
|
||||
return 0
|
||||
}
|
||||
|
||||
# --- part (ii): full reconcile (0 unaccounted) -----------------------------
|
||||
|
||||
# _scope_anchor ANCHOR (content on stdin) — mirror of the detector's anchor
|
||||
# scoping so the reconciler hashes the SAME region the detector would. Extract
|
||||
# from the first line containing the anchor up to the next heading (or EOF).
|
||||
_scope_anchor() {
|
||||
local anchor="$1"
|
||||
awk -v a="$anchor" '
|
||||
index($0, a) > 0 && !inzone { inzone=1; print; next }
|
||||
inzone && /^#/ { exit }
|
||||
inzone { print }
|
||||
'
|
||||
}
|
||||
|
||||
# _recon_key KIND ID — stable per-source ledger key.
|
||||
_recon_key() {
|
||||
printf '%s\037%s' "$1" "$2" | _hash
|
||||
}
|
||||
|
||||
# _observe_source KIND ID DEF — observe current scoped state; echo the hash on
|
||||
# success (rc 0). rc 1 = FAIL LOUD (source error / ambiguous-empty), same G2a
|
||||
# discipline as the detector: an error is never silently "no state".
|
||||
_observe_source() {
|
||||
local kind="$1" id="$2" def="$3"
|
||||
local anchor raw rc deftmp
|
||||
anchor="$(printf '%s' "$def" | jq -r '.anchor // empty')"
|
||||
mkdir -p "$RECON_DIR"
|
||||
# shellcheck disable=SC2154
|
||||
deftmp="$(mktemp "$RECON_DIR/${_wake_tmp_prefix}defXXXXXX")" || return 1
|
||||
printf '%s' "$def" >"$deftmp"
|
||||
raw="$("$WAKE_DETECTOR_SOURCE_CMD" "$kind" "$id" <"$deftmp" 2>/dev/null)"
|
||||
rc=$?
|
||||
rm -f "$deftmp"
|
||||
if [ "$rc" -ne 0 ]; then
|
||||
echo "reconcile.sh: FAIL LOUD (G2a) — source '$kind/$id' errored (adapter exit $rc). Cannot certify parity; not treated as 'no state'." >&2
|
||||
return 1
|
||||
fi
|
||||
if [ -z "$raw" ]; then
|
||||
echo "reconcile.sh: FAIL LOUD (G2a) — source '$kind/$id' returned AMBIGUOUS-EMPTY (empty-that-might-mean-hidden is never 'no state')." >&2
|
||||
return 1
|
||||
fi
|
||||
local scoped
|
||||
if [ -n "$anchor" ]; then
|
||||
scoped="$(printf '%s' "$raw" | _scope_anchor "$anchor")"
|
||||
if [ -z "$scoped" ]; then
|
||||
echo "reconcile.sh: FAIL LOUD (G2a) — source '$kind/$id' anchor '$anchor' not present (ambiguous section state)." >&2
|
||||
return 1
|
||||
fi
|
||||
else
|
||||
scoped="$raw"
|
||||
fi
|
||||
printf '%s' "$scoped" | _hash
|
||||
}
|
||||
|
||||
# _inbox_has KIND ID HASH — true iff a pending inbox entry reflects this exact
|
||||
# source state (observed_seq/inbox is the §4/G3 accounting universe).
|
||||
_inbox_has() {
|
||||
local kind="$1" id="$2" h="$3" n
|
||||
n="$("$STORE_SH" drain 2>/dev/null | jq -s --arg k "$kind" --arg id "$id" --arg h "$h" \
|
||||
'[ .[] | select(.locators.kind==$k and .locators.id==$id and .locators.observed_hash==$h) ] | length' 2>/dev/null || echo 0)"
|
||||
[ "${n:-0}" -gt 0 ]
|
||||
}
|
||||
|
||||
cmd_reconcile() {
|
||||
local enumerate=1 allow_enumerate=0
|
||||
while [ $# -gt 0 ]; do
|
||||
case "$1" in
|
||||
--no-enumerate)
|
||||
enumerate=0
|
||||
shift
|
||||
;;
|
||||
--allow-enumerate)
|
||||
allow_enumerate=1
|
||||
shift
|
||||
;;
|
||||
*)
|
||||
echo "reconcile.sh reconcile: unknown option '$1'" >&2
|
||||
exit 2
|
||||
;;
|
||||
esac
|
||||
done
|
||||
[ "${WAKE_RECONCILE_ALLOW_ENUMERATE:-0}" = "1" ] && allow_enumerate=1
|
||||
|
||||
local json
|
||||
json="$(_load_watchlist)" || exit $?
|
||||
if [ -z "${WAKE_DETECTOR_SOURCE_CMD:-}" ]; then
|
||||
echo "reconcile.sh: WAKE_DETECTOR_SOURCE_CMD is not set (no adapter to observe source state)" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
"$STORE_SH" init >/dev/null 2>&1 || true
|
||||
mkdir -p "$RECON_DIR"
|
||||
|
||||
# --- DUAL-ALLOCATOR SAFETY GATE (fail-closed; #908) ------------------------
|
||||
# Decide, ONCE, whether ENUMERATION (the observed_seq WRITE path) is safe this
|
||||
# pass. It is unsafe — and we REFUSE (flag, never swallow) — whenever a seq we
|
||||
# allocate could be REISSUED by the detector's INDEPENDENT private counter and
|
||||
# alias a distinct obligation (see the header hazard note). --no-enumerate and
|
||||
# `check` never write, so the gate does not apply to them.
|
||||
local enum_mode="$enumerate" enum_refuse_reason=""
|
||||
if [ "$enumerate" -eq 1 ]; then
|
||||
if [ -e "$DET_STATE" ]; then
|
||||
enum_mode=0
|
||||
enum_refuse_reason="a detector is co-feeding this store ($DET_STATE exists); its private observed_seq counter (W4) is INDEPENDENT of the store cursor this reconciler allocates from, so enumerating would risk REISSUING/ALIASING a seq and silently swallowing a distinct obligation. #908 tracks the store-side allocator unification that makes co-feeding safe. OPERATIONAL GUARD: do not run a detector and the reconciler against one store until #908."
|
||||
elif [ "$allow_enumerate" -ne 1 ]; then
|
||||
enum_mode=0
|
||||
enum_refuse_reason="enumeration writes observed_seq via an allocator INDEPENDENT of the detector's private counter (W4); until #908 unifies them, co-feeding one store aliases seqs even under strictly-sequential calls. Set --allow-enumerate (or WAKE_RECONCILE_ALLOW_ENUMERATE=1) to assert this store is reconciler-SOLE-FEEDER (no detector co-feeds it)."
|
||||
fi
|
||||
fi
|
||||
|
||||
# Seq allocation base: the store's authoritative observed_seq (§2.4). Used ONLY
|
||||
# on the sole-feeder path the gate above has proven safe.
|
||||
local obs_base offset
|
||||
obs_base="$("$STORE_SH" cursors 2>/dev/null | sed -n 's/^observed_seq=//p')"
|
||||
case "$obs_base" in '' | *[!0-9]*) obs_base=0 ;; esac
|
||||
offset=0
|
||||
local refuse_announced=0 refused=0
|
||||
|
||||
local pairs kind id failed=0 unaccounted=0 enumerated=0
|
||||
pairs="$(printf '%s' "$json" | jq -r '[ .watches[].sources[] | "\(.kind)\t\(.id)" ] | unique | .[]')"
|
||||
if [ -z "$pairs" ]; then
|
||||
echo "reconcile.sh: watch-list declares no sources under watches[].sources[]" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
echo "# full reconcile (declared+configured source state vs observed_seq/inbox)"
|
||||
while IFS=$'\t' read -r kind id; do
|
||||
[ -n "$kind" ] || continue
|
||||
local coll def
|
||||
if ! coll="$(_coll_for_kind "$kind")"; then
|
||||
echo "reconcile.sh: FAIL LOUD — unknown source kind '$kind' in watch-list" >&2
|
||||
failed=1
|
||||
continue
|
||||
fi
|
||||
def="$(printf '%s' "$json" | jq -c --arg c "$coll" --arg id "$id" '(.[$c] // []) | map(select(.id == $id)) | .[0] // empty')"
|
||||
if [ -z "$def" ]; then
|
||||
echo "reconcile.sh: FAIL LOUD (G3 parity) — watch references '$kind/$id' but no such entry is declared in '$coll'" >&2
|
||||
failed=1
|
||||
continue
|
||||
fi
|
||||
|
||||
local curhash key ledger accounted
|
||||
if ! curhash="$(_observe_source "$kind" "$id" "$def")"; then
|
||||
failed=1
|
||||
continue
|
||||
fi
|
||||
key="$(_recon_key "$kind" "$id")"
|
||||
ledger="$RECON_DIR/seen-$key"
|
||||
|
||||
accounted=0
|
||||
# Reflected in the durable inbox (delivered, awaiting consume)?
|
||||
if _inbox_has "$kind" "$id" "$curhash"; then
|
||||
accounted=1
|
||||
# Or already reconciled to this exact state before (durable ledger)?
|
||||
elif [ -f "$ledger" ] && [ "$(tr -d '[:space:]' <"$ledger")" = "$curhash" ]; then
|
||||
accounted=1
|
||||
fi
|
||||
|
||||
if [ "$accounted" -eq 1 ]; then
|
||||
printf ' %s/%s: ACCOUNTED\n' "$kind" "$id"
|
||||
continue
|
||||
fi
|
||||
|
||||
# UNACCOUNTED: a source state not reflected in observed_seq/inbox => a gap.
|
||||
unaccounted=$((unaccounted + 1))
|
||||
printf ' %s/%s: UNACCOUNTED (current state not reflected in observed_seq/inbox)\n' "$kind" "$id" >&2
|
||||
|
||||
if [ "$enumerate" -eq 1 ] && [ "$enum_mode" -eq 0 ]; then
|
||||
# REFUSE to enumerate (fail-closed): the obligation is loudly FLAGGED, NOT
|
||||
# silently swallowed. Announce the dual-allocator reason once.
|
||||
if [ "$refuse_announced" -eq 0 ]; then
|
||||
echo "reconcile.sh: FAIL LOUD (dual-allocator hazard, #908) — $enum_refuse_reason" >&2
|
||||
refuse_announced=1
|
||||
fi
|
||||
refused=1
|
||||
printf ' -> REFUSED enumeration (FLAGGED, not swallowed; see dual-allocator hazard / #908)\n' >&2
|
||||
elif [ "$enum_mode" -eq 1 ]; then
|
||||
# ENUMERATE the pre-existing/startup obligation into the durable store.
|
||||
# This path runs ONLY when the safety gate proved the reconciler is the
|
||||
# SOLE feeder (no detector co-feeding), so its store-cursor allocation
|
||||
# cannot be aliased. Class = non-coalescible fail-safe `actionable` (§2.3)
|
||||
# so distinct pre-existing obligations never collapse together.
|
||||
offset=$((offset + 1))
|
||||
local seq locators
|
||||
seq=$((obs_base + offset))
|
||||
locators="$(jq -cn --arg kind "$kind" --arg id "$id" --arg hash "$curhash" \
|
||||
--argjson sdef "$def" \
|
||||
'{kind:$kind, id:$id, observed_hash:$hash, reconciled:true}
|
||||
+ ( $sdef | {repo, path, anchor, remote, branches} | with_entries(select(.value != null)) )')"
|
||||
if "$STORE_SH" enqueue --seq "$seq" --class actionable --locators "$locators" >/dev/null 2>&1; then
|
||||
printf '%s' "$curhash" | _atomic_write "$ledger"
|
||||
enumerated=$((enumerated + 1))
|
||||
printf ' -> enumerated into store as observed_seq=%s (class=actionable)\n' "$seq"
|
||||
else
|
||||
echo "reconcile.sh: enumerate FAILED for '$kind/$id' seq $seq" >&2
|
||||
failed=1
|
||||
fi
|
||||
fi
|
||||
done <<EOF
|
||||
$pairs
|
||||
EOF
|
||||
|
||||
echo "reconcile.sh: UNACCOUNTED=$unaccounted ENUMERATED=$enumerated"
|
||||
if [ "$failed" -ne 0 ]; then
|
||||
echo "reconcile.sh: reconcile FAILED (a source could not be observed/enumerated)." >&2
|
||||
return 1
|
||||
fi
|
||||
if [ "$unaccounted" -ne 0 ]; then
|
||||
if [ "$refused" -eq 1 ]; then
|
||||
echo "reconcile.sh: FLAG — $unaccounted unaccounted source-state(s) REFUSED enumeration (dual-allocator hazard, #908). They are flagged, NOT swallowed. Resolve co-feeding / assert sole-feeder, then re-run." >&2
|
||||
elif [ "$enumerate" -eq 1 ]; then
|
||||
echo "reconcile.sh: FLAG — $unaccounted unaccounted source-state(s) found and enumerated. Re-run to confirm 0." >&2
|
||||
else
|
||||
echo "reconcile.sh: FLAG — $unaccounted unaccounted source-state(s) (audit mode; nothing enumerated)." >&2
|
||||
fi
|
||||
return 1
|
||||
fi
|
||||
echo "reconcile.sh: reconcile CLEAN — 0 unaccounted (every declared source state is reflected in observed_seq/inbox)."
|
||||
return 0
|
||||
}
|
||||
|
||||
cmd_check() {
|
||||
# The full §4/G3 gate, side-effect-free.
|
||||
local rc=0
|
||||
cmd_inventory || rc=1
|
||||
cmd_reconcile --no-enumerate || rc=1
|
||||
if [ "$rc" -eq 0 ]; then
|
||||
echo "reconcile.sh: G3 GATE PASS — inventory complete AND 0 unaccounted."
|
||||
else
|
||||
echo "reconcile.sh: G3 GATE FAIL — inventory incomplete OR unaccounted state present." >&2
|
||||
fi
|
||||
return "$rc"
|
||||
}
|
||||
|
||||
main() {
|
||||
[ $# -ge 1 ] || {
|
||||
usage
|
||||
exit 2
|
||||
}
|
||||
local cmd="$1"
|
||||
shift
|
||||
case "$cmd" in
|
||||
inventory) cmd_inventory "$@" ;;
|
||||
reconcile) cmd_reconcile "$@" ;;
|
||||
check) cmd_check "$@" ;;
|
||||
-h | --help | help) usage ;;
|
||||
*)
|
||||
echo "reconcile.sh: unknown command '$cmd'" >&2
|
||||
usage
|
||||
exit 2
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
main "$@"
|
||||
Reference in New Issue
Block a user