@tiangong-lca/foundry 0.1.9 → 0.1.11

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 (107) hide show
  1. package/README.md +13 -11
  2. package/docs/architecture.md +12 -10
  3. package/docs/foundry-task-contracts.md +16 -4
  4. package/docs/import-profiles/bafu/constraints.md +1 -1
  5. package/docs/import-profiles/bafu/profile.md +1 -1
  6. package/docs/import-profiles/worldsteel/constraints.md +3 -3
  7. package/docs/import-profiles/worldsteel/import-coverage.md +3 -3
  8. package/docs/import-profiles/worldsteel/import-plan.md +4 -4
  9. package/docs/import-profiles/worldsteel/profile.md +3 -3
  10. package/docs/package-distribution-contract.md +11 -9
  11. package/docs/public-runtime-contract.md +31 -9
  12. package/docs/runtime-context-contract.md +7 -5
  13. package/docs/task-authorization-contract.md +5 -3
  14. package/package-dist/assets/foundry-package-descriptor.json +300 -154
  15. package/package-dist/scripts/foundry-facade.d.ts +1 -0
  16. package/package-dist/scripts/foundry-facade.js +233 -28
  17. package/package-dist/scripts/foundry-runtime.d.ts +14 -3
  18. package/package-dist/scripts/foundry-runtime.js +2 -2
  19. package/package-dist/scripts/lib/finalize-owners/commit-handoff.js +3 -3
  20. package/package-dist/scripts/lib/finalize-owners/{native-insert-closeout.d.ts → native-draft-closeout.d.ts} +1 -1
  21. package/package-dist/scripts/lib/finalize-owners/{native-insert-closeout.js → native-draft-closeout.js} +10 -6
  22. package/package-dist/scripts/lib/finalize-owners/{native-insert-handoff.d.ts → native-draft-handoff.d.ts} +7 -5
  23. package/package-dist/scripts/lib/finalize-owners/{native-insert-handoff.js → native-draft-handoff.js} +30 -11
  24. package/package-dist/scripts/lib/finalize-owners/post-write-closeout.js +2 -2
  25. package/package-dist/scripts/lib/foundry-authorization-input.d.ts +10 -1
  26. package/package-dist/scripts/lib/foundry-authorization-input.js +27 -3
  27. package/package-dist/scripts/lib/foundry-command-metadata.js +25 -2
  28. package/package-dist/scripts/lib/foundry-command-registry.d.ts +4 -4
  29. package/package-dist/scripts/lib/foundry-command-registry.js +3 -0
  30. package/package-dist/scripts/lib/foundry-execution-admission.js +3 -3
  31. package/package-dist/scripts/lib/foundry-facade-store.js +56 -6
  32. package/package-dist/scripts/lib/foundry-interaction-input.d.ts +19 -0
  33. package/package-dist/scripts/lib/foundry-interaction-input.js +327 -0
  34. package/package-dist/scripts/lib/foundry-interaction-projection.d.ts +22 -0
  35. package/package-dist/scripts/lib/foundry-interaction-projection.js +81 -0
  36. package/package-dist/scripts/lib/foundry-interaction-types.d.ts +17 -0
  37. package/package-dist/scripts/lib/foundry-interaction-types.js +4 -0
  38. package/package-dist/scripts/lib/foundry-owner-execution-store.d.ts +33 -16
  39. package/package-dist/scripts/lib/foundry-owner-execution-store.js +66 -5
  40. package/package-dist/scripts/lib/foundry-owner-readback.d.ts +3 -0
  41. package/package-dist/scripts/lib/foundry-owner-readback.js +101 -27
  42. package/package-dist/scripts/lib/foundry-package-contract.d.ts +4 -4
  43. package/package-dist/scripts/lib/foundry-package-contract.js +4 -2
  44. package/package-dist/scripts/lib/foundry-repair-execution.d.ts +11 -0
  45. package/package-dist/scripts/lib/foundry-repair-execution.js +70 -0
  46. package/package-dist/scripts/lib/foundry-repair-handoff.d.ts +16 -0
  47. package/package-dist/scripts/lib/foundry-repair-handoff.js +108 -0
  48. package/package-dist/scripts/lib/foundry-repair-preflight.d.ts +96 -0
  49. package/package-dist/scripts/lib/foundry-repair-preflight.js +313 -0
  50. package/package-dist/scripts/lib/foundry-repair-reference-binding.d.ts +26 -0
  51. package/package-dist/scripts/lib/foundry-repair-reference-binding.js +120 -0
  52. package/package-dist/scripts/lib/foundry-repair-reference-proof.d.ts +63 -0
  53. package/package-dist/scripts/lib/foundry-repair-reference-proof.js +329 -0
  54. package/package-dist/scripts/lib/foundry-repair-scope.d.ts +76 -0
  55. package/package-dist/scripts/lib/foundry-repair-scope.js +304 -0
  56. package/package-dist/scripts/lib/foundry-runtime-command-policy.js +1 -0
  57. package/package-dist/scripts/lib/foundry-runtime-qualification.js +2 -2
  58. package/package-dist/scripts/lib/foundry-runtime-utils.d.ts +3 -0
  59. package/package-dist/scripts/lib/foundry-runtime-utils.js +6 -1
  60. package/package-dist/scripts/lib/foundry-semantic-input.d.ts +2 -0
  61. package/package-dist/scripts/lib/foundry-semantic-input.js +29 -2
  62. package/package-dist/scripts/lib/foundry-semantic-interaction.d.ts +12 -0
  63. package/package-dist/scripts/lib/foundry-semantic-interaction.js +38 -0
  64. package/package-dist/scripts/lib/foundry-successor-predecessor.d.ts +36 -0
  65. package/package-dist/scripts/lib/foundry-successor-predecessor.js +399 -0
  66. package/package-dist/scripts/lib/foundry-task-registration.js +64 -3
  67. package/package-dist/scripts/lib/foundry-task-start-spec.d.ts +14 -0
  68. package/package-dist/scripts/lib/foundry-task-start-spec.js +60 -1
  69. package/package-dist/scripts/lib/foundry-task-store.d.ts +13 -1
  70. package/package-dist/scripts/lib/foundry-task-store.js +23 -12
  71. package/package-dist/scripts/lib/foundry-task-types.d.ts +22 -1
  72. package/package-dist/scripts/lib/foundry-tidas-source.d.ts +15 -0
  73. package/package-dist/scripts/lib/foundry-tidas-source.js +90 -0
  74. package/package-dist/scripts/lib/foundry-workflow-assessment.d.ts +7 -1
  75. package/package-dist/scripts/lib/foundry-workflow-assessment.js +127 -6
  76. package/package-dist/scripts/lib/foundry-workflow-authorization.d.ts +2 -1
  77. package/package-dist/scripts/lib/foundry-workflow-authorization.js +194 -26
  78. package/package-dist/scripts/lib/foundry-workflow-context.js +4 -0
  79. package/package-dist/scripts/lib/foundry-workflow-execution.js +6 -1
  80. package/package-dist/scripts/lib/foundry-workflow-finalize.js +7 -4
  81. package/package-dist/scripts/lib/foundry-workflow-interaction.d.ts +4 -0
  82. package/package-dist/scripts/lib/foundry-workflow-interaction.js +63 -0
  83. package/package-dist/scripts/lib/foundry-workflow-repair.d.ts +36 -0
  84. package/package-dist/scripts/lib/foundry-workflow-repair.js +580 -0
  85. package/package-dist/scripts/lib/foundry-workflow-semantic.js +21 -1
  86. package/package-dist/scripts/lib/foundry-workflow-state.d.ts +9 -1
  87. package/package-dist/scripts/lib/foundry-workflow-state.js +239 -39
  88. package/package-dist/scripts/lib/import-curation/curation-cleanup.js +39 -8
  89. package/package-dist/scripts/lib/import-curation/internal/context-inputs.js +1 -1
  90. package/package-dist/scripts/lib/import-curation/internal/prewrite-cleanup.d.ts +13 -2
  91. package/package-dist/scripts/lib/import-curation/internal/prewrite-cleanup.js +100 -29
  92. package/package-dist/scripts/lib/import-curation/internal/workflow-authoring-tasks.js +1 -2
  93. package/package-dist/scripts/lib/import-curation/internal/workflow-patch-collect.js +2 -3
  94. package/package-dist/scripts/lib/import-curation/internal/workflow-queue-context.js +8 -8
  95. package/package-dist/scripts/lib/import-curation/internal/workflow-semantic-actions.js +12 -2
  96. package/package-dist/scripts/public-api.d.ts +2 -0
  97. package/package-dist/scripts/public-api.js +1 -0
  98. package/package-dist/scripts/runtime-entry.js +9 -1
  99. package/package.json +3 -2
  100. package/specs/import-profiles.json +1 -1
  101. package/specs/schemas/foundry-authorization-input.schema.json +45 -2
  102. package/specs/schemas/foundry-interaction-input.schema.json +173 -0
  103. package/specs/schemas/foundry-managed-runtime.schema.json +1 -1
  104. package/specs/schemas/foundry-package-descriptor.schema.json +3 -2
  105. package/specs/schemas/foundry-semantic-input.schema.json +12 -1
  106. package/specs/schemas/foundry-task-start.schema.json +275 -19
  107. package/specs/schemas/runtime-qualification.schema.json +1 -1
