@granular-software/fractory 0.0.0-stage → 0.1.25

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 (285) hide show
  1. package/LICENSE +4 -0
  2. package/README.md +28 -2
  3. package/dist/activity-volume.d.ts +18 -0
  4. package/dist/activity-volume.js +94 -0
  5. package/dist/annotations.d.ts +122 -0
  6. package/dist/annotations.js +304 -0
  7. package/dist/benchmark-cli.d.ts +1 -0
  8. package/dist/benchmark-cli.js +95 -0
  9. package/dist/benchmark-worker.d.ts +2 -0
  10. package/dist/benchmark-worker.js +22 -0
  11. package/dist/benchmarks.d.ts +19 -0
  12. package/dist/benchmarks.js +414 -0
  13. package/dist/bin.d.ts +2 -0
  14. package/dist/bin.js +63 -0
  15. package/dist/block-cli.d.ts +1 -0
  16. package/dist/block-cli.js +88 -0
  17. package/dist/block-documents.d.ts +35 -0
  18. package/dist/block-documents.js +84 -0
  19. package/dist/change-impact.d.ts +55 -0
  20. package/dist/change-impact.js +223 -0
  21. package/dist/check-source.d.ts +2 -0
  22. package/dist/check-source.js +66 -0
  23. package/dist/checks-model.d.ts +64 -0
  24. package/dist/checks-model.js +36 -0
  25. package/dist/cli.d.ts +2 -0
  26. package/dist/cli.js +359 -0
  27. package/dist/code-model.d.ts +38 -0
  28. package/dist/code-model.js +94 -0
  29. package/dist/code-store.d.ts +9 -0
  30. package/dist/code-store.js +79 -0
  31. package/dist/compare-artifact.d.ts +6 -0
  32. package/dist/compare-artifact.js +277 -0
  33. package/dist/compare.d.ts +81 -0
  34. package/dist/compare.js +291 -0
  35. package/dist/compiler.d.ts +10 -0
  36. package/dist/compiler.js +1240 -0
  37. package/dist/compose.d.ts +9 -0
  38. package/dist/compose.js +72 -0
  39. package/dist/core.d.ts +87 -0
  40. package/dist/core.js +207 -0
  41. package/dist/coverage-cli.d.ts +1 -0
  42. package/dist/coverage-cli.js +42 -0
  43. package/dist/declaration-sources.d.ts +3 -0
  44. package/dist/declaration-sources.js +51 -0
  45. package/dist/declared-graph.d.ts +3 -0
  46. package/dist/declared-graph.js +67 -0
  47. package/dist/display-name.d.ts +2 -0
  48. package/dist/display-name.js +8 -0
  49. package/dist/error-heat.d.ts +58 -0
  50. package/dist/error-heat.js +96 -0
  51. package/dist/evidence.d.ts +3 -0
  52. package/dist/evidence.js +68 -0
  53. package/dist/factory-graph.d.ts +7 -0
  54. package/dist/factory-graph.js +389 -0
  55. package/dist/factory-model.d.ts +111 -0
  56. package/dist/factory-model.js +1 -0
  57. package/dist/git-code.d.ts +47 -0
  58. package/dist/git-code.js +352 -0
  59. package/dist/git-refs.d.ts +4 -0
  60. package/dist/git-refs.js +37 -0
  61. package/dist/history-activity.d.ts +4 -0
  62. package/dist/history-activity.js +129 -0
  63. package/dist/history-churn.d.ts +36 -0
  64. package/dist/history-churn.js +302 -0
  65. package/dist/history-git.d.ts +21 -0
  66. package/dist/history-git.js +125 -0
  67. package/dist/history-ledger.d.ts +43 -0
  68. package/dist/history-ledger.js +450 -0
  69. package/dist/history-ownership.d.ts +10 -0
  70. package/dist/history-ownership.js +75 -0
  71. package/dist/history-source.d.ts +13 -0
  72. package/dist/history-source.js +100 -0
  73. package/dist/integrations-cli.d.ts +2 -0
  74. package/dist/integrations-cli.js +159 -0
  75. package/dist/interface-map.d.ts +15 -0
  76. package/dist/interface-map.js +125 -0
  77. package/dist/issue-cache.d.ts +9 -0
  78. package/dist/issue-cache.js +68 -0
  79. package/dist/issue-cli.d.ts +1 -0
  80. package/dist/issue-cli.js +89 -0
  81. package/dist/issue-links.d.ts +15 -0
  82. package/dist/issue-links.js +125 -0
  83. package/dist/linear-issues.d.ts +19 -0
  84. package/dist/linear-issues.js +124 -0
  85. package/dist/local-runtime.d.ts +8 -0
  86. package/dist/local-runtime.js +59 -0
  87. package/dist/map-activity.d.ts +73 -0
  88. package/dist/map-activity.js +234 -0
  89. package/dist/map-model.d.ts +5 -0
  90. package/dist/map-model.js +166 -0
  91. package/dist/map-quality.d.ts +20 -0
  92. package/dist/map-quality.js +61 -0
  93. package/dist/mapping-coverage.d.ts +87 -0
  94. package/dist/mapping-coverage.js +404 -0
  95. package/dist/model.d.ts +186 -0
  96. package/dist/model.js +66 -0
  97. package/dist/operation-benchmark-worker.d.ts +2 -0
  98. package/dist/operation-benchmark-worker.js +60 -0
  99. package/dist/operation-benchmark.d.ts +29 -0
  100. package/dist/operation-benchmark.js +1 -0
  101. package/dist/otel-metrics.d.ts +21 -0
  102. package/dist/otel-metrics.js +146 -0
  103. package/dist/performance-model.d.ts +185 -0
  104. package/dist/performance-model.js +396 -0
  105. package/dist/product-map.d.ts +71 -0
  106. package/dist/product-map.js +197 -0
  107. package/dist/provider-access.cjs +207 -0
  108. package/dist/provider-access.d.cts +14 -0
  109. package/dist/public-boundaries.d.ts +13 -0
  110. package/dist/public-boundaries.js +115 -0
  111. package/dist/reports-cli.d.ts +1 -0
  112. package/dist/reports-cli.js +111 -0
  113. package/dist/reports-model.d.ts +27 -0
  114. package/dist/reports-model.js +39 -0
  115. package/dist/reports.d.ts +23 -0
  116. package/dist/reports.js +223 -0
  117. package/dist/repository-map.d.ts +22 -0
  118. package/dist/repository-map.js +153 -0
  119. package/dist/resource-cache.d.ts +17 -0
  120. package/dist/resource-cache.js +65 -0
  121. package/dist/review-cli.d.ts +19 -0
  122. package/dist/review-cli.js +224 -0
  123. package/dist/review.d.ts +48 -0
  124. package/dist/review.js +289 -0
  125. package/dist/runtime-metrics.d.ts +26 -0
  126. package/dist/runtime-metrics.js +290 -0
  127. package/dist/scope.d.ts +14 -0
  128. package/dist/scope.js +168 -0
  129. package/dist/sentry-activity.d.ts +39 -0
  130. package/dist/sentry-activity.js +174 -0
  131. package/dist/sentry.d.ts +130 -0
  132. package/dist/sentry.js +369 -0
  133. package/dist/service-release.d.ts +16 -0
  134. package/dist/service-release.js +14 -0
  135. package/dist/setup-cli.d.ts +2 -0
  136. package/dist/setup-cli.js +52 -0
  137. package/dist/setup-kit.cjs +163 -0
  138. package/dist/setup-kit.d.cts +32 -0
  139. package/dist/source-index.d.ts +37 -0
  140. package/dist/source-index.js +170 -0
  141. package/dist/source-review-git.d.ts +7 -0
  142. package/dist/source-review-git.js +105 -0
  143. package/dist/source-review.d.ts +18 -0
  144. package/dist/source-review.js +573 -0
  145. package/dist/telemetry.d.ts +17 -0
  146. package/dist/telemetry.js +51 -0
  147. package/dist/time-window.d.ts +9 -0
  148. package/dist/time-window.js +35 -0
  149. package/dist/trace-evidence.d.ts +23 -0
  150. package/dist/trace-evidence.js +55 -0
  151. package/dist/trace-model.d.ts +26 -0
  152. package/dist/trace-model.js +1 -0
  153. package/dist/tracing.d.ts +44 -0
  154. package/dist/tracing.js +123 -0
  155. package/dist/work-check.d.ts +18 -0
  156. package/dist/work-check.js +115 -0
  157. package/dist/work-cli.d.ts +1 -0
  158. package/dist/work-cli.js +176 -0
  159. package/dist/work-context.d.ts +59 -0
  160. package/dist/work-context.js +594 -0
  161. package/dist/work-intents.d.ts +6 -0
  162. package/dist/work-intents.js +140 -0
  163. package/dist/work-items.d.ts +58 -0
  164. package/dist/work-items.js +86 -0
  165. package/dist/work-lock-check.d.ts +12 -0
  166. package/dist/work-lock-check.js +339 -0
  167. package/dist/work-locks.d.ts +10 -0
  168. package/dist/work-locks.js +98 -0
  169. package/dist/work-model.d.ts +119 -0
  170. package/dist/work-model.js +310 -0
  171. package/dist/work-review-git.d.ts +8 -0
  172. package/dist/work-review-git.js +111 -0
  173. package/dist/work-review.d.ts +26 -0
  174. package/dist/work-review.js +426 -0
  175. package/dist/work-switcher-model.d.ts +43 -0
  176. package/dist/work-switcher-model.js +79 -0
  177. package/dist/work-switcher.d.ts +6 -0
  178. package/dist/work-switcher.js +171 -0
  179. package/dist/working-cli.d.ts +1 -0
  180. package/dist/working-cli.js +33 -0
  181. package/dist/working-code.d.ts +74 -0
  182. package/dist/working-code.js +421 -0
  183. package/dist/workspace-notes.d.ts +71 -0
  184. package/dist/workspace-notes.js +177 -0
  185. package/dist/workspace-tests.d.ts +21 -0
  186. package/dist/workspace-tests.js +573 -0
  187. package/package.json +547 -4
  188. package/src/activity-volume.ts +149 -0
  189. package/src/annotations.ts +485 -0
  190. package/src/benchmark-cli.ts +118 -0
  191. package/src/benchmark-worker.ts +22 -0
  192. package/src/benchmarks.ts +493 -0
  193. package/src/bin.ts +54 -0
  194. package/src/block-cli.ts +106 -0
  195. package/src/block-documents.ts +117 -0
  196. package/src/change-impact.ts +280 -0
  197. package/src/check-source.ts +82 -0
  198. package/src/checks-model.ts +108 -0
  199. package/src/cli.ts +440 -0
  200. package/src/code-model.ts +159 -0
  201. package/src/code-store.ts +98 -0
  202. package/src/compare-artifact.ts +314 -0
  203. package/src/compare.ts +440 -0
  204. package/src/compiler.ts +1512 -0
  205. package/src/compose.ts +94 -0
  206. package/src/core.ts +361 -0
  207. package/src/coverage-cli.ts +52 -0
  208. package/src/declaration-sources.ts +69 -0
  209. package/src/declared-graph.ts +75 -0
  210. package/src/display-name.ts +8 -0
  211. package/src/error-heat.ts +161 -0
  212. package/src/evidence.ts +94 -0
  213. package/src/factory-graph.ts +462 -0
  214. package/src/factory-model.ts +82 -0
  215. package/src/git-code.ts +461 -0
  216. package/src/git-refs.ts +43 -0
  217. package/src/history-activity.ts +146 -0
  218. package/src/history-churn.ts +416 -0
  219. package/src/history-git.ts +163 -0
  220. package/src/history-ledger.ts +636 -0
  221. package/src/history-ownership.ts +116 -0
  222. package/src/history-source.ts +117 -0
  223. package/src/integrations-cli.ts +187 -0
  224. package/src/interface-map.ts +166 -0
  225. package/src/issue-cache.ts +96 -0
  226. package/src/issue-cli.ts +137 -0
  227. package/src/issue-links.ts +153 -0
  228. package/src/linear-issues.ts +154 -0
  229. package/src/local-runtime.ts +70 -0
  230. package/src/map-activity.ts +309 -0
  231. package/src/map-model.ts +213 -0
  232. package/src/map-quality.ts +66 -0
  233. package/src/mapping-coverage.ts +570 -0
  234. package/src/model.ts +228 -0
  235. package/src/operation-benchmark-worker.ts +60 -0
  236. package/src/operation-benchmark.ts +28 -0
  237. package/src/otel-metrics.ts +176 -0
  238. package/src/performance-model.ts +575 -0
  239. package/src/product-map.ts +271 -0
  240. package/src/provider-access.cjs +207 -0
  241. package/src/provider-access.d.cts +14 -0
  242. package/src/public-boundaries.ts +143 -0
  243. package/src/reports-cli.ts +125 -0
  244. package/src/reports-model.ts +73 -0
  245. package/src/reports.ts +276 -0
  246. package/src/repository-map.ts +191 -0
  247. package/src/resource-cache.ts +76 -0
  248. package/src/review-cli.ts +256 -0
  249. package/src/review.ts +376 -0
  250. package/src/runtime-metrics.ts +386 -0
  251. package/src/scope.ts +192 -0
  252. package/src/sentry-activity.ts +234 -0
  253. package/src/sentry.ts +545 -0
  254. package/src/service-release.ts +18 -0
  255. package/src/setup-cli.ts +58 -0
  256. package/src/setup-kit.cjs +163 -0
  257. package/src/setup-kit.d.cts +32 -0
  258. package/src/source-index.ts +208 -0
  259. package/src/source-review-git.ts +131 -0
  260. package/src/source-review.ts +736 -0
  261. package/src/telemetry.ts +68 -0
  262. package/src/time-window.ts +51 -0
  263. package/src/trace-evidence.ts +80 -0
  264. package/src/trace-model.ts +26 -0
  265. package/src/tracing.ts +165 -0
  266. package/src/work-check.ts +149 -0
  267. package/src/work-cli.ts +229 -0
  268. package/src/work-context.ts +753 -0
  269. package/src/work-intents.ts +196 -0
  270. package/src/work-items.ts +151 -0
  271. package/src/work-lock-check.ts +549 -0
  272. package/src/work-locks.ts +108 -0
  273. package/src/work-model.ts +466 -0
  274. package/src/work-review-git.ts +130 -0
  275. package/src/work-review.ts +573 -0
  276. package/src/work-switcher-model.ts +121 -0
  277. package/src/work-switcher.ts +191 -0
  278. package/src/working-cli.ts +38 -0
  279. package/src/working-code.ts +582 -0
  280. package/src/workspace-notes.ts +203 -0
  281. package/src/workspace-tests.ts +654 -0
  282. package/toolkit/GUIDE.md +354 -0
  283. package/toolkit/SKILL.md +142 -0
  284. package/toolkit/bin/fractory +2 -0
  285. package/toolkit/build.json +1 -0
