@redditech/agent-protocol 0.0.0-stage → 0.2.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.
- package/CHANGELOG.md +89 -0
- package/LICENSE +21 -0
- package/README.md +394 -2
- package/dist/adl.d.ts +141 -0
- package/dist/adl.js +3601 -0
- package/dist/agent-stack-fixtures.d.ts +743 -0
- package/dist/agent-stack-fixtures.js +1554 -0
- package/dist/ai-catalog.d.ts +128 -0
- package/dist/ai-catalog.js +373 -0
- package/dist/attestation-reputation.d.ts +102 -0
- package/dist/attestation-reputation.js +279 -0
- package/dist/audd-rail-config.d.ts +102 -0
- package/dist/audd-rail-config.js +294 -0
- package/dist/browser-wallet-approval.d.ts +293 -0
- package/dist/browser-wallet-approval.js +1201 -0
- package/dist/discovery-source.d.ts +115 -0
- package/dist/discovery-source.js +251 -0
- package/dist/evidence-archive.d.ts +73 -0
- package/dist/evidence-archive.js +238 -0
- package/dist/index.d.ts +23 -0
- package/dist/index.js +23 -0
- package/dist/mpp-tempo-receipt-shapes.d.ts +201 -0
- package/dist/mpp-tempo-receipt-shapes.js +330 -0
- package/dist/okf-adapter.d.ts +229 -0
- package/dist/okf-adapter.js +556 -0
- package/dist/okf-conformance.d.ts +208 -0
- package/dist/okf-conformance.js +651 -0
- package/dist/okf-instruction-safety.d.ts +192 -0
- package/dist/okf-instruction-safety.js +509 -0
- package/dist/onboarding-analyser-handoff.d.ts +391 -0
- package/dist/onboarding-analyser-handoff.js +959 -0
- package/dist/onboarding-state-machine.d.ts +228 -0
- package/dist/onboarding-state-machine.js +432 -0
- package/dist/payment-records.d.ts +181 -0
- package/dist/payment-records.js +599 -0
- package/dist/policy.d.ts +33 -0
- package/dist/policy.js +45 -0
- package/dist/provider-trust.d.ts +113 -0
- package/dist/provider-trust.js +346 -0
- package/dist/quasar-registry-compatibility.d.ts +113 -0
- package/dist/quasar-registry-compatibility.js +214 -0
- package/dist/ranking-explainability.d.ts +202 -0
- package/dist/ranking-explainability.js +302 -0
- package/dist/receipt-v2.d.ts +202 -0
- package/dist/receipt-v2.js +418 -0
- package/dist/repo-explorer-evidence-manifest.d.ts +387 -0
- package/dist/repo-explorer-evidence-manifest.js +1187 -0
- package/dist/source-diagnostics.d.ts +84 -0
- package/dist/source-diagnostics.js +193 -0
- package/dist/source-trust-conformance-matrix.d.ts +207 -0
- package/dist/source-trust-conformance-matrix.js +672 -0
- package/examples/ard-no-spend-ai-catalog.json +51 -0
- package/examples/ard-no-spend-demo.mjs +355 -0
- package/examples/interpretation-guide-scenarios.mjs +302 -0
- package/package.json +144 -4
|
@@ -0,0 +1,651 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* OKF/OpenKB knowledge-bundle conformance diagnostics (#504, epic #468).
|
|
3
|
+
*
|
|
4
|
+
* Deterministic, PURE static-analysis diagnostics that decide whether an
|
|
5
|
+
* OKF-shaped / OpenKB-style knowledge bundle is acceptable as REVIEW/ANALYSIS
|
|
6
|
+
* input for RAP — and nothing more. This module builds directly on the #511
|
|
7
|
+
* adapter spike (`okf-adapter.ts`) and the #503 static fixture corpus
|
|
8
|
+
* (`data/okf-openkb-fixtures/okf-openkb-fixture-corpus.v1.json`): same document
|
|
9
|
+
* roles, trust classifications, and reason-code vocabulary. It does not
|
|
10
|
+
* re-invent either.
|
|
11
|
+
*
|
|
12
|
+
* This module is PURE: no network, no filesystem access, no URL ingestion, no
|
|
13
|
+
* OpenKB install, no LLM/provider call, no MCP/tool call, no script or tool
|
|
14
|
+
* execution, no skill installation, no agent registration, no hosted write,
|
|
15
|
+
* no marketplace publication, no wallet/RPC, no payment activation, no
|
|
16
|
+
* trust/reputation mutation. It only analyses in-memory text the caller
|
|
17
|
+
* already holds. Fail-closed on malformed input and on any request to
|
|
18
|
+
* execute/install/ingest/invoke/generate.
|
|
19
|
+
*
|
|
20
|
+
* ─────────────────────────────────────────────────────────────────────────────
|
|
21
|
+
* REVIEW-ONLY BOUNDARY: a `valid` conformance verdict permits static
|
|
22
|
+
* review/analysis ONLY. It never permits skill installation, agent
|
|
23
|
+
* registration/onboarding, marketplace publication, hosted writes,
|
|
24
|
+
* LLM/provider calls, or execution of any bundle content. Those remain denied
|
|
25
|
+
* regardless of verdict — see `reviewBoundary` on every report.
|
|
26
|
+
* ─────────────────────────────────────────────────────────────────────────────
|
|
27
|
+
*
|
|
28
|
+
* DRAFT/unverified — like the #511 spike, OKF (Open Knowledge Format) is an
|
|
29
|
+
* EXTERNAL format and every OKF-semantic claim below (concept `type`
|
|
30
|
+
* requirement, `index.md`/`log.md` semantics, standard-markdown-link
|
|
31
|
+
* requirement) is illustrative and unconfirmed against the live spec.
|
|
32
|
+
* (DRAFT/unverified — OKF, confirm field semantics before relying on them.)
|
|
33
|
+
*/
|
|
34
|
+
import { adaptOpenKbBundleToOkf, } from './okf-adapter.js';
|
|
35
|
+
export const OKF_CONFORMANCE_SCHEMA_VERSION = 'reddi.okf-conformance.v1';
|
|
36
|
+
/** The OKF semantics this module enforces are unverified against the live external spec. */
|
|
37
|
+
export const OKF_CONFORMANCE_IS_DRAFT = true;
|
|
38
|
+
/** What a passing (or any) conformance report permits — and permanently denies. */
|
|
39
|
+
export const OKF_CONFORMANCE_PERMITTED_USE = [
|
|
40
|
+
'static_review',
|
|
41
|
+
'static_analysis',
|
|
42
|
+
'operator_review_payload',
|
|
43
|
+
'conformance_reporting',
|
|
44
|
+
];
|
|
45
|
+
export const OKF_CONFORMANCE_DENIED_USE = [
|
|
46
|
+
'skill_installation',
|
|
47
|
+
'agent_registration',
|
|
48
|
+
'agent_onboarding',
|
|
49
|
+
'marketplace_publication',
|
|
50
|
+
'hosted_registry_write',
|
|
51
|
+
'llm_or_provider_call',
|
|
52
|
+
'script_or_tool_execution',
|
|
53
|
+
'url_ingestion',
|
|
54
|
+
'payment_activation',
|
|
55
|
+
'trust_or_reputation_mutation',
|
|
56
|
+
];
|
|
57
|
+
/* ────────────────────────────────────────────────────────────────────────────
|
|
58
|
+
* #503 fixture-corpus bridge
|
|
59
|
+
* ──────────────────────────────────────────────────────────────────────────── */
|
|
60
|
+
/**
|
|
61
|
+
* Maps the #503 corpus `expectedDiagnostics[].code` vocabulary onto the
|
|
62
|
+
* conformance code vocabulary (which follows the #511 adapter reason codes).
|
|
63
|
+
*/
|
|
64
|
+
export const OKF_FIXTURE_DIAGNOSTIC_CODE_MAP = {
|
|
65
|
+
unsupported_wikilink_syntax: 'unsupported_link_syntax',
|
|
66
|
+
generated_instruction_untrusted: 'generated_instruction_untrusted',
|
|
67
|
+
generated_skill_untrusted: 'generated_instruction_untrusted',
|
|
68
|
+
script_execution_not_allowed: 'execution_not_allowed',
|
|
69
|
+
};
|
|
70
|
+
/** Maps #503 corpus `expectedDiagnostics[].severity` onto acceptable conformance severities. */
|
|
71
|
+
export const OKF_FIXTURE_DIAGNOSTIC_SEVERITY_MAP = {
|
|
72
|
+
review: ['info', 'warning'],
|
|
73
|
+
blocking: ['blocked'],
|
|
74
|
+
};
|
|
75
|
+
/**
|
|
76
|
+
* Builds a conformance bundle input from one fixture of the #503 corpus
|
|
77
|
+
* (`reddi.okf-openkb-fixture-corpus.v1`). Read-only over the fixture object:
|
|
78
|
+
* file previews are consumed as static text and never mutated, so the
|
|
79
|
+
* fixture's `contentSha256` digests are preserved. Fail-closed: a fixture that
|
|
80
|
+
* does not carry a usable `files` array yields an empty-documents input, which
|
|
81
|
+
* `runOkfConformanceDiagnostics` blocks as `bundle_malformed`.
|
|
82
|
+
*/
|
|
83
|
+
export function conformanceInputFromOkfOpenKbFixture(fixture) {
|
|
84
|
+
if (!isPlainObject(fixture)) {
|
|
85
|
+
return { documents: [] };
|
|
86
|
+
}
|
|
87
|
+
const bundleId = isNonEmptyString(fixture['id']) ? fixture['id'] : undefined;
|
|
88
|
+
const source = isPlainObject(fixture['source']) ? fixture['source'] : {};
|
|
89
|
+
const provenance = {};
|
|
90
|
+
if (isNonEmptyString(source['sourceUrl']))
|
|
91
|
+
provenance.sourceUri = source['sourceUrl'];
|
|
92
|
+
if (isNonEmptyString(source['retrievedAt']))
|
|
93
|
+
provenance.retrievedAt = source['retrievedAt'];
|
|
94
|
+
const files = fixture['files'];
|
|
95
|
+
if (!Array.isArray(files)) {
|
|
96
|
+
return bundleId === undefined ? { documents: [] } : { bundleId, documents: [] };
|
|
97
|
+
}
|
|
98
|
+
const documents = [];
|
|
99
|
+
for (const file of files) {
|
|
100
|
+
if (!isPlainObject(file) || !isNonEmptyString(file['path']))
|
|
101
|
+
continue;
|
|
102
|
+
const doc = {
|
|
103
|
+
path: file['path'].trim(),
|
|
104
|
+
source: typeof file['contentPreview'] === 'string' ? file['contentPreview'] : '',
|
|
105
|
+
};
|
|
106
|
+
if (provenance.sourceUri !== undefined) {
|
|
107
|
+
doc.provenance = { ...provenance };
|
|
108
|
+
}
|
|
109
|
+
documents.push(doc);
|
|
110
|
+
}
|
|
111
|
+
return bundleId === undefined ? { documents } : { bundleId, documents };
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* Deterministically splits raw markdown into YAML frontmatter and body.
|
|
115
|
+
* Conservative YAML subset only: `key: value` scalars, `# comments`, and
|
|
116
|
+
* `key:` followed by indented `- item` list lines. Anything else raises
|
|
117
|
+
* `malformed_frontmatter` and is skipped (fail-closed: unparseable content is
|
|
118
|
+
* never trusted). An unterminated fence is also `malformed_frontmatter`; the
|
|
119
|
+
* whole source is then treated as body with no trusted frontmatter.
|
|
120
|
+
*/
|
|
121
|
+
export function parseOkfDocumentSource(documentId, source) {
|
|
122
|
+
const lines = source.split(/\r?\n/);
|
|
123
|
+
if ((lines[0] ?? '').trim() !== '---') {
|
|
124
|
+
return { frontmatter: undefined, body: source, diagnostics: [] };
|
|
125
|
+
}
|
|
126
|
+
let closing = -1;
|
|
127
|
+
for (let i = 1; i < lines.length; i += 1) {
|
|
128
|
+
if (lines[i].trim() === '---') {
|
|
129
|
+
closing = i;
|
|
130
|
+
break;
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
if (closing === -1) {
|
|
134
|
+
return {
|
|
135
|
+
frontmatter: undefined,
|
|
136
|
+
body: source,
|
|
137
|
+
diagnostics: [
|
|
138
|
+
{
|
|
139
|
+
severity: 'warning',
|
|
140
|
+
code: 'malformed_frontmatter',
|
|
141
|
+
documentId,
|
|
142
|
+
summary: `${documentId} opens a YAML frontmatter fence that never closes; the whole document was treated as body (fail-closed).`,
|
|
143
|
+
action: 'Close the frontmatter fence with a `---` line.',
|
|
144
|
+
},
|
|
145
|
+
],
|
|
146
|
+
};
|
|
147
|
+
}
|
|
148
|
+
const { frontmatter, diagnostics } = parseYamlSubset(lines.slice(1, closing), documentId);
|
|
149
|
+
let bodyStart = closing + 1;
|
|
150
|
+
if (lines[bodyStart] !== undefined && lines[bodyStart].trim() === '')
|
|
151
|
+
bodyStart += 1;
|
|
152
|
+
return { frontmatter, body: lines.slice(bodyStart).join('\n'), diagnostics };
|
|
153
|
+
}
|
|
154
|
+
function parseYamlSubset(lines, documentId) {
|
|
155
|
+
const frontmatter = {};
|
|
156
|
+
const diagnostics = [];
|
|
157
|
+
const keyPattern = /^([A-Za-z0-9_.-]+)\s*:\s*(.*)$/;
|
|
158
|
+
const listItemPattern = /^\s+-\s+(.*)$/;
|
|
159
|
+
let currentListKey = null;
|
|
160
|
+
for (const line of lines) {
|
|
161
|
+
if (line.trim().length === 0)
|
|
162
|
+
continue;
|
|
163
|
+
if (/^\s*#/.test(line))
|
|
164
|
+
continue;
|
|
165
|
+
const listMatch = listItemPattern.exec(line);
|
|
166
|
+
if (listMatch !== null && currentListKey !== null) {
|
|
167
|
+
const existing = frontmatter[currentListKey];
|
|
168
|
+
const list = Array.isArray(existing) ? existing : [];
|
|
169
|
+
list.push(coerceScalar(listMatch[1].trim()));
|
|
170
|
+
frontmatter[currentListKey] = list;
|
|
171
|
+
continue;
|
|
172
|
+
}
|
|
173
|
+
const keyMatch = keyPattern.exec(line);
|
|
174
|
+
if (keyMatch === null) {
|
|
175
|
+
currentListKey = null;
|
|
176
|
+
diagnostics.push({
|
|
177
|
+
severity: 'warning',
|
|
178
|
+
code: 'malformed_frontmatter',
|
|
179
|
+
documentId,
|
|
180
|
+
summary: `${documentId} has an unparseable YAML frontmatter line; it was skipped (fail-closed).`,
|
|
181
|
+
action: 'Use `key: value` scalars or `key:` with indented `- item` list lines.',
|
|
182
|
+
});
|
|
183
|
+
continue;
|
|
184
|
+
}
|
|
185
|
+
const key = keyMatch[1];
|
|
186
|
+
const value = keyMatch[2].trim();
|
|
187
|
+
if (value.length === 0) {
|
|
188
|
+
frontmatter[key] = null;
|
|
189
|
+
currentListKey = key;
|
|
190
|
+
}
|
|
191
|
+
else {
|
|
192
|
+
frontmatter[key] = coerceScalar(value);
|
|
193
|
+
currentListKey = null;
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
return { frontmatter, diagnostics };
|
|
197
|
+
}
|
|
198
|
+
function coerceScalar(value) {
|
|
199
|
+
if (value === 'true')
|
|
200
|
+
return true;
|
|
201
|
+
if (value === 'false')
|
|
202
|
+
return false;
|
|
203
|
+
if (value === 'null')
|
|
204
|
+
return null;
|
|
205
|
+
if (/^-?\d+$/.test(value))
|
|
206
|
+
return Number(value);
|
|
207
|
+
if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
|
|
208
|
+
return value.slice(1, -1);
|
|
209
|
+
}
|
|
210
|
+
return value;
|
|
211
|
+
}
|
|
212
|
+
/* ────────────────────────────────────────────────────────────────────────────
|
|
213
|
+
* Conformance run
|
|
214
|
+
* ──────────────────────────────────────────────────────────────────────────── */
|
|
215
|
+
/**
|
|
216
|
+
* Runs deterministic OKF/OpenKB conformance diagnostics over an in-memory
|
|
217
|
+
* bundle. Pure static analysis: delegates document projection to the #511
|
|
218
|
+
* adapter, then layers the #504 conformance vocabulary (statuses, escalated
|
|
219
|
+
* generated-instruction severities, adaptable-wikilink reporting, index/log
|
|
220
|
+
* expectations, review-only boundary) on top.
|
|
221
|
+
*/
|
|
222
|
+
export function runOkfConformanceDiagnostics(input, options = {}) {
|
|
223
|
+
// Preprocess raw `source` documents into the adapter's input shape, collecting
|
|
224
|
+
// deterministic frontmatter-parse diagnostics per document id.
|
|
225
|
+
const sourceDiagnostics = new Map();
|
|
226
|
+
const adapterInput = preprocessInput(input, sourceDiagnostics);
|
|
227
|
+
const adapterBundle = adaptOpenKbBundleToOkf(adapterInput, {
|
|
228
|
+
requireProvenance: options.requireProvenance,
|
|
229
|
+
execute: options.execute,
|
|
230
|
+
install: options.install,
|
|
231
|
+
ingestUrl: options.ingestUrl,
|
|
232
|
+
invokeLlm: options.invokeLlm,
|
|
233
|
+
generateSkill: options.generateSkill,
|
|
234
|
+
});
|
|
235
|
+
const bundleDiagnostics = [];
|
|
236
|
+
// Bundle-level adapter diagnostics (no documentId): malformed bundle/documents,
|
|
237
|
+
// refused operations. All are blocking for conformance.
|
|
238
|
+
for (const diag of adapterBundle.diagnostics) {
|
|
239
|
+
if (diag.documentId !== undefined)
|
|
240
|
+
continue;
|
|
241
|
+
bundleDiagnostics.push({
|
|
242
|
+
severity: 'blocked',
|
|
243
|
+
code: toConformanceCode(diag),
|
|
244
|
+
summary: diag.summary,
|
|
245
|
+
...(diag.action === undefined ? {} : { action: diag.action }),
|
|
246
|
+
});
|
|
247
|
+
}
|
|
248
|
+
const documents = adapterBundle.documents.map((doc) => buildDocumentReport(doc, sourceDiagnostics.get(doc.id) ?? []));
|
|
249
|
+
// index.md / log.md semantics where applicable.
|
|
250
|
+
bundleDiagnostics.push(...indexLogDiagnostics(adapterBundle, options));
|
|
251
|
+
const allDiagnostics = [
|
|
252
|
+
...bundleDiagnostics,
|
|
253
|
+
...documents.flatMap((doc) => doc.diagnostics),
|
|
254
|
+
];
|
|
255
|
+
const verdict = verdictOf(allDiagnostics, adapterBundle);
|
|
256
|
+
return {
|
|
257
|
+
schemaVersion: OKF_CONFORMANCE_SCHEMA_VERSION,
|
|
258
|
+
draft: true,
|
|
259
|
+
verdict,
|
|
260
|
+
bundleId: adapterBundle.bundleId,
|
|
261
|
+
documents,
|
|
262
|
+
diagnostics: allDiagnostics,
|
|
263
|
+
codes: [...new Set(allDiagnostics.map((diag) => diag.code))],
|
|
264
|
+
index: adapterBundle.index,
|
|
265
|
+
log: adapterBundle.log,
|
|
266
|
+
reviewBoundary: {
|
|
267
|
+
permittedUse: OKF_CONFORMANCE_PERMITTED_USE,
|
|
268
|
+
deniedUse: OKF_CONFORMANCE_DENIED_USE,
|
|
269
|
+
},
|
|
270
|
+
guardrails: {
|
|
271
|
+
network: false,
|
|
272
|
+
fileSystemRead: false,
|
|
273
|
+
executed: false,
|
|
274
|
+
installed: false,
|
|
275
|
+
urlIngested: false,
|
|
276
|
+
llmInvoked: false,
|
|
277
|
+
mcpInvoked: false,
|
|
278
|
+
skillInstalled: false,
|
|
279
|
+
agentRegistered: false,
|
|
280
|
+
hostedWrite: false,
|
|
281
|
+
marketplacePublished: false,
|
|
282
|
+
paymentActivated: false,
|
|
283
|
+
trustMutated: false,
|
|
284
|
+
instructionsTrusted: false,
|
|
285
|
+
},
|
|
286
|
+
notes: [
|
|
287
|
+
'DRAFT/unverified — OKF semantics (concept `type`, index/log, standard-markdown links) are not confirmed against the live external spec.',
|
|
288
|
+
'REVIEW-ONLY: a valid verdict permits static review/analysis only — never skill installation, agent registration, marketplace publication, hosted writes, LLM/provider calls, or execution.',
|
|
289
|
+
'Generated AGENTS.md/SKILL.md/prompts/scripts/skills/tools/agent definitions are untrusted review artifacts regardless of verdict.',
|
|
290
|
+
'Unknown frontmatter fields are preserved verbatim as untrusted review metadata, never policy/runtime configuration.',
|
|
291
|
+
],
|
|
292
|
+
};
|
|
293
|
+
}
|
|
294
|
+
function preprocessInput(input, sourceDiagnostics) {
|
|
295
|
+
if (!isPlainObject(input))
|
|
296
|
+
return input;
|
|
297
|
+
const documents = input.documents;
|
|
298
|
+
if (!Array.isArray(documents))
|
|
299
|
+
return input;
|
|
300
|
+
const adapted = documents.map((doc) => {
|
|
301
|
+
if (!isPlainObject(doc))
|
|
302
|
+
return doc;
|
|
303
|
+
const path = doc['path'];
|
|
304
|
+
const source = doc['source'];
|
|
305
|
+
if (!isNonEmptyString(path) || typeof source !== 'string')
|
|
306
|
+
return doc;
|
|
307
|
+
const documentId = path.trim();
|
|
308
|
+
const parsed = parseOkfDocumentSource(documentId, source);
|
|
309
|
+
if (parsed.diagnostics.length > 0) {
|
|
310
|
+
sourceDiagnostics.set(documentId, [
|
|
311
|
+
...(sourceDiagnostics.get(documentId) ?? []),
|
|
312
|
+
...parsed.diagnostics,
|
|
313
|
+
]);
|
|
314
|
+
}
|
|
315
|
+
const out = { ...doc, path: documentId, body: parsed.body };
|
|
316
|
+
delete out['source'];
|
|
317
|
+
delete out['rawFrontmatter'];
|
|
318
|
+
if (parsed.frontmatter !== undefined) {
|
|
319
|
+
out['frontmatter'] = parsed.frontmatter;
|
|
320
|
+
}
|
|
321
|
+
else {
|
|
322
|
+
delete out['frontmatter'];
|
|
323
|
+
}
|
|
324
|
+
return out;
|
|
325
|
+
});
|
|
326
|
+
const bundleId = input.bundleId;
|
|
327
|
+
return isNonEmptyString(bundleId) ? { bundleId, documents: adapted } : { documents: adapted };
|
|
328
|
+
}
|
|
329
|
+
function buildDocumentReport(doc, parseDiagnostics) {
|
|
330
|
+
const artifactClass = doc.trustClassification === 'untrusted_generated_instruction'
|
|
331
|
+
? classifyGeneratedArtifact(doc)
|
|
332
|
+
: null;
|
|
333
|
+
const diagnostics = [...parseDiagnostics];
|
|
334
|
+
for (const diag of doc.diagnostics) {
|
|
335
|
+
diagnostics.push(mapDocumentDiagnostic(diag, doc, artifactClass));
|
|
336
|
+
}
|
|
337
|
+
// Deterministically-adaptable wikilinks: OKF requires standard markdown links
|
|
338
|
+
// (DRAFT/unverified — OKF, confirm requirement); the #511 adapter already
|
|
339
|
+
// converted these, so they are reported as adaptable info-level findings.
|
|
340
|
+
const wikilinkCount = doc.links.filter((link) => link.origin === 'wikilink').length;
|
|
341
|
+
if (wikilinkCount > 0) {
|
|
342
|
+
diagnostics.push({
|
|
343
|
+
severity: 'info',
|
|
344
|
+
code: 'unsupported_link_syntax',
|
|
345
|
+
documentId: doc.id,
|
|
346
|
+
adaptable: true,
|
|
347
|
+
summary: `${doc.id} used ${wikilinkCount} OpenKB wikilink(s); each was deterministically adapted to a standard markdown link and is reported here.`,
|
|
348
|
+
action: 'Prefer standard markdown links at the source; deterministic adaptation is available via the #511 adapter.',
|
|
349
|
+
});
|
|
350
|
+
}
|
|
351
|
+
return {
|
|
352
|
+
documentId: doc.id,
|
|
353
|
+
documentRole: doc.documentRole,
|
|
354
|
+
trustClassification: doc.trustClassification,
|
|
355
|
+
artifactClass,
|
|
356
|
+
status: statusOf(diagnostics),
|
|
357
|
+
diagnostics,
|
|
358
|
+
};
|
|
359
|
+
}
|
|
360
|
+
function mapDocumentDiagnostic(diag, doc, artifactClass) {
|
|
361
|
+
const base = {
|
|
362
|
+
severity: diag.severity,
|
|
363
|
+
code: toConformanceCode(diag),
|
|
364
|
+
documentId: doc.id,
|
|
365
|
+
summary: diag.summary,
|
|
366
|
+
...(diag.action === undefined ? {} : { action: diag.action }),
|
|
367
|
+
};
|
|
368
|
+
switch (diag.code) {
|
|
369
|
+
case 'generated_instruction_untrusted':
|
|
370
|
+
// Conformance escalates generated-instruction findings to blocked: the
|
|
371
|
+
// artifact is quarantined from any use beyond static review (matches the
|
|
372
|
+
// #503 corpus `blocking` expectation).
|
|
373
|
+
return {
|
|
374
|
+
...base,
|
|
375
|
+
severity: 'blocked',
|
|
376
|
+
...(artifactClass === null ? {} : { artifactClass }),
|
|
377
|
+
};
|
|
378
|
+
case 'execution_not_allowed':
|
|
379
|
+
return {
|
|
380
|
+
...base,
|
|
381
|
+
severity: 'blocked',
|
|
382
|
+
...(artifactClass === null ? {} : { artifactClass }),
|
|
383
|
+
};
|
|
384
|
+
case 'unsupported_link_syntax':
|
|
385
|
+
// Adapter-level link diagnostics are the NON-deterministic cases (embeds,
|
|
386
|
+
// heading/block refs, empty targets) — not adaptable.
|
|
387
|
+
return { ...base, severity: 'warning', adaptable: false };
|
|
388
|
+
default:
|
|
389
|
+
return base;
|
|
390
|
+
}
|
|
391
|
+
}
|
|
392
|
+
function toConformanceCode(diag) {
|
|
393
|
+
switch (diag.code) {
|
|
394
|
+
case 'bundle_malformed':
|
|
395
|
+
return 'bundle_malformed';
|
|
396
|
+
case 'document_malformed':
|
|
397
|
+
return 'document_malformed';
|
|
398
|
+
case 'operation_not_permitted':
|
|
399
|
+
return 'operation_not_permitted';
|
|
400
|
+
case 'unsupported_link_syntax':
|
|
401
|
+
return 'unsupported_link_syntax';
|
|
402
|
+
case 'malformed_frontmatter':
|
|
403
|
+
return 'malformed_frontmatter';
|
|
404
|
+
case 'missing_provenance':
|
|
405
|
+
return 'missing_provenance';
|
|
406
|
+
case 'generated_instruction_untrusted':
|
|
407
|
+
return 'generated_instruction_untrusted';
|
|
408
|
+
case 'execution_not_allowed':
|
|
409
|
+
return 'execution_not_allowed';
|
|
410
|
+
case 'concept_type_missing':
|
|
411
|
+
return 'concept_type_missing';
|
|
412
|
+
case 'unknown_frontmatter_preserved':
|
|
413
|
+
return 'unknown_frontmatter_preserved';
|
|
414
|
+
default:
|
|
415
|
+
// Any future adapter code without a conformance mapping is treated as a
|
|
416
|
+
// malformed-document finding (fail-closed rather than silently dropped).
|
|
417
|
+
return 'document_malformed';
|
|
418
|
+
}
|
|
419
|
+
}
|
|
420
|
+
/** Directory segments / basenames / extensions mirror the #511 adapter's
|
|
421
|
+
* instruction-artifact classification vocabulary. */
|
|
422
|
+
const ARTIFACT_EXECUTABLE_EXTENSIONS = new Set(['sh', 'bash', 'zsh', 'js', 'mjs', 'cjs', 'ts', 'py', 'rb', 'ps1', 'bat', 'cmd']);
|
|
423
|
+
function classifyGeneratedArtifact(doc) {
|
|
424
|
+
const basename = doc.id.split('/').pop()?.toLowerCase() ?? doc.id.toLowerCase();
|
|
425
|
+
if (basename === 'agents.md')
|
|
426
|
+
return 'agent_definition';
|
|
427
|
+
if (basename === 'skill.md' || basename === 'skills.md')
|
|
428
|
+
return 'skill_definition';
|
|
429
|
+
const dirs = doc.id.split('/').slice(0, -1).map((segment) => segment.toLowerCase());
|
|
430
|
+
if (dirs.includes('prompts'))
|
|
431
|
+
return 'prompt';
|
|
432
|
+
if (dirs.includes('scripts'))
|
|
433
|
+
return 'script';
|
|
434
|
+
if (dirs.includes('tools'))
|
|
435
|
+
return 'tool';
|
|
436
|
+
if (dirs.includes('agents'))
|
|
437
|
+
return 'agent_definition';
|
|
438
|
+
if (dirs.includes('skills'))
|
|
439
|
+
return 'skill_definition';
|
|
440
|
+
const fmType = typeof doc.frontmatter['type'] === 'string'
|
|
441
|
+
? doc.frontmatter['type'].toLowerCase()
|
|
442
|
+
: '';
|
|
443
|
+
if (fmType === 'agent')
|
|
444
|
+
return 'agent_definition';
|
|
445
|
+
if (fmType === 'skill')
|
|
446
|
+
return 'skill_definition';
|
|
447
|
+
if (fmType === 'prompt')
|
|
448
|
+
return 'prompt';
|
|
449
|
+
if (fmType === 'tool')
|
|
450
|
+
return 'tool';
|
|
451
|
+
const dot = basename.lastIndexOf('.');
|
|
452
|
+
const extension = dot > 0 && dot < basename.length - 1 ? basename.slice(dot + 1) : '';
|
|
453
|
+
if (ARTIFACT_EXECUTABLE_EXTENSIONS.has(extension))
|
|
454
|
+
return 'script';
|
|
455
|
+
return 'generated_instruction_other';
|
|
456
|
+
}
|
|
457
|
+
function indexLogDiagnostics(bundle, options) {
|
|
458
|
+
const diagnostics = [];
|
|
459
|
+
if (bundle.index !== null) {
|
|
460
|
+
diagnostics.push({
|
|
461
|
+
severity: 'info',
|
|
462
|
+
code: 'index_semantics_normalized',
|
|
463
|
+
documentId: bundle.index.documentId,
|
|
464
|
+
summary: `index.md normalized: ${bundle.index.entries.length} table-of-contents entr(y/ies); not trusted routing/policy.`,
|
|
465
|
+
});
|
|
466
|
+
}
|
|
467
|
+
else if (options.expectIndex === true) {
|
|
468
|
+
diagnostics.push({
|
|
469
|
+
severity: 'warning',
|
|
470
|
+
code: 'index_missing',
|
|
471
|
+
summary: 'Bundle was expected to carry an `index.md` but none was found.',
|
|
472
|
+
action: 'Add an `index.md` table of contents, or drop the expectation for this bundle.',
|
|
473
|
+
});
|
|
474
|
+
}
|
|
475
|
+
if (bundle.log !== null) {
|
|
476
|
+
diagnostics.push({
|
|
477
|
+
severity: 'info',
|
|
478
|
+
code: 'log_semantics_normalized',
|
|
479
|
+
documentId: bundle.log.documentId,
|
|
480
|
+
summary: `log.md normalized: ${bundle.log.entryCount} append-only entr(y/ies); recorded, not trusted as runtime state.`,
|
|
481
|
+
});
|
|
482
|
+
}
|
|
483
|
+
else if (options.expectLog === true) {
|
|
484
|
+
diagnostics.push({
|
|
485
|
+
severity: 'warning',
|
|
486
|
+
code: 'log_missing',
|
|
487
|
+
summary: 'Bundle was expected to carry a `log.md` but none was found.',
|
|
488
|
+
action: 'Add a `log.md` change record, or drop the expectation for this bundle.',
|
|
489
|
+
});
|
|
490
|
+
}
|
|
491
|
+
return diagnostics;
|
|
492
|
+
}
|
|
493
|
+
/** Named-status priority per the #504 acceptance vocabulary. */
|
|
494
|
+
function statusOf(diagnostics) {
|
|
495
|
+
const warningPlus = diagnostics.filter((diag) => diag.severity !== 'info');
|
|
496
|
+
const has = (code) => warningPlus.some((diag) => diag.code === code);
|
|
497
|
+
if (has('execution_not_allowed'))
|
|
498
|
+
return 'execution_not_allowed';
|
|
499
|
+
if (has('generated_instruction_untrusted'))
|
|
500
|
+
return 'untrusted_generated_instruction';
|
|
501
|
+
if (warningPlus.some((diag) => diag.severity === 'blocked'))
|
|
502
|
+
return 'blocked';
|
|
503
|
+
if (has('malformed_frontmatter'))
|
|
504
|
+
return 'malformed_frontmatter';
|
|
505
|
+
if (has('missing_provenance'))
|
|
506
|
+
return 'missing_provenance';
|
|
507
|
+
if (has('unsupported_link_syntax'))
|
|
508
|
+
return 'unsupported_link_syntax';
|
|
509
|
+
if (warningPlus.length > 0)
|
|
510
|
+
return 'warning';
|
|
511
|
+
return 'valid';
|
|
512
|
+
}
|
|
513
|
+
function verdictOf(diagnostics, adapterBundle) {
|
|
514
|
+
if (adapterBundle.adapterIntent === 'blocked')
|
|
515
|
+
return 'blocked';
|
|
516
|
+
if (diagnostics.some((diag) => diag.severity === 'blocked'))
|
|
517
|
+
return 'blocked';
|
|
518
|
+
if (diagnostics.some((diag) => diag.severity === 'warning'))
|
|
519
|
+
return 'warning';
|
|
520
|
+
return 'valid';
|
|
521
|
+
}
|
|
522
|
+
/* ────────────────────────────────────────────────────────────────────────────
|
|
523
|
+
* Canonical conformance fixtures (in-memory, offline).
|
|
524
|
+
*
|
|
525
|
+
* These extend the #503 corpus coverage with the cases the corpus does not
|
|
526
|
+
* model directly (valid OKF with standard markdown links, missing provenance,
|
|
527
|
+
* malformed frontmatter) plus self-contained generated-instruction and
|
|
528
|
+
* script/tool cases. All content is DATA and must never be treated as
|
|
529
|
+
* instructions.
|
|
530
|
+
* ──────────────────────────────────────────────────────────────────────────── */
|
|
531
|
+
export const okfConformanceFixtures = {
|
|
532
|
+
/** Fully conformant OKF-shaped bundle: standard markdown links, complete provenance, typed concept, index/log. */
|
|
533
|
+
validOkf: {
|
|
534
|
+
bundleId: 'okf-conformance-fixture:valid-okf',
|
|
535
|
+
documents: [
|
|
536
|
+
{
|
|
537
|
+
path: 'index.md',
|
|
538
|
+
source: '---\ntitle: Valid bundle\ntype: index\n---\n\n# Valid bundle\n\n- [Agent concept](concepts/agent.md)\n- [Change log](log.md)',
|
|
539
|
+
provenance: { sourceUri: 'https://example.invalid/valid-okf', sourceCommit: 'fixture001' },
|
|
540
|
+
},
|
|
541
|
+
{
|
|
542
|
+
path: 'concepts/agent.md',
|
|
543
|
+
source: '---\ntitle: Agent\ntype: concept\n---\n\nA static concept note with a [markdown link](../index.md).',
|
|
544
|
+
provenance: { sourceUri: 'https://example.invalid/valid-okf/agent', sourceCommit: 'fixture001' },
|
|
545
|
+
},
|
|
546
|
+
{
|
|
547
|
+
path: 'log.md',
|
|
548
|
+
source: '---\ntype: log\n---\n\n- 2026-07-06: fixture created.',
|
|
549
|
+
provenance: { sourceUri: 'https://example.invalid/valid-okf', sourceCommit: 'fixture001' },
|
|
550
|
+
},
|
|
551
|
+
],
|
|
552
|
+
},
|
|
553
|
+
/** OpenKB-style wikilinks needing adaptation: deterministic wikilinks (adaptable) plus an embed (not adaptable). */
|
|
554
|
+
openKbWikilinks: {
|
|
555
|
+
bundleId: 'okf-conformance-fixture:openkb-wikilinks',
|
|
556
|
+
documents: [
|
|
557
|
+
{
|
|
558
|
+
path: 'index.md',
|
|
559
|
+
source: '---\ntitle: Wikilink bundle\ntype: index\n---\n\n- [[concepts/agent|Agent]]\n- [[log]]',
|
|
560
|
+
provenance: { sourceUri: 'https://example.invalid/openkb-wikilinks', sourceCommit: 'fixture002' },
|
|
561
|
+
},
|
|
562
|
+
{
|
|
563
|
+
path: 'concepts/agent.md',
|
|
564
|
+
source: '---\ntitle: Agent\ntype: concept\n---\n\nSee the flow diagram: ![[flow.png]]',
|
|
565
|
+
provenance: { sourceUri: 'https://example.invalid/openkb-wikilinks/agent', sourceCommit: 'fixture002' },
|
|
566
|
+
},
|
|
567
|
+
{
|
|
568
|
+
path: 'log.md',
|
|
569
|
+
source: '---\ntype: log\n---\n\n- 2026-07-06: fixture created.',
|
|
570
|
+
provenance: { sourceUri: 'https://example.invalid/openkb-wikilinks', sourceCommit: 'fixture002' },
|
|
571
|
+
},
|
|
572
|
+
],
|
|
573
|
+
},
|
|
574
|
+
/** Source/provenance completeness: one concept document carries no provenance. */
|
|
575
|
+
missingProvenance: {
|
|
576
|
+
bundleId: 'okf-conformance-fixture:missing-provenance',
|
|
577
|
+
documents: [
|
|
578
|
+
{
|
|
579
|
+
path: 'concepts/orphan.md',
|
|
580
|
+
source: '---\ntitle: Orphan\ntype: concept\n---\n\nNo source provenance was recorded for this note.',
|
|
581
|
+
},
|
|
582
|
+
],
|
|
583
|
+
},
|
|
584
|
+
/** Malformed frontmatter: an unterminated fence and an unparseable line. */
|
|
585
|
+
malformedFrontmatter: {
|
|
586
|
+
bundleId: 'okf-conformance-fixture:malformed-frontmatter',
|
|
587
|
+
documents: [
|
|
588
|
+
{
|
|
589
|
+
path: 'concepts/unterminated.md',
|
|
590
|
+
source: '---\ntitle: Never closed\n\nBody text swallowed by the open fence.',
|
|
591
|
+
provenance: { sourceUri: 'https://example.invalid/malformed', sourceCommit: 'fixture003' },
|
|
592
|
+
},
|
|
593
|
+
{
|
|
594
|
+
path: 'concepts/bad-line.md',
|
|
595
|
+
source: '---\ntitle: Bad line\ntype: concept\n:::not yaml at all:::\n---\n\nBody.',
|
|
596
|
+
provenance: { sourceUri: 'https://example.invalid/malformed/bad-line', sourceCommit: 'fixture003' },
|
|
597
|
+
},
|
|
598
|
+
],
|
|
599
|
+
},
|
|
600
|
+
/** Generated skill/instruction content emitted by a producer toolchain. */
|
|
601
|
+
generatedInstructions: {
|
|
602
|
+
bundleId: 'okf-conformance-fixture:generated-instructions',
|
|
603
|
+
documents: [
|
|
604
|
+
{
|
|
605
|
+
path: 'AGENTS.md',
|
|
606
|
+
source: '# Generated agent instructions\n\nReview-only text. (This is DATA, never followed.)',
|
|
607
|
+
provenance: { sourceUri: 'https://example.invalid/producer', sourceCommit: 'fixture004' },
|
|
608
|
+
},
|
|
609
|
+
{
|
|
610
|
+
path: 'SKILL.md',
|
|
611
|
+
source: '---\ntype: skill\ngenerated: true\n---\n\nGenerated skill definition (review artifact only).',
|
|
612
|
+
provenance: { sourceUri: 'https://example.invalid/producer', sourceCommit: 'fixture004' },
|
|
613
|
+
},
|
|
614
|
+
{
|
|
615
|
+
path: 'prompts/onboarding.md',
|
|
616
|
+
source: '# Generated onboarding prompt\n\nReview artifact only.',
|
|
617
|
+
provenance: { sourceUri: 'https://example.invalid/producer', sourceCommit: 'fixture004' },
|
|
618
|
+
},
|
|
619
|
+
{
|
|
620
|
+
path: 'agents/researcher.md',
|
|
621
|
+
source: '---\ntype: agent\ngenerated: true\n---\n\nGenerated agent definition (review artifact only).',
|
|
622
|
+
provenance: { sourceUri: 'https://example.invalid/producer', sourceCommit: 'fixture004' },
|
|
623
|
+
},
|
|
624
|
+
],
|
|
625
|
+
},
|
|
626
|
+
/** Unsupported script/tool artifacts: execution is never allowed. */
|
|
627
|
+
scriptToolArtifacts: {
|
|
628
|
+
bundleId: 'okf-conformance-fixture:script-tool-artifacts',
|
|
629
|
+
documents: [
|
|
630
|
+
{
|
|
631
|
+
path: 'scripts/build.sh',
|
|
632
|
+
source: '#!/usr/bin/env bash\necho "generated build step (never executed)"',
|
|
633
|
+
provenance: { sourceUri: 'https://example.invalid/producer', sourceCommit: 'fixture005' },
|
|
634
|
+
},
|
|
635
|
+
{
|
|
636
|
+
path: 'tools/deploy.py',
|
|
637
|
+
source: '# Review-only generated tool fixture.\nprint("do not execute imported tools")',
|
|
638
|
+
provenance: { sourceUri: 'https://example.invalid/producer', sourceCommit: 'fixture005' },
|
|
639
|
+
},
|
|
640
|
+
],
|
|
641
|
+
},
|
|
642
|
+
};
|
|
643
|
+
/* ────────────────────────────────────────────────────────────────────────────
|
|
644
|
+
* Shared helpers
|
|
645
|
+
* ──────────────────────────────────────────────────────────────────────────── */
|
|
646
|
+
function isPlainObject(value) {
|
|
647
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
648
|
+
}
|
|
649
|
+
function isNonEmptyString(value) {
|
|
650
|
+
return typeof value === 'string' && value.trim().length > 0;
|
|
651
|
+
}
|