@@ -0,0 +1,329 @@
1
+ import { FoundryContextError } from "./foundry-runtime-context.js";
2
+ import { validateUniqueRootReadbacks } from "./post-write-root-proof.js";
3
+ /**
4
+ * Derive an integrity proof for a remote verification that blocked **only** on retained references.
5
+ *
6
+ * A `version_outdated` reference means the requested version exists exactly and is simply not the
7
+ * newest published one. For a metadata repair over a draft, retaining such a reference unchanged is
8
+ * not an integrity failure, so this module separates the integrity proof from the freshness finding
9
+ * instead of letting the freshness finding veto the whole readback.
10
+ *
11
+ * This module is pure: it reads its inputs, never writes to them, spawns nothing and performs no
12
+ * I/O. It does not rewrite the CLI report, does not change the CLI's status, and does not adjust
13
+ * `counts` -- the raw status and every counter are reported back verbatim so a reader can see that
14
+ * nothing was laundered into a generic quality pass. `publication_ready` is always `false`.
15
+ *
16
+ * Everything that is not explicitly admitted fails closed: a foreign status, a non-outdated
17
+ * blocker, a reference whose exact version is not the requested one, an `ok` bucket that disagrees
18
+ * with the records, duplicate or extra records, a re-declared expectation set, and any root
19
+ * evidence that does not satisfy the unchanged strict exact-payload/owner/state rule.
20
+ */
21
+ export const FOUNDRY_REPAIR_REFERENCE_PROOF_SCHEMA = "tiangong-foundry.repair-reference-proof.v1";
22
+ /** The only status this proof admits: remote verification ran and blocked on retained references. */
23
+ const RETAINED_REFERENCE_STATUS = "blocked_remote_verification";
24
+ const RETAINED_REFERENCE_ROOT_POLICY = "existing";
25
+ const RETAINED_OUTDATED_STATUS = "version_outdated";
26
+ const RETAINED_OK_STATUS = "ok";
27
+ const REFERENCE_ROLE = "reference";
28
+ const ROOT_ROLE = "root";
29
+ const READBACK_SUFFIX = "#readback";
30
+ const CHECK_STATUSES = Object.freeze([
31
+ "ok",
32
+ "lookup_failed",
33
+ "missing_dataset",
34
+ "missing_version",
35
+ "owner_mismatch",
36
+ "payload_mismatch",
37
+ "remote_payload_missing",
38
+ "state_code_mismatch",
39
+ "unsupported_type",
40
+ "version_missing",
41
+ "version_outdated",
42
+ ]);
43
+ /** A reference check and a root resolvability check share one shape; the readback adds five fields. */
44
+ const PROBE_KEYS = Object.freeze([
45
+ "row_index",
46
+ "role",
47
+ "table",
48
+ "type",
49
+ "id",
50
+ "version",
51
+ "path",
52
+ "short_description",
53
+ "status",
54
+ "exact_version",
55
+ "latest_version",
56
+ "exact_source_url",
57
+ "latest_source_url",
58
+ "message",
59
+ ]);
60
+ const READBACK_KEYS = Object.freeze([
61
+ ...PROBE_KEYS,
62
+ "local_payload_sha256",
63
+ "remote_payload_sha256",
64
+ "remote_user_id",
65
+ "remote_state_code",
66
+ "remote_modified_at",
67
+ ]);
68
+ const BLOCKER_KEYS = Object.freeze([
69
+ "code",
70
+ "severity",
71
+ "message",
72
+ "row_index",
73
+ "role",
74
+ "table",
75
+ "id",
76
+ "version",
77
+ "latest_version",
78
+ "path",
79
+ ]);
80
+ const VERSION_PATTERN = /^(\d{1,5})\.(\d{1,5})\.(\d{1,5})$/u;
81
+ function fail(code, message) {
82
+ throw new FoundryContextError(code, message);
83
+ }
84
+ function isRecord(value) {
85
+ return Boolean(value) && typeof value === "object" && !Array.isArray(value);
86
+ }
87
+ function record(value, label) {
88
+ if (!isRecord(value))
89
+ fail("repair_reference_proof_invalid", `${label} must be an object.`);
90
+ return value;
91
+ }
92
+ function exactKeys(value, keys, label) {
93
+ if (Object.keys(value).length !== keys.length || keys.some((key) => !Object.hasOwn(value, key)))
94
+ fail("repair_reference_proof_invalid", `${label} has missing or unsupported fields.`);
95
+ }
96
+ function count(value, label) {
97
+ if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
98
+ fail("repair_reference_proof_invalid", `${label} count must be a nonnegative integer.`);
99
+ return value;
100
+ }
101
+ function text(value, label) {
102
+ if (typeof value !== "string" || !value.trim())
103
+ fail("repair_reference_proof_invalid", `${label} must be a non-empty string.`);
104
+ return value.trim();
105
+ }
106
+ function versionTriplet(value, label) {
107
+ const match = typeof value === "string" ? VERSION_PATTERN.exec(value.trim()) : null;
108
+ if (!match)
109
+ fail("repair_reference_proof_invalid", `${label} version must be an explicit three-part version.`);
110
+ return [Number(match[1]), Number(match[2]), Number(match[3])];
111
+ }
112
+ function compareVersions(left, right) {
113
+ for (let index = 0; index < 3; index += 1) {
114
+ const delta = left[index] - right[index];
115
+ if (delta !== 0)
116
+ return delta < 0 ? -1 : 1;
117
+ }
118
+ return 0;
119
+ }
120
+ /** Identity of one reference occurrence: the same target on another path is another occurrence. */
121
+ function referenceKey(value) {
122
+ return JSON.stringify([value.row_index, value.path, value.table, value.id, value.version]);
123
+ }
124
+ function expectedReferences(references, label) {
125
+ const map = new Map();
126
+ for (const [index, reference] of references.entries()) {
127
+ const item = record(reference, `${label} ${index + 1}`);
128
+ const key = referenceKey({
129
+ row_index: count(item.row_index, `${label} row index`),
130
+ path: text(item.path, `${label} path`),
131
+ table: text(item.table, `${label} table`),
132
+ id: text(item.id, `${label} id`),
133
+ version: text(item.version, `${label} version`),
134
+ });
135
+ if (map.has(key))
136
+ fail("repair_reference_proof_invalid", `${label} contains a duplicate occurrence.`);
137
+ map.set(key, {
138
+ row_index: count(item.row_index, `${label} row index`),
139
+ path: text(item.path, `${label} path`),
140
+ table: text(item.table, `${label} table`),
141
+ id: text(item.id, `${label} id`),
142
+ version: text(item.version, `${label} version`),
143
+ });
144
+ }
145
+ return map;
146
+ }
147
+ export function proveRetainedRepairReferences(input) {
148
+ const report = record(input.report, "Remote verification report");
149
+ const status = text(report.status, "Remote verification status");
150
+ if (status !== RETAINED_REFERENCE_STATUS)
151
+ fail("repair_reference_proof_invalid", "A retained-reference proof requires a blocked remote verification status.");
152
+ if (text(report.root_policy, "Remote verification root policy") !== RETAINED_REFERENCE_ROOT_POLICY)
153
+ fail("repair_reference_proof_invalid", "A retained-reference proof requires the existing root policy.");
154
+ const counts = record(report.counts, "Remote verification counts");
155
+ const rows = count(counts.rows, "Reported rows");
156
+ const references = count(counts.references, "Reported references");
157
+ const checked = count(counts.checked, "Reported checked");
158
+ const rawBlockers = count(counts.blockers, "Reported blockers");
159
+ const rootReadbackChecks = count(counts.root_readback_checks, "Reported root readback checks");
160
+ const rootPayloadMismatches = count(counts.root_payload_mismatches, "Reported root payload");
161
+ const expectedRoots = expectedReferences(input.roots, "Expected root");
162
+ const expectedRefs = expectedReferences(input.references, "Expected reference");
163
+ if (rootPayloadMismatches !== 0)
164
+ fail("repair_reference_proof_invalid", "A retained-reference proof requires zero root payload mismatches.");
165
+ // The CLI counts one root row, one root readback per root, and every remaining record -- the root
166
+ // resolvability record included -- as a reference. Declared expectations must account for every
167
+ // record, so a caller can neither widen nor narrow the retained set.
168
+ if (rows !== input.roots.length || rootReadbackChecks !== input.roots.length)
169
+ fail("repair_reference_proof_invalid", "Report counts must match the declared roots and references exactly; a caller cannot widen or narrow the retained set.");
170
+ if (references !== input.roots.length + input.references.length)
171
+ fail("repair_reference_proof_invalid", "Report counts must match the declared roots and references exactly; a caller cannot widen or narrow the retained set.");
172
+ if (checked !== rows + references)
173
+ fail("repair_reference_proof_invalid", "Report counts must match the declared roots, references and checks exactly.");
174
+ if (!Array.isArray(input.checks) || input.checks.length !== checked || !input.checks.length)
175
+ fail("repair_reference_proof_invalid", "The check records must be present and match the reported check count exactly.");
176
+ const byStatus = record(counts.by_status, "Remote verification status buckets");
177
+ for (const [bucket, value] of Object.entries(byStatus)) {
178
+ if (!CHECK_STATUSES.includes(bucket))
179
+ fail("repair_reference_proof_invalid", `Report status bucket ${bucket} is not a known status.`);
180
+ count(value, `Report status bucket ${bucket}`);
181
+ }
182
+ const blockers = Array.isArray(report.blockers) ? report.blockers : [];
183
+ if (blockers.length !== rawBlockers)
184
+ fail("repair_reference_proof_invalid", "The blocker records must match the reported blocker count.");
185
+ const readbackChecks = [];
186
+ const probeChecks = [];
187
+ for (const [index, value] of input.checks.entries()) {
188
+ const check = record(value, `Check ${index + 1}`);
189
+ const role = text(check.role, `Check ${index + 1} role`);
190
+ const isReadback = role === ROOT_ROLE && String(check.path ?? "").endsWith(READBACK_SUFFIX);
191
+ exactKeys(check, isReadback ? READBACK_KEYS : PROBE_KEYS, `Check ${index + 1}`);
192
+ if (role !== ROOT_ROLE && role !== REFERENCE_ROLE)
193
+ fail("repair_reference_proof_invalid", `Check ${index + 1} role is unsupported.`);
194
+ if (isReadback)
195
+ readbackChecks.push(check);
196
+ else
197
+ probeChecks.push(check);
198
+ }
199
+ // Root evidence: one resolvability record and one strict exact readback per declared root.
200
+ const rootResolve = probeChecks.filter((check) => check.role === ROOT_ROLE);
201
+ const referenceProbes = probeChecks.filter((check) => check.role === REFERENCE_ROLE);
202
+ if (rootResolve.length !== input.roots.length || readbackChecks.length !== rootReadbackChecks)
203
+ fail("repair_reference_proof_invalid", "Root evidence must carry exactly one resolvability record and one readback per declared root.");
204
+ const seenRoots = new Set();
205
+ for (const check of rootResolve) {
206
+ const key = referenceKey({
207
+ row_index: count(check.row_index, "Root row index"),
208
+ path: text(check.path, "Root path"),
209
+ table: text(check.table, "Root table"),
210
+ id: text(check.id, "Root id"),
211
+ version: text(check.version, "Root version"),
212
+ });
213
+ const declared = expectedRoots.get(key);
214
+ if (!declared || seenRoots.has(key))
215
+ fail("repair_reference_proof_invalid", "Root evidence names an undeclared or duplicate root.");
216
+ seenRoots.add(key);
217
+ if (check.status !== RETAINED_OK_STATUS)
218
+ fail("repair_reference_proof_invalid", "Root resolution evidence must be ok.");
219
+ if (check.exact_version !== check.version)
220
+ fail("repair_reference_proof_invalid", "Root resolution must bind the exact requested version.");
221
+ }
222
+ if (seenRoots.size !== input.roots.length)
223
+ fail("repair_reference_proof_invalid", "Every declared root requires its own resolution evidence.");
224
+ const proof = validateUniqueRootReadbacks({
225
+ intended: input.roots.map((root, index) => ({
226
+ rowIndex: index,
227
+ table: root.table,
228
+ id: root.id,
229
+ version: root.version,
230
+ payloadSha256: root.payload_sha256,
231
+ })),
232
+ checks: readbackChecks,
233
+ targetUserId: input.target_user_id,
234
+ expectedStateCode: input.expected_state_code,
235
+ // A repair never accepts a normalized reconstruction of the remote root payload.
236
+ allowTraceHashOnlyNormalization: false,
237
+ });
238
+ if (proof.blockers.length || proof.uniqueReadbackCount !== input.roots.length)
239
+ fail("repair_reference_proof_invalid", "Root readback proof rejected: the strict exact payload, owner and state rule must hold.");
240
+ // References: exactly one record per declared occurrence, in either the ok or the outdated state.
241
+ const seenReferences = new Set();
242
+ const outdated = [];
243
+ let okChecks = rootResolve.length + readbackChecks.length;
244
+ for (const check of referenceProbes) {
245
+ const rowIndex = count(check.row_index, "Reference row index");
246
+ const key = referenceKey({
247
+ row_index: rowIndex,
248
+ path: text(check.path, "Reference path"),
249
+ table: text(check.table, "Reference table"),
250
+ id: text(check.id, "Reference id"),
251
+ version: text(check.version, "Reference version"),
252
+ });
253
+ if (!expectedRefs.has(key))
254
+ fail("repair_reference_proof_invalid", "Reference evidence names an undeclared occurrence.");
255
+ if (seenReferences.has(key))
256
+ fail("repair_reference_proof_invalid", "Reference evidence repeats an occurrence exactly once each.");
257
+ seenReferences.add(key);
258
+ const version = text(check.version, "Reference version");
259
+ if (check.exact_version !== version)
260
+ fail("repair_reference_proof_invalid", "Every retained reference must resolve at its exact requested version.");
261
+ if (check.status === RETAINED_OK_STATUS) {
262
+ okChecks += 1;
263
+ continue;
264
+ }
265
+ if (check.status !== RETAINED_OUTDATED_STATUS)
266
+ fail("repair_reference_outdated_invalid", "A retained reference may only be ok or a version_outdated freshness finding.");
267
+ const latest = versionTriplet(check.latest_version, "Outdated reference");
268
+ if (compareVersions(latest, versionTriplet(version, "Outdated reference")) <= 0)
269
+ fail("repair_reference_outdated_invalid", "An outdated reference must name a strictly greater published version than the requested one.");
270
+ outdated.push({
271
+ row_index: rowIndex,
272
+ table: String(check.table),
273
+ id: String(check.id),
274
+ version,
275
+ latest_version: String(check.latest_version),
276
+ path: String(check.path),
277
+ });
278
+ }
279
+ if (outdated.length === 0)
280
+ fail("repair_reference_proof_invalid", "A blocked freshness report must contain an actual outdated reference finding.");
281
+ if (seenReferences.size !== input.references.length)
282
+ fail("repair_reference_proof_invalid", "Every declared reference requires its own evidence.");
283
+ if (okChecks !== byStatus[RETAINED_OK_STATUS])
284
+ fail("repair_reference_proof_invalid", "Report status buckets must agree with the check records they summarise.");
285
+ if (byStatus[RETAINED_OUTDATED_STATUS] !== outdated.length)
286
+ fail("repair_reference_proof_invalid", "Report status buckets must agree with the check records they summarise.");
287
+ for (const [bucket, value] of Object.entries(byStatus)) {
288
+ if (bucket === RETAINED_OK_STATUS || bucket === RETAINED_OUTDATED_STATUS)
289
+ continue;
290
+ if (value !== 0)
291
+ fail("repair_reference_proof_invalid", `Report status bucket ${bucket} must be zero for a retained-reference proof.`);
292
+ }
293
+ // Blockers: a strict bijection with the outdated findings, and nothing else.
294
+ const claimed = new Map();
295
+ for (const [index, value] of blockers.entries()) {
296
+ const blocker = record(value, `Blocker ${index + 1}`);
297
+ exactKeys(blocker, BLOCKER_KEYS, `Blocker ${index + 1}`);
298
+ if (blocker.code !== RETAINED_OUTDATED_STATUS || blocker.severity !== "error")
299
+ fail("repair_reference_proof_invalid", "A retained-reference proof admits only version_outdated blockers at error severity.");
300
+ if (blocker.role !== REFERENCE_ROLE)
301
+ fail("repair_reference_proof_invalid", "A version_outdated blocker must be on a reference role.");
302
+ const key = referenceKey({
303
+ row_index: count(blocker.row_index, "Blocker row index"),
304
+ path: text(blocker.path, "Blocker path"),
305
+ table: text(blocker.table, "Blocker table"),
306
+ id: text(blocker.id, "Blocker id"),
307
+ version: text(blocker.version, "Blocker version"),
308
+ });
309
+ claimed.set(key, (claimed.get(key) ?? 0) + 1);
310
+ const matches = outdated.filter((item) => referenceKey(item) === key);
311
+ if (matches.length !== 1 || claimed.get(key) !== 1)
312
+ fail("repair_reference_proof_invalid", "Every blocker must correspond to exactly one outdated reference check.");
313
+ if (matches[0].latest_version !== String(blocker.latest_version))
314
+ fail("repair_reference_proof_invalid", "Every blocker must correspond to exactly one outdated reference check.");
315
+ }
316
+ if (claimed.size !== outdated.length)
317
+ fail("repair_reference_proof_invalid", "Every blocker must correspond to exactly one outdated reference check.");
318
+ return Object.freeze({
319
+ schema: FOUNDRY_REPAIR_REFERENCE_PROOF_SCHEMA,
320
+ raw_status: status,
321
+ raw_blocker_count: rawBlockers,
322
+ counts: Object.freeze({ ...counts }),
323
+ root_readbacks: proof.uniqueReadbackCount,
324
+ references_verified: seenReferences.size,
325
+ ok_checks: okChecks,
326
+ outdated: Object.freeze(outdated.map((item) => Object.freeze({ ...item }))),
327
+ publication_ready: false,
328
+ });
329
+ }
@@ -0,0 +1,76 @@
1
+ type JsonRecord = Record<string, unknown>;
2
+ /** Phase 1 admits only Process, and only the two reviewed administrative display-text regions. */
3
+ export declare const FOUNDRY_REPAIR_SELECTION_KIND: "existing-owner-draft-metadata";
4
+ export declare const FOUNDRY_REPAIR_ALLOWED_DATASET_TYPE: "process";
5
+ export declare const FOUNDRY_REPAIR_EDIT_PATHS: readonly [string, string];
6
+ /**
7
+ * A repair touching any of these surfaces can change provider selection or scientific content, so it
8
+ * requires a content-bound provider-impact diagnostic that this repository does not produce yet.
9
+ */
10
+ export declare const FOUNDRY_REPAIR_SHARED_SCIENCE_PREFIXES: readonly ["processDataSet.exchanges", "processDataSet.quantitativeReference", "processDataSet.modellingAndValidation.dataSourcesTreatmentAndRepresentativeness.annualSupplyOrProductionVolume", "processDataSet.modellingAndValidation.LCIMethod", "processDataSet.processInformation.dataSetInformation.name", "processDataSet.processInformation.dataSetInformation.classificationInformation", "processDataSet.processInformation.dataSetInformation.common:other", "processDataSet.processInformation.geography", "processDataSet.administrativeInformation.publicationAndOwnership.common:dataSetVersion", "flowDataSet", "flowPropertyDataSet", "unitGroupDataSet"];
11
+ export interface FoundryRepairSelection {
12
+ readonly kind: typeof FOUNDRY_REPAIR_SELECTION_KIND;
13
+ readonly contract: string;
14
+ readonly before: string;
15
+ readonly candidate: string;
16
+ readonly predecessor: Readonly<{
17
+ task_id: string;
18
+ receipt_sha256: string;
19
+ }> | null;
20
+ }
21
+ export interface FoundryRepairDiffBlocker {
22
+ readonly path: string;
23
+ readonly reason: "provider_impact_diagnostics_missing" | "unsupported_path" | "structure_change";
24
+ }
25
+ export interface FoundryRepairScope {
26
+ readonly kind: typeof FOUNDRY_REPAIR_SELECTION_KIND;
27
+ readonly status: "dispatchable" | "satisfied";
28
+ readonly contract_sha256: string;
29
+ readonly rows_sha256: string;
30
+ readonly changed_paths: readonly string[];
31
+ readonly actions: readonly {
32
+ readonly action_id: string;
33
+ readonly table: string;
34
+ readonly id: string;
35
+ readonly version: string;
36
+ readonly before_sha256: string;
37
+ readonly desired_sha256: string;
38
+ }[];
39
+ }
40
+ /** Parse the optional repair selection of a task-start spec against the independently selected sources. */
41
+ export declare function parseFoundryRepairSelection(value: unknown, sources: readonly {
42
+ readonly path: string;
43
+ }[], resolveSelection?: (file: string) => string): Readonly<FoundryRepairSelection>;
44
+ /**
45
+ * Replace every allowlisted language-node `#text` with one sentinel in a clone of the payload, so that
46
+ * a structure-preserving text-only edit of those nodes disappears while every other difference -
47
+ * values, structure, node count and order, language tags, ids and URIs - survives the canonical hash.
48
+ */
49
+ export declare function blankRepairEditableText(payload: JsonRecord): JsonRecord;
50
+ /** Collect every leaf path where two payloads differ. Values are never included. */
51
+ export declare function collectRepairChangedPaths(before: unknown, after: unknown): string[];
52
+ /**
53
+ * Decide whether a before/candidate payload pair stays inside the phase-1 metadata allowlist: only the
54
+ * existing language nodes' `#text` inside the two reviewed regions may change. Everything else blocks,
55
+ * and a shared-science change reports the missing provider-impact diagnostic instead.
56
+ */
57
+ export declare function classifyRepairMetadataDiff(before: JsonRecord, after: JsonRecord): {
58
+ readonly allowed: boolean;
59
+ readonly blockers: readonly FoundryRepairDiffBlocker[];
60
+ };
61
+ /**
62
+ * Validate one repair task: the CLI execution contract, the CLI-fresh before rows and the candidate rows
63
+ * must agree on the exact same Process identities, every action must be a save_draft against an existing
64
+ * row, and the whole diff must stay inside the metadata allowlist. Nothing is dispatched here.
65
+ */
66
+ export declare function readFoundryRepairScope(input: {
67
+ contractFile: string;
68
+ beforeFile: string;
69
+ candidateFile: string;
70
+ datasetType: string;
71
+ targetUserId: string;
72
+ verifiedProjectRef: string;
73
+ stateCode: string;
74
+ relativePath: (file: string) => string;
75
+ }): Readonly<FoundryRepairScope>;
76
+ export {};