@origintrail-official/dkg-okf 10.0.2

package/dist/mapping.js

@@ -0,0 +1,253 @@
+/**
+ * Deterministic OKF concept → RDF mapping (no LLM, no network).
+ *
+ * One OKF concept document maps to one Knowledge Asset subject IRI plus a set
+ * of content + linkage quads. The mapping reuses the node Markdown extractor's
+ * predicate vocabulary (so an OKF import and a native Markdown import converge),
+ * with the OKF-specific deltas recorded in `docs/adr/0005-okf-rdf-mapping.md`:
+ *
+ *   - body links are real Markdown links `[text](path)` (OKF §5), NOT the
+ *     extractor's `[[wikilinks]]`, so we resolve them with a real Markdown AST
+ *     (`mdast-util-from-markdown`) — which is also what lets us honour the
+ *     CommonMark rule that a link inside an inline code span is literal text;
+ *   - OKF concept titles live in frontmatter, so body headings (including `#`
+ *     H1s like `# Schema`) are genuine sections → `dkg:hasSection`;
+ *   - `timestamp` is OKF's last-modified time → `schema:dateModified`.
+ */
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { toString as mdToString } from 'mdast-util-to-string';
+import { RDF_TYPE, SCHEMA_NS, SCHEMA_NAME, SCHEMA_DESCRIPTION, SCHEMA_KEYWORDS, SCHEMA_MENTIONS, SCHEMA_DATE_MODIFIED, SCHEMA_URL, SCHEMA_CITATION, SCHEMA_IS_PART_OF, DKG_HAS_SECTION, SECTION_GENID_INFIX, XSD_DATE_TIME, XSD_BOOLEAN, XSD_INTEGER, XSD_DECIMAL, DEFAULT_IRI_BASE, } from './constants.js';
+import { conceptIdToIri, resolveLinkTarget } from './paths.js';
+import { isSafeIri, literalTerm, typedLiteralTerm, pascalCase, camelCase, sanitizeForBlank, } from './utils.js';
+const BARE_URL_RE = /https?:\/\/[^\s)<>"]+/g;
+const INLINE_LINK_RE = /\[[^\]]*\]\(([^)\s]+)\)/g;
+/** OKF `type` value → an rdf:type object IRI (raw, no angle brackets). */
+function typeToIri(value) {
+    const s = String(value).trim();
+    if (!s)
+        return null;
+    if (isSafeIri(s))
+        return s; // already a full IRI (e.g. `tag:…`, `https://…`)
+    const pascal = pascalCase(s);
+    return pascal ? SCHEMA_NS + pascal : null;
+}
+function toArray(value) {
+    return Array.isArray(value) ? value : [value];
+}
+function dateToLexical(value) {
+    return value instanceof Date ? value.toISOString() : String(value);
+}
+/** Producer-defined scalar/array values → object terms (typed where possible). */
+function valueToTerms(value) {
+    if (value === null || value === undefined)
+        return [];
+    if (Array.isArray(value))
+        return value.flatMap(valueToTerms);
+    if (value instanceof Date)
+        return [typedLiteralTerm(value.toISOString(), XSD_DATE_TIME)];
+    if (typeof value === 'boolean')
+        return [typedLiteralTerm(String(value), XSD_BOOLEAN)];
+    if (typeof value === 'number') {
+        return [typedLiteralTerm(String(value), Number.isInteger(value) ? XSD_INTEGER : XSD_DECIMAL)];
+    }
+    if (typeof value === 'string') {
+        return [isSafeIri(value) ? value : literalTerm(value)];
+    }
+    return [literalTerm(JSON.stringify(value))];
+}
+/** Map the YAML frontmatter to quads (SPEC §4.1; see the locked table in ADR 0005). */
+export function frontmatterQuads(iri, frontmatter) {
+    const out = [];
+    for (const [key, value] of Object.entries(frontmatter)) {
+        if (value === null || value === undefined)
+            continue;
+        switch (key) {
+            case 'type': {
+                const t = typeToIri(value);
+                if (t)
+                    out.push({ subject: iri, predicate: RDF_TYPE, object: t });
+                break;
+            }
+            case 'title':
+                out.push({ subject: iri, predicate: SCHEMA_NAME, object: literalTerm(String(value)) });
+                break;
+            case 'description':
+                out.push({
+                    subject: iri,
+                    predicate: SCHEMA_DESCRIPTION,
+                    object: literalTerm(String(value)),
+                });
+                break;
+            case 'tags':
+                for (const tag of toArray(value)) {
+                    out.push({ subject: iri, predicate: SCHEMA_KEYWORDS, object: literalTerm(String(tag)) });
+                }
+                break;
+            case 'timestamp':
+                out.push({
+                    subject: iri,
+                    predicate: SCHEMA_DATE_MODIFIED,
+                    object: typedLiteralTerm(dateToLexical(value), XSD_DATE_TIME),
+                });
+                break;
+            case 'resource': {
+                const r = String(value);
+                out.push({
+                    subject: iri,
+                    predicate: SCHEMA_URL,
+                    object: isSafeIri(r) ? r : literalTerm(r),
+                });
+                break;
+            }
+            default: {
+                // Producer-defined keys — preserved, never dropped (SPEC §4.1/§9).
+                const predicate = SCHEMA_NS + camelCase(key);
+                for (const term of valueToTerms(value)) {
+                    out.push({ subject: iri, predicate, object: term });
+                }
+            }
+        }
+    }
+    return out;
+}
+function collect(node, links, codes, texts) {
+    if (node.type === 'link')
+        links.push(node);
+    else if (node.type === 'inlineCode')
+        codes.push(node);
+    else if (node.type === 'text')
+        texts.push(node.value);
+    if ('children' in node && Array.isArray(node.children)) {
+        for (const child of node.children)
+            collect(child, links, codes, texts);
+    }
+}
+function extractInlineLinkHrefs(code) {
+    const out = [];
+    for (const m of code.matchAll(INLINE_LINK_RE))
+        out.push(m[1]);
+    return out;
+}
+/** Parse a concept body with a real Markdown AST. */
+export function parseBody(body) {
+    const tree = fromMarkdown(body);
+    const headings = [];
+    const bodyLinks = [];
+    const codeSpanHrefs = [];
+    const citations = [];
+    let currentSection = '';
+    for (const node of tree.children) {
+        if (node.type === 'heading') {
+            const text = mdToString(node);
+            headings.push(text);
+            currentSection = text.trim().toLowerCase();
+            continue;
+        }
+        const inCitations = currentSection === 'citations';
+        const links = [];
+        const codes = [];
+        const texts = [];
+        collect(node, links, codes, texts);
+        if (inCitations) {
+            for (const l of links) {
+                const label = mdToString(l).trim();
+                citations.push(label ? { url: l.url, label } : { url: l.url });
+            }
+            for (const t of texts) {
+                for (const m of t.matchAll(BARE_URL_RE))
+                    citations.push({ url: m[0] });
+            }
+        }
+        else {
+            for (const l of links)
+                bodyLinks.push(l.url);
+            for (const c of codes)
+                codeSpanHrefs.push(...extractInlineLinkHrefs(c.value));
+        }
+    }
+    return { headings, bodyLinks, codeSpanHrefs, citations };
+}
+/**
+ * Map a single concept to its Knowledge Asset quads + structured link/citation
+ * diagnostics. `conceptExists` decides whether a resolved link target is in the
+ * bundle (a candidate that is not present is a broken link — warned, never fatal).
+ */
+export function mapConcept(doc, iri, conceptExists, opts = {}) {
+    const iriBase = opts.iriBase ?? DEFAULT_IRI_BASE;
+    const quads = [...frontmatterQuads(iri, doc.frontmatter)];
+    const parsed = parseBody(doc.body);
+    // Sections: every body heading (OKF titles live in frontmatter, so H1s count).
+    // Section nodes are skolemized into deterministic concept-scoped IRIs rather
+    // than emitted as RDF blank nodes: the daemon rejects blank-node *objects*
+    // ("RDF object must be a quoted literal term or absolute IRI"), so a blank
+    // `hasSection` object fails the first write on a strict node. The IRI uses the
+    // node's own `.well-known/genid/` scheme, so the stored graph is identical.
+    parsed.headings.forEach((text, i) => {
+        const sectionIri = `${iri}${SECTION_GENID_INFIX}okfsec_${sanitizeForBlank(doc.conceptId)}_${i}`;
+        quads.push({ subject: iri, predicate: DKG_HAS_SECTION, object: sectionIri });
+        quads.push({ subject: sectionIri, predicate: SCHEMA_NAME, object: literalTerm(text) });
+    });
+    const resolvedLinks = [];
+    const brokenLinks = [];
+    const codeSpanLinks = [];
+    const edgeTargets = new Set();
+    const addEdge = (target) => {
+        if (edgeTargets.has(target))
+            return;
+        edgeTargets.add(target);
+        quads.push({
+            subject: iri,
+            predicate: SCHEMA_MENTIONS,
+            object: conceptIdToIri(target, iriBase),
+        });
+    };
+    for (const href of parsed.bodyLinks) {
+        const candidate = resolveLinkTarget(href, doc.conceptId);
+        if (candidate && conceptExists(candidate)) {
+            resolvedLinks.push({ raw: href, targetConceptId: candidate, inCodeSpan: false });
+            addEdge(candidate);
+        }
+        else if (candidate) {
+            // Resolved to a bundle path that doesn't exist → broken (SPEC §5.3/§9).
+            brokenLinks.push({ raw: href, targetConceptId: null, inCodeSpan: false });
+        }
+        // candidate === null → external URL / anchor / escapes root: not a concept edge.
+    }
+    for (const href of parsed.codeSpanHrefs) {
+        const candidate = resolveLinkTarget(href, doc.conceptId);
+        const present = !!candidate && conceptExists(candidate);
+        const link = {
+            raw: href,
+            targetConceptId: present ? candidate : null,
+            inCodeSpan: true,
+        };
+        codeSpanLinks.push(link);
+        if (opts.includeCodeSpanLinks && present && candidate) {
+            resolvedLinks.push(link);
+            addEdge(candidate);
+        }
+    }
+    const citations = [];
+    const seenCitation = new Set();
+    for (const c of parsed.citations) {
+        if (seenCitation.has(c.url))
+            continue;
+        seenCitation.add(c.url);
+        citations.push(c);
+        quads.push({
+            subject: iri,
+            predicate: SCHEMA_CITATION,
+            object: isSafeIri(c.url) ? c.url : literalTerm(c.url),
+        });
+    }
+    if (opts.emitFolderHierarchy && doc.segments.length > 1) {
+        const parentId = doc.segments.slice(0, -1).join('/');
+        quads.push({
+            subject: iri,
+            predicate: SCHEMA_IS_PART_OF,
+            object: conceptIdToIri(parentId, iriBase),
+        });
+    }
+    return { conceptId: doc.conceptId, iri, quads, resolvedLinks, brokenLinks, codeSpanLinks, citations };
+}
+//# sourceMappingURL=mapping.js.map

