@granular-software/fractory 0.1.24 → 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 (63) hide show
  1. package/dist/annotations.d.ts +4 -0
  2. package/dist/compiler.js +161 -4
  3. package/dist/core.d.ts +1 -0
  4. package/dist/core.js +1 -0
  5. package/dist/declared-graph.js +2 -1
  6. package/dist/factory-graph.d.ts +4 -1
  7. package/dist/factory-graph.js +77 -6
  8. package/dist/factory-model.d.ts +14 -0
  9. package/dist/git-code.js +1 -1
  10. package/dist/interface-map.d.ts +15 -0
  11. package/dist/interface-map.js +125 -0
  12. package/dist/map-quality.d.ts +6 -0
  13. package/dist/map-quality.js +5 -0
  14. package/dist/model.d.ts +6 -2
  15. package/dist/product-map.d.ts +2 -0
  16. package/dist/product-map.js +33 -4
  17. package/dist/public-boundaries.d.ts +13 -0
  18. package/dist/public-boundaries.js +115 -0
  19. package/dist/repository-map.js +3 -1
  20. package/dist/scope.d.ts +2 -0
  21. package/dist/scope.js +77 -3
  22. package/dist/source-index.js +4 -0
  23. package/dist/source-review-git.js +3 -1
  24. package/dist/source-review.d.ts +3 -1
  25. package/dist/source-review.js +94 -14
  26. package/dist/work-check.d.ts +1 -0
  27. package/dist/work-check.js +6 -1
  28. package/dist/work-cli.js +29 -1
  29. package/dist/work-context.d.ts +2 -0
  30. package/dist/work-context.js +30 -4
  31. package/dist/work-lock-check.d.ts +12 -0
  32. package/dist/work-lock-check.js +339 -0
  33. package/dist/work-locks.d.ts +10 -0
  34. package/dist/work-locks.js +98 -0
  35. package/dist/work-model.d.ts +9 -0
  36. package/dist/work-model.js +50 -1
  37. package/package.json +1 -1
  38. package/src/annotations.ts +4 -0
  39. package/src/compiler.ts +190 -4
  40. package/src/core.ts +4 -0
  41. package/src/declared-graph.ts +2 -1
  42. package/src/factory-graph.ts +89 -5
  43. package/src/factory-model.ts +9 -0
  44. package/src/git-code.ts +1 -1
  45. package/src/interface-map.ts +166 -0
  46. package/src/map-quality.ts +5 -0
  47. package/src/model.ts +10 -3
  48. package/src/product-map.ts +51 -16
  49. package/src/public-boundaries.ts +143 -0
  50. package/src/repository-map.ts +3 -1
  51. package/src/scope.ts +92 -3
  52. package/src/source-index.ts +3 -0
  53. package/src/source-review-git.ts +3 -1
  54. package/src/source-review.ts +112 -13
  55. package/src/work-check.ts +7 -1
  56. package/src/work-cli.ts +35 -1
  57. package/src/work-context.ts +43 -3
  58. package/src/work-lock-check.ts +549 -0
  59. package/src/work-locks.ts +108 -0
  60. package/src/work-model.ts +67 -1
  61. package/toolkit/GUIDE.md +72 -23
  62. package/toolkit/SKILL.md +16 -5
  63. package/toolkit/build.json +1 -1
@@ -1,14 +1,15 @@
1
- import { mapFromArtifacts, repositoryMapConfiguration, parseMapConfiguration } from "./repository-map.js";
1
+ import { mapFromArtifacts, repositoryMapConfiguration, parseMapConfiguration, } from "./repository-map.js";
2
2
  /** Local work contexts. Git refs are read without checkout; only explicit create adds a worktree. */
3
3
  import { createHash, randomUUID } from "node:crypto";
4
4
  import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, writeFileSync, rmSync, } from "node:fs";
5
5
  import { join, resolve } from "node:path";
