audit-tools 0.55.5 → 0.55.6

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 (166) hide show
  1. package/dist/audit/cli/auditStep.d.ts +15 -1
  2. package/dist/audit/cli/auditStep.d.ts.map +1 -1
  3. package/dist/audit/cli/auditStep.js +24 -11
  4. package/dist/audit/cli/auditStep.js.map +1 -1
  5. package/dist/audit/cli/cleanup.d.ts.map +1 -1
  6. package/dist/audit/cli/cleanup.js +26 -2
  7. package/dist/audit/cli/cleanup.js.map +1 -1
  8. package/dist/audit/cli/conceptualDispatch.d.ts +2 -0
  9. package/dist/audit/cli/conceptualDispatch.d.ts.map +1 -1
  10. package/dist/audit/cli/conceptualDispatch.js +29 -8
  11. package/dist/audit/cli/conceptualDispatch.js.map +1 -1
  12. package/dist/audit/cli/dispatch/hostHandoff.d.ts +37 -3
  13. package/dist/audit/cli/dispatch/hostHandoff.d.ts.map +1 -1
  14. package/dist/audit/cli/dispatch/hostHandoff.js +185 -16
  15. package/dist/audit/cli/dispatch/hostHandoff.js.map +1 -1
  16. package/dist/audit/cli/fanoutLanes.d.ts +30 -0
  17. package/dist/audit/cli/fanoutLanes.d.ts.map +1 -1
  18. package/dist/audit/cli/fanoutLanes.js +76 -8
  19. package/dist/audit/cli/fanoutLanes.js.map +1 -1
  20. package/dist/audit/cli/nextStepCommand.d.ts +3 -0
  21. package/dist/audit/cli/nextStepCommand.d.ts.map +1 -1
  22. package/dist/audit/cli/nextStepCommand.js +104 -66
  23. package/dist/audit/cli/nextStepCommand.js.map +1 -1
  24. package/dist/audit/cli/nextStepHelpers.d.ts +49 -14
  25. package/dist/audit/cli/nextStepHelpers.d.ts.map +1 -1
  26. package/dist/audit/cli/nextStepHelpers.js +164 -68
  27. package/dist/audit/cli/nextStepHelpers.js.map +1 -1
  28. package/dist/audit/cli/reviewRun.d.ts +4 -0
  29. package/dist/audit/cli/reviewRun.d.ts.map +1 -1
  30. package/dist/audit/cli/reviewRun.js +1 -1
  31. package/dist/audit/cli/reviewRun.js.map +1 -1
  32. package/dist/audit/cli/semanticReviewStep.d.ts +2 -0
  33. package/dist/audit/cli/semanticReviewStep.d.ts.map +1 -1
  34. package/dist/audit/cli/semanticReviewStep.js +5 -50
  35. package/dist/audit/cli/semanticReviewStep.js.map +1 -1
  36. package/dist/audit/cli/validateResultsCommand.d.ts.map +1 -1
  37. package/dist/audit/cli/validateResultsCommand.js +3 -1
  38. package/dist/audit/cli/validateResultsCommand.js.map +1 -1
  39. package/dist/audit/extractors/fsIntake.d.ts +13 -0
  40. package/dist/audit/extractors/fsIntake.d.ts.map +1 -1
  41. package/dist/audit/extractors/fsIntake.js +11 -1
  42. package/dist/audit/extractors/fsIntake.js.map +1 -1
  43. package/dist/audit/io/artifacts.d.ts +35 -9
  44. package/dist/audit/io/artifacts.d.ts.map +1 -1
  45. package/dist/audit/io/artifacts.js +84 -67
  46. package/dist/audit/io/artifacts.js.map +1 -1
  47. package/dist/audit/io/rollover.d.ts +18 -0
  48. package/dist/audit/io/rollover.d.ts.map +1 -0
  49. package/dist/audit/io/rollover.js +152 -0
  50. package/dist/audit/io/rollover.js.map +1 -0
  51. package/dist/audit/io/runSnapshot.d.ts +149 -0
  52. package/dist/audit/io/runSnapshot.d.ts.map +1 -0
  53. package/dist/audit/io/runSnapshot.js +710 -0
  54. package/dist/audit/io/runSnapshot.js.map +1 -0
  55. package/dist/audit/orchestrator/advanceTypes.d.ts +11 -0
  56. package/dist/audit/orchestrator/advanceTypes.d.ts.map +1 -1
  57. package/dist/audit/orchestrator/autoFixExecutor.d.ts +9 -0
  58. package/dist/audit/orchestrator/autoFixExecutor.d.ts.map +1 -1
  59. package/dist/audit/orchestrator/autoFixExecutor.js +22 -2
  60. package/dist/audit/orchestrator/autoFixExecutor.js.map +1 -1
  61. package/dist/audit/orchestrator/charterExtractionExecutor.d.ts.map +1 -1
  62. package/dist/audit/orchestrator/charterExtractionExecutor.js +18 -3
  63. package/dist/audit/orchestrator/charterExtractionExecutor.js.map +1 -1
  64. package/dist/audit/orchestrator/charterPackets.d.ts +11 -1
  65. package/dist/audit/orchestrator/charterPackets.d.ts.map +1 -1
  66. package/dist/audit/orchestrator/charterPackets.js +13 -0
  67. package/dist/audit/orchestrator/charterPackets.js.map +1 -1
  68. package/dist/audit/orchestrator/designReviewPrompt.d.ts +9 -0
  69. package/dist/audit/orchestrator/designReviewPrompt.d.ts.map +1 -1
  70. package/dist/audit/orchestrator/designReviewPrompt.js +69 -31
  71. package/dist/audit/orchestrator/designReviewPrompt.js.map +1 -1
  72. package/dist/audit/orchestrator/designReviewSnapshot.d.ts +1 -0
  73. package/dist/audit/orchestrator/designReviewSnapshot.d.ts.map +1 -1
  74. package/dist/audit/orchestrator/designReviewSnapshot.js +2 -1
  75. package/dist/audit/orchestrator/designReviewSnapshot.js.map +1 -1
  76. package/dist/audit/orchestrator/executorRunners.d.ts.map +1 -1
  77. package/dist/audit/orchestrator/executorRunners.js +13 -4
  78. package/dist/audit/orchestrator/executorRunners.js.map +1 -1
  79. package/dist/audit/orchestrator/intakeExecutors.d.ts +8 -1
  80. package/dist/audit/orchestrator/intakeExecutors.d.ts.map +1 -1
  81. package/dist/audit/orchestrator/intakeExecutors.js +13 -4
  82. package/dist/audit/orchestrator/intakeExecutors.js.map +1 -1
  83. package/dist/audit/orchestrator/obligationPolicy.d.ts.map +1 -1
  84. package/dist/audit/orchestrator/obligationPolicy.js +4 -1
  85. package/dist/audit/orchestrator/obligationPolicy.js.map +1 -1
  86. package/dist/audit/orchestrator/planningExecutors.d.ts +1 -1
  87. package/dist/audit/orchestrator/planningExecutors.d.ts.map +1 -1
  88. package/dist/audit/orchestrator/planningExecutors.js +40 -6
  89. package/dist/audit/orchestrator/planningExecutors.js.map +1 -1
  90. package/dist/audit/orchestrator/systemicChallengeExecutor.d.ts.map +1 -1
  91. package/dist/audit/orchestrator/systemicChallengeExecutor.js +4 -1
  92. package/dist/audit/orchestrator/systemicChallengeExecutor.js.map +1 -1
  93. package/dist/audit/orchestrator/taskBuilder.d.ts +20 -0
  94. package/dist/audit/orchestrator/taskBuilder.d.ts.map +1 -1
  95. package/dist/audit/orchestrator/taskBuilder.js +80 -18
  96. package/dist/audit/orchestrator/taskBuilder.js.map +1 -1
  97. package/dist/audit/systemic/reviewFileMap.d.ts +72 -21
  98. package/dist/audit/systemic/reviewFileMap.d.ts.map +1 -1
  99. package/dist/audit/systemic/reviewFileMap.js +96 -45
  100. package/dist/audit/systemic/reviewFileMap.js.map +1 -1
  101. package/dist/audit/systemic/secondOrderAdversaryPrompt.d.ts +7 -0
  102. package/dist/audit/systemic/secondOrderAdversaryPrompt.d.ts.map +1 -1
  103. package/dist/audit/systemic/secondOrderAdversaryPrompt.js +39 -8
  104. package/dist/audit/systemic/secondOrderAdversaryPrompt.js.map +1 -1
  105. package/dist/remediate/phases/close.d.ts.map +1 -1
  106. package/dist/remediate/phases/close.js +19 -4
  107. package/dist/remediate/phases/close.js.map +1 -1
  108. package/dist/remediate/phases/triage.d.ts +2 -1
  109. package/dist/remediate/phases/triage.d.ts.map +1 -1
  110. package/dist/remediate/phases/triage.js +46 -25
  111. package/dist/remediate/phases/triage.js.map +1 -1
  112. package/dist/remediate/phases/triageConformance.d.ts +14 -0
  113. package/dist/remediate/phases/triageConformance.d.ts.map +1 -0
  114. package/dist/remediate/phases/triageConformance.js +189 -0
  115. package/dist/remediate/phases/triageConformance.js.map +1 -0
  116. package/dist/remediate/state/decisionConsumption.d.ts +110 -0
  117. package/dist/remediate/state/decisionConsumption.d.ts.map +1 -0
  118. package/dist/remediate/state/decisionConsumption.js +122 -0
  119. package/dist/remediate/state/decisionConsumption.js.map +1 -0
  120. package/dist/remediate/state/store.d.ts +4 -0
  121. package/dist/remediate/state/store.d.ts.map +1 -1
  122. package/dist/remediate/state/store.js +16 -0
  123. package/dist/remediate/state/store.js.map +1 -1
  124. package/dist/remediate/steps/dispatch/contractConformanceReview.d.ts +9 -0
  125. package/dist/remediate/steps/dispatch/contractConformanceReview.d.ts.map +1 -1
  126. package/dist/remediate/steps/dispatch/contractConformanceReview.js +32 -14
  127. package/dist/remediate/steps/dispatch/contractConformanceReview.js.map +1 -1
  128. package/dist/remediate/steps/dispatch/hostHandoff.d.ts.map +1 -1
  129. package/dist/remediate/steps/dispatch/hostHandoff.js +4 -0
  130. package/dist/remediate/steps/dispatch/hostHandoff.js.map +1 -1
  131. package/dist/remediate/steps/gateCommands.d.ts.map +1 -1
  132. package/dist/remediate/steps/gateCommands.js +6 -52
  133. package/dist/remediate/steps/gateCommands.js.map +1 -1
  134. package/dist/remediate/steps/nextStep.d.ts +7 -0
  135. package/dist/remediate/steps/nextStep.d.ts.map +1 -1
  136. package/dist/remediate/steps/nextStep.js +56 -19
  137. package/dist/remediate/steps/nextStep.js.map +1 -1
  138. package/dist/shared/contentKey.d.ts +3 -2
  139. package/dist/shared/contentKey.d.ts.map +1 -1
  140. package/dist/shared/contentKey.js +3 -2
  141. package/dist/shared/contentKey.js.map +1 -1
  142. package/dist/shared/decompose/charterExtraction.d.ts +189 -1
  143. package/dist/shared/decompose/charterExtraction.d.ts.map +1 -1
  144. package/dist/shared/decompose/charterExtraction.js +17 -2
  145. package/dist/shared/decompose/charterExtraction.js.map +1 -1
  146. package/dist/shared/git.d.ts +30 -1
  147. package/dist/shared/git.d.ts.map +1 -1
  148. package/dist/shared/git.js +65 -6
  149. package/dist/shared/git.js.map +1 -1
  150. package/dist/shared/loopCorePaths.d.ts.map +1 -1
  151. package/dist/shared/loopCorePaths.js +2 -0
  152. package/dist/shared/loopCorePaths.js.map +1 -1
  153. package/dist/shared/prompts.d.ts +2 -0
  154. package/dist/shared/prompts.d.ts.map +1 -1
  155. package/dist/shared/prompts.js +8 -2
  156. package/dist/shared/prompts.js.map +1 -1
  157. package/dist/shared/submission/ingestReport.d.ts.map +1 -1
  158. package/dist/shared/submission/ingestReport.js +19 -1
  159. package/dist/shared/submission/ingestReport.js.map +1 -1
  160. package/dist/shared/types/charter.d.ts +9 -0
  161. package/dist/shared/types/charter.d.ts.map +1 -1
  162. package/dist/shared/types/charter.js +7 -0
  163. package/dist/shared/types/charter.js.map +1 -1
  164. package/docs/audit-pkg/contracts.md +6 -2
  165. package/docs/audit-pkg/operator-guide.md +13 -4
  166. package/package.json +2 -1