package/dist/mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapping.js","sourceRoot":"","sources":["../src/mapping.ts"],"names":[],"mappings":"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"}

package/dist/nquads.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Deterministic N-Quads serialization for golden tests and `export`.
+ *
+ * Quad object terms already use the node's quad encoding (raw IRIs without
+ * angle brackets, literals as `"…"` / `"…"^^<dt>`, blanks as `_:…`). This
+ * renders them as canonical N-Quads: IRIs wrapped in `<…>`, literals/blanks
+ * passed through, then deduplicated and lexically sorted so the same graph
+ * always serialises to byte-identical output.
+ */
+import type { Quad } from './types.js';
+/** Render quads to canonical (deduped + sorted) N-Quads. */
+export declare function quadsToNQuads(quads: Quad[]): string;
+//# sourceMappingURL=nquads.d.ts.map

package/dist/nquads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nquads.d.ts","sourceRoot":"","sources":["../src/nquads.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAQvC,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,CAOnD"}

package/dist/nquads.js

@@ -0,0 +1,26 @@
+/**
+ * Deterministic N-Quads serialization for golden tests and `export`.
+ *
+ * Quad object terms already use the node's quad encoding (raw IRIs without
+ * angle brackets, literals as `"…"` / `"…"^^<dt>`, blanks as `_:…`). This
+ * renders them as canonical N-Quads: IRIs wrapped in `<…>`, literals/blanks
+ * passed through, then deduplicated and lexically sorted so the same graph
+ * always serialises to byte-identical output.
+ */
+function termToNQuads(term) {
+    if (term.startsWith('_:'))
+        return term; // blank node
+    if (term.startsWith('"'))
+        return term; // literal (possibly `"…"^^<dt>` / `"…"@lang`)
+    return `<${term}>`; // IRI
+}
+/** Render quads to canonical (deduped + sorted) N-Quads. */
+export function quadsToNQuads(quads) {
+    const lines = quads.map((q) => {
+        const graph = q.graph ? ` ${termToNQuads(q.graph)}` : '';
+        return `${termToNQuads(q.subject)} <${q.predicate}> ${termToNQuads(q.object)}${graph} .`;
+    });
+    const unique = [...new Set(lines)].sort();
+    return unique.length > 0 ? unique.join('\n') + '\n' : '';
+}
+//# sourceMappingURL=nquads.js.map

