lawspec 0.24.0 → 0.25.0

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 (87) hide show
  1. package/CHANGELOG.md +67 -1
  2. package/README.md +29 -22
  3. package/UNICODE-LICENSE.txt +39 -0
  4. package/api.mjs +14 -23
  5. package/bin/lawspec.mjs +186 -65
  6. package/build.json +255 -159
  7. package/builtin-data-names.mjs +73 -0
  8. package/core.wasm +2 -2
  9. package/examples/native-payments/clojure/lawspec.json +13 -2
  10. package/examples/native-payments/csharp/lawspec.json +13 -2
  11. package/examples/native-payments/elixir/lawspec.json +14 -3
  12. package/examples/native-payments/erlang/lawspec.json +14 -3
  13. package/examples/native-payments/fsharp/lawspec.json +14 -3
  14. package/examples/native-payments/gleam/lawspec.json +14 -3
  15. package/examples/native-payments/go/lawspec.json +14 -3
  16. package/examples/native-payments/groovy/lawspec.json +14 -3
  17. package/examples/native-payments/haskell/lawspec.json +14 -3
  18. package/examples/native-payments/java/lawspec.json +14 -3
  19. package/examples/native-payments/javascript/lawspec.json +14 -3
  20. package/examples/native-payments/kotlin/lawspec.json +14 -3
  21. package/examples/native-payments/python/lawspec.json +14 -3
  22. package/examples/native-payments/rust/lawspec.json +14 -3
  23. package/examples/native-payments/scala/lawspec.json +14 -3
  24. package/examples/native-payments/swift/lawspec.json +14 -3
  25. package/examples/native-payments/typescript/lawspec.json +14 -3
  26. package/examples/packages/orders/lawspec.json +25 -5
  27. package/examples/packages/orders/orders.lawspec +36 -34
  28. package/examples/packages/shop-domain/src/domain.lawspec +23 -21
  29. package/examples/packages/shop-tax-1/src/rates.lawspec +4 -4
  30. package/examples/packages/shop-tax-2/src/rates.lawspec +5 -4
  31. package/examples/rc1/authorization-snapshots.lawspec +112 -0
  32. package/examples/rc1/banner-filenames.lawspec +63 -0
  33. package/examples/rc1/bit-codec.lawspec +56 -0
  34. package/examples/rc1/bounded-witness-search.lawspec +144 -0
  35. package/examples/rc1/conflicting-requirements.lawspec +30 -0
  36. package/examples/rc1/constructive-witnesses.lawspec +113 -0
  37. package/examples/rc1/documentary-review.lawspec +42 -0
  38. package/examples/rc1/empty-domains.lawspec +46 -0
  39. package/examples/rc1/finite-integer-domains.lawspec +75 -0
  40. package/examples/rc1/law-metadata.lawspec +29 -0
  41. package/examples/rc1/native-payments.lawspec +107 -0
  42. package/examples/rc1/nesting/rrr.lawspec +33 -0
  43. package/examples/rc1/nesting/rru.lawspec +56 -0
  44. package/examples/rc1/nesting/rur.lawspec +57 -0
  45. package/examples/rc1/nesting/ruu.lawspec +77 -0
  46. package/examples/rc1/nesting/urr.lawspec +52 -0
  47. package/examples/rc1/nesting/uru.lawspec +72 -0
  48. package/examples/rc1/nesting/uur.lawspec +73 -0
  49. package/examples/rc1/nesting/uuu.lawspec +95 -0
  50. package/examples/rc1/order-workflow.lawspec +126 -0
  51. package/examples/rc1/parcel-measurements.lawspec +92 -0
  52. package/examples/rc1/picture-records.lawspec +51 -0
  53. package/examples/rc1/picture-tuples.lawspec +47 -0
  54. package/examples/rc1/record-payloads.lawspec +56 -0
  55. package/examples/rc1/recursive-records.lawspec +64 -0
  56. package/examples/rc1/refund-conformance.lawspec +44 -0
  57. package/examples/rc1/refund-policy.lawspec +88 -0
  58. package/examples/rc1/requirement-composition.lawspec +89 -0
  59. package/examples/rc1/structural-records.lawspec +53 -0
  60. package/examples/rc1-authoring.lawspec +56 -0
  61. package/examples-command.mjs +11 -5
  62. package/explain.mjs +112 -0
  63. package/expression-presentation.mjs +333 -0
  64. package/files.mjs +16 -0
  65. package/index.d.ts +929 -11
  66. package/lsp.mjs +231 -0
  67. package/migrate.mjs +135 -0
  68. package/migration-bindings.mjs +86 -0
  69. package/migration-cases.mjs +45 -0
  70. package/migration-collections.mjs +54 -0
  71. package/migration-correspondence.mjs +275 -0
  72. package/migration-generation.mjs +99 -0
  73. package/migration-laws.mjs +102 -0
  74. package/migration-records.mjs +166 -0
  75. package/migration-source.mjs +247 -0
  76. package/migration-write.mjs +156 -0
  77. package/native-evidence.mjs +187 -0
  78. package/native-examples.mjs +8 -1
  79. package/node-events-reporter.mjs +23 -0
  80. package/package.json +8 -1
  81. package/positional-fields.mjs +13 -0
  82. package/proof.d.ts +35 -0
  83. package/proof.mjs +174 -0
  84. package/starter-rc1.lawspec +25 -0
  85. package/templates.mjs +2 -2
  86. package/test-command.mjs +107 -35
  87. package/typed-presentation.mjs +165 -0
package/bin/lawspec.mjs CHANGED
@@ -6,13 +6,19 @@ import path from "node:path";
6
6
  import { createCompiler } from "../api.mjs";
