@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,98 @@
1
+ /** Public contracts can nest, but ordinary implementation children are not public
2
+ * merely because they sit inside an interface. Explicit exposure can bridge them. */
3
+ export function publicContractIds(graph, target) {
4
+ const publicKinds = new Set(["interface", "method", "operation"]);
5
+ const byId = new Map(graph.elements.map((n) => [n.id, n]));
6
+ const children = new Map();
7
+ const add = (parent, id) => {
8
+ if (!children.has(parent))
9
+ children.set(parent, []);
10
+ children.get(parent).push(id);
11
+ };
12
+ for (const n of graph.elements)
13
+ if (n.parent && publicKinds.has(n.kind))
14
+ add(n.parent, n.id);
15
+ for (const e of graph.connections)
16
+ if (e.relation === "exposes" &&
17
+ publicKinds.has(byId.get(e.target)?.kind || ""))
18
+ add(e.source, e.target);
19
+ const result = new Set();
20
+ const queue = [target];
21
+ while (queue.length) {
22
+ const id = queue.pop();
23
+ if (result.has(id))
24
+ continue;
25
+ result.add(id);
26
+ queue.push(...(children.get(id) || []));
27
+ }
28
+ return result;
29
+ }
30
+ /** A subtree lock wins over every nested contract lock; inclusion never unlocks code. */
31
+ export function lockIndex(graph, locks) {
32
+ const byId = new Map(graph.elements.map((n) => [n.id, n]));
33
+ const explicit = new Map(locks.map((l) => [l.target, l]));
34
+ const result = new Map();
35
+ for (const lock of locks)
36
+ if (lock.kind === "contract")
37
+ for (const id of publicContractIds(graph, lock.target))
38
+ result.set(id, lock);
39
+ for (const node of graph.elements) {
40
+ const seen = new Set();
41
+ let cursor = node.id;
42
+ let effective = explicit.get(node.id) || result.get(node.id);
43
+ while (cursor && !seen.has(cursor)) {
44
+ seen.add(cursor);
45
+ const lock = explicit.get(cursor);
46
+ if (lock?.kind === "subtree")
47
+ effective = lock;
48
+ cursor = byId.get(cursor)?.parent;
49
+ }
50
+ if (effective)
51
+ result.set(node.id, effective);
52
+ }
53
+ return result;
54
+ }
55
+ export function lockFor(graph, locks, id) {
56
+ return lockIndex(graph, locks).get(id);
57
+ }
58
+ export function validateLocks(graph, input, previous = []) {
59
+ if (!Array.isArray(input) || input.length > 500)
60
+ throw Error("Choose up to 500 block or interface locks.");
61
+ const targets = new Set();
62
+ return input.map((value) => {
63
+ if (!value || typeof value !== "object")
64
+ throw Error("Invalid lock.");
65
+ const { target, kind, note } = value;
66
+ if (typeof target !== "string" || !["subtree", "contract"].includes(kind))
67
+ throw Error("Choose a block subtree or interface contract to lock.");
68
+ if (targets.has(target))
69
+ throw Error("A target can only have one lock.");
70
+ targets.add(target);
71
+ const node = graph.elements.find((n) => n.id === target);
72
+ // Deleted targets remain locked and reviewable; adding an unknown target is rejected.
73
+ if (!node && !previous.some((l) => l.target === target && l.kind === kind))
74
+ throw Error(`Unknown lock target: ${target}`);
75
+ if (node &&
76
+ (node.provenance === "proposed" ||
77
+ (node.kind === "interface" ? kind !== "contract" : kind !== "subtree")))
78
+ throw Error("Lock an interface's public contract or a real block's whole subtree.");
79
+ if (note !== undefined && (typeof note !== "string" || note.length > 4000))
80
+ throw Error("Keep the lock reason below 4,000 characters.");
81
+ return { target, kind, ...(note?.trim() ? { note: note.trim() } : {}) };
82
+ });
83
+ }
84
+ export function lockBrief(graph, locks) {
85
+ if (!locks.length)
86
+ return [];
87
+ return [
88
+ "## Locked boundaries",
89
+ "Locks take precedence over the editable scope and proposed changes. Do not remove or weaken a lock to make a check pass.",
90
+ ...locks.map((lock) => {
91
+ const node = graph.elements.find((n) => n.id === lock.target);
92
+ return `- ${node?.label || lock.target} (${lock.target}): ${lock.kind === "contract"
93
+ ? "Freeze the public contract exactly: names, routes, signatures, inputs, outputs and explicitly exposed nested contracts. Internal implementation may change; this is not permission to change a signature even compatibly."
94
+ : "Freeze this block and its entire subtree, including code, interfaces and nested blocks."}${lock.note ? ` Reason: ${lock.note}` : ""}`;
95
+ }),
96
+ "",
97
+ ];
98
+ }
@@ -0,0 +1,119 @@
1
+ import type { DefinitionGraph } from "./model.js";
2
+ export interface WorkProposal {
3
+ id: string;
4
+ kind: "block" | "connection" | "annotation";
5
+ label: string;
6
+ note: string;
7
+ parent?: string;
8
+ source?: string;
9
+ target?: string;
10
+ change?: "change" | "remove";
11
+ blockKind?: "block" | "interface" | "process";
12
+ position?: {
13
+ x: number;
14
+ y: number;
15
+ };
16
+ createdAt?: string;
17
+ resolved?: boolean;
18
+ /** An explicit link from this intention to an actual mapped block or connection. */
19
+ implementation?: string;
20
+ outcome?: {
21
+ status: "done" | "dropped";
22
+ checkedAt: string;
23
+ /** Source/request fingerprint at confirmation; never a test or compatibility claim. */
24
+ evidence?: string;
25
+ };
26
+ }
27
+ export interface WorkIntentState {
28
+ status: "planned" | "done" | "dropped" | "changed";
29
+ implementation?: string;
30
+ reason?: string;
31
+ }
32
+ /** Constraints are independent of editable scope and temporary canvas selection. */
33
+ export interface WorkLock {
34
+ target: string;
35
+ kind: "subtree" | "contract";
36
+ note?: string;
37
+ }
38
+ export interface WorkPlan {
39
+ schema: "fractory.work.v1";
40
+ id: string;
41
+ title: string;
42
+ branch: string;
43
+ baseRef: string;
44
+ baseCommit: string;
45
+ createdAt: string;
46
+ scope: string[];
47
+ /** Explicit subtree exceptions. The nearest include/exclude rule wins. */
48
+ excluded?: string[];
49
+ locks?: WorkLock[];
50
+ proposals: WorkProposal[];
51
+ bootstrapRevision?: string;
52
+ pullRequest?: {
53
+ url: string;
54
+ title: string;
55
+ };
56
+ }
57
+ export interface WorkContext {
58
+ id: string;
59
+ mode: "main" | "work" | "branch";
60
+ title: string;
61
+ branch: string;
62
+ root: string;
63
+ head: string;
64
+ baseRef: string;
65
+ baseCommit: string;
66
+ plan?: WorkPlan;
67
+ revision?: string;
68
+ mapBasis: "committed" | "checkout" | "baseline";
69
+ /** Map evidence and presence of an editable checkout are independent. */
70
+ hasCheckout?: boolean;
71
+ notice?: string;
72
+ }
73
+ /** Verified GitHub identity, read from the provider rather than a pasted URL. */
74
+ export interface WorkPullRequest {
75
+ number: number;
76
+ title: string;
77
+ url: string;
78
+ state: "open" | "draft" | "merged" | "closed";
79
+ base: string;
80
+ head: string;
81
+ }
82
+ export type WorkPullRequestResult = {
83
+ status: "matched";
84
+ pullRequest: WorkPullRequest;
85
+ } | {
86
+ status: "ambiguous";
87
+ pullRequests: WorkPullRequest[];
88
+ } | {
89
+ status: "none";
90
+ } | {
91
+ status: "unavailable";
92
+ message: string;
93
+ };
94
+ export interface WorkTarget {
95
+ id: string;
96
+ title: string;
97
+ branch: string;
98
+ path?: string;
99
+ current: boolean;
100
+ managed: boolean;
101
+ head: string;
102
+ scope?: string[];
103
+ plannedAt?: string;
104
+ pullRequest?: WorkPlan["pullRequest"];
105
+ }
106
+ export declare function workTargetLabel(graph: DefinitionGraph, proposals: WorkProposal[], id: string): string;
107
+ export declare function scopeBlocks(graph: DefinitionGraph, scope: string[], excluded?: string[]): Set<string>;
108
+ /** Preserve nested exceptions without repeating rules already inherited from a parent. */
109
+ export declare function normalizeWorkScope(graph: DefinitionGraph, scope: string[], excluded?: string[]): {
110
+ scope: string[];
111
+ excluded: string[];
112
+ };
113
+ /** Selecting a parent includes its children; do not repeat children in a work's scope. */
114
+ export declare function compactScope(graph: DefinitionGraph, scope: string[]): string[];
115
+ export declare function validateProposals(graph: DefinitionGraph, proposals: unknown, previous?: WorkProposal[]): WorkProposal[];
116
+ /** Display composition only. Proposed elements never enter the compiler's output. */
117
+ export declare function workDisplayGraph(graph: DefinitionGraph, plan?: WorkPlan, states?: Record<string, WorkIntentState>): DefinitionGraph;
118
+ /** Legacy requests remain readable as intentions, not as invalid callable wires. */
119
+ export declare function proposalConnectionError(graph: DefinitionGraph, plan: WorkPlan | undefined, proposal: WorkProposal): string | undefined;
@@ -0,0 +1,310 @@
1
+ import { publicConnectionError, boundaryViolations } from "./public-boundaries.js";
2
+ export function workTargetLabel(graph, proposals, id) {
3
+ const block = graph.elements.find((node) => node.id === id) ||
4
+ proposals.find((p) => p.kind === "block" && p.id === id);
5
+ if (block)
6
+ return block.label;
7
+ const connection = graph.connections.find((edge) => edge.id === id) ||
8
+ proposals.find((p) => p.kind === "connection" && p.id === id);
9
+ return connection?.label || id;
10
+ }
11
+ export function scopeBlocks(graph, scope, excluded = []) {
12
+ const byId = new Map(graph.elements.map((node) => [node.id, node]));
13
+ const selected = new Set(scope);
14
+ const omitted = new Set(excluded);
15
+ const ids = new Set();
16
+ for (const node of graph.elements) {
17
+ let cursor = node;
18
+ const seen = new Set();
19
+ while (cursor && !seen.has(cursor.id)) {
20
+ if (omitted.has(cursor.id))
21
+ break;
22
+ if (selected.has(cursor.id)) {
23
+ ids.add(node.id);
24
+ break;
25
+ }
26
+ seen.add(cursor.id);
27
+ cursor = byId.get(cursor.parent || "");
28
+ }
29
+ }
30
+ return ids;
31
+ }
32
+ /** Preserve nested exceptions without repeating rules already inherited from a parent. */
33
+ export function normalizeWorkScope(graph, scope, excluded = []) {
34
+ const byId = new Map(graph.elements.map((node) => [node.id, node]));
35
+ if (!Array.isArray(scope) ||
36
+ !Array.isArray(excluded) ||
37
+ scope.length + excluded.length > graph.elements.length * 2)
38
+ throw Error("Select mapped blocks for this work.");
39
+ const rules = new Map();
40
+ for (const [values, include] of [
41
+ [scope, true],
42
+ [excluded, false],
43
+ ])
44
+ for (const id of values) {
45
+ if (!byId.has(id))
46
+ throw Error(`Unknown scope block: ${id}`);
47
+ if (rules.has(id) && rules.get(id) !== include)
48
+ throw Error("A block cannot be both selected and excluded.");
49
+ rules.set(id, include);
50
+ }
51
+ const result = { scope: [], excluded: [] };
52
+ for (const [id, include] of rules) {
53
+ let parent = byId.get(id)?.parent;
54
+ let inherited = false;
55
+ const seen = new Set();
56
+ while (parent && !seen.has(parent)) {
57
+ if (rules.has(parent)) {
58
+ inherited = rules.get(parent);
59
+ break;
60
+ }
61
+ seen.add(parent);
62
+ parent = byId.get(parent)?.parent;
63
+ }
64
+ if (include !== inherited)
65
+ result[include ? "scope" : "excluded"].push(id);
66
+ }
67
+ return result;
68
+ }
69
+ /** Selecting a parent includes its children; do not repeat children in a work's scope. */
70
+ export function compactScope(graph, scope) {
71
+ const unique = [...new Set(scope)];
72
+ if (!unique.length)
73
+ throw Error("Select at least one block.");
74
+ const byId = new Map(graph.elements.map((node) => [node.id, node]));
75
+ for (const id of unique)
76
+ if (!byId.has(id))
77
+ throw Error(`Unknown scope block: ${id}`);
78
+ return unique.filter((id) => {
79
+ let parent = byId.get(id)?.parent;
80
+ const seen = new Set();
81
+ while (parent && !seen.has(parent)) {
82
+ if (unique.includes(parent))
83
+ return false;
84
+ seen.add(parent);
85
+ parent = byId.get(parent)?.parent;
86
+ }
87
+ return true;
88
+ });
89
+ }
90
+ export function validateProposals(graph, proposals, previous = []) {
91
+ if (!Array.isArray(proposals) || proposals.length > 200)
92
+ throw Error("Keep a plan below 200 proposals.");
93
+ const ids = new Set(graph.elements.map((node) => node.id));
94
+ const connections = new Set(graph.connections.map((edge) => edge.id));
95
+ const own = new Set();
96
+ for (const item of proposals) {
97
+ if (!item ||
98
+ typeof item !== "object" ||
99
+ typeof item.id !== "string" ||
100
+ !/^proposal:[a-zA-Z0-9-]{1,70}$/.test(item.id) ||
101
+ own.has(item.id))
102
+ throw Error("Every proposal needs a unique proposal identity.");
103
+ if (!["block", "connection", "annotation"].includes(item.kind))
104
+ throw Error("Unknown proposal kind.");
105
+ if (typeof item.label !== "string" ||
106
+ item.label.length > 160 ||
107
+ typeof item.note !== "string" ||
108
+ item.note.length > 12000)
109
+ throw Error("Keep proposal names and notes concise.");
110
+ own.add(item.id);
111
+ if (item.kind === "block")
112
+ ids.add(item.id);
113
+ if (item.kind === "connection")
114
+ connections.add(item.id);
115
+ }
116
+ const result = proposals.map((item) => {
117
+ // Keep historical references editable after real code disappears. New dangling references are still rejected.
118
+ const known = (field, ids) => typeof item[field] === "string" &&
119
+ !!item[field] &&
120
+ (ids.has(item[field]) ||
121
+ previous.some((p) => p.id === item.id &&
122
+ p.kind === item.kind &&
123
+ p[field] === item[field]));
124
+ const value = {
125
+ id: item.id,
126
+ kind: item.kind,
127
+ label: item.label.trim(),
128
+ note: item.note,
129
+ };
130
+ if (item.implementation !== undefined) {
131
+ if (typeof item.implementation !== "string" ||
132
+ !item.implementation ||
133
+ item.implementation.length > 4096 ||
134
+ item.implementation.startsWith("proposal:"))
135
+ throw Error("Link an actual mapped block or connection.");
136
+ value.implementation = item.implementation;
137
+ }
138
+ if (item.outcome !== undefined) {
139
+ if (!item.outcome ||
140
+ !["done", "dropped"].includes(item.outcome.status) ||
141
+ typeof item.outcome.checkedAt !== "string" ||
142
+ !Number.isFinite(Date.parse(item.outcome.checkedAt)) ||
143
+ (item.outcome.status === "done" &&
144
+ !/^[a-f0-9]{64}$/.test(item.outcome.evidence || "")))
145
+ throw Error("Use a valid intention outcome.");
146
+ value.outcome = {
147
+ status: item.outcome.status,
148
+ checkedAt: item.outcome.checkedAt,
149
+ ...(item.outcome.status === "done"
150
+ ? { evidence: item.outcome.evidence }
151
+ : {}),
152
+ };
153
+ }
154
+ if (item.kind === "block") {
155
+ if (!value.label || !known("parent", ids) || item.parent === item.id)
156
+ throw Error("Choose a containing block for the proposed block.");
157
+ value.parent = item.parent;
158
+ value.blockKind = ["block", "interface", "process"].includes(item.blockKind)
159
+ ? item.blockKind
160
+ : "block";
161
+ }
162
+ else if (item.kind === "connection") {
163
+ if (!value.label || !known("source", ids) || !known("target", ids))
164
+ throw Error("Connect two existing or proposed blocks.");
165
+ value.source = item.source;
166
+ value.target = item.target;
167
+ }
168
+ else {
169
+ if (!known("target", new Set([...ids, ...connections])))
170
+ throw Error("Attach the note to an existing block or connection.");
171
+ value.target = item.target;
172
+ value.change = item.change === "remove" ? "remove" : "change";
173
+ if (item.createdAt !== undefined) {
174
+ if (typeof item.createdAt !== "string" ||
175
+ item.createdAt.length > 40 ||
176
+ !Number.isFinite(Date.parse(item.createdAt)))
177
+ throw Error("Use a valid comment timestamp.");
178
+ value.createdAt = item.createdAt;
179
+ }
180
+ if (item.resolved !== undefined) {
181
+ if (typeof item.resolved !== "boolean")
182
+ throw Error("Invalid comment state.");
183
+ value.resolved = item.resolved;
184
+ }
185
+ }
186
+ if (item.position) {
187
+ if (![item.position.x, item.position.y].every((n) => Number.isFinite(n) && Math.abs(n) <= 100000))
188
+ throw Error("Invalid proposal position.");
189
+ value.position = { x: item.position.x, y: item.position.y };
190
+ }
191
+ return value;
192
+ });
193
+ const parents = new Map(result.filter((p) => p.kind === "block").map((p) => [p.id, p.parent]));
194
+ for (const id of parents.keys()) {
195
+ let cursor = id;
196
+ const seen = new Set();
197
+ while (cursor && parents.has(cursor)) {
198
+ if (seen.has(cursor))
199
+ throw Error("Proposed blocks cannot contain each other in a cycle.");
200
+ seen.add(cursor);
201
+ cursor = parents.get(cursor);
202
+ }
203
+ }
204
+ const candidate = {
205
+ ...graph,
206
+ elements: [
207
+ ...graph.elements,
208
+ ...result
209
+ .filter((item) => item.kind === "block")
210
+ .map((item) => ({
211
+ id: item.id,
212
+ parent: item.parent,
213
+ kind: item.blockKind || "block",
214
+ label: item.label,
215
+ provenance: "proposed",
216
+ })),
217
+ ],
218
+ };
219
+ for (const item of result.filter((item) => item.kind === "connection")) {
220
+ // An unchanged historical request remains editable as a record. New links
221
+ // and endpoint edits must obey the same public contract as compiled maps.
222
+ const old = previous.find((entry) => entry.id === item.id && entry.kind === "connection");
223
+ if (old?.source === item.source && old?.target === item.target)
224
+ continue;
225
+ const error = publicConnectionError(candidate, {
226
+ id: item.id,
227
+ source: item.source,
228
+ target: item.target,
229
+ relation: "calls",
230
+ label: item.label,
231
+ provenance: "proposed",
232
+ });
233
+ if (error)
234
+ throw Error(error);
235
+ }
236
+ return result;
237
+ }
238
+ /** Display composition only. Proposed elements never enter the compiler's output. */
239
+ export function workDisplayGraph(graph, plan, states) {
240
+ const proposals = plan?.proposals || [];
241
+ const status = (p) => states?.[p.id]?.status ||
242
+ (p.outcome?.status === "dropped" ? "dropped" : "planned");
243
+ const active = proposals.filter((p) => !["done", "dropped"].includes(status(p)));
244
+ // An unfinished nested sketch retains its containing proposal. It never floats out of its parent.
245
+ const needed = new Set(active.map((p) => p.id));
246
+ for (const p of active) {
247
+ let parent = p.parent, count = 0;
248
+ while (parent?.startsWith("proposal:") && count++ < proposals.length) {
249
+ needed.add(parent);
250
+ parent = proposals.find((a) => a.id === parent)?.parent;
251
+ }
252
+ }
253
+ const target = (id) => {
254
+ const p = proposals.find((p) => p.id === id);
255
+ return p && !needed.has(id) && status(p) === "done" && p.implementation
256
+ ? p.implementation
257
+ : id;
258
+ };
259
+ const visual = proposals.filter((p) => p.kind !== "annotation" && needed.has(p.id));
260
+ if (!visual.length)
261
+ return graph;
262
+ const scene = {
263
+ ...graph,
264
+ revision: `${graph.revision}:plan:${JSON.stringify(visual)}`,
265
+ elements: [
266
+ ...graph.elements,
267
+ ...visual
268
+ .filter((p) => p.kind === "block")
269
+ .map((p) => ({
270
+ id: p.id,
271
+ parent: p.parent,
272
+ kind: p.blockKind || "block",
273
+ label: p.label,
274
+ description: p.note,
275
+ provenance: "proposed",
276
+ })),
277
+ ],
278
+ connections: [
279
+ ...graph.connections,
280
+ ...visual
281
+ .filter((p) => p.kind === "connection")
282
+ .map((p) => ({
283
+ id: p.id,
284
+ source: target(p.source),
285
+ target: target(p.target),
286
+ label: p.label,
287
+ relation: "calls",
288
+ provenance: "proposed",
289
+ }))
290
+ .filter((edge) => [edge.source, edge.target].every((id) => graph.elements.some((n) => n.id === id) ||
291
+ visual.some((p) => p.kind === "block" && p.id === id))),
292
+ ],
293
+ };
294
+ const invalid = new Set(boundaryViolations(scene).map((issue) => issue.connection));
295
+ scene.connections = scene.connections.filter((edge) => edge.provenance !== "proposed" || !invalid.has(edge.id));
296
+ return scene;
297
+ }
298
+ /** Legacy requests remain readable as intentions, not as invalid callable wires. */
299
+ export function proposalConnectionError(graph, plan, proposal) {
300
+ if (proposal.kind !== "connection")
301
+ return undefined;
302
+ return publicConnectionError(workDisplayGraph(graph, plan), {
303
+ id: proposal.id,
304
+ source: proposal.source,
305
+ target: proposal.target,
306
+ label: proposal.label,
307
+ relation: "calls",
308
+ provenance: "proposed",
309
+ });
310
+ }
@@ -0,0 +1,8 @@
1
+ import { type WorkReview } from "./work-review.js";
2
+ import type { DefinitionGraph } from "./model.js";
3
+ /** Repeated polls reuse immutable Git blobs and the unchanged review. No full compiler pass. */
4
+ export declare function workingConcepts(root: string, base: string, before: DefinitionGraph, after: DefinitionGraph, files: {
5
+ path: string;
6
+ digest?: string;
7
+ status: string;
8
+ }[], historicalOwnership: boolean): WorkReview;
@@ -0,0 +1,111 @@
1
+ import { createHash } from "node:crypto";
2
+ import { execFileSync } from "node:child_process";
3
+ import { readFileSync, realpathSync, lstatSync } from "node:fs";
4
+ import { resolve, sep } from "node:path";
5
+ import { reviewWorkingCode } from "./work-review.js";
6
+ const results = new Map();
7
+ const blobs = new Map();
8
+ const oversized = new Set();
9
+ /** Repeated polls reuse immutable Git blobs and the unchanged review. No full compiler pass. */
10
+ export function workingConcepts(root, base, before, after, files, historicalOwnership) {
11
+ if (!/^[a-f0-9]{40,64}$/.test(base))
12
+ throw Error("Resolve the work's starting revision first.");
13
+ const key = createHash("sha256")
14
+ .update(JSON.stringify([root, base, before, after, files, historicalOwnership]))
15
+ .digest("hex");
16
+ const saved = results.get(key);
17
+ if (saved)
18
+ return saved;
19
+ const directory = realpathSync(root), max = 1024 * 1024;
20
+ const selected = files.filter((f) => /\.[cm]?[jt]sx?$/.test(f.path));
21
+ const eligible = selected.slice(0, 512), missing = eligible.filter((f) => !blobs.has(`${directory}:${base}:${f.path}`) &&
22
+ !/[:\n\r\0]/.test(f.path));
23
+ if (missing.length) {
24
+ const output = execFileSync("git", ["cat-file", "--batch"], {
25
+ cwd: root,
26
+ input: missing.map((f) => `${base}:${f.path}\n`).join(""),
27
+ maxBuffer: 64 * 1024 * 1024,
28
+ timeout: 15000,
29
+ env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
30
+ stdio: ["pipe", "pipe", "pipe"],
31
+ });
32
+ let offset = 0;
33
+ for (const file of missing) {
34
+ const newline = output.indexOf(10, offset);
35
+ if (newline < 0)
36
+ throw Error("Incomplete starting-revision source response");
37
+ const header = output.subarray(offset, newline).toString();
38
+ offset = newline + 1;
39
+ if (header.endsWith(" missing")) {
40
+ blobs.set(`${directory}:${base}:${file.path}`, undefined);
41
+ continue;
42
+ }
43
+ const size = Number(header.split(" ")[2]);
44
+ if (!Number.isSafeInteger(size) ||
45
+ size < 0 ||
46
+ offset + size >= output.length)
47
+ throw Error("Incomplete Git source blob");
48
+ const content = output.subarray(offset, offset + size);
49
+ offset += size + 1;
50
+ const blobKey = `${directory}:${base}:${file.path}`;
51
+ if (size > max || content.includes(0))
52
+ oversized.add(blobKey);
53
+ blobs.set(blobKey, size > max || content.includes(0) ? undefined : content.toString());
54
+ }
55
+ }
56
+ let bytes = 0;
57
+ const source = files.map((f) => {
58
+ if (!/\.[cm]?[jt]sx?$/.test(f.path))
59
+ return { path: f.path, unavailable: "Non-code change" };
60
+ if (!eligible.includes(f))
61
+ return {
62
+ path: f.path,
63
+ unavailable: "Declaration review budget reached; file remains included",
64
+ };
65
+ const blobKey = `${directory}:${base}:${f.path}`;
66
+ if (oversized.has(blobKey))
67
+ return {
68
+ path: f.path,
69
+ unavailable: "Starting source exceeds the review budget or is binary",
70
+ };
71
+ const beforeText = blobs.get(blobKey);
72
+ try {
73
+ if (/[:\n\r\0]/.test(f.path))
74
+ throw Error("Unsupported source filename");
75
+ const location = resolve(directory, f.path);
76
+ if (!location.startsWith(directory + sep))
77
+ throw Error("Source is outside the repository");
78
+ let afterText;
79
+ if (f.status !== "removed") {
80
+ const stat = lstatSync(location);
81
+ if (stat.isSymbolicLink() ||
82
+ stat.size > max ||
83
+ !realpathSync(location).startsWith(directory + sep))
84
+ throw Error("Source is linked or exceeds the review budget");
85
+ bytes += stat.size;
86
+ if (bytes > 24 * 1024 * 1024)
87
+ throw Error("Declaration review budget reached; file remains included");
88
+ afterText = readFileSync(location, "utf8");
89
+ if (afterText.includes("\0"))
90
+ throw Error("Binary source");
91
+ }
92
+ return { path: f.path, before: beforeText, after: afterText };
93
+ }
94
+ catch (error) {
95
+ return {
96
+ path: f.path,
97
+ unavailable: error instanceof Error ? error.message : "Source unavailable",
98
+ };
99
+ }
100
+ });
101
+ const result = reviewWorkingCode(before, after, source, historicalOwnership);
102
+ while (blobs.size > 1024) {
103
+ const oldest = blobs.keys().next().value;
104
+ blobs.delete(oldest);
105
+ oversized.delete(oldest);
106
+ }
107
+ results.set(key, result);
108
+ while (results.size > 4)
109
+ results.delete(results.keys().next().value);
110
+ return result;
111
+ }
@@ -0,0 +1,26 @@
1
+ import type { Connection, DefinitionGraph } from "./model.js";
2
+ export type WorkChangeKind = "implementation" | "interface" | "connection" | "mapping" | "support";
3
+ export interface WorkChange {
4
+ kind: WorkChangeKind;
5
+ block: string;
6
+ file: string;
7
+ label: string;
8
+ before?: string;
9
+ after?: string;
10
+ connection?: Connection;
11
+ change?: "added" | "removed" | "modified";
12
+ }
13
+ export interface WorkReview {
14
+ basis: "saved-code";
15
+ changes: WorkChange[];
16
+ /** Files remain accounted for even when ownership or syntax cannot be proved. */
17
+ unassigned: string[];
18
+ historicalOwnership: boolean;
19
+ }
20
+ /** Only explicit, uniquely mapped functions/methods are classified. Dynamic dispatch is not guessed. */
21
+ export declare function reviewWorkingCode(beforeGraph: DefinitionGraph, graph: DefinitionGraph, files: {
22
+ path: string;
23
+ before?: string;
24
+ after?: string;
25
+ unavailable?: string;
26
+ }[], historicalOwnership: boolean): WorkReview;