@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.
- package/LICENSE +4 -0
- package/README.md +28 -2
- package/dist/activity-volume.d.ts +18 -0
- package/dist/activity-volume.js +94 -0
- package/dist/annotations.d.ts +122 -0
- package/dist/annotations.js +304 -0
- package/dist/benchmark-cli.d.ts +1 -0
- package/dist/benchmark-cli.js +95 -0
- package/dist/benchmark-worker.d.ts +2 -0
- package/dist/benchmark-worker.js +22 -0
- package/dist/benchmarks.d.ts +19 -0
- package/dist/benchmarks.js +414 -0
- package/dist/bin.d.ts +2 -0
- package/dist/bin.js +63 -0
- package/dist/block-cli.d.ts +1 -0
- package/dist/block-cli.js +88 -0
- package/dist/block-documents.d.ts +35 -0
- package/dist/block-documents.js +84 -0
- package/dist/change-impact.d.ts +55 -0
- package/dist/change-impact.js +223 -0
- package/dist/check-source.d.ts +2 -0
- package/dist/check-source.js +66 -0
- package/dist/checks-model.d.ts +64 -0
- package/dist/checks-model.js +36 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +359 -0
- package/dist/code-model.d.ts +38 -0
- package/dist/code-model.js +94 -0
- package/dist/code-store.d.ts +9 -0
- package/dist/code-store.js +79 -0
- package/dist/compare-artifact.d.ts +6 -0
- package/dist/compare-artifact.js +277 -0
- package/dist/compare.d.ts +81 -0
- package/dist/compare.js +291 -0
- package/dist/compiler.d.ts +10 -0
- package/dist/compiler.js +1240 -0
- package/dist/compose.d.ts +9 -0
- package/dist/compose.js +72 -0
- package/dist/core.d.ts +87 -0
- package/dist/core.js +207 -0
- package/dist/coverage-cli.d.ts +1 -0
- package/dist/coverage-cli.js +42 -0
- package/dist/declaration-sources.d.ts +3 -0
- package/dist/declaration-sources.js +51 -0
- package/dist/declared-graph.d.ts +3 -0
- package/dist/declared-graph.js +67 -0
- package/dist/display-name.d.ts +2 -0
- package/dist/display-name.js +8 -0
- package/dist/error-heat.d.ts +58 -0
- package/dist/error-heat.js +96 -0
- package/dist/evidence.d.ts +3 -0
- package/dist/evidence.js +68 -0
- package/dist/factory-graph.d.ts +7 -0
- package/dist/factory-graph.js +389 -0
- package/dist/factory-model.d.ts +111 -0
- package/dist/factory-model.js +1 -0
- package/dist/git-code.d.ts +47 -0
- package/dist/git-code.js +352 -0
- package/dist/git-refs.d.ts +4 -0
- package/dist/git-refs.js +37 -0
- package/dist/history-activity.d.ts +4 -0
- package/dist/history-activity.js +129 -0
- package/dist/history-churn.d.ts +36 -0
- package/dist/history-churn.js +302 -0
- package/dist/history-git.d.ts +21 -0
- package/dist/history-git.js +125 -0
- package/dist/history-ledger.d.ts +43 -0
- package/dist/history-ledger.js +450 -0
- package/dist/history-ownership.d.ts +10 -0
- package/dist/history-ownership.js +75 -0
- package/dist/history-source.d.ts +13 -0
- package/dist/history-source.js +100 -0
- package/dist/integrations-cli.d.ts +2 -0
- package/dist/integrations-cli.js +159 -0
- package/dist/interface-map.d.ts +15 -0
- package/dist/interface-map.js +125 -0
- package/dist/issue-cache.d.ts +9 -0
- package/dist/issue-cache.js +68 -0
- package/dist/issue-cli.d.ts +1 -0
- package/dist/issue-cli.js +89 -0
- package/dist/issue-links.d.ts +15 -0
- package/dist/issue-links.js +125 -0
- package/dist/linear-issues.d.ts +19 -0
- package/dist/linear-issues.js +124 -0
- package/dist/local-runtime.d.ts +8 -0
- package/dist/local-runtime.js +59 -0
- package/dist/map-activity.d.ts +73 -0
- package/dist/map-activity.js +234 -0
- package/dist/map-model.d.ts +5 -0
- package/dist/map-model.js +166 -0
- package/dist/map-quality.d.ts +20 -0
- package/dist/map-quality.js +61 -0
- package/dist/mapping-coverage.d.ts +87 -0
- package/dist/mapping-coverage.js +404 -0
- package/dist/model.d.ts +186 -0
- package/dist/model.js +66 -0
- package/dist/operation-benchmark-worker.d.ts +2 -0
- package/dist/operation-benchmark-worker.js +60 -0
- package/dist/operation-benchmark.d.ts +29 -0
- package/dist/operation-benchmark.js +1 -0
- package/dist/otel-metrics.d.ts +21 -0
- package/dist/otel-metrics.js +146 -0
- package/dist/performance-model.d.ts +185 -0
- package/dist/performance-model.js +396 -0
- package/dist/product-map.d.ts +71 -0
- package/dist/product-map.js +197 -0
- package/dist/provider-access.cjs +207 -0
- package/dist/provider-access.d.cts +14 -0
- package/dist/public-boundaries.d.ts +13 -0
- package/dist/public-boundaries.js +115 -0
- package/dist/reports-cli.d.ts +1 -0
- package/dist/reports-cli.js +111 -0
- package/dist/reports-model.d.ts +27 -0
- package/dist/reports-model.js +39 -0
- package/dist/reports.d.ts +23 -0
- package/dist/reports.js +223 -0
- package/dist/repository-map.d.ts +22 -0
- package/dist/repository-map.js +153 -0
- package/dist/resource-cache.d.ts +17 -0
- package/dist/resource-cache.js +65 -0
- package/dist/review-cli.d.ts +19 -0
- package/dist/review-cli.js +224 -0
- package/dist/review.d.ts +48 -0
- package/dist/review.js +289 -0
- package/dist/runtime-metrics.d.ts +26 -0
- package/dist/runtime-metrics.js +290 -0
- package/dist/scope.d.ts +14 -0
- package/dist/scope.js +168 -0
- package/dist/sentry-activity.d.ts +39 -0
- package/dist/sentry-activity.js +174 -0
- package/dist/sentry.d.ts +130 -0
- package/dist/sentry.js +369 -0
- package/dist/service-release.d.ts +16 -0
- package/dist/service-release.js +14 -0
- package/dist/setup-cli.d.ts +2 -0
- package/dist/setup-cli.js +52 -0
- package/dist/setup-kit.cjs +163 -0
- package/dist/setup-kit.d.cts +32 -0
- package/dist/source-index.d.ts +37 -0
- package/dist/source-index.js +170 -0
- package/dist/source-review-git.d.ts +7 -0
- package/dist/source-review-git.js +105 -0
- package/dist/source-review.d.ts +18 -0
- package/dist/source-review.js +573 -0
- package/dist/telemetry.d.ts +17 -0
- package/dist/telemetry.js +51 -0
- package/dist/time-window.d.ts +9 -0
- package/dist/time-window.js +35 -0
- package/dist/trace-evidence.d.ts +23 -0
- package/dist/trace-evidence.js +55 -0
- package/dist/trace-model.d.ts +26 -0
- package/dist/trace-model.js +1 -0
- package/dist/tracing.d.ts +44 -0
- package/dist/tracing.js +123 -0
- package/dist/work-check.d.ts +18 -0
- package/dist/work-check.js +115 -0
- package/dist/work-cli.d.ts +1 -0
- package/dist/work-cli.js +176 -0
- package/dist/work-context.d.ts +59 -0
- package/dist/work-context.js +594 -0
- package/dist/work-intents.d.ts +6 -0
- package/dist/work-intents.js +140 -0
- package/dist/work-items.d.ts +58 -0
- package/dist/work-items.js +86 -0
- package/dist/work-lock-check.d.ts +12 -0
- package/dist/work-lock-check.js +339 -0
- package/dist/work-locks.d.ts +10 -0
- package/dist/work-locks.js +98 -0
- package/dist/work-model.d.ts +119 -0
- package/dist/work-model.js +310 -0
- package/dist/work-review-git.d.ts +8 -0
- package/dist/work-review-git.js +111 -0
- package/dist/work-review.d.ts +26 -0
- package/dist/work-review.js +426 -0
- package/dist/work-switcher-model.d.ts +43 -0
- package/dist/work-switcher-model.js +79 -0
- package/dist/work-switcher.d.ts +6 -0
- package/dist/work-switcher.js +171 -0
- package/dist/working-cli.d.ts +1 -0
- package/dist/working-cli.js +33 -0
- package/dist/working-code.d.ts +74 -0
- package/dist/working-code.js +421 -0
- package/dist/workspace-notes.d.ts +71 -0
- package/dist/workspace-notes.js +177 -0
- package/dist/workspace-tests.d.ts +21 -0
- package/dist/workspace-tests.js +573 -0
- package/package.json +547 -4
- package/src/activity-volume.ts +149 -0
- package/src/annotations.ts +485 -0
- package/src/benchmark-cli.ts +118 -0
- package/src/benchmark-worker.ts +22 -0
- package/src/benchmarks.ts +493 -0
- package/src/bin.ts +54 -0
- package/src/block-cli.ts +106 -0
- package/src/block-documents.ts +117 -0
- package/src/change-impact.ts +280 -0
- package/src/check-source.ts +82 -0
- package/src/checks-model.ts +108 -0
- package/src/cli.ts +440 -0
- package/src/code-model.ts +159 -0
- package/src/code-store.ts +98 -0
- package/src/compare-artifact.ts +314 -0
- package/src/compare.ts +440 -0
- package/src/compiler.ts +1512 -0
- package/src/compose.ts +94 -0
- package/src/core.ts +361 -0
- package/src/coverage-cli.ts +52 -0
- package/src/declaration-sources.ts +69 -0
- package/src/declared-graph.ts +75 -0
- package/src/display-name.ts +8 -0
- package/src/error-heat.ts +161 -0
- package/src/evidence.ts +94 -0
- package/src/factory-graph.ts +462 -0
- package/src/factory-model.ts +82 -0
- package/src/git-code.ts +461 -0
- package/src/git-refs.ts +43 -0
- package/src/history-activity.ts +146 -0
- package/src/history-churn.ts +416 -0
- package/src/history-git.ts +163 -0
- package/src/history-ledger.ts +636 -0
- package/src/history-ownership.ts +116 -0
- package/src/history-source.ts +117 -0
- package/src/integrations-cli.ts +187 -0
- package/src/interface-map.ts +166 -0
- package/src/issue-cache.ts +96 -0
- package/src/issue-cli.ts +137 -0
- package/src/issue-links.ts +153 -0
- package/src/linear-issues.ts +154 -0
- package/src/local-runtime.ts +70 -0
- package/src/map-activity.ts +309 -0
- package/src/map-model.ts +213 -0
- package/src/map-quality.ts +66 -0
- package/src/mapping-coverage.ts +570 -0
- package/src/model.ts +228 -0
- package/src/operation-benchmark-worker.ts +60 -0
- package/src/operation-benchmark.ts +28 -0
- package/src/otel-metrics.ts +176 -0
- package/src/performance-model.ts +575 -0
- package/src/product-map.ts +271 -0
- package/src/provider-access.cjs +207 -0
- package/src/provider-access.d.cts +14 -0
- package/src/public-boundaries.ts +143 -0
- package/src/reports-cli.ts +125 -0
- package/src/reports-model.ts +73 -0
- package/src/reports.ts +276 -0
- package/src/repository-map.ts +191 -0
- package/src/resource-cache.ts +76 -0
- package/src/review-cli.ts +256 -0
- package/src/review.ts +376 -0
- package/src/runtime-metrics.ts +386 -0
- package/src/scope.ts +192 -0
- package/src/sentry-activity.ts +234 -0
- package/src/sentry.ts +545 -0
- package/src/service-release.ts +18 -0
- package/src/setup-cli.ts +58 -0
- package/src/setup-kit.cjs +163 -0
- package/src/setup-kit.d.cts +32 -0
- package/src/source-index.ts +208 -0
- package/src/source-review-git.ts +131 -0
- package/src/source-review.ts +736 -0
- package/src/telemetry.ts +68 -0
- package/src/time-window.ts +51 -0
- package/src/trace-evidence.ts +80 -0
- package/src/trace-model.ts +26 -0
- package/src/tracing.ts +165 -0
- package/src/work-check.ts +149 -0
- package/src/work-cli.ts +229 -0
- package/src/work-context.ts +753 -0
- package/src/work-intents.ts +196 -0
- package/src/work-items.ts +151 -0
- package/src/work-lock-check.ts +549 -0
- package/src/work-locks.ts +108 -0
- package/src/work-model.ts +466 -0
- package/src/work-review-git.ts +130 -0
- package/src/work-review.ts +573 -0
- package/src/work-switcher-model.ts +121 -0
- package/src/work-switcher.ts +191 -0
- package/src/working-cli.ts +38 -0
- package/src/working-code.ts +582 -0
- package/src/workspace-notes.ts +203 -0
- package/src/workspace-tests.ts +654 -0
- package/toolkit/GUIDE.md +354 -0
- package/toolkit/SKILL.md +142 -0
- package/toolkit/bin/fractory +2 -0
- package/toolkit/build.json +1 -0
package/src/telemetry.ts
ADDED
|
@@ -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
|
+
}
|