Skip to content

armgit / kiln

Public Imported from GitHub
0

Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.

feat(discovery): return known contracts beside unknown IDs (#218) (#232)

Matthew Kissinger8faa8ade014e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e7e6efea..59e70f94 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -83,6 +83,10 @@ does not publish a package.
note naming the part and count, leaving the authored geometry and unit normals untouched.
A zero-length normal fails naming the part and vertex, with `lathe`, `revolveGeo` or
`creaseNormals` as the remedy.
+- Discovery: when some exact IDs are unknown, the known contracts are returned in request order
+ beside the `UNKNOWN_ID` error, which names only the unknown IDs; no substitution is made and
+ a request with no known ID still returns no entries. `pbrMaterial` now ranks first for
+ roughness-map queries (#218).
## 1.3.1 (2026-10-17)
diff --git a/dist/agent-run.mjs b/dist/agent-run.mjs
index 7f38e767..cded262c 100644
--- a/dist/agent-run.mjs
+++ b/dist/agent-run.mjs
@@ -41988,7 +41988,12 @@ define2("pbrMaterial", {
...materialMetadata,
references: ["src/textures.ts"],
aliases: ["textured PBR", "metallic roughness material"],
- intents: ["bind portable material textures and scalar factors"],
+ intents: [
+ "bind portable material textures and scalar factors",
+ "roughness map",
+ "packed roughness and metalness texture",
+ "apply albedo normal and roughness maps"
+ ],
limitations: ["CPU views do not prove texture/metalness appearance."]
});
define2("foliageMaterial", {
@@ -44561,6 +44566,7 @@ ${JSON.stringify(current)}`
}
if (input.mode === "detail") {
const selected = input.ids.map(select);
+ let unresolved = {};
const unknown = input.ids.filter((_, offset) => !selected[offset]);
if (unknown.length) {
const removed = unknown.flatMap((id) => {
@@ -44572,12 +44578,12 @@ ${JSON.stringify(current)}`
${removed.join(`
`)}`));
const suggestions = (await ranked(unknown[0])).slice(0, 3).map(({ entry }) => entry.id);
- return finish({
- ...error(input.mode, "UNKNOWN_ID", `Unknown exact Discovery IDs: ${unknown.join(", ")}. Use query for suggestions; no substitutions were made.`),
- suggestions
- });
+ const message = `Unknown exact Discovery IDs: ${unknown.join(", ")}. Use query for suggestions; no substitutions were made.`;
+ if (selected.every((entry) => !entry))
+ return finish({ ...error(input.mode, "UNKNOWN_ID", message), suggestions });
+ unresolved = { error: { code: "UNKNOWN_ID", message }, suggestions };
}
- const requested = selected;
+ const requested = selected.filter((entry) => !!entry);
if (new Set(requested.map((entry) => entry.id)).size !== requested.length) {
return error(input.mode, "DUPLICATE_ID", "Each exact selector must identify a different catalog entry. A name or unprefixed slug and its canonical ID refer to the same entry.");
}
@@ -44598,7 +44604,9 @@ ${removed.join(`
total: requested.length,
nextOffset: null,
...omitted.length ? { omittedIds: omitted } : {},
- text: JSON.stringify(details) + (omitted.length ? `
+ ...unresolved,
+ text: (unresolved.error ? `${unresolved.error.message}
+` : "") + JSON.stringify(details) + (omitted.length ? `
Not returned, over the result size: ${omitted.join(", ")}. Fetch them with another kiln_discover ids call.` : "")
});
}
diff --git a/dist/build.json b/dist/build.json
index 371581f8..135ec36e 100644
--- a/dist/build.json
+++ b/dist/build.json
@@ -2,10 +2,10 @@
"schemaVersion": 1,
"entries": {
"worker": {
- "identity": "sha256:87db6a4bebbd23ff45c63007ed94737db002c806798867672bc36a3932d705e5",
+ "identity": "sha256:f1936abb73114537073d9061b79c903987853d21562cbc6cf0496e12ff8acb43",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "933586256ec90971162f278942bc4e5ccb37de7b4eedad01b3631a505d70cf28",
+ "sourceHash": "96210a83ce55f04135f19d0ab051aadbf25f6bac5734cd783ec8e48420fd05b1",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -40,10 +40,10 @@
"bundleHash": "sha256:eb4c421782d3d96e7f4ba04072ecdca10af471d17299bc42a1e0e2fc4c54c421"
},
"agent-run": {
- "identity": "sha256:87db6a4bebbd23ff45c63007ed94737db002c806798867672bc36a3932d705e5",
+ "identity": "sha256:f1936abb73114537073d9061b79c903987853d21562cbc6cf0496e12ff8acb43",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "933586256ec90971162f278942bc4e5ccb37de7b4eedad01b3631a505d70cf28",
+ "sourceHash": "96210a83ce55f04135f19d0ab051aadbf25f6bac5734cd783ec8e48420fd05b1",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -75,13 +75,13 @@
},
"target": "node",
"file": "agent-run.mjs",
- "bundleHash": "sha256:463f1803f3cf6cbe1c33e0eba1651b012dc5b39d7afa762a7ef155780a0b31f4"
+ "bundleHash": "sha256:c12f6fdb2e30e1f8694047341588c3b155ef49986322b71c9df7a9535111ae89"
},
"agent-providers": {
- "identity": "sha256:87db6a4bebbd23ff45c63007ed94737db002c806798867672bc36a3932d705e5",
+ "identity": "sha256:f1936abb73114537073d9061b79c903987853d21562cbc6cf0496e12ff8acb43",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "933586256ec90971162f278942bc4e5ccb37de7b4eedad01b3631a505d70cf28",
+ "sourceHash": "96210a83ce55f04135f19d0ab051aadbf25f6bac5734cd783ec8e48420fd05b1",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -116,10 +116,10 @@
"bundleHash": "sha256:9d6faf03d307321bc2e3bd5ce5bdee0bbbf61e0ebed8bfebfa1fb072287b83fa"
},
"mcp": {
- "identity": "sha256:87db6a4bebbd23ff45c63007ed94737db002c806798867672bc36a3932d705e5",
+ "identity": "sha256:f1936abb73114537073d9061b79c903987853d21562cbc6cf0496e12ff8acb43",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "933586256ec90971162f278942bc4e5ccb37de7b4eedad01b3631a505d70cf28",
+ "sourceHash": "96210a83ce55f04135f19d0ab051aadbf25f6bac5734cd783ec8e48420fd05b1",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -154,10 +154,10 @@
"bundleHash": "sha256:a246b2c79d629a332cef4430dbe742b0c4a0d2f04f0281e673c3c60ff22706da"
},
"cli": {
- "identity": "sha256:87db6a4bebbd23ff45c63007ed94737db002c806798867672bc36a3932d705e5",
+ "identity": "sha256:f1936abb73114537073d9061b79c903987853d21562cbc6cf0496e12ff8acb43",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "933586256ec90971162f278942bc4e5ccb37de7b4eedad01b3631a505d70cf28",
+ "sourceHash": "96210a83ce55f04135f19d0ab051aadbf25f6bac5734cd783ec8e48420fd05b1",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -189,13 +189,13 @@
},
"target": "node",
"file": "cli.mjs",
- "bundleHash": "sha256:75e9b3dae1ad7bfcb0bc9ce07d18d005e6720d0ee2f3fc5bbffe2bb4d364981c"
+ "bundleHash": "sha256:9960552936452073bc433f715c4c032a9777a65aa4e02cb92b6ea5c45e2b62d7"
},
"engine": {
- "identity": "sha256:87db6a4bebbd23ff45c63007ed94737db002c806798867672bc36a3932d705e5",
+ "identity": "sha256:f1936abb73114537073d9061b79c903987853d21562cbc6cf0496e12ff8acb43",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "933586256ec90971162f278942bc4e5ccb37de7b4eedad01b3631a505d70cf28",
+ "sourceHash": "96210a83ce55f04135f19d0ab051aadbf25f6bac5734cd783ec8e48420fd05b1",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -227,7 +227,7 @@
},
"target": "node",
"file": "mcp-engine.mjs",
- "bundleHash": "sha256:00469f2fe9953b0dfb942f62d27cab9a2c0e2a5363456592ba0d1f849fd1214c"
+ "bundleHash": "sha256:d80eb0c40aa1e063377c4d1a8e52753af7fb483cc2f9d09129d04bd6a288a379"
}
}
}
diff --git a/dist/cli.mjs b/dist/cli.mjs
index d2a632f0..d67c74b5 100644
--- a/dist/cli.mjs
+++ b/dist/cli.mjs
@@ -45317,7 +45317,12 @@ var init_helper_contracts = __esm(() => {
...materialMetadata,
references: ["src/textures.ts"],
aliases: ["textured PBR", "metallic roughness material"],
- intents: ["bind portable material textures and scalar factors"],
+ intents: [
+ "bind portable material textures and scalar factors",
+ "roughness map",
+ "packed roughness and metalness texture",
+ "apply albedo normal and roughness maps"
+ ],
limitations: ["CPU views do not prove texture/metalness appearance."]
});
define2("foliageMaterial", {
@@ -47918,6 +47923,7 @@ ${JSON.stringify(current)}`
}
if (input.mode === "detail") {
const selected = input.ids.map(select);
+ let unresolved = {};
const unknown = input.ids.filter((_, offset) => !selected[offset]);
if (unknown.length) {
const removed = unknown.flatMap((id) => {
@@ -47929,12 +47935,12 @@ ${JSON.stringify(current)}`
${removed.join(`
`)}`));
const suggestions = (await ranked(unknown[0])).slice(0, 3).map(({ entry }) => entry.id);
- return finish({
- ...error(input.mode, "UNKNOWN_ID", `Unknown exact Discovery IDs: ${unknown.join(", ")}. Use query for suggestions; no substitutions were made.`),
- suggestions
- });
+ const message = `Unknown exact Discovery IDs: ${unknown.join(", ")}. Use query for suggestions; no substitutions were made.`;
+ if (selected.every((entry) => !entry))
+ return finish({ ...error(input.mode, "UNKNOWN_ID", message), suggestions });
+ unresolved = { error: { code: "UNKNOWN_ID", message }, suggestions };
}
- const requested = selected;
+ const requested = selected.filter((entry) => !!entry);
if (new Set(requested.map((entry) => entry.id)).size !== requested.length) {
return error(input.mode, "DUPLICATE_ID", "Each exact selector must identify a different catalog entry. A name or unprefixed slug and its canonical ID refer to the same entry.");
}
@@ -47955,7 +47961,9 @@ ${removed.join(`
total: requested.length,
nextOffset: null,
...omitted.length ? { omittedIds: omitted } : {},
- text: JSON.stringify(details) + (omitted.length ? `
+ ...unresolved,
+ text: (unresolved.error ? `${unresolved.error.message}
+` : "") + JSON.stringify(details) + (omitted.length ? `
Not returned, over the result size: ${omitted.join(", ")}. Fetch them with another kiln_discover ids call.` : "")
});
}
diff --git a/dist/mcp-engine.mjs b/dist/mcp-engine.mjs
index be34a5c3..053cc5c9 100644
--- a/dist/mcp-engine.mjs
+++ b/dist/mcp-engine.mjs
@@ -46103,7 +46103,12 @@ define2("pbrMaterial", {
...materialMetadata,
references: ["src/textures.ts"],
aliases: ["textured PBR", "metallic roughness material"],
- intents: ["bind portable material textures and scalar factors"],
+ intents: [
+ "bind portable material textures and scalar factors",
+ "roughness map",
+ "packed roughness and metalness texture",
+ "apply albedo normal and roughness maps"
+ ],
limitations: ["CPU views do not prove texture/metalness appearance."]
});
define2("foliageMaterial", {
@@ -48676,6 +48681,7 @@ ${JSON.stringify(current)}`
}
if (input.mode === "detail") {
const selected = input.ids.map(select);
+ let unresolved = {};
const unknown = input.ids.filter((_, offset) => !selected[offset]);
if (unknown.length) {
const removed = unknown.flatMap((id) => {
@@ -48687,12 +48693,12 @@ ${JSON.stringify(current)}`
${removed.join(`
`)}`));
const suggestions = (await ranked(unknown[0])).slice(0, 3).map(({ entry }) => entry.id);
- return finish({
- ...error(input.mode, "UNKNOWN_ID", `Unknown exact Discovery IDs: ${unknown.join(", ")}. Use query for suggestions; no substitutions were made.`),
- suggestions
- });
+ const message = `Unknown exact Discovery IDs: ${unknown.join(", ")}. Use query for suggestions; no substitutions were made.`;
+ if (selected.every((entry) => !entry))
+ return finish({ ...error(input.mode, "UNKNOWN_ID", message), suggestions });
+ unresolved = { error: { code: "UNKNOWN_ID", message }, suggestions };
}
- const requested = selected;
+ const requested = selected.filter((entry) => !!entry);
if (new Set(requested.map((entry) => entry.id)).size !== requested.length) {
return error(input.mode, "DUPLICATE_ID", "Each exact selector must identify a different catalog entry. A name or unprefixed slug and its canonical ID refer to the same entry.");
}
@@ -48713,7 +48719,9 @@ ${removed.join(`
total: requested.length,
nextOffset: null,
...omitted.length ? { omittedIds: omitted } : {},
- text: JSON.stringify(details) + (omitted.length ? `
+ ...unresolved,
+ text: (unresolved.error ? `${unresolved.error.message}
+` : "") + JSON.stringify(details) + (omitted.length ? `
Not returned, over the result size: ${omitted.join(", ")}. Fetch them with another kiln_discover ids call.` : "")
});
}
diff --git a/src/__tests__/cli-discovery.test.ts b/src/__tests__/cli-discovery.test.ts
index f30fb825..1ca03445 100644
--- a/src/__tests__/cli-discovery.test.ts
+++ b/src/__tests__/cli-discovery.test.ts
@@ -91,7 +91,7 @@ test('CLI capabilities report the collections and program store the MCP host inj
}
});
-test('CLI exact details preserve ordering and unknown IDs fail atomically', async () => {
+test('CLI exact details preserve ordering and report unknown IDs beside known ones', async () => {
const detail = await command(['--id', 'copyGeometry', '--id', 'operation:boxGeo', '--json']);
expect(detail.status).toBe(0);
expect(JSON.parse(detail.stdout).entries.map((entry: { name: string }) => entry.name)).toEqual([
@@ -101,6 +101,11 @@ test('CLI exact details preserve ordering and unknown IDs fail atomically', asyn
const unknown = await command(['--id', 'copyGeomtry', '--json']);
expect(unknown.status).toBe(1);
expect(JSON.parse(unknown.stdout).error.code).toBe('UNKNOWN_ID');
+ const partial = await command(['--id', 'boxGeo', '--id', 'copyGeomtry', '--json']);
+ expect(partial.status).toBe(1);
+ const body = JSON.parse(partial.stdout);
+ expect(body.error.code).toBe('UNKNOWN_ID');
+ expect(body.entries.map((entry: { name: string }) => entry.name)).toEqual(['boxGeo']);
});
test('CLI rejects retired or contradictory selectors and exposes bounded human overview', async () => {
diff --git a/src/__tests__/discovery.test.ts b/src/__tests__/discovery.test.ts
index a4c93b08..2b0af52e 100644
--- a/src/__tests__/discovery.test.ts
+++ b/src/__tests__/discovery.test.ts
@@ -99,7 +99,8 @@ describe('progressive capability discovery', () => {
})) as Result;
expect(missing.error?.message).toContain('inventedMesh');
expect(missing.error?.message).toContain('unknownSurface');
- expect(missing.entries).toHaveLength(0);
+ expect(missing.error?.message).not.toContain('boxGeo,');
+ expect(missing.entries.map((entry) => entry.name)).toEqual(['boxGeo']);
await expect(tool.run({ ids: ['boxGeo'], family: 'geometry' })).rejects.toThrow('alone');
await expect(tool.run({ ids: Array(7).fill('boxGeo') })).rejects.toThrow();
});
diff --git a/src/discovery/helper-contracts.ts b/src/discovery/helper-contracts.ts
index fed0b665..978779b5 100644
--- a/src/discovery/helper-contracts.ts
+++ b/src/discovery/helper-contracts.ts
@@ -1782,7 +1782,12 @@ define(
...materialMetadata,
references: ['src/textures.ts'],
aliases: ['textured PBR', 'metallic roughness material'],
- intents: ['bind portable material textures and scalar factors'],
+ intents: [
+ 'bind portable material textures and scalar factors',
+ 'roughness map',
+ 'packed roughness and metalness texture',
+ 'apply albedo normal and roughness maps',
+ ],
limitations: ['CPU views do not prove texture/metalness appearance.'],
},
);
diff --git a/src/discovery/lexical-index.test.ts b/src/discovery/lexical-index.test.ts
index 86875749..1ba82f64 100644
--- a/src/discovery/lexical-index.test.ts
+++ b/src/discovery/lexical-index.test.ts
@@ -119,3 +119,18 @@ test('everyday object words reach the reviewed structure and material entries',
?.expandedTerms ?? [],
).not.toContain('cost');
});
+
+test('Cove authoring words reach welding, crease, packed-roughness and V3 shape contracts', async () => {
+ // Cove quality pass (#218): each of these took several queries.
+ const run = createDiscoveryService(
+ entries,
+ createLexicalDiscoveryIndex(entries),
+ async () => ({}),
+ );
+ const first = async (query: string) => (await run({ query })).entries[0]?.id;
+ expect(await first('weld duplicate vertices')).toBe('operation:mergeVertices');
+ expect(await first('crease normals hard edges')).toBe('operation:creaseNormals');
+ expect(await first('roughness map')).toBe('operation:pbrMaterial');
+ expect(await first('packed roughness metalness texture')).toBe('operation:pbrMaterial');
+ expect(await first('V3 texture ellipse polygon shape')).toBe('operation:proceduralTexture');
+});
diff --git a/src/discovery/service.test.ts b/src/discovery/service.test.ts
index 107046d4..0ff555fc 100644
--- a/src/discovery/service.test.ts
+++ b/src/discovery/service.test.ts
@@ -83,11 +83,18 @@ test('detail resolves exact IDs and names in requested order and returns detache
expect((await run({ ids: ['sweepProfile'] })).entries[0]!.tags).not.toContain('mutation');
});
-test('unknown exact names fail as a whole without silently substituting a related function', async () => {
- const result = await make()({ ids: ['sweepProfile', 'sweepProfle'] });
+test('unknown exact names are reported beside the known entries, never substituted', async () => {
+ const result = await make()({ ids: ['copyGeometry', 'sweepProfle', 'sweepProfile'] });
expect(result.error?.code).toBe('UNKNOWN_ID');
- expect(result.entries).toHaveLength(0);
+ expect(result.error?.message).toContain('sweepProfle');
+ expect(result.error?.message).not.toContain('copyGeometry');
+ expect(result.entries.map((entry) => entry.name)).toEqual(['copyGeometry', 'sweepProfile']);
+ expect(result.total).toBe(2);
expect(result.suggestions?.length).toBeGreaterThan(0);
+ expect(result.text).toStartWith('Unknown exact Discovery IDs: sweepProfle.');
+ const none = await make()({ ids: ['sweepProfle'] });
+ expect(none.error?.code).toBe('UNKNOWN_ID');
+ expect(none.entries).toHaveLength(0);
});
test('ranked search filters then paginates and never exposes numeric confidence', async () => {
diff --git a/src/discovery/service.ts b/src/discovery/service.ts
index 99a00c4f..753fc296 100644
--- a/src/discovery/service.ts
+++ b/src/discovery/service.ts
@@ -169,6 +169,7 @@ export function createDiscoveryService(
}
if (input.mode === 'detail') {
const selected = input.ids.map(select);
+ let unresolved: Pick<DiscoveryResponse, 'error' | 'suggestions'> = {};
const unknown = input.ids.filter((_, offset) => !selected[offset]);
if (unknown.length) {
const removed = unknown.flatMap((id) => {
@@ -184,16 +185,13 @@ export function createDiscoveryService(
),
);
const suggestions = (await ranked(unknown[0]!)).slice(0, 3).map(({ entry }) => entry.id);
- return finish({
- ...error(
- input.mode,
- 'UNKNOWN_ID',
- `Unknown exact Discovery IDs: ${unknown.join(', ')}. Use query for suggestions; no substitutions were made.`,
- ),
- suggestions,
- });
+ const message = `Unknown exact Discovery IDs: ${unknown.join(', ')}. Use query for suggestions; no substitutions were made.`;
+ // One typo must not hide the contracts that did resolve: report it beside them.
+ if (selected.every((entry) => !entry))
+ return finish({ ...error(input.mode, 'UNKNOWN_ID', message), suggestions });
+ unresolved = { error: { code: 'UNKNOWN_ID', message }, suggestions };
}
- const requested = selected as DiscoveryEntry[];
+ const requested = selected.filter((entry): entry is DiscoveryEntry => !!entry);
if (new Set(requested.map((entry) => entry.id)).size !== requested.length) {
return error(
input.mode,
@@ -220,9 +218,11 @@ export function createDiscoveryService(
total: requested.length,
nextOffset: null,
...(omitted.length ? { omittedIds: omitted } : {}),
+ ...unresolved,
// One JSON line: a contract is read whole, and one-line JSON costs
// about a quarter fewer tokens than the indented form.
text:
+ (unresolved.error ? `${unresolved.error.message}\n` : '') +
JSON.stringify(details) +
(omitted.length
? `\nNot returned, over the result size: ${omitted.join(', ')}. Fetch them with another kiln_discover ids call.`