oh-my-second-brain 0.1.9 → 0.2.0

package/dist/engine/linkify/mask.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Body masking: split a note body into regions the linkifier may rewrite and
+ * regions it must leave byte-for-byte alone.
+ *
+ * Why this exists: inserting `[[…]]` into a code fence, a URL, an existing
+ * wikilink, or a heading corrupts the note. The span detector therefore never
+ * sees the raw body — it sees only the FREE spans this module returns.
+ *
+ * Design: one collector pass per construct family, then a sort-and-merge into
+ * disjoint ascending ranges, then the complement. Merging (rather than
+ * precedence rules) is what makes overlapping constructs — a URL inside a
+ * markdown link target, a wikilink inside a heading — safe: the union is
+ * protected and nothing is double-counted. Malformed input degrades toward MORE
+ * protection (an unterminated fence protects to end of body), never less.
+ *
+ * Pure module: no I/O, no state. Offsets are UTF-16 indices into the input.
+ */
+import type { MaskResult } from "./types.js";
+/**
+ * Partition `body` into protected and free spans.
+ *
+ * Together the two lists tile `[0, body.length)` exactly once, ascending, with
+ * no zero-length entries. Callers scan `freeSpans` and never touch the rest.
+ */
+export declare function maskBody(body: string): MaskResult;
+/** True when `offset` falls inside any protected span. */
+export declare function isProtected(mask: MaskResult, offset: number): boolean;
+/** The body slices the span detector is allowed to scan, in document order. */
+export declare function freeText(body: string, mask: MaskResult): string[];

package/dist/engine/linkify/mask.js

