@coloopx/colocad 0.1.0-alpha.6 → 0.1.0-alpha.7

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 (46) hide show
  1. package/CHANGELOG.md +44 -0
  2. package/README.md +9 -3
  3. package/README.zh-CN.md +8 -3
  4. package/bin/colocad.mjs +17 -9
  5. package/docs/README.md +7 -2
  6. package/docs/README.zh-CN.md +9 -2
  7. package/docs/agent-modeling-handbook.md +1 -1
  8. package/docs/agent-modeling-handbook.zh-CN.md +2 -2
  9. package/docs/api.md +9 -6
  10. package/docs/engineering-queries.md +122 -0
  11. package/docs/engineering-queries.zh-CN.md +74 -0
  12. package/docs/getting-started.md +1 -1
  13. package/docs/integrations/claude-code.md +1 -1
  14. package/docs/integrations/codex.md +1 -1
  15. package/docs/integrations/pi.md +17 -4
  16. package/docs/integrations/verification.md +7 -1
  17. package/examples/integrations/README.md +11 -2
  18. package/examples/integrations/compact-tools.mjs +1 -1
  19. package/kernel/dist/client.d.ts +5 -2
  20. package/kernel/dist/client.js +35 -7
  21. package/kernel/dist/generated.d.ts +297 -4
  22. package/kernel/dist/process.d.ts +1 -1
  23. package/kernel/dist/process.js +3 -3
  24. package/kernel/dist/query-generated.d.ts +181 -0
  25. package/kernel/dist/query-generated.js +1 -0
  26. package/kernel/dist/tools.d.ts +35 -0
  27. package/kernel/dist/tools.js +11 -2
  28. package/kernel/dist/types.d.ts +9 -0
  29. package/kernel/native/darwin-arm64/agent-cad +2 -2
  30. package/kernel/native/darwin-arm64/manifest.json +2 -2
  31. package/kernel/native/linux-arm64/agent-cad +2 -2
  32. package/kernel/native/linux-arm64/manifest.json +2 -2
  33. package/kernel/native/linux-x64/agent-cad +2 -2
  34. package/kernel/native/linux-x64/manifest.json +2 -2
  35. package/kernel/release.json +4 -4
  36. package/kernel/schemas/model.schema.json +1752 -135
  37. package/kernel/schemas/query.schema.json +1150 -0
  38. package/package.json +5 -2
  39. package/skills/colocad/references/tool-contracts.md +14 -2
  40. package/src/build.mjs +3 -2
  41. package/src/index.d.mts +2 -1
  42. package/src/session.d.mts +5 -3
  43. package/src/session.mjs +26 -10
  44. package/viewer/dist/index.js +179 -179
  45. package/viewer/dist/standalone.js +179 -179
  46. package/viewer/index.d.ts +2 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@coloopx/colocad",
3
- "version": "0.1.0-alpha.6",
3
+ "version": "0.1.0-alpha.7",
4
4
  "description": "Parametric feature instructions, a local Rust B-rep kernel and an experimental SolidWorks author",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -66,9 +66,12 @@
66
66
  "examples/integrations/compact-tools.mjs",
67
67
  "examples/integrations/guided-workflow.mjs",
68
68
  "docs/*.md",
69
- "docs/integrations/*.md"
69
+ "docs/integrations/*.md",
70
+ "CHANGELOG.md"
70
71
  ],