package/dist/nquads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nquads.js","sourceRoot":"","sources":["../src/nquads.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,SAAS,YAAY,CAAC,IAAY;IAChC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,aAAa;IACrD,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,8CAA8C;IACrF,OAAO,IAAI,IAAI,GAAG,CAAC,CAAC,MAAM;AAC5B,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC5B,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzD,OAAO,GAAG,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,SAAS,KAAK,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,KAAK,IAAI,CAAC;IAC3F,CAAC,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1C,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;AAC3D,CAAC"}

package/dist/paths.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Concept-ID ↔ path resolution and OKF cross-link resolution.
+ *
+ * The segment-validation regex is kept byte-for-byte in agreement with the
+ * OKF reference agent's `okf/src/reference_agent/bundle/paths.py`:
+ *
+ *   _SEGMENT_RE = re.compile(r"[A-Za-z0-9_][A-Za-z0-9_.\-]*")
+ *
+ * matched with `fullmatch`. A path segment must start with an alphanumeric or
+ * underscore, then may contain alphanumerics, underscore, dot or hyphen.
+ */
+/** Reserved filenames that are NOT concepts (SPEC §3.1, §6, §7). */
+export declare const RESERVED_FILENAMES: Set<string>;
+export declare function isValidSegment(segment: string): boolean;
+/** POSIX basename of a bundle-relative path. */
+export declare function basename(path: string): string;
+/** True for reserved `index.md` / `log.md` at any depth (SPEC §3.1). */
+export declare function isReservedFile(path: string): boolean;
+/** True for a non-reserved `.md` file (i.e. a concept document, SPEC §4). */
+export declare function isConceptFile(path: string): boolean;
+/**
+ * Bundle-relative path → concept ID (path with `.md` removed, SPEC §2).
+ * `tables/blocks.md` → `tables/blocks`.
+ */
+export declare function pathToConceptId(path: string): string;
+/** Concept ID → deterministic subject IRI. Same bundle ⇒ same IRI. */
+export declare function conceptIdToIri(conceptId: string, iriBase?: string): string;
+/**
+ * Node-side Knowledge Asset / assertion name for a concept.
+ *
+ * DKG asset/assertion names cannot contain `/`, but OKF concept IDs are
+ * path-based (`tables/blocks`). The encoding must be **injective** — a naive
+ * `/`→`__` collapses `a/b` and the literal concept `a__b` onto the same name.
+ * So escape the escape character first (`_`→`_5f`), then `/`→`_2f` (the chars'
+ * hex codes). `a/b`→`a_2fb`, `a__b`→`a_5f_5fb` — distinct. The RDF subject IRI
+ * is unaffected; it keeps the original `/`-bearing concept ID.
+ */
+export declare function conceptIdToKaName(conceptId: string): string;
+/**
+ * Resolve a Markdown link `href` written inside the concept `fromConceptId`
+ * into a candidate target concept ID, per SPEC §5. Handles:
+ *   - absolute (bundle-relative): `/tables/customers.md`
+ *   - relative: `./other.md`, `../tables/x.md`
+ *   - bare-sibling: `x.md`
+ *   - extension-less variants: `x`, `../tables/x`
+ *   - `#anchor` / `?query` suffixes are stripped first
+ *
+ * Returns `null` for: external URLs (scheme-prefixed), pure anchors, paths that
+ * escape the bundle root, directory links, or any candidate whose segments fail
+ * the `paths.py` validation regex (so it could not be a concept ID anyway).
+ *
+ * Note: this returns a *candidate* — whether the target actually exists in the
+ * bundle is decided by the caller against the Pass-1 concept map. A candidate
+ * that does not exist is a broken link, which is NOT an error (SPEC §5.3/§9).
+ */
+export declare function resolveLinkTarget(href: string, fromConceptId: string): string | null;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,oEAAoE;AACpE,eAAO,MAAM,kBAAkB,aAAkC,CAAC;AAQlE,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,gDAAgD;AAChD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7C;AAED,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIpD;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,MAAyB,GAAG,MAAM,CAE5F;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA0CpF"}