6
6
  import { execFileSync } from "node:child_process";
7
7
  import { readGit, resolveComparisonRef, comparisonMergeBase } from "./git-refs.js";
8
- import { normalizeWorkScope, validateProposals, } from "./work-model.js";
8
+ import { normalizeWorkScope, validateProposals, proposalConnectionError, } from "./work-model.js";
9
9
  import { checkedPath } from "./workspace-notes.js";
10
10
  import { logicalMap } from "./map-model.js";
11
11
  import { intentEvidence, workIntentStates } from "./work-intents.js";
12
+ import { validateLocks, lockBrief } from "./work-locks.js";
12
13
  const uuid = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
13
14
  const hash = (value) => createHash("sha256").update(value).digest("hex");
14
15
  const identity = (path) => hash(path).slice(0, 20);
@@ -94,7 +95,16 @@ export function readWorkPlan(root, id, known) {
94
95
  plan.scope.some((id) => typeof id !== "string") ||
95
96
  (plan.excluded !== undefined &&
96
97
  (!Array.isArray(plan.excluded) ||
97
- plan.excluded.some((id) => typeof id !== "string"))))
98
+ plan.excluded.some((id) => typeof id !== "string"))) ||
99
+ (plan.locks !== undefined &&
100
+ (!Array.isArray(plan.locks) ||
101
+ plan.locks.length > 500 ||
102
+ new Set(plan.locks.map((l) => l?.target)).size !== plan.locks.length ||
103
+ plan.locks.some((lock) => !lock ||
104
+ typeof lock.target !== "string" ||
105
+ !["subtree", "contract"].includes(lock.kind) ||
106
+ (lock.note !== undefined &&
107
+ (typeof lock.note !== "string" || lock.note.length > 4000))))))
98
108
  throw Error("Invalid work plan.");
99
109
  return { entry, plan, revision: hash(body) };
100
110
  }
@@ -248,7 +258,9 @@ async function readFactoryMapUncached(root, ref) {
248
258
  }
249
259
  };
250
260
  const configuration = text("fractory.config.json");
251
- const graph = mapFromArtifacts(configuration ? parseMapConfiguration(configuration) : repositoryMapConfiguration(root), text);
261
+ const graph = mapFromArtifacts(configuration
262
+ ? parseMapConfiguration(configuration)
263
+ : repositoryMapConfiguration(root), text);
252
264
  if (!graph)
253
265
  return null;
