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.
Files changed (105) hide show
  1. package/CONTRIBUTING.md +27 -3
  2. package/README.md +13 -13
  3. package/TOOLS.md +27 -3
  4. package/build-info.json +9 -0
  5. package/dist/extensions/cognitive/metacognition/handlers/claim-verification.js +7 -1
  6. package/dist/extensions/cognitive/metacognition/handlers/finalize.js +20 -0
  7. package/dist/extensions/cognitive/metacognition/handlers/hypothesize.d.ts +9 -0
  8. package/dist/extensions/cognitive/metacognition/handlers/hypothesize.js +13 -1
  9. package/dist/extensions/cognitive/metacognition/handlers/verify.js +35 -4
  10. package/dist/extensions/cognitive/topic-drift/index.js +19 -2
  11. package/dist/extensions/core/prompt-builder/inspect.js +9 -3
  12. package/dist/extensions/core/prompt-builder/top-level-extensions.d.ts +6 -5
  13. package/dist/extensions/core/prompt-builder/top-level-extensions.js +64 -29
  14. package/dist/extensions/enforcement/handlers/register-tool-result-formatting.d.ts +1 -1
  15. package/dist/extensions/enforcement/handlers/register-tool-result-formatting.js +1 -1
  16. package/dist/extensions/enforcement/handlers/turn-end-handler.js +1 -1
  17. package/dist/extensions/enforcement/self-state-claims.d.ts +1 -1
  18. package/dist/extensions/enforcement/self-state-claims.js +3 -2
  19. package/dist/extensions/manifest.js +2 -2
  20. package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.d.ts +22 -5
  21. package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.js +43 -11
  22. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +174 -50
  23. package/dist/extensions/memory/context-manager/handlers/tools/context-inspect.js +7 -1
  24. package/dist/extensions/memory/context-manager/handlers/tools/context-navigate.js +4 -1
  25. package/dist/extensions/memory/memory-agent-bridge/explore-paths.d.ts +2 -24
  26. package/dist/extensions/memory/memory-agent-bridge/explore-paths.js +33 -2
  27. package/dist/extensions/memory/memory-agent-bridge/memory-store-tool.js +16 -0
  28. package/dist/extensions/memory/memory-agent-bridge/memory-tool.js +21 -9
  29. package/dist/extensions/memory/scratchpad/format.js +8 -2
  30. package/dist/extensions/memory/scratchpad/index.js +11 -2
  31. package/dist/extensions/memory/session-recall/index.js +19 -6
  32. package/dist/extensions/memory/three-memory-stores/episodes.d.ts +1 -1
  33. package/dist/extensions/memory/three-memory-stores/episodes.js +2 -2
  34. package/dist/extensions/orchestrator/index.js +73 -8
  35. package/dist/extensions/scheduling/timer/index.js +9 -1
  36. package/dist/extensions/self/error-tracking/index.js +8 -1
  37. package/dist/extensions/self/health-maintenance/handlers/session-health-tool.js +9 -2
  38. package/dist/extensions/self/health-maintenance/index.js +112 -9
  39. package/dist/lib/config/braid-settings.d.ts +21 -0
  40. package/dist/lib/config/braid-settings.js +36 -0
  41. package/dist/lib/constants/session-thresholds.d.ts +2 -3
  42. package/dist/lib/constants/session-thresholds.js +2 -3
  43. package/dist/lib/enforcement/turn-dedup.d.ts +2 -2
  44. package/dist/lib/enforcement/turn-dedup.js +2 -2
  45. package/dist/lib/harness/index.d.ts +1 -1
  46. package/dist/lib/harness/index.js +1 -1
  47. package/dist/lib/harness/types.d.ts +1 -1
  48. package/dist/lib/harness/types.js +1 -1
  49. package/dist/lib/orchestrator/index.d.ts +2 -2
  50. package/dist/lib/orchestrator/index.js +1 -1
  51. package/dist/lib/orchestrator/workers.d.ts +184 -2
  52. package/dist/lib/orchestrator/workers.js +521 -6
  53. package/dist/lib/utils/injection-tracker.js +1 -1
  54. package/docs/CONTEXT-POLICY.md +13 -5
  55. package/docs/LOCAL_DEV.md +31 -5
  56. package/docs/ROADMAP.md +10 -7
  57. package/docs/SETUP.md +3 -2
  58. package/package.json +11 -8
  59. package/skills/braid-reference/SKILL.md +23 -23
  60. package/skills/release-pipeline/SKILL.md +46 -37
  61. package/skills/subagent-orchestration/SKILL.md +51 -1
  62. package/src/extensions/cognitive/metacognition/handlers/claim-verification.ts +8 -1
  63. package/src/extensions/cognitive/metacognition/handlers/finalize.ts +21 -0
  64. package/src/extensions/cognitive/metacognition/handlers/hypothesize.ts +14 -1
  65. package/src/extensions/cognitive/metacognition/handlers/verify.ts +39 -5
  66. package/src/extensions/cognitive/topic-drift/index.ts +20 -2
  67. package/src/extensions/core/prompt-builder/AGENTS.md +1 -1
  68. package/src/extensions/core/prompt-builder/inspect.ts +10 -3
  69. package/src/extensions/core/prompt-builder/top-level-extensions.ts +68 -29
  70. package/src/extensions/enforcement/AGENTS.md +25 -19
  71. package/src/extensions/enforcement/handlers/register-tool-result-formatting.ts +1 -1
  72. package/src/extensions/enforcement/handlers/turn-end-handler.ts +1 -1
  73. package/src/extensions/enforcement/self-state-claims.ts +3 -2
  74. package/src/extensions/heartbeat/heartbeat-scheduler/AGENTS.md +6 -3
  75. package/src/extensions/manifest.ts +2 -2
  76. package/src/extensions/memory/AGENTS.md +13 -5
  77. package/src/extensions/memory/context-manager/handlers/tool-batch-boundary.ts +45 -11
  78. package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +202 -60
  79. package/src/extensions/memory/context-manager/handlers/tools/context-inspect.ts +8 -1
  80. package/src/extensions/memory/context-manager/handlers/tools/context-navigate.ts +4 -1
  81. package/src/extensions/memory/memory-agent-bridge/explore-paths.ts +37 -3
  82. package/src/extensions/memory/memory-agent-bridge/memory-store-tool.ts +16 -0
  83. package/src/extensions/memory/memory-agent-bridge/memory-tool.ts +22 -9
  84. package/src/extensions/memory/scratchpad/format.ts +8 -2
  85. package/src/extensions/memory/scratchpad/index.ts +12 -2
  86. package/src/extensions/memory/session-recall/index.ts +20 -8
  87. package/src/extensions/memory/three-memory-stores/episodes.ts +2 -2
  88. package/src/extensions/orchestrator/index.ts +100 -11
  89. package/src/extensions/scheduling/timer/AGENTS.md +7 -0
  90. package/src/extensions/scheduling/timer/index.ts +10 -1
  91. package/src/extensions/self/error-tracking/index.ts +9 -1
  92. package/src/extensions/self/health-maintenance/handlers/session-health-tool.ts +10 -2
  93. package/src/extensions/self/health-maintenance/index.ts +143 -14
  94. package/src/extensions/self/watchdog/AGENTS.md +1 -0
  95. package/src/lib/AGENTS.md +21 -21
  96. package/src/lib/config/braid-settings.ts +74 -0
  97. package/src/lib/constants/session-thresholds.ts +2 -3
  98. package/src/lib/enforcement/turn-dedup.ts +2 -2
  99. package/src/lib/harness/AGENTS.md +1 -1
  100. package/src/lib/harness/index.ts +1 -1
  101. package/src/lib/harness/types.ts +1 -1
  102. package/src/lib/orchestrator/index.ts +26 -0
  103. package/src/lib/orchestrator/workers.ts +705 -7
  104. package/src/lib/utils/AGENTS.md +1 -1
  105. 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 and the lock table untouched.
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({ cmd: gate.cmd, exit: gate.exit, at: nowIso });
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