From 3bd6d9cbcda938d5b0a5b439ecbb59eba62d5afb Mon Sep 17 00:00:00 2001 From: Branimir Rakic Date: Fri, 10 Apr 2026 09:31:58 +0200 Subject: [PATCH 1/3] fix: address remaining PR #104 review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix query error→400 mapping: substring checks now match the actual error messages from the query engine ('agentAddress is required', 'requires a contextGraphId') so invalid view-based requests return 400 instead of falling through as 500s - Add Vary header (Host, X-Forwarded-Host, X-Forwarded-Proto) to the skill endpoint so proxies don't serve cached responses with wrong Base URL to different callers - Remove hardcoded 'text/markdown' from extraction pipelines list; only report what's actually registered in the ExtractionPipelineRegistry - Document subGraphName restriction in SKILL.md query section (cannot be combined with view-based routing) - Replace references to non-existent workflow/api-reference files with inline Common Workflows section showing actual usage patterns Made-with: Cursor --- packages/cli/skills/dkg-node/SKILL.md | 20 +++++++++++++------- packages/cli/src/daemon.ts | 7 ++++--- packages/cli/test/skill-endpoint.test.ts | 2 +- 3 files changed, 18 insertions(+), 11 deletions(-) diff --git a/packages/cli/skills/dkg-node/SKILL.md b/packages/cli/skills/dkg-node/SKILL.md index 61cd09814..b02414cad 100644 --- a/packages/cli/skills/dkg-node/SKILL.md +++ b/packages/cli/skills/dkg-node/SKILL.md @@ -111,7 +111,8 @@ The token is configured in the node's config file or provided at startup. ### Querying -- `POST /api/query` — SPARQL query with optional `view` (`working-memory`, `shared-working-memory`, `verified-memory`), `agentAddress`, `assertionName`, `verifiedGraph`, `subGraphName`, `includeSharedMemory`, `contextGraphId` parameters +- `POST /api/query` — SPARQL query with optional `contextGraphId`, `includeSharedMemory`, `view` (`working-memory`, `shared-working-memory`, `verified-memory`), `agentAddress`, `assertionName`, `verifiedGraph` parameters + - **Note:** `subGraphName` is supported for legacy routing only and cannot be combined with `view` - `POST /api/query-remote` — query a remote peer via P2P ### Working Memory (WM) — Private assertions (🚧 Planned) @@ -179,14 +180,19 @@ curl -X POST $BASE_URL/api/assertion/my-assertion/import-file \ | 502 | Chain/upstream error | Retry — transient blockchain issue | | 503 | Service unavailable | Node is starting up or shutting down | -## 10. Workflow Recipes +## 10. Common Workflows -For detailed step-by-step workflow recipes and the full endpoint reference, see -the supporting files in the skill directory: +**Write → Share → Publish:** -- `workflows.md` — 10 workflow recipes with curl examples -- `api-reference.md` — full endpoint reference grouped by workflow -- `examples/sparql-recipes.md` — SPARQL query patterns +1. Create a context graph (`POST /api/context-graph/create`) +2. Write triples to shared memory (`POST /api/shared-memory/write`) +3. Publish to verified memory (`POST /api/publish`) + +**Query across layers:** + +- Shared memory: `{"sparql": "...", "contextGraphId": "...", "includeSharedMemory": true}` +- Verified memory: `{"sparql": "...", "contextGraphId": "..."}` +- Working memory (planned): `{"sparql": "...", "view": "working-memory", "agentAddress": "..."}` ## Appendix: V9 → V10 Migration diff --git a/packages/cli/src/daemon.ts b/packages/cli/src/daemon.ts index 713cc7801..14b43dea3 100644 --- a/packages/cli/src/daemon.ts +++ b/packages/cli/src/daemon.ts @@ -107,7 +107,7 @@ function buildSkillMd(opts: { `- **Base URL:** ${opts.baseUrl}`, `- **Peer ID:** ${opts.peerId}`, `- **Node role:** ${opts.nodeRole}`, - `- **Available extraction pipelines:** ${opts.extractionPipelines.length > 0 ? opts.extractionPipelines.join(', ') : 'text/markdown'}`, + `- **Available extraction pipelines:** ${opts.extractionPipelines.length > 0 ? opts.extractionPipelines.join(', ') : 'none (install markitdown to enable document conversion)'}`, `- **Subscribed Context Graphs:** use \`GET /api/context-graph/list\` (requires auth)`, ].join('\n'); @@ -1227,7 +1227,7 @@ async function handleRequest( const proto = req.headers['x-forwarded-proto'] ?? 'http'; const host = req.headers['x-forwarded-host'] ?? req.headers.host ?? `localhost:${config.listenPort ?? 9200}`; const baseUrl = `${proto}://${host}`; - const pipelines = ['text/markdown', ...extractionRegistry.availableContentTypes()]; + const pipelines = extractionRegistry.availableContentTypes(); const content = buildSkillMd({ version: nodeVersion, baseUrl, @@ -1244,6 +1244,7 @@ async function handleRequest( 'Content-Type': 'text/markdown; charset=utf-8', 'ETag': etag, 'Cache-Control': 'public, max-age=300', + 'Vary': 'Host, X-Forwarded-Host, X-Forwarded-Proto', }); res.end(content); return; @@ -2116,7 +2117,7 @@ async function handleRequest( msg.startsWith('SPARQL rejected:') || msg.startsWith('Parse error') || /must start with (SELECT|CONSTRUCT|ASK|DESCRIBE)/i.test(msg) || msg.includes('was removed in V10') || - msg.includes('requires agentAddress') || msg.includes('requires contextGraphId') || + msg.includes('agentAddress is required') || msg.includes('requires a contextGraphId') || msg.includes('cannot be combined with') ) { return jsonResponse(res, 400, { error: msg }); diff --git a/packages/cli/test/skill-endpoint.test.ts b/packages/cli/test/skill-endpoint.test.ts index 21c20bfaa..f775abc5f 100644 --- a/packages/cli/test/skill-endpoint.test.ts +++ b/packages/cli/test/skill-endpoint.test.ts @@ -70,7 +70,7 @@ describe('SKILL.md file', () => { expect(skillContent).toContain('## 7. File Ingestion'); expect(skillContent).toContain('## 8. Node Administration'); expect(skillContent).toContain('## 9. Error Reference'); - expect(skillContent).toContain('## 10. Workflow Recipes'); + expect(skillContent).toContain('## 10. Common Workflows'); }); it('contains dynamic placeholders for node info', () => { From 2f09d310354186c6734aa2969366b91d7c564744 Mon Sep 17 00:00:00 2001 From: Branimir Rakic Date: Fri, 10 Apr 2026 10:35:49 +0200 Subject: [PATCH 2/3] fix(skill): correct workflow and query examples in SKILL.md - Quick Start step 3 now uses POST /api/shared-memory/publish (promotes SWM data written in step 2) instead of POST /api/publish (which expects its own quad payload) - Query examples now use the view parameter for layer routing: view: "shared-memory", view: "verified-memory", view: "working-memory" - Working memory query example includes required contextGraphId Made-with: Cursor --- packages/cli/skills/dkg-node/SKILL.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/packages/cli/skills/dkg-node/SKILL.md b/packages/cli/skills/dkg-node/SKILL.md index b02414cad..c8f141b45 100644 --- a/packages/cli/skills/dkg-node/SKILL.md +++ b/packages/cli/skills/dkg-node/SKILL.md @@ -69,10 +69,10 @@ curl -X POST $BASE_URL/api/shared-memory/write \ **Step 3 — Publish to Verified Memory:** ```bash -curl -X POST $BASE_URL/api/publish \ +curl -X POST $BASE_URL/api/shared-memory/publish \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ - -d '{"contextGraphId": "my-context-graph", "quads": [...]}' + -d '{"contextGraphId": "my-context-graph"}' ``` **Step 4 — Query:** @@ -81,7 +81,7 @@ curl -X POST $BASE_URL/api/publish \ curl -X POST $BASE_URL/api/query \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ - -d '{"sparql": "SELECT * WHERE { ?s ?p ?o } LIMIT 10", "contextGraphId": "my-context-graph", "includeSharedMemory": true}' + -d '{"sparql": "SELECT * WHERE { ?s ?p ?o } LIMIT 10", "contextGraphId": "my-context-graph", "view": "shared-memory"}' ``` ## 4. Authentication @@ -186,13 +186,13 @@ curl -X POST $BASE_URL/api/assertion/my-assertion/import-file \ 1. Create a context graph (`POST /api/context-graph/create`) 2. Write triples to shared memory (`POST /api/shared-memory/write`) -3. Publish to verified memory (`POST /api/publish`) +3. Publish to verified memory (`POST /api/shared-memory/publish`) **Query across layers:** -- Shared memory: `{"sparql": "...", "contextGraphId": "...", "includeSharedMemory": true}` -- Verified memory: `{"sparql": "...", "contextGraphId": "..."}` -- Working memory (planned): `{"sparql": "...", "view": "working-memory", "agentAddress": "..."}` +- Shared memory: `{"sparql": "...", "contextGraphId": "...", "view": "shared-memory"}` +- Verified memory: `{"sparql": "...", "contextGraphId": "...", "view": "verified-memory"}` +- Working memory (planned): `{"sparql": "...", "view": "working-memory", "agentAddress": "...", "contextGraphId": "..."}` ## Appendix: V9 → V10 Migration From ef5c1a55610b56c27f7d8665e9b38f1af524e06f Mon Sep 17 00:00:00 2001 From: Branimir Rakic Date: Fri, 10 Apr 2026 10:42:57 +0200 Subject: [PATCH 3/3] fix(skill): use correct view enum values in query examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit shared-memory → shared-working-memory (matches GET_VIEWS in core) Made-with: Cursor --- packages/cli/skills/dkg-node/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/cli/skills/dkg-node/SKILL.md b/packages/cli/skills/dkg-node/SKILL.md index c8f141b45..fa416fcab 100644 --- a/packages/cli/skills/dkg-node/SKILL.md +++ b/packages/cli/skills/dkg-node/SKILL.md @@ -81,7 +81,7 @@ curl -X POST $BASE_URL/api/shared-memory/publish \ curl -X POST $BASE_URL/api/query \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ - -d '{"sparql": "SELECT * WHERE { ?s ?p ?o } LIMIT 10", "contextGraphId": "my-context-graph", "view": "shared-memory"}' + -d '{"sparql": "SELECT * WHERE { ?s ?p ?o } LIMIT 10", "contextGraphId": "my-context-graph", "view": "shared-working-memory"}' ``` ## 4. Authentication @@ -190,7 +190,7 @@ curl -X POST $BASE_URL/api/assertion/my-assertion/import-file \ **Query across layers:** -- Shared memory: `{"sparql": "...", "contextGraphId": "...", "view": "shared-memory"}` +- Shared memory: `{"sparql": "...", "contextGraphId": "...", "view": "shared-working-memory"}` - Verified memory: `{"sparql": "...", "contextGraphId": "...", "view": "verified-memory"}` - Working memory (planned): `{"sparql": "...", "view": "working-memory", "agentAddress": "...", "contextGraphId": "..."}`