7
7
  import { targets, templates, commands, setup } from "../templates.mjs";
8
8
  import { generateExamples } from "../examples-command.mjs";
9
+ import { migrationReport } from "../migrate.mjs";
10
+ import { writeMigration } from "../migration-write.mjs";
11
+ import { proveWithZ3 } from "../proof.mjs";
12
+ import { serveLanguage } from "../lsp.mjs";
13
+ import { explainLaw, explanationViews } from "../explain.mjs";
9
14
  import { showScalar } from "../scalars.mjs";
10
15
  import { doctor } from "../doctor.mjs";
16
+ import { recordNativeAttempts, nativeSeed, attestedKeys, readNativeObservations, attachNativeEvidence, nativeEvidenceText } from "../native-evidence.mjs";
11
17
  import { beamCoverageRequirement, collectBeamCoverage } from "../beam-coverage.mjs";
12
18
  import { collectScalaCoverage } from "../scala-coverage.mjs";
13
19
  import { failureDatabase, projectKey } from "../failure-database.mjs";
14
20
  import { spawn, spawnSync } from "node:child_process";
15
- import { benchmarkInvocations, preparationInvocations, environmentDigest, executedTests, invocations, lawKeys, projectDigest, recordedDigest, selectByTags, mergeJunit,
21
+ import { benchmarkInvocations, configurationInvocations, preparationInvocations, environmentDigest, executedTests, invocations, lawKeys, projectDigest, recordedDigest, selectByTags, mergeJunit,
16
22
  harnessStatistics, coverageTools, junitFromTests, testsToRun } from "../test-command.mjs";
17
23
  import {
18
24
  readOptional,
@@ -20,15 +26,16 @@ import {
20
26
  applyWrites,
21
27
  atomicWrite,
22
28
  safePath,
29
+ collectSources,
23
30
  } from "../files.mjs";
24
- const VERSION = "0.24.0";
31
+ const VERSION = "0.25.0";
25
32
  const args = process.argv.slice(2);
26
33
  const verb = args.shift();
27
34
  const options = {};
28
35
  const positional = [];
29
36
  for (let i = 0; i < args.length; i++) {
30
37
  const arg = args[i];
31
- if (["--target", "--project", "--config", "--output", "--machine-bits", "--example", "--seed", "--report", "--attestation"].includes(arg)) {
38
+ if (["--target", "--project", "--config", "--output", "--machine-bits", "--example", "--seed", "--report", "--attestation", "--view", "--from", "--solver", "--proof-timeout", "--proof-memory", "--proof-rlimit", "--proof-seed"].includes(arg)) {
32
39
  if (!args[i + 1] || args[i + 1].startsWith("--"))
33
40
  throw new Error(`Missing value for ${arg}`);
34
41
  options[arg.slice(2)] = args[++i];
@@ -37,7 +44,7 @@ for (let i = 0; i < args.length; i++) {
37
44
  if (!args[i + 1] || args[i + 1].startsWith("--"))
38
45
  throw new Error(`Missing value for ${arg}`);
39
46
  options[arg.slice(2)] = [...(options[arg.slice(2)] ?? []), ...args[++i].split(",").filter(Boolean)];
40
- } else if (["--dry-run", "--check", "--json", "--minify", "--no-cache", "--fresh", "--coverage", "--update-recorded", "--benchmarks"].includes(arg))
47
+ } else if (["--dry-run", "--check", "--json", "--minify", "--no-cache", "--fresh", "--coverage", "--update-recorded", "--benchmarks", "--write", "--stdio", "--warn-matches"].includes(arg))
41
48
  options[arg.slice(2)] = true;
42
49
  else if (arg.startsWith("--")) throw new Error(`Unknown option: ${arg}`);
43
50
  else positional.push(arg);
@@ -85,24 +92,7 @@ function diagnostics(result) {
85
92
  async function sources(config) {
86
93
  return lawspecFiles(configRoot, config.sources);
87
94
  }
88
- async function lawspecFiles(root, entries) {
89
- const files = [];
90
- async function visit(file) {
91
- const info = await stat(file);
92
- if (info.isDirectory())
93
- for (const entry of (await readdir(file)).sort())
94
- await visit(path.join(file, entry));
95
- else if (file.endsWith(".lawspec")) files.push(file);
96
- }
97
- for (const source of entries) await visit(path.resolve(root, source));
98
- if (!files.length) throw new Error("No .lawspec source files found");
99
- return Promise.all(
100
- [...new Set(files)].sort().map(async (file) => ({
101
- path: path.relative(configRoot, file).split(path.sep).join("/"),
102
- content: await readFile(file, "utf8"),
103
- })),
104
- );
105
- }
95
+ async function lawspecFiles(root,entries){return collectSources(root,entries,configRoot);}
106
96
  // A package directory holds lawspec-package.json: its name, version, source
107
97
  // directories and dependency ranges. The compiler checks names, versions,
108
98
  // namespaces and which units may import which.
@@ -136,12 +126,64 @@ async function packageInput(owner, root) {
136
126
  ...(owner.dependencies !== undefined ? { dependencies: owner.dependencies } : {}),
137
127
  };
138
128
  }
129
+ async function migrateCommand() {
130
+ if(options.write&&options["dry-run"])throw new Error("--write and --dry-run cannot be combined");
131
+ if (options.from !== "0.24") throw new Error("migrate requires --from 0.24");
132
+ const configurationText=await readFile(configFile,"utf8");
133
+ const config = JSON.parse(configurationText);
134
+ if (config.version !== 1) throw new Error("migrate --from 0.24 requires configuration version 1");
135
+ const compiler = await createCompiler();
136
+ const input={
137
+ sources: await sources(config), ...(await packageInput(config, configRoot)),
138
+ generation: config.generation, machineBits: config.machineBits ?? 64, minify: options.minify === true,
139
+ };
140
+ const recheck=async()=>{
141
+ const current={sources:await sources(config),...(await packageInput(config,configRoot))};
142
+ const original={sources:input.sources,...Object.fromEntries(['packages','dependencies']
143
+ .filter(key=>input[key]!==undefined).map(key=>[key,input[key]]))};
144
+ if(JSON.stringify(current)!==JSON.stringify(original))throw new Error('Project sources or package dependencies changed during migration.');
145
+ };
146
+ const report=options.write?await writeMigration(compiler,configRoot,path.basename(configFile),configurationText,input,{recheck}):
147
+ await migrationReport(compiler,config,input);
148
+ diagnostics(report);
149
+ const bindingChanges=report.bindingPreview.targets.flatMap(target=>target.evidence?.changes??[]).length;
150
+ const bindingChecked=report.bindingPreview.targets.filter(target=>target.evidence?.beforeValidated===true).length;
151
+ const bindingMatched=report.bindingPreview.targets.filter(target=>target.status==='matched').length;
152
+ const bindingSummary=`Native binding preview: ${bindingChecked} of ${report.bindingPreview.configurationCount} original configurations checked; ${bindingMatched} proposals match; ${bindingChanges} field changes.\n`;
153
+ const generationAccepted=report.generationPreview.targets.filter(target=>target.status==='accepted').length;
154
+ const generationSummary=`Target generation preview: ${generationAccepted} of ${report.generationPreview.configurationCount} configurations accepted. Native implementation conformance remains unestablished.\n`;
155
+ const boundaryMatched=report.generationPreview.targets.filter(target=>target.nativeBoundary.status==='matched').length;
156
+ const boundarySummary=`Native boundary comparison: ${boundaryMatched} of ${report.generationPreview.configurationCount} configurations match under their existing native implementation assumptions.\n`;
157
+ output(options.json ? report : `${options.write?"Written":"Read-only"} migration report: ${report.baseline.laws.length} laws, ${report.baseline.definitions.length} definitions, ${report.constructorChanges.length} constructor payload changes.\n` + bindingSummary + generationSummary + boundarySummary +
158
+ report.blockers.join("\n") + (options.write?`\n${report.filesWritten.length} files written. Existing native implementation assumptions are retained; no law verification is claimed.`:
159
+ `\nNo files were written. ${report.validated?'The migration is validated under its existing compiler and native implementation assumptions. Use --write to apply it.':'Migration remains incomplete.'} Use --json to inspect the complete report.`));
160
+ }
161
+
162
+ async function formatCommand() {
163
+ const config = positional.length ? null : JSON.parse(await readFile(configFile, "utf8"));
164
+ if(config&&(config.version!==2||config.languageProfile!=="1.0-rc.1"))
165
+ throw new Error("Formatting a project requires configuration version 2 and languageProfile 1.0-rc.1; run lawspec migrate --from 0.24 first.");
166
+ const root = positional.length ? process.cwd() : configRoot;
167
+ const files = await collectSources(root, positional.length ? positional : config.sources);
168
+ const compiler = await createCompiler();
169
+ const result = diagnostics(await compiler.format({
170
+ sources: files, ...(config ? await packageInput(config, configRoot) : {}),
171
+ languageProfile: "1.0-rc.1", verification: { layers: [] },
172
+ }));
173
+ const changed = result.formattedSources.filter((file, index) => file.content !== files[index].content);
174
+ if (!options.check) for (const file of changed) await atomicWrite(path.resolve(root, file.path), file.content);
175
+ output(options.json ? { changed: changed.map(file => file.path), check: !!options.check }
176
+ : changed.length ? `${changed.length} source file(s) ${options.check ? "need formatting" : "formatted"}.` : "All sources are formatted.");
177
+ if (options.check && changed.length) process.exitCode = 1;
178
+ }
179
+
139
180
  async function packageCommand() {
140
181
  const directory = path.resolve(options.project || ".");
141
182
  const { manifest, package: own } = await loadPackage(directory);
142
183
  const compiler = await createCompiler();
143
184
  const result = diagnostics(
144
185
  await compiler.check({
186
+ languageProfile: '1.0-rc.1', verification: {layers: []},
145
187
  sources: own.sources,
146
188
  package: { name: own.name, version: own.version },
147
189
  ...(await packageInput(manifest, directory)),
@@ -181,8 +223,10 @@ async function init() {
181
223
  const current = await readOptional(configFile);
182
224
  const config =
183
225
  current === null
184
- ? { version: 1, sources: ["laws"], targets: [] }
226
+ ? { version: 2, languageProfile: "1.0-rc.1", verification: { layers: [] }, sources: ["laws"], targets: [] }
185
227
  : JSON.parse(current);
228
+ if(config.version!==2||config.languageProfile!=='1.0-rc.1')
229
+ throw new Error('Existing projects require configuration version 2 and languageProfile 1.0-rc.1; run lawspec migrate --from 0.24 first.');
186
230
  if (
187
231
  config.targets.some(
188
232
  (t) =>
@@ -228,7 +272,7 @@ async function init() {
228
272
  if (current === null)
229
273
  await atomicWrite(
230
274
  starter,
231
- await readFile(new URL("../starter.lawspec", import.meta.url), "utf8"),
275
+ await readFile(new URL("../starter-rc1.lawspec", import.meta.url), "utf8"),
232
276
  true,
233
277
  );
234
278
  if (options.machineBits !== undefined) config.machineBits = options.machineBits;
@@ -290,7 +334,7 @@ async function lastRuns() {
290
334
  const known = runs.get(law) ?? {};
291
335
  const latest = (known.passed ?? "") > (run.passed ?? "") ? known : run;
292
336
  runs.set(law, { flaky: known.flaky || run.flaky, adequacy: run.adequacy ?? known.adequacy,
293
- passed: latest.passed, environment: latest.environment });
337
+ passed: latest.passed, seed: latest.seed, environment: latest.environment });
294
338
  }
295
339
  }
296
340
  return { runs, attestations };
@@ -401,11 +445,19 @@ async function runTests(compiler, input, selected, roots, config) {
401
445
  }));
402
446
  // The laws the attestation touches, each with how its dependencies
403
447
  // were wired (the run's id and times aside).
404
- const attested = new Map((planned.evidence ?? []).filter((item) => item.against)
405
- .map((item) => [item.declaration, JSON.stringify([item.environment, item.against])]));
448
+ const attested = attestedKeys(planned);
449
+ if(!planned.tests.length&&!options.benchmarks){
450
+ summaries.push({target:target.language,root:target.root,seed:nativeSeed(seed),ran:[],unchanged:0,
451
+ ok:true,testsExecuted:0,selection:'no-selected-native-checks'});
452
+ continue;
453
+ }
406
454
  const pending = await planWrites(root, planned.files);
407
455
  if (pending.changes.length)
408
456
  throw new Error(`${target.language}: generated files are out of date; run lawspec generate${options.minify ? " --minify" : ""}`);
457
+ for(const preparation of configurationInvocations(target)){
458
+ const result=await spawned(preparation.command,preparation.args,root,process.env);
459
+ if(!result.ok)throw new Error(`${target.language}: native build metadata preparation failed`);
460
+ }
409
461
  const report_ = await doctor(target, root, planned.files);
410
462
  if (!report_.ok) throw new Error(`${target.language}: ${report_.message}\n${report_.instructions}`);
411
463
  const generated = new Set(planned.files.filter((f) => f.ownership === "generated").map((f) => f.path));
@@ -420,6 +472,7 @@ async function runTests(compiler, input, selected, roots, config) {
420
472
  const identity = projectKey(root);
421
473
  const resultsFile = path.join(configRoot, ".lawspec", "results", `${target.language}-${identity}.json`);
422
474
  const previous = JSON.parse((await readOptional(resultsFile)) ?? '{"version":1,"laws":{}}');
475
+ const attempts = {...(previous.attempts ?? {})};
423
476
  const {directory: failures, file: databaseFile, database} = await failureDatabase(configRoot, target.language, root);
424
477
  // Recording again runs every law, so each records what it sees now.
425
478
  const chosen = selectByTags(planned.tests, options.tag ?? [], options["exclude-tag"] ?? []);
@@ -431,10 +484,23 @@ async function runTests(compiler, input, selected, roots, config) {
431
484
  // databases beside it (Hypothesis, proptest).
432
485
  const replayed = options.seed === undefined ? stale.filter((entry) => database[entry.law]) : [];
433
486
  const batches = [
434
- ...[...new Set(replayed.map((entry) => database[entry.law].seed))].map((s) =>
435
- ({ seed: String(s), entries: replayed.filter((entry) => database[entry.law].seed === s) })),
487
+ ...[...new Set(replayed.map((entry) => nativeSeed(database[entry.law].seed)))].map((s) =>
488
+ ({ seed: String(s), entries: replayed.filter((entry) => nativeSeed(database[entry.law].seed) === s) })),
436
489
  { seed, entries: stale.filter((entry) => !replayed.includes(entry)) },
437
490
  ].filter((batch) => batch.entries.length);
491
+ const profile = {target:target.language,root,machineBits:input.machineBits,
492
+ minify:options.minify===true,build};
493
+ // Persist pending attempts before starting a native process. Interrupted or
494
+ // failed setup cannot leave an older passing cache entry looking completed.
495
+ for(const entry of stale){
496
+ Object.assign(attempts,recordNativeAttempts({laws:[entry],command:null},[],
497
+ {keys,seed,ok:false,profile,allEntries:planned.tests}));
498
+ }
499
+ const pendingLaws=Object.fromEntries(Object.entries(previous.laws??{})
500
+ .filter(([id])=>!stale.some(entry=>entry.law===id)));
501
+ await mkdir(path.dirname(resultsFile),{recursive:true});
502
+ await writeFile(path.join(path.dirname(resultsFile),".gitignore"),"*\n");
503
+ await atomicWrite(resultsFile,JSON.stringify({...previous,version:1,laws:pendingLaws,attempts},null,2)+"\n");
438
504
  const passed = [];
439
505
  const unrun = [];
440
506
  let failed = false;
@@ -477,21 +543,26 @@ async function runTests(compiler, input, selected, roots, config) {
477
543
  batches: for (const batch of batches) {
478
544
  for (const run of invocations(target, batch.entries, { offline, scratch, coverage: useCoverage ? coverage : null,
479
545
  xdist, root, coverageConfig: report_.coverage })) {
480
- const since = Date.now() - 1000;
546
+ const since = Date.now();
481
547
  const { ok, output } = await spawned(run.command, run.args, root,
482
548
  { ...process.env, ...run.env, LAWSPEC_SEED: batch.seed, HSPEC_SEED: batch.seed,
483
549
  LAWSPEC_STATS: stats, LAWSPEC_FAILURES: failures, LAWSPEC_RECORDED: recordedFolder,
484
550
  ...(options["update-recorded"] ? { LAWSPEC_UPDATE_RECORDED: "1" } : {}) }, run.report?.kind === "go-json");
485
551
  if (run.coverage) coverageRuns.push(run.coverage);
486
552
  const executed = await executedTests(run.report, output, root, since);
553
+ const observed=recordNativeAttempts(run,executed,{keys,seed:batch.seed,ok,profile,output,allEntries:planned.tests});
554
+ if(!ok&&!run.laws.length)Object.assign(attempts,recordNativeAttempts({laws:batch.entries,command:run.command},[],
555
+ {keys,seed:batch.seed,ok:false,profile,output,allEntries:planned.tests}));
556
+ Object.assign(attempts,observed);
487
557
  for (const law of run.laws) seedOf.set(law.law, batch.seed);
558
+ // A completed combined model method remains scoped to its own checks,
559
+ // even if another selected method in this invocation failed.
560
+ passed.push(...run.laws.filter(entry=>['passed','known-failing'].includes(observed[entry.law]?.outcome)||!expected(entry)));
488
561
  if (report) junit.push({ target: `${target.language} (${target.root})`, xml: await junitOf(run, executed, root, since) });
489
562
  if (!ok || executed.some((test) => test.status === "failed")) { failed = true; break batches; }
490
563
  // A runner whose filter matched nothing reports success, so a law
491
564
  // counts as passed only if the runner's report shows its tests ran.
492
- const ran = new Set(executed.flatMap(run.ran ?? (() => [])));
493
- passed.push(...run.laws.filter((law) => ran.has(law) || !expected(law)));
494
- unrun.push(...run.laws.filter((law) => !ran.has(law) && expected(law)));
565
+ unrun.push(...run.laws.filter(entry=>!passed.includes(entry)&&expected(entry)));
495
566
  }
496
567
  }
497
568
  if (unrun.length) failed = true;
@@ -523,7 +594,7 @@ async function runTests(compiler, input, selected, roots, config) {
523
594
  for (const entry of passed) {
524
595
  const label = entry.label;
525
596
  const observed = statistics.filter((s) => s.law === label);
526
- laws[entry.law] = { key: keys.get(entry.law), seed: Number(seedOf.get(entry.law) ?? seed), passed: new Date().toISOString(),
597
+ laws[entry.law] = { key: keys.get(entry.law), seed: nativeSeed(seedOf.get(entry.law) ?? seed), passed: new Date().toISOString(),
527
598
  // A law the attestation touches names the run it passed in.
528
599
  ...(attestation && attested.has(entry.law) ? { environment: attestation.run.id } : {}),
529
600
  ...(observed.some((s) => s.outcome === "flaky") ? { flaky: true } : {}),
@@ -533,9 +604,10 @@ async function runTests(compiler, input, selected, roots, config) {
533
604
  // A law that failed is recorded with its seed; one that passed leaves.
534
605
  for (const entry of stale) {
535
606
  if (passed.includes(entry)) delete database[entry.law];
536
- else if (seedOf.has(entry.law)) {
607
+ else {
537
608
  delete laws[entry.law];
538
- database[entry.law] = { seed: Number(seedOf.get(entry.law)), failed: new Date().toISOString() };
609
+ if(!seedOf.has(entry.law))continue;
610
+ database[entry.law] = { seed: nativeSeed(seedOf.get(entry.law)), failed: new Date().toISOString() };
539
611
  }
540
612
  }
541
613
  await writeFile(path.join(configRoot, ".lawspec", "failures", ".gitignore"), "*\n");
@@ -546,14 +618,14 @@ async function runTests(compiler, input, selected, roots, config) {
546
618
  const attestations = Object.fromEntries(Object.entries({ ...(previous.attestations ?? {}),
547
619
  ...(attestation ? { [attestation.run.id]: attestation } : {}) })
548
620
  .filter(([id]) => Object.values(laws).some((run) => run.environment === id)));
549
- await writeFile(resultsFile, JSON.stringify({ version: 1, laws,
621
+ await atomicWrite(resultsFile, JSON.stringify({ version: 1, laws, attempts,
550
622
  ...(Object.keys(attestations).length ? { attestations } : {}) }, null, 2) + "\n");
551
623
  const flaky = statistics.filter((s) => s.outcome === "flaky").map((s) => s.law);
552
624
  const unmet = statistics.flatMap((s) => (s.cover ?? []).filter((c) => !c.met).map((c) => `${s.law}: cover ${c.required}% "${c.label}" (${c.observed}%)`));
553
625
  const benchmarks = statistics.filter((s) => s.benchmark);
554
626
  // How each parallel unit's tests actually ran at the same time.
555
627
  const parallelism = statistics.filter((s) => s.parallel).map(({ parallel, mode, workers }) => ({ unit: parallel, mode, workers }));
556
- summaries.push({ target: target.language, root: target.root, seed: Number(seed), ran: stale.map((e) => e.law),
628
+ summaries.push({ target: target.language, root: target.root, seed: nativeSeed(seed), ran: stale.map((e) => e.law),
557
629
  ...(attestation ? { environment: attestation.environment } : {}),
558
630
  unchanged: chosen.length - stale.length, ok: !failed,
559
631
  ...(chosen.length !== planned.tests.length ? { deselected: planned.tests.length - chosen.length } : {}),
@@ -571,7 +643,8 @@ async function runTests(compiler, input, selected, roots, config) {
571
643
  }
572
644
  output(options.json ? summaries : summaries.map((s) =>
573
645
  `${s.target}${summaries.filter(other => other.target === s.target).length > 1 ? ` (${s.root})` : ""}: ${s.ran.length ? `ran ${s.ran.length} law(s) with seed ${s.seed}${s.environment ? ` in environment ${s.environment}` : ""}` : "nothing to run"}` +
574
- `, ${s.unchanged} unchanged since their last passing run.${s.ok ? "" : " FAILED"}` +
646
+ (s.selection==='no-selected-native-checks'?'; no native checks selected; intrinsic definition checks passed.':
647
+ `, ${s.unchanged} unchanged since their last passing run.${s.ok ? "" : " FAILED"}`) +
575
648
  (s.deselected ? `\n${s.deselected} law(s) not selected by --tag or --exclude-tag.` : "") +
576
649
  (s.unrun ? `\nNo tests ran for ${s.unrun.join(", ")}; the runner matched none of their tests.` : "") +
577
650
  (s.flaky ? `\nFlaky (failed, then passed on a retry): ${s.flaky.join(", ")}` : "") +
@@ -672,7 +745,7 @@ async function main() {
672
745
  }
673
746
  if (!verb || ["help", "--help", "-h"].includes(verb)) {
674
747
  output(
675
- "LawSpec " + VERSION + "\nUsage: lawspec init --target <language> [--project <directory>] [--minify]\n lawspec check | doctor | explain <unit>::<law> | generate\n lawspec evidence [<unit> | <unit>::<declaration>] [--attestation <file>]\n lawspec test [--target <language>] [--fresh] [--seed <n>] [--attestation <file>] [--update-recorded] [--tag <t>] [--exclude-tag <t>] [--report junit=<path>] [--coverage] [--benchmarks]\n lawspec package [--project <package directory>]\n lawspec examples [--example payments] [--target <language>] [--output <directory>]\nOptions: --config <path>, --target <language>, --machine-bits <32|64>, --json, --no-cache\nGeneration: --dry-run, --check, --minify\nTargets: " +
748
+ "LawSpec " + VERSION + "\nUsage: lawspec init --target <language> [--project <directory>] [--minify]\n lawspec fmt [paths...] [--check]\n lawspec migrate --from 0.24 [--write]\n lawspec lsp --stdio\n lawspec prove [--solver <z3-executable>] [--proof-timeout <ms>] [--json]\n lawspec check [--warn-matches] | doctor | explain [<unit>::<law>] [--view developer|business|formal|evidence] | generate\n lawspec evidence [<unit> | <unit>::<declaration>] [--attestation <file>]\n lawspec test [--target <language>] [--fresh] [--seed <n>] [--attestation <file>] [--update-recorded] [--tag <t>] [--exclude-tag <t>] [--report junit=<path>] [--coverage] [--benchmarks]\n lawspec package [--project <package directory>]\n lawspec examples [--example payments] [--target <language>] [--output <directory>]\nOptions: --config <path>, --target <language>, --machine-bits <32|64>, --json, --no-cache\nGeneration: --dry-run, --check, --minify\nTargets: " +
676
749
  targets.join(", "),
677
750
  );
678
751
  return;
@@ -681,7 +754,7 @@ async function main() {
681
754
  output(VERSION);
682
755
  return;
683
756
  }
684
- if (positional.length > (["explain", "evidence"].includes(verb) ? 1 : 0))
757
+ if (verb !== "fmt" && positional.length > (["explain", "evidence"].includes(verb) ? 1 : 0))
685
758
  throw new Error(`Unexpected argument: ${positional.join(" ")}`);
686
759
  if (verb === "examples") {
687
760
  if (
@@ -712,6 +785,9 @@ async function main() {
712
785
  );
713
786
  return;
714
787
  }
788
+ if (["solver","proof-timeout","proof-memory","proof-rlimit","proof-seed"].some(key => options[key] !== undefined) && verb !== "prove")
789
+ throw new Error("Z3 options apply to prove");
790
+ if (options.view && verb !== "explain") throw new Error("--view applies to explain");
715
791
  if (options.output) throw new Error("--output is only supported by examples");
716
792
  if (options.example) throw new Error("--example is only supported by examples");
717
793
  if (options.minify && !["init", "generate", "examples", "test"].includes(verb))
@@ -723,23 +799,35 @@ async function main() {
723
799
  throw new Error("--attestation applies to evidence and test");
724
800
  if (options.seed !== undefined && !/^[0-9]+$/.test(options.seed))
725
801
  throw new Error("--seed must be a whole number");
802
+ if (options.from && verb !== "migrate") throw new Error("--from applies to migrate");
803
+ if (options.write && verb !== "migrate") throw new Error("--write applies to migrate");
804
+ if (options["warn-matches"] && verb !== "check") throw new Error("--warn-matches applies to check");
805
+ if (options.stdio && verb !== "lsp") throw new Error("--stdio applies to lsp");
806
+ if (verb === "migrate") return migrateCommand();
807
+ if (verb === "lsp") {
808
+ if (!options.stdio) throw new Error("lsp requires --stdio");
809
+ return serveLanguage();
810
+ }
811
+ if (verb === "fmt") return formatCommand();
726
812
  if (verb === "init") return init();
727
813
  if (verb === "package") return packageCommand();
728
- if (!["check", "doctor", "evidence", "explain", "generate", "test"].includes(verb))
814
+ if (!["check", "doctor", "evidence", "explain", "generate", "test", "prove"].includes(verb))
729
815
  throw new Error(`Unknown command: ${verb}`);
730
816
  const config = JSON.parse(await readFile(configFile, "utf8"));
731
817
  if (
732
- config.version !== 1 ||
818
+ config.version!==2 ||
733
819
  !Array.isArray(config.sources) ||
734
820
  !Array.isArray(config.targets)
735
821
  )
736
822
  throw new Error(
737
- "Expected lawspec.json version 1 with sources and targets arrays",
823
+ "Expected lawspec.json version 2 with languageProfile 1.0-rc.1, sources and targets arrays; run lawspec migrate --from 0.24 for version 1 projects",
738
824
  );
825
+ if (config.languageProfile !== "1.0-rc.1") throw new Error("Configuration version 2 requires languageProfile 1.0-rc.1");
739
826
  const selected = config.targets.filter(
740
827
  (t) => !options.target || t.language === options.target,
741
828
  );
742
- if (["doctor", "generate", "test"].includes(verb) && !selected.length)
829
+ if (["doctor", "generate", "test"].includes(verb) && !selected.length &&
830
+ !(verb === "test" && !options.benchmarks && config.version === 2 && !(config.verification?.layers ?? []).some(layer => ["exhaustive", "property", "examples", "model"].includes(layer))))
743
831
  throw new Error("No matching configured target");
744
832
  const roots = selected.map((t) => path.resolve(configRoot, t.root));
745
833
  if (new Set(roots).size !== roots.length)
@@ -769,11 +857,28 @@ async function main() {
769
857
  const input = {
770
858
  ...(cache === undefined ? {} : { cacheDirectory: cache }),
771
859
  sources: await sources(config),
860
+ languageProfile: config.languageProfile, verification: config.verification ?? { layers: [] },
772
861
  ...(await packageInput(config, configRoot)),
773
862
  generation: config.generation,
774
863
  machineBits: options.machineBits ?? config.machineBits ?? 64,
775
864
  };
776
865
  const compiler = await createCompiler();
866
+ if (verb === "prove") {
867
+ if (config.version !== 2) throw new Error("prove requires configuration version 2 and languageProfile 1.0-rc.1");
868
+ const result = diagnostics(await proveWithZ3(compiler, input, {
869
+ ...(options.solver !== undefined ? {binary: options.solver} : {}),
870
+ ...Object.fromEntries([["proof-timeout","timeoutMs"],["proof-memory","memoryMb"],
871
+ ["proof-rlimit","resourceLimit"],["proof-seed","seed"]]
872
+ .filter(([name]) => options[name] !== undefined).map(([name,key]) => [key,Number(options[name])])),
873
+ }));
874
+ output(options.json ? result : result.solverEvidence.length
875
+ ? result.solverEvidence.map(row => `${row.declaration}: ${row.status} (${row.outcome}). ${row.reason}`).join("\n")
876
+ : (input.verification?.layers.includes("proof")
877
+ ? "No source law obligations are available. No solver was invoked."
878
+ : "No proof layer selected. Intrinsic definition checks passed; no solver was invoked."));
879
+ if (result.solverEvidence.some(row => row.status !== "proved")) process.exitCode = 2;
880
+ return;
881
+ }
777
882
  // Each obligation reports how it is discharged, strongest first.
778
883
  const statuses = [
779
884
  ["proved", "PROVED"],
@@ -788,6 +893,10 @@ async function main() {
788
893
  ["known-failing", "KNOWN FAILING"],
789
894
  ["flaky", "FLAKY"],
790
895
  ["skipped", "SKIPPED"],
896
+ ["planned", "PLANNED"],
897
+ ["not-verified", "NOT VERIFIED"],
898
+ ["incomplete", "INCOMPLETE"],
899
+ ["unsupported", "UNSUPPORTED"],
791
900
  ];
792
901
  const evidenceSummary = (evidence) => {
793
902
  if (!evidence.length) return "";
@@ -800,7 +909,9 @@ async function main() {
800
909
  };
801
910
  const obligationName = (item) => item.declaration.replace("::law::", "::");
802
911
  if (verb === "check") {
803
- const result = diagnostics(await compiler.check(input));
912
+ const result = diagnostics(await compiler.check({...input, ...(options["warn-matches"] ? {warnMatches:true} : {})}));
913
+ if (!options.json) for (const warning of result.warnings ?? [])
914
+ console.error(`${warning.at ? `${warning.at.file}:${warning.at.line}:${warning.at.column}: ` : ""}warning ${warning.code}: ${warning.message}`);
804
915
  for (const target of selected) {
805
916
  if (target.nativeBindings !== undefined)
806
917
  diagnostics(await compiler.check({...input, nativeBindings: target.nativeBindings}));
@@ -808,7 +919,9 @@ async function main() {
808
919
  output(
809
920
  options.json
810
921
  ? result
811
- : `Checked ${result.laws.length} law(s).` + evidenceSummary(result.evidence ?? []),
922
+ : `Compiled ${result.laws.length} law(s). Intrinsic definition checks passed.` +
923
+ (result.verification?.selection === "no-selected-checks"
924
+ ? " No law checks selected." : evidenceSummary(result.evidence ?? [])),
812
925
  );
813
926
  return;
814
927
  }
@@ -817,18 +930,20 @@ async function main() {
817
930
  // ran; otherwise each law shows the attested run it last passed in.
818
931
  const named = await readAttestation(config);
819
932
  const result = diagnostics(await compiler.check({ ...input, ...(named ? { attestation: named } : {}) }));
820
- let evidence = result.evidence;
933
+ let evidence = attachNativeEvidence(result.evidence,await readNativeObservations({compiler,input,selected,roots,
934
+ configRoot,build:await buildDigest(),evidence:result.evidence,attestation:named}));
821
935
  const { runs, attestations } = await lastRuns();
822
936
  const environments = named ? [result.attestation] : [];
823
937
  if (!named) for (const [id, attestation] of attestations) {
824
938
  const laws = new Set([...runs].filter(([, run]) => run.environment === id).map(([law]) => law));
825
939
  if (!laws.size) continue;
826
940
  const attested = diagnostics(await compiler.check({ ...input, attestation }));
827
- const fields = new Map(attested.evidence.filter((item) => item.against && laws.has(item.declaration))
828
- .map(({ declaration, environment, environmentRun, against }) => [declaration, { environment, environmentRun, against }]));
941
+ const fields = new Map(attested.evidence.filter((item) => (item.against || item.plannedAgainst) && laws.has(item.declaration))
942
+ .map(item => [item.declaration, {environment: item.environment ?? item.plannedEnvironment,
943
+ environmentRun: item.environmentRun ?? item.plannedEnvironmentRun, against: item.against ?? item.plannedAgainst}]));
829
944
  evidence = evidence.map((item) => item.stage === "law" && fields.has(item.declaration) ? { ...item, ...fields.get(item.declaration) } : item);
830
945
  environments.push({ ...attested.attestation, dependencies: attested.attestation.dependencies
831
- .map((d) => ({ ...d, obligations: d.obligations.filter((law) => laws.has(law)) })) });
946
+ .map((d) => ({ ...d, obligations: [...new Set([...d.obligations, ...(d.plannedObligations ?? [])])].filter((law) => laws.has(law)), plannedObligations: [] })) });
832
947
  }
833
948
  // Native bindings are configured per target; their obligations are added.
834
949
  for (const target of selected) {
@@ -844,9 +959,10 @@ async function main() {
844
959
  // The last run's outcome (lawspec test): a law that failed, then passed
845
960
  // on a retry, is flaky; what its generated cases covered is its adequacy.
846
961
  evidence = evidence.map((item) => {
962
+ if(item.nativeEvidence)return item;
847
963
  const run = item.stage === "law" ? runs.get(item.declaration) : undefined;
848
964
  if (!run) return item;
849
- return { ...item, ...(run.adequacy ? { adequacy: run.adequacy } : {}),
965
+ return { ...item, lastNativeRun: {passed: run.passed, seed: run.seed}, ...(run.adequacy ? { adequacy: run.adequacy } : {}),
850
966
  ...(run.flaky && ["property-tested", "exhaustively-checked"].includes(item.status)
851
967
  ? { status: "flaky", reason: `${item.reason}; its last run failed, then passed on a retry` } : {}) };
852
968
  });
@@ -861,7 +977,9 @@ async function main() {
861
977
  return `${label} (${items.length})\n` + items.map((item) =>
862
978
  ` ${item.stage} ${obligationName(item)}${item.target ? ` [${item.target}]` : ""}` +
863
979
  (item.claim ? `: ${item.claim.text}` : "") + `\n ${item.reason}` +
864
- (item.against ? `\n ran in environment ${item.environment} (run ${item.environmentRun.id}) against ` +
980
+ (item.nativeEvidence ? `\n ${nativeEvidenceText(item).replaceAll("\n","\n ")}` : "") +
981
+ (item.lastNativeRun ? `\n last native run passed at ${item.lastNativeRun.passed} (seed ${item.lastNativeRun.seed})` : "") +
982
+ (item.against ? `\n last recorded passing run in environment ${item.environment} (run ${item.environmentRun.id}) against ` +
865
983
  item.against.map(dependencyText).join("; ") : "")).join("\n");
866
984
  })
867
985
  .filter((section) => section !== null),
@@ -871,7 +989,8 @@ async function main() {
871
989
  // Where the tests ran: reporting only, so no status above changes.
872
990
  ...environments.map((e) => `ENVIRONMENT ${e.environment} (run ${e.run.id}, recorded ${e.run.recordedAt})\n` +
873
991
  e.dependencies.map((d) => ` ${dependencyText(d)}; ` + (d.obligations.length
874
- ? `${d.obligations.length} tested obligation(s)` : "no tested obligation relies on it")).join("\n"))]
992
+ ? `${d.obligations.length} tested obligation(s)` :
993
+ d.plannedObligations?.length ? `${d.plannedObligations.length} planned obligation(s); no completed run linked` : "no tested obligation relies on it")).join("\n"))]
875
994
  .join("\n\n"),
876
995
  );
877
996
  return;
@@ -884,17 +1003,19 @@ async function main() {
884
1003
  ({ e }) => !positional[0] || `${e.owner}::${e.name}` === positional[0],
885
1004
  );
886
1005
  if (!indices.length) throw new Error("No matching law");
887
- output(
888
- options.json
889
- ? indices.map(({ e, i }) => ({ ...e, expansion: result.expansions[i] }))
890
- : indices
891
- .map(
892
- ({ e, i }) =>
893
- `${e.owner}::${e.name}\n${e.trace.join("\n=> ")}\n=> ${result.expansions[i]}` +
894
- explainAbilities(e, result.expansions[i], result.units) + explainExamples(e),
895
- )
896
- .join("\n\n"),
897
- );
1006
+ const view = options.view ?? "developer";
1007
+ if (!explanationViews.includes(view)) throw new Error(`Choose --view ${explanationViews.join("|")}`);
1008
+ const observed={...result,evidence:attachNativeEvidence(result.evidence,await readNativeObservations({
1009
+ compiler,input,selected,roots,configRoot,build:await buildDigest(),evidence:result.evidence,
1010
+ attestation:await readAttestation(config)}))};
1011
+ const explanations = indices.map(({e}) => explainLaw(e, observed, view));
1012
+ output(options.json ? explanations : explanations.map(e => e.text).join("\n\n"));
1013
+ return;
1014
+ }
1015
+ if (verb === "test" && !options.benchmarks && config.version === 2 && !(config.verification?.layers ?? []).some(layer => ["exhaustive", "property", "examples", "model"].includes(layer))) {
1016
+ const checked = diagnostics(await compiler.check(input));
1017
+ output(options.json ? { verification: checked.verification, evidence: checked.evidence, testsExecuted: 0 }
1018
+ : (config.verification?.layers?.length ? "No native law checks selected. See lawspec evidence for the selected static analyses." : "No law verification layers selected. Intrinsic definition checks passed; no law checks ran."));
898
1019
  return;
899
1020
  }
900
1021
  if (verb === "test") return runTests(compiler, input, selected, roots, config);