Tutorial

Submit three claims against one box and read a passed, a failed and a refused result.

This tutorial extends the quick start box with two more claims. One fails, because the box is narrower than claimed. One is refused, because the engine cannot decide it on a mesh. Reading all three is most of what using GeoSpec takes.

1. Build and admit the box

Start from the quick start script up to engine.ingestMesh(...). The engine answers the ingestion with the subject it admitted:

{ "requestId": "ingest", "result": { "subject": { "contentHash": "1ffb64d1…", "format": "mesh-buffer-v1" } } }

The content hash is the SHA-256 of the mesh bytes. Every later request names the subject by it.

2. Submit three claims

Replace the processRequest call with one plan that carries three claims. A claim names a capability from the engine's registry, the subject slots it reads, a polarity and a payload:

const claim = (claimId, capability, payload) => ({
  claimId,
  capability,
  subjectSlots: ['part'],
  polarity: 'positive',
  workUnitBudget: 100,
  payload,
});

const response = decode(
  engine.processRequest(
    encode({
      method: 'submitClaims',
      requestId: 'claims',
      ...header,
      plan: {
        subjects: [{ slot: 'part', contentHash }],
        claims: [
          claim('size', 'toHaveBoundingBox', { kind: 'boundingBox', expected: { size: { x: 10, y: 20, z: 30 } } }),
          claim('too-wide', 'toHaveBoundingBox', { kind: 'boundingBox', expected: { size: { x: 12 } } }),
          claim('hole', 'toHaveCircularHole', { kind: 'circularHole', expected: { diameter: 5 } }),
        ],
      },
    }),
  ),
);
engine.close();

for (const result of response.result.results) {
  console.log(result.claimId, result.status, result.diagnostics.map((diagnostic) => diagnostic.code).join(' '));
}

3. Read the results

size passed
too-wide failed GEOSPEC_BOUNDING_BOX_MISMATCH
hole refused GEOSPEC_EVIDENCE_UNSUPPORTED

Passed. The size claim's evidence records what was measured, the tolerance applied (0.02) and the profile used (mesh-bounds-v1).

Failed. The too-wide claim carries one diagnostic. Its message names the axis that missed, and its details list each axis failure with the expected and actual values (abridged):

{
  "code": "GEOSPEC_BOUNDING_BOX_MISMATCH",
  "message": "Bounding box is off the declared bounds on size.x (tolerance 0.02).",
  "details": { "axisFailures": [{ "axis": "x", "field": "size", "expected": 12, "actual": 10 }] },
  "suggestion": "Correct the model dimensions to match the declared bounds; preserve the authored tolerance."
}

Refused. A circular hole needs exact BRep evidence, and a triangle mesh does not carry it. The engine says so instead of guessing:

GEOSPEC_EVIDENCE_UNSUPPORTED: expectGeo(...).toHaveCircularHole() needs exact BRep circular-hole evidence, which this subject does not carry.

A refused claim is not a pass and not a fail. Treat it as a question the spec asked of the wrong geometry: give the engine a STEP subject, or ask a question the mesh can answer. Read a refusal covers the common codes.

4. Run it again

Run the script twice and compare the response bytes: the same mesh bytes, claims and engine version give the same result bytes. Reproduce a result shows how to keep and compare them.

1. Build and admit the box

2. Submit three claims

3. Read the results

4. Run it again

On this page