pi-braid 0.40.1 → 0.40.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTRIBUTING.md +27 -3
- package/README.md +13 -13
- package/TOOLS.md +27 -3
- package/build-info.json +9 -0
- package/dist/extensions/cognitive/metacognition/handlers/claim-verification.js +7 -1
- package/dist/extensions/cognitive/metacognition/handlers/finalize.js +20 -0
- package/dist/extensions/cognitive/metacognition/handlers/hypothesize.d.ts +9 -0
- package/dist/extensions/cognitive/metacognition/handlers/hypothesize.js +13 -1
- package/dist/extensions/cognitive/metacognition/handlers/verify.js +35 -4
- package/dist/extensions/cognitive/topic-drift/index.js +19 -2
- package/dist/extensions/core/prompt-builder/inspect.js +9 -3
- package/dist/extensions/core/prompt-builder/top-level-extensions.d.ts +6 -5
- package/dist/extensions/core/prompt-builder/top-level-extensions.js +64 -29
- package/dist/extensions/enforcement/handlers/register-tool-result-formatting.d.ts +1 -1
- package/dist/extensions/enforcement/handlers/register-tool-result-formatting.js +1 -1
- package/dist/extensions/enforcement/handlers/turn-end-handler.js +1 -1
- package/dist/extensions/enforcement/self-state-claims.d.ts +1 -1
- package/dist/extensions/enforcement/self-state-claims.js +3 -2
- package/dist/extensions/manifest.js +2 -2
- package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.d.ts +22 -5
- package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.js +43 -11
- package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +174 -50
- package/dist/extensions/memory/context-manager/handlers/tools/context-inspect.js +7 -1
- package/dist/extensions/memory/context-manager/handlers/tools/context-navigate.js +4 -1
- package/dist/extensions/memory/memory-agent-bridge/explore-paths.d.ts +2 -24
- package/dist/extensions/memory/memory-agent-bridge/explore-paths.js +33 -2
- package/dist/extensions/memory/memory-agent-bridge/memory-store-tool.js +16 -0
- package/dist/extensions/memory/memory-agent-bridge/memory-tool.js +21 -9
- package/dist/extensions/memory/scratchpad/format.js +8 -2
- package/dist/extensions/memory/scratchpad/index.js +11 -2
- package/dist/extensions/memory/session-recall/index.js +19 -6
- package/dist/extensions/memory/three-memory-stores/episodes.d.ts +1 -1
- package/dist/extensions/memory/three-memory-stores/episodes.js +2 -2
- package/dist/extensions/orchestrator/index.js +73 -8
- package/dist/extensions/scheduling/timer/index.js +9 -1
- package/dist/extensions/self/error-tracking/index.js +8 -1
- package/dist/extensions/self/health-maintenance/handlers/session-health-tool.js +9 -2
- package/dist/extensions/self/health-maintenance/index.js +112 -9
- package/dist/lib/config/braid-settings.d.ts +21 -0
- package/dist/lib/config/braid-settings.js +36 -0
- package/dist/lib/constants/session-thresholds.d.ts +2 -3
- package/dist/lib/constants/session-thresholds.js +2 -3
- package/dist/lib/enforcement/turn-dedup.d.ts +2 -2
- package/dist/lib/enforcement/turn-dedup.js +2 -2
- package/dist/lib/harness/index.d.ts +1 -1
- package/dist/lib/harness/index.js +1 -1
- package/dist/lib/harness/types.d.ts +1 -1
- package/dist/lib/harness/types.js +1 -1
- package/dist/lib/orchestrator/index.d.ts +2 -2
- package/dist/lib/orchestrator/index.js +1 -1
- package/dist/lib/orchestrator/workers.d.ts +184 -2
- package/dist/lib/orchestrator/workers.js +521 -6
- package/dist/lib/utils/injection-tracker.js +1 -1
- package/docs/CONTEXT-POLICY.md +13 -5
- package/docs/LOCAL_DEV.md +31 -5
- package/docs/ROADMAP.md +10 -7
- package/docs/SETUP.md +3 -2
- package/package.json +11 -8
- package/skills/braid-reference/SKILL.md +23 -23
- package/skills/release-pipeline/SKILL.md +46 -37
- package/skills/subagent-orchestration/SKILL.md +51 -1
- package/src/extensions/cognitive/metacognition/handlers/claim-verification.ts +8 -1
- package/src/extensions/cognitive/metacognition/handlers/finalize.ts +21 -0
- package/src/extensions/cognitive/metacognition/handlers/hypothesize.ts +14 -1
- package/src/extensions/cognitive/metacognition/handlers/verify.ts +39 -5
- package/src/extensions/cognitive/topic-drift/index.ts +20 -2
- package/src/extensions/core/prompt-builder/AGENTS.md +1 -1
- package/src/extensions/core/prompt-builder/inspect.ts +10 -3
- package/src/extensions/core/prompt-builder/top-level-extensions.ts +68 -29
- package/src/extensions/enforcement/AGENTS.md +25 -19
- package/src/extensions/enforcement/handlers/register-tool-result-formatting.ts +1 -1
- package/src/extensions/enforcement/handlers/turn-end-handler.ts +1 -1
- package/src/extensions/enforcement/self-state-claims.ts +3 -2
- package/src/extensions/heartbeat/heartbeat-scheduler/AGENTS.md +6 -3
- package/src/extensions/manifest.ts +2 -2
- package/src/extensions/memory/AGENTS.md +13 -5
- package/src/extensions/memory/context-manager/handlers/tool-batch-boundary.ts +45 -11
- package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +202 -60
- package/src/extensions/memory/context-manager/handlers/tools/context-inspect.ts +8 -1
- package/src/extensions/memory/context-manager/handlers/tools/context-navigate.ts +4 -1
- package/src/extensions/memory/memory-agent-bridge/explore-paths.ts +37 -3
- package/src/extensions/memory/memory-agent-bridge/memory-store-tool.ts +16 -0
- package/src/extensions/memory/memory-agent-bridge/memory-tool.ts +22 -9
- package/src/extensions/memory/scratchpad/format.ts +8 -2
- package/src/extensions/memory/scratchpad/index.ts +12 -2
- package/src/extensions/memory/session-recall/index.ts +20 -8
- package/src/extensions/memory/three-memory-stores/episodes.ts +2 -2
- package/src/extensions/orchestrator/index.ts +100 -11
- package/src/extensions/scheduling/timer/AGENTS.md +7 -0
- package/src/extensions/scheduling/timer/index.ts +10 -1
- package/src/extensions/self/error-tracking/index.ts +9 -1
- package/src/extensions/self/health-maintenance/handlers/session-health-tool.ts +10 -2
- package/src/extensions/self/health-maintenance/index.ts +143 -14
- package/src/extensions/self/watchdog/AGENTS.md +1 -0
- package/src/lib/AGENTS.md +21 -21
- package/src/lib/config/braid-settings.ts +74 -0
- package/src/lib/constants/session-thresholds.ts +2 -3
- package/src/lib/enforcement/turn-dedup.ts +2 -2
- package/src/lib/harness/AGENTS.md +1 -1
- package/src/lib/harness/index.ts +1 -1
- package/src/lib/harness/types.ts +1 -1
- package/src/lib/orchestrator/index.ts +26 -0
- package/src/lib/orchestrator/workers.ts +705 -7
- package/src/lib/utils/AGENTS.md +1 -1
- package/src/lib/utils/injection-tracker.ts +1 -1
|
@@ -21,6 +21,7 @@
|
|
|
21
21
|
*/
|
|
22
22
|
|
|
23
23
|
import {
|
|
24
|
+
appendFileSync,
|
|
24
25
|
chmodSync,
|
|
25
26
|
existsSync,
|
|
26
27
|
mkdirSync,
|
|
@@ -33,9 +34,14 @@ import {
|
|
|
33
34
|
} from "node:fs";
|
|
34
35
|
import { execFileSync } from "node:child_process";
|
|
35
36
|
import { dirname, join } from "node:path";
|
|
36
|
-
import { getWorkersFilePath, projectsDir } from "../config/braid-paths.js";
|
|
37
|
+
import { braidDir, getWorkersFilePath, projectsDir } from "../config/braid-paths.js";
|
|
38
|
+
import { getCloseGateWellFormedness } from "../config/braid-settings.js";
|
|
39
|
+
import type { CloseGateWellFormednessMode } from "../config/braid-settings.js";
|
|
40
|
+
import { createLogger } from "../core/logger.js";
|
|
37
41
|
import { getAllLocks, releaseLock } from "./locks.js";
|
|
38
42
|
|
|
43
|
+
const log = createLogger("orchestrator:workers");
|
|
44
|
+
|
|
39
45
|
// ── Types ──────────────────────────────────────────────────────────────────
|
|
40
46
|
|
|
41
47
|
export type WorkerStatus =
|
|
@@ -55,6 +61,14 @@ export interface WorkerGate {
|
|
|
55
61
|
cmd: string;
|
|
56
62
|
exit: number;
|
|
57
63
|
at: string;
|
|
64
|
+
/**
|
|
65
|
+
* What the gate's population scan recorded, in the contract's shape
|
|
66
|
+
* (`scanned <n> <unit> at <revision>`). Optional: a gate with no population
|
|
67
|
+
* subject carries none, and a row recorded before the field existed stays
|
|
68
|
+
* valid. Stored verbatim; the read that compares it against the repo lives
|
|
69
|
+
* on the merge path.
|
|
70
|
+
*/
|
|
71
|
+
stamp?: string;
|
|
58
72
|
}
|
|
59
73
|
|
|
60
74
|
/** One duplicate admission a live entry turned away, and the request it refused. */
|
|
@@ -727,7 +741,7 @@ export function recordWorkerMerge(
|
|
|
727
741
|
function assertGateEvidence(
|
|
728
742
|
workerId: string,
|
|
729
743
|
outcome: WorkerOutcome,
|
|
730
|
-
gates: Array<{ cmd: string; exit: number }> | undefined,
|
|
744
|
+
gates: Array<{ cmd: string; exit: number; stamp?: string }> | undefined,
|
|
731
745
|
): void {
|
|
732
746
|
if (gates !== undefined && !Array.isArray(gates)) {
|
|
733
747
|
throw new Error(
|
|
@@ -747,7 +761,7 @@ function assertGateEvidence(
|
|
|
747
761
|
`closeWorker: gates[${i}] must be an object carrying cmd and exit (worker ${workerId})`,
|
|
748
762
|
);
|
|
749
763
|
}
|
|
750
|
-
const { cmd, exit } = gate as { cmd?: unknown; exit?: unknown };
|
|
764
|
+
const { cmd, exit, stamp } = gate as { cmd?: unknown; exit?: unknown; stamp?: unknown };
|
|
751
765
|
if (typeof cmd !== "string" || cmd.trim() === "") {
|
|
752
766
|
throw new Error(
|
|
753
767
|
`closeWorker: gates[${i}].cmd must be a non-empty string (worker ${workerId})`,
|
|
@@ -756,9 +770,638 @@ function assertGateEvidence(
|
|
|
756
770
|
if (typeof exit !== "number" || !Number.isFinite(exit)) {
|
|
757
771
|
throw new Error(`closeWorker: gates[${i}].exit must be a number (worker ${workerId})`);
|
|
758
772
|
}
|
|
773
|
+
// Only the field's type is decided here: whether a stamp is the contract's
|
|
774
|
+
// shape, or is missing from a gate that scanned a population, is the
|
|
775
|
+
// readers' business (the result validator warns; the merge path compares).
|
|
776
|
+
// A non-string stamp cannot be read by either, so it is a shape refusal.
|
|
777
|
+
if (stamp !== undefined && typeof stamp !== "string") {
|
|
778
|
+
throw new Error(`closeWorker: gates[${i}].stamp must be a string (worker ${workerId})`);
|
|
779
|
+
}
|
|
780
|
+
}
|
|
781
|
+
}
|
|
782
|
+
|
|
783
|
+
// ── Gate-row well-formedness (the close path) ──────────────────────────────
|
|
784
|
+
// Four string predicates over each recorded row, none of which reads what the
|
|
785
|
+
// command does and none of which re-runs it: (a) the cmd parses under
|
|
786
|
+
// `sh -n`; (b) after leading `VAR=x` assignments are stripped, the first token
|
|
787
|
+
// resolves to an executable; (c) the field is the command alone, with no
|
|
788
|
+
// top-level decoration by which the recorded exit would belong to another
|
|
789
|
+
// command; (d) a completed close records exit 0 under every row. A failing
|
|
790
|
+
// row is logged, and in enforce mode refused; shadow mode is the shipped
|
|
791
|
+
// default. Replay stays the sampler's sampled job: nothing here executes a
|
|
792
|
+
// cmd, `sh -n` parses only and `command -v` only looks a token up.
|
|
793
|
+
|
|
794
|
+
/** Predicate letters, in the order the four are evaluated. */
|
|
795
|
+
export type GateRowPredicate = "a" | "b" | "c" | "d";
|
|
796
|
+
|
|
797
|
+
export interface GateRowViolation {
|
|
798
|
+
predicate: GateRowPredicate;
|
|
799
|
+
detail: string;
|
|
800
|
+
}
|
|
801
|
+
|
|
802
|
+
/** One leading `VAR=value` assignment, quoted value or not. */
|
|
803
|
+
const ENV_ASSIGNMENT_RE = /^\s*[A-Za-z_][A-Za-z0-9_]*=(?:"(?:[^"\\]|\\.)*"|'[^']*'|[^\s]*)(?=\s|$)/;
|
|
804
|
+
|
|
805
|
+
/**
|
|
806
|
+
* Strip leading env assignments one at a time. A single-assignment regex
|
|
807
|
+
* applied in a loop, rather than one repeated group: the repeated form
|
|
808
|
+
* backtracks over the whole field when it fails to match, and this runs before
|
|
809
|
+
* any row is judged, on a field a caller controls.
|
|
810
|
+
*/
|
|
811
|
+
function stripLeadingEnvAssignments(cmd: string): string {
|
|
812
|
+
let rest = cmd;
|
|
813
|
+
for (;;) {
|
|
814
|
+
const match = rest.match(ENV_ASSIGNMENT_RE);
|
|
815
|
+
if (!match) return rest;
|
|
816
|
+
rest = rest.slice(match[0].length);
|
|
817
|
+
}
|
|
818
|
+
}
|
|
819
|
+
|
|
820
|
+
/** The first whitespace-delimited token after leading env assignments, or null. */
|
|
821
|
+
export function firstCommandToken(cmd: string): string | null {
|
|
822
|
+
const rest = stripLeadingEnvAssignments(cmd).trimStart();
|
|
823
|
+
const token = rest.split(/\s+/, 1)[0];
|
|
824
|
+
return token.length > 0 ? token : null;
|
|
825
|
+
}
|
|
826
|
+
|
|
827
|
+
/** One `sh` look-up outcome: ok, row-fail with the shell's own line, or no shell. */
|
|
828
|
+
type ShellCheck = { ok: true } | { ok: false; detail: string } | { unavailable: true };
|
|
829
|
+
|
|
830
|
+
function runShell(args: string[]): ShellCheck {
|
|
831
|
+
try {
|
|
832
|
+
execFileSync("sh", args, {
|
|
833
|
+
stdio: ["ignore", "ignore", "pipe"],
|
|
834
|
+
encoding: "utf8",
|
|
835
|
+
timeout: 5000,
|
|
836
|
+
});
|
|
837
|
+
return { ok: true };
|
|
838
|
+
} catch (error) {
|
|
839
|
+
const e = error as { code?: unknown; status?: unknown; stderr?: unknown };
|
|
840
|
+
if (e.code === "ENOENT") return { unavailable: true };
|
|
841
|
+
if (e.code === "ERR_INVALID_ARG_VALUE") {
|
|
842
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
843
|
+
return { ok: false, detail: `sh rejected the field (${message})` };
|
|
844
|
+
}
|
|
845
|
+
if (e.status == null) return { unavailable: true };
|
|
846
|
+
const stderr = typeof e.stderr === "string" ? e.stderr : "";
|
|
847
|
+
const line = stderr
|
|
848
|
+
.split("\n")
|
|
849
|
+
.map((candidate) => candidate.trim())
|
|
850
|
+
.find((candidate) => candidate.length > 0);
|
|
851
|
+
return { ok: false, detail: line ?? `sh exited ${String(e.status)}` };
|
|
759
852
|
}
|
|
760
853
|
}
|
|
761
854
|
|
|
855
|
+
/**
|
|
856
|
+
* The (c) instrument: a top-level decoration that makes the field more than
|
|
857
|
+
* the command, so the recorded exit cannot be attributed to what the field
|
|
858
|
+
* names: an unquoted `;` or newline (whatever follows owns the exit), a
|
|
859
|
+
* background `&` (the shell owns it), or a word-starting `#` (the field
|
|
860
|
+
* carries a comment). Quotes, command substitutions and redirections are
|
|
861
|
+
* shell syntax rather than decorations and are skipped, so `2>&1 | tail`,
|
|
862
|
+
* `cd x && npm run ci:check` and a quoted `';'` stay accepted. Returns the
|
|
863
|
+
* decoration found, or null when the field carries none.
|
|
864
|
+
*/
|
|
865
|
+
export function findTopLevelDecoration(cmd: string): string | null {
|
|
866
|
+
type Frame = "top" | "subst";
|
|
867
|
+
type Quote = "single" | "double" | "backtick";
|
|
868
|
+
const frames: Frame[] = ["top"];
|
|
869
|
+
let quote: Quote | null = null;
|
|
870
|
+
let wordStart = true;
|
|
871
|
+
|
|
872
|
+
for (let i = 0; i < cmd.length; i++) {
|
|
873
|
+
const ch = cmd[i];
|
|
874
|
+
const next = cmd[i + 1];
|
|
875
|
+
|
|
876
|
+
if (quote === "single") {
|
|
877
|
+
if (ch === "'") quote = null;
|
|
878
|
+
continue;
|
|
879
|
+
}
|
|
880
|
+
if (quote === "backtick") {
|
|
881
|
+
if (ch === "\\") i++;
|
|
882
|
+
else if (ch === "`") quote = null;
|
|
883
|
+
continue;
|
|
884
|
+
}
|
|
885
|
+
if (quote === "double") {
|
|
886
|
+
if (ch === "\\") i++;
|
|
887
|
+
else if (ch === '"') quote = null;
|
|
888
|
+
else if (ch === "$" && next === "(") {
|
|
889
|
+
frames.push("subst");
|
|
890
|
+
i++;
|
|
891
|
+
} else if (ch === "`") quote = "backtick";
|
|
892
|
+
continue;
|
|
893
|
+
}
|
|
894
|
+
|
|
895
|
+
// Unquoted: at the top level, or inside a command substitution.
|
|
896
|
+
if (ch === "\\") {
|
|
897
|
+
i++;
|
|
898
|
+
continue;
|
|
899
|
+
}
|
|
900
|
+
if (ch === "'") {
|
|
901
|
+
quote = "single";
|
|
902
|
+
wordStart = false;
|
|
903
|
+
continue;
|
|
904
|
+
}
|
|
905
|
+
if (ch === '"') {
|
|
906
|
+
quote = "double";
|
|
907
|
+
wordStart = false;
|
|
908
|
+
continue;
|
|
909
|
+
}
|
|
910
|
+
if (ch === "`") {
|
|
911
|
+
quote = "backtick";
|
|
912
|
+
wordStart = false;
|
|
913
|
+
continue;
|
|
914
|
+
}
|
|
915
|
+
if (ch === "$" && next === "(") {
|
|
916
|
+
frames.push("subst");
|
|
917
|
+
i++;
|
|
918
|
+
wordStart = false;
|
|
919
|
+
continue;
|
|
920
|
+
}
|
|
921
|
+
|
|
922
|
+
if (frames[frames.length - 1] === "subst") {
|
|
923
|
+
if (ch === "(") frames.push("subst");
|
|
924
|
+
else if (ch === ")") frames.pop();
|
|
925
|
+
continue;
|
|
926
|
+
}
|
|
927
|
+
|
|
928
|
+
if (ch === ";") return ";";
|
|
929
|
+
if (ch === "\n") return "newline";
|
|
930
|
+
if (ch === "#" && wordStart) return "comment";
|
|
931
|
+
if (ch === "&") {
|
|
932
|
+
const previous = cmd[i - 1];
|
|
933
|
+
const andAnd = next === "&";
|
|
934
|
+
const redirection = previous === ">" || previous === "<" || next === ">";
|
|
935
|
+
if (!andAnd && !redirection) return "&";
|
|
936
|
+
if (andAnd) i++;
|
|
937
|
+
wordStart = false;
|
|
938
|
+
continue;
|
|
939
|
+
}
|
|
940
|
+
wordStart = ch === " " || ch === "\t";
|
|
941
|
+
}
|
|
942
|
+
return null;
|
|
943
|
+
}
|
|
944
|
+
|
|
945
|
+
/**
|
|
946
|
+
* Run the four predicates over one recorded row and return the first
|
|
947
|
+
* violation, or null when the row is well formed. (a)/(b) need `sh`; when the
|
|
948
|
+
* shell cannot be spawned they are left unjudged (the string-only (c) and (d)
|
|
949
|
+
* still run), so a missing instrument cannot fail every row.
|
|
950
|
+
*/
|
|
951
|
+
export function findGateRowViolation(
|
|
952
|
+
cmd: string,
|
|
953
|
+
exit: number,
|
|
954
|
+
outcome: WorkerOutcome,
|
|
955
|
+
): GateRowViolation | null {
|
|
956
|
+
const parse = runShell(["-n", "-c", cmd]);
|
|
957
|
+
if ("ok" in parse && !parse.ok) {
|
|
958
|
+
return { predicate: "a", detail: `does not parse under sh -n (${parse.detail})` };
|
|
959
|
+
}
|
|
960
|
+
if ("ok" in parse) {
|
|
961
|
+
const token = firstCommandToken(cmd);
|
|
962
|
+
if (token === null) {
|
|
963
|
+
return { predicate: "b", detail: "no command token after the env prefixes" };
|
|
964
|
+
}
|
|
965
|
+
const resolved = runShell(["-c", 'command -v "$1" >/dev/null 2>&1', "sh", token]);
|
|
966
|
+
if ("ok" in resolved && !resolved.ok) {
|
|
967
|
+
return { predicate: "b", detail: `first token "${token}" does not resolve to an executable` };
|
|
968
|
+
}
|
|
969
|
+
}
|
|
970
|
+
const decoration = findTopLevelDecoration(cmd);
|
|
971
|
+
if (decoration !== null) {
|
|
972
|
+
return {
|
|
973
|
+
predicate: "c",
|
|
974
|
+
detail: `top-level ${decoration}: not the command alone`,
|
|
975
|
+
};
|
|
976
|
+
}
|
|
977
|
+
if (outcome === "completed" && exit !== 0) {
|
|
978
|
+
return { predicate: "d", detail: `exit ${exit} recorded under a completed outcome` };
|
|
979
|
+
}
|
|
980
|
+
return null;
|
|
981
|
+
}
|
|
982
|
+
|
|
983
|
+
/** Where close-gate refusals land: one JSONL line per failing row. */
|
|
984
|
+
export function closeGateRefusalLogPath(): string {
|
|
985
|
+
return join(braidDir(), "orchestrator", "close-gate-refusals.jsonl");
|
|
986
|
+
}
|
|
987
|
+
|
|
988
|
+
export interface CloseGateRefusalRecord {
|
|
989
|
+
at: string;
|
|
990
|
+
workerId: string;
|
|
991
|
+
/** Zero-based index into the close's gate evidence rows. */
|
|
992
|
+
row: number;
|
|
993
|
+
predicate: GateRowPredicate;
|
|
994
|
+
cmd: string;
|
|
995
|
+
mode: CloseGateWellFormednessMode;
|
|
996
|
+
outcome: WorkerOutcome;
|
|
997
|
+
detail: string;
|
|
998
|
+
}
|
|
999
|
+
|
|
1000
|
+
/** Warned once per process about an unwritable refusal log. */
|
|
1001
|
+
let _warnedRefusalLogFailure = false;
|
|
1002
|
+
|
|
1003
|
+
/**
|
|
1004
|
+
* Append one refusal line. Never throws: a failed append warns once and
|
|
1005
|
+
* leaves the close's own behavior untouched, so an unwritable braid root
|
|
1006
|
+
* cannot refuse a close that shadow mode would have accepted.
|
|
1007
|
+
*/
|
|
1008
|
+
export function logCloseGateRefusal(record: CloseGateRefusalRecord): void {
|
|
1009
|
+
try {
|
|
1010
|
+
const file = closeGateRefusalLogPath();
|
|
1011
|
+
mkdirSync(dirname(file), { recursive: true });
|
|
1012
|
+
appendFileSync(file, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
|
|
1013
|
+
} catch (error) {
|
|
1014
|
+
if (_warnedRefusalLogFailure) return;
|
|
1015
|
+
_warnedRefusalLogFailure = true;
|
|
1016
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
1017
|
+
log.warn(`close-gate refusal log not writable; refusals continue unlogged: ${message}`);
|
|
1018
|
+
}
|
|
1019
|
+
}
|
|
1020
|
+
|
|
1021
|
+
// ── Production writes (the close-side preflight read) ─────────────────────
|
|
1022
|
+
// A command that creates or mutates state visible outside the repo is a
|
|
1023
|
+
// production write, and a close that records one may not pass without a
|
|
1024
|
+
// preflight row: the credential's identity, the target registry or endpoint,
|
|
1025
|
+
// and a dry-run result, recorded as named pieces. The class is not this
|
|
1026
|
+
// module's knowledge; the seat that owns the vendor verbs publishes the table
|
|
1027
|
+
// as data (production-writes.json under the braid home's orchestrator
|
|
1028
|
+
// directory), and this reader is only the mechanism: member patterns decide
|
|
1029
|
+
// what is a write, piece patterns decide what the close recorded about it, and
|
|
1030
|
+
// the missing pieces are named from the data. A missing or unreadable data file
|
|
1031
|
+
// leaves the class empty and refuses nothing, deliberately: a false refusal is
|
|
1032
|
+
// the failure this read exists to avoid. Read-only verbs stay safe through the
|
|
1033
|
+
// member patterns themselves (the seat's whitelist pins them), and a field
|
|
1034
|
+
// carrying a write beside reads is still a write, because the members match the
|
|
1035
|
+
// write verbs only.
|
|
1036
|
+
|
|
1037
|
+
/** One named pattern in the production-write table, as the seat publishes it. */
|
|
1038
|
+
export interface ProductionWriteRule {
|
|
1039
|
+
id: string;
|
|
1040
|
+
label: string;
|
|
1041
|
+
pattern: string;
|
|
1042
|
+
/** Seat-side metadata (its guard prints this default); unread here. */
|
|
1043
|
+
registry?: string;
|
|
1044
|
+
}
|
|
1045
|
+
|
|
1046
|
+
/** The seat-owned table: what is a write, and what a preflight records. */
|
|
1047
|
+
export interface ProductionWriteClass {
|
|
1048
|
+
members: ProductionWriteRule[];
|
|
1049
|
+
pieces: ProductionWriteRule[];
|
|
1050
|
+
}
|
|
1051
|
+
|
|
1052
|
+
/** One write row and what the close recorded for it. */
|
|
1053
|
+
export interface ProductionWriteRowRead {
|
|
1054
|
+
row: number;
|
|
1055
|
+
cmd: string;
|
|
1056
|
+
member: string;
|
|
1057
|
+
/** Indices of the rows carrying at least one preflight piece. */
|
|
1058
|
+
preflightRows: number[];
|
|
1059
|
+
/** Piece ids no row in the close carries. */
|
|
1060
|
+
missingPieces: string[];
|
|
1061
|
+
}
|
|
1062
|
+
|
|
1063
|
+
export interface ProductionWriteRead {
|
|
1064
|
+
rows: ProductionWriteRowRead[];
|
|
1065
|
+
/** The write rows still missing at least one piece; the first one refuses. */
|
|
1066
|
+
unsatisfied: ProductionWriteRowRead[];
|
|
1067
|
+
}
|
|
1068
|
+
|
|
1069
|
+
/** Where the seat publishes the production-write class it owns. */
|
|
1070
|
+
export function productionWriteClassPath(): string {
|
|
1071
|
+
return join(braidDir(), "orchestrator", "production-writes.json");
|
|
1072
|
+
}
|
|
1073
|
+
|
|
1074
|
+
/** Warned once per process about an unreadable class file. */
|
|
1075
|
+
let _warnedProductionWriteClass = false;
|
|
1076
|
+
|
|
1077
|
+
function warnProductionWriteClass(detail: string): void {
|
|
1078
|
+
if (_warnedProductionWriteClass) return;
|
|
1079
|
+
_warnedProductionWriteClass = true;
|
|
1080
|
+
log.warn(
|
|
1081
|
+
`production-write class not read (${detail}); closes are not refused for recorded writes`,
|
|
1082
|
+
);
|
|
1083
|
+
}
|
|
1084
|
+
|
|
1085
|
+
/**
|
|
1086
|
+
* Read one array of rules out of the class table, keeping only entries a reader
|
|
1087
|
+
* can use: a non-empty id, a non-empty pattern that compiles, and a label
|
|
1088
|
+
* (falling back to the id). Junk entries are dropped rather than thrown: the
|
|
1089
|
+
* file is seat-edited data, and an unusable one must fail open.
|
|
1090
|
+
*/
|
|
1091
|
+
function readRuleList(raw: unknown): ProductionWriteRule[] {
|
|
1092
|
+
if (!Array.isArray(raw)) return [];
|
|
1093
|
+
const rules: ProductionWriteRule[] = [];
|
|
1094
|
+
for (const entry of raw) {
|
|
1095
|
+
if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
|
|
1096
|
+
const { id, label, pattern, registry } = entry as {
|
|
1097
|
+
id?: unknown;
|
|
1098
|
+
label?: unknown;
|
|
1099
|
+
pattern?: unknown;
|
|
1100
|
+
registry?: unknown;
|
|
1101
|
+
};
|
|
1102
|
+
if (typeof id !== "string" || id.trim() === "") continue;
|
|
1103
|
+
if (typeof pattern !== "string" || pattern === "") continue;
|
|
1104
|
+
try {
|
|
1105
|
+
new RegExp(pattern);
|
|
1106
|
+
} catch {
|
|
1107
|
+
continue;
|
|
1108
|
+
}
|
|
1109
|
+
rules.push({
|
|
1110
|
+
id,
|
|
1111
|
+
label: typeof label === "string" && label !== "" ? label : id,
|
|
1112
|
+
pattern,
|
|
1113
|
+
...(typeof registry === "string" ? { registry } : {}),
|
|
1114
|
+
});
|
|
1115
|
+
}
|
|
1116
|
+
return rules;
|
|
1117
|
+
}
|
|
1118
|
+
|
|
1119
|
+
/**
|
|
1120
|
+
* Load the class table the seat owns. Never throws: a braid home that cannot be
|
|
1121
|
+
* resolved, a missing file, an unreadable file and a malformed one all yield an
|
|
1122
|
+
* empty class, which refuses nothing.
|
|
1123
|
+
*/
|
|
1124
|
+
export function readProductionWriteClass(file?: string): ProductionWriteClass {
|
|
1125
|
+
const empty: ProductionWriteClass = { members: [], pieces: [] };
|
|
1126
|
+
let path: string;
|
|
1127
|
+
try {
|
|
1128
|
+
path = file ?? productionWriteClassPath();
|
|
1129
|
+
} catch (error) {
|
|
1130
|
+
warnProductionWriteClass(error instanceof Error ? error.message : String(error));
|
|
1131
|
+
return empty;
|
|
1132
|
+
}
|
|
1133
|
+
let parsed: unknown;
|
|
1134
|
+
try {
|
|
1135
|
+
parsed = JSON.parse(readFileSync(path, "utf-8"));
|
|
1136
|
+
} catch (error) {
|
|
1137
|
+
const code = (error as { code?: unknown }).code;
|
|
1138
|
+
if (code !== "ENOENT") {
|
|
1139
|
+
warnProductionWriteClass(
|
|
1140
|
+
`${path}: ${error instanceof Error ? error.message : String(error)}`,
|
|
1141
|
+
);
|
|
1142
|
+
}
|
|
1143
|
+
return empty;
|
|
1144
|
+
}
|
|
1145
|
+
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
|
|
1146
|
+
warnProductionWriteClass(`${path}: top level is not an object`);
|
|
1147
|
+
return empty;
|
|
1148
|
+
}
|
|
1149
|
+
const table = parsed as { members?: unknown; preflight?: unknown };
|
|
1150
|
+
const pieces = (table.preflight as { pieces?: unknown } | null | undefined)?.pieces;
|
|
1151
|
+
return { members: readRuleList(table.members), pieces: readRuleList(pieces) };
|
|
1152
|
+
}
|
|
1153
|
+
|
|
1154
|
+
/** Compile a rule list, dropping any pattern that does not compile. */
|
|
1155
|
+
function compileProductionWriteRules(
|
|
1156
|
+
rules: ProductionWriteRule[],
|
|
1157
|
+
): Array<{ rule: ProductionWriteRule; re: RegExp }> {
|
|
1158
|
+
const compiled: Array<{ rule: ProductionWriteRule; re: RegExp }> = [];
|
|
1159
|
+
for (const rule of rules) {
|
|
1160
|
+
try {
|
|
1161
|
+
compiled.push({ rule, re: new RegExp(rule.pattern) });
|
|
1162
|
+
} catch {
|
|
1163
|
+
// readRuleList already dropped these; a caller-supplied table may not have.
|
|
1164
|
+
}
|
|
1165
|
+
}
|
|
1166
|
+
return compiled;
|
|
1167
|
+
}
|
|
1168
|
+
|
|
1169
|
+
/**
|
|
1170
|
+
* Read a close's gate rows for production writes and their preflight evidence.
|
|
1171
|
+
* A row is a write when any member pattern matches its cmd — a field carrying a
|
|
1172
|
+
* write beside reads is still a write, because the members match the write
|
|
1173
|
+
* verbs only. A piece is recorded when any row's cmd matches its pattern, so
|
|
1174
|
+
* one composed preflight row and several separate ones both satisfy. Pure over
|
|
1175
|
+
* the rows and the table.
|
|
1176
|
+
*/
|
|
1177
|
+
export function readProductionWrites(
|
|
1178
|
+
rows: Array<{ cmd: string; exit: number; stamp?: string }> | undefined,
|
|
1179
|
+
table: ProductionWriteClass = readProductionWriteClass(),
|
|
1180
|
+
): ProductionWriteRead {
|
|
1181
|
+
if (!rows || rows.length === 0) return { rows: [], unsatisfied: [] };
|
|
1182
|
+
const members = compileProductionWriteRules(table.members);
|
|
1183
|
+
const pieces = compileProductionWriteRules(table.pieces);
|
|
1184
|
+
if (members.length === 0) return { rows: [], unsatisfied: [] };
|
|
1185
|
+
|
|
1186
|
+
const cmdAt = (row: { cmd?: unknown } | undefined): string =>
|
|
1187
|
+
typeof row?.cmd === "string" ? row.cmd : "";
|
|
1188
|
+
const writes: ProductionWriteRowRead[] = [];
|
|
1189
|
+
for (let i = 0; i < rows.length; i++) {
|
|
1190
|
+
const cmd = cmdAt(rows[i]);
|
|
1191
|
+
const member = members.find(({ re }) => re.test(cmd));
|
|
1192
|
+
if (!member) continue;
|
|
1193
|
+
const missing: string[] = [];
|
|
1194
|
+
const preflightRows = new Set<number>();
|
|
1195
|
+
for (const piece of pieces) {
|
|
1196
|
+
let recorded = false;
|
|
1197
|
+
for (let j = 0; j < rows.length; j++) {
|
|
1198
|
+
if (piece.re.test(cmdAt(rows[j]))) {
|
|
1199
|
+
recorded = true;
|
|
1200
|
+
preflightRows.add(j);
|
|
1201
|
+
}
|
|
1202
|
+
}
|
|
1203
|
+
if (!recorded) missing.push(piece.rule.id);
|
|
1204
|
+
}
|
|
1205
|
+
writes.push({
|
|
1206
|
+
row: i,
|
|
1207
|
+
cmd,
|
|
1208
|
+
member: member.rule.id,
|
|
1209
|
+
preflightRows: [...preflightRows].sort((a, b) => a - b),
|
|
1210
|
+
missingPieces: missing,
|
|
1211
|
+
});
|
|
1212
|
+
}
|
|
1213
|
+
return { rows: writes, unsatisfied: writes.filter((row) => row.missingPieces.length > 0) };
|
|
1214
|
+
}
|
|
1215
|
+
|
|
1216
|
+
/**
|
|
1217
|
+
* The refusal sentence for the first write row missing a piece: its index, the
|
|
1218
|
+
* member, the missing piece ids and the command. Null when every write row is
|
|
1219
|
+
* satisfied, so a caller cannot refuse on an empty read.
|
|
1220
|
+
*/
|
|
1221
|
+
export function productionWriteRefusalDetail(read: ProductionWriteRead): string | null {
|
|
1222
|
+
const row = read.unsatisfied[0];
|
|
1223
|
+
if (!row) return null;
|
|
1224
|
+
return (
|
|
1225
|
+
`gates[${row.row}] records a production write ("${row.member}") without a complete ` +
|
|
1226
|
+
`preflight row: missing pieces: ${row.missingPieces.join(", ")}; cmd: ${row.cmd}`
|
|
1227
|
+
);
|
|
1228
|
+
}
|
|
1229
|
+
|
|
1230
|
+
// ── Population stamps (the merge-side census read) ────────────────────────
|
|
1231
|
+
// A gate whose subject is a population of files or rows may record what it
|
|
1232
|
+
// scanned, and at which revision, as an optional `stamp` on its evidence row:
|
|
1233
|
+
//
|
|
1234
|
+
// scanned <n> <unit> at <revision>
|
|
1235
|
+
//
|
|
1236
|
+
// `n` is a non-negative integer, `unit` one lowercase word (`files`, `rows`,
|
|
1237
|
+
// ...), and `revision` a 7-to-40-char hex sha or a ref name. The stamp is the
|
|
1238
|
+
// reporter's own claim, so it is worth exactly what one comparison against git
|
|
1239
|
+
// makes it worth: the merge path resolves the named revision, counts the
|
|
1240
|
+
// entries that revision's tree holds, and refuses the merge when the recorded
|
|
1241
|
+
// number sits below that census (a scan that ran before staging, certifying
|
|
1242
|
+
// fewer tracked entries than the commit carries). The parse and the comparison
|
|
1243
|
+
// are pure, with the count supplied by the caller; nothing here reads what the
|
|
1244
|
+
// scanned files mean.
|
|
1245
|
+
|
|
1246
|
+
export interface PopulationStamp {
|
|
1247
|
+
/** Population size the gate recorded. */
|
|
1248
|
+
n: number;
|
|
1249
|
+
/** The population's unit, one lowercase word. */
|
|
1250
|
+
unit: string;
|
|
1251
|
+
/** Commit sha or ref name the gate read. */
|
|
1252
|
+
revision: string;
|
|
1253
|
+
}
|
|
1254
|
+
|
|
1255
|
+
/**
|
|
1256
|
+
* Bare-token revision rules: an all-hex token is a sha only at 7-40 chars, so
|
|
1257
|
+
* a six-char prefix does not slip through the ref-name alternative as a
|
|
1258
|
+
* revision git can never resolve.
|
|
1259
|
+
*/
|
|
1260
|
+
const POPULATION_STAMP_RE =
|
|
1261
|
+
/^scanned (\d+) ([a-z]+) at ([0-9a-fA-F]{7,40}|[A-Za-z0-9][A-Za-z0-9._/-]*)$/;
|
|
1262
|
+
const ALL_HEX_RE = /^[0-9a-fA-F]+$/;
|
|
1263
|
+
|
|
1264
|
+
/** Parse the stamp shape above; null when the value is not that shape. */
|
|
1265
|
+
export function parsePopulationStamp(value: unknown): PopulationStamp | null {
|
|
1266
|
+
if (typeof value !== "string") return null;
|
|
1267
|
+
const match = POPULATION_STAMP_RE.exec(value);
|
|
1268
|
+
if (!match) return null;
|
|
1269
|
+
const [, rawN, unit, revision] = match;
|
|
1270
|
+
if (ALL_HEX_RE.test(revision) && (revision.length < 7 || revision.length > 40)) return null;
|
|
1271
|
+
return { n: Number(rawN), unit, revision };
|
|
1272
|
+
}
|
|
1273
|
+
|
|
1274
|
+
/** What one gate row's stamp read decided. */
|
|
1275
|
+
export type PopulationVerdict =
|
|
1276
|
+
| "absent"
|
|
1277
|
+
| "unreadable"
|
|
1278
|
+
| "other-subject"
|
|
1279
|
+
| "unresolved"
|
|
1280
|
+
| "match"
|
|
1281
|
+
| "below"
|
|
1282
|
+
| "above";
|
|
1283
|
+
|
|
1284
|
+
export interface PopulationRowRead {
|
|
1285
|
+
/** Zero-based index into the close's gate rows. */
|
|
1286
|
+
row: number;
|
|
1287
|
+
/** The row's command, as recorded (empty when the row carries none). */
|
|
1288
|
+
cmd: string;
|
|
1289
|
+
/** The raw stamp value, as recorded; undefined when the field is absent. */
|
|
1290
|
+
raw: unknown;
|
|
1291
|
+
/** True when the row carries a stamp field at all (even an unreadable one). */
|
|
1292
|
+
present: boolean;
|
|
1293
|
+
/** The parsed stamp, or null when absent or unreadable. */
|
|
1294
|
+
stamp: PopulationStamp | null;
|
|
1295
|
+
/** The census at the stamp's revision, or null when not compared. */
|
|
1296
|
+
census: number | null;
|
|
1297
|
+
/** `census - recorded`, or null when there is no comparison. */
|
|
1298
|
+
delta: number | null;
|
|
1299
|
+
verdict: PopulationVerdict;
|
|
1300
|
+
}
|
|
1301
|
+
|
|
1302
|
+
export interface PopulationRead {
|
|
1303
|
+
rows: PopulationRowRead[];
|
|
1304
|
+
/** Rows whose unit is `files` and whose revision resolved (the comparisons). */
|
|
1305
|
+
comparisons: PopulationRowRead[];
|
|
1306
|
+
/** The first comparison recorded below its census; null when none stands. */
|
|
1307
|
+
standing: PopulationRowRead | null;
|
|
1308
|
+
/** True when any row carries a parseable `files` stamp. */
|
|
1309
|
+
recorded: boolean;
|
|
1310
|
+
/** The report lines, one per readable row, in row order. */
|
|
1311
|
+
lines: string[];
|
|
1312
|
+
}
|
|
1313
|
+
|
|
1314
|
+
/** The census lookup the caller supplies: revision to tree size, or null. */
|
|
1315
|
+
export type PopulationCensus = (revision: string) => number | null;
|
|
1316
|
+
|
|
1317
|
+
function populationLines(rows: PopulationRowRead[]): string[] {
|
|
1318
|
+
const lines: string[] = [];
|
|
1319
|
+
for (const row of rows) {
|
|
1320
|
+
if (row.verdict === "unreadable") {
|
|
1321
|
+
lines.push(`population stamp unreadable: row ${row.row} ${JSON.stringify(row.raw)}`);
|
|
1322
|
+
continue;
|
|
1323
|
+
}
|
|
1324
|
+
if (row.stamp === null || row.stamp.unit !== "files") continue;
|
|
1325
|
+
if (row.verdict === "unresolved") {
|
|
1326
|
+
lines.push(
|
|
1327
|
+
`population delta: recorded ${row.stamp.n} at ${row.stamp.revision} ` +
|
|
1328
|
+
`(row ${row.row}; revision unresolved, not compared)`,
|
|
1329
|
+
);
|
|
1330
|
+
} else if (row.census !== null) {
|
|
1331
|
+
lines.push(
|
|
1332
|
+
`population delta: recorded ${row.stamp.n} vs census ${row.census} at ` +
|
|
1333
|
+
`${row.stamp.revision} (row ${row.row})`,
|
|
1334
|
+
);
|
|
1335
|
+
}
|
|
1336
|
+
}
|
|
1337
|
+
if (!rows.some((row) => row.stamp !== null && row.stamp.unit === "files")) {
|
|
1338
|
+
lines.push("no recorded population");
|
|
1339
|
+
}
|
|
1340
|
+
return lines;
|
|
1341
|
+
}
|
|
1342
|
+
|
|
1343
|
+
/**
|
|
1344
|
+
* Read every gate row for a population stamp and compare the `files` ones
|
|
1345
|
+
* against the census the caller supplies for their named revision. Pure: the
|
|
1346
|
+
* count is a lookup parameter, so the parse and the comparison are testable
|
|
1347
|
+
* without a repository. Rows of another unit are not census subjects and are
|
|
1348
|
+
* left uncompared; an unreadable stamp is named, never silently dropped.
|
|
1349
|
+
*/
|
|
1350
|
+
export function readPopulationStamps(gates: unknown, censusAt: PopulationCensus): PopulationRead {
|
|
1351
|
+
const rows: PopulationRowRead[] = [];
|
|
1352
|
+
const list = Array.isArray(gates) ? gates : [];
|
|
1353
|
+
for (let i = 0; i < list.length; i++) {
|
|
1354
|
+
const gate: unknown = list[i];
|
|
1355
|
+
const record =
|
|
1356
|
+
gate && typeof gate === "object" && !Array.isArray(gate)
|
|
1357
|
+
? (gate as Record<string, unknown>)
|
|
1358
|
+
: null;
|
|
1359
|
+
const cmd = typeof record?.cmd === "string" ? record.cmd : "";
|
|
1360
|
+
const present = record !== null && record.stamp !== undefined;
|
|
1361
|
+
const raw: unknown = present ? record.stamp : undefined;
|
|
1362
|
+
const stamp = present ? parsePopulationStamp(raw) : null;
|
|
1363
|
+
|
|
1364
|
+
let census: number | null = null;
|
|
1365
|
+
let delta: number | null = null;
|
|
1366
|
+
let verdict: PopulationVerdict;
|
|
1367
|
+
if (!present) verdict = "absent";
|
|
1368
|
+
else if (stamp === null) verdict = "unreadable";
|
|
1369
|
+
else if (stamp.unit !== "files") verdict = "other-subject";
|
|
1370
|
+
else {
|
|
1371
|
+
census = censusAt(stamp.revision);
|
|
1372
|
+
if (census === null) verdict = "unresolved";
|
|
1373
|
+
else {
|
|
1374
|
+
delta = census - stamp.n;
|
|
1375
|
+
verdict = delta === 0 ? "match" : delta > 0 ? "below" : "above";
|
|
1376
|
+
}
|
|
1377
|
+
}
|
|
1378
|
+
rows.push({ row: i, cmd, raw, present, stamp, census, delta, verdict });
|
|
1379
|
+
}
|
|
1380
|
+
|
|
1381
|
+
return {
|
|
1382
|
+
rows,
|
|
1383
|
+
comparisons: rows.filter((row) => row.stamp !== null && row.census !== null),
|
|
1384
|
+
standing: rows.find((row) => row.verdict === "below") ?? null,
|
|
1385
|
+
recorded: rows.some((row) => row.stamp !== null && row.stamp.unit === "files"),
|
|
1386
|
+
lines: populationLines(rows),
|
|
1387
|
+
};
|
|
1388
|
+
}
|
|
1389
|
+
|
|
1390
|
+
/**
|
|
1391
|
+
* The refusal sentence for the first standing delta: row index, stamp, census,
|
|
1392
|
+
* delta, and the remedy. Null when no comparison sits below its census, so a
|
|
1393
|
+
* caller cannot refuse on an empty read.
|
|
1394
|
+
*/
|
|
1395
|
+
export function populationRefusalDetail(read: PopulationRead): string | null {
|
|
1396
|
+
const row = read.standing;
|
|
1397
|
+
if (!row || row.stamp === null || row.census === null || row.delta === null) return null;
|
|
1398
|
+
return (
|
|
1399
|
+
`row ${row.row} stamp "scanned ${row.stamp.n} ${row.stamp.unit} at ${row.stamp.revision}" ` +
|
|
1400
|
+
`records ${row.stamp.n} but the census at ${row.stamp.revision} is ${row.census} ` +
|
|
1401
|
+
`(delta ${row.delta}); re-run the gate on the staged tree and re-issue the close`
|
|
1402
|
+
);
|
|
1403
|
+
}
|
|
1404
|
+
|
|
762
1405
|
/**
|
|
763
1406
|
* Close an entry with a terminal outcome and optional gate evidence.
|
|
764
1407
|
* Already-closed entries are left untouched (first close wins); the checks
|
|
@@ -768,8 +1411,24 @@ function assertGateEvidence(
|
|
|
768
1411
|
* A completed close carries evidence: the reporter contract requires a
|
|
769
1412
|
* non-empty `gate_evidence` block, and a probe measured this path storing a
|
|
770
1413
|
* bare `completed` with no gates at all. That contradiction is refused now,
|
|
771
|
-
* and each provided gate is shape-checked (non-empty `cmd`, numeric `exit
|
|
772
|
-
* before any write — a violation leaves the row
|
|
1414
|
+
* and each provided gate is shape-checked (non-empty `cmd`, numeric `exit`,
|
|
1415
|
+
* string `stamp` when present) before any write — a violation leaves the row
|
|
1416
|
+
* and the lock table untouched. A valid `stamp` is stored verbatim, so the
|
|
1417
|
+
* merge path can read the recorded population off the row.
|
|
1418
|
+
*
|
|
1419
|
+
* Every provided row is then read for well-formedness: its `cmd` must parse
|
|
1420
|
+
* under `sh -n`, resolve its first token, and name the command alone, and a
|
|
1421
|
+
* completed close's exits must be 0. The mode is settings-driven
|
|
1422
|
+
* (`braid.orchestrator.closeGateWellFormedness`): "shadow" (default) records
|
|
1423
|
+
* a refusal line and proceeds, "enforce" refuses before any write or lock
|
|
1424
|
+
* release, "off" skips the read. No gate is re-run; replay stays the
|
|
1425
|
+
* sampler's sampled job.
|
|
1426
|
+
*
|
|
1427
|
+
* Every row is also read against the seat's production-write class: a row the
|
|
1428
|
+
* class marks as a write is refused unless the close records every named
|
|
1429
|
+
* preflight piece (identity, registry, dry-run) somewhere in its rows. The
|
|
1430
|
+
* class lives in the seat's data file; when it is absent the class is empty and
|
|
1431
|
+
* nothing is refused.
|
|
773
1432
|
*
|
|
774
1433
|
* Releases the worker's file locks: close is terminal, and a lock that
|
|
775
1434
|
* survives it blocks the next spawn on the same files. The release runs with
|
|
@@ -779,7 +1438,7 @@ function assertGateEvidence(
|
|
|
779
1438
|
export function closeWorker(
|
|
780
1439
|
workerId: string,
|
|
781
1440
|
outcome: WorkerOutcome,
|
|
782
|
-
gates?: Array<{ cmd: string; exit: number }>,
|
|
1441
|
+
gates?: Array<{ cmd: string; exit: number; stamp?: string }>,
|
|
783
1442
|
cwd?: string,
|
|
784
1443
|
): WorkerEntry | null {
|
|
785
1444
|
const parsed = parseWorkerOutcome(outcome);
|
|
@@ -790,6 +1449,40 @@ export function closeWorker(
|
|
|
790
1449
|
|
|
791
1450
|
assertGateEvidence(workerId, parsed, gates);
|
|
792
1451
|
|
|
1452
|
+
const wellFormedness = getCloseGateWellFormedness();
|
|
1453
|
+
if (wellFormedness.mode !== "off" && gates && gates.length > 0) {
|
|
1454
|
+
for (let i = 0; i < gates.length; i++) {
|
|
1455
|
+
const violation = findGateRowViolation(gates[i].cmd, gates[i].exit, parsed);
|
|
1456
|
+
if (!violation) continue;
|
|
1457
|
+
logCloseGateRefusal({
|
|
1458
|
+
at: new Date().toISOString(),
|
|
1459
|
+
workerId,
|
|
1460
|
+
row: i,
|
|
1461
|
+
predicate: violation.predicate,
|
|
1462
|
+
cmd: gates[i].cmd,
|
|
1463
|
+
mode: wellFormedness.mode,
|
|
1464
|
+
outcome: parsed,
|
|
1465
|
+
detail: violation.detail,
|
|
1466
|
+
});
|
|
1467
|
+
if (wellFormedness.mode === "enforce") {
|
|
1468
|
+
throw new Error(
|
|
1469
|
+
`closeWorker: gates[${i}] fails predicate (${violation.predicate}): ${violation.detail}; ` +
|
|
1470
|
+
`cmd: ${gates[i].cmd} (worker ${workerId}, outcome ${parsed})`,
|
|
1471
|
+
);
|
|
1472
|
+
}
|
|
1473
|
+
}
|
|
1474
|
+
}
|
|
1475
|
+
|
|
1476
|
+
// A recorded production write must carry its preflight evidence. The class
|
|
1477
|
+
// table is the seat's data, and an absent one reads as empty (fail-open), so
|
|
1478
|
+
// this refuses only what the seat has declared a write without its pieces.
|
|
1479
|
+
const productionRefusal = productionWriteRefusalDetail(
|
|
1480
|
+
readProductionWrites(gates, readProductionWriteClass()),
|
|
1481
|
+
);
|
|
1482
|
+
if (productionRefusal) {
|
|
1483
|
+
throw new Error(`closeWorker: ${productionRefusal} (worker ${workerId}, outcome ${parsed})`);
|
|
1484
|
+
}
|
|
1485
|
+
|
|
793
1486
|
releaseLock(workerId, located.key);
|
|
794
1487
|
|
|
795
1488
|
const nowIso = new Date().toISOString();
|
|
@@ -799,7 +1492,12 @@ export function closeWorker(
|
|
|
799
1492
|
if (parsed === "completed" && !entry.resultAt) entry.resultAt = nowIso;
|
|
800
1493
|
if (gates && gates.length > 0) {
|
|
801
1494
|
for (const gate of gates) {
|
|
802
|
-
entry.gates.push({
|
|
1495
|
+
entry.gates.push({
|
|
1496
|
+
cmd: gate.cmd,
|
|
1497
|
+
exit: gate.exit,
|
|
1498
|
+
at: nowIso,
|
|
1499
|
+
...(gate.stamp === undefined ? {} : { stamp: gate.stamp }),
|
|
1500
|
+
});
|
|
803
1501
|
}
|
|
804
1502
|
}
|
|
805
1503
|
|