@deepwatch/dsh-adapters 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oxbshw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# @deepwatch/dsh-adapters
+
+Optional adapters: Obsidian vaults and LLMWiki bundles. Watch works fully without either.
+
+Part of **DeepWatch** — the agent workspace built on the official
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
+and powered by [Watch Skill](https://github.com/oxbshw/watch-skill) for perception, evidence, memory and
+independent verification.
+
+> **Optional extra — nothing requires it.**
+> Anyone exporting Watch's memory into another tool. Nothing depends on it.
+
+## Exports
+
+- `@deepwatch/dsh-adapters`
+
+## Install
+
+> **Not on npm yet.** Nothing exists under the `@deepwatch` scope. This
+> package is published for the first time by the `deepwatch-v0.1.0`
+> release; until then the command below resolves nothing, and
+> [the workspace README](https://github.com/oxbshw/watch-skill/tree/main/workspace#readme) has the path
+> that works from a checkout.
+
+```sh
+npm install @deepwatch/dsh-adapters
+```
+
+Rarely on its own. [`@deepwatch/dsh-bundle`](https://github.com/oxbshw/watch-skill/tree/main/workspace/packages/watch/bundle#readme)
+composes this package with the rest of DeepWatch and is what a profile
+normally depends on; installing this one directly is for embedding a
+single piece in a composition you control.
+
+## Example
+
+Export the wiki as an Obsidian vault:
+
+> Pending the `deepwatch-v0.1.0` release — see Install above.
+
+```sh
+import { buildWiki, toVault } from '@deepwatch/dsh-adapters'
+
+const vault = toVault(buildWiki(records), { name: 'Watch' })
+```
+
+## Requirements
+
+- Node `^22.19.0 || >=24.0.0`
+
+## Stability
+
+`0.1.0` — a stable release.
+
+Stable means tested, documented and supported — not 1.0. This is a
+pre-1.0 line, and semantic versioning gives `0.x` no compatibility
+guarantee across minor versions: **a `0.MINOR` bump may change or remove
+surface, and a patch will not.** Depend on it with a tilde range
+(`~0.1.0`) if you want that difference enforced by your lockfile
+rather than by a changelog. The usual major-version promise starts at 1.0.
+
+## Side effects
+
+Importing a module from this package evaluates no side effects, so a
+bundler may drop what a build does not use. Mounting it in a host is a
+separate matter: what it then reads or writes is governed by the
+workspace boundary and the host's permissions, not by this flag.
+
+## Where this fits
+
+Obsidian vaults and LLMWiki bundles, generated from the ledger. An edit in an exported vault is a proposal, never a change: Watch is the record and the folder is a copy.
+
+The twenty packages and how they compose:
+[the package map](https://github.com/oxbshw/watch-skill/blob/main/workspace/docs/packages.md).
+Running DeepWatch, and the gates a change has to pass:
+[the workspace README](https://github.com/oxbshw/watch-skill/tree/main/workspace#readme).
+
+## Attribution
+
+Built on DeepSeek Harness · Powered by Watch Skill
+
+DeepWatch and Watch Skill are independent projects and are not affiliated
+with or endorsed by DeepSeek. MIT licensed; third-party notices are in
+[THIRD_PARTY_NOTICES.md](https://github.com/oxbshw/watch-skill/blob/main/workspace/THIRD_PARTY_NOTICES.md).

package/lib/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Optional adapters.
+ *
+ * Both are optional in the strong sense: Watch is complete without either, and
+ * neither can become an authority for anything. Content that arrives through
+ * an adapter is imported at the weakest origin there is.
+ *
+ * @module @deepwatch/dsh-adapters
+ */
+export * from './obsidian.js';
+export * from './llmwiki.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -0,0 +1,12 @@
+/**
+ * Optional adapters.
+ *
+ * Both are optional in the strong sense: Watch is complete without either, and
+ * neither can become an authority for anything. Content that arrives through
+ * an adapter is imported at the weakest origin there is.
+ *
+ * @module @deepwatch/dsh-adapters
+ */
+export * from './obsidian.js';
+export * from './llmwiki.js';
+//# sourceMappingURL=index.js.map

package/lib/llmwiki.d.ts

@@ -0,0 +1,115 @@
+/**
+ * LLMWiki compatibility: five files in, five files out, no authority moved.
+ *
+ * LLMWiki's shape — raw, wiki, citations, index, log — is a good one, and
+ * being able to read and write it means a workspace is not trapped here. That
+ * is the whole reason this adapter exists, and it is optional in both
+ * directions: nothing in Watch requires it, and nothing about importing a
+ * bundle makes LLMWiki the authority for anything.
+ *
+ * The asymmetry is deliberate and is the only interesting thing in the module.
+ *
+ * **Export is lossless about provenance and lossy about nothing else.** Every
+ * exported statement carries its memory id, and `citations` carries the
+ * evidence refs, so a bundle that leaves here can be read by something else
+ * without the reader having to trust a sentence with no source.
+ *
+ * **Import is lossy on purpose.** Everything imported arrives as `imported`
+ * origin at low confidence, whatever the bundle claims. A bundle that says a
+ * statement is `explicit_user`, or high confidence, or already verified, is a
+ * bundle making claims about a person it has never met. Those fields are read
+ * and discarded rather than trusted, and the discarding is tested with a
+ * bundle that asserts all of them at once.
+ *
+ * @module @deepwatch/dsh-adapters/llmwiki
+ */
+import type { MemoryEvent, MemoryRecord } from '@deepwatch/dsh-memory';
+/** The five files an LLMWiki bundle carries. */
+export interface LlmWikiBundle {
+    /** Statements as they were captured, one per line, with provenance markers. */
+    readonly raw: string;
+    /** The readable pages. */
+    readonly wiki: string;
+    /** Evidence references, one per line. */
+    readonly citations: string;
+    /** What is in the bundle, by kind. */
+    readonly index: string;
+    /** What happened, by id and kind. Never content. */
+    readonly log: string;
+}
+/** One statement, as the bundle format carries it. */
+export interface LlmWikiStatement {
+    readonly id: string;
+    readonly kind: string;
+    readonly text: string;
+    /** What the bundle claims. Read, reported, and never trusted on import. */
+    readonly claimedOrigin: string | null;
+    readonly claimedConfidence: number | null;
+    readonly evidenceRefs: readonly string[];
+}
+/** Parse one statement line back. */
+export declare function parseStatement(line: string): LlmWikiStatement | null;
+/**
+ * Export a bundle.
+ *
+ * Deterministic: the same records and events produce the same five files, so
+ * two exports of an unchanged workspace are identical and a diff between them
+ * is a real change rather than a reordering.
+ */
+export declare function toLlmWiki(records: readonly MemoryRecord[], events?: readonly MemoryEvent[]): LlmWikiBundle;
+/** Why an imported statement was refused. */
+export interface ImportRefusal {
+    readonly statement: LlmWikiStatement;
+    readonly reason: string;
+}
+/** A candidate the ledger may consider, produced from an imported statement. */
+export interface ImportedStatement {
+    readonly kind: MemoryRecord['kind'];
+    readonly content: string;
+    readonly origin: 'imported';
+    readonly confidence: number;
+    readonly sourceRefs: readonly string[];
+    readonly evidenceRefs: readonly string[];
+    /** What the bundle claimed, kept for the review UI. Never acted on. */
+    readonly claimed: {
+        readonly origin: string | null;
+        readonly confidence: number | null;
+    };
+}
+/** The outcome of reading a bundle. */
+export interface ImportResult {
+    readonly accepted: readonly ImportedStatement[];
+    readonly refused: readonly ImportRefusal[];
+    /** One line for the import dialog. */
+    readonly summary: string;
+}
+/**
+ * Read a bundle.
+ *
+ * Every accepted statement comes back as `imported` at a fixed low confidence.
+ * The claimed origin and confidence travel alongside, so a review surface can
+ * show "this bundle says you stated it" without the ledger acting on it —
+ * which is the difference between reporting a claim and believing one.
+ *
+ * The refusals are the same two the wiki import uses, for the same reason: a
+ * bundle is a file, and a file that could grant a permission or assert
+ * something about a protected subject is a file that writes itself into
+ * authority.
+ */
+export declare function fromLlmWiki(bundle: LlmWikiBundle): ImportResult;
+/**
+ * Whether a round trip preserved what it should.
+ *
+ * Checks content and evidence refs, and deliberately does *not* check origin or
+ * confidence — those are supposed to be lost on import, and a round-trip test
+ * that required them to survive would be a test demanding the vulnerability.
+ */
+export declare function roundTripPreservesContent(original: readonly MemoryRecord[], imported: readonly ImportedStatement[]): boolean;
+/** What this adapter can claim. Optional, and never an authority. */
+export declare function llmWikiAvailability(): {
+    readonly adapterId: string;
+    readonly optional: true;
+    readonly proven: readonly string[];
+    readonly notMachineTested: readonly string[];
+};
+//# sourceMappingURL=llmwiki.d.ts.map

package/lib/llmwiki.js

@@ -0,0 +1,207 @@
+/**
+ * LLMWiki compatibility: five files in, five files out, no authority moved.
+ *
+ * LLMWiki's shape — raw, wiki, citations, index, log — is a good one, and
+ * being able to read and write it means a workspace is not trapped here. That
+ * is the whole reason this adapter exists, and it is optional in both
+ * directions: nothing in Watch requires it, and nothing about importing a
+ * bundle makes LLMWiki the authority for anything.
+ *
+ * The asymmetry is deliberate and is the only interesting thing in the module.
+ *
+ * **Export is lossless about provenance and lossy about nothing else.** Every
+ * exported statement carries its memory id, and `citations` carries the
+ * evidence refs, so a bundle that leaves here can be read by something else
+ * without the reader having to trust a sentence with no source.
+ *
+ * **Import is lossy on purpose.** Everything imported arrives as `imported`
+ * origin at low confidence, whatever the bundle claims. A bundle that says a
+ * statement is `explicit_user`, or high confidence, or already verified, is a
+ * bundle making claims about a person it has never met. Those fields are read
+ * and discarded rather than trusted, and the discarding is tested with a
+ * bundle that asserts all of them at once.
+ *
+ * @module @deepwatch/dsh-adapters/llmwiki
+ */
+import { isHighImpact, isProtectedSubject } from '@deepwatch/dsh-memory';
+/** Serialize one statement line. */
+function statementLine(record) {
+    const refs = record.evidenceRefs.length === 0 ? '' : ` refs=${record.evidenceRefs.join(',')}`;
+    return `[${record.memoryId}] (${record.kind}) origin=${record.origin} `
+        + `confidence=${record.confidence.toFixed(2)}${refs} :: ${record.content.replace(/\r?\n/g, ' ')}`;
+}
+/** Parse one statement line back. */
+export function parseStatement(line) {
+    const match = /^\[([^\]]+)\]\s*\(([^)]*)\)\s*(.*?)::\s*(.*)$/.exec(line.trim());
+    if (match === null)
+        return null;
+    const [, id, kind, attributes, text] = match;
+    const origin = /origin=([A-Za-z_]+)/.exec(attributes ?? '')?.[1] ?? null;
+    const confidence = /confidence=([0-9.]+)/.exec(attributes ?? '')?.[1];
+    const refs = /refs=([^\s]+)/.exec(attributes ?? '')?.[1];
+    return {
+        id: id ?? '',
+        kind: kind ?? '',
+        text: (text ?? '').trim(),
+        claimedOrigin: origin,
+        claimedConfidence: confidence === undefined ? null : Number(confidence),
+        evidenceRefs: refs === undefined ? [] : refs.split(',').filter(ref => ref !== ''),
+    };
+}
+/** Records in a stable order, so a bundle is byte-reproducible. */
+function ordered(records) {
+    return [...records].sort((left, right) => left.memoryId.localeCompare(right.memoryId));
+}
+/**
+ * Export a bundle.
+ *
+ * Deterministic: the same records and events produce the same five files, so
+ * two exports of an unchanged workspace are identical and a diff between them
+ * is a real change rather than a reordering.
+ */
+export function toLlmWiki(records, events = []) {
+    const sorted = ordered(records);
+    const raw = sorted.map(statementLine).join('\n');
+    const byKind = new Map();
+    for (const record of sorted) {
+        const bucket = byKind.get(record.kind) ?? [];
+        bucket.push(record);
+        byKind.set(record.kind, bucket);
+    }
+    const wiki = [...byKind.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .flatMap(([kind, bucket]) => [
+        `## ${kind}`,
+        '',
+        ...bucket.map(record => `- ${record.content.replace(/\r?\n/g, ' ')} ^${record.memoryId}`),
+        '',
+    ])
+        .join('\n');
+    const citations = sorted
+        .filter(record => record.evidenceRefs.length > 0 || record.sourceRefs.length > 0)
+        .map(record => `${record.memoryId} :: ${[...record.evidenceRefs, ...record.sourceRefs].join(',')}`)
+        .join('\n');
+    const index = [
+        '| kind | count |',
+        '|---|---:|',
+        ...[...byKind.entries()]
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([kind, bucket]) => `| ${kind} | ${String(bucket.length)} |`),
+    ].join('\n');
+    // Ids, kinds, actors, timestamps. Never content — a log that reproduced what
+    // was forgotten, in the entry recording that it was forgotten, is not a
+    // deletion, and an export is exactly where that mistake escapes the product.
+    const log = events
+        .map(event => `${event.at} ${event.kind} ${event.actor} ${event.memoryId}`)
+        .join('\n');
+    return { raw, wiki, citations, index, log };
+}
+/** Kinds this adapter recognizes; anything else becomes a plain fact. */
+const KNOWN_KINDS = new Set([
+    'preference', 'fact', 'episode', 'decision', 'lesson', 'procedure', 'failure',
+]);
+/** Coerce a claimed kind into one the ledger knows. */
+function kindOf(claimed) {
+    return KNOWN_KINDS.has(claimed)
+        ? claimed
+        : 'fact';
+}
+/**
+ * Read a bundle.
+ *
+ * Every accepted statement comes back as `imported` at a fixed low confidence.
+ * The claimed origin and confidence travel alongside, so a review surface can
+ * show "this bundle says you stated it" without the ledger acting on it —
+ * which is the difference between reporting a claim and believing one.
+ *
+ * The refusals are the same two the wiki import uses, for the same reason: a
+ * bundle is a file, and a file that could grant a permission or assert
+ * something about a protected subject is a file that writes itself into
+ * authority.
+ */
+export function fromLlmWiki(bundle) {
+    const accepted = [];
+    const refused = [];
+    for (const line of bundle.raw.split(/\r?\n/)) {
+        if (line.trim() === '')
+            continue;
+        const statement = parseStatement(line);
+        if (statement === null) {
+            refused.push({
+                statement: { id: '', kind: '', text: line, claimedOrigin: null, claimedConfidence: null, evidenceRefs: [] },
+                reason: 'The line is not in the bundle statement format.',
+            });
+            continue;
+        }
+        if (statement.text === '') {
+            refused.push({ statement, reason: 'The statement is empty.' });
+            continue;
+        }
+        if (isHighImpact(statement.text)) {
+            refused.push({
+                statement,
+                reason: 'An imported statement cannot grant a permission or weaken a safeguard.',
+            });
+            continue;
+        }
+        if (isProtectedSubject(statement.text)) {
+            refused.push({
+                statement,
+                reason: 'An imported statement cannot assert something about a protected subject.',
+            });
+            continue;
+        }
+        accepted.push({
+            kind: kindOf(statement.kind),
+            content: statement.text,
+            // Fixed, whatever the bundle said. A file claiming a person stated
+            // something is a file making a claim about a person it never met.
+            origin: 'imported',
+            confidence: 0.3,
+            sourceRefs: ['llmwiki:import'],
+            evidenceRefs: statement.evidenceRefs,
+            claimed: { origin: statement.claimedOrigin, confidence: statement.claimedConfidence },
+        });
+    }
+    const summary = `${String(accepted.length)} statement(s) proposed, `
+        + `${String(refused.length)} refused. `
+        + 'Everything imported arrives unconfirmed, at the weakest origin.';
+    return { accepted, refused, summary };
+}
+/**
+ * Whether a round trip preserved what it should.
+ *
+ * Checks content and evidence refs, and deliberately does *not* check origin or
+ * confidence — those are supposed to be lost on import, and a round-trip test
+ * that required them to survive would be a test demanding the vulnerability.
+ */
+export function roundTripPreservesContent(original, imported) {
+    const wanted = new Map(original.map(record => [record.content, record.evidenceRefs.join(',')]));
+    for (const statement of imported) {
+        const refs = wanted.get(statement.content);
+        if (refs === undefined)
+            return false;
+        if (refs !== statement.evidenceRefs.join(','))
+            return false;
+    }
+    return wanted.size === new Set(imported.map(statement => statement.content)).size;
+}
+/** What this adapter can claim. Optional, and never an authority. */
+export function llmWikiAvailability() {
+    return {
+        adapterId: 'adapter.llmwiki',
+        optional: true,
+        proven: [
+            'Export of all five files, deterministically.',
+            'Import of a bundle as proposals, at imported origin.',
+            'Round trip preserving content and evidence refs.',
+            'Refusal of a hostile bundle: permissions, safeguards and protected subjects.',
+        ],
+        notMachineTested: [
+            'Interoperability with a specific LLMWiki release. The format here is written '
+                + 'against its documented file set, and no LLMWiki installation was available '
+                + 'to exchange a bundle with.',
+        ],
+    };
+}
+//# sourceMappingURL=llmwiki.js.map

package/lib/obsidian.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The Obsidian adapter: optional, one-directional about authority, and inert.
+ *
+ * Obsidian is a good place to read a workspace wiki and a terrible place to
+ * keep the record of what an agent believes. It is a folder of Markdown that
+ * anything can write to — a sync client, a plugin, a shared drive, another
+ * person — and the thing that makes it pleasant is exactly the thing that
+ * makes it unsuitable as an authority.
+ *
+ * So this adapter does two things and refuses a third.
+ *
+ * It **exports** a vault: the generated wiki, plus the frontmatter and
+ * wikilinks that make Obsidian's graph and backlinks work. It **imports** an
+ * edit as a *proposal*, through the same validation a hand-edited wiki page
+ * goes through. It never lets vault content become authority — not evidence,
+ * not a verdict, not `explicit_user`, not a permission, not a scope change.
+ *
+ * Nothing in Watch Core depends on this module, and nothing here imports
+ * Obsidian. There is no Obsidian API to import; the integration surface is a
+ * folder and a URI scheme, which is why the adapter can be tested completely
+ * against a filesystem-shaped fixture. What cannot be tested here is whether a
+ * real Obsidian installation opens the URI, and that is reported as
+ * NOT MACHINE TESTED rather than assumed.
+ *
+ * @module @deepwatch/dsh-adapters/obsidian
+ */
+import type { MemoryRecord } from '@deepwatch/dsh-memory';
+import type { WikiPage, WikiProjection, ValidatedEdit } from '@deepwatch/dsh-wiki';
+/** One file as it would sit in a vault. */
+export interface VaultFile {
+    /** Path relative to the vault root. */
+    readonly path: string;
+    readonly content: string;
+    /** Tags in the frontmatter, without the leading hash. */
+    readonly tags: readonly string[];
+    /** Pages this one links to, by vault path. */
+    readonly links: readonly string[];
+}
+/** A whole exported vault. */
+export interface Vault {
+    readonly name: string;
+    readonly files: readonly VaultFile[];
+    /**
+     * The note that travels with the export.
+     *
+     * Present as data rather than as a README somebody might not open: the
+     * export writes it into the vault, so a person who arrives at these files
+     * from a sync client rather than from Watch still learns what they are.
+     */
+    readonly readme: string;
+}
+/** How the export should be shaped. */
+export interface VaultOptions {
+    readonly name: string;
+    /** Prefix inside the vault, so a Watch export can live beside other notes. */
+    readonly folder?: string;
+    /** Include the log page. Off by default: it is long and rarely read here. */
+    readonly includeLog?: boolean;
+}
+/**
+ * Export the wiki as an Obsidian vault.
+ *
+ * Frontmatter carries tags and the provenance ids, so a person browsing in
+ * Obsidian can still see where a statement came from — the graph view is
+ * pleasant and it is also a place where provenance is very easy to lose.
+ */
+export declare function toVault(projection: WikiProjection, options: VaultOptions): Vault;
+/**
+ * Backlinks, computed from the export rather than read from Obsidian.
+ *
+ * Computing them here means the export can be checked for a dangling link
+ * before anybody opens it, and means the adapter does not need Obsidian to
+ * answer a question about its own output.
+ */
+export declare function backlinks(vault: Vault): ReadonlyMap<string, readonly string[]>;
+/** Links that point at a file the export does not contain. */
+export declare function danglingLinks(vault: Vault): readonly string[];
+/**
+ * The URI that opens one page in Obsidian.
+ *
+ * Constructed, never executed. Handing a URI to the shell is the desktop
+ * layer's job and is gated there; an adapter that could launch things would be
+ * an adapter that a generated page could aim.
+ */
+export declare function pageUri(vaultName: string, path: string): string;
+/** The URI that opens the vault itself. */
+export declare function vaultUri(vaultName: string): string;
+/**
+ * Strip the frontmatter an export added, so a diff compares like with like.
+ *
+ * Without this, every imported file would appear to have removed the entire
+ * generated page and added an entire new one.
+ */
+export declare function stripFrontmatter(content: string): string;
+/**
+ * Import an edited vault file as a proposal.
+ *
+ * Runs through the wiki's own diff and validation, which is the point: there
+ * is one place that decides what an edited file may assert, and an adapter
+ * that had its own copy of those rules would be a second place for them to
+ * drift.
+ */
+export declare function importVaultFile(file: {
+    readonly path: string;
+    readonly content: string;
+}, generated: WikiPage): ValidatedEdit;
+/**
+ * What this adapter can and cannot claim on this machine.
+ *
+ * Stated as a value so the Settings surface renders the truth rather than a
+ * checkmark. Export, backlinks, URI construction and import are all pure and
+ * are gated by tests. Whether a real Obsidian installation opens the URI is
+ * not something this machine can answer, and it says so.
+ */
+export interface AdapterAvailability {
+    readonly adapterId: string;
+    readonly optional: true;
+    readonly proven: readonly string[];
+    readonly notMachineTested: readonly string[];
+}
+/** The Obsidian adapter's honest self-description. */
+export declare function obsidianAvailability(): AdapterAvailability;
+/**
+ * Whether a memory record may be written into a shared vault.
+ *
+ * An export is a copy that leaves the product, and once it is in a synced
+ * folder it is wherever that folder goes. Personal taste and anything
+ * sensitive stay out by default, and the caller has to say otherwise per
+ * export rather than once in a setting.
+ */
+export declare function mayExport(record: MemoryRecord, options?: {
+    readonly includePersonal?: boolean;
+}): boolean;
+//# sourceMappingURL=obsidian.d.ts.map

package/lib/obsidian.js

@@ -0,0 +1,224 @@
+/**
+ * The Obsidian adapter: optional, one-directional about authority, and inert.
+ *
+ * Obsidian is a good place to read a workspace wiki and a terrible place to
+ * keep the record of what an agent believes. It is a folder of Markdown that
+ * anything can write to — a sync client, a plugin, a shared drive, another
+ * person — and the thing that makes it pleasant is exactly the thing that
+ * makes it unsuitable as an authority.
+ *
+ * So this adapter does two things and refuses a third.
+ *
+ * It **exports** a vault: the generated wiki, plus the frontmatter and
+ * wikilinks that make Obsidian's graph and backlinks work. It **imports** an
+ * edit as a *proposal*, through the same validation a hand-edited wiki page
+ * goes through. It never lets vault content become authority — not evidence,
+ * not a verdict, not `explicit_user`, not a permission, not a scope change.
+ *
+ * Nothing in Watch Core depends on this module, and nothing here imports
+ * Obsidian. There is no Obsidian API to import; the integration surface is a
+ * folder and a URI scheme, which is why the adapter can be tested completely
+ * against a filesystem-shaped fixture. What cannot be tested here is whether a
+ * real Obsidian installation opens the URI, and that is reported as
+ * NOT MACHINE TESTED rather than assumed.
+ *
+ * @module @deepwatch/dsh-adapters/obsidian
+ */
+import { diffUserEdit, validateUserEdit } from '@deepwatch/dsh-wiki';
+/** Escape a YAML scalar the crude, safe way. */
+function yamlString(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/** Derive tags from a page's path and provenance. */
+function tagsFor(page) {
+    const section = page.path.includes('/') ? page.path.split('/')[0] ?? '' : 'index';
+    const tags = ['watch', `watch/${section}`];
+    if (page.provenance.length === 0)
+        tags.push('watch/generated-index');
+    return tags;
+}
+/**
+ * Rewrite a generated page's Markdown links as Obsidian wikilinks.
+ *
+ * Deliberately conservative: only links that resolve to a page in the same
+ * projection are rewritten. A rewritten link that goes nowhere is worse than a
+ * plain one, because Obsidian will offer to create the missing note — and a
+ * note created that way is a file with no provenance sitting in a folder full
+ * of files that have some.
+ */
+function toWikilinks(page, known) {
+    const links = [];
+    const folder = page.path.includes('/') ? `${page.path.split('/')[0] ?? ''}/` : '';
+    const content = page.content.replace(/\[([^\]]+)\]\(([^)]+\.md)\)/g, (whole, label, target) => {
+        const resolved = target.startsWith('.') || target.includes('/')
+            ? target.replace(/^\.\//, '')
+            : `${folder}${target}`;
+        if (!known.has(resolved))
+            return whole;
+        links.push(resolved);
+        const stem = resolved.replace(/\.md$/, '');
+        return `[[${stem}|${label}]]`;
+    });
+    return { content, links };
+}
+/** The note that ships inside every exported vault. */
+const VAULT_README = `# Watch export
+
+These notes are **generated** from the Watch memory ledger. They are a
+projection, not the record.
+
+- Editing a note here does not change what Watch believes. An edit is imported
+  as a *proposal*, validated, and then the note is regenerated from the ledger.
+- Nothing in this vault is evidence, and nothing here can make something
+  verified.
+- A note added by hand — or by a sync client, a plugin, or another person — is
+  imported at the weakest origin there is. It cannot grant a permission, change
+  a memory's scope, or claim that you said something.
+
+If this folder and Watch disagree, Watch is right and this folder is stale.
+Re-export to fix it.
+`;
+/**
+ * Export the wiki as an Obsidian vault.
+ *
+ * Frontmatter carries tags and the provenance ids, so a person browsing in
+ * Obsidian can still see where a statement came from — the graph view is
+ * pleasant and it is also a place where provenance is very easy to lose.
+ */
+export function toVault(projection, options) {
+    const folder = options.folder === undefined || options.folder === ''
+        ? ''
+        : `${options.folder.replace(/\/+$/, '')}/`;
+    const included = projection.pages.filter(page => options.includeLog === true || page.path !== 'log.md');
+    const known = new Set(included.map(page => page.path));
+    const files = included.map(page => {
+        const { content, links } = toWikilinks(page, known);
+        const tags = tagsFor(page);
+        const frontmatter = [
+            '---',
+            `title: ${yamlString(page.title)}`,
+            `tags: [${tags.map(tag => yamlString(tag)).join(', ')}]`,
+            'watch_generated: true',
+            `watch_provenance: [${page.provenance.map(id => yamlString(id)).join(', ')}]`,
+            '---',
+            '',
+        ].join('\n');
+        return {
+            path: `${folder}${page.path}`,
+            content: `${frontmatter}${content}`,
+            tags,
+            links: links.map(link => `${folder}${link}`),
+        };
+    });
+    return {
+        name: options.name,
+        files: [
+            { path: `${folder}README.md`, content: VAULT_README, tags: ['watch'], links: [] },
+            ...files,
+        ],
+        readme: VAULT_README,
+    };
+}
+/**
+ * Backlinks, computed from the export rather than read from Obsidian.
+ *
+ * Computing them here means the export can be checked for a dangling link
+ * before anybody opens it, and means the adapter does not need Obsidian to
+ * answer a question about its own output.
+ */
+export function backlinks(vault) {
+    const incoming = new Map();
+    for (const file of vault.files) {
+        for (const link of file.links) {
+            const list = incoming.get(link) ?? [];
+            list.push(file.path);
+            incoming.set(link, list);
+        }
+    }
+    return new Map([...incoming].map(([path, sources]) => [path, [...sources].sort()]));
+}
+/** Links that point at a file the export does not contain. */
+export function danglingLinks(vault) {
+    const known = new Set(vault.files.map(file => file.path));
+    const dangling = new Set();
+    for (const file of vault.files) {
+        for (const link of file.links)
+            if (!known.has(link))
+                dangling.add(link);
+    }
+    return [...dangling].sort();
+}
+/**
+ * The URI that opens one page in Obsidian.
+ *
+ * Constructed, never executed. Handing a URI to the shell is the desktop
+ * layer's job and is gated there; an adapter that could launch things would be
+ * an adapter that a generated page could aim.
+ */
+export function pageUri(vaultName, path) {
+    const file = path.replace(/\.md$/, '');
+    return `obsidian://open?vault=${encodeURIComponent(vaultName)}&file=${encodeURIComponent(file)}`;
+}
+/** The URI that opens the vault itself. */
+export function vaultUri(vaultName) {
+    return `obsidian://open?vault=${encodeURIComponent(vaultName)}`;
+}
+/**
+ * Strip the frontmatter an export added, so a diff compares like with like.
+ *
+ * Without this, every imported file would appear to have removed the entire
+ * generated page and added an entire new one.
+ */
+export function stripFrontmatter(content) {
+    const match = /^---\r?\n[\s\S]*?\r?\n---\r?\n/.exec(content);
+    return match === null ? content : content.slice(match[0].length);
+}
+/**
+ * Import an edited vault file as a proposal.
+ *
+ * Runs through the wiki's own diff and validation, which is the point: there
+ * is one place that decides what an edited file may assert, and an adapter
+ * that had its own copy of those rules would be a second place for them to
+ * drift.
+ */
+export function importVaultFile(file, generated) {
+    const body = stripFrontmatter(file.content);
+    return validateUserEdit(diffUserEdit(generated, body), generated);
+}
+/** The Obsidian adapter's honest self-description. */
+export function obsidianAvailability() {
+    return {
+        adapterId: 'adapter.obsidian',
+        optional: true,
+        proven: [
+            'Vault export, including frontmatter, tags and wikilinks.',
+            'Backlink and dangling-link computation over the export.',
+            'URI construction for a vault and for one page.',
+            'Import of an edited file as a proposal, through the wiki’s own validation.',
+        ],
+        notMachineTested: [
+            'Opening an obsidian:// URI. No Obsidian installation is present here, so '
+                + 'whether it launches and resolves the page has not been observed.',
+            'Round-tripping through Obsidian’s own editor, which may normalise Markdown '
+                + 'in ways this adapter has not seen.',
+        ],
+    };
+}
+/**
+ * Whether a memory record may be written into a shared vault.
+ *
+ * An export is a copy that leaves the product, and once it is in a synced
+ * folder it is wherever that folder goes. Personal taste and anything
+ * sensitive stay out by default, and the caller has to say otherwise per
+ * export rather than once in a setting.
+ */
+export function mayExport(record, options = {}) {
+    if (record.sensitivity === 'sensitive' || record.sensitivity === 'restricted')
+        return false;
+    if (record.kind === 'preference' && options.includePersonal !== true)
+        return false;
+    if (record.subjectScope === 'user' && options.includePersonal !== true)
+        return false;
+    return true;
+}
+//# sourceMappingURL=obsidian.js.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@deepwatch/dsh-adapters",
+  "version": "0.1.0",
+  "description": "Optional adapters: Obsidian vaults and LLMWiki bundles. Watch works fully without either.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Sayed Allam",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oxbshw/watch-skill.git",
+    "directory": "workspace/packages/watch/adapters"
+  },
+  "homepage": "https://github.com/oxbshw/watch-skill/tree/main/workspace#readme",
+  "bugs": {
+    "url": "https://github.com/oxbshw/watch-skill/issues"
+  },
+  "keywords": [
+    "deepwatch",
+    "deepseek-harness",
+    "watch-skill",
+    "adapters",
+    "perception"
+  ],
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/**/*.d.ts"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@deepwatch/dsh-memory": "^0.1.0",
+    "@deepwatch/dsh-wiki": "^0.1.0"
+  }
+}