package/dist/paths.js

@@ -0,0 +1,126 @@
+/**
+ * Concept-ID ↔ path resolution and OKF cross-link resolution.
+ *
+ * The segment-validation regex is kept byte-for-byte in agreement with the
+ * OKF reference agent's `okf/src/reference_agent/bundle/paths.py`:
+ *
+ *   _SEGMENT_RE = re.compile(r"[A-Za-z0-9_][A-Za-z0-9_.\-]*")
+ *
+ * matched with `fullmatch`. A path segment must start with an alphanumeric or
+ * underscore, then may contain alphanumerics, underscore, dot or hyphen.
+ */
+import { DEFAULT_IRI_BASE } from './constants.js';
+/** Reserved filenames that are NOT concepts (SPEC §3.1, §6, §7). */
+export const RESERVED_FILENAMES = new Set(['index.md', 'log.md']);
+/** Mirrors `paths.py` `_SEGMENT_RE` used with `fullmatch`. */
+const SEGMENT_RE = /^[A-Za-z0-9_][A-Za-z0-9_.\-]*$/;
+/** A scheme-prefixed URL (http:, https:, mailto:, urn:, …) — never a concept link. */
+const SCHEME_RE = /^[A-Za-z][A-Za-z0-9+.-]*:/;
+export function isValidSegment(segment) {
+    return SEGMENT_RE.test(segment);
+}
+/** POSIX basename of a bundle-relative path. */
+export function basename(path) {
+    const parts = path.split('/');
+    return parts[parts.length - 1] ?? '';
+}
+/** True for reserved `index.md` / `log.md` at any depth (SPEC §3.1). */
+export function isReservedFile(path) {
+    return RESERVED_FILENAMES.has(basename(path));
+}
+/** True for a non-reserved `.md` file (i.e. a concept document, SPEC §4). */
+export function isConceptFile(path) {
+    return path.endsWith('.md') && !isReservedFile(path);
+}
+/**
+ * Bundle-relative path → concept ID (path with `.md` removed, SPEC §2).
+ * `tables/blocks.md` → `tables/blocks`.
+ */
+export function pathToConceptId(path) {
+    const noExt = path.endsWith('.md') ? path.slice(0, -3) : path;
+    // Normalise any backslashes a Windows caller might pass; bundles are POSIX.
+    return noExt.split(/[\\/]/).filter((s) => s.length > 0).join('/');
+}
+/** Concept ID → deterministic subject IRI. Same bundle ⇒ same IRI. */
+export function conceptIdToIri(conceptId, iriBase = DEFAULT_IRI_BASE) {
+    return `${iriBase}${conceptId}`;
+}
+/**
+ * Node-side Knowledge Asset / assertion name for a concept.
+ *
+ * DKG asset/assertion names cannot contain `/`, but OKF concept IDs are
+ * path-based (`tables/blocks`). The encoding must be **injective** — a naive
+ * `/`→`__` collapses `a/b` and the literal concept `a__b` onto the same name.
+ * So escape the escape character first (`_`→`_5f`), then `/`→`_2f` (the chars'
+ * hex codes). `a/b`→`a_2fb`, `a__b`→`a_5f_5fb` — distinct. The RDF subject IRI
+ * is unaffected; it keeps the original `/`-bearing concept ID.
+ */
+export function conceptIdToKaName(conceptId) {
+    return conceptId.replace(/_/g, '_5f').replace(/\//g, '_2f');
+}
+/**
+ * Resolve a Markdown link `href` written inside the concept `fromConceptId`
+ * into a candidate target concept ID, per SPEC §5. Handles:
+ *   - absolute (bundle-relative): `/tables/customers.md`
+ *   - relative: `./other.md`, `../tables/x.md`
+ *   - bare-sibling: `x.md`
+ *   - extension-less variants: `x`, `../tables/x`
+ *   - `#anchor` / `?query` suffixes are stripped first
+ *
+ * Returns `null` for: external URLs (scheme-prefixed), pure anchors, paths that
+ * escape the bundle root, directory links, or any candidate whose segments fail
+ * the `paths.py` validation regex (so it could not be a concept ID anyway).
+ *
+ * Note: this returns a *candidate* — whether the target actually exists in the
+ * bundle is decided by the caller against the Pass-1 concept map. A candidate
+ * that does not exist is a broken link, which is NOT an error (SPEC §5.3/§9).
+ */
+export function resolveLinkTarget(href, fromConceptId) {
+    // Strip anchor / query.
+    let target = href.split('#')[0].split('?')[0].trim();
+    if (target.length === 0)
+        return null;
+    // External URL (http:, mailto:, …) — not a concept link.
+    if (SCHEME_RE.test(target))
+        return null;
+    // A trailing slash denotes a directory, not a concept document.
+    if (target.endsWith('/'))
+        return null;
+    let stack;
+    if (target.startsWith('/')) {
+        // Absolute, bundle-relative.
+        stack = [];
+        target = target.slice(1);
+    }
+    else {
+        // Relative to the linking concept's directory.
+        stack = fromConceptId.split('/').slice(0, -1);
+    }
+    for (const part of target.split('/')) {
+        if (part === '' || part === '.')
+            continue;
+        if (part === '..') {
+            if (stack.length === 0)
+                return null; // escapes the bundle root
+            stack.pop();
+            continue;
+        }
+        stack.push(part);
+    }
+    if (stack.length === 0)
+        return null;
+    // Drop a trailing `.md` extension (extension-less links are left as-is).
+    const last = stack[stack.length - 1];
+    if (last.endsWith('.md')) {
+        stack[stack.length - 1] = last.slice(0, -3);
+    }
+    if (stack[stack.length - 1].length === 0)
+        return null; // directory link
+    // Every segment must be a valid concept-ID segment, else it can't be a concept.
+    for (const seg of stack) {
+        if (!isValidSegment(seg))
+            return null;
+    }
+    return stack.join('/');
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Public types for the OKF → DKG mapper.
+ *
+ * The RDF output is a deterministic array of `Quad`s. We reuse the node's
+ * canonical `Quad` shape (`{ subject, predicate, object, graph? }`) so the
+ * mapper's output drops straight into the importer/`/api/assertion/write`
+ * path without translation.
+ */
+/** Canonical quad shape, structurally identical to `dkg-core`'s extraction `Quad`. */
+export interface Quad {
+    subject: string;
+    predicate: string;
+    object: string;
+    graph?: string;
+}
+/** A parsed OKF concept document (frontmatter + body), per SPEC §4. */
+export interface OkfDocument {
+    /** Bundle-relative concept ID (path with `.md` removed), e.g. `tables/blocks`. */
+    conceptId: string;
+    /** Path segments of the concept ID, e.g. `['tables', 'blocks']`. */
+    segments: string[];
+    /** Parsed YAML frontmatter (empty object if none). */
+    frontmatter: Record<string, unknown>;
+    /** Markdown body (everything after the closing `---`). */
+    body: string;
+}
+/** A resolved or unresolved cross-link discovered in a concept body (SPEC §5). */
+export interface OkfLink {
+    /** Raw link target as written in the Markdown, e.g. `../tables/blocks.md`. */
+    raw: string;
+    /** Resolved target concept ID if it exists in the bundle, else `null`. */
+    targetConceptId: string | null;
+    /** True when the link sat inside an inline code span (SPEC/CommonMark edge case). */
+    inCodeSpan: boolean;
+}
+/** A citation captured from a `# Citations` section (SPEC §8). */
+export interface OkfCitation {
+    /** The cited URL (external in the wild). */
+    url: string;
+    /** Optional human label (numbered `[n] [label](url)` style). */
+    label?: string;
+}
+/**
+ * A deterministic, opt-in rule that types a cross-concept edge by the OKF
+ * `type` of its two endpoints — no LLM, no prose parsing. e.g. a link from a
+ * `BigQuery Dataset` to a `BigQuery Table` is containment (`schema:hasPart`),
+ * while `BigQuery Table` → `BigQuery Table` stays an untyped reference
+ * (`schema:mentions`). Both endpoint types come straight from frontmatter, so
+ * this is byte-stable. Default behaviour (no rules) keeps every edge as
+ * `schema:mentions`, preserving the "links are untyped per SPEC §5.3" guarantee.
+ */
+export interface TypeRelation {
+    /** Source concept's OKF `type` (exact string, e.g. `BigQuery Dataset`). */
+    from: string;
+    /** Target concept's OKF `type`. */
+    to: string;
+    /** Predicate IRI to use for edges matching this (from,to) type pair. */
+    predicate: string;
+}
+/** Mapping options. All deterministic; no network, no LLM. */
+export interface OkfMappingOptions {
+    /** IRI namespace for concept subjects. Default `urn:okf:`. */
+    iriBase?: string;
+    /**
+     * Opt-in type-pair edge typing. Empty/undefined ⇒ every cross-concept edge is
+     * `schema:mentions` (the faithful, zero-interpretation default).
+     */
+    typeRelations?: TypeRelation[];
+    /**
+     * Whether a concept link written inside an inline code span counts as an edge.
+     * Default `false` — CommonMark treats code-span content as literal text, so it
+     * is NOT a link. See ADR 0005 / CONTEXT.md "Flagged ambiguities".
+     */
+    includeCodeSpanLinks?: boolean;
+    /**
+     * Whether to emit `schema:isPartOf` triples reflecting the folder hierarchy.
+     * Default `false` — directories are not concepts, so minting them as nodes
+     * muddies the concept graph. See ADR 0005.
+     */
+    emitFolderHierarchy?: boolean;
+}
+/** Per-concept mapping result. */
+export interface ConceptMapping {
+    conceptId: string;
+    /** Deterministic subject IRI for this concept's Knowledge Asset. */
+    iri: string;
+    /** Content + linkage triples for this concept. */
+    quads: Quad[];
+    /** Resolved concept→concept edges (subset of links). */
+    resolvedLinks: OkfLink[];
+    /** Links whose target is not in the bundle (warned, never fatal — SPEC §5.3/§9). */
+    brokenLinks: OkfLink[];
+    /** Links skipped because they sat in a code span and the option is off. */
+    codeSpanLinks: OkfLink[];
+    /** Citations captured (distinct from concept edges). */
+    citations: OkfCitation[];
+}
+/** A non-fatal diagnostic surfaced during a bundle import. */
+export interface OkfWarning {
+    conceptId?: string;
+    code: 'broken-link' | 'code-span-link' | 'missing-type' | 'reserved-skip' | 'parse' | 'invalid-path';
+    message: string;
+}
+/** Result of importing a whole bundle. */
+export interface BundleImport {
+    /** OKF version declared in the root `index.md`, if any (SPEC §11). */
+    okfVersion: string | null;
+    /** Concept ID → subject IRI map (Pass 1). */
+    iriByConceptId: Record<string, string>;
+    /** Per-concept mappings (Pass 2). */
+    concepts: ConceptMapping[];
+    /** Reserved files (`index.md` / `log.md`) skipped — never minted as KAs. */
+    reservedSkipped: string[];
+    /** All quads across all concepts, in concept order. */
+    quads: Quad[];
+    /** Non-fatal diagnostics. */
+    warnings: OkfWarning[];
+}
+/** A single file fed to the in-memory mapper (path is bundle-relative, POSIX). */
+export interface BundleFile {
+    /** Bundle-relative POSIX path including extension, e.g. `tables/blocks.md`. */
+    path: string;
+    /** UTF-8 file contents. */
+    content: string;
+}
+/** §9 conformance report. */
+export interface ConformanceReport {
+    conformant: boolean;
+    /** Hard violations — only §9 rules 1–2 (parseable frontmatter + non-empty `type`) make a bundle non-conformant; reserved-file structure issues are warnings. */
+    errors: string[];
+    /** Things consumers MUST tolerate (§9) — surfaced as info, never failing. */
+    warnings: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}