lawspec 0.26.0 → 0.28.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 (55) hide show
  1. package/CHANGELOG.md +178 -1
  2. package/NORMALIZATION-LICENSES.txt +296 -0
  3. package/README.md +8 -0
  4. package/bin/lawspec.mjs +126 -33
  5. package/build.json +159 -131
  6. package/builtin-data-names.mjs +4 -4
  7. package/core.wasm +2 -2
  8. package/core_jsffi.js +5 -5
  9. package/doctor.mjs +14 -4
  10. package/examples/native-payments/elixir/lib/payments_domain.ex +1 -1
  11. package/examples/native-payments/erlang/src/payments_domain.erl +1 -1
  12. package/examples/native-payments/prolog/lawspec.json +20 -0
  13. package/examples/native-payments/prolog/src/domain/payments.pl +23 -0
  14. package/examples/native-payments/prolog/tests/domain/payment_generators.pl +17 -0
  15. package/examples/rc1/bit-codec.lawspec +6 -6
  16. package/examples/rc1/native-payments.lawspec +6 -6
  17. package/examples/rc1/nesting/rrr.lawspec +2 -2
  18. package/examples/rc1/nesting/rru.lawspec +4 -4
  19. package/examples/rc1/nesting/rur.lawspec +4 -4
  20. package/examples/rc1/nesting/ruu.lawspec +5 -5
  21. package/examples/rc1/nesting/urr.lawspec +4 -4
  22. package/examples/rc1/nesting/uru.lawspec +5 -5
  23. package/examples/rc1/nesting/uur.lawspec +5 -5
  24. package/examples/rc1/nesting/uuu.lawspec +6 -6
  25. package/examples/rc1/recursive-records.lawspec +5 -5
  26. package/examples/rc1/refund-policy.lawspec +4 -0
  27. package/examples/specs/approvals.lawspec +3 -3
  28. package/examples/specs/builtins.lawspec +2 -2
  29. package/examples/specs/collections.lawspec +8 -8
  30. package/examples/specs/composition.lawspec +10 -10
  31. package/examples/specs/contracts.lawspec +2 -2
  32. package/examples/specs/crypto.lawspec +2 -2
  33. package/examples/specs/domain_modeling.lawspec +20 -0
  34. package/examples/specs/flow_stack.lawspec +4 -4
  35. package/examples/specs/generation.lawspec +2 -2
  36. package/examples/specs/limits.lawspec +1 -1
  37. package/examples/specs/list_contracts.lawspec +3 -3
  38. package/examples/specs/lists.lawspec +6 -6
  39. package/examples/specs/matching.lawspec +8 -8
  40. package/examples/specs/payments.lawspec +5 -5
  41. package/examples/specs/records.lawspec +4 -4
  42. package/examples/specs/refinements.lawspec +4 -0
  43. package/examples/specs/resilience.lawspec +2 -2
  44. package/examples/specs/resources.lawspec +5 -5
  45. package/examples/specs/sequences.lawspec +1 -1
  46. package/examples/specs/sum_refinements.lawspec +11 -11
  47. package/examples-command.mjs +3 -1
  48. package/index.d.ts +160 -4
  49. package/native-evidence.mjs +25 -12
  50. package/native-examples.mjs +1 -1
  51. package/package.json +2 -1
  52. package/proof.d.ts +57 -12
  53. package/proof.mjs +277 -13
  54. package/templates.mjs +84 -3
  55. package/test-command.mjs +40 -4
package/proof.mjs CHANGED
@@ -10,7 +10,8 @@ import path from 'node:path';
10
10
  const hash=value=>createHash('sha256').update(value).digest('hex');
11
11
  const frame=value=>Buffer.byteLength(value,'utf8')+':'+value;
12
12
  const fingerprint=values=>hash(values.map(frame).join(''));
13
- const encoding='lawspec-smtlib-v1';
13
+ // v1 is frozen byte for byte; tasks that need later features are v2.
14
+ const encodings=['lawspec-smtlib-v1','lawspec-smtlib-v2'];
14
15
 