71
72
  "scripts": {
73
+ "schema": "node scripts/schema.mjs",
74
+ "schema:check": "node scripts/schema.mjs --check",
72
75
  "test": "node --test test/*.test.mjs",
73
76
  "build:kernel": "node scripts/build-kernel.mjs",
74
77
  "prepack": "node scripts/check-release.mjs",
@@ -4,7 +4,7 @@ The existing harness owns inference, permissions, output locations and artifact
4
4
 
5
5
  ## Expose tools at the useful level
6
6
 
7
- Start with the five tools used by the executable Pi adapter; enable sketch solving or STEP inspection when that workflow needs them. Keep the SDK's schema and `$defs` intact instead of rewriting an approximate subset.
7
+ The executable Pi adapter exposes five core tools and capability-gates `cad_query` as a sixth. Enable sketch solving or STEP inspection when that workflow needs them. Keep the SDK's schema and `$defs` intact instead of rewriting an approximate subset.
8
8
 
9
9
  | Existing tool | Meaning | Important boundary |
10
10
  | --- | --- | --- |
@@ -13,10 +13,11 @@ Start with the five tools used by the executable Pi adapter; enable sketch solvi
13
13
  | `cad_build` | Execute an explicit model and return exact artifacts | Creates a new revision; inspect errors/degradations |
14
14
  | `cad_preview` | Produce a view, reusing eligible saved mesh | Geometry, pose or precision changes can require work |
15
15
  | `cad_edit` | Rebuild changed named parameters | Plain tools take `{model,parameters}`; recorded tools take `{parameters}` |
16
+ | `cad_query` | Observe an accepted exact snapshot: topology, datums, holes/groups/interfaces and explicit part-pair measurements | Requires the latest `query_revision_id`; preserve partial coverage and ambiguity |
16
17
  | `cad_solve_sketch` | Local sketch constraints/residuals/DOF | Local solution/rank is not proof of global uniqueness |
17
18
  | `cad_inspect_step` | Inspect a registered STEP asset and its instances | Import budgets and supported representations apply |
18
19
 
19
- The current API does not provide `image_to_cad`, an automatic drawing-dimension extractor, or a universal exact measurement tool in this tool set. Use the harness's file/image tools for evidence and an appropriate independent geometry verifier for checks. The SDK's `inspect` reads a report; it is not an arbitrary geometric query engine.
20
+ The current API does not provide `image_to_cad`, an automatic drawing-dimension extractor, or universal geometry recognition. Use the harness's file/image tools for evidence and an appropriate independent geometry verifier for checks. The SDK's `inspect` reads a report; `query` is the capability-gated exact-geometry API. It ships in alpha.7; alpha.6 predates it. Inspect installed capabilities before selecting tools.
20
21
 
21
22
  ## Keep feedback focused and inspectable
22
23
 
@@ -31,3 +32,14 @@ For a provider that expects an error flag or thrown error, map `ok:false` into t
31
32
  Use one client/session for sequential revisions of one modeling task. Separate independent tasks' output roots. A session stores accepted inputs and failed attempts; archive its directory before the sandbox expires. `preview` can reuse a checked mesh; observation-only artifacts may point to `source_artifact_directory` for the exact STEP. Avoid overlapping writes to one session.
32
33
 
33
34
  Prefer a small semantic set of SDK tools over an RPC endpoint per primitive. Repeated geometry can be generated in a program/feature graph and sent in a meaningful build. Keep enough milestones to inspect geometry creation, not just the final assembly.
35
+
36
+
37
+ ## Query and repair loop
38
+
39
+ Enable `queryable` when building, or declare persistent datums/interfaces, which require exact snapshots. Keep `query_revision_id` in compact build/edit feedback: the next query needs it. Session-bound `cad_query` uses the latest accepted artifact; after an edit, obtain new refs by rerunning semantic recipes. A failed build/query must not replace accepted source.
40
+
41
+ For installation, select the support plane, then its loops/openings, rather than all circles on the body. A normal test alone can also match a blind-hole bottom: use an earlier named plane with `planar_coplanar_with` when position matters. Symmetric groups do not establish a unique orientation; choose geometry-derived key direction or explicit design intent. A partial result is incomplete evidence, not proof that no hole/collision exists.
42
+
43
+ For clearance, query explicit occurrence pairs in assembly space. Boundary distance is unsigned; inspect the separate relationship/overlap result so a contained part with positive boundary gap cannot pass as clear. Allowed contact has a bounded supported domain, and discrete pose samples do not certify continuous travel. An ineffective required cut returns `NO_MATERIAL_REMOVED`; inspect its placement/axis instead of assuming the machining feature succeeded.
44
+
45
+ On process interruption, reopen the persisted session and resume from its accepted source. Let the SDK invalidate checkpoints whose execution-policy fingerprint differs; do not copy a cache from another build and force its metadata to match.
package/src/build.mjs CHANGED
@@ -15,7 +15,7 @@ import { CadClient } from "../kernel/dist/index.js";
15
15
  export async function build(
16
16
  tree,
17
17
  destination,
18
- { preview = false, binary } = {},
18
+ { preview = false, queryable = false, binary } = {},
19
19
  ) {
20
20
  const plan = compileTree(tree);
21
21
  const model = kernelModel(tree);
@@ -26,7 +26,7 @@ export async function build(
26
26
  let owned = false;
27
27
  try {
28
28
  const client = new CadClient({ outputRoot: stage, binary, wallMs: 120000 });
29
- const result = await client.build(model);
29
+ const result = await client.build(model,{queryable});
30
30
  if (!result.ok)
31
31
  throw Error(result.error.code + ": " + result.error.message);
32
32
  const folder = result.data.artifact_directory;
@@ -59,6 +59,7 @@ export async function build(
59
59
  step: join(out, "part", "model.step"),
60
60
  nativeJob: join(out, "part", "native-job.json"),
61
61
  geometry: receipt.geometry,
62
+ ...(receipt.query_revision_id?{query_revision_id:receipt.query_revision_id}:{}),
62
63
  };
63
64
  } catch (error) {
64
65
  if (owned) await rm(out, { recursive: true, force: true });
package/src/index.d.mts CHANGED
@@ -42,11 +42,12 @@ export function kernelModel(
42
42
  export function build(
43
43
  tree: FeatureTree,
44
44
  destination: string,
45
- options?: { preview?: boolean; binary?: string },
45
+ options?: { preview?: boolean; queryable?: boolean; binary?: string },
46
46
  ): Promise<{
47
47
  directory: string;
48
48
  step: string;
49
49
  nativeJob: string;
50
+ query_revision_id?: string;
50
51
  geometry: Geometry;
51
52
  }>;
52
53
  export function writeSolidWorks(
package/src/session.d.mts CHANGED
@@ -1,13 +1,14 @@
1
- import type { Config, Model, Receipt, PreviewOptions, Sketch } from '../kernel/dist/types.js';
2
- export interface StepMetadata { label?: string; kind?: string; }
1
+ import type { Config, Model, Receipt, PreviewOptions, Sketch, QueryRequest } from '../kernel/dist/types.js';
2
+ export interface StepMetadata { label?: string; kind?: string; queryable?: boolean; }
3
3
  export interface SessionStep {
4
- id: string; label: string; kind: string; operation: 'build'|'edit'|'observe';
4
+ id: string; label: string; kind: string; operation: 'build'|'edit'|'observe'|'query';
5
5
  status: 'running'|'succeeded'|'failed'|'interrupted'; startedAt: string;
6
6
  finishedAt?: string; durationMs?: number; inputFile: string; inputSha256: string;
7
7
  receiptFile?: string; receiptSha256?: string; artifactDirectory?: string;
8
8
  geometry?: Record<string, unknown>; error?: { code: string; message: string };
9
9
  nativeTimingMs?: Record<string, unknown>; degradations?: Record<string, unknown>[];
10
10
  requestedParameters?: Record<string, number>;
11
+ queryable?: boolean; queryRequestFile?: string; queryRequestSha256?: string;
11
12
  }
12
13
  export interface SessionLedger { format: 'colocad/session/1'; id: string; title: string; createdAt: string; steps: SessionStep[]; }
13
14
  export type SessionConfig = Omit<Config, 'outputRoot'>;
@@ -22,6 +23,7 @@ export class ModelingSession {
22
23
  edit(parameters: Record<string, number>, metadata?: StepMetadata): Promise<RecordedReceipt>;
23
24
  preview(model: Model, options?: Partial<PreviewOptions>, metadata?: StepMetadata): Promise<RecordedReceipt>;
24
25
  observe(options?: Partial<PreviewOptions>, metadata?: StepMetadata): Promise<RecordedReceipt>;
26
+ query(request: QueryRequest, metadata?: StepMetadata): Promise<RecordedReceipt>;
25
27
  capabilities(): Promise<Receipt>; schema(): Promise<Receipt>; validate(model: Model): Promise<Receipt>;
26
28
  solveSketch(sketch: Sketch, parameters?: Record<string,number>): Promise<Receipt>;
27
29
  inspectStep(model: Model, asset: string): Promise<Receipt>;
package/src/session.mjs CHANGED
@@ -40,8 +40,8 @@ export class ModelingSession {
40
40
  try{await writeFile(file,json({pid:process.pid}),{flag:'wx'});}catch(e){if(e.code==='EEXIST')throw Error('SESSION_BUSY: another local writer owns this session');throw e;}
41
41
  try{return await fn();}finally{await rm(file,{force:true});}
42
42
  }
43
- async source(){const l=await this.read(),s=l.steps.findLast(x=>x.status==='succeeded'&&x.operation!=='observe');if(!s)throw Error('SESSION_EMPTY: build a model first');return JSON.parse(await checked(this.root,s.inputFile,s.inputSha256));}
44
- async latestGeometry(){return (await this.read()).steps.findLast(x=>x.status==='succeeded'&&x.operation!=='observe');}
43
+ async source(){const l=await this.read(),s=l.steps.findLast(x=>x.status==='succeeded'&&!['observe','query'].includes(x.operation));if(!s)throw Error('SESSION_EMPTY: build a model first');return JSON.parse(await checked(this.root,s.inputFile,s.inputSha256));}
44
+ async latestGeometry(){return (await this.read()).steps.findLast(x=>x.status==='succeeded'&&!['observe','query'].includes(x.operation));}
45
45
  async build(model,metadata={}){const input=structuredClone(model);return this.lock(()=>this.run(input,'build',metadata));}
46
46
  async edit(parameters,metadata={}){return this.lock(async()=>{
47
47
  const model=await this.source();
@@ -56,20 +56,28 @@ export class ModelingSession {
56
56
  }return this.run(next,'build',metadata);
57
57
  });}
58
58
  async observe(options={},metadata={}){return this.lock(async()=>{const model=await this.source();model.preview={...model.preview,...options};return this.run(model,'observe',metadata);});}
59
- async run(model,operation,{label=operation,kind=operation==='observe'?'inspection':'geometry'}={},preset,requestedParameters){
59
+ async query(request,metadata={}){const input=structuredClone(request);return this.lock(async()=>this.run(await this.source(),'query',metadata,undefined,undefined,input));}
60
+ async run(model,operation,{label=operation,kind=['observe','query'].includes(operation)?'inspection':'geometry',queryable}={},preset,requestedParameters,queryRequest){
60
61
  const ledger=await this.read(),id='s'+String(ledger.steps.length+1).padStart(4,'0'),dir=join('steps',id);
61
62
  await mkdir(join(this.root,dir),{recursive:true});
62
- if(operation!=='observe')model.preview={view:'iso',chord_mm:.6,width:960,height:640,...model.preview};
63
+ if(!['observe','query'].includes(operation))model.preview={view:'iso',chord_mm:.6,width:960,height:640,...model.preview};
63
64
  const bytes=json(model);await writeFile(join(this.root,dir,'input.json'),bytes);
64
65
  const step={id,label:String(label),kind:String(kind),operation,status:'running',startedAt:new Date().toISOString(),inputFile:dir+'/input.json',inputSha256:sha(bytes),receiptFile:dir+'/receipt.json'};
65
66
  if(requestedParameters)step.requestedParameters=requestedParameters;
67
+ if(queryRequest){const requestBytes=json(queryRequest);step.queryRequestFile=dir+'/query.json';step.queryRequestSha256=sha(requestBytes);await writeFile(join(this.root,step.queryRequestFile),requestBytes);}
66
68
  ledger.steps.push(step);await atomic(join(this.root,'session.json'),ledger);
67
69
  const start=performance.now();let result;
68
70
  try{
69
- const previous=ledger.steps.slice(0,-1).findLast(x=>x.status==='succeeded'&&x.operation!=='observe');
70
- result=preset??await (operation==='observe'
71
+ const previous=ledger.steps.slice(0,-1).findLast(x=>x.status==='succeeded'&&!['observe','query'].includes(x.operation));
72
+ step.queryable=queryable??((model.datums?.length||model.interfaces?.length)?true:previous?.queryable??false);
73
+ const accepted=operation==='query'?JSON.parse(await checked(this.root,previous.receiptFile,previous.receiptSha256)):undefined;
74
+ if(accepted&&queryRequest.query_revision_id!==accepted.data.query_revision_id)preset={ok:false,error:{code:'QUERY_REVISION_MISMATCH',message:'Query must target the accepted geometry revision'}};
75
+ result=preset??await (operation==='query'
76
+ ?this.cad.query(inside(this.root,previous.artifactDirectory),queryRequest)
77
+ :operation==='observe'
71
78
  ?this.cad.observeArtifact(inside(this.root,previous.artifactDirectory),model.preview)
72
- :this.cad.build(model,previous?inside(this.root,previous.artifactDirectory):undefined));
79
+ :this.cad.build(model,{previousRevision:previous?inside(this.root,previous.artifactDirectory):undefined,queryable:step.queryable}));
80
+ if(operation==='query'&&result.ok){result.data.artifact_directory=inside(this.root,previous.artifactDirectory);result.data.source_artifact_directory=result.data.artifact_directory;result.data.source_artifact_sha256=accepted.data.artifact_sha256;}
73
81
  }catch(e){result={ok:false,error:{code:'SESSION_EXECUTION_FAILED',message:String(e.message)}};}
74
82
  step.durationMs=performance.now()-start;step.finishedAt=new Date().toISOString();step.status=result.ok?'succeeded':'failed';
75
83
  const saved=structuredClone(result);
@@ -91,7 +99,12 @@ export class ModelingSession {
91
99
  export async function createSessionTools(session) {
92
100
  const tools=await createCadTools(session.cad);
93
101
  for(const tool of tools){
94
- if(tool.name==='cad_build')tool.execute=({model})=>session.build(model,{label:'Agent build'});
102
+ if(tool.name==='cad_build')tool.execute=({model,options})=>session.build(model,{label:'Agent build',queryable:options?.queryable});
103
+ if(tool.name==='cad_query'){
104
+ delete tool.inputSchema.properties.artifact_directory;tool.inputSchema.required=['request'];
105
+ tool.description='Query the latest accepted exact snapshot, persist request/result, and reject stale revisions without changing accepted source.';
106
+ tool.execute=({request})=>session.query(request,{label:'Agent geometry query'});
107
+ }
95
108
  if(tool.name==='cad_preview')tool.execute=({model,options})=>session.preview(model,options,{label:'Agent preview'});
96
109
  if(tool.name==='cad_edit'){
97
110
  delete tool.inputSchema.properties.model;
@@ -107,16 +120,19 @@ export async function readSessionBundle(directory,{cutaway=false,view='iso'}={})
107
120
  const root=resolve(directory),ledger=await load(join(root,'session.json'));
108
121
  if(ledger.format!==format)throw Error('SESSION_FORMAT');
109
122
  const bundle={format:'colocad/viewer/1',title:ledger.title,id:ledger.id,createdAt:ledger.createdAt,display:{cutaway,view},steps:[],meshes:{}};
110
- const last=ledger.steps.findLast(x=>x.status==='succeeded'&&x.operation!=='observe');
123
+ const last=ledger.steps.findLast(x=>x.status==='succeeded'&&!['observe','query'].includes(x.operation));
111
124
  for(const entry of ledger.steps){
112
125
  const step={...entry};
113
126
  if(entry.inputFile)step.model=JSON.parse(await checked(root,entry.inputFile,entry.inputSha256));
114
127
  if(entry.receiptFile&&entry.receiptSha256)step.receipt=JSON.parse(await checked(root,entry.receiptFile,entry.receiptSha256));
128
+ if(entry.queryRequestFile)step.queryRequest=JSON.parse(await checked(root,entry.queryRequestFile,entry.queryRequestSha256));
115
129
  if(entry.status==='succeeded'){
116
130
  const data=step.receipt.data,artifact=entry.artifactDirectory;inside(root,artifact);
117
131
  // Observation results keep their original exact-geometry source for later lookup.
118
132
  const source=data.source_artifact_directory??artifact;
119
- const sourceReport=source===artifact?data:await load(inside(root,source+'/report.json'));
133
+ const sourceReport=entry.operation==='query'?{artifact_sha256:data.source_artifact_sha256}:source===artifact?data:await load(inside(root,source+'/report.json'));
134
+ const guideHash=sourceReport.artifact_sha256?.['query-display.json'];
135
+ if(guideHash)step.queryDisplay=JSON.parse(await checked(root,source+'/query-display.json',guideHash));
120
136
  const hash=sourceReport.artifact_sha256?.['preview.mesh.json'];
121
137
  if(!hash)throw Error('SESSION_INTEGRITY: missing native preview mesh hash');
122
138
  const scene=JSON.parse(await checked(root,source+'/preview.mesh.json',hash));