@@ -0,0 +1,173 @@
+/**
+ * Body masking: split a note body into regions the linkifier may rewrite and
+ * regions it must leave byte-for-byte alone.
+ *
+ * Why this exists: inserting `[[…]]` into a code fence, a URL, an existing
+ * wikilink, or a heading corrupts the note. The span detector therefore never
+ * sees the raw body — it sees only the FREE spans this module returns.
+ *
+ * Design: one collector pass per construct family, then a sort-and-merge into
+ * disjoint ascending ranges, then the complement. Merging (rather than
+ * precedence rules) is what makes overlapping constructs — a URL inside a
+ * markdown link target, a wikilink inside a heading — safe: the union is
+ * protected and nothing is double-counted. Malformed input degrades toward MORE
+ * protection (an unterminated fence protects to end of body), never less.
+ *
+ * Pure module: no I/O, no state. Offsets are UTF-16 indices into the input.
+ */
+// ---------------------------------------------------------------------------
+// Collectors — each returns raw (possibly overlapping) protected ranges
+// ---------------------------------------------------------------------------
+/** Leading `---\n … \n---` YAML block only; a mid-body `---` is a thematic break. */
+function frontmatterSpan(body) {
+    if (!body.startsWith("---\n") && !body.startsWith("---\r\n"))
+        return [];
+    const close = /^---[ \t]*\r?$/m.exec(body.slice(3));
+    if (!close || close.index === undefined)
+        return [];
+    return [{ start: 0, end: 3 + close.index + close[0].length, kind: "frontmatter" }];
+}
+/**
+ * Fenced code blocks (``` or ~~~), including the fence lines themselves.
+ * An unterminated fence protects everything to the end of the body.
+ */
+function fencedCodeSpans(body) {
+    const spans = [];
+    const fence = /^[ \t]*(`{3,}|~{3,})[^\n]*$/gm;
+    let match;
+    while ((match = fence.exec(body)) !== null) {
+        const marker = match[1];
+        if (marker === undefined)
+            continue;
+        const opening = match.index;
+        const closer = new RegExp(`^[ \\t]*${marker[0] === "\`" ? "`" : "~"}{${String(marker.length)},}[ \\t]*$`, "m");
+        const rest = body.slice(fence.lastIndex);
+        const closeMatch = closer.exec(rest);
+        const end = closeMatch && closeMatch.index !== undefined
+            ? fence.lastIndex + closeMatch.index + closeMatch[0].length
+            : body.length;
+        spans.push({ start: opening, end, kind: "fenced-code" });
+        fence.lastIndex = end;
+    }
+    return spans;
+}
+/**
+ * Inline code spans: a run of N backticks closed by another run of exactly N
+ * on the same logical block. An unclosed run protects nothing extra — the
+ * fenced-code pass already covers the block-level case.
+ */
+function inlineCodeSpans(body) {
+    const spans = [];
+    const run = /`+/g;
+    let match;
+    while ((match = run.exec(body)) !== null) {
+        const ticks = match[0];
+        const closeIndex = body.indexOf(ticks, match.index + ticks.length);
+        if (closeIndex < 0)
+            continue;
+        const inner = body.slice(match.index + ticks.length, closeIndex);
+        if (inner.includes("\n\n"))
+            continue;
+        const end = closeIndex + ticks.length;
+        spans.push({ start: match.index, end, kind: "inline-code" });
+        run.lastIndex = end;
+    }
+    return spans;
+}
+/** Regex-driven collectors that need no cursor bookkeeping. */
+const SIMPLE_PATTERNS = [
+    // image embeds first so their `!` prefix is inside the span, not left free
+    { kind: "image-embed", pattern: /!\[\[[^\]\n]*\]\]/g },
+    { kind: "image-embed", pattern: /!\[[^\]\n]*\]\([^)\n]*\)/g },
+    { kind: "wikilink", pattern: /\[\[[^\]\n]*\]\]/g },
+    { kind: "markdown-link", pattern: /\[[^\]\n]*\]\([^)\n]*\)/g },
+    { kind: "html", pattern: /<\/?[A-Za-z][^<>\n]*>/g },
+    { kind: "heading", pattern: /^[ \t]{0,3}#{1,6}[ \t][^\n]*$/gm },
+    { kind: "heading", pattern: /^[^\n]+\r?\n[ \t]{0,3}(?:=+|-{2,})[ \t]*$/gm },
+    { kind: "url", pattern: /\b(?:https?|ftp|obsidian|mailto):[^\s<>()[\]]+/g },
+    { kind: "block-id", pattern: /(?<=\s)\^[A-Za-z0-9-]+[ \t]*$/gm },
+    { kind: "tag", pattern: /(?<=^|\s)#[\p{L}\p{N}][\p{L}\p{N}/_-]*/gu },
+];
+function simpleSpans(body) {
+    const spans = [];
+    for (const { kind, pattern } of SIMPLE_PATTERNS) {
+        const scanner = new RegExp(pattern.source, pattern.flags);
+        let match;
+        while ((match = scanner.exec(body)) !== null) {
+            if (match[0].length < 1) {
+                scanner.lastIndex += 1;
+                continue;
+            }
+            spans.push({ start: match.index, end: match.index + match[0].length, kind });
+        }
+    }
+    return spans;
+}
+// ---------------------------------------------------------------------------
+// Merge + complement
+// ---------------------------------------------------------------------------
+/**
+ * Sort by start (earlier wins, longer wins on tie) and fuse overlaps into one
+ * span carrying the first contributor's kind — the union is what matters to the
+ * detector; the kind is reviewer-facing provenance.
+ */
+function mergeSpans(raw) {
+    const sorted = raw
+        .filter((s) => s.end > s.start)
+        .slice()
+        .sort((a, b) => a.start - b.start || b.end - a.end);
+    const merged = [];
+    for (const span of sorted) {
+        const last = merged[merged.length - 1];
+        if (last !== undefined && span.start <= last.end) {
+            if (span.end > last.end) {
+                merged[merged.length - 1] = { start: last.start, end: span.end, kind: last.kind };
+            }
+            continue;
+        }
+        merged.push(span);
+    }
+    return merged;
+}
+/** The complement of `protectedSpans` within `[0, length)`. */
+function complement(protectedSpans, length) {
+    const free = [];
+    let cursor = 0;
+    for (const span of protectedSpans) {
+        if (span.start > cursor)
+            free.push({ start: cursor, end: span.start });
+        cursor = span.end;
+    }
+    if (cursor < length)
+        free.push({ start: cursor, end: length });
+    return free;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Partition `body` into protected and free spans.
+ *
+ * Together the two lists tile `[0, body.length)` exactly once, ascending, with
+ * no zero-length entries. Callers scan `freeSpans` and never touch the rest.
+ */
+export function maskBody(body) {
+    if (body.length < 1)
+        return { protectedSpans: [], freeSpans: [] };
+    const protectedSpans = mergeSpans([
+        ...frontmatterSpan(body),
+        ...fencedCodeSpans(body),
+        ...inlineCodeSpans(body),
+        ...simpleSpans(body),
+    ]);
+    return { protectedSpans, freeSpans: complement(protectedSpans, body.length) };
+}
+/** True when `offset` falls inside any protected span. */
+export function isProtected(mask, offset) {
+    return mask.protectedSpans.some((span) => span.start <= offset && offset < span.end);
+}
+/** The body slices the span detector is allowed to scan, in document order. */
+export function freeText(body, mask) {
+    return mask.freeSpans.map((span) => body.slice(span.start, span.end));
+}
+//# sourceMappingURL=mask.js.map

package/dist/engine/linkify/mask.js.map

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

package/dist/engine/linkify/suggest.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Span detection: propose `[[wikilink]]` insertions for a note body.
+ *
+ * The pipeline is surface-anchored by construction. A candidate exists ONLY
+ * because a term's basename or frontmatter alias literally appears in a FREE
+ * region of the body (see mask.ts). Retrieval signals never create candidates:
+ * an injected lexical ranker may only reorder what the surface already found,
+ * and an injected vector predicate may only veto. This is what keeps the
+ * feature from hallucinating links into a user's vault.
+ *
+ * Two rules encode judgement the machine must not make on its own:
+ *   - FIRST occurrence per target note only — a term linked ten times is noise.
+ *   - Ambiguity (2+ notes claiming one span) is REPORTED, never resolved. The
+ *     resolver's shortest-path tie-break is right for reading an existing link
+ *     and wrong for creating a new one.
+ *
+ * Pure given its injected dependencies: no I/O, no globals, no clock.
+ */
+import type { LinkCandidate, TermNote } from "./types.js";
+/** The ontology concept whose notes are the default link universe. */
+export declare const TERM_CONCEPT = "term";
+/** Minimal shape of `EngineStore.queryLex` results — only what ranking needs. */
+export interface LexHit {
+    readonly docPath: string;
+    readonly score: number;
+}
+/** Options for {@link suggestLinks}; every dependency is optional and injected. */
+export interface SuggestOptions {
+    /** Vault-relative path of the note being linkified; never linked to itself. */
+    readonly notePath: string;
+    /** Optional lexical re-ranker. Reorders surface-anchored candidates only. */
+    readonly queryLex?: (text: string, k: number) => readonly LexHit[];
+    /** Optional semantic veto, honoured only when `embeddingConfigured` is true. */
+    readonly vectorVeto?: (candidate: LinkCandidate) => boolean;
+    /** ADR-007 gate; when false the vector veto is inert. Defaults to true. */
+    readonly embeddingConfigured?: boolean;
+}
+/**
+ * Restrict a candidate set to notes bound to the `term` concept.
+ *
+ * Offered as a helper rather than applied inside {@link suggestLinks} so the
+ * caller owns the universe decision (a vault may want a wider set).
+ */
+export declare function termBoundNotes(notes: readonly TermNote[]): TermNote[];
+/**
+ * Propose link candidates for `body` against `notes`.
+ *
+ * Candidates are returned ranked (highest confidence first, earliest offset
+ * breaking ties) and are guaranteed to be non-overlapping, first-occurrence
+ * only, outside every protected region, and never self-referential.
+ */
+export declare function suggestLinks(body: string, notes: readonly TermNote[], options: SuggestOptions): LinkCandidate[];

package/dist/engine/linkify/suggest.js

@@ -0,0 +1,181 @@
+/**
+ * Span detection: propose `[[wikilink]]` insertions for a note body.
+ *
+ * The pipeline is surface-anchored by construction. A candidate exists ONLY
+ * because a term's basename or frontmatter alias literally appears in a FREE
+ * region of the body (see mask.ts). Retrieval signals never create candidates:
+ * an injected lexical ranker may only reorder what the surface already found,
+ * and an injected vector predicate may only veto. This is what keeps the
+ * feature from hallucinating links into a user's vault.
+ *
+ * Two rules encode judgement the machine must not make on its own:
+ *   - FIRST occurrence per target note only — a term linked ten times is noise.
+ *   - Ambiguity (2+ notes claiming one span) is REPORTED, never resolved. The
+ *     resolver's shortest-path tie-break is right for reading an existing link
+ *     and wrong for creating a new one.
+ *
+ * Pure given its injected dependencies: no I/O, no globals, no clock.
+ */
+import path from "node:path";
+import { matchTermInToken } from "./josa.js";
+import { maskBody } from "./mask.js";
+/** The ontology concept whose notes are the default link universe. */
+export const TERM_CONCEPT = "term";
+const BASENAME_CONFIDENCE = 0.9;
+const ALIAS_CONFIDENCE = 0.6;
+const TOKEN_PATTERN = /[\p{L}\p{N}][\p{L}\p{N}_'-]*/gu;
+// ---------------------------------------------------------------------------
+// Candidate universe
+// ---------------------------------------------------------------------------
+/**
+ * Restrict a candidate set to notes bound to the `term` concept.
+ *
+ * Offered as a helper rather than applied inside {@link suggestLinks} so the
+ * caller owns the universe decision (a vault may want a wider set).
+ */
+export function termBoundNotes(notes) {
+    return notes.filter((note) => note.concept === TERM_CONCEPT);
+}
+/** Basename + alias surfaces of a note, longest first so the greediest wins. */
+function surfacesOf(note) {
+    const basename = path.basename(note.path, ".md");
+    const surfaces = [{ note, text: basename, source: "basename" }];
+    for (const alias of note.aliases) {
+        const trimmed = alias.trim();
+        if (trimmed.length > 0)
+            surfaces.push({ note, text: trimmed, source: "alias" });
+    }
+    return surfaces.sort((a, b) => b.text.length - a.text.length);
+}
+// ---------------------------------------------------------------------------
+// Detection over free spans
+// ---------------------------------------------------------------------------
+/**
+ * Locate every surface hit inside one free span, via the josa-aware matcher.
+ *
+ * At most one hit per NOTE per token (its longest matching surface), but every
+ * note that claims the token is recorded — that is precisely the signal the
+ * ambiguity check downstream needs.
+ */
+function hitsInSpan(body, span, surfaces) {
+    const text = body.slice(span.start, span.end);
+    const hits = [];
+    for (const match of text.matchAll(TOKEN_PATTERN)) {
+        const token = match[0];
+        const tokenStart = match.index;
+        if (tokenStart === undefined)
+            continue;
+        const claimed = new Set();
+        for (const surface of surfaces) {
+            if (claimed.has(surface.note.path))
+                continue;
+            const result = matchTermInToken(surface.text, token);
+            if (result.kind === "no_match")
+                continue;
+            claimed.add(surface.note.path);
+            hits.push({
+                start: span.start + tokenStart + result.stemStart,
+                end: span.start + tokenStart + result.stemEnd,
+                matchedText: token.slice(result.stemStart, result.stemEnd),
+                surface,
+            });
+        }
+    }
+    return hits;
+}
+/** Render the replacement, aliasing whenever the surface differs from the target. */
+function render(matchedText, note) {
+    const basename = path.basename(note.path, ".md");
+    return matchedText === basename ? `[[${basename}]]` : `[[${basename}|${matchedText}]]`;
+}
+// ---------------------------------------------------------------------------
+// Grouping, ranking
+// ---------------------------------------------------------------------------
+/** Fold hits sharing one offset span into a single (possibly ambiguous) candidate. */
+function groupBySpan(hits) {
+    const bySpan = new Map();
+    for (const hit of hits) {
+        const key = `${String(hit.start)}:${String(hit.end)}`;
+        const bucket = bySpan.get(key) ?? [];
+        bucket.push(hit);
+        bySpan.set(key, bucket);
+    }
+    return [...bySpan.values()].map((bucket) => {
+        const rivalPaths = [...new Set(bucket.map((hit) => hit.surface.note.path))];
+        const best = bucket.reduce((a, b) => (confidenceOf(a) >= confidenceOf(b) ? a : b));
+        return {
+            startOffset: best.start,
+            endOffset: best.end,
+            matchedText: best.matchedText,
+            targetPath: best.surface.note.path,
+            renderedReplacement: render(best.matchedText, best.surface.note),
+            source: best.surface.source,
+            confidence: confidenceOf(best),
+            ambiguous: rivalPaths.length > 1,
+            rivalPaths,
+        };
+    });
+}
+function confidenceOf(hit) {
+    return hit.surface.source === "basename" ? BASENAME_CONFIDENCE : ALIAS_CONFIDENCE;
+}
+/** Keep the earliest candidate per target note; later mentions are noise. */
+function firstPerTarget(candidates) {
+    const seen = new Set();
+    return candidates
+        .slice()
+        .sort((a, b) => a.startOffset - b.startOffset)
+        .filter((candidate) => {
+        if (seen.has(candidate.targetPath))
+            return false;
+        seen.add(candidate.targetPath);
+        return true;
+    });
+}
+/**
+ * Additive lexical boost, normalised to (0, 0.1]: strong enough to reorder ties
+ * between candidates of the same source class, too small to lift an alias hit
+ * above an exact basename hit.
+ */
+function lexBoosts(body, options) {
+    const lex = options.queryLex;
+    if (lex === undefined)
+        return new Map();
+    const hits = lex(body, 20);
+    const top = Math.max(...hits.map((hit) => hit.score), 1);
+    return new Map(hits.map((hit) => [hit.docPath, (hit.score / top) * 0.1]));
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Propose link candidates for `body` against `notes`.
+ *
+ * Candidates are returned ranked (highest confidence first, earliest offset
+ * breaking ties) and are guaranteed to be non-overlapping, first-occurrence
+ * only, outside every protected region, and never self-referential.
+ */
+export function suggestLinks(body, notes, options) {
+    if (body.length < 1)
+        return [];
+    const surfaces = notes
+        .filter((note) => note.path !== options.notePath)
+        .flatMap(surfacesOf)
+        .sort((a, b) => b.text.length - a.text.length);
+    if (surfaces.length < 1)
+        return [];
+    const mask = maskBody(body);
+    const hits = mask.freeSpans.flatMap((span) => hitsInSpan(body, span, surfaces));
+    const candidates = firstPerTarget(groupBySpan(hits));
+    const boosts = lexBoosts(body, options);
+    const gateOpen = options.embeddingConfigured ?? true;
+    const veto = gateOpen ? options.vectorVeto : undefined;
+    return candidates
+        .map((candidate) => ({
+        ...candidate,
+        confidence: candidate.confidence + (boosts.get(candidate.targetPath) ?? 0),
+    }))
+        .filter((candidate) => veto === undefined || !veto(candidate))
+        .sort((a, b) => b.confidence - a.confidence || a.startOffset - b.startOffset);
+}
+//# sourceMappingURL=suggest.js.map

package/dist/engine/linkify/suggest.js.map

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

package/dist/engine/linkify/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared value types for the linkify core (mask → suggest → apply).
+ *
+ * Kept in one place because all three stages speak the same coordinate system:
+ * half-open UTF-16 offset ranges into the ORIGINAL note body string. Every
+ * offset any linkify module emits or consumes indexes that same string, so a
+ * caller can splice with `body.slice(start, end)` without a second pass.
+ *
+ * Pure types only: no I/O, no runtime dependencies.
+ */
+/** Why a body region is off-limits to the span detector. */
+export type ProtectedKind = "frontmatter" | "fenced-code" | "inline-code" | "wikilink" | "markdown-link" | "image-embed" | "html" | "heading" | "url" | "block-id" | "tag";
+/** A half-open `[start, end)` range of UTF-16 offsets into the note body. */
+export interface Span {
+    readonly start: number;
+    readonly end: number;
+}
+/** A protected range plus the syntax that claimed it. */
+export interface ProtectedSpan extends Span {
+    readonly kind: ProtectedKind;
+}
+/**
+ * The body partitioned into regions the span detector must not touch
+ * (`protectedSpans`) and the complement it may scan (`freeSpans`).
+ *
+ * Both lists are sorted by `start`, contain no zero-length entries, and never
+ * overlap each other; together they tile the whole body exactly once.
+ */
+export interface MaskResult {
+    readonly protectedSpans: readonly ProtectedSpan[];
+    readonly freeSpans: readonly Span[];
+}
+/** Which surface form of a note a candidate span matched. */
+export type MatchSource = "basename" | "alias";
+/**
+ * One proposed link: the body range to replace and the text to replace it with.
+ *
+ * `renderedReplacement` is the finished wikilink for the STEM only. A trailing
+ * Korean particle is left OUTSIDE both the span and the link — `아타락시아를`
+ * yields the range covering `아타락시아` and the replacement
+ * `[[Ataraxia|아타락시아]]`, so splicing keeps `를` in the prose. Apply never
+ * re-derives the text.
+ */
+export interface LinkCandidate {
+    readonly startOffset: number;
+    readonly endOffset: number;
+    /** Exact body slice `[startOffset, endOffset)` this candidate replaces. */
+    readonly matchedText: string;
+    /** Vault-relative path of the note the link points at. */
+    readonly targetPath: string;
+    readonly renderedReplacement: string;
+    readonly source: MatchSource;
+    /** Higher is better; ranking is total and deterministic. */
+    readonly confidence: number;
+    /** True when 2+ distinct notes claim this span — the caller must disambiguate. */
+    readonly ambiguous: boolean;
+    /** Every note path that claimed the span (length ≥ 2 exactly when ambiguous). */
+    readonly rivalPaths: readonly string[];
+}
+/** A link-target note: its vault path, concept binding, and surface forms. */
+export interface TermNote {
+    /** Vault-relative path (with .md). */
+    readonly path: string;
+    /** Ontology concept this note is bound to, or null when unbound. */
+    readonly concept: string | null;
+    /** Frontmatter `aliases`, already flattened to trimmed strings. */
+    readonly aliases: readonly string[];
+}

package/dist/engine/linkify/types.js

@@ -0,0 +1,12 @@
+/**
+ * Shared value types for the linkify core (mask → suggest → apply).
+ *
+ * Kept in one place because all three stages speak the same coordinate system:
+ * half-open UTF-16 offset ranges into the ORIGINAL note body string. Every
+ * offset any linkify module emits or consumes indexes that same string, so a
+ * caller can splice with `body.slice(start, end)` without a second pass.
+ *
+ * Pure types only: no I/O, no runtime dependencies.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/engine/linkify/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/engine/linkify/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/harness/surface-registry.d.ts

@@ -41,6 +41,7 @@ export interface HarnessRuntimeAssetRoot {
 }
 export interface HarnessPackageAssetSurface {
     readonly npmFiles: readonly string[];
+    readonly rootShippedFiles: readonly string[];
     readonly runtimeAssetRoots: readonly HarnessRuntimeAssetRoot[];
     readonly releaseRequiredPaths: readonly string[];
 }

package/dist/harness/surface-registry.js

@@ -5,6 +5,7 @@ export const harnessSurfaceRegistry = {
         { name: "audit", owner: "cli", stability: "stable" },
         { name: "lint", owner: "cli", stability: "stable" },
         { name: "link", owner: "cli", stability: "experimental" },
+        { name: "linkify", owner: "cli", stability: "experimental" },
         { name: "install", owner: "install", stability: "stable" },
         { name: "uninstall", owner: "install", stability: "stable" },
         { name: "update", owner: "install", stability: "stable" },
@@ -30,6 +31,7 @@ export const harnessSurfaceRegistry = {
         "define",
         "distill",
         "doctor",
+        "link",
         "retrieve",
         "setup",
         "uninstall",
@@ -220,6 +222,24 @@ export const harnessSurfaceRegistry = {
             openWorld: false,
             stability: "stable",
         },
+        {
+            name: "oms_link_suggest",
+            owner: "retrieval",
+            posture: "read",
+            destructive: false,
+            idempotent: true,
+            openWorld: false,
+            stability: "experimental",
+        },
+        {
+            name: "oms_link_apply",
+            owner: "capture",
+            posture: "write",
+            destructive: true,
+            idempotent: false,
+            openWorld: false,
+            stability: "experimental",
+        },
         {
             name: "write",
             owner: "capture",
@@ -239,6 +259,7 @@ export const harnessSurfaceRegistry = {
                 "define",
                 "distill",
                 "doctor",
+                "link",
                 "retrieve",
                 "setup",
                 "uninstall",
@@ -264,6 +285,7 @@ export const harnessSurfaceRegistry = {
                 "oms-distill",
                 "oms-doctor",
                 "oms-install",
+                "oms-link",
                 "oms-retrieve",
                 "oms-setup",
                 "oms-uninstall",
@@ -287,6 +309,7 @@ export const harnessSurfaceRegistry = {
                 "distill",
                 "doctor",
                 "install",
+                "link",
                 "retrieve",
                 "setup",
                 "uninstall",
@@ -327,6 +350,10 @@ export const harnessSurfaceRegistry = {
             "docs/release.md",
             "scripts/install.sh",
             "scripts/uninstall.sh",
+            "CHANGELOG.md",
+        ],
+        rootShippedFiles: [
+            "CHANGELOG.md",
         ],
         runtimeAssetRoots: [
             { id: "ontology", path: "core/ontology", owner: "core" },