254
266
  if (graph.schema !== "fractal.definition.v1" ||
@@ -425,6 +437,9 @@ export function updateWorkPlan(root, id, graph, input, snapshot) {
425
437
  throw Error("This plan changed. Reload it before saving.");
426
438
  const plan = {
427
439
  ...current.plan,
440
+ ...(input.locks !== undefined
441
+ ? { locks: validateLocks(graph, input.locks, current.plan.locks) }
442
+ : {}),
428
443
  proposals: input.proposals === undefined
429
444
  ? current.plan.proposals
430
445
  : validateProposals(graph, input.proposals, current.plan.proposals),
@@ -555,9 +570,20 @@ export function workHandoff(context, graph) {
555
570
  "",
556
571
  ]
557
572
  : []),
573
+ ...lockBrief(graph, plan?.locks || []),
558
574
  "## Intended changes",
575
+ "Connections enter public interfaces. A plain box or internal method is not a valid external destination; preserve the request while choosing its real public contract.",
559
576
  ...(plan?.proposals || []).map((p) => `- [${states[p.id]?.status === "changed" ? "needs recheck" : states[p.id]?.status || "planned"}] ${p.kind === "annotation" ? "comment" : p.kind}: ${p.label || labels.get(p.target || "") || p.target} [${p.id}]${p.resolved ? " [resolved]" : ""}${p.kind === "annotation" && p.target ? `; attached to ${labels.get(p.target) || p.target} (${p.target})` : ""}${p.parent ? `; inside ${labels.get(p.parent) || p.parent}` : ""}${p.source ? `; ${labels.get(p.source) || p.source} → ${labels.get(p.target) || p.target}` : ""}${p.change ? `; ${p.change}` : ""}${p.implementation ? `; implementation: ${labels.get(p.implementation) || p.implementation} (${p.implementation})` : ""}\n ${p.note}`),
560
577
  "",
578
+ ...(plan?.proposals.flatMap((proposal) => {
579
+ const issue = !proposal.implementation &&
580
+ proposalConnectionError(graph, plan, proposal);
581
+ return issue
582
+ ? [
583
+ `Connection ${proposal.label || proposal.id} needs an interface target: ${issue}`,
584
+ ]
585
+ : [];
586
+ }) || []),
561
587
  "Continue planned items and items needing recheck. Done and dropped items remain recorded; do not implement them again without reopening them. Done is an explicit confirmation with a source fingerprint, not a test result.",
562
588
  ...(plan?.pullRequest ? [`Pull request: ${plan.pullRequest.url}`] : []),
563
589
  `Check: fractory work check ${context.id} --root ${JSON.stringify(context.root)}`,
@@ -0,0 +1,12 @@
1
+ import type { DefinitionGraph } from "./model.js";
2
+ import type { WorkPlan, WorkLock } from "./work-model.js";
3
+ export interface LockResult {
4
+ target: string;
5
+ kind: WorkLock["kind"];
6
+ status: "unchanged" | "violated" | "uncertain";
7
+ issues: {
8
+ file?: string;
9
+ message: string;
10
+ }[];
11
+ }
12
+ export declare function checkWorkLocks(root: string, plan: WorkPlan, baseline: DefinitionGraph, graph: DefinitionGraph, changed: string[]): LockResult[];
@@ -0,0 +1,339 @@
1
+ /** Read-only checks against the work's pinned starting revision. Never execute application code. */
2
+ import ts from "typescript";
3
+ import { readFileSync, lstatSync } from "node:fs";
4
+ import { resolve } from "node:path";
5
+ import { checkedPath } from "./workspace-notes.js";
6
+ import { readGit } from "./git-refs.js";
7
+ import { scopeBlocks } from "./work-model.js";
8
+ import { publicContractIds } from "./work-locks.js";
9
+ const stable = (value) => JSON.stringify(value, (_key, v) => v && typeof v === "object" && !Array.isArray(v)
10
+ ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b)))
11
+ : v);
12
+ const refs = (node) => node.sources?.length ? node.sources : node.source ? [node.source] : [];
13
+ const printer = ts.createPrinter({ removeComments: true });
14
+ const print = (n, sf) => printer.printNode(ts.EmitHint.Unspecified, n, sf);
15
+ function declaration(text, ref, contract) {
16
+ const ast = ts.createSourceFile(ref.file, text, ts.ScriptTarget.Latest, true, ref.file.endsWith("x") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
17
+ if (ast.parseDiagnostics
18
+ .length)
19
+ throw Error("Source cannot be parsed");
20
+ const found = [];
21
+ const nameOf = (n) => {
22
+ const name = n.name;
23
+ if (!name)
24
+ return undefined;
25
+ const cls = (ts.isMethodDeclaration(n) || ts.isPropertyDeclaration(n)) &&
26
+ ts.isClassDeclaration(n.parent)
27
+ ? n.parent.name?.text
28
+ : undefined;
29
+ return cls ? `${cls}.${name.getText(ast)}` : name.getText(ast);
30
+ };
31
+ function visit(n) {
32
+ if ((ts.isFunctionDeclaration(n) ||
33
+ ts.isMethodDeclaration(n) ||
34
+ ts.isVariableDeclaration(n) ||
35
+ ts.isInterfaceDeclaration(n) ||
36
+ ts.isTypeAliasDeclaration(n) ||
37
+ ts.isClassDeclaration(n) ||
38
+ ts.isPropertyDeclaration(n)) &&
39
+ (nameOf(n) === ref.symbol ||
40
+ n.name?.getText(ast) === ref.symbol))
41
+ found.push(n);
42
+ ts.forEachChild(n, visit);
43
+ }
44
+ if (ref.symbol)
45
+ visit(ast);
46
+ else if (ref.scope === "file" && contract) {
47
+ // A file-level interface exposes its exported declarations, never every private helper.
48
+ found.push(...ast.statements.filter((n) => ts.canHaveModifiers(n) &&
49
+ ts
50
+ .getModifiers(n)
51
+ ?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)));
52
+ }
53
+ else
54
+ throw Error("No unique source symbol identifies the protected declaration");
55
+ if (!found.length)
56
+ return undefined;
57
+ if (found.length > 1 &&
58
+ !found.every(ts.isFunctionDeclaration) &&
59
+ !found.every((n) => ts.isMethodDeclaration(n) && n.parent === found[0].parent))
60
+ throw Error("Protected source symbol is ambiguous");
61
+ if (!contract)
62
+ return {
63
+ value: found.map((n) => print(n, ast)).join("\n"),
64
+ inferred: false,
65
+ };
66
+ let inferred = false;
67
+ const signatures = found.map((node) => {
68
+ const result = ts.transform(node, [
69
+ (context) => {
70
+ const strip = (n) => {
71
+ if (ts.isClassDeclaration(n)) {
72
+ const members = n.members.filter((m) => !(ts.getCombinedModifierFlags(m) &
73
+ (ts.ModifierFlags.Private | ts.ModifierFlags.Protected) ||
74
+ (m.name && ts.isPrivateIdentifier(m.name))));
75
+ return ts.factory.updateClassDeclaration(n, n.modifiers, n.name, n.typeParameters, n.heritageClauses, members.map((m) => ts.visitNode(m, strip)));
76
+ }
77
+ if (ts.isConstructorDeclaration(n))
78
+ return ts.factory.updateConstructorDeclaration(n, n.modifiers, n.parameters, undefined);
79
+ if (ts.isGetAccessorDeclaration(n)) {
80
+ inferred ||= !!n.body && !n.type;
81
+ return ts.factory.updateGetAccessorDeclaration(n, n.modifiers, n.name, n.parameters, n.type, undefined);
82
+ }
83
+ if (ts.isSetAccessorDeclaration(n))
84
+ return ts.factory.updateSetAccessorDeclaration(n, n.modifiers, n.name, n.parameters, undefined);
85
+ if (ts.isPropertyDeclaration(n)) {
86
+ inferred ||= !!n.initializer && !n.type;
87
+ return ts.factory.updatePropertyDeclaration(n, n.modifiers, n.name, n.questionToken || n.exclamationToken, n.type, undefined);
88
+ }
89
+ if (ts.isFunctionDeclaration(n)) {
90
+ inferred ||= !!n.body && !n.type;
91
+ return ts.factory.updateFunctionDeclaration(n, n.modifiers, n.asteriskToken, n.name, n.typeParameters, n.parameters, n.type, undefined);
92
+ }
93
+ if (ts.isMethodDeclaration(n)) {
94
+ inferred ||= !!n.body && !n.type;
95
+ return ts.factory.updateMethodDeclaration(n, n.modifiers, n.asteriskToken, n.name, n.questionToken, n.typeParameters, n.parameters, n.type, undefined);
96
+ }
97
+ if (ts.isArrowFunction(n)) {
98
+ inferred ||= !n.type;
99
+ return ts.factory.updateArrowFunction(n, n.modifiers, n.typeParameters, n.parameters, n.type, n.equalsGreaterThanToken, ts.factory.createBlock([]));
100
+ }
101
+ if (ts.isFunctionExpression(n)) {
102
+ inferred ||= !n.type;
103
+ return ts.factory.updateFunctionExpression(n, n.modifiers, n.asteriskToken, n.name, n.typeParameters, n.parameters, n.type, ts.factory.createBlock([]));
104
+ }
105
+ return ts.visitEachChild(n, strip, context);
106
+ };
107
+ return (root) => ts.visitNode(root, strip);
108
+ },
109
+ ]);
110
+ let statement = node;
111
+ while (statement.parent && statement.parent !== ast)
112
+ statement = statement.parent;
113
+ const exposure = ts.canHaveModifiers(statement)
114
+ ? ts
115
+ .getModifiers(statement)
116
+ ?.filter((m) => [
117
+ ts.SyntaxKind.ExportKeyword,
118
+ ts.SyntaxKind.DefaultKeyword,
119
+ ].includes(m.kind))
120
+ .map((m) => print(m, ast))
121
+ .join(" ") || ""
122
+ : "";
123
+ const value = exposure + " " + print(result.transformed[0], ast);
124
+ result.dispose();
125
+ return value;
126
+ });
127
+ // Referenced local types and import bindings are part of the syntactic contract.
128
+ // Imported type definitions require a type check when dependencies have changed.
129
+ const referenced = new Set();
130
+ const collect = (n) => {
131
+ if (ts.isTypeReferenceNode(n))
132
+ referenced.add(n.typeName.getText(n.getSourceFile()).split(".")[0]);
133
+ if (ts.isTypeQueryNode(n))
134
+ referenced.add(n.exprName.getText(n.getSourceFile()).split(".")[0]);
135
+ ts.forEachChild(n, collect);
136
+ };
137
+ // Parse the stripped declaration: implementation-only types are not part of its contract.
138
+ collect(ts.createSourceFile("contract.ts", signatures.join("\n"), ts.ScriptTarget.Latest, true));
139
+ const local = ast.statements.filter((n) => ts.isTypeAliasDeclaration(n) || ts.isInterfaceDeclaration(n));
140
+ const types = [];
141
+ let importedTypes = false;
142
+ const used = new Set();
143
+ for (let pending = true; pending;) {
144
+ pending = false;
145
+ for (const n of local)
146
+ if (referenced.has(n.name.text) && !used.has(n.name.text)) {
147
+ used.add(n.name.text);
148
+ types.push(print(n, ast));
149
+ collect(n);
150
+ pending = true;
151
+ }
152
+ }
153
+ for (const n of ast.statements)
154
+ if (ts.isImportDeclaration(n)) {
155
+ const bindings = n.importClause?.namedBindings;
156
+ if (n.importClause?.name && referenced.has(n.importClause.name.text)) {
157
+ importedTypes = true;
158
+ types.push(`default ${n.importClause.name.text} from ${n.moduleSpecifier.getText(ast)}`);
159
+ }
160
+ if (bindings && ts.isNamedImports(bindings))
161
+ for (const item of bindings.elements)
162
+ if (referenced.has(item.name.text))
163
+ types.push(`${item.getText(ast)} from ${n.moduleSpecifier.getText(ast)}`);
164
+ if (bindings &&
165
+ ts.isNamespaceImport(bindings) &&
166
+ referenced.has(bindings.name.text))
167
+ types.push(`${bindings.getText(ast)} from ${n.moduleSpecifier.getText(ast)}`);
168
+ }
169
+ return {
170
+ value: signatures.join("\n") + "\n" + types.sort().join("\n"),
171
+ inferred,
172
+ importedTypes: importedTypes || types.some((text) => text.includes(" from ")),
173
+ };
174
+ }
175
+ export function checkWorkLocks(root, plan, baseline, graph, changed) {
176
+ const changedSet = new Set(changed);
177
+ const cache = new Map();
178
+ function source(file, version) {
179
+ const key = `${version}:${file}`;
180
+ if (cache.has(key))
181
+ return cache.get(key);
182
+ let text;
183
+ try {
184
+ if (version !== "saved")
185
+ text = readGit(root, [
186
+ "show",
187
+ `${version === "base" ? plan.baseCommit : ""}:${file}`,
188
+ ]);
189
+ else {
190
+ const path = checkedPath(root, file), stat = lstatSync(path);
191
+ if (stat.isSymbolicLink() || stat.size > 1024 * 1024)
192
+ throw Error("Linked or oversized source");
193
+ text = readFileSync(resolve(path), "utf8");
194
+ }
195
+ if (text.length > 1024 * 1024 || text.includes("\0"))
196
+ text = undefined;
197
+ }
198
+ catch {
199
+ text = undefined;
200
+ }
201
+ cache.set(key, text);
202
+ return text;
203
+ }
204
+ return (plan.locks || []).map((lock) => {
205
+ const result = {
206
+ target: lock.target,
207
+ kind: lock.kind,
208
+ status: "unchanged",
209
+ issues: [],
210
+ };
211
+ const issue = (status, message, file) => {
212
+ if (result.status !== "violated")
213
+ result.status = status;
214
+ result.issues.push({ ...(file ? { file } : {}), message });
215
+ };
216
+ const old = baseline.elements.find((n) => n.id === lock.target), now = graph.elements.find((n) => n.id === lock.target);
217
+ if (!old) {
218
+ issue("uncertain", "The starting map has no verified boundary for this lock.");
219
+ return result;
220
+ }
221
+ if (!now) {
222
+ issue("violated", "Locked boundary was removed from the map.");
223
+ return result;
224
+ }
225
+ const beforeIds = lock.kind === "subtree"
226
+ ? scopeBlocks(baseline, [lock.target])
227
+ : publicContractIds(baseline, lock.target);
228
+ const afterIds = lock.kind === "subtree"
229
+ ? scopeBlocks(graph, [lock.target])
230
+ : publicContractIds(graph, lock.target);
231
+ const beforeNodes = baseline.elements.filter((n) => beforeIds.has(n.id));
232
+ const afterNodes = graph.elements.filter((n) => afterIds.has(n.id));
233
+ const shape = (nodes) => nodes
234
+ .map((n) => ({
235
+ id: n.id,
236
+ kind: n.kind,
237
+ parent: n.parent,
238
+ contract: n.contract,
239
+ signature: n.signature,
240
+ auth: n.attachments?.auth,
241
+ ...(lock.kind === "subtree"
242
+ ? { implementationBlock: n.implementationBlock }
243
+ : {}),
244
+ }))
245
+ .sort((a, b) => a.id.localeCompare(b.id));
246
+ if (stable(shape(beforeNodes)) !== stable(shape(afterNodes)))
247
+ issue("violated", lock.kind === "contract"
248
+ ? "Public boundary, signature or declared contract changed."
249
+ : "Locked subtree structure or contract changed.");
250
+ const sources = new Map(beforeNodes
251
+ .flatMap((n) => [
252
+ ...refs(n),
253
+ ...(lock.kind === "subtree"
254
+ ? [
255
+ ...(n.attachments?.docs || []),
256
+ ...(n.attachments?.tests || []),
257
+ ].map((file) => ({
258
+ file,
259
+ line: 1,
260
+ digest: "",
261
+ scope: "file",
262
+ }))
263
+ : []),
264
+ ])
265
+ .map((r) => [`${r.file}:${r.scope || r.symbol || r.line}`, r]));
266
+ for (const n of afterNodes)
267
+ for (const r of refs(n)) {
268
+ if (![...sources.values()].some((old) => old.file === r.file &&
269
+ old.symbol === r.symbol &&
270
+ old.scope === r.scope))
271
+ issue("uncertain", "New source ownership in a locked boundary needs review.", r.file);
272
+ }
273
+ for (const ref of sources.values()) {
274
+ const dependencyChange = lock.kind === "contract" &&
275
+ changed.some((f) => f !== ref.file && /\.[cm]?[jt]sx?$/.test(f));
276
+ if (!changedSet.has(ref.file) && !dependencyChange)
277
+ continue;
278
+ const before = source(ref.file, "base");
279
+ const saved = source(ref.file, "saved"), staged = source(ref.file, "index");
280
+ const versions = [["Saved code", saved]];
281
+ if (staged !== saved)
282
+ versions.push(["Staged code", staged]);
283
+ for (const [label, after] of versions) {
284
+ const sourceIssue = (status, message, file) => issue(status, `${label}: ${message}`, file);
285
+ if (before === after && before !== undefined) {
286
+ if (dependencyChange && /\.[cm]?[jt]sx?$/.test(ref.file))
287
+ try {
288
+ const contract = declaration(before, ref, true);
289
+ if (!contract || contract.inferred || contract.importedTypes)
290
+ sourceIssue("uncertain", "Changed type dependencies need a type/API check.", ref.file);
291
+ }
292
+ catch {
293
+ sourceIssue("uncertain", "Dependent contract source cannot be verified.", ref.file);
294
+ }
295
+ continue;
296
+ }
297
+ if (before === undefined) {
298
+ sourceIssue("uncertain", "Starting source is unavailable for this lock.", ref.file);
299
+ continue;
300
+ }
301
+ if (after === undefined) {
302
+ sourceIssue("violated", "Locked source was removed or is unavailable.", ref.file);
303
+ continue;
304
+ }
305
+ if (lock.kind === "subtree" && (ref.scope === "file" || !ref.symbol)) {
306
+ sourceIssue("violated", "Source owned by the locked subtree changed.", ref.file);
307
+ continue;
308
+ }
309
+ if (!/\.[cm]?[jt]sx?$/.test(ref.file)) {
310
+ sourceIssue("uncertain", "This contract needs its language-specific check.", ref.file);
311
+ continue;
312
+ }
313
+ try {
314
+ const b = declaration(before, ref, lock.kind === "contract"), a = declaration(after, ref, lock.kind === "contract");
315
+ if (!b)
316
+ sourceIssue("uncertain", "Starting source symbol cannot be verified.", ref.file);
317
+ else if (!a || a.value !== b.value)
318
+ sourceIssue("violated", lock.kind === "contract"
319
+ ? "Public declaration changed."
320
+ : "Locked implementation changed.", ref.file);
321
+ else if (lock.kind === "contract" && (b.inferred || a.inferred))
322
+ sourceIssue("uncertain", "Return types are inferred; run a type/API check before asserting the contract is unchanged.", ref.file);
323
+ else if (lock.kind === "contract" &&
324
+ dependencyChange &&
325
+ (a.importedTypes || b.importedTypes))
326
+ sourceIssue("uncertain", "Changed type dependencies need a type/API check.", ref.file);
327
+ }
328
+ catch (error) {
329
+ sourceIssue("uncertain", error instanceof Error
330
+ ? error.message
331
+ : "Contract source unavailable.", ref.file);
332
+ }
333
+ }
334
+ }
335
+ if (!sources.size && !old.contract && !old.signature)
336
+ issue("uncertain", "No source or declared contract proves this boundary is unchanged.");
337
+ return result;
338
+ });
339
+ }
@@ -0,0 +1,10 @@
1
+ import type { DefinitionGraph } from "./model.js";
2
+ import type { WorkLock } from "./work-model.js";
3
+ /** Public contracts can nest, but ordinary implementation children are not public
4
+ * merely because they sit inside an interface. Explicit exposure can bridge them. */
5
+ export declare function publicContractIds(graph: DefinitionGraph, target: string): Set<string>;
6
+ /** A subtree lock wins over every nested contract lock; inclusion never unlocks code. */
7
+ export declare function lockIndex(graph: DefinitionGraph, locks: WorkLock[]): Map<string, WorkLock>;
8
+ export declare function lockFor(graph: DefinitionGraph, locks: WorkLock[], id: string): WorkLock | undefined;
9
+ export declare function validateLocks(graph: DefinitionGraph, input: unknown, previous?: WorkLock[]): WorkLock[];
10
+ export declare function lockBrief(graph: DefinitionGraph, locks: WorkLock[]): string[];
@@ -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
+ }
@@ -29,6 +29,12 @@ export interface WorkIntentState {
29
29
  implementation?: string;
30
30
  reason?: string;
31
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
+ }
32
38
  export interface WorkPlan {
33
39
  schema: "fractory.work.v1";
34
40
  id: string;
@@ -40,6 +46,7 @@ export interface WorkPlan {
40
46
  scope: string[];
41
47
  /** Explicit subtree exceptions. The nearest include/exclude rule wins. */
42
48
  excluded?: string[];
49
+ locks?: WorkLock[];
43
50
  proposals: WorkProposal[];
44
51
  bootstrapRevision?: string;
45
52
  pullRequest?: {
@@ -108,3 +115,5 @@ export declare function compactScope(graph: DefinitionGraph, scope: string[]): s
108
115
  export declare function validateProposals(graph: DefinitionGraph, proposals: unknown, previous?: WorkProposal[]): WorkProposal[];
109
116
  /** Display composition only. Proposed elements never enter the compiler's output. */
110
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;
@@ -1,3 +1,4 @@
1
+ import { publicConnectionError, boundaryViolations } from "./public-boundaries.js";
1
2
  export function workTargetLabel(graph, proposals, id) {
2
3
  const block = graph.elements.find((node) => node.id === id) ||
3
4
  proposals.find((p) => p.kind === "block" && p.id === id);
@@ -200,6 +201,38 @@ export function validateProposals(graph, proposals, previous = []) {
200
201
  cursor = parents.get(cursor);
201
202
  }
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
+ }
203
236
  return result;
204
237
  }
205
238
  /** Display composition only. Proposed elements never enter the compiler's output. */
@@ -226,7 +259,7 @@ export function workDisplayGraph(graph, plan, states) {
226
259
  const visual = proposals.filter((p) => p.kind !== "annotation" && needed.has(p.id));
227
260
  if (!visual.length)
228
261
  return graph;
229
- return {
262
+ const scene = {
230
263
  ...graph,
231
264
  revision: `${graph.revision}:plan:${JSON.stringify(visual)}`,
232
265
  elements: [
@@ -258,4 +291,20 @@ export function workDisplayGraph(graph, plan, states) {
258
291
  visual.some((p) => p.kind === "block" && p.id === id))),
259
292
  ],
260
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
+ });
261
310
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@granular-software/fractory",
3
- "version": "0.1.24",
3
+ "version": "0.1.25",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "exports": {
@@ -17,6 +17,8 @@ export interface RuntimeContract {
17
17
  result?: { parse(value: unknown): unknown };
18
18
  }
19
19
  export interface InterfaceOptions extends Attachments {
20
+ /** Explicit publication through enclosing black boxes. Does not change runtime access. */
21
+ exposedBy?: readonly (() => object)[];
20
22
  /** Optional stable identity when adopting an existing mapped interface. */
21
23
  id?: string;
22
24
  label?: string;
@@ -31,6 +33,8 @@ export interface InterfaceRef {
31
33
  readonly options: InterfaceOptions;
32
34
  }
33
35
  export interface BlockOptions extends Attachments {
36
+ /** Publish this block's public interfaces through these enclosing blocks. */
37
+ exposedBy?: readonly (() => object)[];
34
38
  /** Display names only; shapes still come from actual parameters and props. */
35
39
  inputLabel?: string;
36
40
  eventLabel?: string;