@@ -0,0 +1,68 @@
1
+ /** Node/Cloudflare nodejs_compat host adapter. The annotation SDK itself stays portable. */
2
+ import { AsyncLocalStorage } from "node:async_hooks";
3
+ import {
4
+ installFactoryHost,
5
+ type FactoryFrame,
6
+ type FactoryEvent,
7
+ } from "./annotations";
8
+ import { commitFromRelease } from "./code-model";
9
+
10
+ interface MetricOptions {
11
+ attributes: Record<string, string>;
12
+ }
13
+ export function installFactoryTelemetry(options: {
14
+ service: string;
15
+ context?: () => unknown;
16
+ codeRevision?: () => string | undefined;
17
+ count(name: string, value: number, options: MetricOptions): void;
18
+ distribution(
19
+ name: string,
20
+ value: number,
21
+ options: MetricOptions & { unit: string },
22
+ ): void;
23
+ /** Detailed traces can be sampled independently of aggregate counters. */
24
+ trace?: (event: FactoryEvent) => void;
25
+ metrics?: (event: FactoryEvent) => void;
26
+ }) {
27
+ const scope = new AsyncLocalStorage<FactoryFrame>();
28
+ return installFactoryHost({
29
+ current: () => scope.getStore(),
30
+ run: (frame, execute) => scope.run(frame, execute),
31
+ context: options.context,
32
+ codeRevision: () => commitFromRelease(options.codeRevision?.()),
33
+ emit(event) {
34
+ try {
35
+ options.metrics?.(event);
36
+ } catch {
37
+ /* aggregate metrics never affect execution */
38
+ }
39
+ const attributes = {
40
+ service: options.service,
41
+ block: event.blockId,
42
+ interface: event.interfaceId || "",
43
+ method: event.method,
44
+ outcome: event.status,
45
+ };
46
+ try {
47
+ options.count(`fractal.boundary.${event.status}`, 1, { attributes });
48
+ } catch {
49
+ /* independent sink */
50
+ }
51
+ if (event.durationMs !== undefined) {
52
+ try {
53
+ options.distribution("fractal.boundary.duration", event.durationMs, {
54
+ attributes,
55
+ unit: "millisecond",
56
+ });
57
+ } catch {
58
+ /* independent sink */
59
+ }
60
+ }
61
+ try {
62
+ options.trace?.(event);
63
+ } catch {
64
+ /* observational */
65
+ }
66
+ },
67
+ });
68
+ }
@@ -0,0 +1,51 @@
1
+ /** Shared UTC, half-open time interval: from inclusive, to exclusive. */
2
+ export interface TimeWindow {
3
+ from: string;
4
+ to: string;
5
+ }
6
+ export const DAY_MS = 86_400_000;
7
+ export function recentWindow(days = 14, now = Date.now()): TimeWindow {
8
+ const end = Math.floor(now / 60_000) * 60_000;
9
+ return {
10
+ from: new Date(end - days * DAY_MS).toISOString(),
11
+ to: new Date(end).toISOString(),
12
+ };
13
+ }
14
+ export function parseTimeWindow(
15
+ params: Pick<URLSearchParams, "get">,
16
+ now = Date.now(),
17
+ maxDays = 90,
18
+ ): TimeWindow | undefined {
19
+ const from = params.get("from"),
20
+ to = params.get("to");
21
+ if (from === null && to === null) return;
22
+ const start = from && Date.parse(from),
23
+ end = to && Date.parse(to);
24
+ if (
25
+ !from ||
26
+ !to ||
27
+ !/^\d{4}-\d{2}-\d{2}T/.test(from) ||
28
+ !/^\d{4}-\d{2}-\d{2}T/.test(to) ||
29
+ !Number.isFinite(start) ||
30
+ !Number.isFinite(end) ||
31
+ Number(start) < 0 ||
32
+ Number(start) >= Number(end) ||
33
+ Number(end) > now + 60_000 ||
34
+ Number(end) - Number(start) > maxDays * DAY_MS + 1000
35
+ )
36
+ throw Error(
37
+ `Choose a valid time range of up to ${maxDays} days, ending no later than now.`,
38
+ );
39
+ return {
40
+ from: new Date(Number(start)).toISOString(),
41
+ to: new Date(Number(end)).toISOString(),
42
+ };
43
+ }
44
+ export function inTimeWindow(at: string | undefined, window: TimeWindow) {
45
+ const value = Date.parse(at || "");
46
+ return (
47
+ Number.isFinite(value) &&
48
+ value >= Date.parse(window.from) &&
49
+ value < Date.parse(window.to)
50
+ );
51
+ }
@@ -0,0 +1,80 @@
1
+ import type { DefinitionGraph, Connection } from "./model";
2
+ import type { TraceSnapshot, TraceEvent } from "./trace-model";
3
+
4
+ export interface ObservedSpan {
5
+ spanId: string;
6
+ traceId: string;
7
+ elementId: string;
8
+ contract: string;
9
+ parentSpanId?: string;
10
+ linkedSpanId?: string;
11
+ linkedTraceId?: string;
12
+ timestamp: number;
13
+ durationMs?: number;
14
+ jobStatus?: string;
15
+ status: TraceEvent["status"];
16
+ failureCode?: TraceEvent["failureCode"];
17
+ startObserved: boolean;
18
+ }
19
+ /** Only compatible, recorded spans can color the graph. State alone never creates a span. */
20
+ export function executionPath(
21
+ graph: DefinitionGraph,
22
+ snapshot: Pick<TraceSnapshot, "events"> | null | undefined,
23
+ ) {
24
+ const byId = new Map(graph.elements.map((n) => [n.id, n]));
25
+ const spans = new Map<string, ObservedSpan>();
26
+ let incompatibleEvents = 0;
27
+ for (const event of snapshot?.events || []) {
28
+ const node = byId.get(event.elementId);
29
+ if (
30
+ event.definitionRevision !==
31
+ (node?.definitionRevision || graph.revision) ||
32
+ node?.contract?.id !== event.contract ||
33
+ (graph.codeRevision !== undefined &&
34
+ event.codeRevision !== graph.codeRevision)
35
+ ) {
36
+ incompatibleEvents++;
37
+ continue;
38
+ }
39
+ const previous = spans.get(event.spanId);
40
+ spans.set(event.spanId, {
41
+ spanId: event.spanId,
42
+ traceId: event.traceId,
43
+ elementId: event.elementId,
44
+ contract: event.contract,
45
+ parentSpanId: event.parentSpanId,
46
+ linkedSpanId: event.linkedSpanId,
47
+ linkedTraceId: event.linkedTraceId,
48
+ status: event.status,
49
+ durationMs: event.durationMs,
50
+ failureCode: event.failureCode,
51
+ jobStatus: event.jobStatus,
52
+ timestamp: previous?.timestamp ?? event.timestamp,
53
+ startObserved: previous?.startObserved || event.status === "started",
54
+ });
55
+ }
56
+ const connections: Connection[] = [];
57
+ for (const span of spans.values()) {
58
+ const parent = spans.get(span.parentSpanId || span.linkedSpanId || "");
59
+ if (
60
+ !parent ||
61
+ (span.parentSpanId
62
+ ? parent.traceId !== span.traceId
63
+ : parent.traceId !== span.linkedTraceId)
64
+ )
65
+ continue;
66
+ connections.push({
67
+ id: `observed:${span.spanId}`,
68
+ source: parent.elementId,
69
+ target: span.elementId,
70
+ relation: span.parentSpanId ? "calls" : "resumes",
71
+ label: `${span.parentSpanId ? "" : "Continuation · "}${span.contract} · ${span.jobStatus === "failed" ? "job failed" : span.status}`,
72
+ provenance: "observed",
73
+ });
74
+ }
75
+ return {
76
+ spans: [...spans.values()].sort((a, b) => a.timestamp - b.timestamp),
77
+ connections,
78
+ incompatibleEvents,
79
+ };
80
+ }
@@ -0,0 +1,26 @@
1
+ /** Safe, payload-free records emitted only when a decorated boundary executes. */
2
+ export interface TraceEvent {
3
+ id: string;
4
+ traceId: string;
5
+ spanId: string;
6
+ parentSpanId?: string;
7
+ linkedSpanId?: string;
8
+ linkedTraceId?: string;
9
+ elementId: string;
10
+ contract: string;
11
+ definitionRevision: string;
12
+ codeRevision?: string;
13
+ timestamp: number;
14
+ durationMs?: number;
15
+ /** Persisted job state observed at the boundary; distinct from the method outcome. */
16
+ jobStatus?: string;
17
+ status: "started" | "completed" | "failed";
18
+ failureCode?: "InvalidInput" | "InvalidOutput" | "OperationFailed";
19
+ }
20
+ export interface TraceSnapshot {
21
+ schema: "fractal.trace.v1";
22
+ jobId: string;
23
+ events: TraceEvent[];
24
+ droppedEvents: number;
25
+ persistence: "available" | "degraded";
26
+ }
package/src/tracing.ts ADDED
@@ -0,0 +1,165 @@
1
+ import type { OperationRuntime } from "./core";
2
+ import { ContractViolation } from "./core";
3
+ import type { TraceEvent } from "./trace-model";
4
+
5
+ export interface TraceLink {
6
+ traceId: string;
7
+ spanId: string;
8
+ definitionRevision: string;
9
+ }
10
+ export interface TraceFrame {
11
+ owner: object;
12
+ traceId: string;
13
+ spanId?: string;
14
+ linkedSpanId?: string;
15
+ linkedTraceId?: string;
16
+ correlation: { jobId?: string; pending: TraceEvent[] };
17
+ }
18
+ export interface AsyncTraceScope {
19
+ getStore(): TraceFrame | undefined;
20
+ run<T>(frame: TraceFrame, callback: () => T): T;
21
+ }
22
+ /** Async context is supplied by the host; the core remains usable in a browser. */
23
+ export class TraceRuntime implements OperationRuntime {
24
+ constructor(
25
+ private readonly options: {
26
+ owner: object;
27
+ definitionRevision: string;
28
+ codeRevision?: string;
29
+ scope: AsyncTraceScope;
30
+ emit: (jobId: string, event: TraceEvent) => void;
31
+ observeJobStatus?: (
32
+ jobId: string,
33
+ contract: string,
34
+ ) => string | undefined;
35
+ },
36
+ ) {}
37
+ root<T>(
38
+ jobId: string | undefined,
39
+ predecessor: TraceLink | undefined,
40
+ execute: () => Promise<T>,
41
+ fresh = false,
42
+ ): Promise<T> {
43
+ const current = this.current();
44
+ if (current && !fresh) {
45
+ if (!jobId || current.correlation.jobId === jobId) return execute();
46
+ if (!current.correlation.jobId) {
47
+ this.associate(jobId);
48
+ return execute();
49
+ }
50
+ }
51
+ const frame: TraceFrame = {
52
+ owner: this.options.owner,
53
+ traceId: crypto.randomUUID(),
54
+ linkedSpanId: predecessor?.spanId,
55
+ linkedTraceId: predecessor?.traceId,
56
+ correlation: { jobId, pending: [] },
57
+ };
58
+ return this.options.scope.run(frame, execute);
59
+ }
60
+ private current() {
61
+ const frame = this.options.scope.getStore();
62
+ return frame?.owner === this.options.owner ? frame : undefined;
63
+ }
64
+ associate(jobId: string) {
65
+ const frame = this.current();
66
+ if (!frame) throw new Error("Job correlation requires an active trace");
67
+ if (frame.correlation.jobId && frame.correlation.jobId !== jobId)
68
+ throw new Error("A trace cannot change job identity");
69
+ frame.correlation.jobId = jobId;
70
+ for (const event of frame.correlation.pending.splice(0))
71
+ this.emit(jobId, event);
72
+ }
73
+ reference(): TraceLink | undefined {
74
+ const frame = this.current();
75
+ return frame?.spanId
76
+ ? {
77
+ traceId: frame.traceId,
78
+ spanId: frame.spanId,
79
+ definitionRevision: this.options.definitionRevision,
80
+ }
81
+ : undefined;
82
+ }
83
+ private emit(jobId: string, event: TraceEvent) {
84
+ try {
85
+ this.options.emit(jobId, event);
86
+ } catch {
87
+ /* Observation cannot change execution semantics. */
88
+ }
89
+ }
90
+ invoke<T>(
91
+ boundary: { elementId: string; operation: string; contract: string },
92
+ execute: () => Promise<T>,
93
+ ): Promise<T> {
94
+ const parent = this.current();
95
+ if (!parent)
96
+ return this.root(undefined, undefined, () =>
97
+ this.invoke(boundary, execute),
98
+ );
99
+ const spanId = crypto.randomUUID();
100
+ const frame: TraceFrame = { ...parent, spanId };
101
+ const started = performance.now();
102
+ const publish = (
103
+ status: TraceEvent["status"],
104
+ failureCode?: TraceEvent["failureCode"],
105
+ ) => {
106
+ let jobStatus: string | undefined;
107
+ if (status !== "started" && frame.correlation.jobId) {
108
+ try {
109
+ jobStatus = this.options.observeJobStatus?.(
110
+ frame.correlation.jobId,
111
+ boundary.contract,
112
+ );
113
+ } catch {
114
+ /* observation only */
115
+ }
116
+ }
117
+ const event: TraceEvent = {
118
+ id: crypto.randomUUID(),
119
+ traceId: frame.traceId,
120
+ spanId,
121
+ ...(parent.spanId ? { parentSpanId: parent.spanId } : {}),
122
+ ...(!parent.spanId && parent.linkedSpanId
123
+ ? {
124
+ linkedSpanId: parent.linkedSpanId,
125
+ linkedTraceId: parent.linkedTraceId,
126
+ }
127
+ : {}),
128
+ elementId: boundary.elementId,
129
+ contract: boundary.contract,
130
+ definitionRevision: this.options.definitionRevision,
131
+ ...(this.options.codeRevision
132
+ ? { codeRevision: this.options.codeRevision }
133
+ : {}),
134
+ timestamp: Date.now(),
135
+ status,
136
+ ...(status !== "started"
137
+ ? { durationMs: performance.now() - started }
138
+ : {}),
139
+ ...(failureCode ? { failureCode } : {}),
140
+ ...(jobStatus ? { jobStatus } : {}),
141
+ };
142
+ if (frame.correlation.jobId) this.emit(frame.correlation.jobId, event);
143
+ else if (frame.correlation.pending.length < 64)
144
+ frame.correlation.pending.push(event);
145
+ };
146
+ return this.options.scope.run(frame, async () => {
147
+ publish("started");
148
+ try {
149
+ const value = await execute();
150
+ publish("completed");
151
+ return value;
152
+ } catch (error) {
153
+ publish(
154
+ "failed",
155
+ error instanceof ContractViolation
156
+ ? error.phase === "input"
157
+ ? "InvalidInput"
158
+ : "InvalidOutput"
159
+ : "OperationFailed",
160
+ );
161
+ throw error;
162
+ }
163
+ });
164
+ }
165
+ }
@@ -0,0 +1,149 @@
1
+ import { blockNoteFile } from "./workspace-notes";
2
+ import { readReport } from "./reports";
3
+ import type { DefinitionGraph } from "./model";
4
+ import { changedPaths } from "./git-code";
5
+ import { readGit, resolveComparisonRef } from "./git-refs";
6
+ import { parseWorkingStatus } from "./working-code";
7
+ import { readWorkPlan, workBaseline } from "./work-context";
8
+ import { scopeBlocks } from "./work-model";
9
+ import { checkWorkLocks } from "./work-lock-check";
10
+
11
+ /** Conservative file ownership check. Shared and unknown ownership never produce a pass. */
12
+ export async function checkWorkScope(
13
+ root: string,
14
+ id: string,
15
+ currentGraph: DefinitionGraph,
16
+ ) {
17
+ const { entry, plan } = readWorkPlan(root, id);
18
+ const baseline = workBaseline(root, id);
19
+ const head = resolveComparisonRef(entry.root, "HEAD");
20
+ const committed = changedPaths(entry.root, plan.baseCommit, head).map(
21
+ (file) => file.path,
22
+ );
23
+ const working = parseWorkingStatus(
24
+ readGit(entry.root, [
25
+ "status",
26
+ "--porcelain=v2",
27
+ "-z",
28
+ "--untracked-files=all",
29
+ ]),
30
+ );
31
+ const paths = [
32
+ ...new Set([
33
+ ...committed,
34
+ ...working.flatMap((path) => [
35
+ path.path,
36
+ ...(path.originalPath ? [path.originalPath] : []),
37
+ ]),
38
+ ]),
39
+ ].sort();
40
+ if (paths.length > 20000)
41
+ throw Error("Scope check exceeds the path budget; no pass was issued.");
42
+ const allowed = scopeBlocks(currentGraph, plan.scope, plan.excluded);
43
+ const baseAllowed = scopeBlocks(baseline, plan.scope, plan.excluded);
44
+ function owners(graph: DefinitionGraph, path: string) {
45
+ if (/^docs\/fractory\/reports\/[a-f0-9-]{36}\.md$/.test(path))
46
+ try {
47
+ const report = readReport(
48
+ entry.root,
49
+ path.split("/").at(-1)!.slice(0, -3),
50
+ graph === baseline ? plan.baseCommit : undefined,
51
+ );
52
+ return report.blocks.filter((id) =>
53
+ graph.elements.some((n) => n.id === id),
54
+ );
55
+ } catch {}
56
+
57
+ const candidates = graph.elements.filter(
58
+ (node) =>
59
+ (node.sources || (node.source ? [node.source] : [])).some(
60
+ (source) =>
61
+ source.file === path ||
62
+ (path.endsWith("/") && source.file.startsWith(path)),
63
+ ) ||
64
+ (node.attachments?.tests || []).includes(path) ||
65
+ (node.attachments?.docs || []).includes(path) ||
66
+ blockNoteFile(node.id) === path ||
67
+ path.startsWith(blockNoteFile(node.id).replace(/\.md$/, "/")),
68
+ );
69
+ for (const test of graph.tests.filter((test) => test.source.file === path))
70
+ for (const target of test.targets) {
71
+ const node = graph.elements.find((node) => node.id === target);
72
+ if (node && !candidates.some((item) => item.id === node.id))
73
+ candidates.push(node);
74
+ }
75
+ // Parent sources often describe the same module; the most specific mapped owners decide.
76
+ return candidates
77
+ .filter(
78
+ (node) =>
79
+ !candidates.some(
80
+ (other) =>
81
+ other.id !== node.id && isAncestor(graph, node.id, other.id),
82
+ ),
83
+ )
84
+ .map((node) => node.id);
85
+ }
86
+ const files = paths.map((path) => {
87
+ if (
88
+ [
89
+ ".agents/skills/fractory/SKILL.md",
90
+ ".agents/skills/fractory/references/fractory-guide.md",
91
+ ].includes(path)
92
+ )
93
+ return { path, status: "setup" as const, blocks: [] };
94
+ if (path === entry.planFile)
95
+ return {
96
+ path,
97
+ status: "plan" as const,
98
+ blocks: [graphRoot(currentGraph)],
99
+ };
100
+ const baseOwners = owners(baseline, path);
101
+ const selected = baseOwners.length ? baseAllowed : allowed;
102
+ const blocks = baseOwners.length ? baseOwners : owners(currentGraph, path);
103
+ const inside = blocks.filter((block) => selected.has(block));
104
+ const status = !blocks.length
105
+ ? "unassigned"
106
+ : !inside.length
107
+ ? "outside"
108
+ : inside.length !== blocks.length
109
+ ? "shared"
110
+ : "inside";
111
+ return { path, status, blocks };
112
+ });
113
+ const uncertain = files.filter((file) =>
114
+ ["unassigned", "shared"].includes(file.status),
115
+ );
116
+ const outside = files.filter((file) => file.status === "outside");
117
+ const locks = checkWorkLocks(entry.root, plan, baseline, currentGraph, paths);
118
+ return {
119
+ work: id,
120
+ base: plan.baseCommit,
121
+ head,
122
+ pass:
123
+ !outside.length &&
124
+ !uncertain.length &&
125
+ locks.every((l) => l.status === "unchanged"),
126
+ locks,
127
+ files,
128
+ outside: outside.length,
129
+ uncertain: uncertain.length,
130
+ basis: "pinned-file-ownership",
131
+ notice:
132
+ "File ownership is conservative: shared and unassigned files require review. This check is not a filesystem sandbox or a protected-branch rule.",
133
+ };
134
+ }
135
+ function graphRoot(graph: DefinitionGraph) {
136
+ return graph.id;
137
+ }
138
+
139
+ function isAncestor(graph: DefinitionGraph, parent: string, child: string) {
140
+ const byId = new Map(graph.elements.map((n) => [n.id, n]));
141
+ const seen = new Set<string>();
142
+ let id: string | undefined = child;
143
+ while (id && !seen.has(id)) {
144
+ if (id === parent) return true;
145
+ seen.add(id);
146
+ id = byId.get(id)?.parent;
147
+ }
148
+ return false;
149
+ }