@@ -0,0 +1,152 @@
1
+ // sites-pinned: tests/audit/artifacts-dir-rollover.test.ts
2
+ /**
3
+ * The rollover of a finished audit's working dir into the next run (owner
4
+ * decision 2026-10-08, "keep the artifacts dir"; record
5
+ * docs/reviews/artifacts-dir-rollover-plan-2026-10-08.md).
6
+ *
7
+ * PROPERTY: the next run reuses every derived artifact whose inputs did not
8
+ * change — the staleness DAG decides which — and inherits NOTHING that belongs
9
+ * to the finished run. The carried set is an ALLOW-LIST: every entry not named
10
+ * here is deleted, so a run-scoped file added later can never leak into the
11
+ * next run by being forgotten.
12
+ *
13
+ * A run is FINISHED when its terminal step presented a promoted report: that
14
+ * step writes the run-ended marker (`markRunEnded`). The marker, not byte
15
+ * identity between the dir and the archive, is the gate: a host may still
16
+ * append diagnostics after promotion, and an operator may resynthesize the
17
+ * promoted deliverables, and neither may keep the next audit from starting.
18
+ * The appended diagnostics are archived again here before anything is deleted.
19
+ *
20
+ * Deliberately NOT carried, and why:
21
+ * - `audit_state.json`: a `complete` status short-circuits every derivation.
22
+ * - The intake set (`repo_manifest`, `file_disposition`, `scope`,
23
+ * `scope_summary.json`): live-tree drift is never detected against a retained
24
+ * manifest, and `--since` is not a DAG input. Re-intake of an unchanged tree
25
+ * reproduces the same manifest content hash (`generated_at` is not semantic),
26
+ * so nothing downstream re-stales.
27
+ * - Per-run choices (`intent_checkpoint`, consent and the analyzer results it
28
+ * admitted, `auto_fixes_applied`, host fallbacks, and the analyzer install
29
+ * settings in `analyzer-policy.json`): a per-run choice is never persisted
30
+ * into the next run.
31
+ * - The finished run's deliverables in place (already promoted one level up)
32
+ * and every run-scoped record: steps, dispatch, runs, submissions and their
33
+ * ledger, staging, quarantine, lanes, scratch, friction, logs, handoff,
34
+ * guidance, the snapshot record.
35
+ * - `tooling_manifest.json`: never read from disk; every bundle load rebuilds it.
36
+ *
37
+ * Measured (2026-10-08): over an UNCHANGED tree the next run re-derives only
38
+ * deterministic planning (`audit_tasks`, `audit_plan_metrics`,
39
+ * `task_affinity_graph`); the re-intaken manifest differs only in its
40
+ * non-semantic `generated_at`, so the analysis artifacts and the host-judged
41
+ * ones (charter, design assessment, systemic challenge) keep their revisions.
42
+ */
43
+ import { existsSync } from "node:fs";
44
+ import { readdir, rm, writeFile } from "node:fs/promises";
45
+ import { basename, join } from "node:path";
46
+ import { AUDIT_FINDINGS_FILENAME, auditFindingsPath, promotedAuditFindingsPath, SESSION_INTENT_RELATIVE_PATH, } from "audit-tools/shared";
47
+ import { withArtifactTreeHold } from "../../shared/io/artifactTreeHold.js";
48
+ import { ARTIFACT_DEFINITIONS, archiveRunDiagnostics } from "./artifacts.js";
49
+ import { removeRunSnapshot } from "./runSnapshot.js";
50
+ import { CHARTER_PACKET_ARCHIVE_DIRNAME } from "../orchestrator/charterPacketArchive.js";
51
+ import { SNAPSHOT_DIRNAME } from "../orchestrator/designReviewSnapshot.js";
52
+ import { graphEdgeCachePath } from "../orchestrator/graphEdgeCache.js";
53
+ /** Registry artifacts derived from the run's inputs, each staleness-judged by the DAG. */
54
+ const CARRIED_ARTIFACTS = [
55
+ "artifact_metadata",
56
+ "audit_results",
57
+ "unit_manifest",
58
+ "graph_bundle",
59
+ "surface_manifest",
60
+ "critical_flows",
61
+ "flow_coverage",
62
+ "risk_register",
63
+ "git_history",
64
+ "design_assessment",
65
+ "conceptual_review_adjudication",
66
+ "docs_digest",
67
+ "structure_decomposition",
68
+ "charter_register",
69
+ "charter_clarification",
70
+ "systemic_challenge",
71
+ "analyzer_capability",
72
+ "coverage_matrix",
73
+ "runtime_validation_tasks",
74
+ "runtime_validation_report",
75
+ "audit_tasks",
76
+ "audit_plan_metrics",
77
+ "task_affinity_graph",
78
+ "requeue_tasks",
79
+ "access_memory",
80
+ "synthesis_narrative",
81
+ ];
82
+ /** Content-keyed stores outside the registry, each self-invalidating. */
83
+ const CARRIED_STORES = [SNAPSHOT_DIRNAME, basename(graphEdgeCachePath("")), CHARTER_PACKET_ARCHIVE_DIRNAME];
84
+ /**
85
+ * The operator's hand-authored repository intent (docs/audit-pkg/operator-guide.md).
86
+ * It grants nothing to a run on its own; the tool never writes it.
87
+ */
88
+ const CARRIED_INTENT = [basename(SESSION_INTENT_RELATIVE_PATH)];
89
+ const CARRIED = new Set([
90
+ ...CARRIED_ARTIFACTS.map((key) => ARTIFACT_DEFINITIONS[key].fileName),
91
+ ...CARRIED_STORES,
92
+ ...CARRIED_INTENT,
93
+ ]);
94
+ const STATE_FILE = ARTIFACT_DEFINITIONS.audit_state.fileName;
95
+ const runEndedPath = (artifactsDir) => join(artifactsDir, "run-ended.json");
96
+ /**
97
+ * Record that the run ended: its terminal step presented a promoted report.
98
+ * Written by the terminal step only after the promotion succeeded.
99
+ */
100
+ export async function markRunEnded(artifactsDir) {
101
+ await writeFile(runEndedPath(artifactsDir), "{}\n");
102
+ }
103
+ function warn(message) {
104
+ process.stderr.write(`[audit-code] ${message}\n`);
105
+ }
106
+ /**
107
+ * Roll an ENDED run over (see `markRunEnded`), under the artifact-tree hold:
108
+ * archive its diagnostics again, remove its snapshot, and delete every entry
109
+ * that is not carried. The state file and the marker go LAST, so a rollover
110
+ * that fails part-way is retried in full on the next call and never leaves a
111
+ * run-scoped record (consent above all) for the next run to adopt. When a
112
+ * diagnostic does not archive, or the snapshot cannot be removed, nothing is
113
+ * deleted: the dir then holds the only copy, or the record of what to clean.
114
+ * Returns whether it rolled the dir over.
115
+ */
116
+ export async function rollOverFinishedRun(artifactsDir, runLogger) {
117
+ if (!existsSync(runEndedPath(artifactsDir)))
118
+ return false;
119
+ return await withArtifactTreeHold(artifactsDir, runLogger, async () => {
120
+ if (!existsSync(runEndedPath(artifactsDir)))
121
+ return false;
122
+ // The machine contract is promoted at the terminal step, never re-copied
123
+ // here (an operator may have resynthesized the promoted pair). An in-place
124
+ // contract with no promoted copy is the only copy: keep the dir.
125
+ if (existsSync(auditFindingsPath(artifactsDir)) && !existsSync(promotedAuditFindingsPath(artifactsDir))) {
126
+ warn(`the finished audit in ${artifactsDir} was not rolled over: ${AUDIT_FINDINGS_FILENAME} has no promoted copy ` +
127
+ `at ${promotedAuditFindingsPath(artifactsDir)}; copy it there, or run \`audit-code cleanup --force\` to discard it`);
128
+ return false;
129
+ }
130
+ const { lost } = await archiveRunDiagnostics({ artifactsDir });
131
+ if (lost.length > 0) {
132
+ warn(`the finished audit in ${artifactsDir} was not rolled over: could not archive ${lost.join("; ")}`);
133
+ return false;
134
+ }
135
+ const problems = await removeRunSnapshot(artifactsDir);
136
+ if (problems.length > 0) {
137
+ warn(`the finished audit in ${artifactsDir} was not rolled over: run snapshot cleanup: ${problems.join("; ")}`);
138
+ return false;
139
+ }
140
+ // Lock files are never deleted: the hold this runs under owns one of them.
141
+ const last = [STATE_FILE, basename(runEndedPath(artifactsDir))];
142
+ for (const entry of await readdir(artifactsDir)) {
143
+ if (CARRIED.has(entry) || entry.endsWith(".lock") || last.includes(entry))
144
+ continue;
145
+ await rm(join(artifactsDir, entry), { recursive: true, force: true });
146
+ }
147
+ for (const entry of last)
148
+ await rm(join(artifactsDir, entry), { force: true });
149
+ return true;
150
+ });
151
+ }
152
+ //# sourceMappingURL=rollover.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"rollover.js","sourceRoot":"","sources":["../../../src/audit/io/rollover.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,149 @@
1
+ import { z } from "zod";
2
+ declare const RunSnapshotSchema: z.ZodObject<{
3
+ schema_version: z.ZodLiteral<"audit-run-snapshot/v1">;
4
+ repository_root: z.ZodString;
5
+ source_root: z.ZodString;
6
+ kind: z.ZodEnum<["git", "copy"]>;
7
+ /** Root repository first, then each submodule after its parent. Empty for `copy`. */
8
+ pins: z.ZodArray<z.ZodObject<{
9
+ /** realpath of the live repository directory that owns this pin's objects. */
10
+ repository: z.ZodString;
11
+ /** The checkout inside the snapshot. */
12
+ path: z.ZodString;
13
+ /** The live `HEAD` at run start — the checkout's `HEAD`; `null` when unborn. */
14
+ base: z.ZodNullable<z.ZodString>;
15
+ /** The tree of the live INDEX at run start — the checkout's index. */
16
+ index: z.ZodString;
17
+ /** The copied bytes as a commit, kept only to restore the checkout. */
18
+ commit: z.ZodString;
19
+ /** This run's own ref holding `commit`. */
20
+ ref: z.ZodString;
21
+ }, "strict", z.ZodTypeAny, {
22
+ index: string;
23
+ path: string;
24
+ commit: string;
25
+ ref: string;
26
+ base: string | null;
27
+ repository: string;
28
+ }, {
29
+ index: string;
30
+ path: string;
31
+ commit: string;
32
+ ref: string;
33
+ base: string | null;
34
+ repository: string;
35
+ }>, "many">;
36
+ /** Snapshot-relative (POSIX) paths of the directory links the snapshot placed. */
37
+ linked: z.ZodArray<z.ZodString, "many">;
38
+ /** Each `--since` ref this run was given, resolved ONCE against the live root. */
39
+ since: z.ZodRecord<z.ZodString, z.ZodString>;
40
+ }, "strict", z.ZodTypeAny, {
41
+ kind: "git" | "copy";
42
+ schema_version: "audit-run-snapshot/v1";
43
+ repository_root: string;
44
+ since: Record<string, string>;
45
+ source_root: string;
46
+ pins: {
47
+ index: string;
48
+ path: string;
49
+ commit: string;
50
+ ref: string;
51
+ base: string | null;
52
+ repository: string;
53
+ }[];
54
+ linked: string[];
55
+ }, {
56
+ kind: "git" | "copy";
57
+ schema_version: "audit-run-snapshot/v1";
58
+ repository_root: string;
59
+ since: Record<string, string>;
60
+ source_root: string;
61
+ pins: {
62
+ index: string;
63
+ path: string;
64
+ commit: string;
65
+ ref: string;
66
+ base: string | null;
67
+ repository: string;
68
+ }[];
69
+ linked: string[];
70
+ }>;
71
+ export type RunSnapshot = z.infer<typeof RunSnapshotSchema>;
72
+ export declare const runSnapshotPath: (artifactsDir: string) => string;
73
+ /**
74
+ * The run's snapshot: created at run start, its checkouts restored when they
75
+ * went missing, refused when a copy went missing.
76
+ *
77
+ * The caller holds the artifact-tree lock (the snapshot is run state, created
78
+ * once per run). Callers on a run path go through {@link ensureRunSourceRoot},
79
+ * which owns the "a complete run reads nothing" rule.
80
+ */
81
+ export declare function ensureRunSnapshot(root: string, artifactsDir: string): Promise<RunSnapshot>;
82
+ /**
83
+ * The root a run's content reads use — THE one decision every run path shares
84
+ * (the next-step fold and every standalone step command). A COMPLETE run reads
85
+ * nothing more: it is given no snapshot (promotion removed it, and a new one
86
+ * would freeze a tree the run never read), and its terminal step needs only the
87
+ * live root. Any other run reads its frozen snapshot. The caller holds the
88
+ * artifact-tree lock.
89
+ */
90
+ export declare function ensureRunSourceRoot(root: string, artifactsDir: string): Promise<string>;
91
+ /**
92
+ * The commit a `--since` ref named when this run first saw it, resolved against
93
+ * the LIVE root (a pseudo-ref such as the branch upstream @{u} or ORIG_HEAD does
94
+ * not resolve in the detached snapshot) and persisted, so a moving HEAD cannot move the
95
+ * delta mid-run. An unresolvable ref is returned unchanged, for the scope
96
+ * resolver's own full-audit fallback. The caller holds the artifact-tree lock.
97
+ */
98
+ export declare function resolveRunSince(root: string, artifactsDir: string, since: string): Promise<string>;
99
+ /** The `--since` resolution this run recorded, without resolving anything (no lock). */
100
+ export declare function lookupRunSince(artifactsDir: string, since: string): Promise<string>;
101
+ /**
102
+ * The source root of the run in `artifactsDir`, WITHOUT creating a snapshot —
103
+ * for a read-only command that holds no lock. With no run started there is no
104
+ * frozen tree, and the live root is the only content there is.
105
+ */
106
+ export declare function readRunSourceRoot(root: string, artifactsDir: string): Promise<string>;
107
+ /** The directory links the run's snapshot placed — never audit input (see `readAuditReadState`). */
108
+ export declare function readRunSnapshotLinks(artifactsDir: string): Promise<readonly string[]>;
109
+ /**
110
+ * The one statement of where a host lane reads repository source during a run:
111
+ * the frozen snapshot, never its own working directory or the live repository,
112
+ * which may have moved since the run started. Single-sourced so the work-item
113
+ * prompts and every materialized lane prompt say it identically.
114
+ */
115
+ export declare function sourceTreeInstruction(sourceRoot: string): string;
116
+ /**
117
+ * Carry the tool's own edits of the snapshot (the opted-in auto-fix phase) back
118
+ * to the live tree. A file is written only when its live bytes still hash to
119
+ * `startHashes` — the content the run started from — so a user's concurrent
120
+ * edit is never overwritten; such a file is returned as skipped.
121
+ */
122
+ export declare function writeBackSnapshotEdits(params: {
123
+ sourceRoot: string;
124
+ repositoryRoot: string;
125
+ paths: readonly string[];
126
+ startHashes: ReadonlyMap<string, string>;
127
+ }): Promise<{
128
+ written: string[];
129
+ skipped: string[];
130
+ }>;
131
+ /**
132
+ * Re-pin the run's snapshot after the tool edited it (deepest checkout first),
133
+ * so a checkout restored later holds the edited bytes. The checkouts' `HEAD`
134
+ * and index are unchanged: the edit is the run's, not a commit's. The placed
135
+ * links are subtracted — on POSIX a dir-only ignore pattern does not match a
136
+ * symlink, and a pinned link would be restored as a file.
137
+ */
138
+ export declare function repinRunSnapshot(artifactsDir: string): Promise<void>;
139
+ /**
140
+ * Remove the run's snapshot: its links first (each points into the live tree),
141
+ * then the directory, then each checkout's own registration and ref (deepest
142
+ * first), then the record. Never throws — a cleanup must not fail on the
143
+ * scratch it is reclaiming; each problem is returned for the caller to report.
144
+ * The record goes last and only on a clean removal, so a failed one can be
145
+ * retried and a second call is a no-op.
146
+ */
147
+ export declare function removeRunSnapshot(artifactsDir: string): Promise<string[]>;
148
+ export {};
149
+ //# sourceMappingURL=runSnapshot.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"runSnapshot.d.ts","sourceRoot":"","sources":["../../../src/audit/io/runSnapshot.ts"],"names":[],"mappings":"AAmDA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAwBxB,QAAA,MAAM,iBAAiB;;;;;IAKrB,qFAAqF;;QApBrF,8EAA8E;;QAE9E,wCAAwC;;QAExC,gFAAgF;;QAEhF,sEAAsE;;QAEtE,uEAAuE;;QAEvE,2CAA2C;;;;;;;;;;;;;;;;;IAY3C,kFAAkF;;IAElF,kFAAkF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEzE,CAAC;AACZ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,eAAe,GAAI,cAAc,MAAM,KAAG,MAAiD,CAAC;AAsezG;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAqBhG;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAI7F;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAexG;AAED,wFAAwF;AACxF,wBAAsB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEzF;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG3F;AAED,oGAAoG;AACpG,wBAAsB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAE3F;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAGhE;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAoBpD;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB1E;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA4B/E"}