15
16
  export function proofTaskFingerprint(task) {
16
17
  return fingerprint([task.encoding,task.programFingerprint,String(task.machineBits),
@@ -45,7 +46,9 @@ async function executable(binary) {
45
46
 
46
47
  // Only the first response line is a protocol token. Models and unknown reasons
47
48
  // remain raw prover output; this host does not implement another SMT parser.
48
- function execute(binary,args,initial,config,interactive=false) {
49
+ const followUp=token=>token==='sat'?'(get-model)\n(exit)\n':
50
+ token==='unknown'?'(get-info :reason-unknown)\n(exit)\n':'(exit)\n';
51
+ function execute(binary,args,initial,config,interactive=false,finishFor=followUp) {
49
52
  return new Promise(resolve=>{
50
53
  const started=performance.now();
51
54
  const child=spawn(binary,args,{stdio:['pipe','pipe','pipe'],shell:false});
@@ -62,8 +65,7 @@ function execute(binary,args,initial,config,interactive=false) {
62
65
  const token=stdout.slice(0,stdout.indexOf('\n')).trim();
63
66
  if(['sat','unsat','unknown'].includes(token))outcome=token;
64
67
  else error='unexpected Z3 protocol response';
65
- const finish=token==='sat'?'(get-model)\n(exit)\n':
66
- token==='unknown'?'(get-info :reason-unknown)\n(exit)\n':'(exit)\n';
68
+ const finish=finishFor(token);
67
69
  input+=finish;
68
70
  child.stdin.end(finish);
69
71
  }
@@ -82,10 +84,13 @@ function execute(binary,args,initial,config,interactive=false) {
82
84
  });
83
85
  }
84
86
 
87
+ const versionProbeMs=30000;
85
88
  async function prover(config) {
86
89
  const binary=await executable(config.binary);
87
90
  const binaryFingerprint=hash(await readFile(binary));
88
- const versionRun=await execute(binary,['-version'],'',config);
91
+ // The identity probe has its own bound: the task limit is for a solver's
92
+ // work on a task, and the probe does none.
93
+ const versionRun=await execute(binary,['-version'],'',{...config,timeoutMs:versionProbeMs});
89
94
  const version=versionRun.stdout.trim();
90
95
  if(versionRun.exitCode!==0||versionRun.error||versionRun.timeout||versionRun.outputLimit||
91
96
  !/^Z3 version [0-9]+\.[0-9]+/.test(version))
@@ -97,13 +102,87 @@ async function prover(config) {
97
102
  }
98
103
 
99
104
  function validTask(task) {
100
- return task.encoding===encoding&&[32,64].includes(task.machineBits)&&
105
+ return encodings.includes(task.encoding)&&[32,64].includes(task.machineBits)&&
101
106
  ['owner','declaration','programFingerprint','script','taskFingerprint'].every(key=>typeof task[key]==='string')&&
102
107
  /^[0-9a-f]{64}$/.test(task.programFingerprint)&&
103
108
  proofTaskFingerprint(task)===task.taskFingerprint;
104
109
  }
105
110
 
111
+ // Law-set and model tasks need the same process and executable checks as
112
+ // ordinary laws; a protocol token alone is not a completed solver run.
113
+ async function verifiedOutcome(run,selected) {
114
+ if(run.timeout)return 'timeout';
115
+ let unchanged=false;
116
+ try {unchanged=hash(await readFile(selected.binary))===selected.binaryFingerprint;} catch {}
117
+ if(!unchanged||run.outputLimit||run.error||run.exitCode!==0||!run.outcome||run.stdout.includes('(error '))return 'failed';
118
+ return run.outcome;
119
+ }
120
+
121
+ // A task over recursive definitions names its encoding and carries the
122
+ // other one: by unfolding step by step (guarded axioms with fuel, in the
123
+ // IR) and by solver recursion (define-fun-rec). The host tries them in the
124
+ // order the law's harness gives, by default unfolding first. A law may also
125
+ // be proved by induction on an input: each case is its own task, tried in
126
+ // the same encodings, and the law is proved only when every case is. The
127
+ // evidence records which encoding proved the law, and every attempt.
128
+ // Programmers read plain words; the IR keeps the SMT names.
129
+ const recursionName=recursion=>recursion?.encoding==='guarded-axioms'?`unfolding step by step up to ${recursion.fuel} times`:
130
+ recursion?.encoding==='define-fun-rec'?'solver recursion':'';
106
131
  async function solve(task,selected,config) {
132
+ const first=await attempt(task,task.script,task.taskFingerprint,selected,config);
133
+ if(!task.recursion&&!task.induction)return first;
134
+ if(first.status==='unsupported'||(first.status==='incomplete'&&first.outcome==='failed'&&!first.prover))return first;
135
+ const tried=[{recursion:task.recursion,taskFingerprint:task.taskFingerprint,outcome:first.outcome,runFingerprint:first.runFingerprint,elapsedMs:first.elapsedMs}];
136
+ if(first.outcome==='unsat')
137
+ return {...first,recursion:task.recursion,attempts:tried,reason:first.reason+(task.recursion?'; by '+recursionName(task.recursion):'')};
138
+ let best={...first,recursion:task.recursion,attempts:tried};
139
+ const alternative=task.alternative;
140
+ if(alternative&&!selected.error) {
141
+ if(typeof alternative.script!=='string'||proofTaskFingerprint({...task,script:alternative.script})!==alternative.taskFingerprint)
142
+ return {...best,reason:first.reason+'; the alternative encoding\'s binding is invalid'};
143
+ const second=await attempt(task,alternative.script,alternative.taskFingerprint,selected,config);
144
+ tried.push({recursion:alternative.recursion,taskFingerprint:alternative.taskFingerprint,outcome:second.outcome,
145
+ runFingerprint:second.runFingerprint,elapsedMs:second.elapsedMs});
146
+ if(second.outcome==='unsat')
147
+ return {...second,taskFingerprint:alternative.taskFingerprint,recursion:alternative.recursion,attempts:tried,
148
+ reason:second.reason+'; by '+recursionName(alternative.recursion)+' after '+recursionName(task.recursion)+' gave '+first.outcome};
149
+ best={...best,reason:first.reason+'; '+recursionName(alternative.recursion)+' gave '+second.outcome};
150
+ }
151
+ const induction=task.induction;
152
+ if(!induction||selected.error)return best;
153
+ if(induction.status!=='ready')
154
+ return {...best,induction:{on:induction.on,using:induction.using,cases:[]},reason:best.reason+'; induction on '+induction.on+' is unsupported: '+induction.reason};
155
+ const cases=[];
156
+ for(const item of induction.cases) {
157
+ const bound=caseTask=>proofTaskFingerprint({...task,script:caseTask.script})===caseTask.taskFingerprint;
158
+ if(typeof item.script!=='string'||!bound(item)) {
159
+ cases.push({case:item.case,outcome:'failed',reason:'the case\'s binding is invalid'});continue;
160
+ }
161
+ const runs=[{recursion:item.recursion,script:item.script,taskFingerprint:item.taskFingerprint},
162
+ ...(item.alternative&&typeof item.alternative.script==='string'&&bound(item.alternative)?
163
+ [{recursion:item.alternative.recursion,script:item.alternative.script,taskFingerprint:item.alternative.taskFingerprint}]:[])];
164
+ const receipt={case:item.case,attempts:[]};
165
+ for(const run of runs) {
166
+ const done=await attempt(task,run.script,run.taskFingerprint,selected,config,item.inputs);
167
+ receipt.attempts.push({recursion:run.recursion,taskFingerprint:run.taskFingerprint,outcome:done.outcome,
168
+ runFingerprint:done.runFingerprint,elapsedMs:done.elapsedMs});
169
+ Object.assign(receipt,{outcome:done.outcome,recursion:run.recursion,taskFingerprint:run.taskFingerprint,runFingerprint:done.runFingerprint});
170
+ if(done.values&&!receipt.values)receipt.values=done.values;
171
+ if(done.outcome==='unsat')break;
172
+ }
173
+ cases.push(receipt);
174
+ }
175
+ const record={on:induction.on,using:induction.using,asked:induction.asked,cases};
176
+ if(cases.every(c=>c.outcome==='unsat'))
177
+ return {...best,status:'proved',outcome:'unsat',induction:record,model:undefined,modelValidated:undefined,
178
+ reason:'Z3 established this law by induction on '+induction.on+', every case: '+cases.map(c=>c.case+' by '+recursionName(c.recursion)).join(', ')+
179
+ (induction.using.length?'; citing '+induction.using.map(law=>law.split('::law::').pop()).join(', '):'')+
180
+ '; trusts the typed translation and selected solver, without a kernel-checked certificate'};
181
+ const open=cases.filter(c=>c.outcome!=='unsat');
182
+ return {...best,induction:record,reason:best.reason+'; induction on '+induction.on+': '+open.map(c=>'case '+c.case+' gave '+c.outcome).join(', ')};
183
+ }
184
+
185
+ async function attempt(task,script,taskFingerprint,selected,config,names=null) {
107
186
  const common={owner:task.owner,declaration:task.declaration,at:task.at,
108
187
  programFingerprint:task.programFingerprint,taskFingerprint:task.taskFingerprint,
109
188
  encoding:task.encoding,machineBits:task.machineBits,configuration:config};
@@ -113,14 +192,17 @@ async function solve(task,selected,config) {
113
192
  if(selected.error)return {...common,status:'incomplete',outcome:selected.outcome,reason:selected.error};
114
193
  const input=`(set-option :print-success false)\n(set-option :produce-models true)\n`+
115
194
  `(set-option :random-seed ${config.seed})\n(set-option :rlimit ${config.resourceLimit})\n`+
116
- task.script+'(check-sat)\n';
117
- const run=await execute(selected.binary,selected.args,input,config,true);
195
+ script+'(check-sat)\n';
196
+ // An induction case asks for the law's inputs, so its model can be
197
+ // checked as the law's counterexample.
198
+ const run=await execute(selected.binary,selected.args,input,config,true,names?.length?
199
+ token=>token==='sat'?`(get-value (${names.join(' ')}))\n(exit)\n`:followUp(token):followUp);
118
200
  let unchanged=false;
119
201
  try {unchanged=hash(await readFile(selected.binary))===selected.binaryFingerprint;} catch {}
120
202
  const metadata={...common,prover:{name:'z3',version:selected.version,
121
203
  binary:selected.binary,binaryFingerprint:selected.binaryFingerprint,
122
204
  fingerprint:selected.fingerprint,arguments:selected.args},configuration:config,
123
- runFingerprint:fingerprint([task.taskFingerprint,selected.fingerprint,run.input]),
205
+ runFingerprint:fingerprint([taskFingerprint,selected.fingerprint,run.input]),
124
206
  elapsedMs:run.elapsedMs,exitCode:run.exitCode,signal:run.signal,
125
207
  stdout:run.stdout,stderr:run.stderr};
126
208
  let outcome=run.outcome,reason;
@@ -138,31 +220,125 @@ async function solve(task,selected,config) {
138
220
  if(/:reason-unknown\s+"timeout"/.test(run.stdout))outcome='timeout';
139
221
  else if(/:reason-unknown\s+"max\. resource limit exceeded"/.test(run.stdout))outcome='resource-limit';
140
222
  }
223
+ const model=run.outcome==='sat'?run.stdout.slice(run.stdout.indexOf('\n')+1).trim():null;
141
224
  return {...metadata,status:outcome==='unsat'?'proved':'incomplete',outcome,reason,
142
- ...(run.outcome==='sat'?{model:run.stdout.slice(run.stdout.indexOf('\n')+1).trim(),modelValidated:false}:{})};
225
+ ...(model!==null&&!names?.length?{model,modelValidated:false}:{}),...(model!==null&&names?.length?{values:model}:{})};
226
+ }
227
+
228
+ // A satisfiable task's model is not a counterexample. Z3 runs the task's
229
+ // counterexample query (lawspec-smtlib-v2) and gives the values of the law's
230
+ // outer inputs; the compiler, not this host, reads them and re-checks the law
231
+ // at them with its reference evaluator.
232
+ async function counterexampleValues(task,selected,config) {
233
+ const query=task.counterexample;
234
+ if(!query||typeof query.script!=='string'||!Array.isArray(query.inputs))return null;
235
+ if(fingerprint(['lawspec-smtlib-v2',task.programFingerprint,String(task.machineBits),task.owner,task.declaration,
236
+ query.script])!==query.fingerprint)return null;
237
+ const names=query.inputs.map(input=>input.name);
238
+ // A law with no inputs needs no search: the evaluator decides it.
239
+ if(!names.length)return {outcome:'sat',values:'()',fingerprint:query.fingerprint,runFingerprint:null};
240
+ const input=`(set-option :print-success false)\n(set-option :produce-models true)\n`+
241
+ `(set-option :random-seed ${config.seed})\n(set-option :rlimit ${config.resourceLimit})\n`+
242
+ query.script+'(check-sat)\n';
243
+ const run=await execute(selected.binary,selected.args,input,config,true,
244
+ token=>token==='sat'&&names.length?`(get-value (${names.join(' ')}))\n(exit)\n`:'(exit)\n');
245
+ if(run.outcome!=='sat'||run.timeout||run.outputLimit||run.error||run.exitCode!==0)
246
+ return {outcome:run.outcome??'failed',stdout:run.stdout};
247
+ return {outcome:'sat',values:names.length?run.stdout.slice(run.stdout.indexOf('\n')+1).trim():'()',
248
+ fingerprint:query.fingerprint,runFingerprint:fingerprint([query.fingerprint,selected.fingerprint,run.input])};
143
249
  }
144
250
 
145
251
  // Tasks always come freshly from the compiler for the supplied source request.
146
252
  // An imported JSON solver report cannot upgrade a law's evidence through here.
147
253
  export async function proveWithZ3(compiler,request,options={}) {
148
254
  const config=optionsWithDefaults(options);
255
+ // Settlement answers belong to this execution. A caller's imported
256
+ // answers must never upgrade a law before the host invokes its solver.
257
+ request={...request};
258
+ for(const key of ['analysisResults','modelResults','proofCounterexamples'])delete request[key];
149
259
  const result=await compiler.proofTasks(request);
150
260
  if(result.diagnostics?.length)return {...result,solverEvidence:[]};
151
261
  const tasks=result.proofTasks??[];
152
262
  let selected={};
153
- if(tasks.some(task=>task.status==='ready')) {
263
+ const analysis=result.analysisTasks??[];
264
+ const modelTasks=result.modelTasks??[];
265
+ if(tasks.some(task=>task.status==='ready')||analysis.some(row=>row.status==='ready')||modelTasks.some(law=>law.tasks.length)) {
154
266
  try {selected=await prover(config);}
155
267
  catch(error){selected={error:error.message,outcome:error.code==='ENOENT'?'unavailable':error.outcome??'failed'};}
156
268
  }
157
269
  const solverEvidence=[];
158
270
  for(const task of tasks)solverEvidence.push(await solve(task,selected,config));
159
271
  const diagnostics=[...(result.diagnostics??[])];
272
+ // Values to check as each unproved law's counterexample: the
273
+ // counterexample query's (run whenever a law's task was satisfiable, and
274
+ // for every unproved law over recursive definitions, since Z3 unfolds
275
+ // freely there), then each induction case's model.
276
+ const searched=[];
277
+ for(const [index,item] of solverEvidence.entries()) {
278
+ const task=tasks[index];
279
+ if(['proved','unsupported'].includes(item.status)||selected.error)continue;
280
+ if(item.outcome==='sat'||task.recursion) {
281
+ const found=await counterexampleValues(task,selected,config);
282
+ if(found?.outcome==='sat')searched.push({index,found});
283
+ else if(found&&item.outcome==='sat')solverEvidence[index]={...solverEvidence[index],reason:item.reason+'; the counterexample query gave no values ('+found.outcome+')'};
284
+ }
285
+ for(const c of item.induction?.cases??[])
286
+ if(c.outcome==='sat'&&c.values)searched.push({index,found:{outcome:'sat',values:c.values,fingerprint:c.taskFingerprint,runFingerprint:c.runFingerprint},inductionCase:c.case});
287
+ }
288
+ if(searched.length) {
289
+ const checked=await compiler.proofTasks({...request,proofCounterexamples:searched.map(({index,found})=>({
290
+ owner:solverEvidence[index].owner,declaration:solverEvidence[index].declaration,
291
+ taskFingerprint:tasks[index].taskFingerprint,values:found.values}))});
292
+ const checks=checked.counterexampleChecks??[];
293
+ searched.forEach(({index,found,inductionCase},position)=>{
294
+ const item=solverEvidence[index],check=checks[position];
295
+ if(!check||check.owner!==item.owner||check.declaration!==item.declaration||item.status==='refuted')return;
296
+ const counterexample={inputs:check.inputs??[],values:found.values,fingerprint:found.fingerprint,
297
+ runFingerprint:found.runFingerprint,check:check.status};
298
+ if(check.status==='refuted') {
299
+ const shown=(check.inputs??[]).map(input=>input.name+' = '+input.value).join(', ');
300
+ solverEvidence[index]={...item,status:'refuted',modelValidated:true,counterexample,
301
+ reason:(found.runFingerprint?'Z3 found ':'the law has no inputs; ')+(shown?'the input '+shown:'that the law fails')+
302
+ (inductionCase?' in case '+inductionCase+' of the induction':'')+'; the reference evaluator confirms it: '+check.reason};
303
+ } else if(inductionCase&&check.status==='model-not-confirmed') {
304
+ // Why3's SW: the case fails only under its hypothesis, not the law.
305
+ solverEvidence[index]={...item,counterexample,
306
+ reason:item.reason+'; in case '+inductionCase+' the induction hypothesis is too weak: the law holds at Z3\'s input, '+check.reason};
307
+ } else if(check.status==='model-not-confirmed'&&(item.recursion||tasks[index].recursion)) {
308
+ // Unfolding may stop early, so such a model need not be one of the
309
+ // real definitions: incomplete, not a translation error.
310
+ solverEvidence[index]={...item,counterexample,reason:item.reason+'; Z3 gave a model the reference evaluator does not confirm, after unfolding that may have stopped early: '+check.reason};
311
+ } else if(check.status==='model-not-confirmed') {
312
+ solverEvidence[index]={...item,counterexample,reason:'Z3 gave a model the reference evaluator does not confirm: '+check.reason};
313
+ diagnostics.push({code:'proof-translation',message:`Z3's model for ${item.declaration} is not a counterexample: ${check.reason}`,at:item.at});
314
+ } else if(item.outcome==='sat')solverEvidence[index]={...item,counterexample,reason:item.reason+'; '+check.reason};
315
+ });
316
+ }
317
+ // A law proved by induction rests on the laws it cites: while one of them
318
+ // is not proved (or checked on every input), neither is the law.
319
+ const current=new Map();
320
+ for(const row of result.evidence??[])if(row.stage==='law')current.set(row.declaration,row.status);
321
+ for(const item of solverEvidence)if(item.declaration&&!item.kind)current.set(item.declaration,item.status==='proved'?'proved':
322
+ ['proved','exhaustively-checked'].includes(current.get(item.declaration))?current.get(item.declaration):item.status);
323
+ let changed=true;
324
+ while(changed) {
325
+ changed=false;
326
+ solverEvidence.forEach((item,index)=>{
327
+ const cited=item.induction?.using??[];
328
+ if(item.status!=='proved'||!cited.length)return;
329
+ const open=cited.filter(law=>!['proved','exhaustively-checked'].includes(current.get(law)));
330
+ if(!open.length)return;
331
+ solverEvidence[index]={...item,status:'incomplete',reason:item.reason+'; it cites '+
332
+ open.map(law=>law.split('::law::').pop()+', which is '+(current.get(law)??'not proved')).join(', ')};
333
+ current.set(item.declaration,'incomplete');changed=true;
334
+ });
335
+ }
160
336
  const evidence=(result.evidence??[]).map(row=>{
161
337
  const found=solverEvidence.find(item=>item.owner===row.owner&&item.declaration===row.declaration);
162
338
  if(row.stage!=='law'||!found)return row;
163
339
  if(found.status!=='proved') {
164
340
  if(['proved','exhaustively-checked','known-failing','skipped','flaky'].includes(row.status))return row;
165
- return {...row,status:found.status==='unsupported'?'unsupported':'incomplete',reason:found.reason};
341
+ return {...row,status:found.status==='unsupported'?'unsupported':found.status==='refuted'?'refuted':'incomplete',reason:found.reason};
166
342
  }
167
343
  if(row.status==='known-failing') {
168
344
  diagnostics.push({code:'harness',message:`Z3 proved ${row.declaration}; its harness cannot mark it known failing`,at:found.at});
@@ -170,5 +346,93 @@ export async function proveWithZ3(compiler,request,options={}) {
170
346
  }
171
347
  return {...row,status:'proved',reason:found.reason+`; task ${found.taskFingerprint}`};
172
348
  });
173
- return {...result,diagnostics,evidence,solverEvidence};
349
+ // The law-set checks the compiler left undecided (completeness, overlap,
350
+ // conflict, vacuity): Z3 runs each task, and the compiler confirms every
351
+ // model with its reference evaluator before a check is refuted.
352
+ let settled=evidence,found=diagnostics;
353
+ if(analysis.length) {
354
+ const answers=[],ran=new Map();
355
+ for(const row of analysis) {
356
+ if(row.status!=='ready') {
357
+ solverEvidence.push({owner:row.owner,declaration:row.declaration,stage:row.stage,kind:'analysis',
358
+ encoding:'lawspec-smtlib-v2',status:'unsupported',outcome:'unsupported',reason:row.reason,configuration:config});
359
+ continue;
360
+ }
361
+ for(const task of row.tasks) {
362
+ if(selected.error) {ran.set(task.fingerprint,{row,outcome:selected.outcome,error:selected.error});continue;}
363
+ const input=`(set-option :print-success false)\n(set-option :produce-models true)\n`+
364
+ `(set-option :random-seed ${config.seed})\n(set-option :rlimit ${config.resourceLimit})\n`+task.script+'(check-sat)\n';
365
+ const run=await execute(selected.binary,selected.args,input,config,true,
366
+ token=>token==='sat'&&task.inputs.length?`(get-value (${task.inputs.join(' ')}))\n(exit)\n`:'(exit)\n');
367
+ const outcome=await verifiedOutcome(run,selected);
368
+ const values=outcome==='sat'&&task.inputs.length?run.stdout.slice(run.stdout.indexOf('\n')+1).trim():'';
369
+ ran.set(task.fingerprint,{row,outcome,run,runFingerprint:fingerprint([task.fingerprint,selected.fingerprint,run.input])});
370
+ answers.push({fingerprint:task.fingerprint,outcome,values});
371
+ }
372
+ }
373
+ const checked=answers.length?await compiler.proofTasks({...request,analysisResults:answers}):{};
374
+ const rows=new Map((checked.analysisEvidence??[]).map(row=>[row.declaration+'\u0000'+row.stage,row]));
375
+ settled=evidence.map(row=>rows.get(row.declaration+'\u0000'+row.stage)??row);
376
+ found=[...diagnostics,...(checked.diagnostics??[]).filter(row=>row.code==='refuted')];
377
+ for(const verdict of checked.analysisChecks??[]) {
378
+ const done=ran.get(verdict.fingerprint)??{};
379
+ solverEvidence.push({owner:verdict.owner,declaration:verdict.declaration,stage:verdict.stage,kind:'analysis',
380
+ encoding:'lawspec-smtlib-v2',taskFingerprint:verdict.fingerprint,status:verdict.status,
381
+ outcome:done.outcome??'failed',reason:verdict.reason,check:verdict.check,configuration:config,
382
+ ...(done.run?{prover:{name:'z3',version:selected.version,binary:selected.binary,binaryFingerprint:selected.binaryFingerprint,
383
+ fingerprint:selected.fingerprint,arguments:selected.args},runFingerprint:done.runFingerprint,
384
+ elapsedMs:done.run.elapsedMs,exitCode:done.run.exitCode,stdout:done.run.stdout,stderr:done.run.stderr}:{})});
385
+ }
386
+ for(const [fingerprintOf,done] of ran)if(done.error&&!(checked.analysisChecks??[]).some(v=>v.fingerprint===fingerprintOf))
387
+ solverEvidence.push({kind:'analysis',owner:done.row.owner,declaration:done.row.declaration,stage:done.row.stage,
388
+ taskFingerprint:fingerprintOf,encoding:'lawspec-smtlib-v2',status:'incomplete',
389
+ outcome:done.outcome,reason:done.error,configuration:config});
390
+ }
391
+ // Model laws the compiler's own search left open: induction, Spacer (its
392
+ // invariant goes back to the compiler, which asks for plain re-checks),
393
+ // and a bounded run search the compiler replays. Rounds repeat while the
394
+ // compiler asks for new tasks.
395
+ if(modelTasks.length&&selected.error) {
396
+ for(const law of modelTasks)for(const task of law.tasks)
397
+ solverEvidence.push({kind:'model',owner:law.owner,declaration:law.declaration,task:task.kind,
398
+ taskFingerprint:task.fingerprint,encoding:'lawspec-smtlib-v2',status:'incomplete',
399
+ outcome:selected.outcome,reason:selected.error,configuration:config});
400
+ }
401
+ if(modelTasks.length&&!selected.error) {
402
+ const answered=new Map(),modelAnswers=[],modelRows=new Map();
403
+ let pending=modelTasks;
404
+ for(let round=0;round<4;round++) {
405
+ let fresh=0;
406
+ for(const law of pending) for(const task of law.tasks) {
407
+ if(answered.has(task.fingerprint))continue;
408
+ fresh++;
409
+ const input=`(set-option :print-success false)\n(set-option :produce-models true)\n`+
410
+ `(set-option :random-seed ${config.seed})\n(set-option :rlimit ${config.resourceLimit})\n`+task.script+'(check-sat)\n';
411
+ const run=await execute(selected.binary,selected.args,input,config,true,token=>token!=='sat'?'(exit)\n':
412
+ task.kind==='spacer'?'(get-model)\n(exit)\n':task.inputs.length?`(get-value (${task.inputs.join(' ')}))\n(exit)\n`:'(exit)\n');
413
+ const outcome=await verifiedOutcome(run,selected);
414
+ const body=outcome==='sat'?run.stdout.slice(run.stdout.indexOf('\n')+1):'';
415
+ let invariant='';
416
+ if(task.kind==='spacer'&&outcome==='sat') {
417
+ const at=body.indexOf('(define-fun Inv ');
418
+ if(at>=0) {let depth=0;for(let i=at;i<body.length;i++){if(body[i]==='(')depth++;if(body[i]===')'){depth--;if(depth===0){invariant=body.slice(at,i+1);break;}}}}
419
+ }
420
+ const answer={fingerprint:task.fingerprint,outcome,values:task.kind==='spacer'?'':body.trim(),invariant};
421
+ answered.set(task.fingerprint,answer);modelAnswers.push(answer);
422
+ solverEvidence.push({kind:'model',owner:law.owner,declaration:law.declaration,task:task.kind,taskFingerprint:task.fingerprint,
423
+ encoding:'lawspec-smtlib-v2',status:outcome==='unsat'?'proved':'incomplete',outcome,reason:task.kind+': '+outcome,
424
+ prover:{name:'z3',version:selected.version,binary:selected.binary,binaryFingerprint:selected.binaryFingerprint,
425
+ fingerprint:selected.fingerprint,arguments:selected.args},
426
+ runFingerprint:fingerprint([task.fingerprint,selected.fingerprint,run.input]),elapsedMs:run.elapsedMs,
427
+ exitCode:run.exitCode,signal:run.signal,stdout:run.stdout,stderr:run.stderr,configuration:config});
428
+ }
429
+ if(!fresh)break;
430
+ const checked=await compiler.proofTasks({...request,modelResults:modelAnswers});
431
+ for(const row of checked.modelEvidence??[])modelRows.set(row.declaration,row);
432
+ for(const d of checked.diagnostics??[])if(d.code==='refuted'&&!found.some(e=>e.message===d.message))found=[...found,d];
433
+ pending=checked.modelTasks??[];
434
+ }
435
+ settled=settled.map(row=>row.stage==='law'&&modelRows.has(row.declaration)?{...row,...modelRows.get(row.declaration)}:row);
436
+ }
437
+ return {...result,diagnostics:found,evidence:settled,solverEvidence};
174
438
  }
package/templates.mjs CHANGED
@@ -18,8 +18,39 @@ export const targets = [
18
18
  "scala",
19
19
  "groovy",
20
20
  "clojure",
21
- "swift"
21
+ "swift",
22
+ "prolog",
23
+ "hcl",
24
+ "yaml",
25
+ "antlr4",
26
+ "make"
22
27
  ];
28
+ export const programTargets = [
29
+ "java",
30
+ "python",
31
+ "javascript",
32
+ "typescript",
33
+ "go",
34
+ "haskell",
35
+ "kotlin",
36
+ "rust",
37
+ "erlang",
38
+ "elixir",
39
+ "gleam",
40
+ "fsharp",
41
+ "csharp",
42
+ "scala",
43
+ "groovy",
44
+ "clojure",
45
+ "swift",
46
+ "prolog"
47
+ ];
48
+ export const artifactTargets = [
49
+ "hcl",
50
+ "yaml",
51
+ "antlr4",
52
+ "make"
53
+ ];
23
54
  export const targetLabels = [
24
55
  [
25
56
  "java",
@@ -88,6 +119,26 @@ export const targetLabels = [
88
119
  [
89
120
  "swift",
90
121
  "Swift"
122
+ ],
123
+ [
124
+ "prolog",
125
+ "Prolog"
126
+ ],
127
+ [
128
+ "hcl",
129
+ "HCL"
130
+ ],
131
+ [
132
+ "yaml",
133
+ "YAML"
134
+ ],
135
+ [
136
+ "antlr4",
137
+ "ANTLR"
138
+ ],
139
+ [
140
+ "make",
141
+ "Make"
91
142
  ]
92
143
  ];
93
144
 
@@ -108,7 +159,8 @@ export const commands = {
108
159
  "scala": "scala test .",
109
160
  "groovy": "gradle test",
110
161
  "clojure": "clojure -M:test",
111
- "swift": "swift test"
162
+ "swift": "swift test",
163
+ "prolog": "python lawspec_test.py"
112
164
  };
113
165
 
114
166
  export const setup = {
@@ -128,7 +180,12 @@ export const setup = {
128
180
  "scala": "Use JDK 25 and Scala CLI 1.16 (the scala command), with Scala 3.9.0, ScalaCheck 1.20.0 and ScalaTest 3.2.20 (scalatest-funsuite) as test dependencies in project.scala; a program that imports lawspec.crypto or lawspec.network also needs Bouncy Castle bcprov-jdk18on 1.86. Run scala compile --test .",
129
181
  "groovy": "Use JDK 25, Gradle 9.3.0 with the groovy plugin, Groovy 5.0.8 (org.apache.groovy:groovy), Spock 2.5-groovy-5.0, JetCheck 0.3.0 and JUnit Jupiter's API 5.14.0, and useJUnitPlatform(); the Java model compiles jointly with the Groovy sources, so src/main/java and src/test/java are Groovy source directories. A program that imports lawspec.crypto or lawspec.network also needs Bouncy Castle bcprov-jdk18on 1.86. Run gradle testClasses.",
130
182
  "clojure": "Use JDK 25 and the Clojure CLI 1.12 with Clojure 1.12.5 and, for tests, test.check 1.1.3 (the :test alias). The Java model in java/src compiles with the JDK's compiler into target/classes, which lawspec.build does before the tests run (clojure -M:build compiles it alone). A program that imports lawspec.crypto or lawspec.network also needs Bouncy Castle bcprov-jdk18on 1.86. Run clojure -M:test.",
131
- "swift": "Use Swift 6.2 or later (Xcode 26 on macOS 26, where CryptoKit has ML-KEM and ML-DSA) and SwiftPM. The generated runtime and test support are local targets under lawspec/ with no package dependencies; tests run on Swift Testing, from the toolchain, with LawSpec's own property engine. Package.swift declares the targets LawSpecRuntime, LawSpecTesting, App (src) and AppTests (tests), as lawspec init writes it. Run swift build --build-tests."
183
+ "swift": "Use Swift 6.2 or later (Xcode 26 on macOS 26, where CryptoKit has ML-KEM and ML-DSA) and SwiftPM. The generated runtime and test support are local targets under lawspec/ with no package dependencies; tests run on Swift Testing, from the toolchain, with LawSpec's own property engine. Package.swift declares the targets LawSpecRuntime, LawSpecTesting, App (src) and AppTests (tests), as lawspec init writes it. Run swift build --build-tests.",
184
+ "prolog": "Use SWI-Prolog 10.0+ and Python 3.13+ with janus-swi 1.5.3, pytest 8.4.x and Hypothesis 6.x. Install the generated project with python -m pip install -e \".[test]\". Run python lawspec_test.py (PLUnit with the checked Python model), or lawspec test. Set the target python field to the selected interpreter.",
185
+ "hcl": "Generate Terraform variables and checked tfvars using lawspec generate. Run tofu init -backend=false, tofu validate and tofu plan -var-file=configuration.tfvars.json. Artifact generation does not execute application laws.",
186
+ "yaml": "Generate YAML 1.2 configuration and a JSON Schema 2020-12 schema using lawspec generate. Validate edited YAML with a JSON Schema validator. Artifact generation does not execute application laws.",
187
+ "antlr4": "Compile LawSpecData.g4 with ANTLR 4. The grammar checks data syntax; numeric ranges and field predicates require the companion JSON Schema after decoding. Artifact generation does not execute application laws.",
188
+ "make": "Run make to check the project, generate its configured targets and execute its program target tests using the installed lawspec CLI."
132
189
  };
133
190
 
134
191
  // Each target's build files in the readable and the compact (minified) layout.
@@ -304,6 +361,30 @@ const scaffolds = {
304
361
  "compact": {
305
362
  "Package.swift": "// swift-tools-version: 6.2\nimport PackageDescription\nlet package = Package(\n name: \"Example\",\n platforms: [.macOS(.v26)],\n targets: [\n .target(name: \"LawSpecRuntime\", path: \"lawspec/LawSpecRuntime\"),\n .target(name: \"LawSpecTesting\", dependencies: [\"LawSpecRuntime\"], path: \"lawspec/LawSpecTesting\"),\n .target(name: \"App\", dependencies: [\"LawSpecRuntime\"], path: \"src\"),\n .testTarget(name: \"AppTests\", dependencies: [\"App\", \"LawSpecRuntime\", \"LawSpecTesting\"], path: \"tests\"),\n ]\n)\n"
306
363
  }
364
+ },
365
+ "prolog": {
366
+ "readable": {
367
+ "pyproject.toml": "[build-system]\nrequires = [\"setuptools==80.9.0\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[project]\nname = \"lawspec-example\"\nversion = \"0.1.0\"\nrequires-python = \">=3.13\"\ndependencies = [\"janus-swi==1.5.3\"]\n\n[project.optional-dependencies]\ntest = [\"pytest==8.4.2\", \"hypothesis==6.135.26\"]\n\n[tool.setuptools.packages.find]\nwhere = [\"src\"]\n\n[tool.pytest.ini_options]\npythonpath = [\"src\"]\ntestpaths = [\"tests\"]\n"
368
+ },
369
+ "compact": {
370
+ "pyproject.toml": "[build-system]\nrequires = [\"setuptools==80.9.0\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[project]\nname = \"lawspec-example\"\nversion = \"0.1.0\"\nrequires-python = \">=3.13\"\ndependencies = [\"janus-swi==1.5.3\"]\n\n[project.optional-dependencies]\ntest = [\"pytest==8.4.2\", \"hypothesis==6.135.26\"]\n\n[tool.setuptools.packages.find]\nwhere = [\"src\"]\n\n[tool.pytest.ini_options]\npythonpath = [\"src\"]\ntestpaths = [\"tests\"]\n"
371
+ }
372
+ },
373
+ "hcl": {
374
+ "readable": {},
375
+ "compact": {}
376
+ },
377
+ "yaml": {
378
+ "readable": {},
379
+ "compact": {}
380
+ },
381
+ "antlr4": {
382
+ "readable": {},
383
+ "compact": {}
384
+ },
385
+ "make": {
386
+ "readable": {},
387
+ "compact": {}
307
388
  }
308
389
  };
309
390
 
package/test-command.mjs CHANGED
@@ -29,7 +29,22 @@ const digest = (value) => createHash("sha256").update(value).digest("hex");
29
29
  // contribute to the adapter digest; rebuilding the NIF cannot invalidate a pass.
30
30
  const cryptoBuildOutput = (file) => /^priv\/lawspec_crypto_native\.(?:so|dll)(?:\.build|\.\d+\.tmp)?$/.test(file);
31
31
 
32
- // Every file in a project that LawSpec did not generate, by content.
32
+ // An environment attestation records where a run's dependencies were wired
33
+ // and what was observed; it is reporting only, never an input of the
34
+ // project, so one written inside the project is not digested. It is known by
35
+ // its content, whatever its name or whichever tool wrote it.
36
+ // ref:DEC-completed-run-attestation
37
+ export function isAttestation(content) {
38
+ try {
39
+ const value = JSON.parse(content);
40
+ return value !== null && typeof value === "object" && value.format === "environment-attestation";
41
+ } catch {
42
+ return false;
43
+ }
44
+ }
45
+
46
+ // Every file in a project that LawSpec did not generate, by content, except
47
+ // environment attestations.
33
48
  export async function projectDigest(root, generated) {
34
49
  const hash = createHash("sha256");
35
50
  async function walk(folder) {
@@ -40,7 +55,9 @@ export async function projectDigest(root, generated) {
40
55
  if (entry.isDirectory()) {
41
56
  if (!skipped.has(entry.name) && !relative.endsWith("testdata/rapid")) await walk(relative);
42
57
  } else if (entry.isFile() && !generated.has(relative) && !cryptoBuildOutput(relative)) {
43
- hash.update(relative + "\0").update(await readFile(path.join(root, relative))).update("\0");
58
+ const content = await readFile(path.join(root, relative));
59
+ if (relative.endsWith(".json") && isAttestation(content.toString("utf8"))) continue;
60
+ hash.update(relative + "\0").update(content).update("\0");
44
61
  }
45
62
  }
46
63
  }
@@ -121,6 +138,9 @@ export function preparationInvocations(target, files) {
121
138
  export function benchmarkInvocations(target, entries, { offline = false } = {}) {
122
139
  if (!entries.length) return [];
123
140
  const language = target.language;
141
+ if (language === "prolog")
142
+ return [{command: target.python || "python3", args: ["lawspec_test.py",
143
+ ...entries.flatMap(entry => ["--select", `${entry.file}::${entry.name}`])]}];
124
144
  const testDir = target.testDir;
125
145
  const relativeTo = (file, defaultDir) => {
126
146
  const directory = testDir || defaultDir;
@@ -214,6 +234,16 @@ function nativeInvocations(target, entries, { offline = false, scratch = ".", co
214
234
  root = process.cwd(), coverageConfig } = {}) {
215
235
  if (!entries.length) return [];
216
236
  const language = target.language;
237
+ if (language === "prolog") {
238
+ if (coverage) throw new Error("Prolog coverage instrumentation is not integrated");
239
+ const report = path.join(scratch, "prolog.xml");
240
+ const matching = test => entries.filter(entry => entry.kind === "model"
241
+ ? test.name === entry.name : test.name.startsWith(`${entry.name}__`));
242
+ const selections = [...new Set(entries.map(entry => `${entry.file}::${entry.name}`))];
243
+ return [{laws: entries, command: target.python || "python3",
244
+ args: ["lawspec_test.py", ...selections.flatMap(slot => ["--select", slot]), "--junitxml", report],
245
+ report: {kind: "junit", files: [report]}, ran: matching}];
246
+ }
217
247
  const testDir = target.testDir;
218
248
  const relativeTo = (file, defaultDir) => {
219
249
  const directory = testDir || defaultDir;
@@ -587,7 +617,11 @@ export async function executedTests(report, output, root, since) {
587
617
  const values=attributes(element.opening);
588
618
  const native=junitElements(element.xml,["failure","error","skipped"]);
589
619
  const failure=native.filter(element=>element.name!=="skipped");
590
- const status=failure.length?"failed":native.length?"skipped":"passed";
620
+ const incomplete=junitElements(element.xml,["property"]).some(property=>{
621
+ const value=attributes(property.opening);
622
+ return value.name==='lawspec.status'&&value.value==='incomplete';
623
+ });
624
+ const status=incomplete?"incomplete":failure.length?"failed":native.length?"skipped":"passed";
591
625
  const detail=element=>[attributes(element.opening).message,
592
626
  unescapeXml(element.xml.slice(element.opening.length).replace(/<\/(failure|error|skipped)>\s*$/,"")
593
627
  .replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g,(_,text)=>text))].filter(Boolean).join("\n");
@@ -631,6 +665,7 @@ export async function executedTests(report, output, root, since) {
631
665
  // JUnit XML for a runner that writes none, from the tests it printed.
632
666
  export function junitFromTests(tests) {
633
667
  const failures = tests.filter((t) => t.status === "failed").length;
668
+ const errors = tests.filter((t) => t.status === "incomplete").length;
634
669
  const skipped = tests.filter((t) => t.status === "skipped").length;
635
670
  // A BEAM scheduler wraps native functions from several units. Its module
636
671
  // is not the declaring class: retain the unit from the validated identity.
@@ -638,10 +673,11 @@ export function junitFromTests(tests) {
638
673
  const separator = typeof test.identity === "string" ? test.identity.lastIndexOf("::") : -1;
639
674
  return separator > 0 ? test.identity.slice(0, separator) : test.classname ?? "";
640
675
  };
641
- return `<testsuite name="lawspec" tests="${tests.length}" failures="${failures}"${skipped ? ` skipped="${skipped}"` : ""}>\n` +
676
+ return `<testsuite name="lawspec" tests="${tests.length}" failures="${failures}"${errors ? ` errors="${errors}"` : ""}${skipped ? ` skipped="${skipped}"` : ""}>\n` +
642
677
  tests.map((t) => ` <testcase classname="${escapeXml(classname(t))}" name="${escapeXml(t.name)}"` +
643
678
  (Number.isFinite(t.time) ? ` time="${t.time}"` : "") +
644
679
  (t.status === "failed" ? `><failure message="${escapeXml(t.failure ?? "failed")}"/></testcase>` :
680
+ t.status === "incomplete" ? `><properties><property name="lawspec.status" value="incomplete"/></properties><error message="${escapeXml(t.failure ?? t.reason ?? "incomplete execution")}"/></testcase>` :
645
681
  t.status === "skipped" ? `><skipped message="${escapeXml(t.reason ?? "skipped")}"/></testcase>` : "/>")).join("\n") + "\n</testsuite>";
646
682
  }
647
683